JavaScript/TypeScript SDK monorepo for MagicBell - The real-time notification inbox for web & mobile apps
OTHER License
Bot releases are visible (Hide)
Published by github-actions[bot] over 1 year ago
cb7c02a
]:
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
#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
}
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
#153 6aa5cee
Thanks @renovate! - Updated dependencies:
@types/lodash
to ^4.14.195
.Updated dependencies [6aa5cee
, 2c7ba0c
]:
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
6aa5cee
]:
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
#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
#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
Published by github-actions[bot] over 1 year ago
#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.
#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
Published by github-actions[bot] over 1 year ago
#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
Published by github-actions[bot] over 1 year ago
#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
Published by github-actions[bot] over 1 year ago
963fcc1
Thanks @smeijer! - feat: add user options to listen
magicbell listen --user-email [email protected]
magicbell listen --user-external-id usr_123
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
#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
Published by github-actions[bot] over 1 year ago
#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,
});
Published by github-actions[bot] over 1 year ago
Published by github-actions[bot] over 1 year ago
#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',
});