@notiflyio/js

Notifly JavaScript SDK

The @notiflyio/js package provides a JavaScript SDK for building custom inbox notification experiences. The package provides a low-level API for interacting with the Notifly platform In-App notifications.

Note: the SDK's exported class is named Novu — Notifly is a fork of Novu and keeps upstream code identifiers for easy upgrades.

Installation

Install @notiflyio/js npm package in your app

npm install @notiflyio/js

Getting Started

Add the below code in your application

import { Novu } from '@notiflyio/js';

const novu = new Novu({
  applicationIdentifier: 'YOUR_NOTIFLY_APPLICATION_IDENTIFIER',
  subscriber: 'YOUR_INTERNAL_SUBSCRIBER_ID',
});

const { data: notifications, error } = await novu.notifications.list();

|| Info: you can find the applicationIdentifier in the Notifly dashboard under the API keys page.

HMAC Encryption

When HMAC encryption is enabled in your Notifly environment, you need to provide both subscriberHash and optionally contextHash to secure your requests.

Subscriber HMAC

Generate a subscriber hash on your backend:

import { createHmac } from 'crypto';

const subscriberHash = createHmac('sha256', process.env.NOTIFLY_SECRET_KEY)
  .update(subscriberId)
  .digest('hex');

Pass it to the Novu instance:

const novu = new Novu({
  applicationIdentifier: 'YOUR_NOTIFLY_APPLICATION_IDENTIFIER',
  subscriber: 'SUBSCRIBER_ID',
  subscriberHash: 'SUBSCRIBER_HASH_VALUE',
});

Context HMAC (Optional)

If you're using the context option to pass additional data, generate a context hash on your backend:

import { createHmac } from 'crypto';
import { canonicalize } from '@tufjs/canonical-json';

const context = { tenant: 'acme', app: 'dashboard' };
const contextHash = createHmac('sha256', process.env.NOTIFLY_SECRET_KEY)
  .update(canonicalize(context))
  .digest('hex');

Pass both context and contextHash to the Novu instance:

const novu = new Novu({
  applicationIdentifier: 'YOUR_NOTIFLY_APPLICATION_IDENTIFIER',
  subscriber: 'SUBSCRIBER_ID',
  subscriberHash: 'SUBSCRIBER_HASH_VALUE',
  context: { tenant: 'acme', app: 'dashboard' },
  contextHash: 'CONTEXT_HASH_VALUE',
});

Note: When HMAC encryption is enabled and context is provided, the contextHash is required. The hash is order-independent, so {a:1, b:2} produces the same hash as {b:2, a:1}.

Socket Options

You can provide custom socket configuration options using the socketOptions parameter. These options will be merged with the default socket configuration when initializing the WebSocket connection.

Socket Type

By default, the socket type is determined automatically based on the socketUrl. You can explicitly set the socket type using the socketType option:

• 'cloud' — uses PartySocket
• 'self-hosted' — uses socket.io (the default for custom/self-hosted URLs, including Notifly's ws service)

This is useful when proxying the websocket service through your own domain where the URL no longer matches the expected pattern:

const novu = new Novu({
  applicationIdentifier: 'YOUR_NOTIFLY_APPLICATION_IDENTIFIER',
  subscriber: 'YOUR_INTERNAL_SUBSCRIBER_ID',
  socketUrl: 'wss://your-proxy.example.com/notifly-socket',
  socketOptions: {
    socketType: 'self-hosted',
  },
});

Custom socket.io Options

When using socket.io (socketType: 'self-hosted' or a custom URL), you can pass any socket.io-client options:

const novu = new Novu({
  applicationIdentifier: 'YOUR_NOTIFLY_APPLICATION_IDENTIFIER',
  subscriber: 'YOUR_INTERNAL_SUBSCRIBER_ID',
  socketOptions: {
    reconnectionDelay: 5000,
    timeout: 20000,
    path: '/my-custom-path',
    // ... other socket.io-client options
  },
});