@afrisinc/notify-sdk

@afrisinc/notify-sdk

Official SDK for the Notify API — send notifications across email, SMS, push, WhatsApp, and in-app.

Installation

npm install @afrisinc/notify-sdk

Quick Start

import { Notify } from '@afrisinc/notify-sdk';

const notify = new Notify({
  apiKey: 'your_api_key'
});

await notify.send({
  to: 'user@example.com',
  channel: 'email',
  template: 'welcome',
  data: { name: 'Alice' }
});

Usage

Send a Single Notification

const result = await notify.send({
  to: 'user@example.com',
  channel: 'email',
  template: 'order-confirmation',
  data: { orderId: 'ORD-123' },
  priority: 'high'
});

console.log(result.id);     // notification ID
console.log(result.status); // 'queued' | 'sent' | 'pending' | 'failed'

Send SMS

await notify.send({
  to: '+1234567890',
  channel: 'sms',
  template: 'verification-code',
  data: { code: '123456' }
});

Send WhatsApp Message

await notify.send({
  to: '+1234567890',
  channel: 'whatsapp',
  template: 'order-shipped',
  data: { trackingNumber: 'TRK-456' }
});

Send Push Notification

await notify.send({
  to: 'device_token',
  channel: 'push',
  data: { title: 'New message', body: 'You have a new message' }
});

Send In-App Notification

await notify.send({
  to: 'user_id_123',
  channel: 'in_app',
  template: 'new-feature',
  data: { feature: 'Dark Mode' }
});

Bulk Notifications

Send up to 1000 notifications in a single request:

const result = await notify.bulk({
  notifications: [
    { to: 'user1@example.com', channel: 'email', data: { name: 'User 1' } },
    { to: 'user2@example.com', channel: 'email', data: { name: 'User 2' } },
    { to: '+1234567890', channel: 'sms', data: { code: '123456' } }
  ]
});

console.log(result.accepted); // number of accepted notifications
console.log(result.rejected); // number of rejected notifications
console.log(result.errors);   // array of errors (if any)

Get Notification Status

const notification = await notify.get('notification_id');

console.log(notification.id);
console.log(notification.status);
console.log(notification.channel);

List Notifications

const list = await notify.list({
  channel: 'email',
  status: 'sent',
  page: 1,
  limit: 20
});

console.log(list.items);      // array of notifications
console.log(list.total);      // total count
console.log(list.totalPages); // total pages

Configuration

const notify = new Notify({
  apiKey: 'your_api_key',     // required
  baseUrl: 'https://...',     // optional, defaults to production API
  timeout: 30000,             // optional, request timeout in ms (default: 30000)
  retries: 3                  // optional, number of retries (default: 3)
});

Channels

Channel	to field	Description
email	Email address	Send email notifications
sms	Phone number (E.164)	Send SMS messages
whatsapp	Phone number (E.164)	Send WhatsApp messages
push	Device token	Send push notifications
in_app	User ID	Send in-app notifications

Priority Levels

Priority	Description
low	Background notifications
normal	Standard delivery (default)
high	Priority delivery
urgent	Immediate delivery

Error Handling

import {
  Notify,
  NotifyError,
  NotifyAuthenticationError,
  NotifyValidationError,
  NotifyRateLimitError,
  NotifyNetworkError
} from '@afrisinc/notify-sdk';

try {
  await notify.send({ ... });
} catch (error) {
  if (error instanceof NotifyAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotifyValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof NotifyRateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof NotifyNetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof NotifyError) {
    console.error('Error:', error.code, error.message);
  }
}

TypeScript

Full TypeScript support with exported types:

import type {
  NotifyConfig,
  Channel,
  Priority,
  NotificationStatus,
  SendParams,
  SendResponse,
  BulkParams,
  BulkResponse,
  Notification,
  ListParams,
  ListResponse
} from '@afrisinc/notify-sdk';

License

MIT