@mono-agent/messenger-adapter 0.21.0

package/README.md

@@ -0,0 +1,302 @@
+# @mono-agent/messenger-adapter
+
+Connect a mono-agent responder to Facebook Messenger users through the Meta
+Graph API: a signed webhook for inbound messages and the Send API for replies.
+
+## Category
+
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
+Category: `communication`
+Tier: `plugin`
+Catalog responsibility: Adapts Facebook Messenger webhook events to structural agent requests and delivers final-only replies through the Send API.
+
+<!-- package-metadata:end -->
+
+## Responsibility
+
+Verify Meta webhook signatures, deduplicate events, authorize page-scoped user
+ids (PSIDs), turn text, postbacks, images, and documents into agent requests,
+queue work per user, support `/cancel`, and deliver each completed answer as
+plain-text Send API messages. Proactive cron/webhook notifications are
+delivered verbatim and recorded to the conversation's history.
+
+This is a **plugin-tier** package: it publishes to npm in the mono-agent
+lockstep at the same version as the core packages, but it is not part of the
+core `@mono-agent/agent-app` dependency closure. `@mono-agent/agent-app` loads it
+only when a host declares it under `channels.plugins[]`.
+
+The adapter is opt-in: plugin `config.enabled` / `MONO_AGENT_MESSENGER_ENABLED`
+defaults to `false`. While disabled the loader skips secret and allowlist
+validation and the channel reports `disabled` rather than `waiting_for_config`.
+
+## Install / Usage
+
+```bash
+pnpm add @mono-agent/agent-app@latest @mono-agent/messenger-adapter@latest
+```
+
+Put the three Meta credentials in the agent's `.env`:
+
+```bash
+MONO_AGENT_MESSENGER_PAGE_ACCESS_TOKEN=...   # Page access token with pages_messaging
+MONO_AGENT_MESSENGER_APP_SECRET=...          # App secret, verifies X-Hub-Signature-256
+MONO_AGENT_MESSENGER_VERIFY_TOKEN=...        # Any string you also paste into the Meta webhook setup
+```
+
+Then declare the plugin:
+
+```json
+{
+  "channels": {
+    "plugins": [
+      {
+        "package": "@mono-agent/messenger-adapter",
+        "id": "messenger",
+        "config": {
+          "enabled": true,
+          "allowedUserIds": ["1234567890123456"],
+          "host": "0.0.0.0",
+          "port": 8650,
+          "allowNonLoopback": true,
+          "webhookPath": "/messenger/webhook"
+        }
+      }
+    ]
+  }
+}
+```
+
+Expose the webhook over HTTPS (reverse proxy or tunnel) and register
+`https://<public-host>/messenger/webhook` in the Meta app's Messenger webhook
+settings with the same verify token, subscribing to the `messages` and
+`messaging_postbacks` fields. `GET <path>/health` answers `{"ok":true}` for
+liveness checks.
+
+## Architecture
+
+### Data flow
+
+1. The channel driver layers plugin JSON and environment settings, validates
+   secrets and the PSID allowlist, then starts the webhook server on the
+   configured host and port.
+2. The server answers Meta's `hub.challenge` handshake, verifies each POST's
+   `X-Hub-Signature-256` over the raw body, acknowledges with 200, and hands the
+   parsed payload to the adapter afterwards so Meta never waits on a model turn.
+3. The adapter drops echoes, receipts, and duplicate message ids, rejects
+   unauthorized senders with a one-line denial, normalizes text, postbacks, and
+   attachments (downloading images and documents from Meta's CDN), and handles
+   `/start`, `/help`, and `/cancel` without a model call.
+4. Allowed prompts enter the host-owned structural responder behind a per-user
+   queue with typing indicators. The message stream buffers deltas, flattens
+   Markdown, and posts the final answer as 2,000-character Send API messages.
+5. Proactive notifications (`messenger:<psid>` destinations) are posted verbatim
+   with the configured `messaging_type`/tag and recorded to conversation history;
+   process-job wakes steer into an active run or fall back to a follow-up turn.
+6. Shutdown closes the webhook server and aborts active responder work.
+
+### Package structure
+
+| Source module | Responsibility |
+| --- | --- |
+| [`channel-driver.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/channel-driver.ts) | Config-first plugin lifecycle, proactive notify routing, and process-job delivery. |
+| [`config.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/config.ts) | JSON/env layering, secret and allowlist validation, loopback guard, and redacted config metadata. |
+| [`server.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/server.ts) | Meta verification handshake, signature check, body limits, and health endpoint. |
+| [`adapter.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/adapter.ts) | Dedup, authorization, normalization, attachment ingest, per-user queue, commands, cancellation, responder invocation, and proactive delivery. |
+| [`graph-client.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/graph-client.ts) | Send API client for text chunks, attachment URLs, and sender actions. Replay-safe sender actions retry once; message POSTs retry only a `429` and surface every other unknown outcome as an ambiguous delivery. Graph errors are scrubbed of the configured token. |
+| [`message-stream.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/message-stream.ts) | Buffered final-only answer delivery with Markdown flattening. |
+| [`text.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/text.ts) | Signature verification, Markdown stripping, and code-point-safe chunking. |
+| [`start.ts`](https://github.com/robertsreberski/mono-agent/blob/main/extras/messenger-adapter/src/start.ts) | Composition root wiring client, adapter, and server into one start/stop handle. |
+
+### Configuration
+
+| Key | Env | Default | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | `MONO_AGENT_MESSENGER_ENABLED` | `false` | Opt-in switch. |
+| — | `MONO_AGENT_MESSENGER_PAGE_ACCESS_TOKEN` | — | Secret, **env-only**. Page token used for the Send API. Rejected in JSON. |
+| — | `MONO_AGENT_MESSENGER_APP_SECRET` | — | Secret, **env-only**. HMAC key for webhook signature verification. Rejected in JSON. |
+| — | `MONO_AGENT_MESSENGER_VERIFY_TOKEN` | — | Secret, **env-only**. Expected `hub.verify_token` during webhook setup. Rejected in JSON. |
+| `allowedUserIds` | `MONO_AGENT_MESSENGER_ALLOWED_USER_IDS` | `[]` | PSIDs allowed to talk to the agent. |
+| `allowAllUsers` | `MONO_AGENT_MESSENGER_ALLOW_ALL_USERS` | `false` | Allow every user (ignores the allowlist). |
+| `host` | `MONO_AGENT_MESSENGER_HOST` | `127.0.0.1` | Bind address. Non-loopback needs `allowNonLoopback`. |
+| `port` | `MONO_AGENT_MESSENGER_PORT` | `8650` | Bind port. |
+| `webhookPath` | `MONO_AGENT_MESSENGER_WEBHOOK_PATH` | `/messenger/webhook` | Webhook route; `/health` is appended for liveness. |
+| `apiVersion` | `MONO_AGENT_MESSENGER_API_VERSION` | `v21.0` | Graph API version. |
+| `allowNonLoopback` | `MONO_AGENT_MESSENGER_ALLOW_NON_LOOPBACK` | `false` | Explicit opt-in to bind a non-loopback host, enforced at load, at `startMessengerAdapter`, and immediately before `listen()`. |
+| `proactiveMessagingType` | `MONO_AGENT_MESSENGER_PROACTIVE_MESSAGING_TYPE` | `RESPONSE` | `messaging_type` for cron/webhook deliveries (`RESPONSE`, `UPDATE`, `MESSAGE_TAG`). |
+| `proactiveTag` | `MONO_AGENT_MESSENGER_PROACTIVE_TAG` | — | Required with `MESSAGE_TAG`, e.g. `CONFIRMED_EVENT_UPDATE`. |
+
+Meta only delivers ordinary messages inside the 24-hour window after the
+user's last message. A scheduled reminder that may fire outside that window
+needs `proactiveMessagingType: "MESSAGE_TAG"` plus a policy-compliant tag.
+
+### Conversation ids and notifications
+
+Conversations are keyed `messenger:<psid>`. Cron jobs and webhook endpoints can
+target one with `notifyConversationId: "messenger:<psid>"`; the final answer is
+posted verbatim, Markdown flattened, split into 2,000-character messages, and
+recorded to that conversation's history. Destinations outside the allowlist are
+refused by the adapter.
+
+### Behaviour notes
+
+- Meta expects a 200 within seconds; the server acknowledges first and processes
+  the payload afterwards. Duplicate deliveries are dropped by message id.
+- Messages from one user are handled in order. Up to four wait behind the
+  active turn; beyond that the user gets a short busy reply.
+- `/cancel` aborts the active turn and retires every prompt already queued
+  behind it, so a withdrawn message never answers later; a message sent after
+  the cancel runs normally. `/help` and `/start` answer without a model call.
+- Image and PDF/text attachments are downloaded from Meta's CDN and passed to
+  the agent; audio, video, and other files are described in the request text
+  with their URL. Downloads are bounded by an explicit host policy (HTTPS on
+  `fbcdn.net` / `fbsbx.com` by default, configurable via
+  `attachments.allowedHostSuffixes`): redirects are followed manually with
+  every hop re-validated, hostnames must resolve entirely to public addresses,
+  and the 20 MiB cap is applied while streaming rather than after buffering.
+- A background wake reserves its per-user queue slot BEFORE offering live input
+  to the active turn, so a prompt arriving mid-offer cannot overtake it.
+- Replies are plain text: Markdown is flattened before sending.
+- Unauthorized senders receive a one-line denial and are logged; their text
+  never reaches the agent.
+
+## Public API
+
+### Start here
+
+| API | Use it for |
+| --- | --- |
+| `createChannelDriver` / `createMessengerChannelDriver` | Load the adapter through a config-first `channels.plugins[]` entry. |
+| `startMessengerAdapter` | Start the Graph client, adapter, and webhook server together in a custom host. |
+| `MessengerAdapter` | Apply signature-verified webhook events, authorization, commands, cancellation, and responder behavior. |
+| `MessengerAdapter.notify` | Deliver a proactive message verbatim or as a follow-up turn for one user. |
+| `createMessengerWebhookServer` | Serve the Meta verification handshake and signed webhook POSTs. |
+| `MessengerGraphClient` | Send text, attachment URLs, and sender actions through the Send API. |
+| `MessengerMessageStream` | Reuse buffered plain-text final-answer delivery. |
+| `loadMessengerAdapterConfig` | Validate and redact plugin/env config without starting the channel. |
+| `verifyMessengerSignature` / `splitForMessenger` / `stripMarkdownForMessenger` | Reuse the webhook signature check and text shaping helpers. |
+
+<!-- public-api-inventory:start -->
+<!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
+
+Every symbol exported by each public code entrypoint is listed below.
+
+**`@mono-agent/messenger-adapter`**
+
+```text
+AgentMessageStream
+AgentRequest
+AgentResponder
+AgentResponse
+DEFAULT_GRAPH_API_BASE_URL
+DEFAULT_MESSENGER_API_VERSION
+DEFAULT_MESSENGER_ATTACHMENT_HOST_SUFFIXES
+DEFAULT_MESSENGER_HOST
+DEFAULT_MESSENGER_PORT
+DEFAULT_MESSENGER_WEBHOOK_PATH
+LoadMessengerAdapterConfigInput
+MESSENGER_CHANNEL_ID
+MESSENGER_CONFIG_FIELDS
+MESSENGER_ENV_ONLY_SECRET_KEYS
+MESSENGER_MAX_MESSAGE_CHARS
+MESSENGER_MESSAGING_TYPES
+MessengerAdapter
+MessengerAdapterConfig
+MessengerAdapterConfigError
+MessengerAdapterConfigErrorCode
+MessengerAdapterConfigErrorDetails
+MessengerAdapterLogger
+MessengerAdapterMessages
+MessengerAdapterOptions
+MessengerAdapterStartLogger
+MessengerAdapterStartResult
+MessengerAmbiguousDeliveryError
+MessengerAttachmentIngestOptions
+MessengerChannelDriverConfig
+MessengerChannelDriverOptions
+MessengerEventResult
+MessengerGraphClient
+MessengerGraphClientLike
+MessengerGraphClientLogger
+MessengerGraphClientOptions
+MessengerGraphError
+MessengerIgnoredReason
+MessengerMessageStream
+MessengerMessageStreamLogger
+MessengerMessageStreamOptions
+MessengerMessagingType
+MessengerNotifyOptions
+MessengerNotifyResult
+MessengerProactiveOptions
+MessengerRequestMetadata
+MessengerSendOptions
+MessengerSendResult
+MessengerSenderAction
+MessengerWebhookAttachment
+MessengerWebhookEvent
+MessengerWebhookServer
+MessengerWebhookServerLogger
+MessengerWebhookServerOptions
+RedactedMessengerAdapterConfig
+StartMessengerAdapterOptions
+assertMessengerBindAllowed
+assertNoMessengerSecretsInJson
+assertValidMessengerAdapterConfig
+attachmentUrlPolicyRejection
+createChannelDriver
+createMessengerChannelDriver
+createMessengerWebhookServer
+isLoopbackHost
+isMessengerAmbiguousDeliveryError
+isPublicUnicastAddress
+isSafeAttachmentUrl
+loadMessengerAdapterConfig
+messengerConversationId
+messengerUserIdFromConversation
+redactMessengerAdapterConfig
+splitForMessenger
+startMessengerAdapter
+stripMarkdownForMessenger
+verifyMessengerSignature
+```
+
+<!-- public-api-inventory:end -->
+
+### Programmatic use
+
+```ts
+import { loadMessengerAdapterConfig, startMessengerAdapter } from "@mono-agent/messenger-adapter";
+
+const config = await loadMessengerAdapterConfig({ env: process.env, jsonPath: "./mono-agent.config.json" });
+const running = await startMessengerAdapter({ config, responder });
+await running.notify("1234567890123456", "Reminder text", { verbatim: true });
+await running.stop();
+```
+
+## Dependency Boundary
+
+Depends only on `@mono-agent/agent-contracts` and Node's built-in `http`,
+`crypto`, and global `fetch`. It never imports the app host, harness, other
+adapters, or operator surfaces.
+
+## What This Package Does Not Own
+
+It does not own the Meta app or Page, TLS termination or the public URL for the
+webhook, Meta's messaging-window policy, prompt building, model execution,
+memory, or an operator UI.
+
+## Related Documentation
+
+- [Messenger channel guide](https://mono-agent-docs.vercel.app/channels/messenger/)
+- [Channels overview](https://mono-agent-docs.vercel.app/channels/)
+- [Delivery and send tools](https://mono-agent-docs.vercel.app/channels/delivery-and-send-tools/)
+- [Write your own channel adapter](https://mono-agent-docs.vercel.app/programmatic/custom-channels/)
+
+## Verification
+
+```bash
+pnpm --filter @mono-agent/messenger-adapter run build
+pnpm --filter @mono-agent/messenger-adapter run typecheck
+pnpm --filter @mono-agent/messenger-adapter run test
+```

package/dist/adapter.d.ts

@@ -0,0 +1,261 @@
+import { type AgentMessageStream, type AgentRequestBase, type AgentResponder as SharedAgentResponder, type AgentResponse, type NotifyDeliveryResult, type ProcessJobProjection, type ProcessJobWakeDisposition } from "@mono-agent/agent-contracts";
+import type { MessengerMessagingType } from "./config.js";
+import type { MessengerGraphClientLike } from "./graph-client.js";
+import { type MessengerMessageStreamLogger } from "./message-stream.js";
+export declare const MESSENGER_CHANNEL_ID = "messenger";
+/** Conversation id for a Messenger user: `messenger:<psid>`. */
+export declare function messengerConversationId(userId: string): string;
+/** Parse `messenger:<psid>` back into the PSID; undefined for any other shape. */
+export declare function messengerUserIdFromConversation(conversationId: string): string | undefined;
+export interface MessengerWebhookAttachment {
+    readonly type?: string;
+    readonly title?: string;
+    readonly payload?: {
+        readonly url?: string;
+        readonly coordinates?: {
+            readonly lat?: number;
+            readonly long?: number;
+        };
+    };
+}
+/** One `entry[].messaging[]` event from a Messenger webhook payload. */
+export interface MessengerWebhookEvent {
+    readonly sender?: {
+        readonly id?: string;
+    };
+    readonly recipient?: {
+        readonly id?: string;
+    };
+    readonly timestamp?: number;
+    readonly message?: {
+        readonly mid?: string;
+        readonly text?: string;
+        readonly is_echo?: boolean;
+        readonly attachments?: readonly MessengerWebhookAttachment[];
+    };
+    readonly postback?: {
+        readonly mid?: string;
+        readonly title?: string;
+        readonly payload?: string;
+    };
+    readonly delivery?: unknown;
+    readonly read?: unknown;
+}
+export interface MessengerRequestMetadata {
+    readonly user: {
+        readonly id: string;
+    };
+    readonly page?: {
+        readonly id: string;
+    };
+    readonly message: {
+        readonly id?: string;
+        readonly timestamp?: number;
+    };
+    readonly attachmentTypes: readonly string[];
+    readonly trigger: "message" | "postback" | "proactive";
+}
+export interface AgentRequest extends AgentRequestBase {
+    readonly conversationId: string;
+    readonly userId: string;
+    readonly messageId?: string;
+    readonly text: string;
+    readonly abortSignal: AbortSignal;
+    readonly metadata: {
+        readonly messenger: MessengerRequestMetadata;
+        readonly [key: string]: unknown;
+    };
+}
+export type { AgentResponse };
+export type AgentResponder = SharedAgentResponder<AgentRequest, AgentMessageStream, AgentResponse>;
+export interface MessengerAdapterMessages {
+    welcomeText?: string;
+    helpText?: string;
+    busyText?: string;
+    unauthorizedText?: string;
+    cancelledText?: string;
+    errorText?: string;
+    unsupportedText?: string;
+}
+export interface MessengerAdapterLogger extends MessengerMessageStreamLogger {
+    info?(message: string, metadata?: Record<string, unknown>): void;
+}
+export interface MessengerAttachmentIngestOptions {
+    readonly fetch?: typeof fetch;
+    readonly maxBytes?: number;
+    readonly timeoutMs?: number;
+    /**
+     * Explicit host policy for attachment downloads. Only hostnames equal to, or
+     * a subdomain of, one of these suffixes are contacted. Defaults to Meta's
+     * media CDNs ({@link DEFAULT_MESSENGER_ATTACHMENT_HOST_SUFFIXES}) — the only
+     * origin a Messenger webhook legitimately points at. Pass `[]` to disable
+     * attachment downloads entirely.
+     */
+    readonly allowedHostSuffixes?: readonly string[];
+    /** Resolves a hostname to IP addresses. Test seam; defaults to the system resolver. */
+    readonly resolveAddresses?: (hostname: string) => Promise<readonly string[]>;
+}
+export interface MessengerProactiveOptions {
+    readonly messagingType: MessengerMessagingType;
+    readonly tag?: string;
+}
+export interface MessengerAdapterOptions {
+    readonly client: MessengerGraphClientLike;
+    readonly responder: AgentResponder;
+    readonly allowedUserIds?: readonly string[];
+    readonly allowAllUsers?: boolean;
+    readonly messages?: MessengerAdapterMessages;
+    readonly logger?: MessengerAdapterLogger;
+    readonly attachments?: MessengerAttachmentIngestOptions;
+    readonly proactive?: MessengerProactiveOptions;
+    /** Inbound messages queued per user while a turn runs; beyond it the user gets `busyText`. */
+    readonly maxQueuedPerUser?: number;
+    readonly maxMessageChars?: number;
+}
+export interface MessengerNotifyOptions {
+    readonly verbatim?: boolean;
+    readonly deliveryKey?: string;
+    readonly steerActive?: boolean;
+}
+export interface MessengerNotifyResult extends NotifyDeliveryResult {
+    readonly disposition?: ProcessJobWakeDisposition;
+}
+export type MessengerIgnoredReason = "echo" | "receipt" | "no_sender" | "no_content" | "duplicate" | "empty_text";
+export type MessengerEventResult = {
+    kind: "handled";
+    userId: string;
+    messageId?: string;
+    action: "command" | "responded";
+    command?: "start" | "help";
+} | {
+    kind: "ignored";
+    reason: MessengerIgnoredReason;
+    userId?: string;
+    messageId?: string;
+} | {
+    kind: "unauthorized";
+    userId: string;
+    messageId?: string;
+} | {
+    kind: "busy";
+    userId: string;
+    messageId?: string;
+} | {
+    kind: "cancelled";
+    userId: string;
+    messageId?: string;
+} | {
+    kind: "error";
+    userId?: string;
+    messageId?: string;
+    error: unknown;
+};
+/**
+ * Meta's media CDNs. Messenger attachment payload URLs are signed links into
+ * these origins, so an explicit allowlist — rather than "any public-looking
+ * HTTPS host" — is what actually bounds this downloader.
+ */
+export declare const DEFAULT_MESSENGER_ATTACHMENT_HOST_SUFFIXES: readonly string[];
+export declare class MessengerAdapter {
+    private readonly client;
+    private readonly responder;
+    private readonly allowAllUsers;
+    private readonly allowedUserIds;
+    private readonly messages;
+    private readonly logger;
+    private readonly ingest;
+    private readonly proactive;
+    private readonly maxQueuedPerUser;
+    private readonly maxMessageChars;
+    private readonly dedup;
+    /**
+     * Every controller admitted for a user, registered BEFORE the work reaches
+     * the per-user queue. Registering eagerly is what lets `/cancel` retire a
+     * prompt that is still parked behind an earlier run — a controller created
+     * only at execution time would not exist yet.
+     */
+    private readonly pendingControllers;
+    private readonly queueTails;
+    /** Admitted work per user: at most one active turn plus `maxQueuedPerUser` waiting. */
+    private readonly admitted;
+    private stopping;
+    constructor(options: MessengerAdapterOptions);
+    /** Process one full webhook payload (`{ object: "page", entry: [...] }`). */
+    handleWebhookPayload(payload: unknown): Promise<MessengerEventResult[]>;
+    handleEvent(event: MessengerWebhookEvent): Promise<MessengerEventResult>;
+    /** Stop accepting work and abort every active turn. */
+    stop(reason?: unknown): void;
+    /**
+     * Proactive delivery. With `verbatim`, `text` is posted unchanged (no model
+     * call) and recorded to history; otherwise it runs as a turn for the user and
+     * the answer is delivered. Enforces the adapter allowlist.
+     */
+    notify(userId: string, text: string, options?: MessengerNotifyOptions): Promise<MessengerNotifyResult>;
+    /**
+     * Offer a wake to the active turn, having RESERVED this user's queue slot
+     * first.
+     *
+     * The `AgentLiveInputOffer` contract requires an accepted offer to stay
+     * represented by its reserved normal-turn slot until `settled` says whether
+     * that reservation runs or becomes a no-op. Offering first and enqueueing
+     * only afterwards lets a prompt that arrives during the offer overtake the
+     * wake; reserving first keeps arrival order. Every settlement path —
+     * accepted/applied, requeue, discard, uncertain, unavailable, and a throwing
+     * offer — resolves the reservation exactly once.
+     */
+    private steerOrRunReserved;
+    updateProcessJob(userId: string, projection: ProcessJobProjection): Promise<NotifyDeliveryResult>;
+    /** Create and register a controller for a user BEFORE the work is admitted. */
+    private registerController;
+    private unregisterController;
+    /** Abort every controller currently admitted for a user (active and parked). */
+    private cancelPending;
+    /** Append work to a user's serial queue, tracking admitted depth for the busy cap. */
+    private admit;
+    private respondToInbound;
+    private runProactiveTurn;
+    private deliverVerbatim;
+    private normalizeInbound;
+    /**
+     * Fetch one attachment under an explicit host policy.
+     *
+     * Redirects are followed MANUALLY so every hop is re-validated: the original
+     * URL being a signed Meta link says nothing about where a `Location` header
+     * points. Each hop must satisfy the host allowlist AND resolve entirely to
+     * public addresses, so neither an open redirect nor a hostname whose DNS
+     * answer is loopback/private/link-local can reach internal resources. The
+     * body is then read incrementally against the size cap, so a chunked
+     * response with an absent or lying `Content-Length` cannot exhaust memory.
+     */
+    private downloadAttachment;
+    /**
+     * Full per-hop admission check: the static URL policy, then DNS resolution
+     * with every returned address required to be public. Returns a short
+     * rejection reason, or `undefined` when the hop may be fetched.
+     */
+    private attachmentUrlRejection;
+    private createStream;
+    private proactiveSend;
+    private isAuthorized;
+    private finishCancelledUnlessAcknowledged;
+    private finishSafely;
+    private sendTextSafely;
+}
+/**
+ * Static URL policy for an attachment download: HTTPS, no embedded
+ * credentials, no literal IP host, and a hostname inside the configured
+ * allowlist. Returns a short rejection reason, or `undefined` when the URL
+ * passes. Address resolution is a separate, asynchronous check —
+ * see {@link MessengerAdapter.attachmentUrlRejection}.
+ */
+export declare function attachmentUrlPolicyRejection(url: string, allowedHostSuffixes?: readonly string[]): string | undefined;
+/** Only fetch https URLs on allowlisted Meta CDN hostnames. */
+export declare function isSafeAttachmentUrl(url: string, allowedHostSuffixes?: readonly string[]): boolean;
+/**
+ * True only for a globally routable unicast address. Everything else —
+ * loopback, private, link-local, CGNAT, multicast, and the reserved/documentation
+ * ranges — is rejected, so a hostname whose DNS answer points inside the
+ * deployment cannot be fetched.
+ */
+export declare function isPublicUnicastAddress(address: string): boolean;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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