@kuralle-agents/messaging-meta 0.8.0 → 0.9.0

package/dist/whatsapp/commerce.js

@@ -0,0 +1,105 @@
+/**
+ * @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;
+    }
+}
+/**
+ * Extract a product inquiry from an inbound message when the user replied
+ * in the context of a catalog product message (`context.referred_product`).
+ */
+export function parseProductInquiry(message) {
+    const raw = message.raw;
+    const referred = raw?.context?.referred_product;
+    if (!referred?.catalog_id || !referred.product_retailer_id) {
+        return undefined;
+    }
+    return {
+        catalog_id: referred.catalog_id,
+        product_retailer_id: referred.product_retailer_id,
+        context_message_id: raw?.context?.message_id,
+        context_from: raw?.context?.from,
+    };
+}

package/dist/whatsapp/index.d.ts

@@ -30,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, WhatsAppInboundProductInquiry, LocationPayload, ContactPayload, BusinessProfile, TemplateDefinition, TemplateDefinitionComponent, TemplateCreateResponse, TemplateInfo, FlowDefinition, FlowCategory, FlowInfo, FlowAssets, WhatsAppMediaResponse, TextOrTemplateOptions, } from './types.js';
 export { buildTemplateSendPayload, buildTemplatePayload, mapOutboundTemplateComponents, } from './templates.js';
 export type { TypedTemplateConfig, RawTemplateComponents, } from './templates.js';
 export { WhatsAppFormatConverter } from './format.js';
 export { splitMessage } from './split.js';
 export { generateFlowToken, buildFlowInput } from './flows.js';
+export { parseInboundOrder, parseInboundAddress, parseProductInquiry, 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, parseProductInquiry, MAX_PRODUCT_LIST_SECTIONS, MAX_PRODUCT_LIST_PRODUCTS, } from './commerce.js';

package/dist/whatsapp/types.d.ts

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

package/package.json

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