@notifyhub/node

@notifyhub/node is the privileged server package for NotifyHub.

It is for trusted backend code only and is the package that should own your NotifyHub secret key.

It handles:

• recipient session token issuance
• recipient upsert
• server-side inbox notification send

It also exposes a small @notifyhub/node/next helper for Next.js route handlers.

Install

npm install @notifyhub/node

When To Use This Package

Use @notifyhub/node when you need to:

• issue short-lived browser session tokens from your backend
• upsert a recipient profile from trusted server code
• send an inbox notification from your backend

Do not use this package in browser bundles.

Quick Start

import {createNotifyHub} from '@notifyhub/node';

const notifyhub = createNotifyHub({
  baseUrl: 'https://notifyhub.example.com',
  secretKey: process.env.NOTIFYHUB_SECRET_KEY!,
});

await notifyhub.recipients.upsert({
  id: 'recipient-123',
  profile: {
    email: '[email protected]',
    name: 'Taylor Example',
  },
});

const session = await notifyhub.auth.issueSessionToken({
  recipient: {id: 'recipient-123'},
  expiresIn: '30m',
});

await notifyhub.notifications.send({
  to: {
    id: 'recipient-123',
    profile: {
      email: '[email protected]',
      name: 'Taylor Example',
    },
  },
  title: 'Order shipped',
  body: 'Your order is on the way.',
});

Public API

Constructors

| Export | Description | |--------|-------------| | new NotifyHub(config) | Creates the server client directly | | createNotifyHub(config) | Factory helper |

NotifyHubNodeConfig

| Field | Type | Required | Description | |-------|------|----------|-------------| | baseUrl | string | yes | Base URL for the NotifyHub API | | secretKey | string | yes | Trusted server secret key | | fetch | typeof fetch | no | Fetch override for tests or custom runtimes |

notifyhub.auth

issueSessionToken(params)

Issues a short-lived, recipient-scoped session token for browser clients.

| Field | Type | Required | Description | |-------|------|----------|-------------| | recipient | NotifyHubRecipient | yes | Recipient identity used for the token | | expiresIn | number \| string | no | Token lifetime such as 30m, 15m, or a millisecond value | | scopes | NotifyHubSessionScope[] | no | Explicit scope list |

Returns Promise<NotifyHubSession>.

Supported scopes:

• inbox:read
• inbox:write
• preferences:read
• preferences:write

notifyhub.recipients

upsert(params)

Upserts a recipient profile in NotifyHub.

| Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | yes | Your application's canonical recipient ID | | profile | NotifyHubRecipientProfile | no | Optional profile fields to merge |

Returns Promise<UpsertRecipientResponse>.

notifyhub.notifications

send(params)

Sends an inbox notification from trusted server code.

| Field | Type | Required | Description | |-------|------|----------|-------------| | to | NotifyHubRecipient | yes | Recipient to target | | title | string | yes | Notification title | | body | string | yes | Notification body | | type | NotifyHubNotificationType | no | Visual notification type | | priority | NotifyHubNotificationPriority | no | Delivery priority | | data | Record<string, unknown> | no | Extra payload | | topicId | string | no | Topic association | | channels | string[] | no | Explicit channels, defaults to ['inbox'] |

Returns Promise<SendNotificationResponse>.

to.profile can be included during send() so the recipient can be upserted as part of the privileged send path.

Next.js Helper

The @notifyhub/node/next subpath exports createSessionRouteHandler() for App Router route handlers.

import {createNotifyHub} from '@notifyhub/node';
import {createSessionRouteHandler} from '@notifyhub/node/next';

const notifyhub = createNotifyHub({
  baseUrl: process.env.NOTIFYHUB_BASE_URL!,
  secretKey: process.env.NOTIFYHUB_SECRET_KEY!,
});

export const POST = createSessionRouteHandler({
  notifyhub,
  resolveRecipient: async (request) => {
    const session = await getAuthenticatedRecipientFromYourApp(request);

    if (!session) {
      return null;
    }

    return {
      id: session.userId,
      profile: {
        email: session.email,
        name: session.name,
      },
    };
  },
  getSessionOptions: async () => ({
    expiresIn: '30m',
    scopes: ['inbox:read', 'inbox:write', 'preferences:read', 'preferences:write'],
  }),
});

createSessionRouteHandler(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | notifyhub | NotifyHub | yes | Configured server client | | resolveRecipient | (request) => NotifyHubRecipient \| null | yes | Resolves the authenticated recipient from your app | | getSessionOptions | (request, recipient) => NotifyHubSessionHandlerOptions \| null \| undefined | no | Per-request token options | | onUnauthorized | (request) => Response | no | Custom unauthorized response |

The helper returns a handler that responds with a JSON NotifyHubSession on success and 401 on failure unless overridden.

Exported Types

Core Types

• NotifyHubNodeConfig
• NotifyHubSession
• NotifyHubSessionScope
• NotifyHubSessionHandlerOptions
• NotifyHubApiError

Recipient Types

• NotifyHubRecipient
• NotifyHubRecipientProfile
• NotifyHubRecipientRecord
• UpsertRecipientParams
• UpsertRecipientResponse

Send And Token Types

• IssueSessionTokenParams
• SendNotificationParams
• SendNotificationResponse
• NotifyHubNotificationType
• NotifyHubNotificationPriority

Recipient Profile Fields

NotifyHubRecipientProfile supports these optional fields:

• email
• emailVerified
• phone
• phoneVerified
• name
• firstName
• lastName
• avatarUrl
• company
• jobTitle
• locale
• timezone
• tags
• customAttributes

Important Behaviors

• This package is server-only. Never expose secretKey to a browser client.
• Browser clients should authenticate with session tokens issued by your backend, not with the secret key.
• Session tokens are recipient-scoped and intended for inbox and preference access.
• send() is intentionally server-only and is not part of @notifyhub/client.
• Request failures throw an Error with a status property when the backend returns an HTTP error.

Development

From the monorepo root:

bun install

• Tests:

cd packages/node && bun run test:it

• Build:

cd packages/node && bun run build

• Typecheck:

cd packages/node && bun run check:types