New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More
Socket
Sign inDemoInstall
Socket

magicbell

Package Overview
Dependencies
Maintainers
2
Versions
40
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

magicbell - npm Package Compare versions

Comparing version 1.8.0 to 2.0.0

CHANGELOG.md

50

package.json
{
"name": "magicbell",
"version": "1.8.0",
"version": "2.0.0",
"description": "MagicBell API wrapper",

@@ -10,11 +10,6 @@ "author": "MagicBell <bot@magicbell.io> (https://magicbell.com)",

"license": "SEE LICENSE IN LICENSE",
"source": "./src/index.ts",
"main": "dist/index.js",
"module": "dist/magicbell.esm.js",
"typings": "dist/index.d.ts",
"main": "./index.cjs",
"module": "./index.mjs",
"typings": "./index.d.ts",
"sideEffects": false,
"files": [
"/dist",
"/src"
],
"homepage": "https://magicbell.com",

@@ -35,36 +30,9 @@ "keywords": [

},
"scripts": {
"clean": "rimraf dist",
"build": "run-s clean build:*",
"build:dev": "vite build -c ../../scripts/vite/vite.config.js",
"build:prod": "vite build -c ../../scripts/vite/vite.config.js --minify",
"generate:resources": "tsx scripts/generate-resources.ts",
"start": "yarn build:dev --watch",
"size": "size-limit"
},
"size-limit": [
{
"path": "dist/magicbell.cjs.min.js",
"limit": "250 KB"
},
{
"path": "dist/magicbell.esm.min.js",
"limit": "175 KB"
}
],
"devDependencies": {
"@magicbell/codegen": "^0.1.0",
"@size-limit/preset-small-lib": "^8.0.1",
"ast-types": "^0.14.2",
"json5": "^2.2.3",
"openapi-types": "^12.0.2",
"portfinder": "^1.0.32",
"recast": "^0.21.5",
"tsx": "^3.9.0"
},
"dependencies": {
"axios": "^0.27.2",
"debug": "^4.3.4",
"eventsource": "^2.0.2",
"json-schema-to-ts": "2.6.0"
"fetch-addons": "^1.1.0",
"json-schema-to-ts": "2.6.0",
"ky": "^0.33.3"
}
}
}
# MagicBell Node.js Library
This package provides a convenient interface to query the [MagicBell](https://magicbell.com) API. Note that as some methods depend on your secret key, this SDK is not to be used in browsers.
This package provides a convenient interface to query the [MagicBell](https://magicbell.com) API. Note that some methods depend on your secret key, those methods are not to be used in browsers, as your secret key must be kept secret.
## Requirements
Node 14 or higher.
Node 18.13 or higher.
When using older versions, you might need to polyfill `fetch`. See [isomorphic-fetch](https://npmjs.com/isomorphic-fetch) for more information.
## Installation

@@ -29,5 +31,5 @@

```js
import MagicBell from 'magicbell';
import { ProjectClient } from 'magicbell/project-client';
const magicbell = new MagicBell({
const magicbell = new ProjectClient({
apiKey: 'your-api-key',

@@ -52,5 +54,5 @@ apiSecret: 'your-api-secret',

```js
const MagicBell = require('magicbell').default;
const { ProjectClient } = require('magicbell/project-client');
const magicbell = new MagicBell({
const magicbell = new ProjectClient({
apiKey: 'your-api-key',

@@ -70,8 +72,9 @@ apiSecret: 'your-api-secret',

Some endpoints, like `notifications.list` are user oriented, and require the `userEmail` option to be set. This can be done via the client options, or on a per-request basis:
Some endpoints, like `notifications.list` are user oriented, and can be consumed via a user specific client, authenticated using `apiKey` and `userEmail` or `apiKey` and `userExternalId` option.
```js
const magicbell = new MagicBell({
import { UserClient } from 'magicbell/user-client';
const magicbell = new UserClient({
apiKey: 'your-api-key',
apiSecret: 'your-api-secret',
userEmail: 'you@example.com',

@@ -81,7 +84,2 @@ });

const notifications = await magicbell.notifications.list();
// alternatively, provide the userEmail via request option instead
const notifications = await magicbell.notifications.list({
userEmail: 'someone@example.com',
});
```

@@ -91,12 +89,8 @@

This can for example be used to fetch notification preferences for specific users:
This can for example be used to increase the network timeout.
```js
const johnsPreferences = await magicbell.notificationPreferences.list({
userEmail: 'john@example.com',
timeout: 30_000,
});
const janesPreferences = await magicbell.notificationPreferences.list({
userEmail: 'jane@example.com',
});
```

@@ -156,14 +150,37 @@

The package can be initialized with several options:
The package can be initialized with several options, and in two scopes. There's an project client, and a user client.
#### Project Scope
The project client is used to make requests on behalf of the project, and requires the `apiKey` and `apiSecret` options to be set.
```js
import MagicBell from 'magicbell';
import { ProjectClient } from 'magicbell/project-client';
const magicbell = new MagicBell({
host: 'https://api.magicbell.com',
const magicbell = new ProjectClient({
// auth
apiKey: 'your-api-key', // required
apiSecret: 'your-secret-key', // required
// network
timeout: 30_000,
maxRetries: 3,
maxRetryDelay: 60,
telemetry: true,
});
```
#### User Scope
The user client is used to make requests on behalf of a user, and requires the `apiKey` and one of `userEmail` or `userExternalId` options to be set. If your project has HMAC enabled, the `userHmac` option is also required. As no `apiSecret` is needed, this client is suitable for client side usage and safe to be used in the browser.
```js
import { UserClient } from 'magicbell/user-client';
const magicbell = new UserClient({
// auth
apiKey: 'your-api-key', // required
apiSecret: 'your-secret-key', // required for project oriented endpoints
userEmail: 'you@example.com', // required for user oriented endpoints
userEmail: 'you@example.com', // 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

@@ -175,5 +192,2 @@ // network

telemetry: true,
// logging
debug: false,
});

@@ -192,10 +206,18 @@ ```

- **apiSecret** _String_
- **apiSecret** _String_ [project client only]
Your project api secret which can be found on the [MagicBell Dashboard][dashboard]. This key is required for project oriented endpoints.
Your project api secret which can be found on the [MagicBell Dashboard][dashboard]. This key is required for admin oriented endpoints.
- **userEmail** _String_
- **userEmail** _String_ [user client only]
The email of the user you want to make requests for. This key is required for user oriented endpoints, but can also be provided on a per request basis. You only want to provide it to the client, if you're using the SDK for a single user/inbox.
The email of the user you want to make requests for. This key is required for user oriented endpoints when no `userExternalId` is set.
- **userExternalId** _String_ [user client only]
The external-id of the user you want to make requests for. This key is required for user oriented endpoints when no `userEmail` is set.
- **userHmac** _String_ [user client only]
The HMAC of the user you want to make requests for. This key is required for user oriented endpoints when HMAC is enabled.
- **timeout** _Number_

@@ -245,11 +267,2 @@

### Configuring for users
A per-request `userEmail` header can be added to any method. Note that we'll automatically add a `userKey` containing [the HMAC][hmac-authentication], if you've provided the `apiSecret` option.
```js
// List the notifications for a specific account
magicbell.notifications.list({ page: 1 }, { userEmail: 'person@example.com' });
```
### Network retries

@@ -259,3 +272,5 @@

> note: automatic retries are meant to handle short network disturbances. They're handled in-process, and don't use a persistent job queue. They won't survive process restarts. You might need to implement your own persistent workers with retry logic if delivery is crucial to your business.
> **Note**
>
> Automatic retries are meant to handle short network disturbances. They're handled in-process, and don't use a persistent job queue. They won't survive process restarts. You might need to implement your own persistent workers with retry logic if delivery is crucial to your business.

@@ -331,10 +346,23 @@ We'll automatically add [idempotency keys][idempotent-requests] if you haven't provided on, to prevent duplication.

## Resource methods
## Resource Methods
Below you'll find the all supported resource methods, with their signatures. The full documentation can be found in our [api-reference][api-reference]. When comparing the api-reference with these methods, you'll notice that the SDK removes any wrapping entities for your convenience. Meaning, instead of posting `{ notification: { title: 'hi' } }`, you'll call `create({ title: 'hi' })`.
The SDK is divided in two scopes. [Project Resources](#project-resource-methods), and [User Resources](#user-resource-methods). Below you'll find the all supported resource methods, with their signatures. The full documentation can be found in our [api-reference][api-reference]. When comparing the api-reference with these methods, you'll notice that the SDK removes any wrapping entities for your convenience. Meaning, instead of posting `{ notification: { title: 'hi' } }`, you'll call `create({ title: 'hi' })`.
Apart from the removal of the wrappers, returned entities and provided parameters are identical between our REST API and this SDK.
<!-- AUTO-GENERATED-CONTENT:START (RESOURCE_METHODS) -->
## Project Resource Methods
The project scope contains everything you need to manage your project and send notifications. You'll need to be authenticated using `apiKey` and `apiSecret` to use these methods.
```js
import { ProjectClient } from 'magicbell/project-client';
const magicbell = new ProjectClient({
apiKey: 'your-api-key', // required
apiSecret: 'your-secret-key', // required
});
```
<!-- AUTO-GENERATED-CONTENT:START (PROJECT_RESOURCE_METHODS) -->
### Broadcasts

@@ -421,123 +449,2 @@

#### Fetch notifications
Fetch a user's notifications. Notifications are sorted in descendent order by the sent_at timestamp.
```js
await magicbell.notifications.list(
{
per_page: 1,
page: 1,
read: true,
seen: true,
archived: true,
categories: ['…'],
topics: ['…'],
},
{
userEmail: 'person@example.com',
},
);
```
#### Fetch notification by ID
Fetch a user's notification by its ID.
```js
await magicbell.notifications.get('{notification_id}', {
userEmail: 'person@example.com',
});
```
#### Delete a notification
Delete a user's notification by its ID. The notification is deleted immediately and removed from the user's notification inbox in real-time.
```js
await magicbell.notifications.delete('{notification_id}', {
userEmail: 'person@example.com',
});
```
#### Mark a notification as read
Mark a user notification as read. The notification will be automatically marked as seen, too.
The new state will be reflected in the user's notification inbox in real-time.
```js
await magicbell.notifications.markAsRead('{notification_id}', {
userEmail: 'person@example.com',
});
```
#### Mark a notification as unread
Mark a user notification as unread. The new state will be reflected in the user's notification inbox in real-time.
```js
await magicbell.notifications.markAsUnread('{notification_id}', {
userEmail: 'person@example.com',
});
```
#### Archive a notification
Mark a user notification as archived.
```js
await magicbell.notifications.archive('{notification_id}', {
userEmail: 'person@example.com',
});
```
#### Unarchive a notification
Mark a user notification as unarchived.
```js
await magicbell.notifications.unarchive('{notification_id}', {
userEmail: 'person@example.com',
});
```
#### Mark all notifications as read
Mark all notifications of a user as read. When you call this endpoint, the notification inboxes of this user will be updated in real-time.
```js
await magicbell.notifications.markAllRead(
{
archived: true,
read: true,
seen: true,
categories: ['…'],
topics: ['…'],
},
{
userEmail: 'person@example.com',
},
);
```
#### Mark all notifications as seen
Mark all notifications of a user as seen. When you call this endpoint, the notification inboxes of this user will be updated in real-time.
```js
await magicbell.notifications.markAllSeen(
{
archived: true,
read: true,
seen: true,
categories: ['…'],
topics: ['…'],
},
{
userEmail: 'person@example.com',
},
);
```
### Users

@@ -696,187 +603,247 @@

### Push Subscriptions
### Imports
#### Register a device token for a user
#### Create a import
Register a device token for push notifications.
Enqueues an import - currently only supported for users. Amongst other things, the users import allows associating slack channels (if you have already setup the oauth apps).
Please keep in mind that mobile push notifications will be delivered to this device only if the channel is configured and enabled.
```js
await magicbell.imports.create({
users: [
{
external_id: 'ugiabqertz',
email: 'johndoe@example.com',
first_name: 'John',
last_name: 'Doe',
custom_attributes: {
age: 32,
country: 'Spain',
},
channels: {
slack: {
providers: [
{
oauth: {
channel_id: 'U039446XF3Y',
app: {
app_id: 'your_slack_app_id',
team_id: 'workspace_id_from_slack',
},
},
},
],
},
},
},
],
});
```
#### 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.
```js
await magicbell.pushSubscriptions.create(
{
device_token: 'x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV',
platform: 'ios',
},
{
userEmail: 'person@example.com',
},
);
await magicbell.imports.get('{import_id}');
```
#### Delete user's device token
### Metrics
Deletes the registered device token to remove the mobile push subscription.
#### Get notification metrics
Query the metrics of notification broadcasts and their recipients.
```js
await magicbell.pushSubscriptions.delete('{device_token}', {
userEmail: 'person@example.com',
await magicbell.metrics.get();
```
### Metrics Categories
#### Get notification metrics grouped by category
Query the metrics of notification broadcasts and their recipients, grouped by category.
```js
await magicbell.metrics.categories.get();
```
### Metrics Topics
#### Get notification metrics grouped by topic
Query the metrics of notification broadcasts and their recipients, grouped by topic.
```js
await magicbell.metrics.topics.get();
```
<!-- AUTO-GENERATED-CONTENT:END (PROJECT_RESOURCE_METHODS) -->
## User Resource Methods
The user scope contains everything a specific user needs to display their notifications and manage their settings. They'll need to be authenticated using `apiKey`, either `userEmail` or `userExternalId`, and `userHmac` when HMAC is enabled on your project.
As you don't need to authenticate using the `apiSecret`, this scope is safe to use in the browser.
```js
import { UserClient } from 'magicbell/user-client';
const magicbell = new UserClient({
apiKey: 'your-api-key', // required
userEmail: 'you@example.com', // 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
});
```
### Notification Preferences
<!-- AUTO-GENERATED-CONTENT:START (USER_RESOURCE_METHODS) -->
#### Fetch user notification preferences
### Notifications
Fetch a user's notification preferences. If a user does not disable a channel explicitly, we would send notifications through that channel as long as your project is enabled.
#### Fetch notifications
Fetch a user's notifications. Notifications are sorted in descendent order by the sent_at timestamp.
```js
await magicbell.notificationPreferences.get({
userEmail: 'person@example.com',
await magicbell.notifications.list({
per_page: 1,
page: 1,
read: true,
seen: true,
archived: true,
categories: ['…'],
topics: ['…'],
});
```
#### Update user notification preferences
#### Fetch notification by ID
Update a user's notification preferences. These preferences will be applied only to channels you enabled for your project.
Fetch a user's notification by its ID.
```js
await magicbell.notificationPreferences.update(
{
categories: [
{
slug: 'billing',
channels: [
{
slug: 'email',
enabled: false,
},
{
slug: 'web_push',
enabled: false,
},
],
},
],
},
{
userEmail: 'person@example.com',
},
);
await magicbell.notifications.get('{notification_id}');
```
### Subscriptions
#### Delete a notification
#### Fetch user's topic subscriptions
Delete a user's notification by its ID. The notification is deleted immediately and removed from the user's notification inbox in real-time.
Fetch a user's topic subscriptions.
```js
await magicbell.notifications.delete('{notification_id}');
```
#### Mark a notification as read
Mark a user notification as read. The notification will be automatically marked as seen, too.
The new state will be reflected in the user's notification inbox in real-time.
```js
await magicbell.subscriptions.list({
userEmail: 'person@example.com',
});
await magicbell.notifications.markAsRead('{notification_id}');
```
#### Create a topic subscription
#### Mark a notification as unread
Set a user's subscription status to subscribed for a particular topic (and optional categories). If the user previously unsubscribed, the user will be resubscribed.
Mark a user notification as unread. The new state will be reflected in the user's notification inbox in real-time.
```js
await magicbell.subscriptions.create(
{
categories: [
{
slug: 'comments',
reason: 'watching-the-repo',
},
],
topic: 'acme-inc.orders.1234',
},
{
userEmail: 'person@example.com',
},
);
await magicbell.notifications.markAsUnread('{notification_id}');
```
#### Unsubscribe from a topic
#### Archive a notification
Unusbscribe a user from a particular topic (and optional categories).
Mark a user notification as archived.
```js
await magicbell.subscriptions.unsubscribe(
'{topic}',
{
categories: [
{
slug: 'comments',
},
],
},
{
userEmail: 'person@example.com',
},
);
await magicbell.notifications.archive('{notification_id}');
```
#### Show a topic subscription
#### Unarchive a notification
Show a user's subscription status for a particular topic and categories.
Mark a user notification as unarchived.
```js
await magicbell.subscriptions.get('{topic}', {
userEmail: 'person@example.com',
await magicbell.notifications.unarchive('{notification_id}');
```
#### Mark all notifications as read
Mark all notifications of a user as read. When you call this endpoint, the notification inboxes of this user will be updated in real-time.
```js
await magicbell.notifications.markAllRead({
archived: true,
read: true,
seen: true,
categories: ['…'],
topics: ['…'],
});
```
#### Delete topic subscription(s)
#### Mark all notifications as seen
Mark all notifications of a user as seen. When you call this endpoint, the notification inboxes of this user will be updated in real-time.
```js
await magicbell.subscriptions.delete(
'{topic}',
{
categories: [
{
slug: '…',
},
],
},
{
userEmail: 'person@example.com',
},
);
await magicbell.notifications.markAllSeen({
archived: true,
read: true,
seen: true,
categories: ['…'],
topics: ['…'],
});
```
### Imports
### Push Subscriptions
#### Create a import
#### Register a device token for a user
Enqueues an import - currently only supported for users. Amongst other things, the users import allows associating slack channels (if you have already setup the oauth apps).
Register a device token for push notifications.
Please keep in mind that mobile push notifications will be delivered to this device only if the channel is configured and enabled.
```js
await magicbell.imports.create({
users: [
await magicbell.pushSubscriptions.create({
device_token: 'x4doKe98yEZ21Kum2Qq39M3b8jkhonuIupobyFnL0wJMSWAZ8zoTp2dyHgV',
platform: 'ios',
});
```
#### Delete user's device token
Deletes the registered device token to remove the mobile push subscription.
```js
await magicbell.pushSubscriptions.delete('{device_token}');
```
### Notification Preferences
#### Fetch user notification preferences
Fetch a user's notification preferences. If a user does not disable a channel explicitly, we would send notifications through that channel as long as your project is enabled.
```js
await magicbell.notificationPreferences.get();
```
#### Update user notification preferences
Update a user's notification preferences. These preferences will be applied only to channels you enabled for your project.
```js
await magicbell.notificationPreferences.update({
categories: [
{
external_id: 'ugiabqertz',
email: 'johndoe@example.com',
first_name: 'John',
last_name: 'Doe',
custom_attributes: {
age: 32,
country: 'Spain',
},
channels: {
slack: {
providers: [
{
oauth: {
channel_id: 'U039446XF3Y',
app: {
app_id: 'your_slack_app_id',
team_id: 'workspace_id_from_slack',
},
},
},
],
slug: 'billing',
channels: [
{
slug: 'email',
enabled: false,
},
},
{
slug: 'web_push',
enabled: false,
},
],
},

@@ -887,41 +854,63 @@ ],

#### Get the status of an import
### Subscriptions
Query the status of the import for a summary of imported records and failures for each record that could not be imported successfully.
#### Fetch user's topic subscriptions
Fetch a user's topic subscriptions.
```js
await magicbell.imports.get('{import_id}');
await magicbell.subscriptions.list();
```
### Metrics
#### Create a topic subscription
#### Get notification metrics
Set a user's subscription status to subscribed for a particular topic (and optional categories). If the user previously unsubscribed, the user will be resubscribed.
Query the metrics of notification broadcasts and their recipients.
```js
await magicbell.metrics.get();
await magicbell.subscriptions.create({
categories: [
{
slug: 'comments',
reason: 'watching-the-repo',
},
],
topic: 'acme-inc.orders.1234',
});
```
### Metrics Categories
#### Unsubscribe from a topic
#### Get notification metrics grouped by category
Unusbscribe a user from a particular topic (and optional categories).
Query the metrics of notification broadcasts and their recipients, grouped by category.
```js
await magicbell.metrics.categories.get();
await magicbell.subscriptions.unsubscribe('{topic}', {
categories: [
{
slug: 'comments',
},
],
});
```
### Metrics Topics
#### Show a topic subscription
#### Get notification metrics grouped by topic
Show a user's subscription status for a particular topic and categories.
Query the metrics of notification broadcasts and their recipients, grouped by topic.
```js
await magicbell.subscriptions.get('{topic}');
```
#### Delete topic subscription(s)
```js
await magicbell.metrics.topics.get();
await magicbell.subscriptions.delete('{topic}', {
categories: [
{
slug: '…',
},
],
});
```
<!-- AUTO-GENERATED-CONTENT:END (RESOURCE_METHODS) -->
<!-- AUTO-GENERATED-CONTENT:END (USER_RESOURCE_METHODS) -->

@@ -940,3 +929,3 @@ ## Realtime

magicbell.listen({ userEmail: 'someone@example.com' });
magicbell.listen();
```

@@ -943,0 +932,0 @@

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc