@ariaflowagents/messaging-meta 0.8.1

package/dist/instagram/client.js

@@ -0,0 +1,857 @@
+/**
+ * @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 { MessagingError, MediaError, } from '@ariaflowagents/messaging';
+import { GraphAPIClient } from '../graph-api/client.js';
+import { verifySignature } from '../webhook/verifier.js';
+import { normalizeWebhook } from '../webhook/normalizer.js';
+import { InstagramFormatConverter } from './format.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Maximum message size in bytes for Instagram messages.
+ * Instagram enforces a 1000-byte limit on text messages (UTF-8 encoded).
+ */
+const MAX_MESSAGE_BYTES = 1000;
+/** Maximum number of quick replies per message. */
+const MAX_QUICK_REPLIES = 13;
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * 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 function createInstagramClient(config) {
+    return new InstagramClient(config);
+}
+// ---------------------------------------------------------------------------
+// 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 class InstagramClient {
+    /** @inheritdoc */
+    platform = 'instagram';
+    graphApi;
+    config;
+    messageHandlers = [];
+    statusHandlers = [];
+    reactionHandlers = [];
+    formatConverterInstance;
+    mediaCache;
+    constructor(config) {
+        this.config = config;
+        this.graphApi = new GraphAPIClient({
+            accessToken: config.accessToken,
+            appSecret: config.appSecret,
+            apiVersion: config.apiVersion ?? 'v24.0',
+            baseUrl: config.baseUrl ?? 'https://graph.instagram.com',
+            retry: config.retry,
+            rateLimiter: config.rateLimiter,
+            logger: config.logger,
+        });
+        this.formatConverterInstance = new InstagramFormatConverter();
+        this.mediaCache = config.mediaCache;
+    }
+    /** Instagram-specific format converter (plain text). */
+    get formatConverter() {
+        return this.formatConverterInstance;
+    }
+    // =========================================================================
+    // Lifecycle -- handler registration
+    // =========================================================================
+    /**
+     * 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) {
+        this.messageHandlers.push(handler);
+    }
+    /**
+     * Register a handler for delivery/read status updates.
+     *
+     * @param handler - Callback invoked with the normalised status update.
+     */
+    onStatus(handler) {
+        this.statusHandlers.push(handler);
+    }
+    /**
+     * Register a handler for reaction events.
+     *
+     * @param handler - Callback invoked with the normalised reaction data.
+     */
+    onReaction(handler) {
+        this.reactionHandlers.push(handler);
+    }
+    // =========================================================================
+    // Webhook handling
+    // =========================================================================
+    /**
+     * 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).
+     */
+    async handleWebhook(request) {
+        if (request.method === 'GET') {
+            return this.handleVerification(request);
+        }
+        const rawBody = await request.text();
+        const signature = request.headers.get('x-hub-signature-256');
+        if (!signature ||
+            !verifySignature({
+                appSecret: this.config.appSecret,
+                rawBody,
+                signatureHeader: signature,
+            })) {
+            return new Response('Unauthorized', { status: 401 });
+        }
+        const payload = JSON.parse(rawBody);
+        const events = normalizeWebhook(payload);
+        // Dispatch messages
+        for (const msg of events.messages) {
+            const inbound = this.toInboundMessage(msg);
+            for (const handler of this.messageHandlers) {
+                await handler(inbound, msg);
+            }
+        }
+        // Dispatch statuses
+        for (const status of events.statuses) {
+            const update = this.toStatusUpdate(status);
+            for (const handler of this.statusHandlers) {
+                await handler(update);
+            }
+        }
+        // Dispatch reactions
+        for (const reaction of events.reactions) {
+            const data = this.toReactionData(reaction);
+            for (const handler of this.reactionHandlers) {
+                await handler(data);
+            }
+        }
+        return new Response('OK', { status: 200 });
+    }
+    /**
+     * 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.
+     */
+    handleVerification(request) {
+        const url = new URL(request.url);
+        const mode = url.searchParams.get('hub.mode');
+        const token = url.searchParams.get('hub.verify_token');
+        const challenge = url.searchParams.get('hub.challenge');
+        if (mode === 'subscribe' && token === this.config.verifyToken) {
+            return new Response(challenge ?? '', { status: 200 });
+        }
+        return new Response('Forbidden', { status: 403 });
+    }
+    // =========================================================================
+    // Outbound -- core PlatformClient methods
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async sendText(to, text) {
+        const chunks = splitByBytes(text, MAX_MESSAGE_BYTES);
+        let result;
+        for (const chunk of chunks) {
+            result = await this.sendSingleText(to, chunk);
+        }
+        return result;
+    }
+    /**
+     * 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`.
+     */
+    async sendMedia(to, media) {
+        if (media.type !== 'image') {
+            throw new MediaError(`Instagram only supports image attachments. Received: ${media.type}`, 'instagram');
+        }
+        let url;
+        if (typeof media.data === 'string') {
+            url = media.data;
+        }
+        else if (Buffer.isBuffer(media.data)) {
+            const handle = await this.uploadMedia(media.data, {
+                mimeType: media.mimeType,
+                filename: media.filename,
+            });
+            // For Instagram, uploaded media returns an ID; however the send API
+            // uses URL-based payloads. We store the URL if available.
+            url = handle.url ?? '';
+        }
+        else {
+            // ReadableStream -- convert to Buffer first
+            const buffer = await streamToBuffer(media.data);
+            const handle = await this.uploadMedia(buffer, {
+                mimeType: media.mimeType,
+                filename: media.filename,
+            });
+            url = handle.url ?? '';
+        }
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            message: {
+                attachments: [
+                    {
+                        type: 'image',
+                        payload: { url },
+                    },
+                ],
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * 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.
+     */
+    async sendInteractive(to, msg) {
+        if (msg.action.type === 'buttons') {
+            return this.sendButtonTemplate(to, {
+                text: msg.body,
+                buttons: msg.action.buttons.map((b) => ({
+                    type: 'postback',
+                    title: b.title,
+                    payload: b.id,
+                })),
+            });
+        }
+        if (msg.action.type === 'list') {
+            // Map list sections to generic template elements
+            const elements = [];
+            for (const section of msg.action.sections) {
+                for (const row of section.rows) {
+                    elements.push({
+                        title: row.title,
+                        subtitle: row.description,
+                        buttons: [
+                            {
+                                type: 'postback',
+                                title: row.title.slice(0, 20),
+                                payload: row.id,
+                            },
+                        ],
+                    });
+                }
+            }
+            return this.sendGenericTemplate(to, { elements });
+        }
+        throw new MessagingError(`Unsupported interactive type: ${msg.action.type}`, 'UNSUPPORTED_TYPE', 'instagram');
+    }
+    /**
+     * 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.
+     */
+    async sendRaw(to, payload) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            ...payload,
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * 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).
+     */
+    async markAsRead(_messageId) {
+        // Instagram Messaging API does not support marking messages as read.
+        // This is a no-op to satisfy the PlatformClient interface.
+    }
+    /**
+     * Send a typing indicator (composing state) to a conversation.
+     *
+     * Uses the same `sender_action: "typing_on"` mechanism as Messenger.
+     *
+     * @param to - Recipient IGSID.
+     */
+    async sendTypingIndicator(to) {
+        await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            sender_action: 'typing_on',
+        });
+    }
+    // =========================================================================
+    // Media
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async uploadMedia(file, options) {
+        const buffer = Buffer.isBuffer(file) ? file : await streamToBuffer(file);
+        const blob = new Blob([buffer], { type: options.mimeType });
+        const formData = new FormData();
+        formData.append('file', blob, options.filename ?? 'file');
+        formData.append('type', options.mimeType);
+        const response = await this.graphApi.postFormData(`${this.config.igId}/media`, formData);
+        return { mediaId: response.id, url: response.url };
+    }
+    /**
+     * 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.
+     */
+    async downloadMedia(mediaId) {
+        if (this.mediaCache) {
+            return this.mediaCache.getOrDownload(mediaId, async () => {
+                const mediaInfo = await this.graphApi.get(mediaId);
+                const data = await this.graphApi.fetchBinary(mediaInfo.url);
+                return { data, mimeType: mediaInfo.mime_type };
+            });
+        }
+        const mediaInfo = await this.graphApi.get(mediaId);
+        const data = await this.graphApi.fetchBinary(mediaInfo.url);
+        return { data, mimeType: mediaInfo.mime_type };
+    }
+    // =========================================================================
+    // Instagram-specific -- Quick Replies
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async sendQuickReplies(to, text, replies) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            messaging_type: 'RESPONSE',
+            message: {
+                text,
+                quick_replies: replies.slice(0, MAX_QUICK_REPLIES),
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
+    // Instagram-specific -- Generic Template (Carousel)
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async sendGenericTemplate(to, template) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            message: {
+                attachment: {
+                    type: 'template',
+                    payload: {
+                        template_type: 'generic',
+                        elements: template.elements.slice(0, 10),
+                    },
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
+    // Instagram-specific -- Button Template
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async sendButtonTemplate(to, template) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            message: {
+                attachment: {
+                    type: 'template',
+                    payload: {
+                        template_type: 'button',
+                        text: template.text,
+                        buttons: template.buttons.slice(0, 3),
+                    },
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
+    // Instagram-specific -- Private Reply
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async sendPrivateReply(options) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { comment_id: options.commentId },
+            message: { text: options.text },
+        });
+        return {
+            messageId: response.message_id,
+            threadId: `instagram:${this.config.igId}:comment:${options.commentId}`,
+            timestamp: new Date(),
+            raw: response,
+        };
+    }
+    // =========================================================================
+    // Instagram-specific -- Ice Breakers
+    // =========================================================================
+    /**
+     * 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.
+     */
+    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: async (breakers) => {
+            await this.graphApi.post(`${this.config.igId}/messenger_profile`, {
+                platform: 'instagram',
+                ice_breakers: breakers,
+            });
+        },
+        /**
+         * Get the current ice breaker configuration.
+         *
+         * @returns Array of ice breaker configurations currently set.
+         */
+        get: async () => {
+            const result = await this.graphApi.get(`${this.config.igId}/messenger_profile`, { fields: 'ice_breakers' });
+            return result.data?.[0]?.ice_breakers ?? [];
+        },
+        /**
+         * 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: async () => {
+            await this.graphApi.post(`${this.config.igId}/messenger_profile`, {
+                fields: ['ice_breakers'],
+                _method: 'DELETE',
+            });
+        },
+    };
+    // =========================================================================
+    // Instagram-specific -- Message with Tag
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async sendTextWithTag(to, text, tag) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            messaging_type: 'MESSAGE_TAG',
+            tag,
+            message: { text },
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
+    // Webhook router
+    // =========================================================================
+    /**
+     * 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());
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    webhookRouter() {
+        // Dynamic import to avoid hard dependency on Hono at the module level.
+        // The caller must have Hono installed (it's a peer dependency via @ariaflowagents/messaging).
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { Hono } = require('hono');
+        const router = new Hono();
+        const self = this;
+        router.all('/*', async (c) => {
+            return self.handleWebhook(c.req.raw);
+        });
+        return router;
+    }
+    // =========================================================================
+    // Private -- conversion helpers
+    // =========================================================================
+    /**
+     * Convert a normalised webhook message to a platform-agnostic {@link InboundMessage}.
+     */
+    toInboundMessage(msg) {
+        const threadId = `instagram:${this.config.igId}:${msg.from}`;
+        return {
+            id: msg.id,
+            platform: 'instagram',
+            threadId,
+            from: {
+                id: msg.from,
+                name: msg.contactName,
+            },
+            timestamp: new Date(parseInt(msg.timestamp, 10) * 1000),
+            type: this.mapMessageType(msg.type),
+            text: msg.text?.body ?? this.extractTextFallback(msg),
+            media: this.extractMedia(msg),
+            location: msg.location,
+            interactive: msg.interactive
+                ? {
+                    type: msg.interactive.type,
+                    id: msg.interactive.button_reply?.id ??
+                        msg.interactive.list_reply?.id ??
+                        '',
+                    title: msg.interactive.button_reply?.title ??
+                        msg.interactive.list_reply?.title,
+                    description: msg.interactive.list_reply?.description,
+                }
+                : undefined,
+            context: msg.context
+                ? { messageId: msg.context.message_id, from: msg.context.from }
+                : undefined,
+            raw: msg,
+        };
+    }
+    /**
+     * Convert a normalised webhook status to a platform-agnostic {@link StatusUpdate}.
+     */
+    toStatusUpdate(status) {
+        return {
+            messageId: status.id,
+            status: status.status,
+            timestamp: new Date(parseInt(status.timestamp, 10) * 1000),
+            recipientId: status.recipientId,
+            threadId: `instagram:${this.config.igId}:${status.recipientId}`,
+            raw: status,
+        };
+    }
+    /**
+     * Convert a normalised webhook reaction to a platform-agnostic {@link ReactionData}.
+     */
+    toReactionData(reaction) {
+        return {
+            messageId: reaction.messageId,
+            emoji: reaction.emoji,
+            action: reaction.emoji ? 'react' : 'unreact',
+            userId: reaction.from,
+        };
+    }
+    /**
+     * Convert an {@link InstagramSendResponse} to a platform-agnostic {@link SendResult}.
+     *
+     * Note: Instagram send responses do NOT include `recipient_id` unlike Messenger.
+     */
+    toSendResult(to, response) {
+        return {
+            messageId: response.message_id,
+            threadId: `instagram:${this.config.igId}:${to}`,
+            timestamp: new Date(),
+            raw: response,
+        };
+    }
+    /**
+     * Map an Instagram message type string to the normalised {@link InboundMessage} type union.
+     */
+    mapMessageType(type) {
+        const typeMap = {
+            text: 'text',
+            image: 'image',
+            video: 'video',
+            audio: 'audio',
+            sticker: 'sticker',
+            interactive: 'interactive',
+            postback: 'interactive',
+            reaction: 'reaction',
+        };
+        return typeMap[type] ?? 'unknown';
+    }
+    /**
+     * Extract a text fallback from non-text message types (captions, button text, etc.).
+     */
+    extractTextFallback(msg) {
+        if (msg.image?.caption)
+            return msg.image.caption;
+        if (msg.button)
+            return msg.button.text;
+        if (msg.interactive?.button_reply)
+            return msg.interactive.button_reply.title;
+        if (msg.interactive?.list_reply)
+            return msg.interactive.list_reply.title;
+        return undefined;
+    }
+    /**
+     * Extract a {@link MediaReference} from a normalised message if it contains media.
+     */
+    extractMedia(msg) {
+        // Instagram primarily deals with images in DMs
+        const mediaTypes = ['image', 'video', 'audio', 'sticker'];
+        for (const type of mediaTypes) {
+            const media = msg[type];
+            if (media && 'id' in media) {
+                return {
+                    id: media.id,
+                    mimeType: 'mime_type' in media ? media.mime_type : undefined,
+                    caption: 'caption' in media ? media.caption : undefined,
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Send a single text message (without splitting).
+     */
+    async sendSingleText(to, text) {
+        const response = await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: to },
+            message: { text },
+        });
+        return this.toSendResult(to, response);
+    }
+}
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+/**
+ * Split a text message into chunks that fit within a byte limit.
+ *
+ * Instagram enforces a 1000-byte limit on text messages (UTF-8 encoded).
+ * This function splits at natural boundaries (paragraph breaks, line breaks,
+ * word boundaries) while respecting the byte limit.
+ *
+ * @param text     - The full message text.
+ * @param maxBytes - Maximum bytes per chunk. Default `1000`.
+ * @returns An array of text chunks, each within `maxBytes`.
+ */
+function splitByBytes(text, maxBytes = MAX_MESSAGE_BYTES) {
+    const encoder = new TextEncoder();
+    if (encoder.encode(text).length <= maxBytes) {
+        return [text];
+    }
+    const chunks = [];
+    let remaining = text;
+    while (encoder.encode(remaining).length > maxBytes) {
+        // Find the longest prefix that fits within the byte limit.
+        // Start from a character estimate and adjust.
+        let end = Math.min(remaining.length, maxBytes);
+        // Binary search for the right split point
+        while (encoder.encode(remaining.slice(0, end)).length > maxBytes) {
+            end = Math.floor(end * 0.9);
+        }
+        // Expand to fill as much as possible
+        while (end < remaining.length &&
+            encoder.encode(remaining.slice(0, end + 1)).length <= maxBytes) {
+            end++;
+        }
+        const minSplit = Math.floor(end / 2);
+        // Try to find a natural break point
+        let splitIndex = -1;
+        // 1. Try paragraph boundary (\n\n)
+        splitIndex = remaining.lastIndexOf('\n\n', end);
+        if (splitIndex > 0 && splitIndex >= minSplit) {
+            chunks.push(remaining.slice(0, splitIndex).trimEnd());
+            remaining = remaining.slice(splitIndex + 2).trimStart();
+            continue;
+        }
+        // 2. Try line boundary (\n)
+        splitIndex = remaining.lastIndexOf('\n', end);
+        if (splitIndex > 0 && splitIndex >= minSplit) {
+            chunks.push(remaining.slice(0, splitIndex).trimEnd());
+            remaining = remaining.slice(splitIndex + 1).trimStart();
+            continue;
+        }
+        // 3. Try word boundary (space)
+        splitIndex = remaining.lastIndexOf(' ', end);
+        if (splitIndex > 0 && splitIndex >= minSplit) {
+            chunks.push(remaining.slice(0, splitIndex).trimEnd());
+            remaining = remaining.slice(splitIndex + 1).trimStart();
+            continue;
+        }
+        // 4. Hard split at the byte boundary
+        chunks.push(remaining.slice(0, end));
+        remaining = remaining.slice(end);
+    }
+    if (remaining.length > 0) {
+        chunks.push(remaining);
+    }
+    return chunks;
+}
+/**
+ * Convert a `ReadableStream` to a `Buffer`.
+ *
+ * @param stream - The readable stream to consume.
+ * @returns A Buffer containing all chunks from the stream.
+ */
+async function streamToBuffer(stream) {
+    const chunks = [];
+    const reader = stream.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}
+//# sourceMappingURL=client.js.map