@warriorteam/messenger-sdk 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -336,32 +336,114 @@ declare class Messenger {
 }
 
 /**
- * Facebook Messenger Platform - Message Edits Webhook Types
+ * Facebook Messenger Platform - Base Webhook Types
  *
- * These types represent the webhook event structure for message_edits events.
- * Triggered when a user edits a previously sent message.
+ * This file contains the common base types and interfaces shared across
+ * all webhook event types. It provides the foundation for a properly
+ * structured type system with inheritance and discriminated unions.
  *
- * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-edits/
+ * @module webhooks/base-types
  */
 /**
- * Represents the sender information in a message edit webhook event
+ * Common sender interface for all webhook events.
+ * Represents the user who initiated the action.
  */
-interface MessageEditSender {
-    /** Page-scoped ID (PSID) of the user who sent the message */
+interface WebhookSender {
+    /**
+     * Page-scoped ID (PSID) of the user.
+     * 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.
+     * Only present for chat plugin events where the user hasn't been identified yet.
      */
     user_ref?: string;
 }
 /**
- * Represents the recipient information in a message edit webhook event
+ * Common recipient interface for all webhook events.
+ * Represents the Facebook Page that received the event.
+ */
+interface WebhookRecipient {
+    /** Facebook Page ID that received the event */
+    id: string;
+}
+/**
+ * Base interface for all webhook events.
+ * Contains the common properties shared by all event types.
+ */
+interface BaseWebhookEvent {
+    /** Information about the user who initiated the event */
+    sender: WebhookSender;
+    /** Information about the page that received the event */
+    recipient: WebhookRecipient;
+    /**
+     * Unix timestamp when the event occurred (in milliseconds since epoch).
+     * Represents when the action was performed, not when the webhook was sent.
+     */
+    timestamp: number;
+}
+/**
+ * Webhook event types enum with discriminator values.
+ * Used for type narrowing in discriminated unions.
+ */
+declare enum WebhookEventType {
+    MESSAGE = "message",
+    MESSAGE_EDIT = "message_edit",
+    MESSAGE_REACTION = "reaction",
+    MESSAGE_READ = "read",
+    MESSAGING_FEEDBACK = "messaging_feedback",
+    MESSAGING_POSTBACK = "postback"
+}
+/**
+ * Generic webhook entry structure.
+ * Represents a single entry in the webhook payload.
  */
-interface MessageEditRecipient {
-    /** Page ID that received the message */
+interface WebhookEntry<T extends BaseWebhookEvent = BaseWebhookEvent> {
+    /** Unique ID of the page */
     id: string;
+    /** Time of update (epoch time in milliseconds) */
+    time: number;
+    /** Array of messaging events */
+    messaging: T[];
+}
+/**
+ * Generic webhook payload structure.
+ * This is the top-level structure received from Facebook webhooks.
+ */
+interface WebhookPayload<T extends BaseWebhookEvent = BaseWebhookEvent> {
+    /** Always 'page' for Messenger webhooks */
+    object: 'page';
+    /** Array of entry objects containing the actual events */
+    entry: WebhookEntry<T>[];
+}
+/**
+ * Common processing context for all webhook events
+ */
+interface BaseProcessingContext {
+    /** The user who initiated the event (PSID or user_ref) */
+    senderId?: string;
+    /** User reference for anonymous users */
+    userRef?: string;
+    /** The page that received the event */
+    recipientId: string;
+    /** When the event occurred */
+    timestamp: number;
+    /** Whether the sender is identified (has PSID) */
+    isIdentifiedUser: boolean;
+    /** Human-readable datetime for the event timestamp */
+    eventDate: Date;
 }
+
+/**
+ * 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 edited message information
  */
@@ -382,7 +464,7 @@ interface MessageEdit {
     num_edit: number;
 }
 /**
- * Main webhook event structure for message edits
+ * Main webhook event structure for message edits with discriminator
  *
  * This event is triggered when a user edits a previously sent message.
  * The webhook provides the updated message content and edit count.
@@ -390,6 +472,7 @@ interface MessageEdit {
  * @example
  * ```json
  * {
+ *   "type": "message_edit",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -405,16 +488,9 @@ interface MessageEdit {
  * }
  * ```
  */
-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;
+interface MessageEditWebhookEvent extends BaseWebhookEvent {
+    /** Discriminator for type narrowing */
+    type: WebhookEventType.MESSAGE_EDIT;
     /** Details about the edited message */
     message_edit: MessageEdit;
 }
@@ -422,18 +498,7 @@ interface MessageEditWebhookEvent {
  * 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[];
-    }>;
+interface MessageEditWebhookPayload extends WebhookPayload<MessageEditWebhookEvent> {
 }
 /**
  * Type guard to check if a webhook event is a message edit event
@@ -453,19 +518,13 @@ declare function isMessageEditEvent(event: any): event is MessageEditWebhookEven
 /**
  * Utility type for common message edit properties that might be used in processing
  */
-interface MessageEditProcessingContext {
+interface MessageEditProcessingContext extends BaseProcessingContext {
     /** 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
@@ -498,6 +557,7 @@ declare const MESSAGE_EDIT_CONSTANTS: {
  *
  * @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.
@@ -529,26 +589,7 @@ declare enum MessageReactionAction {
     /** 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.
  */
@@ -574,19 +615,12 @@ interface MessageReactionData {
     mid: string;
 }
 /**
- * Complete webhook event structure for message reactions.
+ * Complete webhook event structure for message reactions with discriminator.
  * 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;
+interface MessageReactionWebhookEvent extends BaseWebhookEvent {
+    /** Discriminator for type narrowing */
+    type: WebhookEventType.MESSAGE_REACTION;
     /** Detailed information about the reaction */
     reaction: MessageReactionData;
 }
@@ -594,18 +628,7 @@ interface MessageReactionWebhookEvent {
  * 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[];
-    }>;
+interface MessageReactionWebhookPayload extends WebhookPayload<MessageReactionWebhookEvent> {
 }
 /**
  * Context object for processing message reaction webhooks.
@@ -670,25 +693,7 @@ interface MessageReactionWebhookConfig {
  *
  * @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
  */
@@ -701,7 +706,7 @@ interface MessageRead {
     watermark: number;
 }
 /**
- * Main webhook event structure for message reads
+ * Main webhook event structure for message reads with discriminator
  *
  * 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.
@@ -709,6 +714,7 @@ interface MessageRead {
  * @example
  * ```json
  * {
+ *   "type": "read",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -722,16 +728,9 @@ interface MessageRead {
  * }
  * ```
  */
-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;
+interface MessageReadsWebhookEvent extends BaseWebhookEvent {
+    /** Discriminator for type narrowing */
+    type: WebhookEventType.MESSAGE_READ;
     /** Read receipt information containing the watermark */
     read: MessageRead;
 }
@@ -739,18 +738,7 @@ interface MessageReadsWebhookEvent {
  * 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[];
-    }>;
+interface MessageReadsWebhookPayload extends WebhookPayload<MessageReadsWebhookEvent> {
 }
 /**
  * Type guard to check if a webhook event is a message reads event
@@ -895,28 +883,7 @@ type WatermarkTimestamp = number;
  *
  * @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
  *
@@ -972,7 +939,7 @@ interface PostbackData {
     referral?: PostbackReferral;
 }
 /**
- * Main webhook event structure for messaging postbacks
+ * Main webhook event structure for messaging postbacks with discriminator
  *
  * This event is triggered when a user interacts with postback buttons,
  * including regular postback buttons, Get Started button, and persistent menu items.
@@ -981,6 +948,7 @@ interface PostbackData {
  * Basic postback from a button click:
  * ```json
  * {
+ *   "type": "postback",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -1000,6 +968,7 @@ interface PostbackData {
  * Postback with referral data from m.me link:
  * ```json
  * {
+ *   "type": "postback",
  *   "sender": {
  *     "user_ref": "unique_ref_param"
  *   },
@@ -1019,16 +988,9 @@ interface PostbackData {
  * }
  * ```
  */
-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;
+interface MessagingPostbackWebhookEvent extends BaseWebhookEvent {
+    /** Discriminator for type narrowing */
+    type: WebhookEventType.MESSAGING_POSTBACK;
     /** Details about the postback that was triggered */
     postback: PostbackData;
 }
@@ -1036,18 +998,7 @@ interface MessagingPostbackWebhookEvent {
  * 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[];
-    }>;
+interface MessagingPostbackWebhookPayload extends WebhookPayload<MessagingPostbackWebhookEvent> {
 }
 /**
  * Type guard to check if a webhook event is a messaging postback event
@@ -1102,7 +1053,7 @@ declare function hasReferralData(event: MessagingPostbackWebhookEvent): event is
  * }
  * ```
  */
-declare function isIdentifiedSender(sender: PostbackSender): sender is PostbackSender & {
+declare function isIdentifiedSender(sender: WebhookSender): sender is WebhookSender & {
     id: string;
 };
 /**
@@ -1223,6 +1174,7 @@ type ReferralType$1 = typeof POSTBACK_CONSTANTS.REFERRAL_TYPES[keyof typeof POST
  *
  * @see https://developers.facebook.com/docs/messenger-platform/send-messages/templates/customer-feedback-template
  */
+
 /**
  * Available feedback types for customer feedback templates
  */
@@ -1266,25 +1218,7 @@ 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
  */
@@ -1346,7 +1280,7 @@ interface MessagingFeedbackData {
     feedback_screens: FeedbackScreen[];
 }
 /**
- * Main webhook event structure for messaging feedback
+ * Main webhook event structure for messaging feedback with discriminator
  *
  * This event is triggered when a user submits feedback through a
  * Customer Feedback Template. The webhook provides the user's
@@ -1355,6 +1289,7 @@ interface MessagingFeedbackData {
  * @example
  * ```json
  * {
+ *   "type": "messaging_feedback",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -1380,16 +1315,9 @@ interface MessagingFeedbackData {
  * }
  * ```
  */
-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;
+interface MessagingFeedbackWebhookEvent extends BaseWebhookEvent {
+    /** Discriminator for type narrowing */
+    type: WebhookEventType.MESSAGING_FEEDBACK;
     /** The actual feedback data containing user responses */
     messaging_feedback: MessagingFeedbackData;
 }
@@ -1397,18 +1325,7 @@ interface MessagingFeedbackWebhookEvent {
  * 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[];
-    }>;
+interface MessagingFeedbackWebhookPayload extends WebhookPayload<MessagingFeedbackWebhookEvent> {
 }
 /**
  * Type guard to check if a webhook event is a messaging feedback event
@@ -1587,6 +1504,7 @@ declare function isValidTextFeedback(textFeedback: string): boolean;
  *
  * @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
  */
+
 /**
  * Enumeration of attachment types supported by the Messenger Platform
  */
@@ -1617,25 +1535,7 @@ declare enum ReferralSource {
     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
  */
@@ -1803,7 +1703,7 @@ interface Message {
     commands?: MessageCommand[];
 }
 /**
- * Main webhook event structure for messages
+ * Main webhook event structure for messages with discriminator
  *
  * This event is triggered when a user sends a message to your page.
  * The webhook provides the message content and metadata.
@@ -1811,6 +1711,7 @@ interface Message {
  * @example Text message:
  * ```json
  * {
+ *   "type": "message",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -1828,6 +1729,7 @@ interface Message {
  * @example Message with attachment:
  * ```json
  * {
+ *   "type": "message",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -1852,6 +1754,7 @@ interface Message {
  * @example Message with quick reply:
  * ```json
  * {
+ *   "type": "message",
  *   "sender": {
  *     "id": "1234567890123456"
  *   },
@@ -1869,16 +1772,9 @@ interface Message {
  * }
  * ```
  */
-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;
+interface MessageWebhookEvent extends BaseWebhookEvent {
+    /** Discriminator for type narrowing */
+    type: WebhookEventType.MESSAGE;
     /** The message content and metadata */
     message: Message;
 }
@@ -1886,18 +1782,7 @@ interface MessageWebhookEvent {
  * 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[];
-    }>;
+interface MessageWebhookPayload extends WebhookPayload<MessageWebhookEvent> {
 }
 /**
  * Type guard to check if a webhook event is a message event
@@ -1972,13 +1857,9 @@ declare function isAttachmentType<T extends AttachmentType>(attachment: MessageA
 /**
  * Utility type for common message properties that might be used in processing
  */
-interface MessageProcessingContext {
+interface MessageProcessingContext extends BaseProcessingContext {
     /** 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 */
@@ -1989,8 +1870,6 @@ interface MessageProcessingContext {
     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 */
@@ -2065,17 +1944,18 @@ declare const ATTACHMENT_MIME_TYPES: {
 };
 
 /**
- * Facebook Messenger Webhook Events
+ * Facebook Messenger Webhook Events - Main Entry Point
  *
- * 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.
+ * This file provides the unified type system for all webhook events supported
+ * by the Messenger Platform. It uses discriminated unions with proper type
+ * narrowing to ensure type safety.
  *
  * @module webhooks/webhook-events
  */
 
 /**
- * Union type of all possible webhook events
+ * Discriminated union type of all possible webhook events.
+ * Each event has a 'type' field that allows TypeScript to narrow the type.
  */
 type MessengerWebhookEvent = MessageEditWebhookEvent | MessageReactionWebhookEvent | MessageWebhookEvent | MessageReadsWebhookEvent | MessagingFeedbackWebhookEvent | MessagingPostbackWebhookEvent;
 /**
@@ -2083,46 +1963,59 @@ type MessengerWebhookEvent = MessageEditWebhookEvent | MessageReactionWebhookEve
  */
 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
+ * Type guard to check webhook event type for a SINGLE event.
+ * This function now properly handles individual events from the messaging array.
+ *
+ * @param event - A single webhook event from the messaging array
+ * @returns The event type or null if unknown
+ *
+ * @example
+ * ```typescript
+ * const events = extractWebhookEvents(payload);
+ * for (const event of events) {
+ *   const eventType = getWebhookEventType(event);
+ *   console.log(`Event type: ${eventType}`);
+ * }
+ * ```
  */
-declare function getWebhookEventType(event: MessengerWebhookEvent): WebhookEventType | null;
+declare function getWebhookEventType(event: MessengerWebhookEvent | any): WebhookEventType | null;
 /**
- * Extract all events from a webhook payload
+ * Extract all events from a webhook payload.
+ * This properly extracts individual events from the nested structure.
+ *
+ * @param payload - The complete webhook payload
+ * @returns Array of individual webhook events
+ *
+ * @example
+ * ```typescript
+ * const events = extractWebhookEvents(payload);
+ * events.forEach(event => {
+ *   const type = getWebhookEventType(event);
+ *   console.log(`Processing ${type} event`);
+ * });
+ * ```
  */
-declare function extractWebhookEvents(payload: GenericWebhookPayload): MessengerWebhookEvent[];
+declare function extractWebhookEvents(payload: WebhookPayload): MessengerWebhookEvent[];
 /**
- * Process webhook events by type
+ * Process webhook events by type with proper type narrowing.
+ * This uses the discriminated union for automatic type narrowing.
+ *
+ * @param payload - The complete webhook payload
+ * @param handlers - Object with handler functions for each event type
+ *
+ * @example
+ * ```typescript
+ * processWebhookEvents(payload, {
+ *   onMessage: async (event) => {
+ *     // TypeScript knows event is MessageWebhookEvent
+ *     console.log(`Message: ${event.message.text}`);
+ *   },
+ *   onMessageEdit: async (event) => {
+ *     // TypeScript knows event is MessageEditWebhookEvent
+ *     console.log(`Edited to: ${event.message_edit.text}`);
+ *   }
+ * });
+ * ```
  */
 interface WebhookEventHandlers {
     onMessage?: (event: MessageWebhookEvent) => void | Promise<void>;
@@ -2133,12 +2026,9 @@ interface WebhookEventHandlers {
     onMessagingPostback?: (event: MessagingPostbackWebhookEvent) => void | Promise<void>;
     onUnknown?: (event: any) => void | Promise<void>;
 }
+declare function processWebhookEvents(payload: WebhookPayload, handlers: WebhookEventHandlers): Promise<void>;
 /**
- * Process webhook events with type-safe handlers
- */
-declare function processWebhookEvents(payload: GenericWebhookPayload, handlers: WebhookEventHandlers): Promise<void>;
-/**
- * Webhook verification parameters
+ * Webhook verification parameters for subscription verification
  */
 interface WebhookVerificationParams {
     'hub.mode': string;
@@ -2146,7 +2036,23 @@ interface WebhookVerificationParams {
     'hub.challenge': string;
 }
 /**
- * Verify webhook subscription
+ * Verify webhook subscription during initial setup
+ *
+ * @param params - Query parameters from Facebook's verification request
+ * @param verifyToken - Your webhook verify token
+ * @returns The challenge string if valid, null if invalid
+ *
+ * @example
+ * ```typescript
+ * app.get('/webhook', (req, res) => {
+ *   const challenge = verifyWebhookSubscription(req.query, process.env.VERIFY_TOKEN);
+ *   if (challenge) {
+ *     res.send(challenge);
+ *   } else {
+ *     res.status(403).send('Forbidden');
+ *   }
+ * });
+ * ```
  */
 declare function verifyWebhookSubscription(params: WebhookVerificationParams, verifyToken: string): string | null;
 
@@ -2200,4 +2106,4 @@ declare const TEMPLATE_LIMITS: {
     readonly MEDIA_BUTTONS_MAX_COUNT: 3;
 };
 
-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 };
+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 WebhookPayload as 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 WebhookRecipient as MessageEditRecipient, type WebhookSender as MessageEditSender, type MessageEditWebhookEvent, type MessageEditWebhookPayload, type MessageProcessingContext, MessageReactionAction, type MessageReactionData, type MessageReactionProcessingContext, type WebhookRecipient as MessageReactionRecipient, type WebhookSender as MessageReactionSender, type MessageReactionStats, MessageReactionType, type MessageReactionWebhookConfig, type MessageReactionWebhookEvent, type MessageReactionWebhookPayload, type MessageReadData, type MessageReadsProcessingContext, type MessageReadsWebhookEvent, type MessageReadsWebhookPayload, type WebhookRecipient as MessageRecipient, type MessageReferral, ReferralSource as MessageReferralSource, ReferralType as MessageReferralType, type WebhookSender as 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 WebhookRecipient as PostbackRecipient, type PostbackReferral, type WebhookSender as 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 };