@ariaflowagents/messaging 0.8.1

package/README.md

@@ -0,0 +1,165 @@
+# @ariaflowagents/messaging
+
+Core interfaces and Hono adapter for connecting messaging platforms to the AriaFlow runtime.
+
+## Install
+
+```bash
+npm install @ariaflowagents/messaging
+```
+
+## Quick Start
+
+```ts
+import { Hono } from 'hono';
+import { Runtime } from '@ariaflowagents/core';
+import { createMessagingRouter } from '@ariaflowagents/messaging';
+import { createWhatsAppClient } from '@ariaflowagents/messaging-meta/whatsapp';
+
+const whatsapp = createWhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+  appSecret: process.env.META_APP_SECRET!,
+  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
+});
+
+const runtime = new Runtime({ agents: [/* ... */], defaultAgentId: 'support' });
+
+const router = createMessagingRouter({
+  runtime,
+  platforms: { whatsapp },
+});
+
+const app = new Hono();
+app.route('/messaging', router);
+// Webhook URL: POST /messaging/whatsapp/webhook
+```
+
+## Core Concepts
+
+- **`PlatformClient`** -- The interface every vendor package implements. Normalizes sending, receiving, media, webhooks, and format conversion into a single contract.
+- **`SessionResolver`** -- Maps inbound messages to AriaFlow sessions. Default: `{platform}:{threadId}`.
+- **`ResponseMapper`** -- Controls how runtime stream output is sent to the platform. Default sends accumulated text and renders suggested questions as interactive buttons.
+- **`StreamMapper`** -- Consumes `AsyncIterable<HarnessStreamPart>`, sends typing indicators during streaming, delegates final output to a `ResponseMapper`.
+
+## Error Handling
+
+All errors extend `MessagingError` with a machine-readable `code` and `platform` field.
+
+| Class | Code | When |
+|---|---|---|
+| `RateLimitError` | `RATE_LIMIT` | Platform rate limit exceeded. Carries `retryAfterMs`. |
+| `WindowClosedError` | `WINDOW_CLOSED` | 24h messaging window expired. Carries `suggestedTemplates`. |
+| `AuthenticationError` | `AUTH_FAILED` | Invalid or expired API token. |
+| `PermissionError` | `PERMISSION_DENIED` | Token lacks required permissions. |
+| `RecipientError` | `RECIPIENT_ERROR` | Recipient invalid, blocked, or unreachable. |
+| `TemplateError` | `TEMPLATE_ERROR` | Template message invalid or not approved. |
+| `MediaError` | `MEDIA_ERROR` | Media upload/download/format failure. |
+| `WebhookVerificationError` | `WEBHOOK_VERIFICATION_FAILED` | Webhook signature check failed. |
+
+```ts
+import { RateLimitError, WindowClosedError } from '@ariaflowagents/messaging';
+
+try {
+  await client.sendText(to, text);
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    await sleep(e.retryAfterMs);
+  }
+  if (e instanceof WindowClosedError) {
+    // Send a template message instead
+  }
+}
+```
+
+## Shared Utilities
+
+### MessageDeduplicator
+
+LRU cache that prevents duplicate webhook processing. Used automatically by `createMessagingRouter`.
+
+```ts
+import { MessageDeduplicator } from '@ariaflowagents/messaging';
+
+const dedup = new MessageDeduplicator(10_000, 300_000); // maxSize, ttlMs
+if (dedup.isDuplicate(messageId)) return;
+```
+
+### WindowTracker
+
+Tracks 24-hour messaging windows per thread. Updated automatically from inbound messages and status webhooks.
+
+```ts
+import { WindowTracker } from '@ariaflowagents/messaging';
+
+const tracker = new WindowTracker();
+tracker.recordInbound(threadId, new Date());
+tracker.isWindowOpen(threadId); // true (within 24h)
+```
+
+## Custom Session Resolver
+
+```ts
+import { createMessagingRouter } from '@ariaflowagents/messaging';
+import type { SessionResolver } from '@ariaflowagents/messaging';
+
+const resolver: SessionResolver = {
+  async resolve(message) {
+    const userId = await lookupUser(message.from.phone);
+    return { sessionId: `user:${userId}`, userId };
+  },
+};
+
+const router = createMessagingRouter({
+  runtime,
+  platforms: { whatsapp },
+  sessionResolver: resolver,
+});
+```
+
+## Custom Response Mapper
+
+```ts
+import { createMessagingRouter } from '@ariaflowagents/messaging';
+import type { ResponseMapper, ResponseContext } from '@ariaflowagents/messaging';
+import type { HarnessStreamPart } from '@ariaflowagents/core';
+
+const mapper: ResponseMapper = {
+  async mapResponse(parts: HarnessStreamPart[], ctx: ResponseContext) {
+    const text = parts
+      .filter((p) => p.type === 'text-delta')
+      .map((p) => p.text)
+      .join('');
+
+    // Split long responses into multiple messages
+    for (const chunk of splitIntoChunks(text, 4096)) {
+      await ctx.sendText(chunk);
+    }
+  },
+};
+
+const router = createMessagingRouter({
+  runtime,
+  platforms: { whatsapp },
+  responseMapper: mapper,
+});
+```
+
+## Multi-Platform
+
+Pass multiple clients to `platforms`. Add `onStatus`, `onError`, and `fallbackMessage` for production use:
+
+```ts
+const router = createMessagingRouter({
+  runtime,
+  platforms: { whatsapp, messenger, instagram },
+  onStatus: (status) => console.log(`${status.status}: ${status.messageId}`),
+  onError: (err, ctx) => console.error(`[${ctx.platform}]`, err.message),
+  fallbackMessage: 'Something went wrong. Please try again later.',
+});
+```
+
+## Related
+
+- [`@ariaflowagents/messaging-meta`](../ariaflow-messaging-meta) -- WhatsApp, Messenger, and Instagram clients
+- [`@ariaflowagents/core`](../ariaflow-core) -- Runtime, agents, flows

package/dist/adapter/createMessagingRouter.d.ts

@@ -0,0 +1,37 @@
+import { Hono } from 'hono';
+import type { MessagingRouterConfig } from '../types.js';
+/**
+ * Create a Hono router that bridges messaging platform webhooks with the AriaFlow runtime.
+ *
+ * For each platform in the config, this function:
+ * 1. Registers message, status, and reaction handlers on the platform client
+ * 2. Mounts GET and POST webhook routes at `/{platformName}/webhook`
+ *
+ * When a message arrives:
+ * 1. The platform client verifies the webhook signature, parses the payload,
+ *    and dispatches to the registered message handler
+ * 2. The handler deduplicates the message, tracks the conversation window,
+ *    resolves the session, and streams the runtime response
+ * 3. The stream mapper sends the response back through the platform client
+ *
+ * @param config - Router configuration with runtime, platforms, and optional customizations.
+ * @returns A Hono app with webhook routes mounted for each platform.
+ *
+ * @example
+ * ```typescript
+ * import { createMessagingRouter } from '@ariaflowagents/messaging';
+ *
+ * const router = createMessagingRouter({
+ *   runtime,
+ *   platforms: {
+ *     whatsapp: whatsappClient,
+ *     messenger: messengerClient,
+ *   },
+ * });
+ *
+ * // Mount into your main Hono app
+ * app.route('/messaging', router);
+ * ```
+ */
+export declare function createMessagingRouter(config: MessagingRouterConfig): Hono;
+//# sourceMappingURL=createMessagingRouter.d.ts.map

package/dist/adapter/createMessagingRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMessagingRouter.d.ts","sourceRoot":"","sources":["../../src/adapter/createMessagingRouter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,qBAAqB,EAAgB,MAAM,aAAa,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAyFzE"}

package/dist/adapter/createMessagingRouter.js

@@ -0,0 +1,115 @@
+import { Hono } from 'hono';
+import { MessageDeduplicator } from '../shared/deduplicator.js';
+import { WindowTracker } from './window-tracker.js';
+import { defaultSessionResolver } from './session-resolver.js';
+import { StreamMapper } from './stream-mapper.js';
+/**
+ * Create a Hono router that bridges messaging platform webhooks with the AriaFlow runtime.
+ *
+ * For each platform in the config, this function:
+ * 1. Registers message, status, and reaction handlers on the platform client
+ * 2. Mounts GET and POST webhook routes at `/{platformName}/webhook`
+ *
+ * When a message arrives:
+ * 1. The platform client verifies the webhook signature, parses the payload,
+ *    and dispatches to the registered message handler
+ * 2. The handler deduplicates the message, tracks the conversation window,
+ *    resolves the session, and streams the runtime response
+ * 3. The stream mapper sends the response back through the platform client
+ *
+ * @param config - Router configuration with runtime, platforms, and optional customizations.
+ * @returns A Hono app with webhook routes mounted for each platform.
+ *
+ * @example
+ * ```typescript
+ * import { createMessagingRouter } from '@ariaflowagents/messaging';
+ *
+ * const router = createMessagingRouter({
+ *   runtime,
+ *   platforms: {
+ *     whatsapp: whatsappClient,
+ *     messenger: messengerClient,
+ *   },
+ * });
+ *
+ * // Mount into your main Hono app
+ * app.route('/messaging', router);
+ * ```
+ */
+export function createMessagingRouter(config) {
+    const app = new Hono();
+    const deduplicator = new MessageDeduplicator();
+    const windowTracker = new WindowTracker();
+    const sessionResolver = config.sessionResolver ?? defaultSessionResolver;
+    const streamMapper = new StreamMapper();
+    const fallbackMessage = config.fallbackMessage ?? "Sorry, I'm having trouble right now. Please try again.";
+    for (const [name, platform] of Object.entries(config.platforms)) {
+        // -------------------------------------------------------
+        // Register message handler
+        // -------------------------------------------------------
+        platform.onMessage(async (message) => {
+            // Deduplicate — webhooks can be retried by the platform
+            if (deduplicator.isDuplicate(message.id))
+                return;
+            // Track the messaging window
+            windowTracker.recordInbound(message.threadId, message.timestamp);
+            // Resolve AriaFlow session
+            const { sessionId, userId } = await sessionResolver.resolve(message);
+            // Extract text input — fall back to a type indicator for non-text messages
+            const input = message.text ?? `[${message.type}]`;
+            try {
+                // Stream from the AriaFlow runtime
+                const stream = config.runtime.stream({
+                    input,
+                    sessionId,
+                    userId,
+                });
+                // Map the stream output to platform messages
+                await streamMapper.mapStream(stream, platform, message.threadId, {
+                    responseMapper: config.responseMapper,
+                });
+            }
+            catch (error) {
+                // Attempt to send a fallback message
+                try {
+                    await platform.sendText(message.threadId, fallbackMessage);
+                }
+                catch {
+                    // Cannot even send fallback — nothing more we can do
+                }
+                const errorContext = {
+                    message,
+                    platform: name,
+                    error: error,
+                };
+                config.onError?.(error, errorContext);
+            }
+        });
+        // -------------------------------------------------------
+        // Register status handler
+        // -------------------------------------------------------
+        platform.onStatus(async (status) => {
+            // Track window expiry from platform-reported conversation info.
+            // Use status.threadId (set by platform clients in the same format as
+            // inbound messages) so the window tracker key matches recordInbound().
+            if (status.conversation?.expirationTimestamp && status.threadId) {
+                windowTracker.recordExpiry(status.threadId, status.conversation.expirationTimestamp);
+            }
+            // Forward to user-provided status handler
+            config.onStatus?.(status);
+        });
+        // -------------------------------------------------------
+        // Mount webhook routes
+        // -------------------------------------------------------
+        // GET — webhook verification (e.g. Meta's hub.verify_token challenge)
+        app.get(`/${name}/webhook`, async (c) => {
+            return platform.handleWebhook(c.req.raw);
+        });
+        // POST — incoming events (messages, statuses, reactions)
+        app.post(`/${name}/webhook`, async (c) => {
+            return platform.handleWebhook(c.req.raw);
+        });
+    }
+    return app;
+}
+//# sourceMappingURL=createMessagingRouter.js.map

package/dist/adapter/createMessagingRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMessagingRouter.js","sourceRoot":"","sources":["../../src/adapter/createMessagingRouter.ts"],"names":[],"mappings":"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"}

package/dist/adapter/session-resolver.d.ts

@@ -0,0 +1,13 @@
+import type { SessionResolver } from '../types.js';
+/**
+ * Default session resolver that maps inbound messages to AriaFlow sessions.
+ *
+ * Session ID format: `{platform}:{threadId}` — ensures uniqueness across
+ * platforms even when thread IDs collide (e.g. phone numbers used as both
+ * WhatsApp and SMS thread IDs).
+ *
+ * User ID is taken from the message sender's contact ID.
+ */
+export declare const defaultSessionResolver: SessionResolver;
+export type { SessionResolver } from '../types.js';
+//# sourceMappingURL=session-resolver.d.ts.map

package/dist/adapter/session-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-resolver.d.ts","sourceRoot":"","sources":["../../src/adapter/session-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,eAOpC,CAAC;AAGF,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapter/session-resolver.js

@@ -0,0 +1,18 @@
+/**
+ * Default session resolver that maps inbound messages to AriaFlow sessions.
+ *
+ * Session ID format: `{platform}:{threadId}` — ensures uniqueness across
+ * platforms even when thread IDs collide (e.g. phone numbers used as both
+ * WhatsApp and SMS thread IDs).
+ *
+ * User ID is taken from the message sender's contact ID.
+ */
+export const defaultSessionResolver = {
+    async resolve(message) {
+        return {
+            sessionId: `${message.platform}:${message.threadId}`,
+            userId: message.from.id,
+        };
+    },
+};
+//# sourceMappingURL=session-resolver.js.map

package/dist/adapter/session-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-resolver.js","sourceRoot":"","sources":["../../src/adapter/session-resolver.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAoB;IACrD,KAAK,CAAC,OAAO,CAAC,OAAuB;QACnC,OAAO;YACL,SAAS,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,EAAE;YACpD,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE;SACxB,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/adapter/stream-mapper.d.ts

@@ -0,0 +1,33 @@
+import type { HarnessStreamPart } from '@ariaflowagents/core';
+import type { PlatformClient, StreamMapperOptions } from '../types.js';
+/**
+ * Maps an AriaFlow runtime stream to platform messages.
+ *
+ * The mapper:
+ * 1. Starts a typing indicator interval on the platform
+ * 2. Buffers all `text-delta` events into a complete response string
+ * 3. Collects metadata events (suggested-questions, handoff, flow-end, done)
+ * 4. When the stream completes, either delegates to a custom `ResponseMapper`
+ *    or uses the default behavior:
+ *    - Sends the accumulated text via `platform.sendText()`
+ *    - If suggested questions exist, sends them as interactive buttons
+ * 5. Clears the typing indicator
+ * 6. Returns all collected stream parts
+ */
+export declare class StreamMapper {
+    /**
+     * Consume an AriaFlow runtime stream and send the response to a platform.
+     *
+     * @param stream - The async iterable from `runtime.stream()`.
+     * @param platform - The platform client to send messages through.
+     * @param threadId - The thread to send responses to.
+     * @param options - Optional configuration for response mapping and typing interval.
+     * @returns All collected stream parts for inspection or logging.
+     */
+    mapStream(stream: AsyncIterable<HarnessStreamPart>, platform: PlatformClient, threadId: string, options?: StreamMapperOptions): Promise<HarnessStreamPart[]>;
+    /**
+     * Default response mapping: send accumulated text and optional suggested questions.
+     */
+    private defaultMapResponse;
+}
+//# sourceMappingURL=stream-mapper.d.ts.map

package/dist/adapter/stream-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-mapper.d.ts","sourceRoot":"","sources":["../../src/adapter/stream-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EACV,cAAc,EAEd,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB;;;;;;;;OAQG;IACG,SAAS,CACb,MAAM,EAAE,aAAa,CAAC,iBAAiB,CAAC,EACxC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA6D/B;;OAEG;YACW,kBAAkB;CAuCjC"}

package/dist/adapter/stream-mapper.js

@@ -0,0 +1,117 @@
+/** Default interval for sending typing indicators during streaming (ms). */
+const DEFAULT_TYPING_INTERVAL_MS = 5_000;
+/**
+ * Maps an AriaFlow runtime stream to platform messages.
+ *
+ * The mapper:
+ * 1. Starts a typing indicator interval on the platform
+ * 2. Buffers all `text-delta` events into a complete response string
+ * 3. Collects metadata events (suggested-questions, handoff, flow-end, done)
+ * 4. When the stream completes, either delegates to a custom `ResponseMapper`
+ *    or uses the default behavior:
+ *    - Sends the accumulated text via `platform.sendText()`
+ *    - If suggested questions exist, sends them as interactive buttons
+ * 5. Clears the typing indicator
+ * 6. Returns all collected stream parts
+ */
+export class StreamMapper {
+    /**
+     * Consume an AriaFlow runtime stream and send the response to a platform.
+     *
+     * @param stream - The async iterable from `runtime.stream()`.
+     * @param platform - The platform client to send messages through.
+     * @param threadId - The thread to send responses to.
+     * @param options - Optional configuration for response mapping and typing interval.
+     * @returns All collected stream parts for inspection or logging.
+     */
+    async mapStream(stream, platform, threadId, options) {
+        const parts = [];
+        let textBuffer = '';
+        const typingIntervalMs = options?.typingIntervalMs ?? DEFAULT_TYPING_INTERVAL_MS;
+        // Start typing indicator loop
+        let typingActive = true;
+        const typingInterval = setInterval(async () => {
+            if (!typingActive)
+                return;
+            try {
+                await platform.sendTypingIndicator(threadId);
+            }
+            catch {
+                // Typing indicator failures are non-critical — silently ignore
+            }
+        }, typingIntervalMs);
+        // Send an initial typing indicator immediately
+        try {
+            await platform.sendTypingIndicator(threadId);
+        }
+        catch {
+            // Non-critical
+        }
+        try {
+            for await (const part of stream) {
+                parts.push(part);
+                switch (part.type) {
+                    case 'text-delta':
+                        textBuffer += part.text;
+                        break;
+                    // All other event types are collected for the response mapper
+                    // but don't require special handling during streaming
+                }
+            }
+            // Stop typing indicator
+            typingActive = false;
+            clearInterval(typingInterval);
+            // Delegate to custom response mapper or use default behavior
+            if (options?.responseMapper) {
+                await options.responseMapper.mapResponse(parts, {
+                    threadId,
+                    platform: platform.platform,
+                    sendText: (text) => platform.sendText(threadId, text),
+                    sendInteractive: (msg) => platform.sendInteractive(threadId, msg),
+                    sendMedia: (media) => platform.sendMedia(threadId, media),
+                });
+            }
+            else {
+                await this.defaultMapResponse(platform, threadId, textBuffer, parts);
+            }
+        }
+        finally {
+            // Ensure typing indicator is always cleaned up
+            typingActive = false;
+            clearInterval(typingInterval);
+        }
+        return parts;
+    }
+    /**
+     * Default response mapping: send accumulated text and optional suggested questions.
+     */
+    async defaultMapResponse(platform, threadId, text, parts) {
+        // Send the accumulated text response
+        if (text.trim().length > 0) {
+            const formatted = platform.formatConverter.toPlatformFormat(text);
+            await platform.sendText(threadId, formatted);
+        }
+        // Check for suggested questions
+        const suggestedPart = parts.find((p) => p.type === 'suggested-questions');
+        if (suggestedPart && suggestedPart.suggestions.length > 0) {
+            // Limit to 3 buttons (most platforms cap at 3)
+            const buttons = suggestedPart.suggestions.slice(0, 3).map((suggestion, i) => ({
+                id: `suggestion_${i}`,
+                title: suggestion.length > 20 ? suggestion.substring(0, 17) + '...' : suggestion,
+            }));
+            const interactive = {
+                type: 'buttons',
+                body: 'You might also want to ask:',
+                action: { type: 'buttons', buttons },
+            };
+            try {
+                await platform.sendInteractive(threadId, interactive);
+            }
+            catch {
+                // If interactive messages aren't supported, silently skip
+                // The text response was already sent
+            }
+        }
+    }
+}
+//# sourceMappingURL=stream-mapper.js.map

package/dist/adapter/stream-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-mapper.js","sourceRoot":"","sources":["../../src/adapter/stream-mapper.ts"],"names":[],"mappings":"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"}

package/dist/adapter/window-tracker.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare class WindowTracker {
+    private readonly windows;
+    private lastCleanup;
+    /**
+     * 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: string, timestamp: Date): void;
+    /**
+     * 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: string, expiresAt: Date): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): Date | null;
+    /**
+     * Run cleanup if enough time has passed since the last cleanup.
+     * Removes all expired entries to prevent unbounded memory growth.
+     */
+    private maybeCleanup;
+    /** Return the number of tracked windows. */
+    get size(): number;
+    /** Clear all tracked windows. */
+    clear(): void;
+}
+//# sourceMappingURL=window-tracker.d.ts.map

package/dist/adapter/window-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-tracker.d.ts","sourceRoot":"","sources":["../../src/adapter/window-tracker.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,WAAW,CAAsB;IAEzC;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;IAWtD;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI;IAKrD;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMvC;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAKxC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAapB,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,iCAAiC;IACjC,KAAK,IAAI,IAAI;CAGd"}