@kuralle-agents/messaging-meta 0.8.5 → 0.9.0

package/README.md

@@ -12,11 +12,11 @@ npm install @kuralle-agents/messaging-meta @kuralle-agents/messaging
 
 Provides production-ready clients for Meta's three messaging platforms, built on a shared Graph API foundation with retry logic, rate limiting, and unified error handling.
 
-- **WhatsApp** — full API coverage: text (auto-split at 4096 chars), media, templates, interactive buttons, list messages, CTA buttons, WhatsApp Flows, reactions, locations, contacts, commerce (single/multi-product, catalog, and address messages, plus inbound order parsing).
-- **Messenger** — button templates, generic templates (carousel), quick replies, sender actions, user profile lookups.
-- **Instagram** — text (auto-split at 1000 bytes), quick replies, carousels, private replies to comments, ice breakers, message tags.
+- **WhatsApp** — full API coverage: text (auto-split at 4096 chars), media, templates, interactive buttons, list messages (max 10 rows total), CTA buttons, WhatsApp Flows, reactions, locations, contacts, typing indicators (via message id), commerce (single/multi-product, catalog, address messages, inbound order + product-inquiry parsing).
+- **Messenger** — button templates, generic templates (carousel), quick replies, sender actions (`mark_seen` via PSID), user profile lookups.
+- **Instagram** — text (auto-split at 1000 bytes), media by URL (audio/image/video/file), quick replies, carousels, private replies to comments, ice breakers, message tags, `mark_seen`.
 - **Main barrel** — `GraphAPIClient`, `BaseMetaClient`, `verifySignature`, `normalizeWebhook`, error classes.
-- **Shared Graph API** — `MetaErrorClassifier`, `SmartSplitter`, `TruncateSplitter`, `ByteLimitSplitter`, unicode utilities.
+- **Shared Graph API** — default `v24.0`, `MetaErrorClassifier`, `SmartSplitter`, `TruncateSplitter`, `ByteLimitSplitter`, unicode utilities.
 
 WhatsApp is available only via the `/whatsapp` subpath (see below).
 
@@ -71,7 +71,7 @@ const instagram = createInstagramClient({
 Share catalog products and receive orders without leaving WhatsApp:
 
 ```typescript
-import { parseInboundOrder } from '@kuralle-agents/messaging-meta/whatsapp';
+import { parseInboundOrder, parseProductInquiry } from '@kuralle-agents/messaging-meta/whatsapp';
 
 // Single product, multi-product (max 10 sections / 30 products), catalog, address request
 await whatsapp.sendProduct(to, { catalogId, productRetailerId: 'sku-1', body: { text: 'Check this out' } });
@@ -110,7 +110,7 @@ const events = normalizeWebhook(JSON.parse(rawBody));
 | Import path | Contents |
 |---|---|
 | `@kuralle-agents/messaging-meta` | `GraphAPIClient`, `BaseMetaClient`, errors, `verifySignature`, `normalizeWebhook`, `MessengerClient`, `InstagramClient` |
-| `@kuralle-agents/messaging-meta/whatsapp` | `WhatsAppClient`, `createWhatsAppClient`, templates, flows, commerce (`parseInboundOrder`, `parseInboundAddress`), format converter |
+| `@kuralle-agents/messaging-meta/whatsapp` | `WhatsAppClient`, `createWhatsAppClient`, templates, flows, commerce (`parseInboundOrder`, `parseInboundAddress`, `parseProductInquiry`), format converter |
 | `@kuralle-agents/messaging-meta/messenger` | `MessengerClient`, `createMessengerClient`, format converter |
 | `@kuralle-agents/messaging-meta/instagram` | `InstagramClient`, `createInstagramClient`, ice breakers, format converter |
 | `@kuralle-agents/messaging-meta/webhooks` | `verifySignature`, `normalizeWebhook` only |

package/dist/graph-api/client.d.ts

@@ -16,7 +16,7 @@ export interface GraphAPIClientConfig {
     accessToken: string;
     /** App secret used for webhook signature verification and appsecret_proof. */
     appSecret: string;
-    /** Graph API version (e.g. `"v21.0"`). Default `"v21.0"`. */
+    /** Graph API version (e.g. `"v24.0"`). Default `"v24.0"`. */
     apiVersion?: string;
     /** Base URL for the Graph API. Default `"https://graph.facebook.com"`. */
     baseUrl?: string;
@@ -52,6 +52,11 @@ export declare class GraphAPIClient {
     post<T>(endpoint: string, body: unknown): Promise<T>;
     /** POST with a multipart body (e.g. media uploads). */
     postFormData<T>(endpoint: string, formData: FormData): Promise<T>;
+    /** DELETE with `access_token` query param applied. */
+    delete<T>(endpoint: string, opts?: {
+        params?: Record<string, string>;
+        body?: unknown;
+    }): Promise<T>;
     /** Fetch a binary resource from an absolute CDN URL. */
     fetchBinary(url: string): Promise<Buffer>;
     /** App secret proof generation is left to callers that need it (not part of the HTTP layer). */

package/dist/graph-api/client.js

@@ -29,7 +29,7 @@ export class GraphAPIClient {
     constructor(config) {
         this.accessToken = config.accessToken;
         this.appSecret = config.appSecret;
-        const apiVersion = config.apiVersion ?? 'v21.0';
+        const apiVersion = config.apiVersion ?? 'v24.0';
         const baseUrl = (config.baseUrl ?? 'https://graph.facebook.com').replace(/\/+$/, '');
         this.http = new HttpClient({
             baseUrl: `${baseUrl}/${apiVersion}`,
@@ -56,6 +56,13 @@ export class GraphAPIClient {
     async postFormData(endpoint, formData) {
         return this.http.postFormData(endpoint, formData);
     }
+    /** DELETE with `access_token` query param applied. */
+    async delete(endpoint, opts) {
+        return this.http.delete(endpoint, {
+            params: { access_token: this.accessToken, ...(opts?.params ?? {}) },
+            body: opts?.body,
+        });
+    }
     /** Fetch a binary resource from an absolute CDN URL. */
     async fetchBinary(url) {
         return this.http.fetchBinary(url);

package/dist/graph-api/errors.js

@@ -50,10 +50,14 @@ export function classifyMetaError(status, body, platform) {
     if (status === 403 || metaCode === 10 || metaCode === 200) {
         return new PermissionError(metaMessage, platform);
     }
-    // --- 24-hour window closed (Meta code 131047) ---
-    if (metaCode === 131047) {
+    // --- 24-hour window closed (WhatsApp 131047, Messenger 1545041) ---
+    if (metaCode === 131047 || metaCode === 1545041) {
         return new WindowClosedError(metaMessage, platform, new Date());
     }
+    // --- Person unavailable (Messenger 551) ---
+    if (metaCode === 551 || metaSubcode === 551) {
+        return new MessagingError(metaMessage, 'person_unavailable', platform);
+    }
     // --- Recipient not reachable (HTTP 404 or Meta code 131026) ---
     if (status === 404 || metaCode === 131026) {
         return new RecipientError(metaMessage, platform);

package/dist/instagram/client.d.ts

@@ -8,13 +8,13 @@
  * inherited. Only Instagram-specific outbound paths and inbound
  * normalization live here.
  *
- * Key quirks vs Messenger:
+ * Key differences from WhatsApp / Messenger:
  * - Base URL is `graph.instagram.com` by default.
- * - Only IMAGE attachments are supported.
- * - Send API caps at 1000 UTF-8 bytes per message — long text is split
- *   via the shared {@link ByteLimitSplitter} strategy.
- * - Send response only carries `message_id` (no `recipient_id`).
- * - Mark-as-read is a no-op (platform doesn't expose it).
+ * - Media is sent by public URL (audio, image, video, file attachments).
+ * - Message limit is 1000 bytes (UTF-8), not characters.
+ * - Send response contains `message_id` (recipient id is implicit).
+ * - Only `HUMAN_AGENT` message tag is supported (7-day window).
+ * - Ice breakers replace persistent menus.
  */
 import { type FormatConverter, type InboundMessage, type InteractiveMessage, type MediaDownload, type MediaHandle, type MediaPayload, type MediaUploadOptions, type ReactionData, type SendResult, type StatusUpdate } from '@kuralle-agents/messaging';
 import { BaseMetaClient } from '../base-client.js';
@@ -31,8 +31,6 @@ export declare class InstagramClient extends BaseMetaClient<InstagramInbound, In
     readonly platform: "instagram";
     private readonly config;
     private readonly formatConverterInstance;
-    private readonly mediaCache?;
-    private readonly mediaStrategy;
     private readonly splitter;
     constructor(config: InstagramClientConfig);
     /** Instagram-specific format converter (plain text). */
@@ -44,19 +42,20 @@ export declare class InstagramClient extends BaseMetaClient<InstagramInbound, In
      */
     sendText(to: string, text: string): Promise<SendResult>;
     /**
-     * Send an image. Instagram only supports image attachments.
-     *
-     * Uses {@link MediaStrategy} so identical Buffer uploads dedup by
-     * SHA-256 content hash (C-13.7).
+     * Send a media message by URL. Instagram messaging supports audio, image,
+     * video, and file attachments via `attachment.payload.url`.
      */
     sendMedia(to: string, media: MediaPayload): Promise<SendResult>;
     sendInteractive(to: string, msg: InteractiveMessage): Promise<SendResult>;
     sendRaw(to: string, payload: InstagramOutbound): Promise<SendResult>;
-    /** Instagram has no mark-as-read endpoint; this is a no-op. */
-    markAsRead(_messageId: string): Promise<void>;
+    /**
+     * Messenger/Instagram `mark_seen` targets the conversation partner (PSID),
+     * not a message id. Pass the user's IGSID despite the PlatformClient param name.
+     */
+    markAsRead(recipientId: string): Promise<void>;
     sendTypingIndicator(to: string): Promise<void>;
-    uploadMedia(file: Buffer | ReadableStream, options: MediaUploadOptions): Promise<MediaHandle>;
-    downloadMedia(mediaId: string): Promise<MediaDownload>;
+    uploadMedia(_file: Buffer | ReadableStream, _options: MediaUploadOptions): Promise<MediaHandle>;
+    downloadMedia(_mediaId: string): Promise<MediaDownload>;
     sendQuickReplies(to: string, text: string, replies: InstagramQuickReply[]): Promise<SendResult>;
     sendGenericTemplate(to: string, template: InstagramGenericTemplate): Promise<SendResult>;
     sendButtonTemplate(to: string, template: InstagramButtonTemplate): Promise<SendResult>;
@@ -74,6 +73,7 @@ export declare class InstagramClient extends BaseMetaClient<InstagramInbound, In
     private mapMessageType;
     private extractTextFallback;
     private extractMedia;
+    private resolveAttachmentType;
     private sendSingleText;
 }
 export {};

package/dist/instagram/client.js

@@ -8,15 +8,15 @@
  * inherited. Only Instagram-specific outbound paths and inbound
  * normalization live here.
  *
- * Key quirks vs Messenger:
+ * Key differences from WhatsApp / Messenger:
  * - Base URL is `graph.instagram.com` by default.
- * - Only IMAGE attachments are supported.
- * - Send API caps at 1000 UTF-8 bytes per message — long text is split
- *   via the shared {@link ByteLimitSplitter} strategy.
- * - Send response only carries `message_id` (no `recipient_id`).
- * - Mark-as-read is a no-op (platform doesn't expose it).
+ * - Media is sent by public URL (audio, image, video, file attachments).
+ * - Message limit is 1000 bytes (UTF-8), not characters.
+ * - Send response contains `message_id` (recipient id is implicit).
+ * - Only `HUMAN_AGENT` message tag is supported (7-day window).
+ * - Ice breakers replace persistent menus.
  */
-import { MediaError, MessagingError, FileHashDedupStrategy, UploadStrategy, } from '@kuralle-agents/messaging';
+import { MessagingError, } from '@kuralle-agents/messaging';
 import { BaseMetaClient } from '../base-client.js';
 import { GraphAPIClient } from '../graph-api/client.js';
 import { ByteLimitSplitter } from '../message-splitter.js';
@@ -40,8 +40,6 @@ export class InstagramClient extends BaseMetaClient {
     platform = 'instagram';
     config;
     formatConverterInstance;
-    mediaCache;
-    mediaStrategy;
     splitter = new ByteLimitSplitter(MAX_MESSAGE_BYTES);
     constructor(config) {
         const full = config;
@@ -58,8 +56,6 @@ export class InstagramClient extends BaseMetaClient {
         super(full, graphApi);
         this.config = full;
         this.formatConverterInstance = new InstagramFormatConverter();
-        this.mediaCache = config.mediaCache;
-        this.mediaStrategy = new FileHashDedupStrategy(new UploadStrategy((file, opts) => this.uploadMedia(file, opts)));
     }
     /** Instagram-specific format converter (plain text). */
     get formatConverter() {
@@ -82,25 +78,18 @@ export class InstagramClient extends BaseMetaClient {
         return result;
     }
     /**
-     * Send an image. Instagram only supports image attachments.
-     *
-     * Uses {@link MediaStrategy} so identical Buffer uploads dedup by
-     * SHA-256 content hash (C-13.7).
+     * Send a media message by URL. Instagram messaging supports audio, image,
+     * video, and file attachments via `attachment.payload.url`.
      */
     async sendMedia(to, media) {
-        if (media.type !== 'image') {
-            throw new MediaError(`Instagram only supports image attachments. Received: ${media.type}`, 'instagram');
+        if (typeof media.data !== 'string') {
+            throw new MessagingError('Instagram messaging sends media by public URL — pass media.data as a URL string.', 'unsupported', 'instagram');
         }
-        // Normalize stream → Buffer so dedup can hash.
-        const normalized = typeof media.data === 'string' || Buffer.isBuffer(media.data)
-            ? media
-            : { ...media, data: await streamToBuffer(media.data) };
-        const resolved = await this.mediaStrategy.resolve(normalized);
-        const url = resolved.kind === 'url' ? resolved.url : (resolved.handle.url ?? '');
+        const attachmentType = this.resolveAttachmentType(media.mimeType, media.type);
         const response = await this.graphApi.post(`${this.config.igId}/messages`, {
             recipient: { id: to },
             message: {
-                attachments: [{ type: 'image', payload: { url } }],
+                attachment: { type: attachmentType, payload: { url: media.data } },
             },
         });
         return this.toSendResult(to, response);
@@ -144,9 +133,15 @@ export class InstagramClient extends BaseMetaClient {
         });
         return this.toSendResult(to, response);
     }
-    /** Instagram has no mark-as-read endpoint; this is a no-op. */
-    async markAsRead(_messageId) {
-        // intentionally empty
+    /**
+     * Messenger/Instagram `mark_seen` targets the conversation partner (PSID),
+     * not a message id. Pass the user's IGSID despite the PlatformClient param name.
+     */
+    async markAsRead(recipientId) {
+        await this.graphApi.post(`${this.config.igId}/messages`, {
+            recipient: { id: recipientId },
+            sender_action: 'mark_seen',
+        });
     }
     async sendTypingIndicator(to) {
         await this.graphApi.post(`${this.config.igId}/messages`, {
@@ -157,26 +152,11 @@ export class InstagramClient extends BaseMetaClient {
     // =========================================================================
     // Media
     // =========================================================================
-    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 };
+    async uploadMedia(_file, _options) {
+        throw new MessagingError('Instagram messaging sends media by public URL — uploadMedia is not supported. Pass a URL via sendMedia instead.', 'unsupported', 'instagram');
     }
-    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 };
+    async downloadMedia(_mediaId) {
+        throw new MessagingError('Instagram inbound media arrives as CDN URLs in webhooks — downloadMedia is not supported.', 'unsupported', 'instagram');
     }
     // =========================================================================
     // Instagram-specific — Quick Replies
@@ -253,12 +233,14 @@ export class InstagramClient extends BaseMetaClient {
         },
         get: async () => {
             const result = await this.graphApi.get(`${this.config.igId}/messenger_profile`, { fields: 'ice_breakers' });
-            return result.data?.[0]?.ice_breakers ?? [];
+            const row = result.data?.[0];
+            if (!row?.call_to_actions)
+                return [];
+            return [{ call_to_actions: row.call_to_actions, locale: row.locale }];
         },
         delete: async () => {
-            await this.graphApi.post(`${this.config.igId}/messenger_profile`, {
-                fields: ['ice_breakers'],
-                _method: 'DELETE',
+            await this.graphApi.delete(`${this.config.igId}/messenger_profile`, {
+                body: { fields: ['ice_breakers'] },
             });
         },
     };
@@ -343,6 +325,8 @@ export class InstagramClient extends BaseMetaClient {
             image: 'image',
             video: 'video',
             audio: 'audio',
+            file: 'document',
+            document: 'document',
             sticker: 'sticker',
             interactive: 'interactive',
             postback: 'interactive',
@@ -362,19 +346,32 @@ export class InstagramClient extends BaseMetaClient {
         return undefined;
     }
     extractMedia(msg) {
-        const mediaTypes = ['image', 'video', 'audio', 'sticker'];
+        const mediaTypes = ['image', 'video', 'audio', 'document', 'sticker'];
         for (const type of mediaTypes) {
             const media = msg[type];
-            if (media && 'id' in media) {
+            if (media && ('id' in media || 'url' in media)) {
                 return {
-                    id: media.id,
+                    id: 'id' in media ? media.id : '',
                     mimeType: 'mime_type' in media ? media.mime_type : undefined,
+                    url: 'url' in media ? media.url : undefined,
                     caption: 'caption' in media ? media.caption : undefined,
+                    filename: 'filename' in media ? media.filename : undefined,
                 };
             }
         }
         return undefined;
     }
+    resolveAttachmentType(mimeType, mediaType) {
+        if (mediaType === 'document')
+            return 'file';
+        if (mimeType.startsWith('image/'))
+            return 'image';
+        if (mimeType.startsWith('video/'))
+            return 'video';
+        if (mimeType.startsWith('audio/'))
+            return 'audio';
+        return 'file';
+    }
     async sendSingleText(to, text) {
         const response = await this.graphApi.post(`${this.config.igId}/messages`, {
             recipient: { id: to },
@@ -383,17 +380,3 @@ export class InstagramClient extends BaseMetaClient {
         return this.toSendResult(to, response);
     }
 }
-// ---------------------------------------------------------------------------
-// Utility
-// ---------------------------------------------------------------------------
-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);
-}

package/dist/instagram/types.d.ts

@@ -9,9 +9,9 @@
  *
  * 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).
+ * - Media is sent by public URL (audio, image, video, file attachments).
  * - Message limit is 1000 bytes (UTF-8), not characters.
- * - Send response contains `message_id` only (no `recipient_id`).
+ * - Quick replies support text, user_phone_number, and user_email content types.
  * - Only `HUMAN_AGENT` message tag is supported (7-day window).
  * - Ice breakers replace persistent menus.
  */
@@ -61,27 +61,25 @@ export interface InstagramThreadId {
 }
 /**
  * Raw response from the Instagram Messaging API messages endpoint.
- *
- * NOTE: Unlike Messenger, Instagram does NOT return `recipient_id`
- * in the send response.
  */
 export interface InstagramSendResponse {
     /** Platform-assigned message identifier. */
     message_id: string;
+    /** Recipient IGSID (returned by some API versions). */
+    recipient_id?: string;
 }
 /**
  * A quick reply option for Instagram messages.
  *
- * Instagram only supports `content_type: "text"` quick replies.
  * Maximum 13 quick replies per message.
  */
 export interface InstagramQuickReply {
-    /** Must be `"text"`. Instagram only supports text quick replies. */
-    content_type: 'text';
-    /** Display text for the quick reply button (max 20 chars). */
-    title: string;
+    /** Quick reply content type. */
+    content_type: 'text' | 'user_phone_number' | 'user_email';
+    /** Display text for text quick replies (max 20 chars). */
+    title?: string;
     /** Payload string returned when the user taps this quick reply. */
-    payload: string;
+    payload?: string;
 }
 /**
  * A button within an Instagram template message.

package/dist/instagram/types.js

@@ -9,9 +9,9 @@
  *
  * 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).
+ * - Media is sent by public URL (audio, image, video, file attachments).
  * - Message limit is 1000 bytes (UTF-8), not characters.
- * - Send response contains `message_id` only (no `recipient_id`).
+ * - Quick replies support text, user_phone_number, and user_email content types.
  * - Only `HUMAN_AGENT` message tag is supported (7-day window).
  * - Ice breakers replace persistent menus.
  */

package/dist/messenger/client.d.ts

@@ -63,7 +63,7 @@ export declare class MessengerClient extends BaseMetaClient<MessengerInbound, Me
     sendMedia(to: string, media: MediaPayload): Promise<SendResult>;
     sendInteractive(to: string, msg: InteractiveMessage): Promise<SendResult>;
     sendRaw(to: string, payload: MessengerOutbound): Promise<SendResult>;
-    markAsRead(messageId: string): Promise<void>;
+    markAsRead(recipientId: string): Promise<void>;
     sendTypingIndicator(to: string): Promise<void>;
     sendButtonTemplate(to: string, template: ButtonTemplate): Promise<SendResult>;
     sendGenericTemplate(to: string, template: GenericTemplate): Promise<SendResult>;

package/dist/messenger/client.js

@@ -150,11 +150,12 @@ export class MessengerClient extends BaseMetaClient {
         });
         return this.toSendResult(to, response);
     }
-    async markAsRead(messageId) {
-        // Messenger's mark_seen is a sender action that requires the recipient ID,
-        // not a message ID. We accept the recipient PSID here since the platform
-        // does not support marking individual messages.
-        await this.sendSenderAction(messageId, 'mark_seen');
+    async markAsRead(recipientId) {
+        /**
+         * Messenger/Instagram `mark_seen` targets the conversation partner (PSID),
+         * not a message id. Pass the user's PSID despite the PlatformClient param name.
+         */
+        await this.sendSenderAction(recipientId, 'mark_seen');
     }
     async sendTypingIndicator(to) {
         await this.sendSenderAction(to, 'typing_on');
@@ -231,7 +232,7 @@ export class MessengerClient extends BaseMetaClient {
             return this.graphApi.post(`${this.config.pageId}/personas`, config);
         },
         delete: async (personaId) => {
-            await this.graphApi.post(personaId, { _method: 'DELETE' });
+            await this.graphApi.delete(personaId);
         },
     };
     // =========================================================================

package/dist/webhook/index.d.ts

@@ -6,4 +6,4 @@
 export { verifySignature } from './verifier.js';
 export type { VerifySignatureOptions } from './verifier.js';
 export { normalizeWebhook } from './normalizer.js';
-export type { NormalizedWebhookEvents, NormalizedMessage, NormalizedStatus, NormalizedReaction, } from './normalizer.js';
+export type { NormalizedWebhookEvents, NormalizedMessage, NormalizedStatus, NormalizedReaction, NormalizedWebhookError, WhatsAppReferral, } from './normalizer.js';

package/dist/webhook/normalizer.d.ts

@@ -20,6 +20,19 @@ export interface NormalizedWebhookEvents {
     statuses: NormalizedStatus[];
     /** Emoji reactions on existing messages. */
     reactions: NormalizedReaction[];
+    /** Account-level webhook errors (WhatsApp `value.errors`). */
+    errors: NormalizedWebhookError[];
+}
+/** Account-level error from a Meta webhook payload. */
+export interface NormalizedWebhookError {
+    code: number;
+    title?: string;
+    message?: string;
+    error_data?: {
+        details?: string;
+    };
+    href?: string;
+    phoneNumberId?: string;
 }
 /** A single inbound message extracted from the webhook payload. */
 export interface NormalizedMessage {
@@ -101,10 +114,19 @@ export interface NormalizedMessage {
             currency: string;
         }>;
     };
-    /** Quoted/replied-to message context. */
+    /** Quoted/replied-to message context (normalized: WhatsApp's raw `context.id` maps to `message_id`). */
     context?: {
         message_id: string;
         from?: string;
+        /** Set when the message was forwarded (WhatsApp). */
+        forwarded?: boolean;
+        /** Set when forwarded many times (WhatsApp). */
+        frequently_forwarded?: boolean;
+        /** Catalog product the user is asking about (WhatsApp product inquiry). */
+        referred_product?: {
+            catalog_id: string;
+            product_retailer_id: string;
+        };
     };
     /** Reaction (only set for WhatsApp reaction messages before they're split out). */
     reaction?: {
@@ -112,7 +134,23 @@ export interface NormalizedMessage {
         emoji: string;
     };
     /** Click-to-WhatsApp ad referral data. */
-    referral?: unknown;
+    referral?: WhatsAppReferral;
+}
+/** Click-to-WhatsApp ad referral object from WhatsApp webhooks. */
+export interface WhatsAppReferral {
+    source_url?: string;
+    source_id?: string;
+    source_type?: string;
+    body?: string;
+    headline?: string;
+    media_type?: string;
+    image_url?: string;
+    video_url?: string;
+    thumbnail_url?: string;
+    ctwa_clid?: string;
+    welcome_message?: {
+        text?: string;
+    };
 }
 /** A delivery status update. */
 export interface NormalizedStatus {
@@ -120,12 +158,16 @@ export interface NormalizedStatus {
     id: string;
     /** Recipient identifier. */
     recipientId: string;
-    /** Status value. */
-    status: 'sent' | 'delivered' | 'read' | 'failed';
+    /** Status value (`played` is WhatsApp voice-note playback). */
+    status: 'sent' | 'delivered' | 'read' | 'failed' | 'played' | (string & {});
     /** Unix timestamp (seconds) as a string. */
     timestamp: string;
     /** Phone number ID or page ID that sent the original message. */
     phoneNumberId: string;
+    /** Recipient type (WhatsApp). */
+    recipient_type?: string;
+    /** Opaque callback data echoed from the send request (WhatsApp). */
+    biz_opaque_callback_data?: string;
     /** Conversation metadata (WhatsApp-specific). */
     conversation?: {
         id: string;
@@ -138,13 +180,18 @@ export interface NormalizedStatus {
     pricing?: {
         billable: boolean;
         pricing_model: string;
-        category: string;
+        category: string | (string & {});
+        type?: 'regular' | 'free_customer_service' | 'free_entry_point' | (string & {});
     };
     /** Error details when `status === "failed"`. */
     errors?: Array<{
         code: number;
         title?: string;
         message?: string;
+        error_data?: {
+            details?: string;
+        };
+        href?: string;
     }>;
 }
 /** An emoji reaction on an existing message. */

package/dist/webhook/normalizer.js

@@ -41,6 +41,7 @@ export function normalizeWebhook(payload) {
         messages: [],
         statuses: [],
         reactions: [],
+        errors: [],
     };
     if (!payload || typeof payload !== 'object') {
         return result;
@@ -68,6 +69,7 @@ function normalizeWhatsAppWebhook(payload) {
         messages: [],
         statuses: [],
         reactions: [],
+        errors: [],
     };
     const entries = payload.entry ?? [];
     for (const entry of entries) {
@@ -130,12 +132,30 @@ function normalizeWhatsAppWebhook(payload) {
                     normalized.button = msg.button;
                 if (msg.order)
                     normalized.order = msg.order;
-                if (msg.context)
-                    normalized.context = msg.context;
+                if (msg.context) {
+                    // Real WhatsApp webhooks send `context.{id, from}` (plus forwarding
+                    // flags / referred_product) — normalize raw `id` to `message_id`.
+                    const referred = msg.context.referred_product;
+                    normalized.context = {
+                        message_id: msg.context.id ?? '',
+                        from: msg.context.from,
+                        forwarded: msg.context.forwarded,
+                        frequently_forwarded: msg.context.frequently_forwarded,
+                        referred_product: referred?.catalog_id && referred.product_retailer_id
+                            ? {
+                                catalog_id: referred.catalog_id,
+                                product_retailer_id: referred.product_retailer_id,
+                            }
+                            : undefined,
+                    };
+                }
                 if (msg.referral)
                     normalized.referral = msg.referral;
                 result.messages.push(normalized);
             }
+            for (const err of value.errors ?? []) {
+                result.errors.push(normalizeWebhookError(err, phoneNumberId));
+            }
             // --- Statuses ---
             for (const status of value.statuses ?? []) {
                 const normalizedStatus = {
@@ -145,6 +165,11 @@ function normalizeWhatsAppWebhook(payload) {
                     timestamp: status.timestamp ?? '',
                     phoneNumberId,
                 };
+                if (status.recipient_type)
+                    normalizedStatus.recipient_type = status.recipient_type;
+                if (status.biz_opaque_callback_data) {
+                    normalizedStatus.biz_opaque_callback_data = status.biz_opaque_callback_data;
+                }
                 if (status.conversation) {
                     normalizedStatus.conversation = status.conversation;
                 }
@@ -174,6 +199,7 @@ function normalizePageWebhook(payload) {
         messages: [],
         statuses: [],
         reactions: [],
+        errors: [],
     };
     const entries = payload.entry ?? [];
     for (const entry of entries) {
@@ -216,6 +242,13 @@ function normalizePageWebhook(payload) {
                 if (msg.reply_to?.mid) {
                     normalized.context = { message_id: msg.reply_to.mid };
                 }
+                if (msg.quick_reply?.payload) {
+                    normalized.type = 'postback';
+                    normalized.button = {
+                        text: msg.text ?? '',
+                        payload: msg.quick_reply.payload,
+                    };
+                }
                 result.messages.push(normalized);
                 continue;
             }
@@ -288,15 +321,30 @@ function resolvePageMessageType(msg) {
     }
     return 'unknown';
 }
-/** Normalise a status string to the union type, defaulting to `"sent"`. */
+/** Normalise a status string; unknown values pass through unchanged. */
 function normalizeStatusValue(raw) {
+    if (!raw)
+        return 'sent';
     switch (raw) {
         case 'sent':
         case 'delivered':
         case 'read':
         case 'failed':
+        case 'played':
             return raw;
         default:
-            return 'sent';
+            return raw;
     }
 }
+function normalizeWebhookError(err, phoneNumberId) {
+    return {
+        code: typeof err.code === 'number' ? err.code : 0,
+        title: typeof err.title === 'string' ? err.title : undefined,
+        message: typeof err.message === 'string' ? err.message : undefined,
+        error_data: err.error_data && typeof err.error_data === 'object'
+            ? err.error_data
+            : undefined,
+        href: typeof err.href === 'string' ? err.href : undefined,
+        phoneNumberId,
+    };
+}

package/dist/whatsapp/client.d.ts

@@ -25,7 +25,7 @@ import { type FormatConverter, type InboundMessage, type InteractiveMessage, typ
 import { BaseMetaClient } from '../base-client.js';
 import type { BaseMetaClientConfig } from '../base-client.js';
 import type { NormalizedMessage, NormalizedReaction, NormalizedStatus } from '../webhook/normalizer.js';
-import type { WhatsAppClientConfig, TemplateMessage, TemplateInfo, TemplateDefinition, TextOrTemplateOptions, ListMessage, ButtonMessage, CTAButtonMessage, FlowInteractiveInput, ProductMessage, ProductListMessage, CatalogMessage, AddressMessage, LocationPayload, ContactPayload, BusinessProfile, FlowDefinition, FlowInfo, FlowAssets } from './types.js';
+import type { WhatsAppClientConfig, TemplateMessage, TemplateInfo, TemplateDefinition, TemplateCreateResponse, TextOrTemplateOptions, ListMessage, ButtonMessage, CTAButtonMessage, FlowInteractiveInput, ProductMessage, ProductListMessage, CatalogMessage, AddressMessage, LocationPayload, ContactPayload, BusinessProfile, FlowDefinition, FlowInfo, FlowAssets } from './types.js';
 type WhatsAppInbound = NormalizedMessage;
 type WhatsAppOutbound = Record<string, unknown>;
 /** Internal config — base-client common fields threaded through the public config. */
@@ -61,8 +61,15 @@ export declare class WhatsAppClient extends BaseMetaClient<WhatsAppInbound, What
     sendMedia(to: string, media: MediaPayload): Promise<SendResult>;
     sendInteractive(to: string, msg: InteractiveMessage): Promise<SendResult>;
     sendRaw(to: string, payload: WhatsAppOutbound): Promise<SendResult>;
-    markAsRead(messageId: string): Promise<void>;
-    /** WhatsApp Cloud API does not support typing indicators — no-op. */
+    markAsRead(messageId: string, opts?: {
+        typing?: boolean;
+    }): Promise<void>;
+    /** Show a typing indicator for 25s (requires a recent inbound message id). */
+    sendTypingIndicatorFor(messageId: string): Promise<void>;
+    /**
+     * WhatsApp typing indicators are keyed by message ID, not recipient.
+     * Use {@link sendTypingIndicatorFor} with the inbound message id instead.
+     */
     sendTypingIndicator(_to: string): Promise<void>;
     sendTemplate(to: string, template: TemplateMessage): Promise<SendResult>;
     /**
@@ -116,8 +123,11 @@ export declare class WhatsAppClient extends BaseMetaClient<WhatsAppInbound, What
     sendContacts(to: string, contacts: ContactPayload[]): Promise<SendResult>;
     readonly templates: {
         list: (wabaId: string) => Promise<TemplateInfo[]>;
-        create: (wabaId: string, template: TemplateDefinition) => Promise<TemplateInfo>;
-        delete: (wabaId: string, name: string) => Promise<void>;
+        create: (wabaId: string, template: TemplateDefinition) => Promise<TemplateCreateResponse>;
+        delete: (wabaId: string, opts: {
+            name?: string;
+            hsm_id?: string;
+        }) => Promise<void>;
     };
     readonly phoneNumbers: {
         requestCode: (phoneNumberId: string, method: "SMS" | "VOICE", language: string) => Promise<void>;
@@ -130,6 +140,7 @@ export declare class WhatsAppClient extends BaseMetaClient<WhatsAppInbound, What
         create: (wabaId: string, flow: FlowDefinition) => Promise<FlowInfo>;
         update: (flowId: string, flow: Partial<FlowDefinition>) => Promise<FlowInfo>;
         publish: (flowId: string) => Promise<void>;
+        deprecate: (flowId: string) => Promise<void>;
         delete: (flowId: string) => Promise<void>;
         getAssets: (flowId: string) => Promise<FlowAssets>;
     };

package/dist/whatsapp/client.js

@@ -137,7 +137,7 @@ export class WhatsAppClient extends BaseMetaClient {
                 footer: msg.footer ? { text: msg.footer } : undefined,
                 flowId: msg.action.flowId,
                 flowCta: 'Continue',
-                flowToken: msg.action.flowToken ?? '',
+                flowToken: msg.action.flowToken,
                 flowAction: 'navigate',
                 flowActionPayload: msg.action.parameters,
             });
@@ -153,14 +153,25 @@ export class WhatsAppClient extends BaseMetaClient {
         });
         return this.toSendResult(to, response);
     }
-    async markAsRead(messageId) {
-        await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+    async markAsRead(messageId, opts) {
+        const body = {
             messaging_product: 'whatsapp',
             status: 'read',
             message_id: messageId,
-        });
+        };
+        if (opts?.typing) {
+            body.typing_indicator = { type: 'text' };
+        }
+        await this.graphApi.post(`${this.config.phoneNumberId}/messages`, body);
     }
-    /** WhatsApp Cloud API does not support typing indicators — no-op. */
+    /** Show a typing indicator for 25s (requires a recent inbound message id). */
+    async sendTypingIndicatorFor(messageId) {
+        await this.markAsRead(messageId, { typing: true });
+    }
+    /**
+     * WhatsApp typing indicators are keyed by message ID, not recipient.
+     * Use {@link sendTypingIndicatorFor} with the inbound message id instead.
+     */
     async sendTypingIndicator(_to) {
         // intentionally empty
     }
@@ -199,6 +210,10 @@ export class WhatsAppClient extends BaseMetaClient {
     // WhatsApp-specific — Interactive messages
     // =========================================================================
     async sendListMessage(to, list) {
+        const totalRows = list.sections.reduce((sum, section) => sum + section.rows.length, 0);
+        if (totalRows > 10) {
+            throw new MessagingError(`List message exceeds maximum of 10 rows across all sections (has ${totalRows})`, 'INVALID_LIST_MESSAGE', 'whatsapp');
+        }
         const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
             messaging_product: 'whatsapp',
             recipient_type: 'individual',
@@ -258,6 +273,16 @@ export class WhatsAppClient extends BaseMetaClient {
         return this.toSendResult(to, response);
     }
     async sendInteractiveFlow(to, flow) {
+        const parameters = {
+            flow_message_version: '3',
+            flow_id: flow.flowId,
+            flow_cta: flow.flowCta,
+            flow_action: flow.flowAction,
+            flow_action_payload: flow.flowActionPayload,
+        };
+        if (flow.flowToken) {
+            parameters.flow_token = flow.flowToken;
+        }
         const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
             messaging_product: 'whatsapp',
             recipient_type: 'individual',
@@ -269,14 +294,7 @@ export class WhatsAppClient extends BaseMetaClient {
                 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,
-                    },
+                    parameters,
                 },
             },
         });
@@ -438,17 +456,31 @@ export class WhatsAppClient extends BaseMetaClient {
     // =========================================================================
     templates = {
         list: async (wabaId) => {
-            const result = await this.graphApi.get(`${wabaId}/message_templates`);
-            return result.data.map(mapListTemplateRow);
+            const all = [];
+            let endpoint = `${wabaId}/message_templates`;
+            let extraParams;
+            for (let page = 0; page < 50; page++) {
+                const result = await this.graphApi.get(endpoint, extraParams);
+                all.push(...result.data.map(mapListTemplateRow));
+                const next = result.paging?.next;
+                if (!next)
+                    break;
+                const parsed = parseGraphPagingNext(next);
+                endpoint = parsed.endpoint;
+                extraParams = parsed.params;
+            }
+            return all;
         },
         create: async (wabaId, template) => {
             return this.graphApi.post(`${wabaId}/message_templates`, template);
         },
-        delete: async (wabaId, name) => {
-            await this.graphApi.post(`${wabaId}/message_templates`, {
-                name,
-                _method: 'DELETE',
-            });
+        delete: async (wabaId, opts) => {
+            const params = {};
+            if (opts.name)
+                params.name = opts.name;
+            if (opts.hsm_id)
+                params.hsm_id = opts.hsm_id;
+            await this.graphApi.delete(`${wabaId}/message_templates`, { params });
         },
     };
     // =========================================================================
@@ -494,8 +526,11 @@ export class WhatsAppClient extends BaseMetaClient {
         publish: async (flowId) => {
             await this.graphApi.post(`${flowId}/publish`, {});
         },
+        deprecate: async (flowId) => {
+            await this.graphApi.post(`${flowId}/deprecate`, {});
+        },
         delete: async (flowId) => {
-            await this.graphApi.post(flowId, { status: 'DEPRECATED' });
+            await this.graphApi.delete(flowId);
         },
         getAssets: async (flowId) => {
             return this.graphApi.get(`${flowId}/assets`);
@@ -562,7 +597,10 @@ export class WhatsAppClient extends BaseMetaClient {
                 }
                 : undefined,
             context: msg.context
-                ? { messageId: msg.context.message_id, from: msg.context.from }
+                ? {
+                    messageId: msg.context.message_id,
+                    from: msg.context.from,
+                }
                 : undefined,
             raw: msg,
         };
@@ -594,6 +632,7 @@ export class WhatsAppClient extends BaseMetaClient {
                 ? {
                     model: status.pricing.pricing_model,
                     category: status.pricing.category,
+                    ...(status.pricing.type ? { type: status.pricing.type } : {}),
                 }
                 : undefined,
             raw: status,
@@ -717,6 +756,17 @@ function mapListTemplateRow(raw) {
         paused,
     };
 }
+function parseGraphPagingNext(nextUrl) {
+    const url = new URL(nextUrl);
+    const parts = url.pathname.split('/').filter(Boolean);
+    const endpoint = parts.slice(1).join('/');
+    const params = {};
+    for (const [key, value] of url.searchParams.entries()) {
+        if (key !== 'access_token')
+            params[key] = value;
+    }
+    return { endpoint, params: Object.keys(params).length > 0 ? params : undefined };
+}
 // ---------------------------------------------------------------------------
 // Utility
 // ---------------------------------------------------------------------------

package/dist/whatsapp/commerce.d.ts

@@ -12,8 +12,8 @@
  * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/order
  */
 import type { InboundMessage } from '@kuralle-agents/messaging';
-import type { WhatsAppInboundOrder, WhatsAppInboundAddress } from './types.js';
-export type { ProductMessage, ProductListMessage, ProductSection, CatalogMessage, AddressMessage, WhatsAppAddressValues, WhatsAppSavedAddress, WhatsAppOrderItem, WhatsAppInboundOrder, WhatsAppInboundAddress, } from './types.js';
+import type { WhatsAppInboundOrder, WhatsAppInboundAddress, WhatsAppInboundProductInquiry } from './types.js';
+export type { ProductMessage, ProductListMessage, ProductSection, CatalogMessage, AddressMessage, WhatsAppAddressValues, WhatsAppSavedAddress, WhatsAppOrderItem, WhatsAppInboundOrder, WhatsAppInboundAddress, WhatsAppInboundProductInquiry, } from './types.js';
 /** Maximum number of sections in a multi-product message. */
 export declare const MAX_PRODUCT_LIST_SECTIONS = 10;
 /** Maximum number of products across all sections of a multi-product message. */
@@ -56,3 +56,8 @@ export declare function parseInboundOrder(message: InboundMessage): WhatsAppInbo
  *          address submission (or the payload is malformed).
  */
 export declare function parseInboundAddress(message: InboundMessage): WhatsAppInboundAddress | undefined;
+/**
+ * Extract a product inquiry from an inbound message when the user replied
+ * in the context of a catalog product message (`context.referred_product`).
+ */
+export declare function parseProductInquiry(message: InboundMessage): WhatsAppInboundProductInquiry | undefined;

package/dist/whatsapp/commerce.js

@@ -86,3 +86,20 @@ export function parseInboundAddress(message) {
         return undefined;
     }
 }
+/**
+ * Extract a product inquiry from an inbound message when the user replied
+ * in the context of a catalog product message (`context.referred_product`).
+ */
+export function parseProductInquiry(message) {
+    const raw = message.raw;
+    const referred = raw?.context?.referred_product;
+    if (!referred?.catalog_id || !referred.product_retailer_id) {
+        return undefined;
+    }
+    return {
+        catalog_id: referred.catalog_id,
+        product_retailer_id: referred.product_retailer_id,
+        context_message_id: raw?.context?.message_id,
+        context_from: raw?.context?.from,
+    };
+}

package/dist/whatsapp/index.d.ts

@@ -30,10 +30,10 @@
  * @packageDocumentation
  */
 export { WhatsAppClient, createWhatsAppClient } from './client.js';
-export type { WhatsAppClientConfig, WhatsAppThreadId, WhatsAppSendResponse, TemplateMessage, TemplateLanguage, TemplateComponent, TemplateParameter, MediaObject, ListMessage, ListSection, ListRow, ButtonMessage, ReplyButton, CTAButtonMessage, FlowInteractiveInput, ProductMessage, ProductListMessage, ProductSection, CatalogMessage, AddressMessage, WhatsAppAddressValues, WhatsAppSavedAddress, WhatsAppOrderItem, WhatsAppInboundOrder, WhatsAppInboundAddress, LocationPayload, ContactPayload, BusinessProfile, TemplateDefinition, TemplateDefinitionComponent, TemplateInfo, FlowDefinition, FlowInfo, FlowAssets, WhatsAppMediaResponse, TextOrTemplateOptions, } from './types.js';
+export type { WhatsAppClientConfig, WhatsAppThreadId, WhatsAppSendResponse, TemplateMessage, TemplateLanguage, TemplateComponent, TemplateParameter, MediaObject, ListMessage, ListSection, ListRow, ButtonMessage, ReplyButton, CTAButtonMessage, FlowInteractiveInput, ProductMessage, ProductListMessage, ProductSection, CatalogMessage, AddressMessage, WhatsAppAddressValues, WhatsAppSavedAddress, WhatsAppOrderItem, WhatsAppInboundOrder, WhatsAppInboundAddress, WhatsAppInboundProductInquiry, LocationPayload, ContactPayload, BusinessProfile, TemplateDefinition, TemplateDefinitionComponent, TemplateCreateResponse, TemplateInfo, FlowDefinition, FlowCategory, FlowInfo, FlowAssets, WhatsAppMediaResponse, TextOrTemplateOptions, } from './types.js';
 export { buildTemplateSendPayload, buildTemplatePayload, mapOutboundTemplateComponents, } from './templates.js';
 export type { TypedTemplateConfig, RawTemplateComponents, } from './templates.js';
 export { WhatsAppFormatConverter } from './format.js';
 export { splitMessage } from './split.js';
 export { generateFlowToken, buildFlowInput } from './flows.js';
-export { parseInboundOrder, parseInboundAddress, MAX_PRODUCT_LIST_SECTIONS, MAX_PRODUCT_LIST_PRODUCTS, } from './commerce.js';
+export { parseInboundOrder, parseInboundAddress, parseProductInquiry, MAX_PRODUCT_LIST_SECTIONS, MAX_PRODUCT_LIST_PRODUCTS, } from './commerce.js';

package/dist/whatsapp/index.js

@@ -40,4 +40,4 @@ export { splitMessage } from './split.js';
 // ─── Flows ──────────────────────────────────────────────────────────────
 export { generateFlowToken, buildFlowInput } from './flows.js';
 // ─── Commerce ───────────────────────────────────────────────────────────
-export { parseInboundOrder, parseInboundAddress, MAX_PRODUCT_LIST_SECTIONS, MAX_PRODUCT_LIST_PRODUCTS, } from './commerce.js';
+export { parseInboundOrder, parseInboundAddress, parseProductInquiry, MAX_PRODUCT_LIST_SECTIONS, MAX_PRODUCT_LIST_PRODUCTS, } from './commerce.js';

package/dist/whatsapp/types.d.ts

@@ -27,7 +27,7 @@ export interface WhatsAppClientConfig {
     phoneNumberId: string;
     /** Custom verify token for webhook subscription validation. */
     verifyToken: string;
-    /** Graph API version (e.g. `"v21.0"`). Default `"v21.0"`. */
+    /** Graph API version (e.g. `"v24.0"`). Default `"v24.0"`. */
     apiVersion?: string;
     /** Base URL for the Graph API. Default `"https://graph.facebook.com"`. */
     baseUrl?: string;
@@ -127,6 +127,8 @@ export interface TemplateParameter {
     payload?: string;
     /** Action payload (when `type` is `"action"`). */
     action?: Record<string, unknown>;
+    /** Parameter name for named-parameter templates. */
+    parameter_name?: string;
 }
 /**
  * A media object used within WhatsApp messages.
@@ -149,7 +151,7 @@ export interface MediaObject {
 /**
  * A list-style interactive message with expandable sections.
  *
- * Supports up to 10 sections with up to 10 rows each. The `button` text
+ * Supports up to 10 rows total across all sections. The `button` text
  * appears on the collapsed list control.
  */
 export interface ListMessage {
@@ -272,8 +274,8 @@ export interface FlowInteractiveInput {
     flowId: string;
     /** Call-to-action button text that opens the flow. */
     flowCta: string;
-    /** Unique token for this flow session. */
-    flowToken: string;
+    /** Unique token for this flow session (omit when not required). */
+    flowToken?: string;
     /** Flow action type. */
     flowAction: 'navigate' | 'data_exchange';
     /** Optional initial data for the flow. */
@@ -446,6 +448,13 @@ export interface WhatsAppInboundAddress {
     /** Address fields entered or confirmed by the user. */
     values: WhatsAppAddressValues;
 }
+/** A product inquiry from an inbound message context.referred_product. */
+export interface WhatsAppInboundProductInquiry {
+    catalog_id: string;
+    product_retailer_id: string;
+    context_message_id?: string;
+    context_from?: string;
+}
 /** A location payload for sending a map pin. */
 export interface LocationPayload {
     /** Latitude in decimal degrees. */
@@ -510,6 +519,14 @@ export interface TemplateDefinition {
     components: TemplateDefinitionComponent[];
     /** Whether Meta can auto-recategorize the template. */
     allow_category_change?: boolean;
+    /** Named vs positional parameter placeholders. */
+    parameter_format?: 'named' | 'positional';
+}
+/** Response from creating a message template. */
+export interface TemplateCreateResponse {
+    id: string;
+    status: string;
+    category: string;
 }
 /** A component within a template definition. */
 export interface TemplateDefinitionComponent {
@@ -554,11 +571,19 @@ export interface TemplateInfo {
 export interface FlowDefinition {
     /** Flow name. */
     name: string;
-    /** Flow categories. */
-    categories?: string[];
+    /** Flow categories (at least one required by the API). */
+    categories: FlowCategory[];
     /** Clone from an existing flow. */
     clone_flow_id?: string;
-}
+    /** Initial flow JSON definition. */
+    flow_json?: string;
+    /** Publish immediately after creation. */
+    publish?: boolean;
+    /** Endpoint URI for data_exchange flows. */
+    endpoint_uri?: string;
+}
+/** Valid WhatsApp Flow categories. */
+export type FlowCategory = 'SIGN_UP' | 'SIGN_IN' | 'APPOINTMENT_BOOKING' | 'LEAD_GENERATION' | 'CONTACT_US' | 'CUSTOMER_SUPPORT' | 'SURVEY' | 'OTHER';
 /** Information about an existing WhatsApp Flow. */
 export interface FlowInfo {
     /** Flow ID. */

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-messaging-meta"
   },
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Meta platform clients (WhatsApp, Messenger, Instagram) for Kuralle messaging",
   "type": "module",
   "main": "dist/index.js",
@@ -41,8 +41,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@kuralle-agents/http-client": "0.8.5",
-    "@kuralle-agents/messaging": "0.8.5"
+    "@kuralle-agents/http-client": "0.9.0",
+    "@kuralle-agents/messaging": "0.9.0"
   },
   "peerDependencies": {
     "hono": "^4.12.0"
@@ -58,9 +58,9 @@
     "redis": "^4.7.0",
     "typescript": "^5.8.2",
     "zod": "^4.0.0",
-    "@kuralle-agents/core": "0.8.5",
-    "@kuralle-agents/hono-server": "0.8.5",
-    "@kuralle-agents/engagement": "0.8.5"
+    "@kuralle-agents/engagement": "0.9.0",
+    "@kuralle-agents/core": "0.9.0",
+    "@kuralle-agents/hono-server": "0.9.0"
   },
   "scripts": {
     "prebuild": "rm -rf dist",