@kuralle-agents/messaging-meta 0.8.0 → 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.
-- **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).
 
@@ -66,6 +66,35 @@ const instagram = createInstagramClient({
 });
 ```
 
+### WhatsApp commerce
+
+Share catalog products and receive orders without leaving WhatsApp:
+
+```typescript
+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' } });
+await whatsapp.sendProductList(to, {
+  header: { type: 'text', text: 'Bestsellers' },
+  body: { text: 'Pick your favorites' },
+  catalogId,
+  sections: [{ title: 'Cakes', productRetailerIds: ['sku-1', 'sku-2'] }],
+});
+await whatsapp.sendCatalog(to, { body: { text: 'Browse our catalog' } });
+await whatsapp.sendAddressRequest(to, { body: { text: 'Where should we deliver?' }, country: 'IN' });
+
+// Inbound orders (webhook message type "order") arrive typed:
+whatsapp.onMessage(async (msg) => {
+  const order = parseInboundOrder(msg);
+  if (order) {
+    // order.catalog_id, order.product_items[].{product_retailer_id, quantity, item_price, currency}
+  }
+});
+```
+
+Address submissions arrive as `nfm_reply` interactive messages — use `parseInboundAddress(msg)` for a typed accessor. Address messages are country-gated by Meta (currently India only).
+
 ### Webhook verification without a client
 
 ```typescript
@@ -81,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, 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 {
@@ -83,16 +96,37 @@ export interface NormalizedMessage {
         nfm_reply?: {
             name?: string;
             response_json: string;
+            body?: string;
         };
     };
     button?: {
         text: string;
         payload: string;
     };
-    /** Quoted/replied-to message context. */
+    /** Order placed from a catalog, single-, or multi-product message. */
+    order?: {
+        catalog_id: string;
+        text?: string;
+        product_items: Array<{
+            product_retailer_id: string;
+            quantity: number;
+            item_price: number;
+            currency: string;
+        }>;
+    };
+    /** 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?: {
@@ -100,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 {
@@ -108,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;
@@ -126,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. */