@semboja/connect 0.2.2 → 0.3.0

package/dist/index.d.mts

@@ -310,7 +310,7 @@ interface InteractiveListSection {
     }>;
 }
 interface InteractiveMessage {
-    type: 'button' | 'list' | 'product' | 'product_list';
+    type: 'button' | 'list' | 'product' | 'product_list' | 'flow';
     header?: {
         type: 'text' | 'image' | 'video' | 'document';
         text?: string;
@@ -325,17 +325,76 @@ interface InteractiveMessage {
         text: string;
     };
     action: {
+        /** Button text for list messages */
         button?: string;
+        /** Reply buttons (for button type) */
         buttons?: InteractiveButton[];
+        /** List sections (for list type) */
         sections?: InteractiveListSection[];
+        /** Flow action name (for flow type) */
+        name?: 'flow';
+        /** Flow parameters (for flow type) */
+        parameters?: FlowActionParameters;
     };
 }
+/**
+ * Parameters for WhatsApp Flow interactive messages
+ */
+interface FlowActionParameters {
+    /** Flow message version (must be "3") */
+    flow_message_version: '3';
+    /** The Flow ID from WhatsApp Business Manager */
+    flow_id: string;
+    /** Text displayed on the CTA button (max ~30 chars, no emoji) */
+    flow_cta: string;
+    /** Token to identify this flow session (returned in nfm_reply webhook) */
+    flow_token?: string;
+    /** How the flow starts: navigate to a screen or call the endpoint */
+    flow_action?: 'navigate' | 'data_exchange';
+    /** Initial screen and data when flow_action is 'navigate' */
+    flow_action_payload?: {
+        /** Screen name to navigate to */
+        screen: string;
+        /** Data to pass to the screen */
+        data?: Record<string, unknown>;
+    };
+    /** Use 'draft' to test unpublished flows */
+    mode?: 'draft' | 'published';
+}
 interface SendInteractiveOptions extends SendMessageOptions {
     /** Interactive message configuration */
     interactive: InteractiveMessage;
     /** Message ID to reply to */
     replyTo?: string;
 }
+/**
+ * Options for sending a WhatsApp Flow message.
+ * Convenience type that enforces flow-specific interactive message shape.
+ */
+interface SendFlowOptions extends SendMessageOptions {
+    /** Flow message body text */
+    body: string;
+    /** Optional header text */
+    header?: string;
+    /** Optional footer text */
+    footer?: string;
+    /** The Flow ID from WhatsApp Business Manager */
+    flowId: string;
+    /** Text displayed on the CTA button (max ~30 chars, no emoji) */
+    flowCta: string;
+    /** Token to identify this flow session (returned in nfm_reply webhook) */
+    flowToken?: string;
+    /** How the flow starts: navigate to a screen or call the endpoint (default: navigate) */
+    flowAction?: 'navigate' | 'data_exchange';
+    /** Initial screen name (required when flowAction is 'navigate') */
+    screen?: string;
+    /** Initial data to pass to the screen */
+    screenData?: Record<string, unknown>;
+    /** Use 'draft' to test unpublished flows (default: published) */
+    mode?: 'draft' | 'published';
+    /** Message ID to reply to */
+    replyTo?: string;
+}
 interface MessageContact {
     input: string;
     wa_id: string;
@@ -370,18 +429,18 @@ interface MetaPhoneNumberInfo {
     id: string;
     verified_name: string;
     display_phone_number: string;
-    quality_rating: "GREEN" | "YELLOW" | "RED" | "UNKNOWN";
-    code_verification_status: "VERIFIED" | "NOT_VERIFIED" | "EXPIRED";
+    quality_rating: 'GREEN' | 'YELLOW' | 'RED' | 'UNKNOWN';
+    code_verification_status: 'VERIFIED' | 'NOT_VERIFIED' | 'EXPIRED';
     is_official_business_account: boolean;
     is_pin_enabled: boolean;
-    name_status: "APPROVED" | "PENDING" | "DECLINED" | "NONE";
-    new_name_status?: "APPROVED" | "PENDING" | "DECLINED" | "NONE";
+    name_status: 'APPROVED' | 'PENDING' | 'DECLINED' | 'NONE';
+    new_name_status?: 'APPROVED' | 'PENDING' | 'DECLINED' | 'NONE';
     messaging_limit_tier?: string;
     platform_type?: string;
     throughput?: {
         level: string;
     };
-    account_mode?: "LIVE" | "SANDBOX";
+    account_mode?: 'LIVE' | 'SANDBOX';
 }
 /** Business profile from Meta Graph API */
 interface MetaBusinessProfile {
@@ -432,6 +491,43 @@ interface VerifyWebhookOptions {
     /** Your webhook secret */
     secret: string;
 }
+/**
+ * Interactive reply data from an incoming webhook message.
+ * Covers button_reply, list_reply, and nfm_reply (WhatsApp Flows).
+ */
+interface WebhookInteractiveReply {
+    type: 'button_reply' | 'list_reply' | 'nfm_reply';
+    /** Button reply data (when type is 'button_reply') */
+    button_reply?: {
+        id: string;
+        title: string;
+    };
+    /** List reply data (when type is 'list_reply') */
+    list_reply?: {
+        id: string;
+        title: string;
+        description?: string;
+    };
+    /** Flow reply data (when type is 'nfm_reply') */
+    nfm_reply?: {
+        /** Stringified JSON containing flow_token and all collected data */
+        response_json: string;
+        /** Display body text (usually "Sent") */
+        body: string;
+        /** Flow name identifier */
+        name: string;
+    };
+}
+/**
+ * Parsed flow response data from an nfm_reply webhook message.
+ * The response_json string parsed into a typed object.
+ */
+interface FlowResponseData {
+    /** The flow_token that was passed when sending the flow */
+    flow_token: string;
+    /** All key-value pairs collected by the flow screens */
+    [key: string]: unknown;
+}
 
 /**
  * Messages API resource
@@ -673,6 +769,42 @@ declare class Messages {
      * ```
      */
     sendContacts(options: SendContactsOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send a WhatsApp Flow message
+     *
+     * WhatsApp Flows allow you to create structured, multi-screen forms
+     * that run entirely inside WhatsApp. The flow must be registered via
+     * the Meta Business Manager before sending.
+     *
+     * @param options - Flow message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * // Send a flow with navigate action (most common)
+     * await client.messages.sendFlow({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   body: 'Please fill in your company details',
+     *   flowId: '1234567890',
+     *   flowCta: 'Start Form',
+     *   flowToken: 'session_abc123',
+     *   flowAction: 'navigate',
+     *   screen: 'COMPANY_NAME',
+     * });
+     *
+     * // Send a draft flow for testing
+     * await client.messages.sendFlow({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   body: 'Test flow',
+     *   flowId: '1234567890',
+     *   flowCta: 'Open',
+     *   mode: 'draft',
+     * });
+     * ```
+     */
+    sendFlow(options: SendFlowOptions): Promise<ApiResponse<MessageResponseData>>;
     /**
      * Mark a message as read
      *
@@ -996,6 +1128,29 @@ declare function verifyWebhookSignature(options: VerifyWebhookOptions): boolean;
  * @returns Parsed webhook event
  */
 declare function parseWebhookPayload<T = unknown>(payload: string | object): T;
+/**
+ * Parse the response_json string from a WhatsApp Flow nfm_reply webhook.
+ *
+ * When a user completes a WhatsApp Flow, the webhook delivers an interactive
+ * message with type 'nfm_reply'. The `response_json` field contains a stringified
+ * JSON object with the `flow_token` and all data collected by the flow screens.
+ *
+ * @param responseJson - The response_json string from nfm_reply
+ * @returns Parsed flow response data including flow_token and collected fields
+ *
+ * @example
+ * ```typescript
+ * import { parseFlowResponse } from '@semboja/connect';
+ *
+ * // In your webhook handler:
+ * if (message.interactive?.type === 'nfm_reply') {
+ *   const flowData = parseFlowResponse(message.interactive.nfm_reply.response_json);
+ *   console.log('Flow token:', flowData.flow_token);
+ *   console.log('Company name:', flowData.company_name);
+ * }
+ * ```
+ */
+declare function parseFlowResponse(responseJson: string): FlowResponseData;
 
 /**
  * Base error class for all Semboja API errors
@@ -1080,4 +1235,4 @@ declare class NetworkError extends SembojaError {
  * @packageDocumentation
  */
 
-export { type ApiErrorResponse, type ApiResponse, AuthenticationError, type ClientOptions, type Contact, type ContactAddress, type ContactEmail, type ContactName, type ContactOrg, type ContactPhone, type ContactUrl, type InteractiveButton, type InteractiveListSection, type InteractiveMessage, type ListTemplatesOptions, type LocationObject, type MarkAsReadOptions, type MarkAsReadResponseData, type MediaObject, type MessageContact, type MessageResponseData, type MessageResult, type MessageType, type MetaBusinessProfile, type MetaPhoneNumberInfo, NetworkError, NotFoundError, type PhoneNumber, type PhoneNumberProfile, RateLimitError, SembojaClient, SembojaError, type SendAudioOptions, type SendContactsOptions, type SendDocumentOptions, type SendImageOptions, type SendInteractiveOptions, type SendLocationOptions, type SendMessageOptions, type SendReactionOptions, type SendStickerOptions, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, ServerError, type StickerObject, type Template, type TemplateComponent, type TemplateInfo, type TemplateLanguage, type TemplateParameter, type TemplateStatus, type TriggerWebhookOptions, type UsageData, type UsageMessages, type UsagePeriod, ValidationError, type VerifyWebhookOptions, SembojaClient as default, parseWebhookPayload, verifyWebhookSignature };
+export { type ApiErrorResponse, type ApiResponse, AuthenticationError, type ClientOptions, type Contact, type ContactAddress, type ContactEmail, type ContactName, type ContactOrg, type ContactPhone, type ContactUrl, type FlowActionParameters, type FlowResponseData, type InteractiveButton, type InteractiveListSection, type InteractiveMessage, type ListTemplatesOptions, type LocationObject, type MarkAsReadOptions, type MarkAsReadResponseData, type MediaObject, type MessageContact, type MessageResponseData, type MessageResult, type MessageType, type MetaBusinessProfile, type MetaPhoneNumberInfo, NetworkError, NotFoundError, type PhoneNumber, type PhoneNumberProfile, RateLimitError, SembojaClient, SembojaError, type SendAudioOptions, type SendContactsOptions, type SendDocumentOptions, type SendFlowOptions, type SendImageOptions, type SendInteractiveOptions, type SendLocationOptions, type SendMessageOptions, type SendReactionOptions, type SendStickerOptions, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, ServerError, type StickerObject, type Template, type TemplateComponent, type TemplateInfo, type TemplateLanguage, type TemplateParameter, type TemplateStatus, type TriggerWebhookOptions, type UsageData, type UsageMessages, type UsagePeriod, ValidationError, type VerifyWebhookOptions, type WebhookInteractiveReply, SembojaClient as default, parseFlowResponse, parseWebhookPayload, verifyWebhookSignature };

package/dist/index.d.ts

@@ -310,7 +310,7 @@ interface InteractiveListSection {
     }>;
 }
 interface InteractiveMessage {
-    type: 'button' | 'list' | 'product' | 'product_list';
+    type: 'button' | 'list' | 'product' | 'product_list' | 'flow';
     header?: {
         type: 'text' | 'image' | 'video' | 'document';
         text?: string;
@@ -325,17 +325,76 @@ interface InteractiveMessage {
         text: string;
     };
     action: {
+        /** Button text for list messages */
         button?: string;
+        /** Reply buttons (for button type) */
         buttons?: InteractiveButton[];
+        /** List sections (for list type) */
         sections?: InteractiveListSection[];
+        /** Flow action name (for flow type) */
+        name?: 'flow';
+        /** Flow parameters (for flow type) */
+        parameters?: FlowActionParameters;
     };
 }
+/**
+ * Parameters for WhatsApp Flow interactive messages
+ */
+interface FlowActionParameters {
+    /** Flow message version (must be "3") */
+    flow_message_version: '3';
+    /** The Flow ID from WhatsApp Business Manager */
+    flow_id: string;
+    /** Text displayed on the CTA button (max ~30 chars, no emoji) */
+    flow_cta: string;
+    /** Token to identify this flow session (returned in nfm_reply webhook) */
+    flow_token?: string;
+    /** How the flow starts: navigate to a screen or call the endpoint */
+    flow_action?: 'navigate' | 'data_exchange';
+    /** Initial screen and data when flow_action is 'navigate' */
+    flow_action_payload?: {
+        /** Screen name to navigate to */
+        screen: string;
+        /** Data to pass to the screen */
+        data?: Record<string, unknown>;
+    };
+    /** Use 'draft' to test unpublished flows */
+    mode?: 'draft' | 'published';
+}
 interface SendInteractiveOptions extends SendMessageOptions {
     /** Interactive message configuration */
     interactive: InteractiveMessage;
     /** Message ID to reply to */
     replyTo?: string;
 }
+/**
+ * Options for sending a WhatsApp Flow message.
+ * Convenience type that enforces flow-specific interactive message shape.
+ */
+interface SendFlowOptions extends SendMessageOptions {
+    /** Flow message body text */
+    body: string;
+    /** Optional header text */
+    header?: string;
+    /** Optional footer text */
+    footer?: string;
+    /** The Flow ID from WhatsApp Business Manager */
+    flowId: string;
+    /** Text displayed on the CTA button (max ~30 chars, no emoji) */
+    flowCta: string;
+    /** Token to identify this flow session (returned in nfm_reply webhook) */
+    flowToken?: string;
+    /** How the flow starts: navigate to a screen or call the endpoint (default: navigate) */
+    flowAction?: 'navigate' | 'data_exchange';
+    /** Initial screen name (required when flowAction is 'navigate') */
+    screen?: string;
+    /** Initial data to pass to the screen */
+    screenData?: Record<string, unknown>;
+    /** Use 'draft' to test unpublished flows (default: published) */
+    mode?: 'draft' | 'published';
+    /** Message ID to reply to */
+    replyTo?: string;
+}
 interface MessageContact {
     input: string;
     wa_id: string;
@@ -370,18 +429,18 @@ interface MetaPhoneNumberInfo {
     id: string;
     verified_name: string;
     display_phone_number: string;
-    quality_rating: "GREEN" | "YELLOW" | "RED" | "UNKNOWN";
-    code_verification_status: "VERIFIED" | "NOT_VERIFIED" | "EXPIRED";
+    quality_rating: 'GREEN' | 'YELLOW' | 'RED' | 'UNKNOWN';
+    code_verification_status: 'VERIFIED' | 'NOT_VERIFIED' | 'EXPIRED';
     is_official_business_account: boolean;
     is_pin_enabled: boolean;
-    name_status: "APPROVED" | "PENDING" | "DECLINED" | "NONE";
-    new_name_status?: "APPROVED" | "PENDING" | "DECLINED" | "NONE";
+    name_status: 'APPROVED' | 'PENDING' | 'DECLINED' | 'NONE';
+    new_name_status?: 'APPROVED' | 'PENDING' | 'DECLINED' | 'NONE';
     messaging_limit_tier?: string;
     platform_type?: string;
     throughput?: {
         level: string;
     };
-    account_mode?: "LIVE" | "SANDBOX";
+    account_mode?: 'LIVE' | 'SANDBOX';
 }
 /** Business profile from Meta Graph API */
 interface MetaBusinessProfile {
@@ -432,6 +491,43 @@ interface VerifyWebhookOptions {
     /** Your webhook secret */
     secret: string;
 }
+/**
+ * Interactive reply data from an incoming webhook message.
+ * Covers button_reply, list_reply, and nfm_reply (WhatsApp Flows).
+ */
+interface WebhookInteractiveReply {
+    type: 'button_reply' | 'list_reply' | 'nfm_reply';
+    /** Button reply data (when type is 'button_reply') */
+    button_reply?: {
+        id: string;
+        title: string;
+    };
+    /** List reply data (when type is 'list_reply') */
+    list_reply?: {
+        id: string;
+        title: string;
+        description?: string;
+    };
+    /** Flow reply data (when type is 'nfm_reply') */
+    nfm_reply?: {
+        /** Stringified JSON containing flow_token and all collected data */
+        response_json: string;
+        /** Display body text (usually "Sent") */
+        body: string;
+        /** Flow name identifier */
+        name: string;
+    };
+}
+/**
+ * Parsed flow response data from an nfm_reply webhook message.
+ * The response_json string parsed into a typed object.
+ */
+interface FlowResponseData {
+    /** The flow_token that was passed when sending the flow */
+    flow_token: string;
+    /** All key-value pairs collected by the flow screens */
+    [key: string]: unknown;
+}
 
 /**
  * Messages API resource
@@ -673,6 +769,42 @@ declare class Messages {
      * ```
      */
     sendContacts(options: SendContactsOptions): Promise<ApiResponse<MessageResponseData>>;
+    /**
+     * Send a WhatsApp Flow message
+     *
+     * WhatsApp Flows allow you to create structured, multi-screen forms
+     * that run entirely inside WhatsApp. The flow must be registered via
+     * the Meta Business Manager before sending.
+     *
+     * @param options - Flow message options
+     * @returns Message response with message ID
+     *
+     * @example
+     * ```typescript
+     * // Send a flow with navigate action (most common)
+     * await client.messages.sendFlow({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   body: 'Please fill in your company details',
+     *   flowId: '1234567890',
+     *   flowCta: 'Start Form',
+     *   flowToken: 'session_abc123',
+     *   flowAction: 'navigate',
+     *   screen: 'COMPANY_NAME',
+     * });
+     *
+     * // Send a draft flow for testing
+     * await client.messages.sendFlow({
+     *   phoneNumberId: '123456789',
+     *   to: '+6281234567890',
+     *   body: 'Test flow',
+     *   flowId: '1234567890',
+     *   flowCta: 'Open',
+     *   mode: 'draft',
+     * });
+     * ```
+     */
+    sendFlow(options: SendFlowOptions): Promise<ApiResponse<MessageResponseData>>;
     /**
      * Mark a message as read
      *
@@ -996,6 +1128,29 @@ declare function verifyWebhookSignature(options: VerifyWebhookOptions): boolean;
  * @returns Parsed webhook event
  */
 declare function parseWebhookPayload<T = unknown>(payload: string | object): T;
+/**
+ * Parse the response_json string from a WhatsApp Flow nfm_reply webhook.
+ *
+ * When a user completes a WhatsApp Flow, the webhook delivers an interactive
+ * message with type 'nfm_reply'. The `response_json` field contains a stringified
+ * JSON object with the `flow_token` and all data collected by the flow screens.
+ *
+ * @param responseJson - The response_json string from nfm_reply
+ * @returns Parsed flow response data including flow_token and collected fields
+ *
+ * @example
+ * ```typescript
+ * import { parseFlowResponse } from '@semboja/connect';
+ *
+ * // In your webhook handler:
+ * if (message.interactive?.type === 'nfm_reply') {
+ *   const flowData = parseFlowResponse(message.interactive.nfm_reply.response_json);
+ *   console.log('Flow token:', flowData.flow_token);
+ *   console.log('Company name:', flowData.company_name);
+ * }
+ * ```
+ */
+declare function parseFlowResponse(responseJson: string): FlowResponseData;
 
 /**
  * Base error class for all Semboja API errors
@@ -1080,4 +1235,4 @@ declare class NetworkError extends SembojaError {
  * @packageDocumentation
  */
 
-export { type ApiErrorResponse, type ApiResponse, AuthenticationError, type ClientOptions, type Contact, type ContactAddress, type ContactEmail, type ContactName, type ContactOrg, type ContactPhone, type ContactUrl, type InteractiveButton, type InteractiveListSection, type InteractiveMessage, type ListTemplatesOptions, type LocationObject, type MarkAsReadOptions, type MarkAsReadResponseData, type MediaObject, type MessageContact, type MessageResponseData, type MessageResult, type MessageType, type MetaBusinessProfile, type MetaPhoneNumberInfo, NetworkError, NotFoundError, type PhoneNumber, type PhoneNumberProfile, RateLimitError, SembojaClient, SembojaError, type SendAudioOptions, type SendContactsOptions, type SendDocumentOptions, type SendImageOptions, type SendInteractiveOptions, type SendLocationOptions, type SendMessageOptions, type SendReactionOptions, type SendStickerOptions, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, ServerError, type StickerObject, type Template, type TemplateComponent, type TemplateInfo, type TemplateLanguage, type TemplateParameter, type TemplateStatus, type TriggerWebhookOptions, type UsageData, type UsageMessages, type UsagePeriod, ValidationError, type VerifyWebhookOptions, SembojaClient as default, parseWebhookPayload, verifyWebhookSignature };
+export { type ApiErrorResponse, type ApiResponse, AuthenticationError, type ClientOptions, type Contact, type ContactAddress, type ContactEmail, type ContactName, type ContactOrg, type ContactPhone, type ContactUrl, type FlowActionParameters, type FlowResponseData, type InteractiveButton, type InteractiveListSection, type InteractiveMessage, type ListTemplatesOptions, type LocationObject, type MarkAsReadOptions, type MarkAsReadResponseData, type MediaObject, type MessageContact, type MessageResponseData, type MessageResult, type MessageType, type MetaBusinessProfile, type MetaPhoneNumberInfo, NetworkError, NotFoundError, type PhoneNumber, type PhoneNumberProfile, RateLimitError, SembojaClient, SembojaError, type SendAudioOptions, type SendContactsOptions, type SendDocumentOptions, type SendFlowOptions, type SendImageOptions, type SendInteractiveOptions, type SendLocationOptions, type SendMessageOptions, type SendReactionOptions, type SendStickerOptions, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, ServerError, type StickerObject, type Template, type TemplateComponent, type TemplateInfo, type TemplateLanguage, type TemplateParameter, type TemplateStatus, type TriggerWebhookOptions, type UsageData, type UsageMessages, type UsagePeriod, ValidationError, type VerifyWebhookOptions, type WebhookInteractiveReply, SembojaClient as default, parseFlowResponse, parseWebhookPayload, verifyWebhookSignature };