@notifyhub/node

@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.users.upsert({
  id: 'user-123',
  profile: {
    email: '[e-mail]',
    name: 'Taylor Example',
  },
});

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

await notifyhub.notifications.send({
  to: {
    id: 'user-123',
    profile: {
      email: '[e-mail]',
      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.users

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<UpsertUserResponse>.

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 getSignedInUserFromYourApp(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
• NotifyHubUser
• UpsertUserParams
• UpsertUserResponse

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

• Build:

cd packages/node && bun run build

• Typecheck:

cd packages/node && bun run check-types