OmniChannel SDK

A unified TypeScript/Node.js library for sending multi-channel notifications (WhatsApp, Email, SMS) through a single interface using the Provider Pattern.

Features

• Unified API: Single notify() method for all channels
• Provider Pattern: Easily extensible with custom providers
• Type-Safe: Full TypeScript support with comprehensive types
• Zero Dependencies: No production dependencies
• Validation: Built-in recipient and message validation
• Broadcast: Send to multiple channels simultaneously

Installation

npm install omnichannel-sdk

Quick Start

import {
  OmniChannel,
  EmailProvider,
  SMSProvider,
  WhatsAppProvider,
} from 'omnichannel-sdk';

// Create instance
const omni = new OmniChannel();

// Register providers
omni.registerProvider(new EmailProvider());
omni.registerProvider(new SMSProvider());
omni.registerProvider(new WhatsAppProvider());

// Send notifications
await omni.notify('email', 'user@example.com', {
  subject: 'Welcome!',
  body: 'Thanks for joining us.',
});

await omni.notify('sms', '+1234567890', {
  body: 'Your code is 123456',
});

await omni.notify('whatsapp', '+1234567890', {
  body: 'Hello from WhatsApp!',
});

API Reference

OmniChannel

Main class for sending notifications.

Constructor

const omni = new OmniChannel(config?: OmniChannelConfig);

Config Options:

• defaultChannel?: Channel - Default channel when not specified
• debug?: boolean - Enable debug logging
• providers?: Map<Channel, NotificationProvider> - Pre-registered providers

Methods

registerProvider(provider: NotificationProvider): void

Register a notification provider.

omni.registerProvider(new EmailProvider());

notify(channel: Channel, recipient: string, message: Message): Promise<SendResult>

Send a notification through a specific channel.

const result = await omni.notify('email', 'user@example.com', {
  subject: 'Hello',
  body: 'Message content',
});

broadcast(channels: Channel[], recipient: string, message: Message): Promise<SendResult[]>

Send a message to multiple channels simultaneously.

const results = await omni.broadcast(
  ['sms', 'whatsapp'],
  '+1234567890',
  { body: 'Multi-channel message' }
);

validateRecipient(channel: Channel, recipient: string): boolean

Validate a recipient for a specific channel.

const isValid = omni.validateRecipient('email', 'user@example.com');

hasProvider(channel: Channel): boolean

Check if a provider is registered for a channel.

listChannels(): Channel[]

List all registered channels.

Types

type Channel = 'whatsapp' | 'email' | 'sms';

interface Message {
  subject?: string;      // Only for email
  body: string;
  templateId?: string;
  metadata?: Record<string, unknown>;
}

interface SendResult {
  success: boolean;
  messageId?: string;
  channel: Channel;
  recipient: string;
  timestamp: Date;
  error?: string;
}

Error Handling

The SDK provides custom error classes:

• ValidationError: Invalid input data
• ProviderNotFoundError: Channel not registered
• SendError: Send operation failed

import { ValidationError, ProviderNotFoundError } from 'omnichannel-sdk';

try {
  await omni.notify('email', 'invalid-email', { body: 'Test' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Invalid input:', error.message);
  }
}

Creating Custom Providers

Extend BaseProvider to create custom providers:

import { BaseProvider, Message, SendResult, Channel } from 'omnichannel-sdk';

export class TwilioSMSProvider extends BaseProvider {
  readonly channel: Channel = 'sms';

  constructor(
    private accountSid: string,
    private authToken: string
  ) {
    super();
  }

  validate(recipient: string): boolean {
    // Custom validation logic
    return /^\+[1-9]\d{9,14}$/.test(recipient);
  }

  async send(recipient: string, message: Message): Promise<SendResult> {
    if (!this.validate(recipient)) {
      throw new ValidationError('Invalid phone number');
    }

    // Implement Twilio API call here
    // const response = await twilioClient.messages.create({...});

    return this.createSuccessResult(recipient);
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Run example
npm run example

License

MIT

Author: @Nicoo01x