@magicbell/core
    TypeScript icon, indicating that this package has built-in type declarations

    5.0.3 • Public • Published

    codecov TypeScript code style: prettier minified minified + gzip npm version

    Magicbell API wrapper

    This is the official MagicBell API wrapper for Node and the browser. You can easily fetch, delete and create notifications.

    If you are looking to build a notification inbox in React, check our React hooks package and the React package.

    Quick Start

    First, grab your API key from your MagicBell dashboard. Then install the package and fetch your notifications.

    npm i @magicbell/core --save
    # or
    yarn add @magicbell/core
    import MagicBellClient, { NotificationStore } from '@magicbell/core';
    
    const client = await MagicBellClient.createInstance({
      apiKey: 'MAGICBELL_API_KEY',
      userEmail: 'customer@example.com',
    });
    
    const notificationsStore = new NotificationStore();
    await notificationsStore.fetch();
    console.log(`User ${userEmail} has ${notificationsStore.unreadCount} unread notifications.`);

    Try a working example.

    Table of Contents

    MagicBellClient

    Use this class to create a MagicBell client. It configures the AJAX client used to interact with the magicbell.com server, fetches the configuration values for your account.

    These are the arguments accepted by this function:

    Property Type Description
    apiKey string The API key of your MagicBell project
    apiSecret string The secret key of your MagicBell project (optional)
    userEmail string The email of the user you want to show notifications for
    userExternalId string The id of the user you want to show notifications for
    userKey string The HMAC for the user. It is recommended to enable HMAC authentication but not required

    Real time events

    The MagicBellClient also handles real time events. You need to start the real time listener calling the startRealTimeListener. This method returns a function you need call in the cleanup phase of your application to prevent memory leaks. The listener will emit events to the pushEventAggregator object, which is simple event bus for pub/sub.

    import MagicBellClient, { pushEventAggregator } from '@magicbell/core';
    
    const client = await MagicBellClient.createInstance({
      apiKey: 'MAGICBELL_API_KEY',
      userEmail: 'customer@example.com',
    });
    
    const dispose = client.startRealTimeListener();
    
    pushEventAggregator.on('notifications.new', (notification) => {
      // Do something with the notification
    });
    
    dispose();

    This is a list of events you can listen to:

    Event name Description
    * Any event
    notifications.new A new notification for the authenticated user was created
    notifications.read A notification was marked as read
    notifications.read.all All notifications were marked as read
    notifications.unread A notification was marked as unread
    notifications.seen.all All notifications were marked as seen
    notifications.delete A notification was deleted

    Create notifications

    The simplest way to create a notification is using the Notification.create method:

    import MagicBellClient, { Notification } from '@magicbell/core';
    
    MagicBellClient.configure({ apiKey: 'MAGICBELL_API_KEY', apiSecret: 'MAGICBELL_API_SECRET' });
    
    const notification = Notification.create({
      title: 'New reply: I want to book a demo',
      content: 'Hi, I would like to book it on Monday, please',
      recipients: [{ email: 'customer@example.com' }],
    });

    Another approach, useful for building UIs, is to create the notification through a notifications store:

    import MagicBellClient, { NotificationStore } from '@magicbell/core';
    
    const client = await MagicBellClient.createInstance({
      apiKey: 'MAGICBELL_API_KEY',
      apiSecret: 'MAGICBELL_API_SECRET',
    });
    
    const store = new NotificationStore();
    const notification = await store.create({
      title: 'New reply: I want to book a demo',
      content: 'Hi, I would like to book it on Monday, please',
      recipients: [{ email: 'customer@example.com' }],
    });

    The new notification will be added to the store of notifications, too.

    Notification

    The Notification class represents a MagicBell notification. It implements this interface:

    interface INotification {
      // Attributes
      id: string | null;
      title: string;
      content: string | null;
      category: string | null;
      actionUrl: string;
      customAttributes: any;
      readAt: number | null;
      seenAt: number | null;
      sentAt: number;
    
      // Getters/setters
      isRead: boolean;
      isSeen: boolean;
    
      // Read-only properties
      seenAtDate: Dayjs | null;
      sentAtDate: Dayjs;
      readAtDate: Dayjs | null;
    
      // Methods
      fetch: () => Promise;
      markAsRead: () => Promise;
      markAsUnread: () => Promise;
      delete: () => Promise;
    }

    All attributes are MobX observables.

    seenAtDate

    A date representation of the seenAt attribute. It returns an immutable instance of Dayjs. Dayjs exposes an API similar to moment.js.

    notification.seenAtDate.format('DD/MM/YYYY'); // '01/04/2021'
    notification.seenAtDate.fromNow(); // 1mo
    notification.seenAtDate.to('2021-01-01'); // in 4mo
    notification.seenAtDate.add(2, 'day');

    readAtDate

    A date representation of the readAt attribute. It returns an immutable instance of Dayjs.

    sentAtDate

    A date representation of the sentAt attribute. It returns an immutable instance of Dayjs.

    fetch

    Fetches the notification from the Magicbell API server. All fetched attributes are assigned to the current object.

    markAsRead

    This method makes a POST request to the read notification API endpoint. It sets the readAt attribute as well.

    markAsUnread

    This method makes a POST request to the unread notification API endpoint. It sets the readAt attribute to null as well.

    delete

    This method makes a DELETE request to the delete notification API endpoint. If the notification belongs to a store, it will remove itself from the store.

    NotificationStore

    The NotificationStore class represents a collection of MagicBell notifications. It implements this interface:

    interface INotificationStore {
      // Attributes
      unseenCount: number;
      unreadCount: number;
      total: number;
      perPage: number;
      totalPages: number;
      currentPage: number;
      items: Notification[];
    
      // Read only properties
      length: number;
      isEmpty: boolean;
      hasNextPage: boolean;
    
      // Methods
      at: (number) => Notification | null;
      get: (id) => Notification;
      find: (fn) => Notification;
      filter: (fn) => Notification[];
      map: (fn) => any[];
      push: (notification) => void;
      remove: (notification) => void;
    
      fetch: (queryParams, options = { reset: false }) => Promise;
      fetchNextPage: (queryParams) => Promise;
      create: (data) => Promise<Notification>;
      markAllAsRead: () => Promise;
      markAllAsSeen: () => Promise;
    }

    In the following example, we are fetching notifications and marking all of them as read.

    let store = new NotificationStore();
    await store.fetch();
    await store.markAllAsRead();

    length

    Number of notifications in the items array.

    at

    Get a notification from the items array, specified by index.

    map

    Creates an array of values by running each notification in items array thru iteratee. The iteratee is invoked with three arguments: (notification, index, itemsArray).

    find

    Returns the first notification the given predicate returns truthy for.

    filter

    Returns an array of all notifications the given predicate returns truthy for.

    fetch

    Fetch notifications from the magicbell server. The pagination data is also updated. The provided query parameters are included in the request to the server.

    The response is appended to the current array of notifications, so it can be used as the view model for an infinite scroll list. If you want to reset the collection instead, pass the reset: true option to this method:

    notifications.fetch({ page: 2 }, { reset: true });

    fetchNextPage

    This method is simply wrapping the fetch method, sending as a parameter the next page of notifications. You can include query parameters to this method.

    create

    Create a new notification.

    It is equivalent to creating a Notification instance with some attributes, saving the notification to the MagicBell server, and adding it to the array of items after being successfully created.

    markAllAsRead

    Makes a POST request to the read notifications API endpoint. It also marks all notifications in the collection as read.

    markAllAsSeen

    Makes a POST request to the seen notifications API endpoint. It also sets the unseenCount to 0 and marks all notifications in the collection as seen.

    remove

    Removes the given notification from the items array. It does not make any request to the server. If you want to delete a notification, use the delete method of the notification object instead.

    Install

    npm i @magicbell/core

    DownloadsWeekly Downloads

    15,774

    Version

    5.0.3

    License

    SEE LICENSE IN LICENSE

    Unpacked Size

    360 kB

    Total Files

    43

    Last publish

    Collaborators

    • unamashana
    • josue-sb