@dawntech/dispatcher 0.2.6 → 0.2.8

package/dist/index.d.mts

@@ -1,11 +1,583 @@
-export { CallbackMap, DispatcherDescriptor, DispatcherDescriptorOptions } from './core/DispatcherDescriptor.mjs';
-export { Dispatcher } from './core/Dispatcher.mjs';
-export { Blip, BlipError } from './core/Blip.mjs';
-export { DispatcherMonitor, MonitorAlert, MonitorOptions, MonitorRule } from './core/DispatcherMonitor.mjs';
-export { DispatcherRepository } from './core/DispatcherRepository.mjs';
-export { enableLogger, getLogger } from './utils/logger.mjs';
-export { CallbackEvent, ConnectionConfig, Contact, DispatchMessageOptions, DispatchState, DispatcherManifest, DispatcherMetrics, DispatcherOptions, Intent, Message, MessageData, MessageDispatcherOptions, MessageOptions, MessagePayload, MessageState, MessageStatus, QueryFilter, Shift, Weekdays } from './types/index.mjs';
-export { BlipConfig, DateInterval, PartiallyOptional, PartiallyRequiredStrict, Vnd } from './types/blip.mjs';
-import './core/DispatcherQuery.mjs';
-import 'events';
-import 'ioredis';
+import IORedis from 'ioredis';
+import { EventEmitter } from 'events';
+
+/**
+ * Type definitions for Blip Platform API
+ * Based on the LIME protocol and Blip extensions
+ */
+declare namespace Vnd {
+    namespace Lime {
+        enum Method {
+            GET = "get",
+            SET = "set",
+            DELETE = "delete",
+            OBSERVE = "observe",
+            SUBSCRIBE = "subscribe",
+            MERGE = "merge"
+        }
+        enum Status {
+            SUCCESS = "success",
+            FAILURE = "failure"
+        }
+        namespace Transport {
+            namespace Payload {
+                interface Request<T = unknown> {
+                    id?: string;
+                    to?: string;
+                    method: Method;
+                    uri: string;
+                    type?: string;
+                    resource?: T;
+                }
+                interface Response<T = unknown> {
+                    id?: string;
+                    from?: string;
+                    to?: string;
+                    method?: Method;
+                    status: Status;
+                    type?: string;
+                    resource?: T;
+                    reason?: {
+                        code: number;
+                        description: string;
+                    };
+                }
+            }
+        }
+        interface Message<T = unknown> {
+            id?: string;
+            to: string;
+            from?: string;
+            type: string;
+            content: T;
+        }
+        namespace Command {
+            interface Resource<T = unknown> {
+                [key: string]: T;
+            }
+        }
+    }
+    namespace Iris {
+        interface ThreadMessage {
+            id: string;
+            direction: 'sent' | 'received';
+            type: string;
+            content: unknown;
+            date: string;
+            status?: string;
+            [key: string]: unknown;
+        }
+        interface Contact {
+            identity: string;
+            name?: string;
+            email?: string;
+            phoneNumber?: string;
+            taxDocument?: string;
+            gender?: string;
+            city?: string;
+            extras?: Record<string, string>;
+            [key: string]: unknown;
+        }
+        interface EventTrack {
+            category: string;
+            action: string;
+            contact?: {
+                identity: string;
+            };
+            extras?: unknown;
+            count?: number;
+        }
+        interface Ticket {
+            id: string;
+            sequentialId: number;
+            ownerIdentity: string;
+            customerIdentity: string;
+            providerIdentity: string;
+            status: string;
+            storageDate: string;
+            externalId?: string;
+            rating?: number;
+            team?: string;
+            agentIdentity?: string;
+            closedDate?: string;
+            transfers?: number;
+            [key: string]: unknown;
+        }
+        namespace ActiveCampaign {
+            interface AudienceSummary {
+                total: number;
+                sent: number;
+                failed: number;
+                scheduled: number;
+                canceled: number;
+            }
+        }
+    }
+}
+interface BlipConfig {
+    botUrl: string;
+    botKey: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+interface DateInterval {
+    from?: Date;
+    to: Date;
+}
+type PartiallyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type PartiallyRequiredStrict<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
+type Contact = Omit<Vnd.Iris.Contact, 'identity'>;
+type MessageData = {
+    type: string;
+    content: Record<string, unknown> | string;
+};
+type MessagePayload = Record<string, unknown> | Array<unknown> | string;
+declare enum MessageState {
+    INIT = "INIT",
+    DISPATCHED = "DISPATCHED",
+    SCHEDULED = "SCHEDULED",
+    QUEUED = "QUEUED",
+    FINAL = "FINAL"
+}
+declare enum MessageStatus {
+    INIT = "INIT",
+    PENDING = "PENDING",
+    SENDING = "SENDING",
+    DELIVERED = "DELIVERED",
+    READ = "READ",
+    REPLIED = "REPLIED",
+    FAILED = "FAILED",
+    CANCELED = "CANCELED"
+}
+declare enum DispatchState {
+    ACCEPTED = "accepted",
+    DISPATCHED = "dispatched",
+    RECEIVED = "received",
+    CONSUMED = "consumed",
+    FAILED = "failed"
+}
+interface Message {
+    messageId: string;
+    contactId: string;
+    descriptorId: string;
+    payload: MessageData;
+    status: MessageStatus;
+    state: MessageState;
+    attempts?: number;
+    retries?: number;
+    options?: MessageOptions;
+    expiresAt?: string;
+    scheduledTo?: string;
+    sentAt?: string;
+    acceptedAt?: string;
+    lastDispatchAttemptAt?: string;
+    createdAt: string;
+    deliveredAt?: string;
+    readAt?: string;
+    repliedAt?: string;
+    failedAt?: string;
+    error?: string;
+}
+interface Shift {
+    days: number;
+    start: string;
+    end: string;
+    gmt?: string;
+}
+declare enum Channel {
+    BLIP_CHAT = "BLIP_CHAT",
+    EMAIL = "EMAIL",
+    MESSENGER = "MESSENGER",
+    SKYPE = "SKYPE",
+    SMS_TAKE = "SMS_TAKE",
+    SMS_TANGRAM = "SMS_TANGRAM",
+    TELEGRAM = "TELEGRAM",
+    WHATSAPP = "WHATSAPP",
+    INSTAGRAM = "INSTAGRAM",
+    GOOGLE_RCS = "GOOGLE_RCS",
+    MICROSOFT_TEAMS = "MICROSOFT_TEAMS",
+    APPLE_BUSINESS_CHAT = "APPLE_BUSINESS_CHAT",
+    WORKPLACE = "WORKPLACE"
+}
+declare enum Weekdays {
+    MONDAY = 1,
+    TUESDAY = 2,
+    WEDNESDAY = 4,
+    THURSDAY = 8,
+    FRIDAY = 16,
+    SATURDAY = 32,
+    SUNDAY = 64
+}
+interface Intent {
+    intent: string;
+    dueDate?: string;
+    event?: string;
+    payload?: unknown;
+    expired?: {
+        event?: string;
+        intent?: string;
+    };
+}
+type CallbackEvent = 'dispatch' | 'sending' | 'delivered' | 'failed' | 'read' | 'replied' | 'scheduled' | 'retry' | 'evicted' | 'canceled';
+type ConnectionConfig = {
+    contract: string;
+    key: string;
+};
+interface MessageOptions {
+    shifts?: Array<Shift>;
+    contact?: Contact;
+    state?: {
+        stateId: string;
+        botId: string;
+        botIds?: Array<string>;
+    };
+    intent?: string | Intent;
+    finalStatus?: 'DELIVERED' | 'READ' | 'REPLIED';
+}
+interface DispatchMessageOptions extends MessageOptions {
+    schedule?: string;
+}
+interface DispatcherOptions {
+    maxRetries?: number;
+    retryIntervals?: number[];
+    retention?: number;
+    timeouts?: {
+        pending?: number;
+        sending?: number;
+    };
+    batchSize?: number;
+    pollingIntervals?: {
+        scheduled?: number;
+        pending?: number;
+        sending?: number;
+        delivered?: number;
+        read?: number;
+        queue?: number;
+    };
+    maxQueueSize?: number;
+    rateLimits?: {
+        global?: {
+            points: number;
+            duration: number;
+        };
+        message?: {
+            points: number;
+            duration: number;
+        };
+    };
+}
+interface QueryFilter {
+    contactId?: string;
+    descriptorId?: string;
+    status?: MessageStatus | MessageStatus[];
+    state?: MessageState | MessageState[];
+    size?: number;
+    skip?: number;
+}
+interface DispatcherMetrics {
+    total: number;
+    byState: {
+        [key in MessageState]?: number;
+    };
+    byStatus: {
+        [key in MessageStatus]?: number;
+    };
+    cumulative: {
+        dispatched: number;
+        delivered: number;
+        failed: number;
+    };
+}
+interface DispatcherManifest {
+    version: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * @deprecated Use DispatcherOptions instead
+ */
+type MessageDispatcherOptions = DispatcherOptions;
+
+/**
+ * Blip - Low-level client wrapper for Blip Platform API interactions
+ *
+ * Responsibilities:
+ * - Send messages to contacts via Blip HTTP API
+ * - Merge contact metadata (custom fields)
+ * - Send analytics events to Blip
+ * - Manage bot conversation state transitions
+ * - Check message delivery status
+ */
+
+declare class Blip {
+    private client;
+    /**
+     * Create a new Blip instance
+     * @param contract - Blip contract ID (without https:// prefix)
+     * @param key - Blip API key
+     * @param timeout - Request timeout in milliseconds (default: 30000)
+     */
+    constructor(contract: string, key: string, timeout?: number);
+    /**
+     * Send a command to the Blip API
+     */
+    private postCommand;
+    /**
+     * Send a message through the Blip API
+     */
+    private postMessage;
+    /**
+     * Merge contact metadata (custom fields)
+     * @param contactId - Contact identifier
+     * @param data - Key-value pairs to merge into contact
+     */
+    mergeContact(contactId: string, data: Omit<Vnd.Iris.Contact, 'identity'>): Promise<void>;
+    /**
+     * Send a message to a contact
+     * @param contactId - Contact identifier
+     * @param message - Message data to send
+     * @param id - Optional message ID (if not provided, a new one is generated)
+     * @returns message ID
+     */
+    sendMessage(contactId: string, message: MessageData, id?: string): Promise<string>;
+    /**
+     * Get raw dispatch state from Blip notifications
+     * @param messageId - Message ID to check
+     * @param contactId - Contact identifier to filter notifications
+     * @returns DispatchState or null if not found
+     */
+    getDispatchState(messageId: string, contactId: string): Promise<DispatchState | null>;
+    /**
+     * Get the first message received after a specific message ID
+     * @param contactId - Contact identifier
+     * @param messageId - Message ID to use as anchor
+     * @returns ThreadMessage or null if no message found
+     */
+    getMessageAfter(contactId: string, messageId: string): Promise<Vnd.Iris.ThreadMessage | null>;
+    /**
+     * Send an analytics event to Blip
+     * @param contactId - Contact identifier
+     * @param category - Event category
+     * @param action - Event action
+     * @param extras - Additional event data
+     */
+    sendEvent(contactId: string, category: string, action: string, extras: Record<string, string>): Promise<void>;
+    /**
+     * Set the bot conversation state for a contact
+     * @param contactId - Contact identifier
+     * @param botId - Bot identifier (short name)
+     * @param stateId - State identifier (default: "onboarding")
+     */
+    setState(contactId: string, botId: string, stateId?: string): Promise<void>;
+}
+/**
+ * Custom error class for Blip errors
+ */
+declare class BlipError extends Error {
+    code: number;
+    constructor(message: string, code: number);
+}
+
+type CallbackMap = Partial<Record<CallbackEvent, (message: Message, api: Blip, dispatcherId: string) => void>>;
+interface DispatcherDescriptorOptions extends MessageOptions {
+    toContactId?: (contactId: string) => string;
+}
+declare class DispatcherDescriptor {
+    readonly id: string;
+    private transformFn;
+    private callbacks;
+    private options?;
+    private contactIdTransform;
+    constructor(id: string, transform: (payload: MessagePayload) => MessageData, options?: DispatcherDescriptorOptions);
+    transform(payload: MessagePayload): MessageData;
+    toContactId(contactId: string): string;
+    get messageOptions(): MessageOptions | undefined;
+    on(event: CallbackEvent, callback: (message: Message, api: Blip, dispatcherId: string) => void): this;
+    emit(event: CallbackEvent, message: Message, api: Blip, dispatcherId: string): void;
+}
+
+declare class DispatcherRepository {
+    private static readonly INDEXED_STATUSES;
+    private static readonly INDEXED_STATES;
+    private client;
+    private keyPrefix;
+    constructor(dispatcherId: string, redisUrl: string);
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+    get redis(): IORedis;
+    getManifestKey(): string;
+    getKey(messageId: string): string;
+    getStateKey(state: MessageState): string;
+    getStatusKey(status: MessageStatus): string;
+    getContactKey(contactId: string): string;
+    getDescriptorKey(descriptorId: string): string;
+    getQueueKey(name: 'scheduled' | 'queued' | 'dispatched' | 'expiration' | 'retention'): string;
+    upsertMessage(message: Message, ttl?: number): Promise<void>;
+    getMessage(messageId: string): Promise<Message | null>;
+    getMessages(filter: {
+        status?: MessageStatus;
+        state?: MessageState;
+        size?: number;
+        skip?: number;
+    }): Promise<Message[]>;
+    getQueueSize(): Promise<number>;
+    evictOldest(count: number): Promise<number>;
+    getExpiredMessages(count?: number): Promise<string[]>;
+    getRetentionMessages(count?: number): Promise<string[]>;
+    incrementMetric(key: string, value?: number): Promise<number>;
+    getMetric(key: string): Promise<number>;
+    deleteMessage(messageId: string): Promise<void>;
+    private deleteMessageData;
+    countMessages(filter: {
+        status?: MessageStatus;
+        state?: MessageState;
+    }): Promise<number>;
+    getMetrics(descriptorId?: string): Promise<{
+        cumulative: {
+            dispatched: number;
+            delivered: number;
+            failed: number;
+        };
+        queues: {
+            queued: number;
+            scheduled: number;
+            dispatched: number;
+        };
+        status: Record<string, number>;
+    }>;
+    getDescriptors(): Promise<{
+        id: string;
+        count: number;
+    }[]>;
+    writeManifest(manifest: DispatcherManifest): Promise<void>;
+    getManifest(): Promise<DispatcherManifest | null>;
+}
+
+declare class DispatcherQuery {
+    private repository;
+    constructor(repository: DispatcherRepository);
+    private get client();
+    query(filter: QueryFilter): Promise<Message[]>;
+    private cleanupIndices;
+}
+
+declare class Dispatcher {
+    readonly id: string;
+    private repository;
+    private stateMachine;
+    private api;
+    private callbacks;
+    private descriptors;
+    private queue;
+    private worker;
+    private redis;
+    private queueName;
+    private maxRetries;
+    private retryIntervals;
+    private timeouts;
+    private retention;
+    private pollingIntervals;
+    private isRunning;
+    private setupCompleted;
+    private setupPromise;
+    private timeoutMonitorRunning;
+    private timeoutTimer;
+    readonly query: DispatcherQuery;
+    constructor(id: string, repository: DispatcherRepository, connection: ConnectionConfig, options?: DispatcherOptions);
+    setup(): Promise<void>;
+    private _doSetup;
+    teardown(): Promise<void>;
+    on(event: CallbackEvent, callback: (message: Message, api: Blip, dispatcherId: string) => void): this;
+    getMetrics(): Promise<DispatcherMetrics>;
+    private emit;
+    send(descriptor: DispatcherDescriptor, contactId: string, payload: MessagePayload, options?: DispatchMessageOptions): Promise<Message>;
+    cancel(messageId: string): Promise<boolean>;
+    private processJob;
+    private handleSendJob;
+    private handlePostSendOperations;
+    private handleCheckJob;
+    private checkAndHandleTimeout;
+    private handleTimeout;
+    private startTimeoutMonitor;
+    private _runTimeoutMonitorCycle;
+    private rescheduleCheck;
+    private handleDeliveredState;
+    private handleDispatchFailure;
+    private calculateScheduledTime;
+    private isWithinShifts;
+    private findNextShiftTime;
+    private getStatusRank;
+    static sanitizeContactId(id: string, source: Channel): string;
+}
+
+interface MonitorRule {
+    type: 'failure_rate' | 'queue_size';
+    threshold: number;
+    window?: number;
+    debounce?: number;
+}
+interface MonitorOptions {
+    interval?: number;
+    rules: MonitorRule[];
+    historySize?: number;
+}
+type MonitorAlert = {
+    type: string;
+    message: string;
+    level: 'warning' | 'critical';
+    details: Record<string, unknown>;
+    timestamp: string;
+};
+declare class DispatcherMonitor extends EventEmitter {
+    private id;
+    private repository;
+    private options;
+    private queue;
+    private worker;
+    private queueName;
+    private history;
+    private lastAlerts;
+    private activeAlerts;
+    private isRunning;
+    constructor(id: string, repository: DispatcherRepository, options: MonitorOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Independent metrics collection directly from Repository
+     */
+    private collectMetrics;
+    private check;
+    private cleanHistory;
+    private evaluateRule;
+    private isDebounced;
+    private emitAlert;
+    private resolveAlert;
+    private findSnapshotAt;
+}
+
+type LogFunction = (...args: unknown[]) => void;
+interface Logger {
+    debug: LogFunction;
+    info: LogFunction;
+    warn: LogFunction;
+    error: LogFunction;
+}
+/**
+ * Creates a logger with a specific scope.
+ *
+ * @param scope - The scope for the logger (e.g., 'blip-api', 'dispatcher').
+ * @returns A logger object with methods for each log level.
+ */
+declare function getLogger(scope: string): Logger;
+/**
+ * Enables logging for a specific scope and level.
+ * This is a convenience function to programmatically enable logging,
+ * equivalent to setting the DEBUG environment variable.
+ *
+ * @param scope - The scope to enable (e.g., 'blip-api').
+ * @param level - The minimum log level to enable (e.g., 'info').
+ */
+declare function enableLogger(namespaces: string): void;
+
+export { Blip, type BlipConfig, BlipError, type CallbackEvent, type CallbackMap, Channel, type ConnectionConfig, type Contact, type DateInterval, type DispatchMessageOptions, DispatchState, Dispatcher, DispatcherDescriptor, type DispatcherDescriptorOptions, type DispatcherManifest, type DispatcherMetrics, DispatcherMonitor, type DispatcherOptions, DispatcherRepository, type Intent, type Message, type MessageData, type MessageDispatcherOptions, type MessageOptions, type MessagePayload, MessageState, MessageStatus, type MonitorAlert, type MonitorOptions, type MonitorRule, type PartiallyOptional, type PartiallyRequiredStrict, type QueryFilter, type Shift, Vnd, Weekdays, enableLogger, getLogger };