@kuralle-agents/messaging-meta 0.8.0 → 0.9.0

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) {
@@ -128,12 +130,32 @@ function normalizeWhatsAppWebhook(payload) {
                     normalized.interactive = msg.interactive;
                 if (msg.button)
                     normalized.button = msg.button;
-                if (msg.context)
-                    normalized.context = msg.context;
+                if (msg.order)
+                    normalized.order = msg.order;
+                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 = {
@@ -143,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;
                 }
@@ -172,6 +199,7 @@ function normalizePageWebhook(payload) {
         messages: [],
         statuses: [],
         reactions: [],
+        errors: [],
     };
     const entries = payload.entry ?? [];
     for (const entry of entries) {
@@ -214,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;
             }
@@ -286,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

@@ -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, 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. */
@@ -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";
@@ -60,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>;
     /**
@@ -76,13 +84,50 @@ 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>;
     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>;
@@ -95,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>;
     };
@@ -103,6 +149,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';
@@ -135,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,
             });
@@ -151,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
     }
@@ -197,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',
@@ -256,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',
@@ -267,13 +294,124 @@ export class WhatsAppClient extends BaseMetaClient {
                 footer: flow.footer,
                 action: {
                     name: 'flow',
+                    parameters,
+                },
+            },
+        });
+        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: {
-                        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,
+                        country: address.country,
+                        values: address.values,
+                        saved_addresses: address.savedAddresses,
+                        validation_errors: address.validationErrors,
                     },
                 },
             },
@@ -318,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 });
         },
     };
     // =========================================================================
@@ -374,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`);
@@ -442,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,
         };
@@ -474,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,
@@ -490,6 +649,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 +699,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}`;
         }
@@ -582,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

@@ -0,0 +1,63 @@
+/**
+ * @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, 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. */
+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;
+/**
+ * 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;