@ariaflowagents/messaging-meta 0.8.1

package/dist/instagram/types.js

@@ -0,0 +1,19 @@
+/**
+ * @module instagram/types
+ *
+ * Comprehensive TypeScript types for the Instagram Messaging API.
+ *
+ * These types cover configuration, message payloads (text, image, quick replies,
+ * generic templates, button templates), ice breakers, private replies, and API
+ * response shapes.
+ *
+ * Key differences from WhatsApp / Messenger:
+ * - Base URL is `graph.instagram.com` (not `graph.facebook.com`).
+ * - Only IMAGE attachments are supported (no video, audio, or file).
+ * - Message limit is 1000 bytes (UTF-8), not characters.
+ * - Send response contains `message_id` only (no `recipient_id`).
+ * - Only `HUMAN_AGENT` message tag is supported (7-day window).
+ * - Ice breakers replace persistent menus.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/instagram/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/instagram/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/messenger/client.d.ts

@@ -0,0 +1,339 @@
+/**
+ * @module messenger/client
+ *
+ * Facebook Messenger Platform client implementing the {@link PlatformClient}
+ * interface from `@ariaflowagents/messaging`.
+ *
+ * Provides a complete, production-ready integration with Meta's Messenger
+ * Platform including:
+ *
+ * - Sending text, media, interactive (button/generic templates), and quick replies
+ * - Webhook handling with signature verification
+ * - Sender actions (typing indicators, mark-seen)
+ * - User profile retrieval
+ * - Persona management (create, delete)
+ * - Media upload and download
+ * - Messenger-specific format conversion (plain text)
+ *
+ * @example
+ * ```ts
+ * import { createMessengerClient } from '@ariaflowagents/messaging-meta/messenger';
+ *
+ * const client = createMessengerClient({
+ *   pageAccessToken: process.env.MESSENGER_PAGE_ACCESS_TOKEN!,
+ *   appSecret: process.env.META_APP_SECRET!,
+ *   pageId: process.env.MESSENGER_PAGE_ID!,
+ *   verifyToken: process.env.MESSENGER_VERIFY_TOKEN!,
+ * });
+ *
+ * client.onMessage(async (msg) => {
+ *   await client.sendText(msg.from.id, `Echo: ${msg.text}`);
+ * });
+ * ```
+ */
+import type { PlatformClient, SendResult, MediaPayload, MediaHandle, MediaDownload, MediaUploadOptions, InteractiveMessage, MessageHandler, StatusHandler, ReactionHandler, FormatConverter } from '@ariaflowagents/messaging';
+import type { NormalizedMessage } from '../webhook/normalizer.js';
+import type { MessengerClientConfig, ButtonTemplate, GenericTemplate, QuickReply, UserProfile, PersonaConfig, PersonaInfo, SenderAction } from './types.js';
+/** Raw inbound type (the normalised message from the webhook). */
+type MessengerInbound = NormalizedMessage;
+/** Raw outbound type (arbitrary JSON payload). */
+type MessengerOutbound = Record<string, unknown>;
+/**
+ * Create a new {@link MessengerClient} instance.
+ *
+ * This is the recommended entry point. It constructs the client with all
+ * internal dependencies wired up (Graph API client, format converter).
+ *
+ * @param config - Messenger client configuration.
+ * @returns A fully configured {@link MessengerClient}.
+ *
+ * @example
+ * ```ts
+ * const messenger = createMessengerClient({
+ *   pageAccessToken: process.env.MESSENGER_PAGE_ACCESS_TOKEN!,
+ *   appSecret: process.env.META_APP_SECRET!,
+ *   pageId: process.env.MESSENGER_PAGE_ID!,
+ *   verifyToken: process.env.MESSENGER_VERIFY_TOKEN!,
+ * });
+ * ```
+ */
+export declare function createMessengerClient(config: MessengerClientConfig): MessengerClient;
+/**
+ * Full-featured Facebook Messenger Platform client.
+ *
+ * Implements the `PlatformClient` interface from `@ariaflowagents/messaging`
+ * so it can be plugged into the messaging adapter layer, while also exposing
+ * Messenger-specific capabilities (button templates, generic templates,
+ * quick replies, personas, user profiles).
+ *
+ * Use {@link createMessengerClient} to instantiate.
+ */
+export declare class MessengerClient implements PlatformClient<MessengerClientConfig, string, MessengerInbound, MessengerOutbound> {
+    /** @inheritdoc */
+    readonly platform: "messenger";
+    private readonly graphApi;
+    private readonly config;
+    private readonly messageHandlers;
+    private readonly statusHandlers;
+    private readonly reactionHandlers;
+    private readonly formatConverterInstance;
+    private readonly mediaCache?;
+    constructor(config: MessengerClientConfig);
+    /** Messenger-specific format converter. */
+    get formatConverter(): FormatConverter;
+    /**
+     * Register a handler for inbound messages.
+     *
+     * Multiple handlers can be registered; they are called in order for
+     * each incoming message.
+     *
+     * @param handler - Callback invoked with the normalised message and raw payload.
+     */
+    onMessage(handler: MessageHandler<MessengerInbound>): void;
+    /**
+     * Register a handler for delivery/read status updates.
+     *
+     * @param handler - Callback invoked with the normalised status update.
+     */
+    onStatus(handler: StatusHandler): void;
+    /**
+     * Register a handler for reaction events.
+     *
+     * @param handler - Callback invoked with the normalised reaction data.
+     */
+    onReaction(handler: ReactionHandler): void;
+    /**
+     * Handle an incoming webhook request from Meta.
+     *
+     * - **GET** requests are treated as subscription verification challenges.
+     * - **POST** requests are validated via HMAC-SHA256 signature, normalised,
+     *   and dispatched to registered handlers.
+     *
+     * @param request - The incoming HTTP request.
+     * @returns An HTTP response (200 OK, 401 Unauthorized, or 403 Forbidden).
+     */
+    handleWebhook(request: Request): Promise<Response>;
+    /**
+     * Handle webhook verification (GET) from Meta.
+     *
+     * @param request - The GET request with `hub.mode`, `hub.verify_token`, and `hub.challenge`.
+     * @returns 200 with the challenge string, or 403 Forbidden.
+     */
+    private handleVerification;
+    /**
+     * Send a text message.
+     *
+     * Messages exceeding the 2000-character Messenger limit are truncated.
+     *
+     * @param to   - Recipient PSID.
+     * @param text - The text content to send.
+     * @returns The send result.
+     */
+    sendText(to: string, text: string): Promise<SendResult>;
+    /**
+     * Send a media message (image, video, audio, or file).
+     *
+     * Accepts URLs (string), Buffers (uploaded automatically), or ReadableStreams.
+     *
+     * @param to    - Recipient PSID.
+     * @param media - The media payload to send.
+     * @returns The send result.
+     */
+    sendMedia(to: string, media: MediaPayload): Promise<SendResult>;
+    /**
+     * Send an interactive message (buttons or list).
+     *
+     * Converts the platform-agnostic {@link InteractiveMessage} into
+     * Messenger's template format:
+     * - `action.type === 'buttons'` maps to a button template
+     * - `action.type === 'list'` maps to a generic template (carousel)
+     *
+     * @param to  - Recipient PSID.
+     * @param msg - The interactive message definition.
+     * @returns The send result.
+     * @throws {@link MessagingError} if the interactive type is unsupported.
+     */
+    sendInteractive(to: string, msg: InteractiveMessage): Promise<SendResult>;
+    /**
+     * Send a raw platform-specific payload.
+     *
+     * This is an escape hatch for features not covered by the normalised
+     * interface. The payload is merged with the standard messaging envelope.
+     *
+     * @param to      - Recipient PSID.
+     * @param payload - Raw Messenger API payload fields.
+     * @returns The send result.
+     */
+    sendRaw(to: string, payload: MessengerOutbound): Promise<SendResult>;
+    /**
+     * Mark a conversation as seen.
+     *
+     * Sends a `mark_seen` sender action to the recipient. Note that unlike
+     * WhatsApp, Messenger's mark-seen operates on the recipient (PSID) rather
+     * than a specific message ID.
+     *
+     * @param messageId - The message ID (used to identify the recipient via
+     *                    stored mapping; falls back to treating it as a PSID).
+     */
+    markAsRead(messageId: string): Promise<void>;
+    /**
+     * Send a typing indicator to a recipient.
+     *
+     * Sends the `typing_on` sender action. The indicator is automatically
+     * dismissed after 20 seconds or when a message is sent.
+     *
+     * @param to - Recipient PSID.
+     */
+    sendTypingIndicator(to: string): Promise<void>;
+    /**
+     * Send a button template message.
+     *
+     * Displays a text message with up to 3 buttons below it. Buttons can be
+     * postback (returns a payload to the webhook) or web URL (opens a browser).
+     *
+     * @param to       - Recipient PSID.
+     * @param template - The button template payload.
+     * @returns The send result.
+     */
+    sendButtonTemplate(to: string, template: ButtonTemplate): Promise<SendResult>;
+    /**
+     * Send a generic template (carousel) message.
+     *
+     * Displays a horizontally scrollable set of cards, each with an image,
+     * title, subtitle, and optional buttons.
+     *
+     * @param to       - Recipient PSID.
+     * @param template - The generic template payload.
+     * @returns The send result.
+     */
+    sendGenericTemplate(to: string, template: GenericTemplate): Promise<SendResult>;
+    /**
+     * Send quick reply options with a text message.
+     *
+     * Quick replies appear as pill-shaped buttons above the composer and
+     * disappear once the user taps one or types a message.
+     *
+     * @param to      - Recipient PSID.
+     * @param text    - The text message to display above the quick replies.
+     * @param replies - Array of quick reply options (max 13).
+     * @returns The send result.
+     */
+    sendQuickReplies(to: string, text: string, replies: QuickReply[]): Promise<SendResult>;
+    /**
+     * Send a sender action (typing indicator or mark-seen).
+     *
+     * Sender actions cannot be combined with a `message` field — they must
+     * be sent as separate requests.
+     *
+     * @param to     - Recipient PSID.
+     * @param action - The sender action (`"typing_on"`, `"typing_off"`, or `"mark_seen"`).
+     */
+    sendSenderAction(to: string, action: SenderAction): Promise<void>;
+    /**
+     * Retrieve a user's public profile information.
+     *
+     * Returns the first name, last name, and profile picture URL for the
+     * given PSID.
+     *
+     * @param psid - The user's page-scoped ID.
+     * @returns The user's profile information.
+     */
+    getUserProfile(psid: string): Promise<UserProfile>;
+    /**
+     * Persona management operations.
+     *
+     * Personas allow the bot to respond as a named human agent with a
+     * custom profile picture. Useful for the HUMAN_AGENT message tag flow.
+     */
+    readonly personas: {
+        /**
+         * Create a new persona for the page.
+         *
+         * @param config - The persona name and profile picture URL.
+         * @returns The created persona with its ID.
+         */
+        create: (config: PersonaConfig) => Promise<PersonaInfo>;
+        /**
+         * Delete a persona.
+         *
+         * @param personaId - The persona ID to delete.
+         */
+        delete: (personaId: string) => Promise<void>;
+    };
+    /**
+     * Upload media to Messenger for later use in messages.
+     *
+     * Uses the Attachment Upload API to upload files and receive an
+     * `attachment_id` that can be reused across messages.
+     *
+     * @param file    - The file content as a Buffer or ReadableStream.
+     * @param options - Upload options including MIME type and optional filename.
+     * @returns A handle containing the platform-assigned media ID.
+     */
+    uploadMedia(file: Buffer | ReadableStream, options: MediaUploadOptions): Promise<MediaHandle>;
+    /**
+     * Download media from a URL.
+     *
+     * Messenger media URLs are typically publicly accessible (unlike WhatsApp
+     * which requires a two-step media-ID-to-URL lookup). This method fetches
+     * the binary content from the provided URL.
+     *
+     * @param mediaUrl - The media URL to download from.
+     * @returns The downloaded media content and MIME type.
+     */
+    downloadMedia(mediaUrl: string): Promise<MediaDownload>;
+    /**
+     * Returns a Hono sub-application that handles webhook routes.
+     *
+     * Mounts GET (verification) and POST (event delivery) handlers at the
+     * root path. Use this to integrate the webhook into an existing Hono app.
+     *
+     * Requires `hono` to be installed as a peer dependency. The import is
+     * performed dynamically to avoid a hard compile-time dependency.
+     *
+     * @returns A Hono application with webhook routes.
+     *
+     * @example
+     * ```ts
+     * import { Hono } from 'hono';
+     *
+     * const app = new Hono();
+     * app.route('/webhooks/messenger', client.webhookRouter());
+     * ```
+     */
+    webhookRouter(): any;
+    /**
+     * Convert a normalised webhook message to a platform-agnostic {@link InboundMessage}.
+     */
+    private toInboundMessage;
+    /**
+     * Convert a normalised webhook status to a platform-agnostic {@link StatusUpdate}.
+     */
+    private toStatusUpdate;
+    /**
+     * Convert a normalised webhook reaction to a platform-agnostic {@link ReactionData}.
+     */
+    private toReactionData;
+    /**
+     * Convert a {@link MessengerSendResponse} to a platform-agnostic {@link SendResult}.
+     */
+    private toSendResult;
+    /**
+     * Map a Messenger message type string to the normalised {@link InboundMessage} type union.
+     */
+    private mapMessageType;
+    /**
+     * Extract a text fallback from non-text message types.
+     */
+    private extractTextFallback;
+    /**
+     * Extract a {@link MediaReference} from a normalised message if it contains media.
+     */
+    private extractMedia;
+    /**
+     * Resolve a MIME type to a Messenger attachment type string.
+     */
+    private resolveAttachmentType;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/messenger/client.d.ts.map

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