@ariaflowagents/messaging-meta 0.8.1

package/dist/whatsapp/client.js

@@ -0,0 +1,1043 @@
+/**
+ * @module whatsapp/client
+ *
+ * WhatsApp Cloud API client implementing the {@link PlatformClient} interface
+ * from `@ariaflowagents/messaging`.
+ *
+ * Provides a complete, production-ready integration with Meta's WhatsApp
+ * Business Platform including:
+ *
+ * - Sending text, media, interactive, template, location, and contact messages
+ * - Webhook handling with signature verification
+ * - Template management (list, create, delete)
+ * - Phone number management (register, verify, business profile)
+ * - WhatsApp Flows management
+ * - Media upload and download
+ * - Smart message splitting for the 4096-char limit
+ * - WhatsApp-specific format conversion
+ *
+ * @example
+ * ```ts
+ * import { createWhatsAppClient } from '@ariaflowagents/messaging-meta/whatsapp';
+ *
+ * const client = 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!,
+ * });
+ *
+ * client.onMessage(async (msg) => {
+ *   await client.sendText(msg.from.phone!, `Echo: ${msg.text}`);
+ * });
+ * ```
+ */
+import { MessagingError, WindowClosedError, } from '@ariaflowagents/messaging';
+import { GraphAPIClient } from '../graph-api/client.js';
+import { verifySignature } from '../webhook/verifier.js';
+import { normalizeWebhook } from '../webhook/normalizer.js';
+import { WhatsAppFormatConverter } from './format.js';
+import { splitMessage } from './split.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a new {@link WhatsAppClient} instance.
+ *
+ * This is the recommended entry point. It constructs the client with all
+ * internal dependencies wired up (Graph API client, format converter).
+ *
+ * @param config - WhatsApp client configuration.
+ * @returns A fully configured {@link WhatsAppClient}.
+ *
+ * @example
+ * ```ts
+ * 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!,
+ * });
+ * ```
+ */
+export function createWhatsAppClient(config) {
+    return new WhatsAppClient(config);
+}
+// ---------------------------------------------------------------------------
+// WhatsAppClient
+// ---------------------------------------------------------------------------
+/**
+ * Full-featured WhatsApp Cloud API client.
+ *
+ * Implements the `PlatformClient` interface from `@ariaflowagents/messaging`
+ * so it can be plugged into the messaging adapter layer, while also exposing
+ * WhatsApp-specific capabilities (templates, flows, reactions, CTA buttons).
+ *
+ * Use {@link createWhatsAppClient} to instantiate.
+ */
+export class WhatsAppClient {
+    /** @inheritdoc */
+    platform = 'whatsapp';
+    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,
+            baseUrl: config.baseUrl,
+            retry: config.retry,
+            rateLimiter: config.rateLimiter,
+            logger: config.logger,
+        });
+        this.formatConverterInstance = new WhatsAppFormatConverter();
+        this.mediaCache = config.mediaCache;
+    }
+    /** WhatsApp-specific format converter. */
+    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
+     * (paragraphs, lines, words) to stay within WhatsApp's 4096-character limit.
+     *
+     * @param to   - Recipient phone number in E.164 format.
+     * @param text - The text content to send.
+     * @returns The result of the last chunk sent.
+     */
+    async sendText(to, text) {
+        const chunks = splitMessage(text);
+        let result;
+        for (const chunk of chunks) {
+            result = await this.sendSingleText(to, chunk);
+        }
+        return result;
+    }
+    /**
+     * Send a media message (image, video, audio, document, or sticker).
+     *
+     * Accepts URLs (string), Buffers (uploaded automatically), or ReadableStreams.
+     *
+     * @param to    - Recipient phone number in E.164 format.
+     * @param media - The media payload to send.
+     * @returns The send result.
+     */
+    async sendMedia(to, media) {
+        const mediaType = this.resolveMediaType(media.mimeType);
+        const mediaObj = {};
+        if (typeof media.data === 'string') {
+            mediaObj.link = media.data;
+        }
+        else if (Buffer.isBuffer(media.data)) {
+            const handle = await this.uploadMedia(media.data, {
+                mimeType: media.mimeType,
+                filename: media.filename,
+            });
+            mediaObj.id = handle.mediaId;
+        }
+        else {
+            // ReadableStream — convert to Buffer first
+            const buffer = await streamToBuffer(media.data);
+            const handle = await this.uploadMedia(buffer, {
+                mimeType: media.mimeType,
+                filename: media.filename,
+            });
+            mediaObj.id = handle.mediaId;
+        }
+        if (media.caption)
+            mediaObj.caption = media.caption;
+        if (media.filename)
+            mediaObj.filename = media.filename;
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: mediaType,
+            [mediaType]: mediaObj,
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send an interactive message (buttons or list).
+     *
+     * Converts the platform-agnostic {@link InteractiveMessage} into WhatsApp's
+     * interactive message format.
+     *
+     * @param to  - Recipient phone number in E.164 format.
+     * @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.sendInteractiveButtons(to, {
+                body: { text: msg.body },
+                header: msg.header?.type === 'text' ? { type: 'text', text: msg.header.content } : undefined,
+                footer: msg.footer ? { text: msg.footer } : undefined,
+                buttons: msg.action.buttons.map((b) => ({ id: b.id, title: b.title })),
+            });
+        }
+        if (msg.action.type === 'list') {
+            return this.sendListMessage(to, {
+                body: { text: msg.body },
+                header: msg.header?.type === 'text' ? { type: 'text', text: msg.header.content } : undefined,
+                footer: msg.footer ? { text: msg.footer } : undefined,
+                button: msg.action.button,
+                sections: msg.action.sections,
+            });
+        }
+        if (msg.action.type === 'flow') {
+            return this.sendInteractiveFlow(to, {
+                body: { text: msg.body },
+                footer: msg.footer ? { text: msg.footer } : undefined,
+                flowId: msg.action.flowId,
+                flowCta: 'Continue',
+                flowToken: msg.action.flowToken ?? '',
+                flowAction: 'navigate',
+                flowActionPayload: msg.action.parameters,
+            });
+        }
+        throw new MessagingError(`Unsupported interactive type: ${msg.action.type}`, 'UNSUPPORTED_TYPE', 'whatsapp');
+    }
+    /**
+     * 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 phone number in E.164 format.
+     * @param payload - Raw WhatsApp API payload fields.
+     * @returns The send result.
+     */
+    async sendRaw(to, payload) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            ...payload,
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Mark a message as read on WhatsApp.
+     *
+     * Sends the blue double-tick indicator to the sender.
+     *
+     * @param messageId - The WhatsApp message ID to mark as read.
+     */
+    async markAsRead(messageId) {
+        await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            status: 'read',
+            message_id: messageId,
+        });
+    }
+    /**
+     * Send a typing indicator.
+     *
+     * WhatsApp Cloud API does not currently support typing indicators,
+     * so this method is a no-op that satisfies the {@link PlatformClient} interface.
+     *
+     * @param _to - Recipient phone number (unused).
+     */
+    async sendTypingIndicator(_to) {
+        // WhatsApp Cloud API does not support typing indicators.
+        // This is a no-op to satisfy the PlatformClient interface.
+    }
+    // =========================================================================
+    // WhatsApp-specific — Templates
+    // =========================================================================
+    /**
+     * Send a pre-approved template message.
+     *
+     * Templates are the only message type allowed outside the 24-hour
+     * customer service window. They must be approved by Meta before use.
+     *
+     * @param to       - Recipient phone number in E.164 format.
+     * @param template - The template message payload.
+     * @returns The send result.
+     */
+    async sendTemplate(to, template) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'template',
+            template,
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a text message with automatic template fallback.
+     *
+     * Attempts to send a free-form text message first. If the 24-hour
+     * customer service window has closed (indicated by a {@link WindowClosedError}),
+     * automatically falls back to the specified template message.
+     *
+     * @param to   - Recipient phone number in E.164 format.
+     * @param opts - Text content and fallback template configuration.
+     * @returns The send result (from either the text or template delivery).
+     */
+    async sendTextOrTemplate(to, opts) {
+        try {
+            return await this.sendText(to, opts.text);
+        }
+        catch (error) {
+            if (error instanceof WindowClosedError) {
+                return this.sendTemplate(to, opts.fallbackTemplate);
+            }
+            throw error;
+        }
+    }
+    // =========================================================================
+    // WhatsApp-specific — Interactive messages
+    // =========================================================================
+    /**
+     * Send a list interactive message.
+     *
+     * Lists display an expandable set of sections with selectable rows,
+     * useful for menus, catalogs, or multi-option selections.
+     *
+     * @param to   - Recipient phone number in E.164 format.
+     * @param list - The list message configuration.
+     * @returns The send result.
+     */
+    async sendListMessage(to, list) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'list',
+                header: list.header,
+                body: list.body,
+                footer: list.footer,
+                action: {
+                    button: list.button,
+                    sections: list.sections,
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a button interactive message.
+     *
+     * Supports up to 3 quick-reply buttons. Button titles are truncated
+     * to 20 characters per WhatsApp's requirements.
+     *
+     * @param to  - Recipient phone number in E.164 format.
+     * @param msg - The button message configuration.
+     * @returns The send result.
+     */
+    async sendInteractiveButtons(to, msg) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'button',
+                header: msg.header,
+                body: msg.body,
+                footer: msg.footer,
+                action: {
+                    buttons: msg.buttons.slice(0, 3).map((b) => ({
+                        type: 'reply',
+                        reply: { id: b.id, title: b.title.slice(0, 20) },
+                    })),
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a call-to-action URL button message.
+     *
+     * Renders a button that opens the specified URL in the user's browser
+     * when tapped.
+     *
+     * @param to  - Recipient phone number in E.164 format.
+     * @param cta - The CTA button configuration.
+     * @returns The send result.
+     */
+    async sendCTAButton(to, cta) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'cta_url',
+                header: cta.header,
+                body: cta.body,
+                footer: cta.footer,
+                action: {
+                    name: cta.name,
+                    parameters: cta.parameters,
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a WhatsApp Flow as an interactive message.
+     *
+     * WhatsApp Flows are multi-screen forms that run natively inside WhatsApp,
+     * enabling structured data collection without leaving the chat.
+     *
+     * @param to   - Recipient phone number in E.164 format.
+     * @param flow - The flow interactive input configuration.
+     * @returns The send result.
+     */
+    async sendInteractiveFlow(to, flow) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'flow',
+                body: flow.body,
+                footer: flow.footer,
+                action: {
+                    name: 'flow',
+                    parameters: {
+                        flow_message_version: '3',
+                        flow_id: flow.flowId,
+                        flow_cta: flow.flowCta,
+                        flow_token: flow.flowToken,
+                        flow_action: flow.flowAction,
+                        flow_action_payload: flow.flowActionPayload,
+                    },
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
+    // WhatsApp-specific — Reactions, location, contacts
+    // =========================================================================
+    /**
+     * Send a reaction emoji on an existing message.
+     *
+     * To remove a reaction, pass an empty string as the emoji.
+     *
+     * @param to        - Recipient phone number in E.164 format.
+     * @param messageId - The message to react to.
+     * @param emoji     - The emoji to react with (e.g. `"\ud83d\udc4d"`).
+     * @returns The send result.
+     */
+    async sendReaction(to, messageId, emoji) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'reaction',
+            reaction: { message_id: messageId, emoji },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a location pin message.
+     *
+     * Renders a map preview with the specified coordinates, name, and address.
+     *
+     * @param to       - Recipient phone number in E.164 format.
+     * @param location - The location payload with coordinates and optional metadata.
+     * @returns The send result.
+     */
+    async sendLocation(to, location) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'location',
+            location,
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send one or more contact cards.
+     *
+     * @param to       - Recipient phone number in E.164 format.
+     * @param contacts - Array of contact payloads.
+     * @returns The send result.
+     */
+    async sendContacts(to, contacts) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'contacts',
+            contacts,
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
+    // Template management
+    // =========================================================================
+    /**
+     * Template management operations.
+     *
+     * Provides methods to list, create, and delete message templates
+     * via the WhatsApp Business Management API.
+     */
+    templates = {
+        /**
+         * List all message templates for a WhatsApp Business Account.
+         *
+         * @param wabaId - The WhatsApp Business Account ID.
+         * @returns Array of template information objects.
+         */
+        list: async (wabaId) => {
+            const result = await this.graphApi.get(`${wabaId}/message_templates`);
+            return result.data;
+        },
+        /**
+         * Create a new message template.
+         *
+         * The template must be approved by Meta before it can be used for sending.
+         *
+         * @param wabaId   - The WhatsApp Business Account ID.
+         * @param template - The template definition.
+         * @returns The created template information.
+         */
+        create: async (wabaId, template) => {
+            return this.graphApi.post(`${wabaId}/message_templates`, template);
+        },
+        /**
+         * Delete a message template by name.
+         *
+         * Deletes all language variants of the template. Uses a POST with
+         * a `_method=DELETE` override since the Graph API client does not
+         * expose a dedicated DELETE method.
+         *
+         * @param wabaId - The WhatsApp Business Account ID.
+         * @param name   - The template name to delete.
+         */
+        delete: async (wabaId, name) => {
+            // The Graph API accepts DELETE for template removal. We use the
+            // GET endpoint with the name parameter for the query, but to
+            // actually delete we need to call the endpoint with method override.
+            // For simplicity, use a direct fetch via the low-level post with
+            // hsm_id approach — but the standard pattern is a POST to the
+            // message_templates endpoint with the name and a method override.
+            await this.graphApi.post(`${wabaId}/message_templates`, {
+                name,
+                _method: 'DELETE',
+            });
+        },
+    };
+    // =========================================================================
+    // Phone number management
+    // =========================================================================
+    /**
+     * Phone number management operations.
+     *
+     * Provides methods for phone number registration, verification,
+     * and business profile management.
+     */
+    phoneNumbers = {
+        /**
+         * Request a verification code for a phone number.
+         *
+         * @param phoneNumberId - The phone number ID to verify.
+         * @param method        - Delivery method (`"SMS"` or `"VOICE"`).
+         * @param language      - Language code for the verification message.
+         */
+        requestCode: async (phoneNumberId, method, language) => {
+            await this.graphApi.post(`${phoneNumberId}/request_code`, {
+                code_method: method,
+                language,
+            });
+        },
+        /**
+         * Verify a phone number with the received code.
+         *
+         * @param phoneNumberId - The phone number ID to verify.
+         * @param code          - The verification code received via SMS or voice.
+         */
+        verifyCode: async (phoneNumberId, code) => {
+            await this.graphApi.post(`${phoneNumberId}/verify_code`, { code });
+        },
+        /**
+         * Register a phone number for WhatsApp Business.
+         *
+         * @param phoneNumberId - The phone number ID to register.
+         * @param pin           - A 6-digit PIN for two-step verification.
+         */
+        register: async (phoneNumberId, pin) => {
+            await this.graphApi.post(`${phoneNumberId}/register`, {
+                messaging_product: 'whatsapp',
+                pin,
+            });
+        },
+        /**
+         * Get the WhatsApp Business profile for a phone number.
+         *
+         * @param phoneNumberId - The phone number ID.
+         * @returns The business profile data.
+         */
+        getBusinessProfile: async (phoneNumberId) => {
+            const result = await this.graphApi.get(`${phoneNumberId}/whatsapp_business_profile`, { fields: 'about,address,description,email,profile_picture_url,websites,vertical' });
+            return result.data[0] ?? {};
+        },
+        /**
+         * Update the WhatsApp Business profile for a phone number.
+         *
+         * @param phoneNumberId - The phone number ID.
+         * @param profile       - The profile fields to update.
+         */
+        updateBusinessProfile: async (phoneNumberId, profile) => {
+            await this.graphApi.post(`${phoneNumberId}/whatsapp_business_profile`, {
+                messaging_product: 'whatsapp',
+                ...profile,
+            });
+        },
+    };
+    // =========================================================================
+    // WhatsApp Flows management
+    // =========================================================================
+    /**
+     * WhatsApp Flows management operations.
+     *
+     * Provides methods to create, update, publish, deprecate, and inspect
+     * WhatsApp Flows.
+     */
+    flows = {
+        /**
+         * Create a new WhatsApp Flow.
+         *
+         * @param wabaId - The WhatsApp Business Account ID.
+         * @param flow   - The flow definition.
+         * @returns The created flow information.
+         */
+        create: async (wabaId, flow) => {
+            return this.graphApi.post(`${wabaId}/flows`, flow);
+        },
+        /**
+         * Update an existing WhatsApp Flow.
+         *
+         * @param flowId - The flow ID to update.
+         * @param flow   - The fields to update.
+         * @returns The updated flow information.
+         */
+        update: async (flowId, flow) => {
+            return this.graphApi.post(flowId, flow);
+        },
+        /**
+         * Publish a draft WhatsApp Flow, making it available for use in messages.
+         *
+         * @param flowId - The flow ID to publish.
+         */
+        publish: async (flowId) => {
+            await this.graphApi.post(`${flowId}/publish`, {});
+        },
+        /**
+         * Deprecate a WhatsApp Flow (soft delete).
+         *
+         * Deprecated flows can no longer be sent but existing instances continue working.
+         *
+         * @param flowId - The flow ID to deprecate.
+         */
+        delete: async (flowId) => {
+            await this.graphApi.post(flowId, { status: 'DEPRECATED' });
+        },
+        /**
+         * Get the assets (JSON definition) for a WhatsApp Flow.
+         *
+         * @param flowId - The flow ID.
+         * @returns The flow assets including download URLs.
+         */
+        getAssets: async (flowId) => {
+            return this.graphApi.get(`${flowId}/assets`);
+        },
+    };
+    // =========================================================================
+    // Media
+    // =========================================================================
+    /**
+     * Upload media to WhatsApp for later use in 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.
+     */
+    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('messaging_product', 'whatsapp');
+        formData.append('type', options.mimeType);
+        const response = await this.graphApi.postFormData(`${this.config.phoneNumberId}/media`, formData);
+        return { mediaId: response.id };
+    }
+    /**
+     * Download media from WhatsApp by its ID.
+     *
+     * Performs a two-step process: first retrieves the temporary download URL
+     * via the media info endpoint, then downloads the binary content.
+     *
+     * @param mediaId - The WhatsApp 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 };
+    }
+    // =========================================================================
+    // 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/whatsapp', 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 = `whatsapp:${this.config.phoneNumberId}:${msg.from}`;
+        return {
+            id: msg.id,
+            platform: 'whatsapp',
+            threadId,
+            from: {
+                id: msg.from,
+                name: msg.contactName,
+                phone: msg.from,
+            },
+            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: `whatsapp:${status.phoneNumberId}:${status.recipientId}`,
+            error: status.errors?.[0]
+                ? {
+                    code: String(status.errors[0].code),
+                    title: status.errors[0].title,
+                    message: status.errors[0].message,
+                }
+                : undefined,
+            conversation: status.conversation
+                ? {
+                    id: status.conversation.id,
+                    expirationTimestamp: status.conversation.expiration_timestamp
+                        ? new Date(parseInt(status.conversation.expiration_timestamp, 10) * 1000)
+                        : undefined,
+                    origin: status.conversation.origin?.type,
+                }
+                : undefined,
+            pricing: status.pricing
+                ? {
+                    model: status.pricing.pricing_model,
+                    category: status.pricing.category,
+                }
+                : undefined,
+            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 a {@link WhatsAppSendResponse} to a platform-agnostic {@link SendResult}.
+     */
+    toSendResult(to, response) {
+        return {
+            messageId: response.messages[0]?.id ?? '',
+            threadId: `whatsapp:${this.config.phoneNumberId}:${to}`,
+            timestamp: new Date(),
+            raw: response,
+        };
+    }
+    /**
+     * Map a WhatsApp message type string to the normalised {@link InboundMessage} type union.
+     */
+    mapMessageType(type) {
+        const typeMap = {
+            text: 'text',
+            image: 'image',
+            video: 'video',
+            audio: 'audio',
+            document: 'document',
+            sticker: 'sticker',
+            location: 'location',
+            contacts: 'contacts',
+            interactive: 'interactive',
+            button: '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.video?.caption)
+            return msg.video.caption;
+        if (msg.document?.caption)
+            return msg.document.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;
+        if (msg.location) {
+            return msg.location.name ?? `${msg.location.latitude},${msg.location.longitude}`;
+        }
+        return undefined;
+    }
+    /**
+     * Extract a {@link MediaReference} from a normalised message if it contains media.
+     */
+    extractMedia(msg) {
+        const mediaTypes = ['image', 'video', 'audio', 'document', '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,
+                    filename: 'filename' in media ? media.filename : undefined,
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Send a single text message (without splitting).
+     */
+    async sendSingleText(to, text) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'text',
+            text: { preview_url: false, body: text },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Resolve a MIME type to a WhatsApp media type string.
+     */
+    resolveMediaType(mimeType) {
+        if (mimeType.startsWith('image/'))
+            return 'image';
+        if (mimeType.startsWith('video/'))
+            return 'video';
+        if (mimeType.startsWith('audio/'))
+            return 'audio';
+        return 'document';
+    }
+}
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+/**
+ * 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