@kuralle-agents/messaging-meta 0.8.0 → 0.8.5

package/README.md

@@ -12,7 +12,7 @@ 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.
+- **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.
 - **Main barrel** — `GraphAPIClient`, `BaseMetaClient`, `verifySignature`, `normalizeWebhook`, error classes.
@@ -66,6 +66,35 @@ const instagram = createInstagramClient({
 });
 ```
 
+### WhatsApp commerce
+
+Share catalog products and receive orders without leaving WhatsApp:
+
+```typescript
+import { parseInboundOrder } 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`), 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/webhook/normalizer.d.ts

@@ -83,12 +83,24 @@ export interface NormalizedMessage {
         nfm_reply?: {
             name?: string;
             response_json: string;
+            body?: string;
         };
     };
     button?: {
         text: string;
         payload: string;
     };
+    /** 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. */
     context?: {
         message_id: string;

package/dist/webhook/normalizer.js

@@ -128,6 +128,8 @@ function normalizeWhatsAppWebhook(payload) {
                     normalized.interactive = msg.interactive;
                 if (msg.button)
                     normalized.button = msg.button;
+                if (msg.order)
+                    normalized.order = msg.order;
                 if (msg.context)
                     normalized.context = msg.context;
                 if (msg.referral)

package/dist/whatsapp/client.d.ts

@@ -5,8 +5,9 @@
  *
  * Extends {@link BaseMetaClient} for shared webhook verification, payload
  * normalization, handler dispatch, and `/webhook` Hono sub-app. Templates,
- * Flows, phone-number management, CTA buttons, reactions, location, and
- * contact messages remain in this file as WhatsApp-specific surface.
+ * Flows, phone-number management, CTA buttons, commerce (product, catalog,
+ * and address messages), reactions, location, and contact messages remain
+ * in this file as WhatsApp-specific surface.
  *
  * @example
  * ```ts
@@ -24,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, LocationPayload, ContactPayload, BusinessProfile, FlowDefinition, FlowInfo, FlowAssets } from './types.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';
 type WhatsAppInbound = NormalizedMessage;
 type WhatsAppOutbound = Record<string, unknown>;
 /** Internal config — base-client common fields threaded through the public config. */
@@ -34,8 +35,8 @@ export declare function createWhatsAppClient(config: WhatsAppClientConfig): What
  * Full-featured WhatsApp Cloud API client.
  *
  * Implements the `PlatformClient` interface via {@link BaseMetaClient}.
- * Layers WhatsApp-specific capabilities (templates, Flows, reactions, CTA
- * buttons, locations, contacts) on top.
+ * Layers WhatsApp-specific capabilities (templates, Flows, commerce,
+ * reactions, CTA buttons, locations, contacts) on top.
  */
 export declare class WhatsAppClient extends BaseMetaClient<WhatsAppInbound, WhatsAppOutbound, InternalWhatsAppConfig> {
     readonly platform: "whatsapp";
@@ -76,6 +77,40 @@ export declare class WhatsAppClient extends BaseMetaClient<WhatsAppInbound, What
     sendInteractiveButtons(to: string, msg: ButtonMessage): Promise<SendResult>;
     sendCTAButton(to: string, cta: CTAButtonMessage): Promise<SendResult>;
     sendInteractiveFlow(to: string, flow: FlowInteractiveInput): Promise<SendResult>;
+    /**
+     * Send a single-product message (`interactive.type: "product"`).
+     *
+     * Displays one catalog product with a **View** button; the user can open
+     * the Product Detail Page, add to cart, and send an order. Orders arrive
+     * as inbound `type: "order"` messages — see {@link parseInboundOrder}.
+     */
+    sendProduct(to: string, product: ProductMessage): Promise<SendResult>;
+    /**
+     * Send a multi-product message (`interactive.type: "product_list"`).
+     *
+     * Displays up to {@link MAX_PRODUCT_LIST_PRODUCTS} catalog products across
+     * up to {@link MAX_PRODUCT_LIST_SECTIONS} sections. Header and body are
+     * required by the Cloud API.
+     *
+     * @throws {MessagingError} `INVALID_PRODUCT_LIST` when the section or
+     *         product limits are violated, or a section has no products.
+     */
+    sendProductList(to: string, list: ProductListMessage): Promise<SendResult>;
+    /**
+     * Send a catalog message (`interactive.type: "catalog_message"`).
+     *
+     * Displays a product thumbnail header, custom body text, and a
+     * **View catalog** button that opens the full catalog within WhatsApp.
+     */
+    sendCatalog(to: string, catalog: CatalogMessage): Promise<SendResult>;
+    /**
+     * Send an address request message (`interactive.type: "address_message"`).
+     *
+     * Country-gated by Meta — currently India-based businesses and their
+     * India customers only. The user's submission arrives as an inbound
+     * `nfm_reply` interactive message — see {@link parseInboundAddress}.
+     */
+    sendAddressRequest(to: string, address: AddressMessage): Promise<SendResult>;
     sendReaction(to: string, messageId: string, emoji: string): Promise<SendResult>;
     sendLocation(to: string, location: LocationPayload): Promise<SendResult>;
     sendContacts(to: string, contacts: ContactPayload[]): Promise<SendResult>;
@@ -103,6 +138,7 @@ export declare class WhatsAppClient extends BaseMetaClient<WhatsAppInbound, What
     protected toInboundMessage(msg: NormalizedMessage): InboundMessage;
     protected toStatusUpdate(status: NormalizedStatus): StatusUpdate;
     protected toReactionData(reaction: NormalizedReaction): ReactionData;
+    private validateProductList;
     private toSendResult;
     private mapMessageType;
     private extractTextFallback;

package/dist/whatsapp/client.js

@@ -5,8 +5,9 @@
  *
  * Extends {@link BaseMetaClient} for shared webhook verification, payload
  * normalization, handler dispatch, and `/webhook` Hono sub-app. Templates,
- * Flows, phone-number management, CTA buttons, reactions, location, and
- * contact messages remain in this file as WhatsApp-specific surface.
+ * Flows, phone-number management, CTA buttons, commerce (product, catalog,
+ * and address messages), reactions, location, and contact messages remain
+ * in this file as WhatsApp-specific surface.
  *
  * @example
  * ```ts
@@ -24,6 +25,7 @@ import { MessagingError, WindowClosedError, FileHashDedupStrategy, UploadStrateg
 import { BaseMetaClient } from '../base-client.js';
 import { GraphAPIClient } from '../graph-api/client.js';
 import { SmartSplitter } from '../message-splitter.js';
+import { MAX_PRODUCT_LIST_SECTIONS, MAX_PRODUCT_LIST_PRODUCTS, } from './commerce.js';
 import { WhatsAppFormatConverter } from './format.js';
 // ---------------------------------------------------------------------------
 // Factory
@@ -38,8 +40,8 @@ export function createWhatsAppClient(config) {
  * Full-featured WhatsApp Cloud API client.
  *
  * Implements the `PlatformClient` interface via {@link BaseMetaClient}.
- * Layers WhatsApp-specific capabilities (templates, Flows, reactions, CTA
- * buttons, locations, contacts) on top.
+ * Layers WhatsApp-specific capabilities (templates, Flows, commerce,
+ * reactions, CTA buttons, locations, contacts) on top.
  */
 export class WhatsAppClient extends BaseMetaClient {
     platform = 'whatsapp';
@@ -281,6 +283,124 @@ export class WhatsAppClient extends BaseMetaClient {
         return this.toSendResult(to, response);
     }
     // =========================================================================
+    // WhatsApp-specific — Commerce (products, catalog, addresses)
+    // =========================================================================
+    /**
+     * Send a single-product message (`interactive.type: "product"`).
+     *
+     * Displays one catalog product with a **View** button; the user can open
+     * the Product Detail Page, add to cart, and send an order. Orders arrive
+     * as inbound `type: "order"` messages — see {@link parseInboundOrder}.
+     */
+    async sendProduct(to, product) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'product',
+                body: product.body,
+                footer: product.footer,
+                action: {
+                    catalog_id: product.catalogId,
+                    product_retailer_id: product.productRetailerId,
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a multi-product message (`interactive.type: "product_list"`).
+     *
+     * Displays up to {@link MAX_PRODUCT_LIST_PRODUCTS} catalog products across
+     * up to {@link MAX_PRODUCT_LIST_SECTIONS} sections. Header and body are
+     * required by the Cloud API.
+     *
+     * @throws {MessagingError} `INVALID_PRODUCT_LIST` when the section or
+     *         product limits are violated, or a section has no products.
+     */
+    async sendProductList(to, list) {
+        this.validateProductList(list);
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'product_list',
+                header: list.header,
+                body: list.body,
+                footer: list.footer,
+                action: {
+                    catalog_id: list.catalogId,
+                    sections: list.sections.map((section) => ({
+                        title: section.title,
+                        product_items: section.productRetailerIds.map((id) => ({
+                            product_retailer_id: id,
+                        })),
+                    })),
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send a catalog message (`interactive.type: "catalog_message"`).
+     *
+     * Displays a product thumbnail header, custom body text, and a
+     * **View catalog** button that opens the full catalog within WhatsApp.
+     */
+    async sendCatalog(to, catalog) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'catalog_message',
+                body: catalog.body,
+                footer: catalog.footer,
+                action: {
+                    name: 'catalog_message',
+                    parameters: catalog.thumbnailProductRetailerId
+                        ? { thumbnail_product_retailer_id: catalog.thumbnailProductRetailerId }
+                        : undefined,
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    /**
+     * Send an address request message (`interactive.type: "address_message"`).
+     *
+     * Country-gated by Meta — currently India-based businesses and their
+     * India customers only. The user's submission arrives as an inbound
+     * `nfm_reply` interactive message — see {@link parseInboundAddress}.
+     */
+    async sendAddressRequest(to, address) {
+        const response = await this.graphApi.post(`${this.config.phoneNumberId}/messages`, {
+            messaging_product: 'whatsapp',
+            recipient_type: 'individual',
+            to,
+            type: 'interactive',
+            interactive: {
+                type: 'address_message',
+                body: address.body,
+                action: {
+                    name: 'address_message',
+                    parameters: {
+                        country: address.country,
+                        values: address.values,
+                        saved_addresses: address.savedAddresses,
+                        validation_errors: address.validationErrors,
+                    },
+                },
+            },
+        });
+        return this.toSendResult(to, response);
+    }
+    // =========================================================================
     // WhatsApp-specific — Reactions, location, contacts
     // =========================================================================
     async sendReaction(to, messageId, emoji) {
@@ -490,6 +610,19 @@ export class WhatsAppClient extends BaseMetaClient {
     // =========================================================================
     // Private — conversion helpers
     // =========================================================================
+    validateProductList(list) {
+        if (list.sections.length === 0 || list.sections.length > MAX_PRODUCT_LIST_SECTIONS) {
+            throw new MessagingError(`Product list must have between 1 and ${MAX_PRODUCT_LIST_SECTIONS} sections (has ${list.sections.length})`, 'INVALID_PRODUCT_LIST', 'whatsapp');
+        }
+        const emptySection = list.sections.find((s) => s.productRetailerIds.length === 0);
+        if (emptySection) {
+            throw new MessagingError(`Product list section "${emptySection.title}" has no products`, 'INVALID_PRODUCT_LIST', 'whatsapp');
+        }
+        const totalProducts = list.sections.reduce((sum, s) => sum + s.productRetailerIds.length, 0);
+        if (totalProducts > MAX_PRODUCT_LIST_PRODUCTS) {
+            throw new MessagingError(`Product list exceeds maximum of ${MAX_PRODUCT_LIST_PRODUCTS} products across all sections (has ${totalProducts})`, 'INVALID_PRODUCT_LIST', 'whatsapp');
+        }
+    }
     toSendResult(to, response) {
         return {
             messageId: response.messages[0]?.id ?? '',
@@ -527,6 +660,8 @@ export class WhatsAppClient extends BaseMetaClient {
             return msg.interactive.button_reply.title;
         if (msg.interactive?.list_reply)
             return msg.interactive.list_reply.title;
+        if (msg.order?.text)
+            return msg.order.text;
         if (msg.location) {
             return msg.location.name ?? `${msg.location.latitude},${msg.location.longitude}`;
         }

package/dist/whatsapp/commerce.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module whatsapp/commerce
+ *
+ * Helpers and limits for WhatsApp commerce messages.
+ *
+ * Commerce messages let you share products from a Meta catalog and receive
+ * orders directly in WhatsApp. The send methods live on the
+ * {@link WhatsAppClient} (`sendProduct`, `sendProductList`, `sendCatalog`,
+ * `sendAddressRequest`); this module provides the inbound typed accessors.
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/share-products
+ * @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';
+/** 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. */
+export declare const MAX_PRODUCT_LIST_PRODUCTS = 30;
+/**
+ * Extract the typed order from an inbound message, when the user placed an
+ * order from a catalog, single-, or multi-product message.
+ *
+ * The generic `InboundMessage` type has no `order` field, so the order
+ * travels on `message.raw` (the normalized WhatsApp webhook message). This
+ * accessor returns it typed.
+ *
+ * @param message - An inbound message from the WhatsApp client.
+ * @returns The order, or `undefined` if the message is not an order.
+ *
+ * @example
+ * ```ts
+ * client.onMessage(async (msg) => {
+ *   const order = parseInboundOrder(msg);
+ *   if (order) {
+ *     console.log(`Order against catalog ${order.catalog_id}:`);
+ *     for (const item of order.product_items) {
+ *       console.log(`  ${item.quantity}x ${item.product_retailer_id} @ ${item.item_price} ${item.currency}`);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function parseInboundOrder(message: InboundMessage): WhatsAppInboundOrder | undefined;
+/**
+ * Extract the typed address submission from an inbound message, when the
+ * user replied to an address message (`sendAddressRequest`).
+ *
+ * Address replies arrive as `interactive.type === "nfm_reply"` messages with
+ * `nfm_reply.name === "address_message"`; the address fields are JSON-encoded
+ * in `nfm_reply.response_json`.
+ *
+ * @param message - An inbound message from the WhatsApp client.
+ * @returns The parsed address, or `undefined` if the message is not an
+ *          address submission (or the payload is malformed).
+ */
+export declare function parseInboundAddress(message: InboundMessage): WhatsAppInboundAddress | undefined;

package/dist/whatsapp/commerce.js

@@ -0,0 +1,88 @@
+/**
+ * @module whatsapp/commerce
+ *
+ * Helpers and limits for WhatsApp commerce messages.
+ *
+ * Commerce messages let you share products from a Meta catalog and receive
+ * orders directly in WhatsApp. The send methods live on the
+ * {@link WhatsAppClient} (`sendProduct`, `sendProductList`, `sendCatalog`,
+ * `sendAddressRequest`); this module provides the inbound typed accessors.
+ *
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/catalogs/share-products
+ * @see https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/order
+ */
+// ---------------------------------------------------------------------------
+// Limits (per Meta Cloud API docs)
+// ---------------------------------------------------------------------------
+/** Maximum number of sections in a multi-product message. */
+export const MAX_PRODUCT_LIST_SECTIONS = 10;
+/** Maximum number of products across all sections of a multi-product message. */
+export const MAX_PRODUCT_LIST_PRODUCTS = 30;
+// ---------------------------------------------------------------------------
+// Inbound typed accessors
+// ---------------------------------------------------------------------------
+/**
+ * Extract the typed order from an inbound message, when the user placed an
+ * order from a catalog, single-, or multi-product message.
+ *
+ * The generic `InboundMessage` type has no `order` field, so the order
+ * travels on `message.raw` (the normalized WhatsApp webhook message). This
+ * accessor returns it typed.
+ *
+ * @param message - An inbound message from the WhatsApp client.
+ * @returns The order, or `undefined` if the message is not an order.
+ *
+ * @example
+ * ```ts
+ * client.onMessage(async (msg) => {
+ *   const order = parseInboundOrder(msg);
+ *   if (order) {
+ *     console.log(`Order against catalog ${order.catalog_id}:`);
+ *     for (const item of order.product_items) {
+ *       console.log(`  ${item.quantity}x ${item.product_retailer_id} @ ${item.item_price} ${item.currency}`);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function parseInboundOrder(message) {
+    const raw = message.raw;
+    const order = raw?.order;
+    if (!order || typeof order.catalog_id !== 'string' || !Array.isArray(order.product_items)) {
+        return undefined;
+    }
+    return order;
+}
+/**
+ * Extract the typed address submission from an inbound message, when the
+ * user replied to an address message (`sendAddressRequest`).
+ *
+ * Address replies arrive as `interactive.type === "nfm_reply"` messages with
+ * `nfm_reply.name === "address_message"`; the address fields are JSON-encoded
+ * in `nfm_reply.response_json`.
+ *
+ * @param message - An inbound message from the WhatsApp client.
+ * @returns The parsed address, or `undefined` if the message is not an
+ *          address submission (or the payload is malformed).
+ */
+export function parseInboundAddress(message) {
+    const raw = message.raw;
+    const nfm = raw?.interactive?.nfm_reply;
+    if (!nfm || nfm.name !== 'address_message' || !nfm.response_json) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(nfm.response_json);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed) &&
+            typeof parsed.values === 'object' &&
+            parsed.values !== null) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/whatsapp/index.d.ts

@@ -30,9 +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, 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, LocationPayload, ContactPayload, BusinessProfile, TemplateDefinition, TemplateDefinitionComponent, TemplateInfo, FlowDefinition, 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';

package/dist/whatsapp/index.js

@@ -39,3 +39,5 @@ export { WhatsAppFormatConverter } from './format.js';
 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';

package/dist/whatsapp/types.d.ts

@@ -279,6 +279,173 @@ export interface FlowInteractiveInput {
     /** Optional initial data for the flow. */
     flowActionPayload?: Record<string, unknown>;
 }
+/**
+ * A single-product interactive message (`interactive.type: "product"`).
+ *
+ * Displays one product from your catalog with a product image, title,
+ * price, and a **View** button that opens the Product Detail Page.
+ */
+export interface ProductMessage {
+    /** Optional body text (max 1024 chars). */
+    body?: {
+        text: string;
+    };
+    /** Optional footer text (max 60 chars). */
+    footer?: {
+        text: string;
+    };
+    /** Meta product catalog ID. */
+    catalogId: string;
+    /** Product SKU (labeled **Content ID** in Commerce Manager). */
+    productRetailerId: string;
+}
+/**
+ * A multi-product interactive message (`interactive.type: "product_list"`).
+ *
+ * Displays up to 30 products from your catalog, organized into up to
+ * 10 sections. Header and body are required by the Cloud API.
+ */
+export interface ProductListMessage {
+    /** Required header (text only for product lists). */
+    header: {
+        type: 'text';
+        text: string;
+    };
+    /** Body text (required, max 1024 chars). */
+    body: {
+        text: string;
+    };
+    /** Optional footer text (max 60 chars). */
+    footer?: {
+        text: string;
+    };
+    /** Meta product catalog ID. */
+    catalogId: string;
+    /** Product sections (max 10; max 30 products across all sections). */
+    sections: ProductSection[];
+}
+/** A section within a multi-product message. */
+export interface ProductSection {
+    /** Section title. */
+    title: string;
+    /** Product SKUs in this section (Content IDs in Commerce Manager). */
+    productRetailerIds: string[];
+}
+/**
+ * A catalog interactive message (`interactive.type: "catalog_message"`).
+ *
+ * Displays a product thumbnail header image, custom body text, and a
+ * **View catalog** button that opens your full catalog within WhatsApp.
+ */
+export interface CatalogMessage {
+    /** Body text (required, max 1024 chars). */
+    body: {
+        text: string;
+    };
+    /** Optional footer text (max 60 chars). */
+    footer?: {
+        text: string;
+    };
+    /**
+     * Optional product SKU whose image is used as the header thumbnail.
+     * When omitted, the first item in the catalog is used.
+     */
+    thumbnailProductRetailerId?: string;
+}
+/**
+ * Address field values used in address messages.
+ *
+ * Field names mirror the Cloud API wire format. Currently only available
+ * for India-based businesses and their India customers.
+ */
+export interface WhatsAppAddressValues {
+    /** Recipient name. */
+    name?: string;
+    /** Recipient phone number. */
+    phone_number?: string;
+    /** Pin code (India, max 6 chars). */
+    in_pin_code?: string;
+    /** Flat/house number. */
+    house_number?: string;
+    /** Floor number. */
+    floor_number?: string;
+    /** Tower number. */
+    tower_number?: string;
+    /** Building/apartment name. */
+    building_name?: string;
+    /** Street address. */
+    address?: string;
+    /** Landmark/area. */
+    landmark_area?: string;
+    /** City. */
+    city?: string;
+    /** State. */
+    state?: string;
+}
+/** A previously saved address offered to the user in an address message. */
+export interface WhatsAppSavedAddress {
+    /** Identifier returned as `saved_address_id` when the user selects it. */
+    id: string;
+    /** The saved address field values. */
+    value: WhatsAppAddressValues;
+}
+/**
+ * An address request interactive message (`interactive.type: "address_message"`).
+ *
+ * Country-gated: only available for India-based businesses and their
+ * India customers. The user's submission arrives as an inbound
+ * `interactive.type: "nfm_reply"` message — see {@link parseInboundAddress}.
+ */
+export interface AddressMessage {
+    /** Body text (required). */
+    body: {
+        text: string;
+    };
+    /** ISO country code (required by the API, e.g. `"IN"`). */
+    country: string;
+    /** Optional prefilled address field values. */
+    values?: WhatsAppAddressValues;
+    /** Optional saved addresses the user can pick instead of typing. */
+    savedAddresses?: WhatsAppSavedAddress[];
+    /**
+     * Optional per-field validation errors. WhatsApp blocks submission
+     * until the flagged fields are corrected.
+     */
+    validationErrors?: Partial<Record<keyof WhatsAppAddressValues, string>>;
+}
+/** A line item in an inbound WhatsApp order (wire format). */
+export interface WhatsAppOrderItem {
+    /** Product SKU (Content ID in Commerce Manager). */
+    product_retailer_id: string;
+    /** Quantity ordered. */
+    quantity: number;
+    /** Unit price of the item. */
+    item_price: number;
+    /** Catalog currency code (e.g. `"USD"`). */
+    currency: string;
+}
+/**
+ * An inbound order placed by a user from a catalog, single-, or
+ * multi-product message (webhook message `type: "order"`).
+ */
+export interface WhatsAppInboundOrder {
+    /** Meta product catalog ID the order was placed against. */
+    catalog_id: string;
+    /** Text accompanying the order. */
+    text?: string;
+    /** Ordered line items. */
+    product_items: WhatsAppOrderItem[];
+}
+/**
+ * A parsed inbound address submission (the `nfm_reply.response_json`
+ * of an address message reply).
+ */
+export interface WhatsAppInboundAddress {
+    /** ID of the saved address the user selected, when applicable. */
+    saved_address_id?: string;
+    /** Address fields entered or confirmed by the user. */
+    values: WhatsAppAddressValues;
+}
 /** A location payload for sending a map pin. */
 export interface LocationPayload {
     /** Latitude in decimal degrees. */

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-messaging-meta"
   },
-  "version": "0.8.0",
+  "version": "0.8.5",
   "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.0",
-    "@kuralle-agents/messaging": "0.8.0"
+    "@kuralle-agents/http-client": "0.8.5",
+    "@kuralle-agents/messaging": "0.8.5"
   },
   "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.0",
-    "@kuralle-agents/engagement": "0.8.0",
-    "@kuralle-agents/hono-server": "0.8.0"
+    "@kuralle-agents/core": "0.8.5",
+    "@kuralle-agents/hono-server": "0.8.5",
+    "@kuralle-agents/engagement": "0.8.5"
   },
   "scripts": {
     "prebuild": "rm -rf dist",