@ariaflowagents/messaging-meta 0.8.1

package/dist/instagram/client.d.ts

@@ -0,0 +1,365 @@
+/**
+ * @module instagram/client
+ *
+ * Instagram Messaging API client implementing the {@link PlatformClient}
+ * interface from `@ariaflowagents/messaging`.
+ *
+ * Provides a complete, production-ready integration with Meta's Instagram
+ * Messaging API including:
+ *
+ * - Sending text, image, quick reply, and template messages
+ * - Webhook handling with HMAC-SHA256 signature verification
+ * - Generic template (carousel) and button template messages
+ * - Private replies to comments on posts and reels
+ * - Ice breaker management (set, get, delete)
+ * - Typing indicator support
+ * - Smart message splitting for the 1000-byte limit
+ * - Instagram-specific format conversion (plain text)
+ *
+ * Key differences from WhatsApp / Messenger:
+ * - Uses `graph.instagram.com` as the base URL (not `graph.facebook.com`).
+ * - Only IMAGE attachments are supported (no video, audio, or file).
+ * - Message limit is 1000 bytes (UTF-8 encoded), not characters.
+ * - Send response contains only `message_id` (no `recipient_id`).
+ * - Only `HUMAN_AGENT` message tag is supported (7-day window).
+ * - Ice breakers replace persistent menus.
+ *
+ * @example
+ * ```ts
+ * import { createInstagramClient } from '@ariaflowagents/messaging-meta/instagram';
+ *
+ * const client = createInstagramClient({
+ *   accessToken: process.env.INSTAGRAM_ACCESS_TOKEN!,
+ *   appSecret: process.env.META_APP_SECRET!,
+ *   igId: process.env.INSTAGRAM_ACCOUNT_ID!,
+ *   verifyToken: process.env.INSTAGRAM_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 { InstagramClientConfig, InstagramQuickReply, InstagramGenericTemplate, InstagramButtonTemplate, PrivateReplyOptions, IceBreakerConfig, InstagramMessageTag } from './types.js';
+/** Raw inbound type (the normalised message from the webhook). */
+type InstagramInbound = NormalizedMessage;
+/** Raw outbound type (arbitrary JSON payload). */
+type InstagramOutbound = Record<string, unknown>;
+/**
+ * Create a new {@link InstagramClient} instance.
+ *
+ * This is the recommended entry point. It constructs the client with all
+ * internal dependencies wired up (Graph API client, format converter).
+ *
+ * @param config - Instagram client configuration.
+ * @returns A fully configured {@link InstagramClient}.
+ *
+ * @example
+ * ```ts
+ * const instagram = createInstagramClient({
+ *   accessToken: process.env.INSTAGRAM_ACCESS_TOKEN!,
+ *   appSecret: process.env.META_APP_SECRET!,
+ *   igId: process.env.INSTAGRAM_ACCOUNT_ID!,
+ *   verifyToken: process.env.INSTAGRAM_VERIFY_TOKEN!,
+ * });
+ * ```
+ */
+export declare function createInstagramClient(config: InstagramClientConfig): InstagramClient;
+/**
+ * Full-featured Instagram Messaging API client.
+ *
+ * Implements the `PlatformClient` interface from `@ariaflowagents/messaging`
+ * so it can be plugged into the messaging adapter layer, while also exposing
+ * Instagram-specific capabilities (quick replies, templates, ice breakers,
+ * private replies to comments).
+ *
+ * Use {@link createInstagramClient} to instantiate.
+ */
+export declare class InstagramClient implements PlatformClient<InstagramClientConfig, string, InstagramInbound, InstagramOutbound> {
+    /** @inheritdoc */
+    readonly platform: "instagram";
+    private readonly graphApi;
+    private readonly config;
+    private readonly messageHandlers;
+    private readonly statusHandlers;
+    private readonly reactionHandlers;
+    private readonly formatConverterInstance;
+    private readonly mediaCache?;
+    constructor(config: InstagramClientConfig);
+    /** Instagram-specific format converter (plain text). */
+    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<InstagramInbound>): 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.
+     *
+     * Long messages are automatically split at natural boundaries to stay
+     * within Instagram's 1000-byte (UTF-8) limit.
+     *
+     * @param to   - Recipient IGSID (Instagram-scoped user ID).
+     * @param text - The text content to send.
+     * @returns The result of the last chunk sent.
+     */
+    sendText(to: string, text: string): Promise<SendResult>;
+    /**
+     * Send a media message.
+     *
+     * Instagram only supports IMAGE attachments. Attempting to send video,
+     * audio, document, or sticker media will throw a {@link MediaError}.
+     *
+     * @param to    - Recipient IGSID.
+     * @param media - The media payload to send. Only `image` type is supported.
+     * @returns The send result.
+     * @throws {@link MediaError} if the media type is not `image`.
+     */
+    sendMedia(to: string, media: MediaPayload): Promise<SendResult>;
+    /**
+     * Send an interactive message (buttons or list).
+     *
+     * Converts the platform-agnostic {@link InteractiveMessage} into
+     * Instagram's template format:
+     * - `buttons` action type -> button template
+     * - `list` action type -> generic template (carousel)
+     *
+     * @param to  - Recipient IGSID.
+     * @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 IGSID.
+     * @param payload - Raw Instagram API payload fields.
+     * @returns The send result.
+     */
+    sendRaw(to: string, payload: InstagramOutbound): Promise<SendResult>;
+    /**
+     * Mark a message as read.
+     *
+     * Instagram Messaging API does not expose a dedicated mark-as-read
+     * endpoint. This method is a no-op that satisfies the {@link PlatformClient}
+     * interface.
+     *
+     * @param _messageId - The message ID (unused).
+     */
+    markAsRead(_messageId: string): Promise<void>;
+    /**
+     * Send a typing indicator (composing state) to a conversation.
+     *
+     * Uses the same `sender_action: "typing_on"` mechanism as Messenger.
+     *
+     * @param to - Recipient IGSID.
+     */
+    sendTypingIndicator(to: string): Promise<void>;
+    /**
+     * Upload media to Instagram for later use in messages.
+     *
+     * Note: Instagram image sending uses URL-based payloads. This method
+     * uploads via the Graph API and returns the media ID and URL if available.
+     *
+     * @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 Instagram by its ID.
+     *
+     * Performs a two-step process: first retrieves the media URL via the
+     * Graph API, then downloads the binary content.
+     *
+     * @param mediaId - The Instagram media ID.
+     * @returns The downloaded media content, MIME type, and optional filename.
+     */
+    downloadMedia(mediaId: string): Promise<MediaDownload>;
+    /**
+     * Send a text message with quick reply buttons.
+     *
+     * Quick replies appear as tappable buttons below the message. Instagram
+     * supports a maximum of 13 quick replies per message, and only
+     * `content_type: "text"` is supported.
+     *
+     * @param to      - Recipient IGSID.
+     * @param text    - The text content displayed above the quick replies.
+     * @param replies - Array of quick reply options (max 13).
+     * @returns The send result.
+     */
+    sendQuickReplies(to: string, text: string, replies: InstagramQuickReply[]): Promise<SendResult>;
+    /**
+     * Send a generic template (carousel) message.
+     *
+     * Generic templates render as horizontally scrollable cards, each with
+     * an optional image, title, subtitle, default tap action, and buttons.
+     * Supports up to 10 elements.
+     *
+     * @param to       - Recipient IGSID.
+     * @param template - The generic template configuration.
+     * @returns The send result.
+     */
+    sendGenericTemplate(to: string, template: InstagramGenericTemplate): Promise<SendResult>;
+    /**
+     * Send a button template message.
+     *
+     * Displays a text message with up to 3 buttons below it. Supports
+     * `postback` and `web_url` button types.
+     *
+     * @param to       - Recipient IGSID.
+     * @param template - The button template configuration.
+     * @returns The send result.
+     */
+    sendButtonTemplate(to: string, template: InstagramButtonTemplate): Promise<SendResult>;
+    /**
+     * Send a private reply to a comment on a post or reel.
+     *
+     * Uses `recipient.comment_id` instead of `recipient.id` to initiate
+     * a DM thread from a comment. This is rate-limited to:
+     * - 100 calls/sec for live comments
+     * - 750 calls/hour for post/reel comments
+     *
+     * @param options - The private reply options (comment ID and text).
+     * @returns The send result.
+     */
+    sendPrivateReply(options: PrivateReplyOptions): Promise<SendResult>;
+    /**
+     * Ice breaker management operations.
+     *
+     * Ice breakers are conversation starters displayed when a user opens
+     * a DM thread for the first time. They deliver `messaging_postback`
+     * webhook events when tapped.
+     */
+    readonly iceBreakers: {
+        /**
+         * Set ice breakers for the Instagram professional account.
+         *
+         * Replaces any existing ice breakers with the provided configuration.
+         *
+         * @param breakers - Array of ice breaker configurations.
+         */
+        set: (breakers: IceBreakerConfig[]) => Promise<void>;
+        /**
+         * Get the current ice breaker configuration.
+         *
+         * @returns Array of ice breaker configurations currently set.
+         */
+        get: () => Promise<IceBreakerConfig[]>;
+        /**
+         * Delete all ice breakers for the Instagram professional account.
+         *
+         * Uses a POST with `_method=DELETE` override since the Graph API
+         * client does not expose a dedicated DELETE method.
+         */
+        delete: () => Promise<void>;
+    };
+    /**
+     * Send a text message with a message tag.
+     *
+     * Instagram only supports the `HUMAN_AGENT` tag, which extends the
+     * messaging window to 7 days for live agent handoff scenarios.
+     *
+     * @param to   - Recipient IGSID.
+     * @param text - The text content to send.
+     * @param tag  - The message tag (only `"HUMAN_AGENT"` is supported).
+     * @returns The send result.
+     */
+    sendTextWithTag(to: string, text: string, tag: InstagramMessageTag): Promise<SendResult>;
+    /**
+     * 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/instagram', 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 an {@link InstagramSendResponse} to a platform-agnostic {@link SendResult}.
+     *
+     * Note: Instagram send responses do NOT include `recipient_id` unlike Messenger.
+     */
+    private toSendResult;
+    /**
+     * Map an Instagram message type string to the normalised {@link InboundMessage} type union.
+     */
+    private mapMessageType;
+    /**
+     * Extract a text fallback from non-text message types (captions, button text, etc.).
+     */
+    private extractTextFallback;
+    /**
+     * Extract a {@link MediaReference} from a normalised message if it contains media.
+     */
+    private extractMedia;
+    /**
+     * Send a single text message (without splitting).
+     */
+    private sendSingleText;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

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

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