@warriorteam/messenger-sdk 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -1,15 +1,19 @@
 interface ClientConfig {
-    accessToken: string;
+    accessToken?: string;
     version: string;
     baseUrl?: string;
     timeout?: number;
     maxRetries?: number;
 }
+interface APIOptions {
+    accessToken?: string;
+}
 interface RequestOptions {
     method: 'GET' | 'POST' | 'DELETE';
     path: string;
     body?: any;
     query?: Record<string, string | number | boolean>;
+    accessToken?: string;
 }
 declare class HTTPClient {
     private readonly config;
@@ -30,23 +34,23 @@ interface Recipient {
         last_name: string;
     };
 }
-interface QuickReply {
+interface QuickReply$1 {
     content_type: 'text' | 'user_phone_number' | 'user_email';
     title?: string;
     payload?: string;
     image_url?: string;
 }
-interface Message {
+interface Message$1 {
     text?: string;
     attachment?: Attachment;
-    quick_replies?: QuickReply[];
+    quick_replies?: QuickReply$1[];
     metadata?: string;
 }
 interface Attachment {
     type: 'image' | 'audio' | 'video' | 'file' | 'template';
-    payload: AttachmentPayload | TemplatePayload;
+    payload: AttachmentPayload$1 | TemplatePayload;
 }
-interface AttachmentPayload {
+interface AttachmentPayload$1 {
     url?: string;
     attachment_id?: string;
     is_reusable?: boolean;
@@ -62,7 +66,7 @@ type MessagingType = 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG';
 interface SendMessageRequest {
     recipient: Recipient;
     messaging_type: MessagingType;
-    message?: Message;
+    message?: Message$1;
     sender_action?: SenderAction;
     notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH';
     tag?: string;
@@ -84,9 +88,9 @@ interface ErrorResponse {
     error: MessengerError;
 }
 
-type AttachmentType = 'image' | 'audio' | 'video' | 'file';
+type AttachmentType$1 = 'image' | 'audio' | 'video' | 'file';
 interface AttachmentUploadRequest {
-    type: AttachmentType;
+    type: AttachmentType$1;
     url: string;
     is_reusable?: boolean;
 }
@@ -97,35 +101,35 @@ interface AttachmentUploadResponse {
 declare class SendAPI {
     private httpClient;
     constructor(httpClient: HTTPClient);
-    message(request: SendMessageRequest): Promise<SendMessageResponse>;
-    action(recipientId: string, action: SenderAction): Promise<SendMessageResponse>;
-    typingOn(recipientId: string): Promise<SendMessageResponse>;
-    typingOff(recipientId: string): Promise<SendMessageResponse>;
-    markSeen(recipientId: string): Promise<SendMessageResponse>;
+    message(request: SendMessageRequest, options?: APIOptions): Promise<SendMessageResponse>;
+    action(recipientId: string, action: SenderAction, options?: APIOptions): Promise<SendMessageResponse>;
+    typingOn(recipientId: string, options?: APIOptions): Promise<SendMessageResponse>;
+    typingOff(recipientId: string, options?: APIOptions): Promise<SendMessageResponse>;
+    markSeen(recipientId: string, options?: APIOptions): Promise<SendMessageResponse>;
     /**
      * Send an attachment using a previously uploaded attachment_id
      */
     attachment(options: {
         recipient: Recipient;
-        type: AttachmentType;
+        type: AttachmentType$1;
         attachment_id: string;
         messaging_type?: 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG';
-    }): Promise<SendMessageResponse>;
+    }, apiOptions?: APIOptions): Promise<SendMessageResponse>;
     /**
      * Upload and send an attachment from URL in a single request
      */
     attachmentFromUrl(options: {
         recipient: Recipient;
-        type: AttachmentType;
+        type: AttachmentType$1;
         url: string;
         messaging_type?: 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG';
-    }): Promise<SendMessageResponse>;
+    }, apiOptions?: APIOptions): Promise<SendMessageResponse>;
 }
 
 declare class AttachmentsAPI {
     private httpClient;
     constructor(httpClient: HTTPClient);
-    upload(request: AttachmentUploadRequest): Promise<AttachmentUploadResponse>;
+    upload(request: AttachmentUploadRequest, options?: APIOptions): Promise<AttachmentUploadResponse>;
 }
 
 interface UserId {
@@ -147,35 +151,35 @@ declare class ModerationAPI {
      * Moderate conversations with specified actions
      * Up to 10 user IDs and up to 2 actions per request
      */
-    moderate(request: ModerateConversationsRequest): Promise<ModerateConversationsResponse>;
+    moderate(request: ModerateConversationsRequest, options?: APIOptions): Promise<ModerateConversationsResponse>;
     /**
      * Block a user from messaging the page
      * Prevents messaging but user can still interact with page content on Facebook
      */
-    blockUser(userIds: string | string[]): Promise<ModerateConversationsResponse>;
+    blockUser(userIds: string | string[], options?: APIOptions): Promise<ModerateConversationsResponse>;
     /**
      * Unblock a user to allow messaging again
      */
-    unblockUser(userIds: string | string[]): Promise<ModerateConversationsResponse>;
+    unblockUser(userIds: string | string[], options?: APIOptions): Promise<ModerateConversationsResponse>;
     /**
      * Ban a user from both messaging and Facebook interactions
      * More restrictive than blocking - prevents all interactions
      * Note: Cannot ban user who was unbanned in last 48 hours
      */
-    banUser(userIds: string | string[]): Promise<ModerateConversationsResponse>;
+    banUser(userIds: string | string[], options?: APIOptions): Promise<ModerateConversationsResponse>;
     /**
      * Unban a user to restore all interactions
      * Note: Banned user cannot be unblocked, they must be unbanned first
      */
-    unbanUser(userIds: string | string[]): Promise<ModerateConversationsResponse>;
+    unbanUser(userIds: string | string[], options?: APIOptions): Promise<ModerateConversationsResponse>;
     /**
      * Move conversation to spam folder in Meta Business Suite Inbox
      */
-    moveToSpam(userIds: string | string[]): Promise<ModerateConversationsResponse>;
+    moveToSpam(userIds: string | string[], options?: APIOptions): Promise<ModerateConversationsResponse>;
     /**
      * Block user and move to spam (common moderation action)
      */
-    blockAndSpam(userIds: string | string[]): Promise<ModerateConversationsResponse>;
+    blockAndSpam(userIds: string | string[], options?: APIOptions): Promise<ModerateConversationsResponse>;
 }
 
 interface Button {
@@ -246,7 +250,7 @@ declare class TemplatesAPI {
         image_aspect_ratio?: 'horizontal' | 'square';
         notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH';
         tag?: string;
-    }): Promise<SendMessageResponse>;
+    }, apiOptions?: APIOptions): Promise<SendMessageResponse>;
     button(options: {
         recipient: Recipient;
         text: string;
@@ -254,21 +258,21 @@ declare class TemplatesAPI {
         messaging_type?: MessagingType;
         notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH';
         tag?: string;
-    }): Promise<SendMessageResponse>;
+    }, apiOptions?: APIOptions): Promise<SendMessageResponse>;
     media(options: {
         recipient: Recipient;
         element: MediaTemplateElement;
         messaging_type?: MessagingType;
         notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH';
         tag?: string;
-    }): Promise<SendMessageResponse>;
+    }, apiOptions?: APIOptions): Promise<SendMessageResponse>;
     product(options: {
         recipient: Recipient;
         elements: ProductTemplateElement[];
         messaging_type?: MessagingType;
         notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH';
         tag?: string;
-    }): Promise<SendMessageResponse>;
+    }, apiOptions?: APIOptions): Promise<SendMessageResponse>;
 }
 
 type ProfileField = 'id' | 'name' | 'first_name' | 'last_name' | 'profile_pic' | 'locale' | 'timezone' | 'gender';
@@ -294,27 +298,27 @@ declare class ProfileAPI {
      * Get user profile information using PSID
      * Requires "Advanced User Profile Access" feature
      */
-    get(request: GetProfileRequest): Promise<UserProfile>;
+    get(request: GetProfileRequest, options?: APIOptions): Promise<UserProfile>;
     /**
      * Get user profile with default fields (first_name, last_name, profile_pic)
      */
-    getBasic(psid: string): Promise<UserProfile>;
+    getBasic(psid: string, options?: APIOptions): Promise<UserProfile>;
     /**
      * Get comprehensive user profile with all available fields
      */
-    getFull(psid: string): Promise<UserProfile>;
+    getFull(psid: string, options?: APIOptions): Promise<UserProfile>;
     /**
      * Get user's name (first_name and last_name)
      */
-    getName(psid: string): Promise<UserProfile>;
+    getName(psid: string, options?: APIOptions): Promise<UserProfile>;
     /**
      * Get user's profile picture URL
      */
-    getProfilePicture(psid: string): Promise<UserProfile>;
+    getProfilePicture(psid: string, options?: APIOptions): Promise<UserProfile>;
 }
 
 interface MessengerConfig {
-    accessToken: string;
+    accessToken?: string;
     version?: string;
     baseUrl?: string;
     timeout?: number;
@@ -327,10 +331,1825 @@ declare class Messenger {
     readonly templates: TemplatesAPI;
     readonly profile: ProfileAPI;
     private readonly httpClient;
-    constructor(config: MessengerConfig);
+    constructor(config?: MessengerConfig);
     private validateConfig;
 }
 
+/**
+ * Facebook Messenger Platform - Message Edits Webhook Types
+ *
+ * These types represent the webhook event structure for message_edits events.
+ * Triggered when a user edits a previously sent message.
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-edits/
+ */
+/**
+ * Represents the sender information in a message edit webhook event
+ */
+interface MessageEditSender {
+    /** Page-scoped ID (PSID) of the user who sent the message */
+    id: string;
+    /**
+     * User reference provided by the chat plugin, if applicable.
+     * Only present for chat plugin events.
+     */
+    user_ref?: string;
+}
+/**
+ * Represents the recipient information in a message edit webhook event
+ */
+interface MessageEditRecipient {
+    /** Page ID that received the message */
+    id: string;
+}
+/**
+ * Represents the edited message information
+ */
+interface MessageEdit {
+    /**
+     * Unique message identifier for the edited message
+     */
+    mid: string;
+    /**
+     * New message content after the edit.
+     * Contains the updated text of the message.
+     */
+    text: string;
+    /**
+     * Number of times the message has been edited.
+     * Maximum value is 5 (client-side constraint).
+     */
+    num_edit: number;
+}
+/**
+ * Main webhook event structure for message edits
+ *
+ * This event is triggered when a user edits a previously sent message.
+ * The webhook provides the updated message content and edit count.
+ *
+ * @example
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1458668856463,
+ *   "message_edit": {
+ *     "mid": "mid.1458668856218:ed81099e15d3f4f233",
+ *     "text": "This is the updated message content",
+ *     "num_edit": 2
+ *   }
+ * }
+ * ```
+ */
+interface MessageEditWebhookEvent {
+    /** Information about the user who edited the message */
+    sender: MessageEditSender;
+    /** Information about the page that received the message */
+    recipient: MessageEditRecipient;
+    /**
+     * Timestamp when the edit occurred (in milliseconds since epoch).
+     * Represents the time the edit was made, not the original message time.
+     */
+    timestamp: number;
+    /** Details about the edited message */
+    message_edit: MessageEdit;
+}
+/**
+ * Complete webhook payload structure that includes the message edit event
+ * along with other webhook metadata
+ */
+interface MessageEditWebhookPayload {
+    /** The webhook object type - always "page" for Messenger */
+    object: 'page';
+    /** Array of webhook entries containing the actual events */
+    entry: Array<{
+        /** Page ID */
+        id: string;
+        /** Timestamp of the webhook entry */
+        time: number;
+        /** Array of messaging events - contains the message edit event */
+        messaging: MessageEditWebhookEvent[];
+    }>;
+}
+/**
+ * Type guard to check if a webhook event is a message edit event
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event contains a message_edit property
+ *
+ * @example
+ * ```typescript
+ * if (isMessageEditEvent(event)) {
+ *   // TypeScript now knows event has message_edit property
+ *   console.log(`Message edited ${event.message_edit.num_edit} times`);
+ * }
+ * ```
+ */
+declare function isMessageEditEvent(event: any): event is MessageEditWebhookEvent;
+/**
+ * Utility type for common message edit properties that might be used in processing
+ */
+interface MessageEditProcessingContext {
+    /** The edited message ID */
+    messageId: string;
+    /** The user who made the edit */
+    senderId: string;
+    /** The page that received the edit */
+    recipientId: string;
+    /** Updated message content */
+    updatedText: string;
+    /** Number of edits made */
+    editCount: number;
+    /** When the edit occurred */
+    editTimestamp: number;
+}
+/**
+ * Helper function to extract processing context from a message edit event
+ *
+ * @param event - The message edit webhook event
+ * @returns Simplified processing context
+ *
+ * @example
+ * ```typescript
+ * const context = extractMessageEditContext(webhookEvent);
+ * console.log(`User ${context.senderId} edited message to: "${context.updatedText}"`);
+ * ```
+ */
+declare function extractMessageEditContext(event: MessageEditWebhookEvent): MessageEditProcessingContext;
+/**
+ * Constants related to message editing limits and constraints
+ */
+declare const MESSAGE_EDIT_CONSTANTS: {
+    /** Maximum number of edits allowed per message */
+    readonly MAX_EDITS: 5;
+    /** Webhook event type identifier */
+    readonly EVENT_TYPE: "message_edit";
+};
+
+/**
+ * Facebook Messenger Platform Message Reactions Webhook Types
+ *
+ * These types define the structure of webhook events received when users
+ * react to messages in Messenger conversations.
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-reactions
+ */
+/**
+ * Types of reactions that can be applied to messages in Messenger.
+ * These are the predefined reaction types supported by Facebook.
+ */
+declare enum MessageReactionType {
+    /** Standard like reaction */
+    LIKE = "like",
+    /** Dislike reaction */
+    DISLIKE = "dislike",
+    /** Love reaction (heart) */
+    LOVE = "love",
+    /** Sad reaction */
+    SAD = "sad",
+    /** Angry reaction */
+    ANGRY = "angry",
+    /** Wow/surprised reaction */
+    WOW = "wow",
+    /** Smile/laugh reaction */
+    SMILE = "smile",
+    /** Other/unrecognized emoji reactions */
+    OTHER = "other"
+}
+/**
+ * Actions that can be performed on message reactions.
+ */
+declare enum MessageReactionAction {
+    /** Adding a reaction to a message */
+    REACT = "react",
+    /** Removing a reaction from a message */
+    UNREACT = "unreact"
+}
+/**
+ * Represents the sender of the reaction.
+ * Contains the Page-Scoped User ID (PSID) of the user who reacted.
+ */
+interface MessageReactionSender {
+    /** Page-Scoped User ID (PSID) of the user who reacted */
+    id: string;
+    /**
+     * User reference for chat plugin events (optional)
+     * Used when the reaction comes from a chat plugin integration
+     */
+    user_ref?: string;
+}
+/**
+ * Represents the recipient (page) that received the reaction.
+ */
+interface MessageReactionRecipient {
+    /** Page ID of the Facebook page that received the reaction */
+    id: string;
+}
+/**
+ * Contains the detailed information about the reaction.
+ */
+interface MessageReactionData {
+    /**
+     * The type of reaction applied to the message.
+     * Can be one of the predefined types or "other" for unrecognized emojis.
+     */
+    reaction: MessageReactionType;
+    /**
+     * The UTF-8 emoji representation of the reaction (optional).
+     * Example: "\u{2764}\u{FE0F}" for heart emoji
+     */
+    emoji?: string;
+    /**
+     * The action performed - either adding or removing the reaction.
+     */
+    action: MessageReactionAction;
+    /**
+     * The message ID that the reaction was applied to.
+     * This corresponds to the 'mid' field of the original message.
+     */
+    mid: string;
+}
+/**
+ * Complete webhook event structure for message reactions.
+ * This is the main payload received when a user reacts to a message.
+ */
+interface MessageReactionWebhookEvent {
+    /** Information about the user who performed the reaction */
+    sender: MessageReactionSender;
+    /** Information about the page that received the reaction */
+    recipient: MessageReactionRecipient;
+    /**
+     * Unix timestamp (in milliseconds) when the reaction occurred.
+     * Example: 1458668856463
+     */
+    timestamp: number;
+    /** Detailed information about the reaction */
+    reaction: MessageReactionData;
+}
+/**
+ * The complete webhook payload containing the message reaction event.
+ * This matches the structure of the webhook POST request body.
+ */
+interface MessageReactionWebhookPayload {
+    /** The page object containing the reaction events */
+    object: 'page';
+    /** Array of page entries, each containing reaction events */
+    entry: Array<{
+        /** Page ID */
+        id: string;
+        /** Unix timestamp when the webhook was triggered */
+        time: number;
+        /** Array of messaging events containing the reactions */
+        messaging: MessageReactionWebhookEvent[];
+    }>;
+}
+/**
+ * Context object for processing message reaction webhooks.
+ * Useful for handlers that need additional processing information.
+ */
+interface MessageReactionProcessingContext {
+    /** The original webhook event */
+    event: MessageReactionWebhookEvent;
+    /** Page ID that received the reaction */
+    pageId: string;
+    /** User ID who performed the reaction */
+    userId: string;
+    /** ID of the message that was reacted to */
+    messageId: string;
+    /** Whether this is a new reaction (true) or removal (false) */
+    isReactionAdded: boolean;
+    /** The type of reaction */
+    reactionType: MessageReactionType;
+    /** Raw emoji string if available */
+    emoji?: string;
+    /** Timestamp when the reaction occurred */
+    timestamp: Date;
+}
+/**
+ * Helper type for reaction statistics and aggregation.
+ * Useful for tracking reaction counts on messages.
+ */
+interface MessageReactionStats {
+    /** The message ID these stats apply to */
+    messageId: string;
+    /** Count of each reaction type */
+    reactions: {
+        [K in MessageReactionType]?: number;
+    };
+    /** Total number of reactions */
+    totalReactions: number;
+    /** Last updated timestamp */
+    lastUpdated: Date;
+}
+/**
+ * Configuration options for handling message reaction webhooks.
+ */
+interface MessageReactionWebhookConfig {
+    /** Whether to track reaction statistics */
+    enableStats?: boolean;
+    /** Whether to handle emoji reactions beyond predefined types */
+    handleCustomEmojis?: boolean;
+    /** Maximum age of reactions to process (in milliseconds) */
+    maxReactionAge?: number;
+    /** Whether to validate webhook signatures */
+    validateSignature?: boolean;
+}
+
+/**
+ * Facebook Messenger Platform - Message Reads Webhook Types
+ *
+ * These types represent the webhook event structure for message_reads events.
+ * Triggered when a user reads messages sent by a Page.
+ *
+ * The message_reads webhook event indicates that all messages up to a certain
+ * watermark timestamp have been read by the recipient.
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-reads/
+ */
+/**
+ * Represents the sender information in a message reads webhook event
+ */
+interface MessageReadsSender {
+    /** Page-scoped ID (PSID) of the user who read the messages */
+    id: string;
+    /**
+     * User reference provided by the chat plugin, if applicable.
+     * Only present for chat plugin events.
+     */
+    user_ref?: string;
+}
+/**
+ * Represents the recipient information in a message reads webhook event
+ */
+interface MessageReadsRecipient {
+    /** Page ID that sent the original messages */
+    id: string;
+}
+/**
+ * Represents the read receipt information
+ */
+interface MessageRead {
+    /**
+     * Watermark timestamp indicating all messages up to this point have been read.
+     * This is a Unix timestamp in milliseconds.
+     * All messages with a timestamp less than or equal to this value have been read.
+     */
+    watermark: number;
+}
+/**
+ * Main webhook event structure for message reads
+ *
+ * This event is triggered when a user reads messages sent by a Page.
+ * The watermark indicates the timestamp up to which all messages have been read.
+ *
+ * @example
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1458668856463,
+ *   "read": {
+ *     "watermark": 1458668856253
+ *   }
+ * }
+ * ```
+ */
+interface MessageReadsWebhookEvent {
+    /** Information about the user who read the messages */
+    sender: MessageReadsSender;
+    /** Information about the page that sent the messages */
+    recipient: MessageReadsRecipient;
+    /**
+     * Timestamp when the read event occurred (in milliseconds since epoch).
+     * Represents when the read receipt was generated.
+     */
+    timestamp: number;
+    /** Read receipt information containing the watermark */
+    read: MessageRead;
+}
+/**
+ * Complete webhook payload structure that includes the message reads event
+ * along with other webhook metadata
+ */
+interface MessageReadsWebhookPayload {
+    /** The webhook object type - always "page" for Messenger */
+    object: 'page';
+    /** Array of webhook entries containing the actual events */
+    entry: Array<{
+        /** Page ID */
+        id: string;
+        /** Timestamp of the webhook entry */
+        time: number;
+        /** Array of messaging events - contains the message reads event */
+        messaging: MessageReadsWebhookEvent[];
+    }>;
+}
+/**
+ * Type guard to check if a webhook event is a message reads event
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event contains a read property
+ *
+ * @example
+ * ```typescript
+ * if (isMessageReadsEvent(event)) {
+ *   // TypeScript now knows event has read property
+ *   console.log(`Messages read up to timestamp: ${event.read.watermark}`);
+ * }
+ * ```
+ */
+declare function isMessageReadsEvent(event: any): event is MessageReadsWebhookEvent;
+/**
+ * Utility type for extracting just the read data from a webhook event
+ */
+type MessageReadData = MessageRead;
+/**
+ * Utility type for common message reads properties that might be used in processing
+ */
+interface MessageReadsProcessingContext {
+    /** The user who read the messages */
+    senderId: string;
+    /** The page that sent the messages */
+    recipientId: string;
+    /** Timestamp up to which all messages have been read */
+    watermarkTimestamp: number;
+    /** When the read event occurred */
+    readTimestamp: number;
+    /**
+     * Human-readable datetime for the watermark timestamp.
+     * Useful for logging and debugging.
+     */
+    watermarkDate: Date;
+    /**
+     * Human-readable datetime for the read event timestamp.
+     * Useful for logging and debugging.
+     */
+    readDate: Date;
+}
+/**
+ * Helper function to extract processing context from a message reads event
+ *
+ * @param event - The message reads webhook event
+ * @returns Simplified processing context with additional computed fields
+ *
+ * @example
+ * ```typescript
+ * const context = extractMessageReadsContext(webhookEvent);
+ * console.log(`User ${context.senderId} read messages up to ${context.watermarkDate.toISOString()}`);
+ * ```
+ */
+declare function extractMessageReadsContext(event: MessageReadsWebhookEvent): MessageReadsProcessingContext;
+/**
+ * Helper function to check if a specific message timestamp was read
+ *
+ * @param messageTimestamp - The timestamp of the message to check
+ * @param watermark - The watermark timestamp from the read event
+ * @returns True if the message with the given timestamp has been read
+ *
+ * @example
+ * ```typescript
+ * const messageTime = 1458668855000;
+ * const watermark = 1458668856253;
+ *
+ * if (isMessageRead(messageTime, watermark)) {
+ *   console.log('This message has been read');
+ * }
+ * ```
+ */
+declare function isMessageRead(messageTimestamp: number, watermark: number): boolean;
+/**
+ * Helper function to determine which messages in a list have been read
+ *
+ * @param messages - Array of messages with timestamp property
+ * @param watermark - The watermark timestamp from the read event
+ * @returns Array of messages that have been read
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { id: '1', timestamp: 1458668855000, text: 'Hello' },
+ *   { id: '2', timestamp: 1458668857000, text: 'World' }
+ * ];
+ * const watermark = 1458668856253;
+ *
+ * const readMessages = getReadMessages(messages, watermark);
+ * // Returns only the first message as it's before the watermark
+ * ```
+ */
+declare function getReadMessages<T extends {
+    timestamp: number;
+}>(messages: T[], watermark: number): T[];
+/**
+ * Helper function to get the count of read messages from a list
+ *
+ * @param messages - Array of messages with timestamp property
+ * @param watermark - The watermark timestamp from the read event
+ * @returns Number of messages that have been read
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { id: '1', timestamp: 1458668855000 },
+ *   { id: '2', timestamp: 1458668857000 }
+ * ];
+ * const watermark = 1458668856253;
+ *
+ * const readCount = getReadMessageCount(messages, watermark);
+ * // Returns 1
+ * ```
+ */
+declare function getReadMessageCount<T extends {
+    timestamp: number;
+}>(messages: T[], watermark: number): number;
+/**
+ * Constants related to message reads functionality
+ */
+declare const MESSAGE_READS_CONSTANTS: {
+    /** Webhook event type identifier */
+    readonly EVENT_TYPE: "message_reads";
+    /**
+     * Property name in the webhook event that contains read data.
+     * Used for type guards and event identification.
+     */
+    readonly READ_PROPERTY: "read";
+};
+/**
+ * Type for the watermark timestamp
+ * Represents a Unix timestamp in milliseconds indicating read status
+ */
+type WatermarkTimestamp = number;
+
+/**
+ * Facebook Messenger Platform - Messaging Postbacks Webhook Types
+ *
+ * These types represent the webhook event structure for messaging_postbacks events.
+ * Triggered when a user clicks on a postback button, Get Started button, or persistent menu item.
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_postbacks
+ */
+/**
+ * Represents the sender information in a messaging postback webhook event
+ */
+interface PostbackSender {
+    /**
+     * Page-scoped ID (PSID) of the user who triggered the postback.
+     * This is the unique identifier for the user within the context of your page.
+     */
+    id?: string;
+    /**
+     * User reference provided by the chat plugin, if applicable.
+     * Only present for chat plugin events where the user hasn't been identified yet.
+     */
+    user_ref?: string;
+}
+/**
+ * Represents the recipient information in a messaging postback webhook event
+ */
+interface PostbackRecipient {
+    /** Facebook Page ID that received the postback */
+    id: string;
+}
+/**
+ * Represents referral information for postbacks that originated from external sources
+ *
+ * This object is included when a postback is triggered as part of a conversation
+ * that was started via m.me links, Click to Messenger ads, Messenger QR codes,
+ * or the Welcome Screen.
+ */
+interface PostbackReferral {
+    /**
+     * Arbitrary data that was included in the original referral.
+     * This is the custom parameter you set when creating the referral link.
+     */
+    ref?: string;
+    /**
+     * Source of the referral. Indicates how the conversation was initiated.
+     * Common values include:
+     * - "SHORTLINK" - from m.me links
+     * - "ADS" - from Click to Messenger ads
+     * - "MESSENGER_CODE" - from Messenger QR codes
+     */
+    source?: string;
+    /**
+     * Type of referral action that initiated the conversation.
+     * Common value is "OPEN_THREAD" for most referral types.
+     */
+    type?: string;
+}
+/**
+ * Represents the postback data in a messaging postback webhook event
+ */
+interface PostbackData {
+    /**
+     * Message ID associated with the postback.
+     * Unique identifier for the message that contained the postback button.
+     */
+    mid?: string;
+    /**
+     * Title of the postback button that was clicked.
+     * This is the user-visible text that was displayed on the button.
+     */
+    title?: string;
+    /**
+     * Developer-defined payload that was associated with the postback button.
+     * This contains the custom data you specified when creating the button.
+     * Maximum length is 1000 characters.
+     */
+    payload: string;
+    /**
+     * Referral information if the postback is part of a referred conversation.
+     * Only present when the conversation was initiated through external sources
+     * like m.me links, ads, QR codes, or Welcome Screen.
+     */
+    referral?: PostbackReferral;
+}
+/**
+ * Main webhook event structure for messaging postbacks
+ *
+ * This event is triggered when a user interacts with postback buttons,
+ * including regular postback buttons, Get Started button, and persistent menu items.
+ *
+ * @example
+ * Basic postback from a button click:
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1527459824,
+ *   "postback": {
+ *     "mid": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdHtHaW",
+ *     "title": "Get Started",
+ *     "payload": "GET_STARTED_PAYLOAD"
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Postback with referral data from m.me link:
+ * ```json
+ * {
+ *   "sender": {
+ *     "user_ref": "unique_ref_param"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1527459824,
+ *   "postback": {
+ *     "title": "Contact Sales",
+ *     "payload": "CONTACT_SALES",
+ *     "referral": {
+ *       "ref": "landing_page_ad_campaign",
+ *       "source": "SHORTLINK",
+ *       "type": "OPEN_THREAD"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface MessagingPostbackWebhookEvent {
+    /** Information about the user who triggered the postback */
+    sender: PostbackSender;
+    /** Information about the page that received the postback */
+    recipient: PostbackRecipient;
+    /**
+     * Unix timestamp when the postback was triggered (in milliseconds since epoch).
+     * Represents when the user clicked the button, not when the webhook was sent.
+     */
+    timestamp: number;
+    /** Details about the postback that was triggered */
+    postback: PostbackData;
+}
+/**
+ * Complete webhook payload structure that includes the messaging postback event
+ * along with other webhook metadata
+ */
+interface MessagingPostbackWebhookPayload {
+    /** The webhook object type - always "page" for Messenger */
+    object: 'page';
+    /** Array of webhook entries containing the actual events */
+    entry: Array<{
+        /** Page ID */
+        id: string;
+        /** Timestamp of the webhook entry */
+        time: number;
+        /** Array of messaging events - contains the postback event */
+        messaging: MessagingPostbackWebhookEvent[];
+    }>;
+}
+/**
+ * Type guard to check if a webhook event is a messaging postback event
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event contains a postback property
+ *
+ * @example
+ * ```typescript
+ * if (isMessagingPostbackEvent(event)) {
+ *   // TypeScript now knows event has postback property
+ *   console.log(`User clicked: ${event.postback.title}`);
+ *   console.log(`Payload: ${event.postback.payload}`);
+ * }
+ * ```
+ */
+declare function isMessagingPostbackEvent(event: any): event is MessagingPostbackWebhookEvent;
+/**
+ * Type guard to check if a postback event includes referral data
+ *
+ * @param event - The messaging postback event to check
+ * @returns True if the event contains referral information
+ *
+ * @example
+ * ```typescript
+ * if (hasReferralData(event)) {
+ *   // Handle referred conversation
+ *   console.log(`Referred from: ${event.postback.referral.source}`);
+ *   console.log(`Ref parameter: ${event.postback.referral.ref}`);
+ * }
+ * ```
+ */
+declare function hasReferralData(event: MessagingPostbackWebhookEvent): event is MessagingPostbackWebhookEvent & {
+    postback: PostbackData & {
+        referral: PostbackReferral;
+    };
+};
+/**
+ * Type guard to check if sender is identified (has PSID) vs anonymous (has user_ref)
+ *
+ * @param sender - The sender object to check
+ * @returns True if sender has a PSID (is identified)
+ *
+ * @example
+ * ```typescript
+ * if (isIdentifiedSender(event.sender)) {
+ *   // User has been identified and has a PSID
+ *   console.log(`User PSID: ${event.sender.id}`);
+ * } else {
+ *   // Anonymous user with user_ref (likely from chat plugin)
+ *   console.log(`Anonymous user ref: ${event.sender.user_ref}`);
+ * }
+ * ```
+ */
+declare function isIdentifiedSender(sender: PostbackSender): sender is PostbackSender & {
+    id: string;
+};
+/**
+ * Utility type for extracting just the postback data from a webhook event
+ */
+type PostbackEventData = PostbackData;
+/**
+ * Utility type for common postback properties that might be used in processing
+ */
+interface PostbackProcessingContext {
+    /** The postback payload data */
+    payload: string;
+    /** The user who triggered the postback (PSID or user_ref) */
+    senderId?: string;
+    /** User reference for anonymous users */
+    userRef?: string;
+    /** The page that received the postback */
+    recipientId: string;
+    /** Button title if available */
+    buttonTitle?: string;
+    /** Message ID if available */
+    messageId?: string;
+    /** When the postback occurred */
+    timestamp: number;
+    /** Referral context if present */
+    referralContext?: {
+        ref?: string;
+        source?: string;
+        type?: string;
+    };
+    /** Whether this is from a referred conversation */
+    isReferred: boolean;
+    /** Whether the sender is identified (has PSID) */
+    isIdentifiedUser: boolean;
+}
+/**
+ * Helper function to extract processing context from a messaging postback event
+ *
+ * @param event - The messaging postback webhook event
+ * @returns Simplified processing context with all relevant data
+ *
+ * @example
+ * ```typescript
+ * const context = extractPostbackContext(webhookEvent);
+ *
+ * if (context.isReferred) {
+ *   console.log(`New conversation from ${context.referralContext?.source}`);
+ * }
+ *
+ * if (context.isIdentifiedUser) {
+ *   console.log(`Known user ${context.senderId} clicked: ${context.payload}`);
+ * } else {
+ *   console.log(`Anonymous user ${context.userRef} clicked: ${context.payload}`);
+ * }
+ * ```
+ */
+declare function extractPostbackContext(event: MessagingPostbackWebhookEvent): PostbackProcessingContext;
+/**
+ * Common postback payload patterns used in Messenger bots
+ */
+declare const COMMON_POSTBACK_PAYLOADS: {
+    /** Get Started button payload */
+    readonly GET_STARTED: "GET_STARTED";
+    /** Main menu navigation */
+    readonly MAIN_MENU: "MAIN_MENU";
+    /** Help/Support options */
+    readonly HELP: "HELP";
+    readonly SUPPORT: "SUPPORT";
+    /** Contact information */
+    readonly CONTACT: "CONTACT";
+    readonly CONTACT_SALES: "CONTACT_SALES";
+    readonly CONTACT_SUPPORT: "CONTACT_SUPPORT";
+    /** Navigation actions */
+    readonly BACK: "BACK";
+    readonly NEXT: "NEXT";
+    readonly CANCEL: "CANCEL";
+    /** User preferences */
+    readonly SETTINGS: "SETTINGS";
+    readonly PREFERENCES: "PREFERENCES";
+};
+/**
+ * Constants related to postback events and constraints
+ */
+declare const POSTBACK_CONSTANTS: {
+    /** Maximum payload length in characters */
+    readonly MAX_PAYLOAD_LENGTH: 1000;
+    /** Webhook event type identifier */
+    readonly EVENT_TYPE: "postback";
+    /** Common referral sources */
+    readonly REFERRAL_SOURCES: {
+        readonly SHORTLINK: "SHORTLINK";
+        readonly ADS: "ADS";
+        readonly MESSENGER_CODE: "MESSENGER_CODE";
+    };
+    /** Common referral types */
+    readonly REFERRAL_TYPES: {
+        readonly OPEN_THREAD: "OPEN_THREAD";
+    };
+};
+/**
+ * Type for postback payload values - can be custom strings or common patterns
+ */
+type PostbackPayload = string | typeof COMMON_POSTBACK_PAYLOADS[keyof typeof COMMON_POSTBACK_PAYLOADS];
+/**
+ * Type for referral sources
+ */
+type ReferralSource$1 = typeof POSTBACK_CONSTANTS.REFERRAL_SOURCES[keyof typeof POSTBACK_CONSTANTS.REFERRAL_SOURCES] | string;
+/**
+ * Type for referral types
+ */
+type ReferralType$1 = typeof POSTBACK_CONSTANTS.REFERRAL_TYPES[keyof typeof POSTBACK_CONSTANTS.REFERRAL_TYPES] | string;
+
+/**
+ * Facebook Messenger Platform - Customer Feedback Webhook Types
+ *
+ * These types represent the webhook event structure for messaging_feedback events.
+ * Triggered when a user submits feedback through a Customer Feedback Template.
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/send-messages/templates/customer-feedback-template
+ */
+/**
+ * Available feedback types for customer feedback templates
+ */
+declare enum FeedbackType {
+    /** Customer Satisfaction - Score range 1-5 */
+    CSAT = "csat",
+    /** Net Promoter Score - Score range 0-10 */
+    NPS = "nps",
+    /** Customer Effort Score - Score range 1-7 */
+    CES = "ces"
+}
+/**
+ * Available display options for CSAT feedback type
+ */
+declare enum CSATDisplayOption {
+    /** Numeric scale from 1 to 5 */
+    ONE_TO_FIVE = "one_to_five",
+    /** Five star rating display */
+    FIVE_STARS = "five_stars",
+    /** Five emoji rating display */
+    FIVE_EMOJIS = "five_emojis"
+}
+/**
+ * Available display options for NPS feedback type
+ */
+declare enum NPSDisplayOption {
+    /** Numeric scale from 0 to 10 */
+    ZERO_TO_TEN = "zero_to_ten"
+}
+/**
+ * Available display options for CES feedback type
+ */
+declare enum CESDisplayOption {
+    /** Numeric scale from 1 to 7 */
+    ONE_TO_SEVEN = "one_to_seven"
+}
+/**
+ * Follow-up feedback type for optional text input
+ */
+declare enum FollowUpType {
+    /** Free-form text input (max 400 characters) */
+    FREE_FORM = "free_form"
+}
+/**
+ * Represents the sender information in a messaging feedback webhook event
+ */
+interface MessagingFeedbackSender {
+    /** Page-scoped ID (PSID) of the user who submitted the feedback */
+    id: string;
+    /**
+     * User reference provided by the chat plugin, if applicable.
+     * Only present for chat plugin events.
+     */
+    user_ref?: string;
+}
+/**
+ * Represents the recipient information in a messaging feedback webhook event
+ */
+interface MessagingFeedbackRecipient {
+    /** Page ID that received the feedback */
+    id: string;
+}
+/**
+ * Represents optional follow-up feedback data
+ */
+interface FeedbackFollowUp {
+    /** Type of follow-up feedback - currently only supports free_form */
+    type: FollowUpType.FREE_FORM;
+    /**
+     * User-provided text feedback.
+     * Limited to 400 characters maximum.
+     */
+    payload: string;
+}
+/**
+ * Represents individual question feedback data within a screen
+ */
+interface FeedbackQuestion {
+    /**
+     * Type of feedback question (CSAT, NPS, or CES).
+     * Determines the scoring range and display format.
+     */
+    type: FeedbackType;
+    /**
+     * Numeric score provided by the user.
+     * Range depends on feedback type:
+     * - CSAT: 1-5
+     * - NPS: 0-10
+     * - CES: 1-7
+     */
+    payload: string;
+    /**
+     * Optional follow-up text feedback from the user.
+     * Only present if the template included a text input field.
+     */
+    follow_up?: FeedbackFollowUp;
+}
+/**
+ * Represents a feedback screen containing questions and responses
+ */
+interface FeedbackScreen {
+    /**
+     * Screen identifier within the feedback template.
+     * Typically 0 for single-screen templates.
+     */
+    screen_id: number;
+    /**
+     * Map of question IDs to their corresponding feedback responses.
+     * Question IDs are defined when creating the feedback template.
+     */
+    questions: Record<string, FeedbackQuestion>;
+}
+/**
+ * Main messaging feedback data structure
+ */
+interface MessagingFeedbackData {
+    /**
+     * Array of feedback screens with user responses.
+     * Each screen contains questions and their answers.
+     */
+    feedback_screens: FeedbackScreen[];
+}
+/**
+ * Main webhook event structure for messaging feedback
+ *
+ * This event is triggered when a user submits feedback through a
+ * Customer Feedback Template. The webhook provides the user's
+ * scores and optional text feedback.
+ *
+ * @example
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1458668856463,
+ *   "messaging_feedback": {
+ *     "feedback_screens": [{
+ *       "screen_id": 0,
+ *       "questions": {
+ *         "satisfaction_q1": {
+ *           "type": "csat",
+ *           "payload": "4",
+ *           "follow_up": {
+ *             "type": "free_form",
+ *             "payload": "Good service overall!"
+ *           }
+ *         }
+ *       }
+ *     }]
+ *   }
+ * }
+ * ```
+ */
+interface MessagingFeedbackWebhookEvent {
+    /** Information about the user who submitted the feedback */
+    sender: MessagingFeedbackSender;
+    /** Information about the page that received the feedback */
+    recipient: MessagingFeedbackRecipient;
+    /**
+     * Timestamp when the feedback was submitted (in milliseconds since epoch).
+     * Represents when the user completed and submitted the feedback form.
+     */
+    timestamp: number;
+    /** The actual feedback data containing user responses */
+    messaging_feedback: MessagingFeedbackData;
+}
+/**
+ * Complete webhook payload structure that includes the messaging feedback event
+ * along with other webhook metadata
+ */
+interface MessagingFeedbackWebhookPayload {
+    /** The webhook object type - always "page" for Messenger */
+    object: 'page';
+    /** Array of webhook entries containing the actual events */
+    entry: Array<{
+        /** Page ID */
+        id: string;
+        /** Timestamp of the webhook entry */
+        time: number;
+        /** Array of messaging events - contains the feedback event */
+        messaging: MessagingFeedbackWebhookEvent[];
+    }>;
+}
+/**
+ * Type guard to check if a webhook event is a messaging feedback event
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event contains a messaging_feedback property
+ *
+ * @example
+ * ```typescript
+ * if (isMessagingFeedbackEvent(event)) {
+ *   // TypeScript now knows event has messaging_feedback property
+ *   console.log(`Received feedback with ${event.messaging_feedback.feedback_screens.length} screens`);
+ * }
+ * ```
+ */
+declare function isMessagingFeedbackEvent(event: any): event is MessagingFeedbackWebhookEvent;
+/**
+ * Utility type for common feedback properties that might be used in processing
+ */
+interface MessagingFeedbackProcessingContext {
+    /** The user who submitted the feedback */
+    senderId: string;
+    /** The page that received the feedback */
+    recipientId: string;
+    /** When the feedback was submitted */
+    submissionTimestamp: number;
+    /** Total number of feedback screens */
+    screenCount: number;
+    /** All question responses flattened from all screens */
+    allResponses: Array<{
+        questionId: string;
+        feedbackType: FeedbackType;
+        score: number;
+        textFeedback?: string;
+        screenId: number;
+    }>;
+}
+/**
+ * Helper function to extract processing context from a messaging feedback event
+ *
+ * @param event - The messaging feedback webhook event
+ * @returns Simplified processing context with flattened responses
+ *
+ * @example
+ * ```typescript
+ * const context = extractMessagingFeedbackContext(webhookEvent);
+ * console.log(`User ${context.senderId} submitted ${context.allResponses.length} feedback responses`);
+ * context.allResponses.forEach(response => {
+ *   console.log(`${response.questionId}: ${response.score}/10 (${response.feedbackType})`);
+ * });
+ * ```
+ */
+declare function extractMessagingFeedbackContext(event: MessagingFeedbackWebhookEvent): MessagingFeedbackProcessingContext;
+/**
+ * Helper function to get feedback scores by type from an event
+ *
+ * @param event - The messaging feedback webhook event
+ * @returns Map of feedback types to their scores
+ *
+ * @example
+ * ```typescript
+ * const scores = getFeedbackScoresByType(webhookEvent);
+ * const csatScore = scores.get(FeedbackType.CSAT); // number | undefined
+ * const npsScore = scores.get(FeedbackType.NPS);   // number | undefined
+ * ```
+ */
+declare function getFeedbackScoresByType(event: MessagingFeedbackWebhookEvent): Map<FeedbackType, number[]>;
+/**
+ * Helper function to extract all text feedback from an event
+ *
+ * @param event - The messaging feedback webhook event
+ * @returns Array of text feedback strings
+ *
+ * @example
+ * ```typescript
+ * const textFeedback = extractTextFeedback(webhookEvent);
+ * textFeedback.forEach(feedback => {
+ *   console.log(`User comment: "${feedback}"`);
+ * });
+ * ```
+ */
+declare function extractTextFeedback(event: MessagingFeedbackWebhookEvent): string[];
+/**
+ * Constants related to customer feedback constraints and limits
+ */
+declare const MESSAGING_FEEDBACK_CONSTANTS: {
+    /** Maximum characters allowed in free-form text feedback */
+    readonly MAX_TEXT_FEEDBACK_LENGTH: 400;
+    /** Score ranges for different feedback types */
+    readonly SCORE_RANGES: {
+        readonly csat: {
+            readonly min: 1;
+            readonly max: 5;
+        };
+        readonly nps: {
+            readonly min: 0;
+            readonly max: 10;
+        };
+        readonly ces: {
+            readonly min: 1;
+            readonly max: 7;
+        };
+    };
+    /** Template expiry constraints */
+    readonly TEMPLATE_EXPIRY: {
+        /** Minimum expiry days */
+        readonly MIN_DAYS: 1;
+        /** Maximum expiry days */
+        readonly MAX_DAYS: 7;
+        /** Default expiry days */
+        readonly DEFAULT_DAYS: 1;
+    };
+    /** Question ID constraints */
+    readonly QUESTION_ID: {
+        /** Maximum length for question IDs */
+        readonly MAX_LENGTH: 80;
+        /** Valid characters pattern (alphanumeric) */
+        readonly VALID_PATTERN: RegExp;
+    };
+    /** Template limits */
+    readonly TEMPLATE_LIMITS: {
+        /** Maximum number of titles per template */
+        readonly MAX_TITLES: 1;
+        /** Maximum number of scoring components per template */
+        readonly MAX_SCORING_COMPONENTS: 1;
+    };
+    /** Webhook event type identifier */
+    readonly EVENT_TYPE: "messaging_feedback";
+};
+/**
+ * Validation helper to check if a score is valid for a given feedback type
+ *
+ * @param feedbackType - The type of feedback being validated
+ * @param score - The score to validate
+ * @returns True if the score is within the valid range for the feedback type
+ *
+ * @example
+ * ```typescript
+ * const isValid = isValidFeedbackScore(FeedbackType.CSAT, 4); // true
+ * const isInvalid = isValidFeedbackScore(FeedbackType.NPS, 15); // false
+ * ```
+ */
+declare function isValidFeedbackScore(feedbackType: FeedbackType, score: number): boolean;
+/**
+ * Validation helper to check if a question ID is valid
+ *
+ * @param questionId - The question ID to validate
+ * @returns True if the question ID meets the format requirements
+ *
+ * @example
+ * ```typescript
+ * const isValid = isValidQuestionId('satisfaction_q1'); // true
+ * const isInvalid = isValidQuestionId('invalid-id!'); // false
+ * ```
+ */
+declare function isValidQuestionId(questionId: string): boolean;
+/**
+ * Validation helper to check if text feedback is within character limits
+ *
+ * @param textFeedback - The text feedback to validate
+ * @returns True if the text is within the character limit
+ *
+ * @example
+ * ```typescript
+ * const isValid = isValidTextFeedback('Great service!'); // true
+ * const isInvalid = isValidTextFeedback('a'.repeat(500)); // false
+ * ```
+ */
+declare function isValidTextFeedback(textFeedback: string): boolean;
+
+/**
+ * Facebook Messenger Platform - Messages Webhook Types
+ *
+ * These types represent the webhook event structure for messages events.
+ * Triggered when a user sends a message to your page.
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+ */
+/**
+ * Enumeration of attachment types supported by the Messenger Platform
+ */
+declare enum AttachmentType {
+    AUDIO = "audio",
+    FILE = "file",
+    IMAGE = "image",
+    VIDEO = "video",
+    FALLBACK = "fallback",
+    REEL = "reel",
+    IG_REEL = "ig_reel"
+}
+/**
+ * Enumeration of referral types for message referrals
+ */
+declare enum ReferralType {
+    OPEN_THREAD = "OPEN_THREAD",
+    PRODUCT = "product",
+    ADS = "ads"
+}
+/**
+ * Enumeration of referral sources
+ */
+declare enum ReferralSource {
+    MESSENGER_CODE = "MESSENGER_CODE",
+    DISCOVER_TAB = "DISCOVER_TAB",
+    ADS = "ADS",
+    SHORTLINK = "SHORTLINK",
+    CUSTOMER_CHAT_PLUGIN = "CUSTOMER_CHAT_PLUGIN"
+}
+/**
+ * Represents the sender information in a message webhook event
+ */
+interface MessageSender {
+    /** Page-scoped ID (PSID) of the user who sent the message */
+    id: string;
+    /**
+     * User reference provided by the chat plugin, if applicable.
+     * Only present for chat plugin events.
+     */
+    user_ref?: string;
+}
+/**
+ * Represents the recipient information in a message webhook event
+ */
+interface MessageRecipient {
+    /** Page ID that received the message */
+    id: string;
+}
+/**
+ * Represents a quick reply payload in a message
+ */
+interface QuickReply {
+    /**
+     * The payload string that was defined when the quick reply was sent.
+     * Maximum 1000 characters.
+     */
+    payload: string;
+}
+/**
+ * Represents the reply-to information when a message is a reply
+ */
+interface ReplyTo {
+    /**
+     * Message ID of the message being replied to
+     */
+    mid: string;
+}
+/**
+ * Base attachment payload interface
+ */
+interface BaseAttachmentPayload {
+    /** URL to the attachment file */
+    url: string;
+}
+/**
+ * Attachment payload for media files (audio, image, video, file)
+ */
+interface MediaAttachmentPayload extends BaseAttachmentPayload {
+    /** URL to the attachment file */
+    url: string;
+    /** Title of the attachment, if available */
+    title?: string;
+}
+/**
+ * Attachment payload for sticker attachments
+ */
+interface StickerAttachmentPayload extends BaseAttachmentPayload {
+    /** URL to the sticker image */
+    url: string;
+    /** Sticker ID for the sent sticker */
+    sticker_id: number;
+}
+/**
+ * Attachment payload for reel attachments (Instagram Reels, Facebook Reels)
+ */
+interface ReelAttachmentPayload extends BaseAttachmentPayload {
+    /** URL to the reel */
+    url: string;
+    /** Video ID of the reel */
+    reel_video_id?: number;
+}
+/**
+ * Attachment payload for fallback attachments
+ */
+interface FallbackAttachmentPayload extends BaseAttachmentPayload {
+    /** URL to the attachment */
+    url: string;
+    /** Title of the fallback attachment */
+    title?: string;
+}
+/**
+ * Union type for all possible attachment payload types
+ */
+type AttachmentPayload = MediaAttachmentPayload | StickerAttachmentPayload | ReelAttachmentPayload | FallbackAttachmentPayload;
+/**
+ * Represents an attachment in a message
+ */
+interface MessageAttachment {
+    /** The type of attachment */
+    type: AttachmentType;
+    /** The attachment payload containing the actual attachment data */
+    payload: AttachmentPayload;
+}
+/**
+ * Represents referral data in a message (for referral campaigns, ads, etc.)
+ */
+interface MessageReferral {
+    /** The source of the referral */
+    source: ReferralSource;
+    /** The type of referral */
+    type: ReferralType;
+    /**
+     * The optional ref parameter passed in the referral.
+     * Maximum 250 characters.
+     */
+    ref?: string;
+    /**
+     * URL of the website where the referral was triggered.
+     * Only present for CUSTOMER_CHAT_PLUGIN source.
+     */
+    referer_uri?: string;
+    /**
+     * Indicates whether the referral is from a guest user.
+     * Only present for CUSTOMER_CHAT_PLUGIN source.
+     */
+    is_guest_user?: boolean;
+    /**
+     * Product information for product referrals.
+     * Only present when type is 'product'.
+     */
+    product?: {
+        /** Product ID */
+        id: string;
+    };
+    /**
+     * Ad information for ad referrals.
+     * Only present when type is 'ads'.
+     */
+    ads?: {
+        /** Ad ID */
+        id: string;
+        /** Ad title */
+        title?: string;
+        /** Ad image URL */
+        image_url?: string;
+    };
+}
+/**
+ * Represents a command in a message (for bot commands)
+ */
+interface MessageCommand {
+    /** The name of the command */
+    name: string;
+}
+/**
+ * Represents the main message content in a webhook event
+ */
+interface Message {
+    /**
+     * Unique message identifier
+     */
+    mid: string;
+    /**
+     * Text content of the message.
+     * Present for text messages and messages with quick replies.
+     * Maximum 2000 UTF-8 characters.
+     */
+    text?: string;
+    /**
+     * Quick reply payload, if the message was sent as a response to a quick reply.
+     * Only present when the user taps a quick reply button.
+     */
+    quick_reply?: QuickReply;
+    /**
+     * Reply-to information, if this message is a reply to another message.
+     * Only present when the user replies to a specific message.
+     */
+    reply_to?: ReplyTo;
+    /**
+     * Array of attachments sent with the message.
+     * Can include images, audio, video, files, location, etc.
+     */
+    attachments?: MessageAttachment[];
+    /**
+     * Referral information, if the message came from a referral.
+     * Present when users click on ads, m.me links, etc.
+     */
+    referral?: MessageReferral;
+    /**
+     * Array of commands, if the message contains bot commands.
+     * Present when users send commands like /start, /help, etc.
+     */
+    commands?: MessageCommand[];
+}
+/**
+ * Main webhook event structure for messages
+ *
+ * This event is triggered when a user sends a message to your page.
+ * The webhook provides the message content and metadata.
+ *
+ * @example Text message:
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1458668856463,
+ *   "message": {
+ *     "mid": "mid.1458668856218:ed81099e15d3f4f233",
+ *     "text": "Hello, world!"
+ *   }
+ * }
+ * ```
+ *
+ * @example Message with attachment:
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1458668856463,
+ *   "message": {
+ *     "mid": "mid.1458668856218:ed81099e15d3f4f233",
+ *     "attachments": [
+ *       {
+ *         "type": "image",
+ *         "payload": {
+ *           "url": "https://scontent.xx.fbcdn.net/v/image.jpg"
+ *         }
+ *       }
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * @example Message with quick reply:
+ * ```json
+ * {
+ *   "sender": {
+ *     "id": "1234567890123456"
+ *   },
+ *   "recipient": {
+ *     "id": "9876543210987654"
+ *   },
+ *   "timestamp": 1458668856463,
+ *   "message": {
+ *     "mid": "mid.1458668856218:ed81099e15d3f4f233",
+ *     "text": "Yes",
+ *     "quick_reply": {
+ *       "payload": "YES_PAYLOAD"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface MessageWebhookEvent {
+    /** Information about the user who sent the message */
+    sender: MessageSender;
+    /** Information about the page that received the message */
+    recipient: MessageRecipient;
+    /**
+     * Timestamp when the message was sent (in milliseconds since epoch).
+     * Note: This represents when the message was sent, not when it was received.
+     */
+    timestamp: number;
+    /** The message content and metadata */
+    message: Message;
+}
+/**
+ * Complete webhook payload structure that includes the message event
+ * along with other webhook metadata
+ */
+interface MessageWebhookPayload {
+    /** The webhook object type - always "page" for Messenger */
+    object: 'page';
+    /** Array of webhook entries containing the actual events */
+    entry: Array<{
+        /** Page ID */
+        id: string;
+        /** Timestamp of the webhook entry */
+        time: number;
+        /** Array of messaging events - contains the message event */
+        messaging: MessageWebhookEvent[];
+    }>;
+}
+/**
+ * Type guard to check if a webhook event is a message event
+ *
+ * @param event - The webhook event to check
+ * @returns True if the event contains a message property
+ *
+ * @example
+ * ```typescript
+ * if (isMessageEvent(event)) {
+ *   // TypeScript now knows event has message property
+ *   console.log(`Received message: ${event.message.text || '[attachment]'}`);
+ * }
+ * ```
+ */
+declare function isMessageEvent(event: any): event is MessageWebhookEvent;
+/**
+ * Type guard to check if a message has text content
+ *
+ * @param message - The message to check
+ * @returns True if the message has text content
+ */
+declare function isTextMessage(message: Message): message is Message & {
+    text: string;
+};
+/**
+ * Type guard to check if a message has attachments
+ *
+ * @param message - The message to check
+ * @returns True if the message has attachments
+ */
+declare function hasAttachments(message: Message): message is Message & {
+    attachments: MessageAttachment[];
+};
+/**
+ * Type guard to check if a message has a quick reply
+ *
+ * @param message - The message to check
+ * @returns True if the message has a quick reply
+ */
+declare function hasQuickReply(message: Message): message is Message & {
+    quick_reply: QuickReply;
+};
+/**
+ * Type guard to check if a message is a reply to another message
+ *
+ * @param message - The message to check
+ * @returns True if the message is a reply
+ */
+declare function isReplyMessage(message: Message): message is Message & {
+    reply_to: ReplyTo;
+};
+/**
+ * Type guard to check if a message has referral data
+ *
+ * @param message - The message to check
+ * @returns True if the message has referral data
+ */
+declare function hasReferral(message: Message): message is Message & {
+    referral: MessageReferral;
+};
+/**
+ * Type guard to check if an attachment is a specific type
+ *
+ * @param attachment - The attachment to check
+ * @param type - The attachment type to check for
+ * @returns True if the attachment is of the specified type
+ */
+declare function isAttachmentType<T extends AttachmentType>(attachment: MessageAttachment, type: T): attachment is MessageAttachment & {
+    type: T;
+};
+/**
+ * Utility type for common message properties that might be used in processing
+ */
+interface MessageProcessingContext {
+    /** The message ID */
+    messageId: string;
+    /** The user who sent the message */
+    senderId: string;
+    /** The page that received the message */
+    recipientId: string;
+    /** Message text content, if available */
+    text?: string;
+    /** Whether the message has attachments */
+    hasAttachments: boolean;
+    /** Whether the message is a quick reply */
+    isQuickReply: boolean;
+    /** Whether the message is a reply to another message */
+    isReply: boolean;
+    /** Whether the message has referral data */
+    hasReferral: boolean;
+    /** When the message was sent */
+    timestamp: number;
+    /** Quick reply payload, if available */
+    quickReplyPayload?: string;
+    /** Replied message ID, if this is a reply */
+    repliedToMessageId?: string;
+}
+/**
+ * Helper function to extract processing context from a message event
+ *
+ * @param event - The message webhook event
+ * @returns Simplified processing context
+ *
+ * @example
+ * ```typescript
+ * const context = extractMessageContext(webhookEvent);
+ * console.log(`User ${context.senderId} sent: "${context.text || '[attachment]'}"`);
+ * if (context.isQuickReply) {
+ *   console.log(`Quick reply payload: ${context.quickReplyPayload}`);
+ * }
+ * ```
+ */
+declare function extractMessageContext(event: MessageWebhookEvent): MessageProcessingContext;
+/**
+ * Helper function to get attachments of a specific type from a message
+ *
+ * @param message - The message to extract attachments from
+ * @param type - The attachment type to filter by
+ * @returns Array of attachments of the specified type
+ *
+ * @example
+ * ```typescript
+ * const images = getAttachmentsByType(message, AttachmentType.IMAGE);
+ * console.log(`Message contains ${images.length} image(s)`);
+ * ```
+ */
+declare function getAttachmentsByType<T extends AttachmentType>(message: Message, type: T): Array<MessageAttachment & {
+    type: T;
+}>;
+/**
+ * Helper function to extract all URLs from message attachments
+ *
+ * @param message - The message to extract URLs from
+ * @returns Array of attachment URLs
+ *
+ * @example
+ * ```typescript
+ * const urls = getAttachmentUrls(message);
+ * console.log(`Message contains ${urls.length} attachment(s)`);
+ * ```
+ */
+declare function getAttachmentUrls(message: Message): string[];
+/**
+ * Constants related to message limits and constraints
+ */
+declare const MESSAGE_CONSTANTS: {
+    /** Maximum length of message text */
+    readonly MAX_TEXT_LENGTH: 2000;
+    /** Maximum length of quick reply payload */
+    readonly MAX_QUICK_REPLY_PAYLOAD_LENGTH: 1000;
+    /** Maximum length of referral ref parameter */
+    readonly MAX_REFERRAL_REF_LENGTH: 250;
+    /** Webhook event type identifier */
+    readonly EVENT_TYPE: "message";
+};
+/**
+ * Common attachment MIME types for validation
+ */
+declare const ATTACHMENT_MIME_TYPES: {
+    readonly image: readonly ["image/jpeg", "image/png", "image/gif", "image/webp"];
+    readonly video: readonly ["video/mp4", "video/avi", "video/quicktime", "video/webm"];
+    readonly audio: readonly ["audio/mpeg", "audio/mp4", "audio/wav", "audio/ogg"];
+    readonly file: readonly ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "text/plain"];
+};
+
+/**
+ * Facebook Messenger Webhook Events
+ *
+ * This file provides unified types for all webhook events supported by the Messenger Platform.
+ * It includes a discriminated union type that allows TypeScript to narrow the event type
+ * based on the event properties.
+ *
+ * @module webhooks/webhook-events
+ */
+
+/**
+ * Union type of all possible webhook events
+ */
+type MessengerWebhookEvent = MessageEditWebhookEvent | MessageReactionWebhookEvent | MessageWebhookEvent | MessageReadsWebhookEvent | MessagingFeedbackWebhookEvent | MessagingPostbackWebhookEvent;
+/**
+ * Union type of all possible webhook payloads
+ */
+type MessengerWebhookPayload = MessageEditWebhookPayload | MessageReactionWebhookPayload | MessageWebhookPayload | MessageReadsWebhookPayload | MessagingFeedbackWebhookPayload | MessagingPostbackWebhookPayload;
+/**
+ * Generic webhook entry structure
+ */
+interface WebhookEntry {
+    /** Unique ID of the page */
+    id: string;
+    /** Time of update (epoch time in milliseconds) */
+    time: number;
+    /** Array of messaging events */
+    messaging: MessengerWebhookEvent[];
+}
+/**
+ * Generic webhook payload structure
+ */
+interface GenericWebhookPayload {
+    /** Always 'page' for Messenger webhooks */
+    object: 'page';
+    /** Array of entry objects */
+    entry: WebhookEntry[];
+}
+/**
+ * Webhook event types enum
+ */
+declare enum WebhookEventType {
+    MESSAGE = "message",
+    MESSAGE_EDIT = "message_edit",
+    MESSAGE_REACTION = "reaction",
+    MESSAGE_READ = "read",
+    MESSAGING_FEEDBACK = "messaging_feedback",
+    MESSAGING_POSTBACK = "postback"
+}
+/**
+ * Type guard to check webhook event type
+ */
+declare function getWebhookEventType(event: MessengerWebhookEvent): WebhookEventType | null;
+/**
+ * Extract all events from a webhook payload
+ */
+declare function extractWebhookEvents(payload: GenericWebhookPayload): MessengerWebhookEvent[];
+/**
+ * Process webhook events by type
+ */
+interface WebhookEventHandlers {
+    onMessage?: (event: MessageWebhookEvent) => void | Promise<void>;
+    onMessageEdit?: (event: MessageEditWebhookEvent) => void | Promise<void>;
+    onMessageReaction?: (event: MessageReactionWebhookEvent) => void | Promise<void>;
+    onMessageRead?: (event: MessageReadsWebhookEvent) => void | Promise<void>;
+    onMessagingFeedback?: (event: MessagingFeedbackWebhookEvent) => void | Promise<void>;
+    onMessagingPostback?: (event: MessagingPostbackWebhookEvent) => void | Promise<void>;
+    onUnknown?: (event: any) => void | Promise<void>;
+}
+/**
+ * Process webhook events with type-safe handlers
+ */
+declare function processWebhookEvents(payload: GenericWebhookPayload, handlers: WebhookEventHandlers): Promise<void>;
+/**
+ * Webhook verification parameters
+ */
+interface WebhookVerificationParams {
+    'hub.mode': string;
+    'hub.verify_token': string;
+    'hub.challenge': string;
+}
+/**
+ * Verify webhook subscription
+ */
+declare function verifyWebhookSubscription(params: WebhookVerificationParams, verifyToken: string): string | null;
+
 declare class MessengerAPIError extends Error {
     readonly code: number;
     readonly type: string;
@@ -381,4 +2200,4 @@ declare const TEMPLATE_LIMITS: {
     readonly MEDIA_BUTTONS_MAX_COUNT: 3;
 };
 
-export { ATTACHMENT_LIMITS, type AttachmentType, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsAPI, type Button, type ButtonTemplatePayload, type DefaultAction, type ErrorResponse, type GenericTemplateElement, type GenericTemplatePayload, type GetProfileRequest, MESSAGE_LIMITS, type MediaTemplateElement, type MediaTemplatePayload, type Message, MessageValidationError, type MessagingType, Messenger, MessengerAPIError, type MessengerConfig, MessengerConfigError, type MessengerError, MessengerNetworkError, MessengerTimeoutError, type ModerateConversationsRequest, type ModerateConversationsResponse, ModerationAPI, type ModerationAction, type ProductTemplateElement, type ProductTemplatePayload, ProfileAPI, type ProfileField, type QuickReply, type Recipient, SendAPI, type SendMessageRequest, type SendMessageResponse, type SenderAction, TEMPLATE_LIMITS, TemplateValidationError, TemplatesAPI, type UserId, type UserProfile };
+export { ATTACHMENT_LIMITS, ATTACHMENT_MIME_TYPES, type AttachmentPayload, type AttachmentType$1 as AttachmentType, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsAPI, type Button, type ButtonTemplatePayload, CESDisplayOption, COMMON_POSTBACK_PAYLOADS, CSATDisplayOption, type DefaultAction, type ErrorResponse, type FallbackAttachmentPayload, type FeedbackFollowUp, type FeedbackQuestion, type FeedbackScreen, FeedbackType, FollowUpType, type GenericTemplateElement, type GenericTemplatePayload, type GenericWebhookPayload, type GetProfileRequest, MESSAGE_CONSTANTS, MESSAGE_EDIT_CONSTANTS, MESSAGE_LIMITS, MESSAGE_READS_CONSTANTS, MESSAGING_FEEDBACK_CONSTANTS, type MediaAttachmentPayload, type MediaTemplateElement, type MediaTemplatePayload, type Message$1 as Message, type MessageAttachment, type MessageCommand, type MessageEdit, type MessageEditProcessingContext, type MessageEditRecipient, type MessageEditSender, type MessageEditWebhookEvent, type MessageEditWebhookPayload, type MessageProcessingContext, MessageReactionAction, type MessageReactionData, type MessageReactionProcessingContext, type MessageReactionRecipient, type MessageReactionSender, type MessageReactionStats, MessageReactionType, type MessageReactionWebhookConfig, type MessageReactionWebhookEvent, type MessageReactionWebhookPayload, type MessageReadData, type MessageReadsProcessingContext, type MessageReadsWebhookEvent, type MessageReadsWebhookPayload, type MessageRecipient, type MessageReferral, ReferralSource as MessageReferralSource, ReferralType as MessageReferralType, type MessageSender, MessageValidationError, type MessageWebhookEvent, type MessageWebhookPayload, type MessagingFeedbackData, type MessagingFeedbackProcessingContext, type MessagingFeedbackWebhookEvent, type MessagingFeedbackWebhookPayload, type MessagingPostbackWebhookEvent, type MessagingPostbackWebhookPayload, type MessagingType, Messenger, MessengerAPIError, type MessengerConfig, MessengerConfigError, type MessengerError, MessengerNetworkError, MessengerTimeoutError, type MessengerWebhookEvent, type MessengerWebhookPayload, type ModerateConversationsRequest, type ModerateConversationsResponse, ModerationAPI, type ModerationAction, NPSDisplayOption, POSTBACK_CONSTANTS, type PostbackData, type PostbackEventData, type PostbackPayload, type PostbackProcessingContext, type PostbackRecipient, type PostbackReferral, type PostbackSender, type ProductTemplateElement, type ProductTemplatePayload, ProfileAPI, type ProfileField, type QuickReply$1 as QuickReply, type Recipient, type ReelAttachmentPayload, type ReferralSource$1 as ReferralSource, type ReferralType$1 as ReferralType, type ReplyTo, SendAPI, type SendMessageRequest, type SendMessageResponse, type SenderAction, type StickerAttachmentPayload, TEMPLATE_LIMITS, TemplateValidationError, TemplatesAPI, type UserId, type UserProfile, type WatermarkTimestamp, AttachmentType as WebhookAttachmentType, type WebhookEntry, type WebhookEventHandlers, WebhookEventType, type Message as WebhookMessage, type QuickReply as WebhookQuickReply, type WebhookVerificationParams, extractMessageContext, extractMessageEditContext, extractMessageReadsContext, extractMessagingFeedbackContext, extractPostbackContext, extractTextFeedback, extractWebhookEvents, getAttachmentUrls, getAttachmentsByType, getFeedbackScoresByType, getReadMessageCount, getReadMessages, getWebhookEventType, hasAttachments, hasQuickReply, hasReferral, hasReferralData, isAttachmentType, isIdentifiedSender, isMessageEditEvent, isMessageEvent, isMessageRead, isMessageReadsEvent, isMessagingFeedbackEvent, isMessagingPostbackEvent, isReplyMessage, isTextMessage, isValidFeedbackScore, isValidQuestionId, isValidTextFeedback, processWebhookEvents, verifyWebhookSubscription };