@ariaflowagents/messaging 0.8.1

package/dist/adapter/window-tracker.js

@@ -0,0 +1,95 @@
+/** Default messaging window duration: 24 hours. */
+const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Stale entry cleanup interval: 1 hour. */
+const CLEANUP_INTERVAL_MS = 60 * 60 * 1000;
+/**
+ * Tracks the 24-hour messaging window for each conversation thread.
+ *
+ * Many messaging platforms (notably WhatsApp) only allow free-form messages
+ * within a window that starts when the user last messaged. After the window
+ * closes, only template messages can be sent.
+ *
+ * The tracker records:
+ * - Inbound message timestamps (sets window to `timestamp + 24h`)
+ * - Platform-reported expiry times (from status webhooks, more accurate)
+ *
+ * Stale entries are periodically cleaned up to prevent unbounded memory growth.
+ */
+export class WindowTracker {
+    windows = new Map();
+    lastCleanup = Date.now();
+    /**
+     * Record an inbound message, opening or extending the messaging window.
+     * The window is set to 24 hours from the message timestamp.
+     *
+     * @param threadId - The conversation thread identifier.
+     * @param timestamp - When the user's message was sent.
+     */
+    recordInbound(threadId, timestamp) {
+        this.maybeCleanup();
+        const expiresAt = new Date(timestamp.getTime() + DEFAULT_WINDOW_MS);
+        const existing = this.windows.get(threadId);
+        // Only extend — never shrink the window
+        if (!existing || expiresAt > existing.expiresAt) {
+            this.windows.set(threadId, { expiresAt });
+        }
+    }
+    /**
+     * Record a platform-reported window expiry (e.g. from a WhatsApp status webhook).
+     * Platform-reported values are more accurate than computed ones.
+     *
+     * @param threadId - The conversation thread identifier.
+     * @param expiresAt - The platform-reported expiration timestamp.
+     */
+    recordExpiry(threadId, expiresAt) {
+        this.maybeCleanup();
+        this.windows.set(threadId, { expiresAt });
+    }
+    /**
+     * Check whether the messaging window is currently open for a thread.
+     *
+     * @param threadId - The conversation thread identifier.
+     * @returns `true` if the window is open and free-form messages can be sent.
+     */
+    isWindowOpen(threadId) {
+        const entry = this.windows.get(threadId);
+        if (!entry)
+            return false;
+        return entry.expiresAt > new Date();
+    }
+    /**
+     * Get the window expiry timestamp for a thread.
+     *
+     * @param threadId - The conversation thread identifier.
+     * @returns The expiry date, or `null` if no window is tracked.
+     */
+    getExpiry(threadId) {
+        const entry = this.windows.get(threadId);
+        return entry?.expiresAt ?? null;
+    }
+    /**
+     * Run cleanup if enough time has passed since the last cleanup.
+     * Removes all expired entries to prevent unbounded memory growth.
+     */
+    maybeCleanup() {
+        const now = Date.now();
+        if (now - this.lastCleanup < CLEANUP_INTERVAL_MS)
+            return;
+        this.lastCleanup = now;
+        const cutoff = new Date(now);
+        for (const [threadId, entry] of this.windows) {
+            if (entry.expiresAt <= cutoff) {
+                this.windows.delete(threadId);
+            }
+        }
+    }
+    /** Return the number of tracked windows. */
+    get size() {
+        return this.windows.size;
+    }
+    /** Clear all tracked windows. */
+    clear() {
+        this.windows.clear();
+    }
+}
+//# sourceMappingURL=window-tracker.js.map

package/dist/adapter/window-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-tracker.js","sourceRoot":"","sources":["../../src/adapter/window-tracker.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,iBAAiB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9C,4CAA4C;AAC5C,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAO3C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAa;IACP,OAAO,GAA6B,IAAI,GAAG,EAAE,CAAC;IACvD,WAAW,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;IAEzC;;;;;;OAMG;IACH,aAAa,CAAC,QAAgB,EAAE,SAAe;QAC7C,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC;QACpE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAE5C,wCAAwC;QACxC,IAAI,CAAC,QAAQ,IAAI,SAAS,GAAG,QAAQ,CAAC,SAAS,EAAE,CAAC;YAChD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,QAAgB,EAAE,SAAe;QAC5C,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,QAAgB;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,KAAK,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,QAAgB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,KAAK,EAAE,SAAS,IAAI,IAAI,CAAC;IAClC,CAAC;IAED;;;OAGG;IACK,YAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,GAAG,mBAAmB;YAAE,OAAO;QAEzD,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7B,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7C,IAAI,KAAK,CAAC,SAAS,IAAI,MAAM,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,4CAA4C;IAC5C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,iCAAiC;IACjC,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Base error class for all messaging SDK errors.
+ * Carries a machine-readable `code` and the `platform` where the error originated.
+ */
+export declare class MessagingError extends Error {
+    /** Machine-readable error code (e.g. "RATE_LIMIT", "AUTH_FAILED"). */
+    readonly code: string;
+    /** The platform where this error originated (e.g. "whatsapp", "messenger"). */
+    readonly platform: string;
+    constructor(message: string, code: string, platform: string);
+}
+/**
+ * Thrown when the platform's rate limit has been exceeded.
+ * Includes the recommended wait time before retrying.
+ */
+export declare class RateLimitError extends MessagingError {
+    /** Number of milliseconds to wait before retrying. */
+    readonly retryAfterMs: number;
+    constructor(message: string, platform: string, retryAfterMs: number);
+}
+/**
+ * Thrown when attempting to send a message outside the allowed messaging window
+ * (e.g. WhatsApp's 24-hour customer service window).
+ */
+export declare class WindowClosedError extends MessagingError {
+    /** When the messaging window expired. */
+    readonly expiredAt: Date;
+    /** Template message IDs that can still be sent outside the window. */
+    readonly suggestedTemplates?: string[];
+    constructor(message: string, platform: string, expiredAt: Date, suggestedTemplates?: string[]);
+}
+/**
+ * Thrown when API authentication fails (invalid token, expired credentials).
+ */
+export declare class AuthenticationError extends MessagingError {
+    constructor(message: string, platform: string);
+}
+/**
+ * Thrown when the API token lacks required permissions for the operation.
+ */
+export declare class PermissionError extends MessagingError {
+    constructor(message: string, platform: string);
+}
+/**
+ * Thrown when the recipient is invalid, blocked, or unreachable.
+ */
+export declare class RecipientError extends MessagingError {
+    constructor(message: string, platform: string);
+}
+/**
+ * Thrown when a template message is invalid or not approved.
+ */
+export declare class TemplateError extends MessagingError {
+    constructor(message: string, platform: string);
+}
+/**
+ * Thrown when a media operation fails (upload, download, invalid format).
+ */
+export declare class MediaError extends MessagingError {
+    constructor(message: string, platform: string);
+}
+/**
+ * Thrown when webhook signature verification fails.
+ * Indicates a potentially spoofed or tampered webhook request.
+ */
+export declare class WebhookVerificationError extends MessagingError {
+    constructor(message: string, platform: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,sEAAsE;IACtE,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,+EAA+E;IAC/E,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAM5D;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,sDAAsD;IACtD,SAAgB,YAAY,EAAE,MAAM,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAKpE;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,yCAAyC;IACzC,SAAgB,SAAS,EAAE,IAAI,CAAC;IAEhC,sEAAsE;IACtE,SAAgB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;gBAElC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,MAAM,EAAE;CAM9F;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,cAAc;gBACrC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,cAAc;gBACpC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,cAAc;gBAChC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,cAAc;gBAC9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI9C"}

package/dist/errors.js

@@ -0,0 +1,101 @@
+/**
+ * Base error class for all messaging SDK errors.
+ * Carries a machine-readable `code` and the `platform` where the error originated.
+ */
+export class MessagingError extends Error {
+    /** Machine-readable error code (e.g. "RATE_LIMIT", "AUTH_FAILED"). */
+    code;
+    /** The platform where this error originated (e.g. "whatsapp", "messenger"). */
+    platform;
+    constructor(message, code, platform) {
+        super(message);
+        this.name = 'MessagingError';
+        this.code = code;
+        this.platform = platform;
+    }
+}
+/**
+ * Thrown when the platform's rate limit has been exceeded.
+ * Includes the recommended wait time before retrying.
+ */
+export class RateLimitError extends MessagingError {
+    /** Number of milliseconds to wait before retrying. */
+    retryAfterMs;
+    constructor(message, platform, retryAfterMs) {
+        super(message, 'RATE_LIMIT', platform);
+        this.name = 'RateLimitError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Thrown when attempting to send a message outside the allowed messaging window
+ * (e.g. WhatsApp's 24-hour customer service window).
+ */
+export class WindowClosedError extends MessagingError {
+    /** When the messaging window expired. */
+    expiredAt;
+    /** Template message IDs that can still be sent outside the window. */
+    suggestedTemplates;
+    constructor(message, platform, expiredAt, suggestedTemplates) {
+        super(message, 'WINDOW_CLOSED', platform);
+        this.name = 'WindowClosedError';
+        this.expiredAt = expiredAt;
+        this.suggestedTemplates = suggestedTemplates;
+    }
+}
+/**
+ * Thrown when API authentication fails (invalid token, expired credentials).
+ */
+export class AuthenticationError extends MessagingError {
+    constructor(message, platform) {
+        super(message, 'AUTH_FAILED', platform);
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Thrown when the API token lacks required permissions for the operation.
+ */
+export class PermissionError extends MessagingError {
+    constructor(message, platform) {
+        super(message, 'PERMISSION_DENIED', platform);
+        this.name = 'PermissionError';
+    }
+}
+/**
+ * Thrown when the recipient is invalid, blocked, or unreachable.
+ */
+export class RecipientError extends MessagingError {
+    constructor(message, platform) {
+        super(message, 'RECIPIENT_ERROR', platform);
+        this.name = 'RecipientError';
+    }
+}
+/**
+ * Thrown when a template message is invalid or not approved.
+ */
+export class TemplateError extends MessagingError {
+    constructor(message, platform) {
+        super(message, 'TEMPLATE_ERROR', platform);
+        this.name = 'TemplateError';
+    }
+}
+/**
+ * Thrown when a media operation fails (upload, download, invalid format).
+ */
+export class MediaError extends MessagingError {
+    constructor(message, platform) {
+        super(message, 'MEDIA_ERROR', platform);
+        this.name = 'MediaError';
+    }
+}
+/**
+ * Thrown when webhook signature verification fails.
+ * Indicates a potentially spoofed or tampered webhook request.
+ */
+export class WebhookVerificationError extends MessagingError {
+    constructor(message, platform) {
+        super(message, 'WEBHOOK_VERIFICATION_FAILED', platform);
+        this.name = 'WebhookVerificationError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,sEAAsE;IACtD,IAAI,CAAS;IAE7B,+EAA+E;IAC/D,QAAQ,CAAS;IAEjC,YAAY,OAAe,EAAE,IAAY,EAAE,QAAgB;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,cAAc;IAChD,sDAAsD;IACtC,YAAY,CAAS;IAErC,YAAY,OAAe,EAAE,QAAgB,EAAE,YAAoB;QACjE,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,yCAAyC;IACzB,SAAS,CAAO;IAEhC,sEAAsE;IACtD,kBAAkB,CAAY;IAE9C,YAAY,OAAe,EAAE,QAAgB,EAAE,SAAe,EAAE,kBAA6B;QAC3F,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IAC/C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,cAAc;IACrD,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,cAAc;IAChD,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,cAAc;IAC/C,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,cAAc;IAC5C,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAC1D,YAAY,OAAe,EAAE,QAAgB;QAC3C,KAAK,CAAC,OAAO,EAAE,6BAA6B,EAAE,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { PlatformClient, InboundMessage, StatusUpdate, SendResult, MediaPayload, MediaHandle, MediaDownload, MediaUploadOptions, MediaReference, InteractiveMessage, InteractiveAction, InteractiveReply, ContactInfo, LocationData, ReactionData, MessageContext, ConversationInfo, PricingInfo, StatusError, FormatConverter, MessageHandler, StatusHandler, ReactionHandler, MessagingRouterConfig, SessionResolver, ResponseMapper, ResponseContext, ErrorContext, StreamMapperOptions, } from './types.js';
+export { MessagingError, RateLimitError, WindowClosedError, AuthenticationError, PermissionError, RecipientError, TemplateError, MediaError, WebhookVerificationError, } from './errors.js';
+export { createMessagingRouter } from './adapter/createMessagingRouter.js';
+export { defaultSessionResolver } from './adapter/session-resolver.js';
+export { StreamMapper } from './adapter/stream-mapper.js';
+export { WindowTracker } from './adapter/window-tracker.js';
+export { MessageDeduplicator } from './shared/deduplicator.js';
+export { BaseFormatConverter } from './shared/format-base.js';
+export { MediaCache } from './shared/media-cache.js';
+export type { MediaCacheConfig, CachedMedia } from './shared/media-cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAK5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+// ====================================
+// Errors
+// ====================================
+export { MessagingError, RateLimitError, WindowClosedError, AuthenticationError, PermissionError, RecipientError, TemplateError, MediaError, WebhookVerificationError, } from './errors.js';
+// ====================================
+// Adapter
+// ====================================
+export { createMessagingRouter } from './adapter/createMessagingRouter.js';
+export { defaultSessionResolver } from './adapter/session-resolver.js';
+export { StreamMapper } from './adapter/stream-mapper.js';
+export { WindowTracker } from './adapter/window-tracker.js';
+// ====================================
+// Shared
+// ====================================
+export { MessageDeduplicator } from './shared/deduplicator.js';
+export { BaseFormatConverter } from './shared/format-base.js';
+export { MediaCache } from './shared/media-cache.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmCA,uCAAuC;AACvC,SAAS;AACT,uCAAuC;AACvC,OAAO,EACL,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB,uCAAuC;AACvC,UAAU;AACV,uCAAuC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,uCAAuC;AACvC,SAAS;AACT,uCAAuC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/shared/deduplicator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LRU-based message deduplication to prevent processing the same
+ * webhook event twice. Uses a Map (which preserves insertion order)
+ * as the underlying data structure with TTL-based expiration.
+ */
+export declare class MessageDeduplicator {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    /**
+     * Create a new deduplicator.
+     * @param maxSize - Maximum number of message IDs to track. Default: 10000.
+     * @param ttlMs - Time-to-live for entries in milliseconds. Default: 300000 (5 minutes).
+     */
+    constructor(maxSize?: number, ttlMs?: number);
+    /**
+     * Check if a message ID has been seen recently.
+     *
+     * If the message ID is new, it is recorded and `false` is returned.
+     * If it has been seen within the TTL window, `true` is returned.
+     * Expired entries are treated as new.
+     *
+     * @param messageId - The platform-specific message identifier.
+     * @returns `true` if this message was already processed (duplicate), `false` if new.
+     */
+    isDuplicate(messageId: string): boolean;
+    /**
+     * Remove expired entries, then evict oldest if still at capacity.
+     */
+    private evict;
+    /** Return the current number of tracked message IDs. */
+    get size(): number;
+    /** Clear all tracked message IDs. */
+    clear(): void;
+}
+//# sourceMappingURL=deduplicator.d.ts.map

package/dist/shared/deduplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplicator.d.ts","sourceRoot":"","sources":["../../src/shared/deduplicator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;OAIG;gBACS,OAAO,SAAS,EAAE,KAAK,SAAU;IAM7C;;;;;;;;;OASG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAuBvC;;OAEG;IACH,OAAO,CAAC,KAAK;IAoBb,wDAAwD;IACxD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,qCAAqC;IACrC,KAAK,IAAI,IAAI;CAGd"}

package/dist/shared/deduplicator.js

@@ -0,0 +1,80 @@
+/**
+ * LRU-based message deduplication to prevent processing the same
+ * webhook event twice. Uses a Map (which preserves insertion order)
+ * as the underlying data structure with TTL-based expiration.
+ */
+export class MessageDeduplicator {
+    cache;
+    maxSize;
+    ttlMs;
+    /**
+     * Create a new deduplicator.
+     * @param maxSize - Maximum number of message IDs to track. Default: 10000.
+     * @param ttlMs - Time-to-live for entries in milliseconds. Default: 300000 (5 minutes).
+     */
+    constructor(maxSize = 10_000, ttlMs = 300_000) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Check if a message ID has been seen recently.
+     *
+     * If the message ID is new, it is recorded and `false` is returned.
+     * If it has been seen within the TTL window, `true` is returned.
+     * Expired entries are treated as new.
+     *
+     * @param messageId - The platform-specific message identifier.
+     * @returns `true` if this message was already processed (duplicate), `false` if new.
+     */
+    isDuplicate(messageId) {
+        const now = Date.now();
+        const existing = this.cache.get(messageId);
+        if (existing !== undefined) {
+            // Check if the entry has expired
+            if (now - existing < this.ttlMs) {
+                return true;
+            }
+            // Expired — delete so we can re-insert at the end
+            this.cache.delete(messageId);
+        }
+        // Evict oldest entries if at capacity
+        if (this.cache.size >= this.maxSize) {
+            this.evict(now);
+        }
+        // Record this message
+        this.cache.set(messageId, now);
+        return false;
+    }
+    /**
+     * Remove expired entries, then evict oldest if still at capacity.
+     */
+    evict(now) {
+        // First pass: remove all expired entries
+        for (const [key, timestamp] of this.cache) {
+            if (now - timestamp >= this.ttlMs) {
+                this.cache.delete(key);
+            }
+        }
+        // If still at capacity, remove oldest entries (Map iterates in insertion order)
+        if (this.cache.size >= this.maxSize) {
+            const toRemove = this.cache.size - this.maxSize + 1;
+            let removed = 0;
+            for (const key of this.cache.keys()) {
+                if (removed >= toRemove)
+                    break;
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+    }
+    /** Return the current number of tracked message IDs. */
+    get size() {
+        return this.cache.size;
+    }
+    /** Clear all tracked message IDs. */
+    clear() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=deduplicator.js.map

package/dist/shared/deduplicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplicator.js","sourceRoot":"","sources":["../../src/shared/deduplicator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IACb,KAAK,CAAsB;IAC3B,OAAO,CAAS;IAChB,KAAK,CAAS;IAE/B;;;;OAIG;IACH,YAAY,OAAO,GAAG,MAAM,EAAE,KAAK,GAAG,OAAO;QAC3C,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW,CAAC,SAAiB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAE3C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,iCAAiC;YACjC,IAAI,GAAG,GAAG,QAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,kDAAkD;YAClD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC;QAED,sCAAsC;QACtC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;QAED,sBAAsB;QACtB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,GAAW;QACvB,yCAAyC;QACzC,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1C,IAAI,GAAG,GAAG,SAAS,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,gFAAgF;QAChF,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;YACpD,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,OAAO,IAAI,QAAQ;oBAAE,MAAM;gBAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACvB,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,qCAAqC;IACrC,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/shared/format-base.d.ts

@@ -0,0 +1,44 @@
+import type { FormatConverter } from '../types.js';
+/**
+ * Base format converter that passes text through unchanged.
+ *
+ * Platform-specific packages should extend this class and override
+ * methods to handle their native formatting conventions. For example,
+ * a WhatsApp converter would translate Markdown bold (`**text**`) to
+ * WhatsApp bold (`*text*`).
+ *
+ * @example
+ * ```typescript
+ * class WhatsAppFormatConverter extends BaseFormatConverter {
+ *   toPlatformFormat(markdown: string): string {
+ *     return markdown
+ *       .replace(/\*\*(.*?)\*\* /g, '*$1*')  // bold
+ *       .replace(/__(.*?)__/g, '_$1_');       // italic
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseFormatConverter implements FormatConverter {
+    /**
+     * Convert Markdown text to plain text by stripping all formatting.
+     * Default implementation returns the input unchanged.
+     * @param markdown - Markdown-formatted text.
+     * @returns Plain text with formatting removed.
+     */
+    toPlainText(markdown: string): string;
+    /**
+     * Convert platform-specific formatted text to Markdown.
+     * Default implementation returns the input unchanged.
+     * @param text - Platform-formatted text.
+     * @returns Markdown-formatted text.
+     */
+    toMarkdown(text: string): string;
+    /**
+     * Convert Markdown to the platform's native text format.
+     * Default implementation returns the input unchanged.
+     * @param markdown - Markdown-formatted text.
+     * @returns Text in the platform's native format.
+     */
+    toPlatformFormat(markdown: string): string;
+}
+//# sourceMappingURL=format-base.d.ts.map

package/dist/shared/format-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-base.d.ts","sourceRoot":"","sources":["../../src/shared/format-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,mBAAoB,YAAW,eAAe;IAClE;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIrC;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIhC;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAG3C"}

package/dist/shared/format-base.js

@@ -0,0 +1,49 @@
+/**
+ * Base format converter that passes text through unchanged.
+ *
+ * Platform-specific packages should extend this class and override
+ * methods to handle their native formatting conventions. For example,
+ * a WhatsApp converter would translate Markdown bold (`**text**`) to
+ * WhatsApp bold (`*text*`).
+ *
+ * @example
+ * ```typescript
+ * class WhatsAppFormatConverter extends BaseFormatConverter {
+ *   toPlatformFormat(markdown: string): string {
+ *     return markdown
+ *       .replace(/\*\*(.*?)\*\* /g, '*$1*')  // bold
+ *       .replace(/__(.*?)__/g, '_$1_');       // italic
+ *   }
+ * }
+ * ```
+ */
+export class BaseFormatConverter {
+    /**
+     * Convert Markdown text to plain text by stripping all formatting.
+     * Default implementation returns the input unchanged.
+     * @param markdown - Markdown-formatted text.
+     * @returns Plain text with formatting removed.
+     */
+    toPlainText(markdown) {
+        return markdown;
+    }
+    /**
+     * Convert platform-specific formatted text to Markdown.
+     * Default implementation returns the input unchanged.
+     * @param text - Platform-formatted text.
+     * @returns Markdown-formatted text.
+     */
+    toMarkdown(text) {
+        return text;
+    }
+    /**
+     * Convert Markdown to the platform's native text format.
+     * Default implementation returns the input unchanged.
+     * @param markdown - Markdown-formatted text.
+     * @returns Text in the platform's native format.
+     */
+    toPlatformFormat(markdown) {
+        return markdown;
+    }
+}
+//# sourceMappingURL=format-base.js.map

package/dist/shared/format-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-base.js","sourceRoot":"","sources":["../../src/shared/format-base.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAgB,mBAAmB;IACvC;;;;;OAKG;IACH,WAAW,CAAC,QAAgB;QAC1B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,QAAgB;QAC/B,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/shared/media-cache.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module shared/media-cache
+ *
+ * In-memory LRU cache for downloaded media attachments.
+ *
+ * Avoids re-downloading the same attachment when multiple handlers
+ * or retry logic access the same media ID. Uses a Map-based LRU
+ * with TTL expiration (media URLs from Meta are temporary -- typically
+ * valid for ~5 minutes).
+ */
+/** Configuration for the {@link MediaCache}. */
+export interface MediaCacheConfig {
+    /** Max entries in the cache. Default: 100. */
+    maxSize?: number;
+    /** TTL for cached entries in ms. Default: 300_000 (5 minutes). */
+    ttlMs?: number;
+}
+/** A cached media entry with metadata. */
+export interface CachedMedia {
+    /** Raw media bytes. */
+    data: Buffer;
+    /** MIME type of the media. */
+    mimeType: string;
+    /** Original filename (if available). */
+    filename?: string;
+    /** Timestamp when the entry was cached (ms since epoch). */
+    cachedAt: number;
+}
+/**
+ * In-memory LRU cache for downloaded media.
+ *
+ * Avoids re-downloading the same attachment when multiple handlers
+ * or retry logic access the same media ID. Uses a Map-based LRU
+ * with TTL expiration (media URLs from Meta are temporary -- typically
+ * valid for ~5 minutes).
+ */
+export declare class MediaCache {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(config?: MediaCacheConfig);
+    /**
+     * Get cached media by ID. Returns `undefined` if not found or expired.
+     *
+     * Accessing an entry refreshes its LRU position (moves it to the end
+     * of the eviction queue).
+     *
+     * @param mediaId - The platform-specific media identifier.
+     * @returns The cached media entry, or `undefined`.
+     */
+    get(mediaId: string): CachedMedia | undefined;
+    /**
+     * Store media in the cache.
+     *
+     * If the cache is at capacity, the least-recently-used entry is evicted.
+     *
+     * @param mediaId - The platform-specific media identifier.
+     * @param media   - The media content to cache.
+     */
+    set(mediaId: string, media: {
+        data: Buffer;
+        mimeType: string;
+        filename?: string;
+    }): void;
+    /**
+     * Check if media is cached and not expired.
+     *
+     * @param mediaId - The platform-specific media identifier.
+     * @returns `true` if the media is cached and still valid.
+     */
+    has(mediaId: string): boolean;
+    /**
+     * Wrap a download function with caching.
+     *
+     * If the media is cached, returns the cached version. Otherwise
+     * calls `downloadFn`, caches the result, and returns it.
+     *
+     * @param mediaId    - The platform-specific media identifier.
+     * @param downloadFn - A function that downloads the media.
+     * @returns The media content (from cache or fresh download).
+     */
+    getOrDownload(mediaId: string, downloadFn: () => Promise<{
+        data: Buffer;
+        mimeType: string;
+        filename?: string;
+    }>): Promise<{
+        data: Buffer;
+        mimeType: string;
+        filename?: string;
+    }>;
+    /** Return the current number of cached entries. */
+    get size(): number;
+    /** Clear all cached entries. */
+    clear(): void;
+}
+//# sourceMappingURL=media-cache.d.ts.map

package/dist/shared/media-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-cache.d.ts","sourceRoot":"","sources":["../../src/shared/media-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,CAAC,EAAE,gBAAgB;IAMrC;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAe7C;;;;;;;OAOG;IACH,GAAG,CACD,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3D,IAAI;IAeP;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B;;;;;;;;;OASG;IACG,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAC/E,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAWjE,mDAAmD;IACnD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gCAAgC;IAChC,KAAK,IAAI,IAAI;CAGd"}