@skoolite/notify-hub 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1080 @@
+import { CountryCode } from 'libphonenumber-js';
+
+/**
+ * Notification channels supported by NotifyHub
+ */
+type Channel = 'sms' | 'whatsapp' | 'email';
+/**
+ * Message delivery status
+ */
+type MessageStatus = 'queued' | 'sent' | 'delivered' | 'read' | 'failed' | 'undelivered' | 'unknown';
+/**
+ * Result of sending a notification
+ */
+interface SendResult {
+    /** Whether the send operation succeeded */
+    success: boolean;
+    /** Provider-specific message ID */
+    messageId?: string;
+    /** Channel used for sending */
+    channel: Channel;
+    /** Current message status */
+    status: MessageStatus;
+    /** Provider that was used */
+    provider: string;
+    /** Error details if failed */
+    error?: NotifyError;
+    /** Cost information if available */
+    cost?: Cost;
+    /** Timestamp of the send operation */
+    timestamp: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Error information
+ */
+interface NotifyError {
+    /** Error code from provider or internal */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether this error is retriable */
+    retriable: boolean;
+    /** Original error from provider */
+    originalError?: unknown;
+}
+/**
+ * Cost information for a message
+ */
+interface Cost {
+    /** Amount in the smallest currency unit */
+    amount: number;
+    /** Currency code (e.g., 'USD', 'PKR') */
+    currency: string;
+}
+/**
+ * Result of bulk sending operation
+ */
+interface BulkResult {
+    /** Individual results for each message */
+    results: SendResult[];
+    /** Summary statistics */
+    summary: BulkSummary;
+}
+/**
+ * Summary of bulk operation
+ */
+interface BulkSummary {
+    /** Total messages attempted */
+    total: number;
+    /** Successfully sent count */
+    sent: number;
+    /** Failed count */
+    failed: number;
+    /** Total cost if available */
+    cost?: Cost;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Options for bulk sending
+ */
+interface BulkOptions {
+    /** Rate limiting configuration */
+    rateLimit?: RateLimitConfig;
+    /** Progress callback */
+    onProgress?: (sent: number, total: number) => void;
+    /** Whether to stop on first error */
+    stopOnError?: boolean;
+    /** Maximum concurrent sends */
+    concurrency?: number;
+}
+/**
+ * Rate limiting configuration
+ */
+interface RateLimitConfig {
+    /** Maximum messages per second */
+    messagesPerSecond: number;
+}
+/**
+ * Base provider interface
+ */
+interface BaseProvider {
+    /** Provider name */
+    readonly name: string;
+    /** Initialize the provider */
+    initialize?(): Promise<void>;
+    /** Cleanup resources */
+    destroy?(): Promise<void>;
+}
+/**
+ * SMS provider interface
+ */
+interface SmsProvider extends BaseProvider {
+    /**
+     * Send an SMS message
+     * @param to Phone number in E.164 format
+     * @param message Message content
+     * @param options Additional options
+     */
+    send(to: string, message: string, options?: SmsOptions): Promise<SendResult>;
+    /**
+     * Get delivery status of a message
+     * @param messageId Provider-specific message ID
+     */
+    getStatus?(messageId: string): Promise<MessageStatus>;
+    /**
+     * Send bulk SMS messages
+     * @param messages Array of messages to send
+     * @param options Bulk options
+     */
+    sendBulk?(messages: SmsMessage[], options?: BulkOptions): Promise<BulkResult>;
+}
+/**
+ * SMS message for bulk sending
+ */
+interface SmsMessage {
+    /** Phone number in E.164 format */
+    to: string;
+    /** Message content */
+    message: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * SMS sending options
+ */
+interface SmsOptions {
+    /** Sender ID or phone number */
+    from?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * WhatsApp provider interface
+ */
+interface WhatsAppProvider extends BaseProvider {
+    /**
+     * Send a text message (within 24hr window)
+     * @param to Phone number in E.164 format
+     * @param message Message content
+     */
+    sendText(to: string, message: string, options?: WhatsAppOptions): Promise<SendResult>;
+    /**
+     * Send a template message
+     * @param to Phone number in E.164 format
+     * @param template Template configuration
+     */
+    sendTemplate(to: string, template: WhatsAppTemplate, options?: WhatsAppOptions): Promise<SendResult>;
+    /**
+     * Get delivery status of a message
+     * @param messageId Provider-specific message ID
+     */
+    getStatus?(messageId: string): Promise<MessageStatus>;
+}
+/**
+ * WhatsApp template configuration
+ */
+interface WhatsAppTemplate {
+    /** Template name as registered with Meta */
+    name: string;
+    /** Template language code (e.g., 'en', 'en_US') */
+    language: string;
+    /** Template variables (positional or named) */
+    variables?: Record<string, string> | string[];
+    /** Header parameters */
+    header?: WhatsAppTemplateHeader;
+    /** Button parameters */
+    buttons?: WhatsAppTemplateButton[];
+}
+/**
+ * WhatsApp template header
+ */
+interface WhatsAppTemplateHeader {
+    type: 'text' | 'image' | 'document' | 'video';
+    /** URL for media types */
+    url?: string;
+    /** Text for text type */
+    text?: string;
+}
+/**
+ * WhatsApp template button
+ */
+interface WhatsAppTemplateButton {
+    type: 'url' | 'quick_reply';
+    index: number;
+    payload?: string;
+}
+/**
+ * WhatsApp sending options
+ */
+interface WhatsAppOptions {
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * WhatsApp message for bulk sending
+ */
+interface WhatsAppMessage {
+    /** Phone number in E.164 format */
+    to: string;
+    /** Text message (for text type) */
+    message?: string;
+    /** Template configuration (for template type) */
+    template?: WhatsAppTemplate;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Email provider interface
+ */
+interface EmailProvider extends BaseProvider {
+    /**
+     * Send an email
+     * @param to Recipient email address
+     * @param email Email content
+     */
+    send(to: string, email: EmailMessage, options?: EmailOptions): Promise<SendResult>;
+    /**
+     * Send to multiple recipients
+     * @param messages Array of email messages
+     * @param options Bulk options
+     */
+    sendBulk?(messages: EmailMessageWithRecipient[], options?: BulkOptions): Promise<BulkResult>;
+}
+/**
+ * Email message content
+ */
+interface EmailMessage {
+    /** Email subject */
+    subject: string;
+    /** Plain text body */
+    body?: string;
+    /** HTML body */
+    html?: string;
+    /** Attachments */
+    attachments?: EmailAttachment[];
+}
+/**
+ * Email message with recipient for bulk sending
+ */
+interface EmailMessageWithRecipient extends EmailMessage {
+    /** Recipient email address */
+    to: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Email attachment
+ */
+interface EmailAttachment {
+    /** Attachment filename */
+    filename: string;
+    /** Content as Buffer or base64 string */
+    content: Buffer | string;
+    /** MIME type */
+    contentType: string;
+}
+/**
+ * Email sending options
+ */
+interface EmailOptions {
+    /** From address override */
+    from?: string;
+    /** From name override */
+    fromName?: string;
+    /** Reply-to address */
+    replyTo?: string;
+    /** CC recipients */
+    cc?: string[];
+    /** BCC recipients */
+    bcc?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Twilio SMS provider configuration
+ */
+interface TwilioConfig {
+    /** Twilio Account SID */
+    accountSid: string;
+    /** Twilio Auth Token */
+    authToken: string;
+    /** Default from phone number */
+    fromNumber: string;
+    /** Messaging Service SID (optional, for advanced features) */
+    messagingServiceSid?: string;
+}
+/**
+ * Local Pakistan SMS provider configuration
+ */
+interface LocalSmsConfig {
+    /** Provider name: telenor, jazz, zong */
+    provider: 'telenor' | 'jazz' | 'zong';
+    /** API key or username */
+    apiKey: string;
+    /** API secret or password */
+    apiSecret?: string;
+    /** Sender ID */
+    senderId: string;
+    /** Base URL override */
+    baseUrl?: string;
+}
+/**
+ * Meta WhatsApp Cloud API configuration
+ */
+interface MetaWhatsAppConfig {
+    /** Access token from Meta */
+    accessToken: string;
+    /** Phone Number ID */
+    phoneNumberId: string;
+    /** Business Account ID */
+    businessAccountId?: string;
+    /** API version (default: v18.0) */
+    apiVersion?: string;
+    /** Webhook verify token */
+    webhookVerifyToken?: string;
+}
+/**
+ * AWS SES email provider configuration
+ */
+interface SesConfig {
+    /** AWS region */
+    region: string;
+    /** Default from address */
+    fromAddress: string;
+    /** Default from name */
+    fromName?: string;
+    /** AWS credentials (optional, will use default credential chain) */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+/**
+ * Provider-specific configuration union
+ */
+type SmsProviderConfig = {
+    provider: 'twilio';
+    config: TwilioConfig;
+} | {
+    provider: 'local';
+    config: LocalSmsConfig;
+} | {
+    provider: 'custom';
+    instance: SmsProvider;
+};
+type WhatsAppProviderConfig = {
+    provider: 'meta';
+    config: MetaWhatsAppConfig;
+} | {
+    provider: 'custom';
+    instance: WhatsAppProvider;
+};
+type EmailProviderConfig = {
+    provider: 'ses';
+    config: SesConfig;
+} | {
+    provider: 'custom';
+    instance: EmailProvider;
+};
+/**
+ * Routing configuration for smart provider selection
+ */
+interface RoutingConfig {
+    /** Phone prefix to provider mapping (e.g., '+92': 'primary') */
+    [prefix: string]: 'primary' | 'fallback';
+}
+/**
+ * SMS channel configuration
+ */
+interface SmsChannelConfig {
+    /** Primary provider */
+    primary: SmsProviderConfig;
+    /** Fallback provider (optional) */
+    fallback?: SmsProviderConfig;
+    /** Routing rules */
+    routing?: RoutingConfig;
+}
+/**
+ * Retry configuration
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Initial backoff in milliseconds */
+    backoffMs: number;
+    /** Backoff multiplier for exponential backoff */
+    backoffMultiplier: number;
+    /** Maximum backoff in milliseconds */
+    maxBackoffMs?: number;
+    /** Add jitter to backoff */
+    jitter?: boolean;
+}
+/**
+ * Logger interface (compatible with console, winston, pino)
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Main NotifyHub configuration
+ */
+interface NotifyHubConfig {
+    /** Default channel for notifications */
+    defaultChannel?: Channel;
+    /** SMS configuration */
+    sms?: SmsChannelConfig;
+    /** WhatsApp configuration */
+    whatsapp?: WhatsAppProviderConfig;
+    /** Email configuration */
+    email?: EmailProviderConfig;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Generic webhook event
+ */
+interface WebhookEvent {
+    /** Event type */
+    type: 'status' | 'message';
+    /** Provider-specific message ID */
+    messageId: string;
+    /** Channel */
+    channel: Channel;
+    /** Timestamp */
+    timestamp: Date;
+    /** Provider name */
+    provider: string;
+}
+/**
+ * Delivery status webhook event
+ */
+interface StatusWebhookEvent extends WebhookEvent {
+    type: 'status';
+    /** New status */
+    status: MessageStatus;
+    /** Recipient phone/email */
+    to: string;
+    /** Error info if failed */
+    error?: NotifyError;
+}
+/**
+ * Incoming message webhook event
+ */
+interface IncomingMessageEvent extends WebhookEvent {
+    type: 'message';
+    /** Sender phone/email */
+    from: string;
+    /** Message content */
+    message?: string;
+    /** Media URL if present */
+    mediaUrl?: string;
+    /** Media type */
+    mediaType?: string;
+}
+/**
+ * Webhook handler interface
+ */
+interface WebhookHandler<T = unknown> {
+    /**
+     * Verify webhook signature
+     * @param body Raw request body
+     * @param headers Request headers
+     */
+    verify(body: unknown, headers: Record<string, string>): boolean;
+    /**
+     * Parse webhook payload
+     * @param body Request body
+     */
+    parse(body: T): WebhookEvent[];
+    /**
+     * Handle verification challenge (for WhatsApp)
+     * @param verifyToken Token from query params
+     * @param challenge Challenge string
+     */
+    verifyChallenge?(verifyToken: string, challenge: string): string | null;
+}
+/**
+ * Generic notification for the send() method
+ */
+interface Notification {
+    /** Channel to use */
+    channel: Channel;
+    /** Recipient (phone or email) */
+    to: string;
+    /** Message content (for SMS and WhatsApp text) */
+    message?: string;
+    /** Template (for WhatsApp template messages) */
+    template?: WhatsAppTemplate;
+    /** Email content */
+    email?: EmailMessage;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * NotifyHub - Multi-channel notification hub
+ *
+ * @example
+ * ```typescript
+ * const notifyHub = new NotifyHub({
+ *   sms: {
+ *     primary: {
+ *       provider: 'twilio',
+ *       config: {
+ *         accountSid: 'xxx',
+ *         authToken: 'xxx',
+ *         fromNumber: '+1234567890',
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * await notifyHub.sms('+923001234567', 'Hello!');
+ * ```
+ */
+declare class NotifyHub {
+    private readonly config;
+    private readonly logger;
+    private readonly retryConfig;
+    private primarySmsProvider?;
+    private fallbackSmsProvider?;
+    private whatsappProvider?;
+    private emailProvider?;
+    private initialized;
+    constructor(config: NotifyHubConfig);
+    /**
+     * Initialize all configured providers
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create an SMS provider from configuration
+     */
+    private createSmsProvider;
+    /**
+     * Create a WhatsApp provider from configuration
+     */
+    private createWhatsAppProvider;
+    /**
+     * Create an Email provider from configuration
+     */
+    private createEmailProvider;
+    /**
+     * Ensure NotifyHub is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Get the appropriate SMS provider based on phone number
+     */
+    private getSmsProvider;
+    /**
+     * Send an SMS message
+     * @param to Phone number in any format (will be converted to E.164)
+     * @param message Message content
+     * @param options Additional options
+     */
+    sms(to: string, message: string, options?: SmsOptions): Promise<SendResult>;
+    /**
+     * Send bulk SMS messages
+     */
+    bulkSms(messages: SmsMessage[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Get SMS delivery status
+     */
+    getSmsStatus(messageId: string): Promise<MessageStatus>;
+    /**
+     * Send a WhatsApp text message (within 24hr window)
+     */
+    whatsapp(to: string, message: string, options?: WhatsAppOptions): Promise<SendResult>;
+    /**
+     * Send a WhatsApp template message
+     */
+    whatsappTemplate(to: string, template: WhatsAppTemplate, options?: WhatsAppOptions): Promise<SendResult>;
+    /**
+     * Send bulk WhatsApp messages
+     */
+    bulkWhatsApp(messages: WhatsAppMessage[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Send an email
+     */
+    email(to: string, email: EmailMessage, options?: EmailOptions): Promise<SendResult>;
+    /**
+     * Send bulk emails
+     */
+    bulkEmail(messages: EmailMessageWithRecipient[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Send a notification using the specified channel
+     */
+    send(notification: Notification): Promise<SendResult>;
+    /**
+     * Cleanup and destroy all providers
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Twilio SMS provider implementation
+ */
+declare class TwilioSmsProvider implements SmsProvider {
+    readonly name = "twilio";
+    private client;
+    private readonly config;
+    private readonly logger?;
+    private readonly retryConfig;
+    constructor(config: TwilioConfig, options?: {
+        logger?: Logger;
+        retryConfig?: RetryConfig;
+    });
+    /**
+     * Initialize the Twilio client
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure client is initialized
+     */
+    private ensureClient;
+    /**
+     * Send an SMS message
+     */
+    send(to: string, message: string, options?: SmsOptions): Promise<SendResult>;
+    /**
+     * Get delivery status of a message
+     */
+    getStatus(messageId: string): Promise<MessageStatus>;
+    /**
+     * Send bulk SMS messages
+     */
+    sendBulk(messages: SmsMessage[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Abstract base class for Pakistan local SMS providers
+ * Each provider (Telenor, Jazz, Zong) extends this class
+ */
+declare abstract class BaseLocalSmsProvider implements SmsProvider {
+    abstract readonly name: string;
+    protected readonly config: LocalSmsConfig;
+    protected readonly logger?: Logger;
+    protected readonly retryConfig: RetryConfig;
+    protected abstract readonly baseUrl: string;
+    constructor(config: LocalSmsConfig, options?: {
+        logger?: Logger;
+        retryConfig?: RetryConfig;
+    });
+    /**
+     * Initialize the provider
+     */
+    initialize(): Promise<void>;
+    /**
+     * Format phone number for local provider
+     * Pakistan providers typically want: 923001234567 (no + prefix)
+     */
+    protected formatPhoneNumber(phone: string): string | null;
+    /**
+     * Make API request to the provider
+     * Each provider implements this differently
+     */
+    protected abstract makeRequest(to: string, message: string): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+    /**
+     * Send an SMS message
+     */
+    send(to: string, message: string, options?: SmsOptions): Promise<SendResult>;
+    /**
+     * Get delivery status (most local providers don't support this)
+     */
+    getStatus(_messageId: string): Promise<MessageStatus>;
+    /**
+     * Send bulk SMS messages
+     */
+    sendBulk(messages: SmsMessage[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Telenor Pakistan SMS provider
+ *
+ * API Documentation: Contact Telenor Pakistan for API access
+ *
+ * Note: This is a simplified implementation. Actual Telenor API
+ * may have different endpoints and authentication methods.
+ */
+declare class TelenorSmsProvider extends BaseLocalSmsProvider {
+    readonly name = "telenor";
+    protected readonly baseUrl: string;
+    constructor(config: LocalSmsConfig, options?: {
+        logger?: Logger;
+        retryConfig?: RetryConfig;
+    });
+    /**
+     * Make API request to Telenor
+     */
+    protected makeRequest(to: string, message: string): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+}
+
+/**
+ * Jazz (Mobilink) Pakistan SMS provider
+ *
+ * API Documentation: Contact Jazz Pakistan for API access
+ *
+ * Note: This is a simplified implementation. Actual Jazz API
+ * may have different endpoints and authentication methods.
+ */
+declare class JazzSmsProvider extends BaseLocalSmsProvider {
+    readonly name = "jazz";
+    protected readonly baseUrl: string;
+    constructor(config: LocalSmsConfig, options?: {
+        logger?: Logger;
+        retryConfig?: RetryConfig;
+    });
+    /**
+     * Make API request to Jazz
+     */
+    protected makeRequest(to: string, message: string): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+}
+
+/**
+ * Zong Pakistan SMS provider
+ *
+ * API Documentation: Contact Zong Pakistan for API access
+ *
+ * Note: This is a simplified implementation. Actual Zong API
+ * may have different endpoints and authentication methods.
+ */
+declare class ZongSmsProvider extends BaseLocalSmsProvider {
+    readonly name = "zong";
+    protected readonly baseUrl: string;
+    constructor(config: LocalSmsConfig, options?: {
+        logger?: Logger;
+        retryConfig?: RetryConfig;
+    });
+    /**
+     * Make API request to Zong
+     */
+    protected makeRequest(to: string, message: string): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+}
+
+/**
+ * Meta WhatsApp Cloud API provider implementation
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api
+ */
+declare class MetaWhatsAppProvider implements WhatsAppProvider {
+    readonly name = "meta";
+    private readonly config;
+    private readonly logger?;
+    private readonly retryConfig;
+    private readonly apiVersion;
+    private readonly baseUrl;
+    constructor(config: MetaWhatsAppConfig, options?: {
+        logger?: Logger;
+        retryConfig?: RetryConfig;
+    });
+    /**
+     * Initialize the provider (no-op for Meta, just validates config)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Make an API request to Meta WhatsApp Cloud API
+     */
+    private makeRequest;
+    /**
+     * Send a text message (within 24hr conversation window)
+     */
+    sendText(to: string, message: string, options?: WhatsAppOptions): Promise<SendResult>;
+    /**
+     * Send a template message (works outside 24hr window)
+     */
+    sendTemplate(to: string, template: WhatsAppTemplate, options?: WhatsAppOptions): Promise<SendResult>;
+    /**
+     * Get delivery status of a message
+     * Note: Meta doesn't have a direct status lookup API - statuses come via webhooks
+     */
+    getStatus(_messageId: string): Promise<MessageStatus>;
+    /**
+     * Cleanup resources (no-op for Meta)
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Twilio webhook payload for message status updates
+ */
+interface TwilioStatusPayload {
+    MessageSid: string;
+    MessageStatus: string;
+    To: string;
+    From?: string;
+    ErrorCode?: string;
+    ErrorMessage?: string;
+    AccountSid?: string;
+    ApiVersion?: string;
+}
+/**
+ * Twilio webhook payload for incoming messages
+ */
+interface TwilioIncomingPayload {
+    MessageSid: string;
+    Body: string;
+    From: string;
+    To: string;
+    NumMedia?: string;
+    MediaUrl0?: string;
+    MediaContentType0?: string;
+    AccountSid?: string;
+}
+/**
+ * Twilio webhook handler
+ */
+declare class TwilioWebhookHandler implements WebhookHandler<TwilioStatusPayload | TwilioIncomingPayload> {
+    private readonly authToken;
+    constructor(authToken: string);
+    /**
+     * Verify Twilio webhook signature
+     * @see https://www.twilio.com/docs/usage/webhooks/webhooks-security
+     */
+    verify(body: unknown, headers: Record<string, string>): boolean;
+    /**
+     * Parse Twilio webhook payload
+     */
+    parse(body: TwilioStatusPayload | TwilioIncomingPayload): WebhookEvent[];
+}
+/**
+ * Create a Twilio webhook handler
+ */
+declare function createTwilioWebhookHandler(authToken: string): TwilioWebhookHandler;
+
+/**
+ * Meta WhatsApp webhook payload structure
+ * @see https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components
+ */
+interface MetaWebhookPayload {
+    object: 'whatsapp_business_account';
+    entry: Array<{
+        id: string;
+        changes: Array<{
+            value: {
+                messaging_product: 'whatsapp';
+                metadata: {
+                    display_phone_number: string;
+                    phone_number_id: string;
+                };
+                contacts?: Array<{
+                    profile: {
+                        name: string;
+                    };
+                    wa_id: string;
+                }>;
+                messages?: Array<{
+                    from: string;
+                    id: string;
+                    timestamp: string;
+                    type: 'text' | 'image' | 'document' | 'audio' | 'video' | 'sticker' | 'location' | 'contacts' | 'button' | 'interactive';
+                    text?: {
+                        body: string;
+                    };
+                    image?: {
+                        id: string;
+                        mime_type: string;
+                        sha256: string;
+                    };
+                    document?: {
+                        id: string;
+                        mime_type: string;
+                        sha256: string;
+                        filename?: string;
+                    };
+                    audio?: {
+                        id: string;
+                        mime_type: string;
+                    };
+                    video?: {
+                        id: string;
+                        mime_type: string;
+                    };
+                    button?: {
+                        text: string;
+                        payload: string;
+                    };
+                    interactive?: {
+                        type: string;
+                        button_reply?: {
+                            id: string;
+                            title: string;
+                        };
+                        list_reply?: {
+                            id: string;
+                            title: string;
+                        };
+                    };
+                }>;
+                statuses?: Array<{
+                    id: string;
+                    status: 'sent' | 'delivered' | 'read' | 'failed';
+                    timestamp: string;
+                    recipient_id: string;
+                    errors?: Array<{
+                        code: number;
+                        title: string;
+                        message?: string;
+                        error_data?: {
+                            details: string;
+                        };
+                    }>;
+                }>;
+            };
+            field: 'messages';
+        }>;
+    }>;
+}
+/**
+ * Meta WhatsApp Cloud API webhook handler
+ */
+declare class WhatsAppWebhookHandler implements WebhookHandler<MetaWebhookPayload> {
+    private readonly appSecret;
+    private readonly verifyToken;
+    constructor(appSecret: string, verifyToken: string);
+    /**
+     * Verify WhatsApp webhook challenge (for initial setup)
+     */
+    verifyChallenge(verifyToken: string, challenge: string): string | null;
+    /**
+     * Verify Meta webhook signature
+     * @see https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests
+     */
+    verify(body: unknown, headers: Record<string, string>): boolean;
+    /**
+     * Parse Meta WhatsApp webhook payload
+     */
+    parse(body: MetaWebhookPayload): WebhookEvent[];
+}
+/**
+ * Create a WhatsApp webhook handler
+ */
+declare function createWhatsAppWebhookHandler(appSecret: string, verifyToken: string): WhatsAppWebhookHandler;
+
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Check if an error is retriable
+ */
+declare function isRetriableError(error: unknown): boolean;
+/**
+ * Calculate backoff delay with optional jitter
+ */
+declare function calculateBackoff(attempt: number, config: RetryConfig): number;
+/**
+ * Retry result containing the value or error
+ */
+interface RetryResult<T> {
+    success: boolean;
+    value?: T;
+    error?: Error;
+    attempts: number;
+    totalDurationMs: number;
+}
+/**
+ * Execute a function with retries
+ * @param fn Function to execute
+ * @param config Retry configuration
+ * @param shouldRetry Optional custom retry predicate
+ */
+declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, shouldRetry?: (error: unknown) => boolean): Promise<RetryResult<T>>;
+/**
+ * Create a NotifyError from an unknown error
+ */
+declare function createNotifyError(error: unknown, defaultCode?: string): NotifyError;
+
+/**
+ * Phone number validation result
+ */
+interface PhoneValidationResult {
+    isValid: boolean;
+    e164?: string;
+    countryCode?: string;
+    nationalNumber?: string;
+    error?: string;
+}
+/**
+ * Validate and parse a phone number to E.164 format
+ * @param phone Phone number in any format
+ * @param defaultCountry Default country code for numbers without country prefix
+ */
+declare function validatePhoneNumber(phone: string, defaultCountry?: CountryCode): PhoneValidationResult;
+/**
+ * Clean a phone number by removing common formatting characters
+ */
+declare function cleanPhoneNumber(phone: string): string;
+/**
+ * Format phone number to E.164 format
+ * @param phone Phone number in any format
+ * @param defaultCountry Default country code
+ * @returns E.164 formatted number or null if invalid
+ */
+declare function toE164(phone: string, defaultCountry?: CountryCode): string | null;
+/**
+ * Check if a phone number belongs to a specific country
+ * @param phone Phone number in E.164 format
+ * @param countryCode Two-letter country code
+ */
+declare function isCountry(phone: string, countryCode: CountryCode): boolean;
+/**
+ * Get the country code from a phone number
+ * @param phone Phone number in E.164 format
+ */
+declare function getCountryCode(phone: string): string | null;
+/**
+ * Get the calling code (e.g., +92 for Pakistan)
+ * @param phone Phone number in E.164 format
+ */
+declare function getCallingCode(phone: string): string | null;
+/**
+ * Check if a phone number is a Pakistan mobile number
+ * Pakistan mobile numbers start with 03xx
+ */
+declare function isPakistanMobile(phone: string): boolean;
+/**
+ * Get the Pakistan mobile network from a phone number
+ * @param phone Phone number
+ * @returns Network name or null if not a Pakistan mobile
+ */
+declare function getPakistanNetwork(phone: string): 'jazz' | 'telenor' | 'zong' | 'ufone' | null;
+/**
+ * Determine the best provider for a phone number based on prefix
+ * @param phone Phone number in E.164 format
+ * @param routing Routing configuration
+ * @returns 'primary' or 'fallback'
+ */
+declare function routeByPrefix(phone: string, routing: Record<string, 'primary' | 'fallback'>): 'primary' | 'fallback';
+
+export { BaseLocalSmsProvider, type BaseProvider, type BulkOptions, type BulkResult, type BulkSummary, type Channel, type Cost, DEFAULT_RETRY_CONFIG, type EmailAttachment, type EmailMessage, type EmailMessageWithRecipient, type EmailOptions, type EmailProvider, type EmailProviderConfig, type IncomingMessageEvent, JazzSmsProvider, type LocalSmsConfig, type Logger, type MessageStatus, type MetaWhatsAppConfig, MetaWhatsAppProvider, type Notification, type NotifyError, NotifyHub, type NotifyHubConfig, type RateLimitConfig, type RetryConfig, type RoutingConfig, type SendResult, type SesConfig, type SmsChannelConfig, type SmsMessage, type SmsOptions, type SmsProvider, type SmsProviderConfig, type StatusWebhookEvent, TelenorSmsProvider, type TwilioConfig, TwilioSmsProvider, TwilioWebhookHandler, type WebhookEvent, type WebhookHandler, type WhatsAppMessage, type WhatsAppOptions, type WhatsAppProvider, type WhatsAppProviderConfig, type WhatsAppTemplate, type WhatsAppTemplateButton, type WhatsAppTemplateHeader, WhatsAppWebhookHandler, ZongSmsProvider, calculateBackoff, cleanPhoneNumber, createNotifyError, createTwilioWebhookHandler, createWhatsAppWebhookHandler, getCallingCode, getCountryCode, getPakistanNetwork, isCountry, isPakistanMobile, isRetriableError, routeByPrefix, toE164, validatePhoneNumber, withRetry };