notifyon

NotifyOn Node.js SDK

Send real-time browser and push notifications to your users when long-running agent tasks complete.

Installation

npm install notifyon
# or
yarn add notifyon
# or
pnpm add notifyon

Quick Start

import { NotifyOn } from 'notifyon';

// Initialize the client
const notifyon = new NotifyOn({
  apiKey: process.env.NOTIFYON_API_KEY
});

// That's it! Just send a notification when your agent task completes
await notifyon.send('user_123');

// Optionally, you can include a custom message
await notifyon.send('user_123', 'Your data analysis is complete');

How It Works

NotifyOn uses a progressive notification strategy that automatically handles channel selection:

• Browser Sound (enabled by default): Plays a pleasant notification sound when the user has your site open
• Push Notifications (enabled by default): Shows only when the user's tab is not visible/focused
• Email (coming soon): Sends only if both browser and push fail to deliver
• Slack (coming soon): Integration with Slack workspaces

No configuration needed! Users are automatically set up with sensible defaults when you first call send().

API Reference

new NotifyOn(config)

Creates a new NotifyOn client instance.

Parameters:

• config.apiKey (required): Your NotifyOn API key
• config.baseUrl (optional): Custom API endpoint (defaults to https://dashboard.notifyon.app/v1)

notifyon.send(userId, message?)

Send a notification to a user when their task completes.

Parameters:

• userId: External user identifier
• message (optional): Custom notification message

Returns: Promise<void>

// Simple notification
await notifyon.send('user_123');

// With custom message
await notifyon.send('user_123', 'Your report is ready for download');

notifyon.set(userId, preferences)

Optional method - Only use if you need to manually control channel preferences.

By default, browser and push are enabled automatically. Use this method only to:

• Disable specific channels for a user
• Give users control over their notification preferences

Parameters:

• userId: External user identifier
• preferences: Object containing channel preferences
  • browser: Enable/disable browser sound notifications
  • push: Enable/disable push notifications
  • email: Enable/disable email notifications (future)
  • slack: Enable/disable Slack notifications (future)

Returns: Promise<void>

// Example: User disabled push notifications in their settings
await notifyon.set('user_123', { push: false });

// Example: User wants only browser sounds
await notifyon.set('user_123', { browser: true, push: false });

Error Handling

The SDK throws NotifyOnError for API errors:

import { NotifyOn, NotifyOnError } from 'notifyon';

try {
  await notifyon.send('user_123');
} catch (error) {
  if (error instanceof NotifyOnError) {
    console.error('NotifyOn Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Error Code:', error.code);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { NotifyOn, NotifyOnConfig, NotificationPreferences } from 'notifyon';

const config: NotifyOnConfig = {
  apiKey: 'your-api-key'
};

// Optional: Only if you need manual control
const preferences: NotificationPreferences = {
  browser: true,
  push: false,
  email: false,
  slack: false
};

Browser Integration

To receive notifications in the browser, include the NotifyOn browser SDK in your web application:

// In your web app
import { NotifyOn } from '@notifyon/web';

const client = new NotifyOn({
  publicKey: 'your-public-key',
  userId: 'user_123'
});

// Connect to receive notifications
await client.connect();

The browser SDK will:

• Play a soft, pleasant sound when notifications arrive (if tab is visible)
• Show push notifications when the tab is hidden/unfocused
• Automatically handle the progressive notification strategy

Requirements

• Node.js >= 18.0.0
• Valid NotifyOn API key (get one at dashboard.notifyon.app)

License

MIT