magicbell-js

Patch Changes

• Updated dependencies [cb7c02a]:
  • @magicbell/[email protected]

Patch Changes

• #161 4ef2b07 Thanks @smeijer! - Use a fork of ky that includes commonjs support

Patch Changes

• #158 d0121d9 Thanks @smeijer! - inject ky during build for a dep free install

Minor Changes

• #155 2c7ba0c Thanks @moxley01! - Adds an 'isSubscribed' method that checks if the user is subscribed to push notifications in the current browser, e.g.

  import { isSubscribed } from '@magicbell/webpush';
  
  const subscribed = await isSubscribed({
    token: 'jwt-token',
    host: 'https://api.magicbell.com',
    project: 'string',
  });
  
  if (subscribed) {
    // Do something
  } else {
    // Do something else
  }
  

Patch Changes

• #153 6aa5cee Thanks @renovate! - Updated dependencies:

  • updated @types/lodash to ^4.14.195.

Patch Changes

• #153 6aa5cee Thanks @renovate! - Updated dependencies:

  • updated @types/lodash to ^4.14.195.

• Updated dependencies [6aa5cee, 2c7ba0c]:

  • @magicbell/[email protected]
  • @magicbell/[email protected]

Patch Changes

• #156 16016dc Thanks @smeijer! - declare exports in package.json

Patch Changes

• Updated dependencies [6aa5cee]:
  • @magicbell/[email protected]

Patch Changes

• #153 6aa5cee Thanks @renovate! - Updated dependencies:

  • updated @types/lodash to ^4.14.195.

Patch Changes

• 125c9d2 Thanks @smeijer! - - updated magicbell to 2.0.1

Major Changes

• #154 da22233 Thanks @smeijer! - Breaking Changes - please read carefully.

  We've separated the project from user resources. All user resources have been moved under the user namespace. This is a virtual path, that does not translate one-on-one to the REST api. All user resources require a --user-email or --user-external-id option to be provided.

  Project Resources

  The project resources have been left untouched, and work as before. This includes the commands as below. Note that magicbell notifications was a mixture of project and user scoped resources, and has been split into magicbell notifications and magicbell user notifications. On the project scope, only magicbell notifications create remains.

  magicbell broadcasts
  magicbell imports
  magicbell metrics
  magicbell notifications
  magicbell users
  

  User Resources

  User resources include all API endpoints that do not require the api secret key, but use the api key and user email or user external id to authenticate the user. This includes the resources as below. Please note that all user scoped commands require a --user-email or --user-external-id option to be provided. If you're authenticated with api-secret we'll compute the --user-hmac for you. Otherwise, you'll have to provide it manually with the --user-hmac option if HMAC is enabled for your project.

  magicbell user listen
  magicbell user notification-preferences
  magicbell user notifications
  magicbell user push-subscriptions
  magicbell user subscriptions
  

Minor Changes

• #149 3cd329b Thanks @smeijer! - The CLI now accepts the global --print-request curl option that prints the request object to the console. When that option is provided, the request will be printed in the requested format, and no network requests will be made. We'll add more formats in the future.

  magicbell notifications list --print-request curl
  magicbell notifications create --title hi --print-request curl
  

• #152 035b9e8 Thanks @smeijer! - We now use debug for logging, and have dropped support for the debug property that could be provided to Client. Debugging can be enabled via the DEBUG environment variable.

  We're using the namespaces magicbell:debug, magicbell:log and magicbell:error.

  DEBUG=magicbell:* node my-app.js
  DEBUG=magicbell:debug node my-app.js
  

Patch Changes

• #148 f6558fb Thanks @renovate! - Updated dependencies:

  • updated esbuild to ^0.18.11.

Major Changes

• #154 da22233 Thanks @smeijer! - Breaking Changes - please read carefully.

  We've separated the project from user resources. There are now two API clients exposed that can be used independently. A ProjectClient and a UserClient.

  Project Client

  The ProjectClient provides access to all our API endpoints that require the api secret key. It's the same client as in v1, but with all user scoped endpoints removed.

  In most cases, you'll only have to change the import statements to use the new client.

  - import { Client } from 'magicbell';
  + import { ProjectClient } from 'magicbell/project-client';
  
  - const magicbell = new Client({
  + const magicbell = new ProjectClient({
    apiKey: 'your-api-key', // required
    apiSecret: 'your-secret-key', // required
  });
  
  magicbell.users.list();
  

  User Client

  The UserClient provides access to all our API endpoints that require the user email or user external id. As the user client only supports user scoped APIs and does not require or accept the api secret key, it's safe to use in the browser.

  If you've used the client scoped resources before, you'll have to migrate those calls to the user client. Note that if you provided the apiSecret to the old client, you'll have to remove it from the new one. User credentials are now provided in the constructor, and no longer overridable on a per request basis.

  - import { Client } from 'magicbell';
  + import { UserClient } from 'magicbell/user-client';
  
  - const magicbell = new Client({
  + const magicbell = new UserClient({
    apiKey: 'your-api-key', // required
  - apiSecret: 'your-secret-key',
  + userEmail: '[email protected]', // required if userExternalId is not set
  + userExternalId: 'your-external-id', // required if userEmail is not set
  + userHmac: 'your-user-hmac', // required if HMAC is enabled
  });
  
  magicbell.notifications.list();
  

  User HMAC

  As the UserClient does not have access to your api secret key, userHmac keys are no longer automatically generated. You'll have to generate them yourself and provide them to the client. This is a necessary change to make the client safe to use in the browser without exposing your api secret key.

  We've exported a createHmac util for you to generate the HMAC keys. You can use it in your backend to generate the HMAC keys.

  import { createHmac } from 'magicbell/crypto';
  
  const userHmac = createHmac(process.env.MAGICBELL_API_KEY, user);
  

  We've made the createHmac util as flexible as possible. It accepts MagicBell user objects with properties as userEmail and/or userExternalId, as well as objects with id, _id, or email properties. When providing the id, we assume that it maps to our userExternalId. If none of those properties work for you, it's possible to provide a string as second argument.

  // these are all supported and the same
  const userHmac = createHmac('secret-key', 'value');
  const userHmac = createHmac('secret-key', { userExternalId: 'value' });
  const userHmac = createHmac('secret-key', { userEmail: 'value' });
  const userHmac = createHmac('secret-key', { id: 'value' });
  const userHmac = createHmac('secret-key', { _id: 'value' });
  const userHmac = createHmac('secret-key', { email: 'value' });
  

• #152 035b9e8 Thanks @smeijer! - We're now using ky instead of axios for making HTTP requests. This is a breaking change, as ky is build around the fetch module. Fetch is natively supported in all modern browsers, and is also available in Node.js since version 18.13.0.

  If you're using an older version of node, we recommend you to upgrade to the latest LTS version. Alternatively, include a fetch polyfill such as isomorphic-fetch.

Minor Changes

• #152 035b9e8 Thanks @smeijer! - The magicbell client now supports lifecycle hooks. This way you can add custom logic to the client when certain events occur. For example to add logging, or to wrap requests with timing information.

  Your hooks will be passed directly to ky, so please see ky/hooks for more information.

  const magicbell = new Client({
    hooks: {
      beforeRequest: [(request) => {}],
      beforeRetry: [(request, options, error, retryCount) => {}],
      beforeError: [(error) => error],
      afterResponse: [(request, options, response) => response],
    },
  });
  

• #152 035b9e8 Thanks @smeijer! - We now use debug for logging, and have dropped support for the debug property that could be provided to Client. Debugging can be enabled via the DEBUG environment variable.

  We're using the namespaces magicbell:debug, magicbell:log and magicbell:error.

  DEBUG=magicbell:* node my-app.js
  DEBUG=magicbell:debug node my-app.js
  

Minor Changes

• #147 b2f240a Thanks @smeijer! - add --host flag so the cli can be used against other environments, such as localhost, staging and review.

  magicbell --host localhost:3000
  magicbell --host localhost:3000/api/v1
  

  When an alternative host is provided during login, the host gets bound to that session. Meaning, the profile will use that host as default.

  magicbell login
  magicbell users list # run against production
  
  # or export MAGICBELL_PROFILE=dev
  magicbell login -p dev -h localhost:3000
  magicbell users list -p dev # run against localhost:3000
  

Patch Changes

• #145 871c9f4 Thanks @smeijer! - remove -v and -h alias. Use --version and --help instead.

Minor Changes

• #143 26e9e1a Thanks @smeijer! - Add --max-items to methods supporting --paginate. This way it's trivial to auto paginate over records at MagicBell, till a certain reasonable limit is reached. By default, --paginate iterates over every single record potentially hitting, but respecting, API rate limits.

  $ magicbell broadcasts list --paginate --max-items 1000
  

Minor Changes

• 963fcc1 Thanks @smeijer! - feat: add user options to listen

  magicbell listen --user-email [email protected]
  magicbell listen --user-external-id usr_123
  

Minor Changes

• #139 22f7267 Thanks @smeijer! - Small changes to the (internal) codegen package.

  • Fix hyphen-case
  • Don't crash on missing pagination properties
  • Support shorthand object properties
  • Add id helper

Major Changes

• #139 22f7267 Thanks @smeijer! - Work with MagicBell from the command line!

  npm i -g @magicbell/cli
  
  magicbell login
  magicbell --help
  

  Example output of magicbell --help:

  Usage
    magicbell [options] [command]
  
  Resource commands
    broadcasts                Manage broadcasts
    imports                   Manage imports
    listen                    Listen to events for a users inbox
    metrics                   Manage metrics
    notification-preferences  Manage notification preferences
    notifications             Send and retrieve notifications
    push-subscriptions        Manage push subscriptions
    subscriptions             Manage subscriptions
    users                     Manage all known users
  
  Other commands
    config                    Manage configuration for magicbell
    login                     Login to your MagicBell account
    logout                    Logout of your MagicBell account
  
  Options
    -v, --version             Show magicbell version
    -p, --profile <string>    Profile to use (default: "default")
    --no-color                Color output
    -h, --help                Show help for command
  

Minor Changes

• #131 ac58966 Thanks @smeijer! - Added a users.notifications resource which can be used to iterate notifications for a given user.

  const notifications = magicbell.users.notifications.list(userId, { per_page: 10 });
  
  for await (const notification of notifications) {
    console.log(notification.title);
  }
  

• #134 66dae2e Thanks @smeijer! - Added the metrics resource. The metrics resource contains a collection of endpoints that return metrics about the sent Notifications. All metrics are for the last 30 days. The following endpoints are available:

  const notificationCounts = await magicbell.metrics.get();
  
  const countsPerCategory = await magicbell.metrics.categories.get();
  
  const countsPerTopic = await magicbell.metrics.topics.get();
  

• #136 0e08df7 Thanks @smeijer! - Release the users.pushSubscriptions resource as stable. This includes the following apis:

  Fetch user's push subscriptions

  Fetch a user's push subscriptions. Returns a paginated list of web and mobile push subscriptions for all platforms.

  await magicbell.users.pushSubscriptions.list('{user_id}', {
    page: 1,
    per_page: 1,
  });
  

  Delete user's push subscription

  Delete a user's push subscriptions. Identifies the user by the user's ID and the push subscription by the subscription's ID.

  await magicbell.users.pushSubscriptions.delete('{user_id}', '{subscription_id}');
  

• #138 18e0e49 Thanks @smeijer! - Release the imports resource as stable. This includes the following apis:

  Create a import

  Enqueues an import - currently only supported for users.

  await magicbell.imports.create({
    users: [
      {
        external_id: 'ugiabqertz',
        email: '[email protected]',
        first_name: 'John',
        last_name: 'Doe',
        custom_attributes: {
          age: 32,
          country: 'Spain',
        },
      },
    ],
  });
  

  Get the status of an import

  Query the status of the import for a summary of imported records and failures for each record that could not be imported successfully.

  await magicbell.imports.get('{import_id}');
  

• #130 0491ba2 Thanks @smeijer! - Added support for per-request header overrides

  const magicbell = new Client({
    headers: {
      'x-custom-header-one': 'one',
    },
  });
  
  await client.request({
    path: '/me',
    headers: {
      'x-custom-header-two': 'two',
    },
  });
  
  // request is made using the following headers:
  //   x-custom-header-one: one
  //   x-custom-header-two: two
  

• #135 7038d80 Thanks @smeijer! - Release broadcasts resource as stable. This includes the following apis:

  List notification broadcasts

  await magicbell.broadcasts.list({
    page: 1,
    per_page: 1,
  });
  

  Fetch a notification broadcast by its ID

  await magicbell.broadcasts.get('{broadcast_id}');
  

  Fetch notifications by broadcast id.

  await magicbell.broadcasts.notifications.list('{broadcast_id}', {
    page: 1,
    per_page: 1,
  });
  

Minor Changes

• #137 8818e8b Thanks @smeijer! - support scenarios where we don't have beta methods

Minor Changes

• #126 03f2d30 Thanks @smeijer! - Added warmup method to speedup subscription process. By prefetching config, you'll separate the subscription from config fetching, and thereby reduce the time to subscribe, which improves the user experience.

  import { prefetchConfig } from '@magicbell/webpush';
  
  prefetchConfig({
    token: 'jwt-token',
    host: 'https://api.magicbell.com',
    project: 'string',
    serviceWorkerPath: '/sw.js',
  });