EduSight Notification SDK

TypeScript/JavaScript SDK for the EduSight Notification Service.

Installation

npm install @edusight/notification-sdk

Usage

SDK Initialization (Recommended)

For a complete initialization experience with subscriber context management, use the NotificationSDK:

import { NotificationSDK } from '@edusight/notification-sdk';

// Initialize SDK with subscriberId and applicationIdentifier
const sdk = new NotificationSDK(
  'user_123',           // subscriberId
  'app_456',            // applicationIdentifier
  {
    apiUrl: 'http://localhost:3000',
    socketUrl: 'http://localhost:3000',  // Optional: for real-time events
    apiKey: 'your-api-key',
    tenantId: 'your-tenant-id',
    environmentId: 'default',
    locale: 'en-US',
  }
);

// Set subscriber context
sdk.setContext('userId', 'user_123');
sdk.setContext('role', 'admin');

// Set subscriber data
sdk.setSubscriberData({
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
});

// Connect to WebSocket for real-time events
sdk.connectSocket();

// Access the HTTP client
const client = sdk.getClient();
const notifications = await client.notifications.list();

For detailed SDK initialization documentation, see SDK_INITIALIZATION.md.

Direct Client Usage

Alternatively, use NotificationClient directly for lower-level control:

import { NotificationClient } from '@edusight/notification-sdk';

const client = new NotificationClient({
  apiKey: 'your-api-key',
  apiUrl: 'https://api.example.com',
  apiScope: 'api', // optional, defaults to 'api'
  apiVersion: 'v1', // optional, defaults to 'v1'
  tenantId: 'your-tenant-id',
  environmentId: 'default',
});

The SDK automatically injects x-tenant-id and x-environment-id headers on every request, so make sure both values are provided (the environment header is required to route between staging/dev/prod workloads).

API version composition

NotificationClient builds the HTTP base URL from apiUrl, apiScope, and apiVersion (defaults: api, v1), so every service call targets https://host/api/v1/.... Changing the configured scope or version via setApiScope() / setApiVersion() keeps REST endpoints stable, and the real-time client derives its WebSocket handshake from the same host + version pair (scope is not reused), eliminating the need to concatenate /api/v1 yourself.

Workflows

const workflows = await client.workflows.list();

const workflow = await client.workflows.create({
  workflowId: 'welcome-email',
  name: 'Welcome Email',
  steps: [],
  triggers: ['user-registered'],
});

const preview = await client.workflows.preview('welcome-email', {
  payload: { userName: 'John' },
});

await client.workflows.sync('welcome-email', {
  targetEnvironmentId: 'production',
});

Events

await client.events.trigger({
  eventType: 'user-registered',
  userId: 'user-123',
  payload: { userName: 'John' },
});

await client.events.triggerBulk([
  { eventType: 'user-registered', userId: 'user-1', payload: {} },
  { eventType: 'user-registered', userId: 'user-2', payload: {} },
]);

await client.events.broadcast({
  eventType: 'announcement',
  payload: { message: 'System maintenance' },
});

Topics

const topics = await client.topics.list();

await client.topics.create({
  key: 'product-updates',
  name: 'Product Updates',
});

await client.topics.addSubscribers('product-updates', ['sub-1', 'sub-2']);

Subscribers

await client.subscribers.create({
  subscriberId: 'user-123',
  email: '[email protected]',
});

await client.preferences.update('user-123', {
  channels: [Channel.EMAIL, Channel.PUSH],
});

await client.subscribers.addTokens('user-123', ['fcm-token'], 'your-tenant-id', 'dev');

Notifications

const inbox = await client.notifications.list({
  subscriberId: 'user-123',
  limit: 50,
});

const unreadCount = await client.notifications.getUnreadCount('user-123');

await client.notifications.markAsRead('notification-id', 'user-123');

await client.notifications.delete('notification-id', 'user-123');

await client.notifications.markAllAsRead('user-123');

client.notifications exposes a first-class inbox API that mirrors the /inbox/notifications endpoints on the service (list, unread count, read/unread toggles, delete).

Inbox

const notifications = await client.inbox.getNotifications('user-123');

await client.inbox.markAsRead('user-123', 'notification-id');

await client.inbox.markAllAsRead('user-123');

Analytics

const metrics = await client.analytics.getMetrics({
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  channel: 'push',
});

Services

• client.workflows - Workflow management
• client.events - Event triggering
• client.topics - Topic management
• client.subscribers - Subscriber management
• client.preferences - Preference management
• client.inbox - Inbox operations
• client.integrations - Integration management
• client.analytics - Analytics

client.integrations now exposes activation/health helpers so you can toggle, inspect, and refresh adapter caches:

await client.integrations.activate('integration-id', 'your-tenant-id', 'staging');
await client.integrations.health('integration-id', 'your-tenant-id', 'staging');
await client.integrations.clearCache('integration-id', 'your-tenant-id', 'staging');

Real-time WebSocket Client

NotificationSocketClient pairs with the backend /notifications namespace to provide:

• resilient reconnects with configurable delays and retry limits,
• persisted acknowledgement queue that survives page reloads via localStorage,
• typed events for delivery updates and ack confirmations,
• automatic context propagation (tenantId, environmentId, subscriberId).
  • the gateway requires tenantId, environmentId, and subscriberId as part of the handshake query (or via auth.token) so the service can route you into the correct tenant/room.

The WebSocket gateway is co-hosted with the HTTP API on the same host and PORT (the apiUrl value configured for NotificationClient). The SDK therefore derives its namespace from apiVersion and DEFAULT_NAMESPACE Simply use your API base when constructing NotificationSocketClient.

import { NotificationSocketClient } from '@edusight/notification-sdk';

const socketClient = new NotificationSocketClient({
  apiHost: client.getApiHost(),
  apiVersion: client.getApiVersion(),
  tenantId: 'your-tenant-id',
  environmentId: 'dev',
  subscriberId: 'user-123',
  path: '/notifications',
});

socketClient.on('notification', (payload) => {
  console.log('Live notification', payload);
});

socketClient.on('ack', (ack) => {
  console.log('Delivery acknowledged', ack.notificationId);
});

socketClient.connect();

If your deployment uses a custom socket path (e.g., the Nest gateway listens at /notifications instead of /socket.io), pass that value via the path option. Otherwise the client will default to the Socket.IO standard /socket.io handshake route.

Call socketClient.ack(notificationId) to send an acknowledgement; pending IDs are retried automatically whenever the socket reconnects.

Local Development Setup

Installing SDK Locally for Dashboard Development

To use this SDK locally in the EduSight-Notification-Dashboard project without publishing to npm, use the provided installation script:

./install-sdk-local.sh

This script will:

1. Build the SDK (npm run build)
2. Create a global npm link
3. Link the SDK into the Dashboard's node_modules directory
4. No changes to package.json - uses symlinks only

Requirements:

• Both Edusight-Notification-SDK and EduSight-Notification-Dashboard must be in the same parent directory
• Node.js 18+ installed
• npm installed

To unlink:

cd ../EduSight-Notification-Dashboard
npm unlink @edusight/notification-sdk

cd ../Edusight-Notification-SDK
npm unlink

Note: When you publish to npm, you can replace the link with:

npm install @edusight/notification-sdk

License

MIT