meta-cloud-api 1.0.0 → 1.0.2

package/dist/WebhookProcessor-BXYunz4N.d.ts

@@ -0,0 +1,707 @@
+import { a as FlowEndpointRequest, F as FlowTypeEnum } from './common-lV0NsO7t.js';
+import { WabaConfigType, WhatsAppConfig } from './types/config.js';
+import { M as MessageTypesEnum } from './enums-BZd9T2ul.js';
+import { W as WhatsApp } from './WhatsApp-pTZPQm81.js';
+
+interface WebhookContact {
+    /**
+     * WhatsApp ID of the contact. Business can respond to this contact using this ID.
+     */
+    wa_id: string;
+    /**
+     *  Additional unique, alphanumeric identifier for a WhatsApp user
+     */
+    user_id?: string;
+    /**
+     * Profile of Whatsapp user
+     */
+    profile: {
+        /**
+         * The display name of the contact
+         */
+        name: string;
+    };
+}
+/**
+ * Base message interface with common properties
+ */
+interface BaseMessage {
+    id: string;
+    from: string;
+    timestamp: string;
+    type: MessageTypesEnum;
+    /**
+     * Context object, included when a user replies or interacts
+     */
+    context?: {
+        /**
+         * ID of the message
+         */
+        id?: string;
+        /**
+         * ID of the sender
+         */
+        from?: string;
+        /**
+         * ID of the message being replied to or interacted with
+         */
+        message_id: string;
+        /**
+         * ID of the forwarded message, if applicable
+         */
+        forwarded?: boolean;
+        /**
+         * Frequently forwarded status
+         */
+        frequently_forwarded?: boolean;
+        /**
+         * Original message information if the message was referred
+         */
+        referred_product?: {
+            /**
+             * Catalog ID
+             */
+            catalog_id: string;
+            /**
+             * Product ID
+             */
+            product_retailer_id: string;
+        };
+    };
+    /**
+     * Errors array, if the message had errors
+     */
+    errors?: Array<{
+        /**
+         * Error code
+         */
+        code: number;
+        /**
+         * Error title
+         */
+        title: string;
+        /**
+         * Error message
+         */
+        message: string;
+        /**
+         * Error details object
+         */
+        error_data?: {
+            /**
+             * Describes the error details
+             */
+            details: string;
+        };
+    }>;
+}
+/**
+ * Text message interface
+ */
+interface TextMessage extends BaseMessage {
+    type: MessageTypesEnum.Text;
+    text: {
+        /**
+         * The text content of the message
+         */
+        body: string;
+        preview_url?: boolean;
+    };
+}
+/**
+ * Image message interface
+ */
+interface ImageMessage extends BaseMessage {
+    type: MessageTypesEnum.Image;
+    image: {
+        /**
+         * The image caption (if provided)
+         */
+        caption?: string;
+        /**
+         * The SHA256 hash of the image
+         */
+        sha256?: string;
+        /**
+         * The ID for the image
+         */
+        id: string;
+        /**
+         * The MIME type of the image
+         */
+        mime_type: string;
+    };
+}
+/**
+ * Video message interface
+ */
+interface VideoMessage extends BaseMessage {
+    type: MessageTypesEnum.Video;
+    video: {
+        /**
+         * The video caption (if provided)
+         */
+        caption?: string;
+        /**
+         * The SHA256 hash of the video
+         */
+        sha256?: string;
+        /**
+         * The ID for the video
+         */
+        id: string;
+        /**
+         * The MIME type of the video
+         */
+        mime_type: string;
+    };
+}
+/**
+ * Audio message interface
+ */
+interface AudioMessage extends BaseMessage {
+    type: MessageTypesEnum.Audio;
+    audio: {
+        /**
+         * The ID for the audio file
+         */
+        id: string;
+        /**
+         * The MIME type of the audio file
+         */
+        mime_type: string;
+        /**
+         * Whether the audio is a voice message
+         */
+        voice?: boolean;
+    };
+}
+/**
+ * Document message interface
+ */
+interface DocumentMessage extends BaseMessage {
+    type: MessageTypesEnum.Document;
+    document: {
+        /**
+         * The document caption (if provided)
+         */
+        caption?: string;
+        /**
+         * The document filename
+         */
+        filename: string;
+        /**
+         * The SHA256 hash of the document
+         */
+        sha256?: string;
+        /**
+         * The ID for the document
+         */
+        id: string;
+        /**
+         * The MIME type of the document
+         */
+        mime_type: string;
+    };
+}
+/**
+ * Sticker message interface
+ */
+interface StickerMessage extends BaseMessage {
+    type: MessageTypesEnum.Sticker;
+    sticker: {
+        /**
+         * The ID for the sticker
+         */
+        id: string;
+        /**
+         * Whether this is an animated sticker
+         */
+        animated: boolean;
+        /**
+         * The MIME type of the sticker
+         */
+        mime_type: string;
+    };
+}
+/**
+ * Reaction message interface
+ */
+interface ReactionMessage extends BaseMessage {
+    type: MessageTypesEnum.Reaction;
+    reaction: {
+        /**
+         * The ID of the message being reacted to
+         */
+        message_id: string;
+        /**
+         * Emoji used for the reaction
+         */
+        emoji: string;
+    };
+}
+/**
+ * Contacts message interface
+ */
+interface ContactsMessage extends BaseMessage {
+    type: MessageTypesEnum.Contacts;
+    contacts: Array<{
+        /**
+         * The contact's name
+         */
+        name: {
+            /**
+             * The formatted name
+             */
+            formatted_name: string;
+            /**
+             * The first name
+             */
+            first_name?: string;
+            /**
+             * The last name
+             */
+            last_name?: string;
+            /**
+             * The middle name
+             */
+            middle_name?: string;
+            /**
+             * The suffix
+             */
+            suffix?: string;
+            /**
+             * The prefix
+             */
+            prefix?: string;
+        };
+        /**
+         * The contact's phone numbers
+         */
+        phones?: Array<{
+            phone: string;
+            type?: string;
+            wa_id?: string;
+        }>;
+        /**
+         * The contact's emails
+         */
+        emails?: Array<{
+            email: string;
+            type?: string;
+        }>;
+        /**
+         * The contact's addresses
+         */
+        addresses?: Array<{
+            street?: string;
+            city?: string;
+            state?: string;
+            zip?: string;
+            country?: string;
+            country_code?: string;
+            type?: string;
+        }>;
+        /**
+         * The contact's organizations
+         */
+        org?: {
+            company?: string;
+            department?: string;
+            title?: string;
+        };
+        /**
+         * The contact's URLs
+         */
+        urls?: Array<{
+            url: string;
+            type?: string;
+        }>;
+        /**
+         * The contact's birthday (YYYY-MM-DD format)
+         */
+        birthday?: string;
+    }>;
+}
+/**
+ * Location message interface
+ */
+interface LocationMessage extends BaseMessage {
+    type: MessageTypesEnum.Location;
+    location: {
+        /**
+         * Latitude of the location
+         */
+        latitude: number;
+        /**
+         * Longitude of the location
+         */
+        longitude: number;
+        /**
+         * Name of the location
+         */
+        name?: string;
+        /**
+         * Address of the location
+         */
+        address?: string;
+    };
+}
+/**
+ * Interactive message interface
+ */
+interface InteractiveMessage extends BaseMessage {
+    type: MessageTypesEnum.Interactive;
+    interactive: {
+        /**
+         * Type of the interactive message
+         * Can be: button_reply, list_reply, flow, nfm_reply, etc.
+         */
+        type: string;
+        /**
+         * ID for the button that was clicked
+         */
+        button_reply?: {
+            id: string;
+            title: string;
+        };
+        /**
+         * ID for the list item that was selected
+         */
+        list_reply?: {
+            id: string;
+            title: string;
+            description?: string;
+        };
+        /**
+         * NFM (No-Code Flow Message) reply data
+         */
+        nfm_reply?: {
+            /**
+             * Response data in JSON format
+             */
+            response_json: string;
+            /**
+             * Body text of the reply
+             */
+            body: string;
+            /**
+             * Name of the flow
+             */
+            name: string;
+        };
+    };
+}
+/**
+ * System message interface
+ */
+interface SystemMessage extends BaseMessage {
+    type: MessageTypesEnum.System;
+    system: {
+        /**
+         * The type of system update
+         */
+        type: string;
+        /**
+         * User's identity if the update is a customer identity change
+         */
+        identity?: string;
+        /**
+         * Old and new phone numbers if the update is a phone number change
+         */
+        customer?: {
+            /**
+             * The previous phone number
+             */
+            previous_wa_id: string;
+            /**
+             * The new phone number
+             */
+            wa_id: string;
+        };
+    };
+}
+/**
+ * Order message interface
+ */
+interface OrderMessage extends BaseMessage {
+    type: MessageTypesEnum.Order;
+    order: {
+        /**
+         * Catalog ID
+         */
+        catalog_id: string;
+        /**
+         * Product items in the order
+         */
+        product_items: Array<{
+            /**
+             * Product ID
+             */
+            product_retailer_id: string;
+            /**
+             * Quantity of the product
+             */
+            quantity: number;
+            /**
+             * Item price
+             */
+            item_price: number;
+            /**
+             * Currency code
+             */
+            currency: string;
+        }>;
+        /**
+         * Text message included with the order
+         */
+        text?: string;
+    };
+}
+/**
+ * Button message interface
+ */
+interface ButtonMessage extends BaseMessage {
+    type: MessageTypesEnum.Button;
+    button: {
+        /**
+         * The payload for the button
+         */
+        payload: string;
+        /**
+         * Button text
+         */
+        text: string;
+    };
+}
+/**
+ * Represents a message received through the webhook
+ * Based on Meta's documentation: https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object
+ */
+interface WebhookMessage {
+    /**
+     * The WhatsApp Business Account ID
+     */
+    wabaId: string;
+    /**
+     * The message ID
+     */
+    id: string;
+    /**
+     * The sender's phone number
+     */
+    from: string;
+    /**
+     * The timestamp of the message
+     */
+    timestamp: string;
+    /**
+     * The type of message (text, image, etc.)
+     */
+    type: MessageTypesEnum;
+    /**
+     * The phone number ID that received the message
+     */
+    phoneNumberId: string;
+    /**
+     * The display phone number that received the message
+     */
+    displayPhoneNumber: string;
+    /**
+     * The profile name of the sender
+     */
+    profileName: string;
+    text?: TextMessage['text'];
+    image?: ImageMessage['image'];
+    video?: VideoMessage['video'];
+    audio?: AudioMessage['audio'];
+    document?: DocumentMessage['document'];
+    sticker?: StickerMessage['sticker'];
+    location?: LocationMessage['location'];
+    contacts?: ContactsMessage['contacts'];
+    interactive?: InteractiveMessage['interactive'];
+    button?: ButtonMessage['button'];
+    order?: OrderMessage['order'];
+    system?: SystemMessage['system'];
+    reaction?: ReactionMessage['reaction'];
+    statuses?: {
+        /**
+         * Arbitrary string included in sent message
+         */
+        biz_opaque_callback_data?: string;
+        /**
+         * Information about the conversation
+         */
+        conversation?: {
+            /**
+             * Represents the ID of the conversation the given status notification belongs to
+             */
+            id: string;
+            /**
+             * Describes conversation category
+             */
+            origin: {
+                /**
+                 * Indicates conversation category. This can also be referred to as a conversation entry point
+                 * - authentication: Conversation opened by business sending template categorized as AUTHENTICATION
+                 * - marketing: Conversation opened by business sending template categorized as MARKETING
+                 * - utility: Conversation opened by business sending template categorized as UTILITY
+                 * - service: Conversation opened by business replying to customer within service window
+                 * - referral_conversion: Free entry point conversation
+                 */
+                type: 'authentication' | 'marketing' | 'utility' | 'service' | 'referral_conversion';
+            };
+            /**
+             * Date when the conversation expires. Only present for messages with status 'sent'
+             */
+            expiration_timestamp?: string;
+        };
+        /**
+         * Array of error objects describing the error
+         */
+        errors?: Array<{
+            /**
+             * Error code
+             */
+            code: number;
+            /**
+             * Error code title
+             */
+            title: string;
+            /**
+             * Error code message
+             */
+            message: string;
+            /**
+             * Error details object
+             */
+            error_data?: {
+                /**
+                 * Describes the error details
+                 */
+                details: string;
+            };
+        }>;
+        /**
+         * The ID for the message that the business sent to a customer
+         */
+        id: string;
+        /**
+         * Pricing information for the message/conversation
+         */
+        pricing?: {
+            /**
+             * Indicates if the given message or conversation is billable
+             * @deprecated This field is deprecated. Visit the WhatsApp Changelog for more information.
+             */
+            billable?: boolean;
+            /**
+             * Indicates the conversation category:
+             * - authentication: Authentication conversation
+             * - authentication_international: Authentication-international conversation
+             * - marketing: Marketing conversation
+             * - utility: Utility conversation
+             * - service: Service conversation
+             * - referral_conversion: Free entry point conversation
+             */
+            category: 'authentication' | 'authentication_international' | 'marketing' | 'utility' | 'service' | 'referral_conversion';
+            /**
+             * Type of pricing model used by the business. Current supported value is CBP
+             */
+            pricing_model: 'CBP';
+        };
+        /**
+         * The customer's WhatsApp ID. Business can respond to customer using this ID.
+         * This ID may not match the customer's phone number.
+         */
+        recipient_id: string;
+        /**
+         * Status of the message:
+         * - delivered: Message has been delivered
+         * - read: Message has been read by the customer
+         * - sent: Message has been sent to the customer
+         */
+        status: 'delivered' | 'read' | 'sent';
+        /**
+         * Unix timestamp for the status message
+         */
+        timestamp: string;
+    };
+    /**
+     * The original message data as received from the webhook
+     */
+    originalData: any;
+}
+/**
+ * Webhook event received from WhatsApp
+ */
+interface WebhookEvent {
+    /**
+     * The field type of the event
+     */
+    field: string;
+    /**
+     * The event data
+     */
+    value: any;
+    /**
+     * The timestamp when the event was received
+     */
+    timestamp: number;
+}
+/**
+ * Message status enum
+ */
+declare enum MessageStatus {
+    DELIVERED = "delivered",
+    READ = "read",
+    SENT = "sent"
+}
+
+type MessageHandler = (whatsapp: WhatsApp, message: WebhookMessage) => void | Promise<void>;
+type FlowHandler = (whatsapp: WhatsApp, request: FlowEndpointRequest) => any | Promise<any>;
+/**
+ * Process webhook messages
+ */
+declare function processWebhookMessages(request: Request, whatsapp: WhatsApp, handlers: {
+    messageHandlers: Map<MessageTypesEnum, MessageHandler>;
+    preProcessHandler?: MessageHandler;
+    postProcessHandler?: MessageHandler;
+}): Promise<Response>;
+/**
+ * Handle flow requests
+ */
+declare function processFlowRequest(request: Request, config: WabaConfigType, whatsapp: WhatsApp, flowHandlers: Map<FlowTypeEnum, FlowHandler>): Promise<Response>;
+/**
+ * Constructs a full URL from framework-specific request headers and URL
+ * @param headers - Request headers containing host and protocol information
+ * @param url - Relative URL path
+ * @returns Full URL string
+ */
+declare function constructFullUrl(headers: Record<string, string | string[] | undefined>, url?: string): string;
+
+interface WebhookResponse {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+}
+declare class WebhookProcessor {
+    private config;
+    private client;
+    private messageHandlers;
+    private preProcessHandler;
+    private postProcessHandler;
+    private flowHandlers;
+    constructor(config: WhatsAppConfig);
+    processVerification(mode: string | null, token: string | null, challenge: string | null): Promise<WebhookResponse>;
+    processWebhook(request: Request): Promise<WebhookResponse>;
+    processFlow(request: Request): Promise<WebhookResponse>;
+    onMessage(type: MessageTypesEnum, handler: MessageHandler): void;
+    onMessagePreProcess(handler: MessageHandler): void;
+    onMessagePostProcess(handler: MessageHandler): void;
+    onFlow(type: FlowTypeEnum, handler: FlowHandler): void;
+    getClient(): WhatsApp;
+    getConfig(): WabaConfigType;
+}
+
+export { type FlowHandler as F, MessageStatus as M, type WebhookContact as W, type WebhookEvent as a, type WebhookMessage as b, WebhookProcessor as c, type WebhookResponse as d, type MessageHandler as e, processFlowRequest as f, constructFullUrl as g, processWebhookMessages as p };