integrate-sdk 0.9.25-dev.0 → 0.9.26-dev.0

package/dist/src/integrations/whatsapp-client.d.ts

@@ -1,320 +1,515 @@
 /**
  * WhatsApp Business Integration Client Types
- * Fully typed interface for WhatsApp Business integration methods
+ * Fully typed interface for WhatsApp Business Cloud API methods
  */
 import type { MCPToolCallResponse } from "../protocol/messages.js";
-/**
- * WhatsApp Message
- */
-export interface WhatsAppMessage {
-    id: string;
-    from: string;
-    to: string;
-    timestamp: string;
-    type: "text" | "image" | "video" | "audio" | "document" | "template";
-    text?: {
-        body: string;
-    };
-    image?: {
-        id: string;
-        mime_type: string;
-        sha256: string;
-    };
-    video?: {
-        id: string;
-        mime_type: string;
-        sha256: string;
-    };
-    audio?: {
-        id: string;
-        mime_type: string;
-        sha256: string;
-    };
-    document?: {
+export interface WhatsAppSendResult {
+    messages: Array<{
         id: string;
-        mime_type: string;
-        sha256: string;
-        filename: string;
-    };
-    status?: "sent" | "delivered" | "read" | "failed";
+    }>;
+    contacts: Array<{
+        input: string;
+        wa_id: string;
+    }>;
 }
-/**
- * WhatsApp Message Template
- */
 export interface WhatsAppTemplate {
     id: string;
     name: string;
+    status: "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED";
+    category: "MARKETING" | "UTILITY" | "AUTHENTICATION";
     language: string;
-    status: "approved" | "pending" | "rejected";
-    category: "marketing" | "utility" | "authentication";
     components: Array<{
-        type: "header" | "body" | "footer" | "button";
-        text?: string;
+        type: "HEADER" | "BODY" | "FOOTER" | "BUTTONS";
         format?: string;
-        example?: {
-            header_text?: string[];
-            body_text?: string[][];
-        };
+        text?: string;
+        buttons?: Array<{
+            type: string;
+            text: string;
+            url?: string;
+        }>;
     }>;
 }
-/**
- * WhatsApp Phone Number
- */
 export interface WhatsAppPhoneNumber {
     id: string;
     display_phone_number: string;
     verified_name: string;
     code_verification_status: string;
-    quality_rating: "green" | "yellow" | "red";
+    quality_rating: "GREEN" | "YELLOW" | "RED";
     platform_type: string;
     throughput: {
         level: string;
     };
 }
-/**
- * WhatsApp Business Profile
- */
 export interface WhatsAppBusinessProfile {
     about?: string;
     address?: string;
     description?: string;
     email?: string;
-    messaging_product: string;
     profile_picture_url?: string;
     websites?: string[];
     vertical?: string;
 }
 /**
- * WhatsApp Message Status
- */
-export interface WhatsAppMessageStatus {
-    id: string;
-    status: "sent" | "delivered" | "read" | "failed";
-    timestamp: string;
-    recipient_id: string;
-    errors?: Array<{
-        code: number;
-        title: string;
-        message: string;
-        error_data?: {
-            details: string;
-        };
-    }>;
-}
-/**
- * WhatsApp Integration Client Interface
- * Provides type-safe methods for all WhatsApp Business operations
+ * WhatsApp Business Integration Client Interface
  */
 export interface WhatsAppIntegrationClient {
     /**
-     * Send a text message
+     * Send a plain text message
      *
      * @example
      * ```typescript
-     * const result = await client.whatsapp.sendMessage({
-     *   to: "+1234567890",
-     *   type: "text",
-     *   text: { body: "Hello, World!" }
+     * await client.whatsapp.sendMessage({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   text: "Hello!",
      * });
      * ```
      */
     sendMessage(params: {
-        /** Recipient phone number (E.164 format) */
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number in E.164 format */
         to: string;
-        /** Message type */
-        type: "text";
-        /** Text message content */
-        text: {
-            /** Message body text */
-            body: string;
-            /** Preview URL (optional) */
-            preview_url?: boolean;
-        };
+        /** Message body text */
+        text: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * Send a template message
+     * Reply to a specific message (quoted reply)
      *
      * @example
      * ```typescript
-     * const result = await client.whatsapp.sendTemplate({
-     *   to: "+1234567890",
-     *   template: {
-     *     name: "welcome_message",
-     *     language: { code: "en_US" },
-     *     components: [
-     *       {
-     *         type: "body",
-     *         parameters: [{ type: "text", text: "John" }]
-     *       }
-     *     ]
-     *   }
+     * await client.whatsapp.replyMessage({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   message_id: "wamid.XXX",
+     *   text: "Got it!",
+     * });
+     * ```
+     */
+    replyMessage(params: {
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
+        to: string;
+        /** The wamid of the message to reply to */
+        message_id: string;
+        /** Reply text */
+        text: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Send a pre-approved template message
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.sendTemplate({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   template_name: "order_confirmation",
+     *   language_code: "en_US",
+     *   components: JSON.stringify([{
+     *     type: "body",
+     *     parameters: [{ type: "text", text: "Alice" }, { type: "text", text: "ORDER-123" }],
+     *   }]),
      * });
      * ```
      */
     sendTemplate(params: {
-        /** Recipient phone number (E.164 format) */
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
         to: string;
-        /** Template configuration */
-        template: {
-            /** Template name */
-            name: string;
-            /** Template language */
-            language: {
-                /** Language code */
-                code: string;
-            };
-            /** Template components with parameters */
-            components?: Array<{
-                type: "header" | "body" | "button";
-                parameters?: Array<{
-                    type: "text" | "currency" | "date_time" | "image" | "document" | "video";
-                    text?: string;
-                    currency?: {
-                        fallback_value: string;
-                        code: string;
-                        amount_1000: number;
-                    };
-                    date_time?: {
-                        fallback_value: string;
-                    };
-                    image?: {
-                        link: string;
-                    };
-                    document?: {
-                        link: string;
-                        filename?: string;
-                    };
-                    video?: {
-                        link: string;
-                    };
-                }>;
-                sub_type?: string;
-                index?: number;
-            }>;
-        };
+        /** Approved template name */
+        template_name: string;
+        /** Language code e.g. en_US, es, pt_BR */
+        language_code: string;
+        /** JSON array of component objects for variable substitution */
+        components?: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * Send media (image/video/document/audio)
+     * Send an image, video, document, or audio file by URL
      *
      * @example
      * ```typescript
-     * const result = await client.whatsapp.sendMedia({
-     *   to: "+1234567890",
-     *   type: "image",
-     *   image: {
-     *     link: "https://example.com/image.jpg",
-     *     caption: "Check this out!"
-     *   }
+     * await client.whatsapp.sendMedia({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   media_type: "image",
+     *   media_url: "https://example.com/photo.jpg",
+     *   caption: "Check this out",
      * });
      * ```
      */
     sendMedia(params: {
-        /** Recipient phone number (E.164 format) */
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
+        to: string;
+        /** image, video, document, or audio */
+        media_type: "image" | "video" | "document" | "audio";
+        /** Publicly accessible URL to the media file */
+        media_url: string;
+        /** Caption text (supported for image, video, document) */
+        caption?: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * React to a message with an emoji
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.sendReaction({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   message_id: "wamid.XXX",
+     *   emoji: "👍",
+     * });
+     * ```
+     */
+    sendReaction(params: {
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
         to: string;
-        /** Media type */
-        type: "image" | "video" | "document" | "audio";
-        /** Image media (when type is "image") */
-        image?: {
-            /** Media URL or ID */
-            link?: string;
-            id?: string;
-            /** Image caption */
-            caption?: string;
-        };
-        /** Video media (when type is "video") */
-        video?: {
-            /** Media URL or ID */
-            link?: string;
-            id?: string;
-            /** Video caption */
-            caption?: string;
-        };
-        /** Document media (when type is "document") */
-        document?: {
-            /** Media URL or ID */
-            link?: string;
-            id?: string;
-            /** Document caption */
-            caption?: string;
-            /** Document filename */
-            filename?: string;
-        };
-        /** Audio media (when type is "audio") */
-        audio?: {
-            /** Media URL or ID */
-            link?: string;
-            id?: string;
-        };
+        /** The wamid of the message to react to */
+        message_id: string;
+        /** A single emoji character */
+        emoji: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * List message templates
+     * Send a location pin
      *
      * @example
      * ```typescript
-     * const templates = await client.whatsapp.listTemplates({
-     *   limit: 50
+     * await client.whatsapp.sendLocation({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   latitude: "37.7749",
+     *   longitude: "-122.4194",
+     *   name: "Golden Gate Park",
      * });
      * ```
      */
-    listTemplates(params?: {
-        /** Maximum number of templates to return */
-        limit?: number;
-        /** Pagination cursor */
-        after?: string;
-        /** Pagination cursor */
-        before?: string;
+    sendLocation(params: {
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
+        to: string;
+        /** Decimal latitude */
+        latitude: string;
+        /** Decimal longitude */
+        longitude: string;
+        /** Location name */
+        name?: string;
+        /** Address string */
+        address?: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * Get registered phone numbers
+     * Send one or more vCard-style contact cards
      *
      * @example
      * ```typescript
-     * const phoneNumbers = await client.whatsapp.getPhoneNumbers();
+     * await client.whatsapp.sendContact({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   contacts: JSON.stringify([{
+     *     name: { formatted_name: "Alice Smith", first_name: "Alice", last_name: "Smith" },
+     *     phones: [{ phone: "+15551234567", type: "CELL" }],
+     *   }]),
+     * });
      * ```
      */
-    getPhoneNumbers(params?: {
-        /** Maximum number of phone numbers to return */
-        limit?: number;
+    sendContact(params: {
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
+        to: string;
+        /** JSON array of contact objects */
+        contacts: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * Get message delivery status
+     * Send a message with up to 3 quick-reply buttons
      *
      * @example
      * ```typescript
-     * const status = await client.whatsapp.getMessageStatus({
-     *   message_id: "wamid.xxxxx"
+     * await client.whatsapp.sendInteractiveButtons({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   body_text: "Do you confirm your order?",
+     *   buttons: JSON.stringify([{ id: "yes", title: "Yes" }, { id: "no", title: "No" }]),
      * });
      * ```
      */
-    getMessageStatus(params: {
-        /** WhatsApp message ID */
-        message_id: string;
+    sendInteractiveButtons(params: {
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
+        to: string;
+        /** Main message body */
+        body_text: string;
+        /** JSON array of 1–3 button objects [{"id":"btn1","title":"Yes"}] */
+        buttons: string;
+        /** Optional header above the body */
+        header_text?: string;
+        /** Optional footer below the buttons */
+        footer_text?: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Send a message with a scrollable list of options
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.sendInteractiveList({
+     *   phone_number_id: "123456789",
+     *   to: "+15551234567",
+     *   body_text: "Choose your shipping method",
+     *   button_text: "See options",
+     *   sections: JSON.stringify([{
+     *     title: "Shipping",
+     *     rows: [
+     *       { id: "standard", title: "Standard (5-7 days)", description: "Free" },
+     *       { id: "express", title: "Express (1-2 days)", description: "$9.99" },
+     *     ],
+     *   }]),
+     * });
+     * ```
+     */
+    sendInteractiveList(params: {
+        /** Sending phone number ID */
+        phone_number_id: string;
+        /** Recipient phone number */
+        to: string;
+        /** Main message body */
+        body_text: string;
+        /** Label on the button that opens the list (max 20 chars) */
+        button_text: string;
+        /** JSON array of section objects */
+        sections: string;
+        /** Optional header */
+        header_text?: string;
+        /** Optional footer */
+        footer_text?: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * Mark message as read
+     * Mark a received message as read (shows blue ticks to sender)
      *
      * @example
      * ```typescript
      * await client.whatsapp.markRead({
-     *   message_id: "wamid.xxxxx"
+     *   phone_number_id: "123456789",
+     *   message_id: "wamid.XXX",
      * });
      * ```
      */
     markRead(params: {
-        /** WhatsApp message ID to mark as read */
+        /** Your phone number ID */
+        phone_number_id: string;
+        /** The wamid of the received message */
         message_id: string;
     }): Promise<MCPToolCallResponse>;
     /**
-     * Get business profile
+     * Get the download URL and metadata for a received media object
+     *
+     * @example
+     * ```typescript
+     * const media = await client.whatsapp.getMediaUrl({
+     *   media_id: "media123",
+     *   phone_number_id: "123456789",
+     * });
+     * // media.url expires in ~5 minutes — download promptly
+     * ```
+     */
+    getMediaUrl(params: {
+        /** Media object ID (from webhook payload) */
+        media_id: string;
+        /** Your phone number ID */
+        phone_number_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Delete an uploaded media object from Meta's servers
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.deleteMedia({ media_id: "media123", phone_number_id: "123456789" });
+     * ```
+     */
+    deleteMedia(params: {
+        /** Media object ID */
+        media_id: string;
+        /** Your phone number ID */
+        phone_number_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * List all message templates for a WhatsApp Business Account
+     *
+     * @example
+     * ```typescript
+     * const templates = await client.whatsapp.listTemplates({ business_account_id: "WABA123" });
+     * ```
+     */
+    listTemplates(params: {
+        /** WABA ID */
+        business_account_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Get a specific template by name
+     *
+     * @example
+     * ```typescript
+     * const tpl = await client.whatsapp.getTemplate({ business_account_id: "WABA123", name: "order_confirmation" });
+     * ```
+     */
+    getTemplate(params: {
+        /** WABA ID */
+        business_account_id: string;
+        /** Template name */
+        name: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Create a new message template (submitted for Meta review)
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.createTemplate({
+     *   business_account_id: "WABA123",
+     *   name: "order_ready",
+     *   language: "en_US",
+     *   category: "UTILITY",
+     *   components: JSON.stringify([
+     *     { type: "BODY", text: "Hi {{1}}, your order {{2}} is ready for pickup." },
+     *   ]),
+     * });
+     * ```
+     */
+    createTemplate(params: {
+        /** WABA ID */
+        business_account_id: string;
+        /** Template name — lowercase letters, numbers, underscores only */
+        name: string;
+        /** Language code e.g. en_US */
+        language: string;
+        /** MARKETING, UTILITY, or AUTHENTICATION */
+        category: "MARKETING" | "UTILITY" | "AUTHENTICATION";
+        /** JSON array of component objects */
+        components: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Delete a template by name (all language variants)
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.deleteTemplate({ business_account_id: "WABA123", name: "old_promo" });
+     * ```
+     */
+    deleteTemplate(params: {
+        /** WABA ID */
+        business_account_id: string;
+        /** Template name to delete */
+        name: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * List all phone numbers registered to a WABA
+     *
+     * @example
+     * ```typescript
+     * const numbers = await client.whatsapp.getPhoneNumbers({ business_account_id: "WABA123" });
+     * ```
+     */
+    getPhoneNumbers(params: {
+        /** WABA ID */
+        business_account_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Get full details for a specific phone number
+     *
+     * @example
+     * ```typescript
+     * const number = await client.whatsapp.getPhoneNumber({ phone_number_id: "123456789" });
+     * ```
+     */
+    getPhoneNumber(params: {
+        /** Phone number ID */
+        phone_number_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Get the public business profile for a phone number
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.whatsapp.getProfile({ phone_number_id: "123456789" });
+     * ```
+     */
+    getProfile(params: {
+        /** Phone number ID */
+        phone_number_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Update the business profile (pass only the fields you want to change)
+     *
+     * @example
+     * ```typescript
+     * await client.whatsapp.updateProfile({
+     *   phone_number_id: "123456789",
+     *   about: "Best prices guaranteed",
+     *   email: "support@example.com",
+     * });
+     * ```
+     */
+    updateProfile(params: {
+        /** Phone number ID */
+        phone_number_id: string;
+        /** Short about text (max 139 chars) */
+        about?: string;
+        /** Business address */
+        address?: string;
+        /** Business description */
+        description?: string;
+        /** Business email */
+        email?: string;
+        /** Industry vertical */
+        vertical?: string;
+        /** JSON array of URLs (max 2) */
+        websites?: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Get status of a sent message by message ID
+     *
+     * @example
+     * ```typescript
+     * const status = await client.whatsapp.getMessageStatus({ message_id: "wamid.XXX" });
+     * ```
+     */
+    getMessageStatus(params: {
+        /** The wamid of the message */
+        message_id: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * Create a QR code that opens a chat with a prefilled message
+     *
+     * @example
+     * ```typescript
+     * const qr = await client.whatsapp.createQrCode({
+     *   phone_number_id: "123456789",
+     *   prefilled_message: "Hi, I have a question",
+     * });
+     * console.log(qr.deep_link_url, qr.qr_image_url);
+     * ```
+     */
+    createQrCode(params: {
+        /** Phone number ID */
+        phone_number_id: string;
+        /** Message text to prefill when QR is scanned */
+        prefilled_message: string;
+    }): Promise<MCPToolCallResponse>;
+    /**
+     * List all QR codes for a phone number
      *
      * @example
      * ```typescript
-     * const profile = await client.whatsapp.getProfile();
+     * const codes = await client.whatsapp.listQrCodes({ phone_number_id: "123456789" });
      * ```
      */
-    getProfile(params?: {
-        /** Fields to retrieve */
-        fields?: string[];
+    listQrCodes(params: {
+        /** Phone number ID */
+        phone_number_id: string;
     }): Promise<MCPToolCallResponse>;
 }
 //# sourceMappingURL=whatsapp-client.d.ts.map