@warriorteam/messenger-sdk 1.4.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -40,7 +40,7 @@ interface QuickReply$1 {
40
40
  payload?: string;
41
41
  image_url?: string;
42
42
  }
43
- interface Message$1 {
43
+ interface Message$2 {
44
44
  text?: string;
45
45
  attachment?: Attachment;
46
46
  quick_replies?: QuickReply$1[];
@@ -66,7 +66,7 @@ type MessagingType = 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG';
66
66
  interface SendMessageRequest {
67
67
  recipient: Recipient;
68
68
  messaging_type: MessagingType;
69
- message?: Message$1;
69
+ message?: Message$2;
70
70
  sender_action?: SenderAction;
71
71
  notification_type?: 'REGULAR' | 'SILENT_PUSH' | 'NO_PUSH';
72
72
  tag?: string;
@@ -317,6 +317,521 @@ declare class ProfileAPI {
317
317
  getProfilePicture(psid: string, options?: APIOptions): Promise<UserProfile>;
318
318
  }
319
319
 
320
+ /**
321
+ * Facebook Messenger Platform - Conversations API Types
322
+ *
323
+ * Type definitions for retrieving conversations and messages between users and Pages/Instagram Business accounts.
324
+ *
325
+ * @see https://developers.facebook.com/docs/messenger-platform/conversations
326
+ */
327
+ /**
328
+ * Platform type for conversations
329
+ */
330
+ type ConversationPlatform = 'instagram' | 'messenger';
331
+ /**
332
+ * Conversation folder types
333
+ */
334
+ type ConversationFolder = 'inbox' | 'pending' | 'spam';
335
+ /**
336
+ * Basic conversation information
337
+ */
338
+ interface Conversation {
339
+ /** The conversation ID */
340
+ id: string;
341
+ /** Timestamp of the most recent message (Unix timestamp) */
342
+ updated_time: string;
343
+ }
344
+ /**
345
+ * Participant in a conversation
346
+ */
347
+ interface ConversationParticipant {
348
+ /** Instagram-scoped ID or Page-scoped ID of a person, or Page ID, or Instagram Business Account ID */
349
+ id: string;
350
+ /** Email of the person or Page (Messenger only) */
351
+ email?: string;
352
+ /** Name of the person or Page (Messenger only) */
353
+ name?: string;
354
+ /** Instagram username of a person or your Instagram Business Account (Instagram only) */
355
+ username?: string;
356
+ }
357
+ /**
358
+ * Detailed conversation with messages and participants
359
+ */
360
+ interface ConversationDetail {
361
+ /** The conversation ID */
362
+ id: string;
363
+ /** Messages in the conversation */
364
+ messages?: {
365
+ data: MessageBasic[];
366
+ paging?: {
367
+ cursors?: {
368
+ before?: string;
369
+ after?: string;
370
+ };
371
+ next?: string;
372
+ previous?: string;
373
+ };
374
+ };
375
+ /** Participants in the conversation */
376
+ participants?: {
377
+ data: ConversationParticipant[];
378
+ };
379
+ /** Timestamp of the most recent message */
380
+ updated_time?: string;
381
+ }
382
+ /**
383
+ * Basic message information (ID and timestamp)
384
+ */
385
+ interface MessageBasic {
386
+ /** The message ID */
387
+ id: string;
388
+ /** When the message was created (ISO 8601 timestamp) */
389
+ created_time: string;
390
+ }
391
+ /**
392
+ * Message sender/recipient information
393
+ */
394
+ interface MessageParticipant {
395
+ /** Instagram-scoped ID or Page-scoped ID or Instagram Business Account ID */
396
+ id: string;
397
+ /** Email (Messenger only) */
398
+ email?: string;
399
+ /** Name (Messenger only) */
400
+ name?: string;
401
+ /** Instagram username (Instagram only) */
402
+ username?: string;
403
+ }
404
+ /**
405
+ * Message attachment types
406
+ */
407
+ type MessageAttachmentType = 'image' | 'video' | 'audio' | 'file';
408
+ /**
409
+ * Image data in attachment
410
+ */
411
+ interface ImageData {
412
+ /** Preview URL of the image */
413
+ preview_url?: string;
414
+ /** Full URL of the image */
415
+ url?: string;
416
+ /** Width in pixels */
417
+ width?: number;
418
+ /** Height in pixels */
419
+ height?: number;
420
+ /** Max width in pixels */
421
+ max_width?: number;
422
+ /** Max height in pixels */
423
+ max_height?: number;
424
+ /** URL of animated GIF preview */
425
+ animated_gif_preview_url?: string;
426
+ /** URL of animated GIF */
427
+ animated_gif_url?: string;
428
+ /** Whether to render as sticker */
429
+ render_as_sticker?: boolean;
430
+ }
431
+ /**
432
+ * Video data in attachment
433
+ */
434
+ interface VideoData {
435
+ /** URL of the video */
436
+ url?: string;
437
+ /** Width in pixels */
438
+ width?: number;
439
+ /** Height in pixels */
440
+ height?: number;
441
+ /** Preview URL */
442
+ preview_url?: string;
443
+ }
444
+ /**
445
+ * Generic template in attachment
446
+ */
447
+ interface GenericTemplate {
448
+ /** Call-to-action button */
449
+ cta?: {
450
+ title?: string;
451
+ type?: string;
452
+ url?: string;
453
+ };
454
+ /** Media URL */
455
+ media_url?: string;
456
+ /** Subtitle text */
457
+ subtitle?: string;
458
+ /** Title text */
459
+ title?: string;
460
+ }
461
+ /**
462
+ * Message attachment
463
+ */
464
+ interface MessageAttachment$1 {
465
+ /** Attachment ID */
466
+ id?: string;
467
+ /** File URL */
468
+ file_url?: string;
469
+ /** Image data */
470
+ image_data?: ImageData;
471
+ /** Video data */
472
+ video_data?: VideoData;
473
+ /** Generic template */
474
+ generic_template?: GenericTemplate;
475
+ /** File name */
476
+ name?: string;
477
+ }
478
+ /**
479
+ * Reaction to a message
480
+ */
481
+ interface MessageReaction {
482
+ /** Emoji reaction (e.g., "❤️", "😂", "👍") */
483
+ reaction: string;
484
+ /** Users who reacted with this emoji */
485
+ users: Array<{
486
+ id: string;
487
+ username?: string;
488
+ }>;
489
+ }
490
+ /**
491
+ * Reply information
492
+ */
493
+ interface ReplyInfo {
494
+ /** Message ID being replied to */
495
+ mid: string;
496
+ /** Whether this is a self-reply (reply to own message) */
497
+ is_self_reply?: boolean;
498
+ }
499
+ /**
500
+ * Story share/mention
501
+ */
502
+ interface StoryShare {
503
+ /** CDN URL of the story */
504
+ link: string;
505
+ /** Story ID */
506
+ id: string;
507
+ }
508
+ /**
509
+ * Product in a share
510
+ */
511
+ interface SharedProduct {
512
+ /** Product ID (0 if business can't see this product) */
513
+ id: string;
514
+ /** ID assigned by the retailer */
515
+ retailer_id?: string;
516
+ /** Product image URL */
517
+ image_url?: string;
518
+ /** Product name */
519
+ name?: string;
520
+ /** Product price */
521
+ price?: string;
522
+ }
523
+ /**
524
+ * Share template payload
525
+ */
526
+ interface ShareTemplatePayload {
527
+ product?: {
528
+ elements?: {
529
+ data: SharedProduct[];
530
+ };
531
+ };
532
+ }
533
+ /**
534
+ * Shared content
535
+ */
536
+ interface MessageShare {
537
+ /** Share template */
538
+ template?: {
539
+ payload?: ShareTemplatePayload;
540
+ };
541
+ }
542
+ /**
543
+ * Message tags
544
+ */
545
+ interface MessageTag {
546
+ /** Tag name (e.g., "inbox", "read", "source:chat") */
547
+ name: string;
548
+ }
549
+ /**
550
+ * Detailed message information
551
+ */
552
+ interface Message$1 {
553
+ /** The message ID */
554
+ id: string;
555
+ /** When the message was created */
556
+ created_time: string;
557
+ /** Sender information */
558
+ from?: MessageParticipant;
559
+ /** Recipient information */
560
+ to?: {
561
+ data: MessageParticipant[];
562
+ };
563
+ /** Text content of the message (empty if no text) */
564
+ message?: string;
565
+ /** Message attachments */
566
+ attachments?: {
567
+ data: MessageAttachment$1[];
568
+ };
569
+ /** Reactions to the message */
570
+ reactions?: {
571
+ data: MessageReaction[];
572
+ };
573
+ /** Shared content (posts, products, etc.) */
574
+ shares?: {
575
+ data: MessageShare[];
576
+ };
577
+ /** Story reply or mention */
578
+ story?: StoryShare;
579
+ /** Reply information */
580
+ reply_to?: ReplyInfo;
581
+ /** Message tags */
582
+ tags?: {
583
+ data: MessageTag[];
584
+ };
585
+ /** Whether the message contains unsupported content */
586
+ is_unsupported?: boolean;
587
+ }
588
+ /**
589
+ * Request parameters for listing conversations
590
+ */
591
+ interface ListConversationsParams {
592
+ /** Platform to filter by */
593
+ platform?: ConversationPlatform;
594
+ /** User ID to find conversations with specific user */
595
+ user_id?: string;
596
+ /** Folder to filter by */
597
+ folder?: ConversationFolder;
598
+ /** Number of conversations to return */
599
+ limit?: number;
600
+ /** Pagination cursor */
601
+ after?: string;
602
+ /** Pagination cursor */
603
+ before?: string;
604
+ }
605
+ /**
606
+ * Request parameters for getting conversation details
607
+ */
608
+ interface GetConversationParams {
609
+ /** Fields to retrieve (e.g., 'messages', 'participants') */
610
+ fields?: string[];
611
+ /** Number of messages to return */
612
+ limit?: number;
613
+ /** Pagination cursor */
614
+ after?: string;
615
+ /** Pagination cursor */
616
+ before?: string;
617
+ }
618
+ /**
619
+ * Request parameters for getting message details
620
+ */
621
+ interface GetMessageParams {
622
+ /** Fields to retrieve */
623
+ fields?: string[];
624
+ }
625
+ /**
626
+ * Response for listing conversations
627
+ */
628
+ interface ListConversationsResponse {
629
+ data: Conversation[];
630
+ paging?: {
631
+ cursors?: {
632
+ before?: string;
633
+ after?: string;
634
+ };
635
+ next?: string;
636
+ previous?: string;
637
+ };
638
+ }
639
+ /**
640
+ * Response for getting messages in a conversation
641
+ */
642
+ interface ListMessagesResponse {
643
+ data: MessageBasic[];
644
+ paging?: {
645
+ cursors?: {
646
+ before?: string;
647
+ after?: string;
648
+ };
649
+ next?: string;
650
+ previous?: string;
651
+ };
652
+ }
653
+
654
+ /**
655
+ * Conversations API Resource
656
+ *
657
+ * Handles retrieving conversations and messages between users and Pages/Instagram Business accounts.
658
+ *
659
+ * @see https://developers.facebook.com/docs/messenger-platform/conversations
660
+ */
661
+
662
+ /**
663
+ * Conversations API class for retrieving conversation and message data
664
+ *
665
+ * @example
666
+ * ```typescript
667
+ * const messenger = new Messenger({ accessToken: 'PAGE_TOKEN' });
668
+ *
669
+ * // List all conversations
670
+ * const conversations = await messenger.conversations.list('PAGE_ID', {
671
+ * platform: 'messenger'
672
+ * });
673
+ *
674
+ * // Get conversation details
675
+ * const conversation = await messenger.conversations.get('CONVERSATION_ID');
676
+ *
677
+ * // Get message details
678
+ * const message = await messenger.conversations.getMessage('MESSAGE_ID');
679
+ * ```
680
+ */
681
+ declare class ConversationsAPI {
682
+ private httpClient;
683
+ constructor(httpClient: HTTPClient);
684
+ /**
685
+ * Get a list of conversations for a Page or Instagram Business Account
686
+ *
687
+ * @param pageId - The Page ID or Instagram Business Account ID
688
+ * @param params - Optional parameters for filtering and pagination
689
+ * @param options - Optional request options (e.g., token override)
690
+ * @returns List of conversations
691
+ *
692
+ * @example
693
+ * ```typescript
694
+ * // List Messenger conversations
695
+ * const conversations = await messenger.conversations.list('PAGE_ID', {
696
+ * platform: 'messenger',
697
+ * limit: 25
698
+ * });
699
+ *
700
+ * // Find conversation with specific user
701
+ * const userConvos = await messenger.conversations.list('PAGE_ID', {
702
+ * platform: 'instagram',
703
+ * user_id: 'USER_INSTAGRAM_SCOPED_ID'
704
+ * });
705
+ *
706
+ * // Paginate through conversations
707
+ * const nextPage = await messenger.conversations.list('PAGE_ID', {
708
+ * platform: 'messenger',
709
+ * after: conversations.paging?.cursors?.after
710
+ * });
711
+ * ```
712
+ */
713
+ list(pageId: string, params?: ListConversationsParams, options?: APIOptions): Promise<ListConversationsResponse>;
714
+ /**
715
+ * Get details about a specific conversation
716
+ *
717
+ * @param conversationId - The conversation ID
718
+ * @param params - Optional parameters for fields and pagination
719
+ * @param options - Optional request options (e.g., token override)
720
+ * @returns Conversation details
721
+ *
722
+ * @example
723
+ * ```typescript
724
+ * // Get conversation with messages
725
+ * const conversation = await messenger.conversations.get('CONVERSATION_ID', {
726
+ * fields: ['messages', 'participants']
727
+ * });
728
+ *
729
+ * // Get only participants
730
+ * const participants = await messenger.conversations.get('CONVERSATION_ID', {
731
+ * fields: ['participants']
732
+ * });
733
+ * ```
734
+ */
735
+ get(conversationId: string, params?: GetConversationParams, options?: APIOptions): Promise<ConversationDetail>;
736
+ /**
737
+ * Get messages in a conversation
738
+ *
739
+ * @param conversationId - The conversation ID
740
+ * @param params - Optional parameters for pagination
741
+ * @param options - Optional request options (e.g., token override)
742
+ * @returns List of messages
743
+ *
744
+ * @example
745
+ * ```typescript
746
+ * // Get messages in a conversation
747
+ * const messages = await messenger.conversations.getMessages('CONVERSATION_ID', {
748
+ * limit: 20
749
+ * });
750
+ *
751
+ * // Paginate through messages
752
+ * const nextPage = await messenger.conversations.getMessages('CONVERSATION_ID', {
753
+ * after: messages.paging?.cursors?.after
754
+ * });
755
+ * ```
756
+ */
757
+ getMessages(conversationId: string, params?: {
758
+ limit?: number;
759
+ after?: string;
760
+ before?: string;
761
+ }, options?: APIOptions): Promise<ListMessagesResponse>;
762
+ /**
763
+ * Get details about a specific message
764
+ *
765
+ * Note: You can only retrieve details for the 20 most recent messages in a conversation.
766
+ * Older messages will return an error indicating the message was deleted.
767
+ *
768
+ * @param messageId - The message ID
769
+ * @param params - Optional parameters for fields to retrieve
770
+ * @param options - Optional request options (e.g., token override)
771
+ * @returns Message details
772
+ *
773
+ * @example
774
+ * ```typescript
775
+ * // Get full message details
776
+ * const message = await messenger.conversations.getMessage('MESSAGE_ID', {
777
+ * fields: ['id', 'created_time', 'from', 'to', 'message', 'attachments', 'reactions']
778
+ * });
779
+ *
780
+ * // Get basic message info
781
+ * const basicMessage = await messenger.conversations.getMessage('MESSAGE_ID');
782
+ * ```
783
+ */
784
+ getMessage(messageId: string, params?: GetMessageParams, options?: APIOptions): Promise<Message$1>;
785
+ /**
786
+ * Get the 20 most recent messages in a conversation with full details
787
+ *
788
+ * This is a convenience method that retrieves message IDs and then fetches
789
+ * full details for each message. Note that only the 20 most recent messages
790
+ * can have their details retrieved.
791
+ *
792
+ * @param conversationId - The conversation ID
793
+ * @param options - Optional request options (e.g., token override)
794
+ * @returns Array of detailed messages
795
+ *
796
+ * @example
797
+ * ```typescript
798
+ * // Get recent messages with full details
799
+ * const messages = await messenger.conversations.getRecentMessages('CONVERSATION_ID');
800
+ *
801
+ * for (const message of messages) {
802
+ * console.log(`${message.from?.username}: ${message.message}`);
803
+ * }
804
+ * ```
805
+ */
806
+ getRecentMessages(conversationId: string, options?: APIOptions): Promise<Message$1[]>;
807
+ /**
808
+ * Find a conversation between a Page and a specific user
809
+ *
810
+ * This is a convenience method that finds a conversation with a specific user.
811
+ *
812
+ * @param pageId - The Page ID or Instagram Business Account ID
813
+ * @param userId - The user's Instagram-scoped ID or Page-scoped ID
814
+ * @param platform - The platform ('instagram' or 'messenger')
815
+ * @param options - Optional request options (e.g., token override)
816
+ * @returns The conversation ID, or null if not found
817
+ *
818
+ * @example
819
+ * ```typescript
820
+ * // Find conversation with Instagram user
821
+ * const conversationId = await messenger.conversations.findByUser(
822
+ * 'PAGE_ID',
823
+ * 'USER_INSTAGRAM_SCOPED_ID',
824
+ * 'instagram'
825
+ * );
826
+ *
827
+ * if (conversationId) {
828
+ * const messages = await messenger.conversations.getRecentMessages(conversationId);
829
+ * }
830
+ * ```
831
+ */
832
+ findByUser(pageId: string, userId: string, platform: 'instagram' | 'messenger', options?: APIOptions): Promise<string | null>;
833
+ }
834
+
320
835
  interface MessengerConfig {
321
836
  accessToken?: string;
322
837
  version?: string;
@@ -330,6 +845,7 @@ declare class Messenger {
330
845
  readonly moderation: ModerationAPI;
331
846
  readonly templates: TemplatesAPI;
332
847
  readonly profile: ProfileAPI;
848
+ readonly conversations: ConversationsAPI;
333
849
  private readonly httpClient;
334
850
  constructor(config?: MessengerConfig);
335
851
  private validateConfig;
@@ -417,6 +933,35 @@ interface WebhookPayload<T extends BaseWebhookEvent = BaseWebhookEvent> {
417
933
  /** Array of entry objects containing the actual events */
418
934
  entry: WebhookEntry<T>[];
419
935
  }
936
+ /**
937
+ * Generic webhook entry structure for Page webhooks (uses 'changes' instead of 'messaging').
938
+ * Represents a single entry in a Page webhook payload.
939
+ */
940
+ interface PageWebhookEntry<T = any> {
941
+ /** Unique ID of the page */
942
+ id: string;
943
+ /** Time of update (epoch time in milliseconds) */
944
+ time: number;
945
+ /** Array of change events */
946
+ changes: T[];
947
+ }
948
+ /**
949
+ * Generic webhook payload structure for Page webhooks.
950
+ * This is the top-level structure received from Facebook Page webhooks.
951
+ */
952
+ interface PageWebhookPayload<T = any> {
953
+ /** Always 'page' for Page webhooks */
954
+ object: 'page';
955
+ /** Array of entry objects containing the actual events */
956
+ entry: PageWebhookEntry<T>[];
957
+ }
958
+ /**
959
+ * Extract all events from a Page webhook payload (uses 'changes' array)
960
+ *
961
+ * @param payload - The Page webhook payload to extract events from
962
+ * @returns Array of Page webhook events
963
+ */
964
+ declare function extractPageEvents<T>(payload: PageWebhookPayload<T>): T[];
420
965
  /**
421
966
  * Common processing context for all webhook events
422
967
  */
@@ -1496,6 +2041,776 @@ declare function isValidQuestionId(questionId: string): boolean;
1496
2041
  */
1497
2042
  declare function isValidTextFeedback(textFeedback: string): boolean;
1498
2043
 
2044
+ /**
2045
+ * Facebook Page - Feed Webhook Types
2046
+ *
2047
+ * These types represent the webhook event structure for feed events.
2048
+ * Triggered when there are changes to a Page's feed, such as Posts, shares,
2049
+ * likes, comments, etc. Webhooks are not sent for Ad Posts, but are sent
2050
+ * for Comments on Ad Posts. Notifications for Page likes will only be sent
2051
+ * for Pages that have fewer than 10K likes.
2052
+ *
2053
+ * @see https://developers.facebook.com/docs/graph-api/webhooks/reference/page/#feed
2054
+ */
2055
+
2056
+ /**
2057
+ * Enumeration of item types in feed events
2058
+ */
2059
+ declare enum FeedItemType {
2060
+ ALBUM = "album",
2061
+ ADDRESS = "address",
2062
+ COMMENT = "comment",
2063
+ CONNECTION = "connection",
2064
+ COUPON = "coupon",
2065
+ EVENT = "event",
2066
+ EXPERIENCE = "experience",
2067
+ GROUP = "group",
2068
+ GROUP_MESSAGE = "group_message",
2069
+ INTEREST = "interest",
2070
+ LINK = "link",
2071
+ MENTION = "mention",
2072
+ MILESTONE = "milestone",
2073
+ NOTE = "note",
2074
+ PAGE = "page",
2075
+ PICTURE = "picture",
2076
+ PLATFORM_STORY = "platform-story",
2077
+ PHOTO = "photo",
2078
+ PHOTO_ALBUM = "photo-album",
2079
+ POST = "post",
2080
+ PROFILE = "profile",
2081
+ QUESTION = "question",
2082
+ RATING = "rating",
2083
+ REACTION = "reaction",
2084
+ RELATIONSHIP_STATUS = "relationship-status",
2085
+ SHARE = "share",
2086
+ STATUS = "status",
2087
+ STORY = "story",
2088
+ TIMELINE_COVER = "timeline cover",
2089
+ TAG = "tag",
2090
+ VIDEO = "video"
2091
+ }
2092
+ /**
2093
+ * Enumeration of action verbs in feed events
2094
+ */
2095
+ declare enum FeedActionVerb {
2096
+ ADD = "add",
2097
+ BLOCK = "block",
2098
+ EDIT = "edit",
2099
+ EDITED = "edited",
2100
+ DELETE = "delete",
2101
+ FOLLOW = "follow",
2102
+ HIDE = "hide",
2103
+ MUTE = "mute",
2104
+ REMOVE = "remove",
2105
+ UNBLOCK = "unblock",
2106
+ UNHIDE = "unhide",
2107
+ UPDATE = "update"
2108
+ }
2109
+ /**
2110
+ * Sender information in feed events
2111
+ */
2112
+ interface FeedSender {
2113
+ /** The ID of the sender */
2114
+ id: string;
2115
+ /** The name of the sender */
2116
+ name?: string;
2117
+ }
2118
+ /**
2119
+ * Page post additional information
2120
+ */
2121
+ interface FeedPagePost {
2122
+ /** Type of the post (e.g., photo, video) */
2123
+ type?: string;
2124
+ /** Status type (e.g., added_photos) */
2125
+ status_type?: string;
2126
+ /** Whether the post is published */
2127
+ is_published?: boolean;
2128
+ /** Timestamp of when the post was last updated */
2129
+ updated_time?: string;
2130
+ /** Permanent static URL to the post */
2131
+ permalink_url?: string;
2132
+ /** Promotion status (e.g., inactive, extendable) */
2133
+ promotion_status?: string;
2134
+ }
2135
+ /**
2136
+ * Feed event value data
2137
+ */
2138
+ interface FeedEventValue {
2139
+ /** Edited time (datetime) */
2140
+ edited_time?: string;
2141
+ /** The sender information */
2142
+ from?: FeedSender;
2143
+ /** Additional post content information */
2144
+ post?: FeedPagePost;
2145
+ /** Description of the type of a status update */
2146
+ status_type?: string;
2147
+ /** Whether a scheduled post was published */
2148
+ is_published?: boolean;
2149
+ /** The time the post was last updated */
2150
+ updated_time?: string;
2151
+ /** The permanent static URL to the post on facebook.com */
2152
+ permalink_url?: string;
2153
+ /** Whether the post is hidden or not */
2154
+ is_hidden?: boolean;
2155
+ /** The link to attached content */
2156
+ link?: string;
2157
+ /** The message that is part of the content */
2158
+ message?: string;
2159
+ /** The link to an attached photo */
2160
+ photo?: string;
2161
+ /** The IDs of the photos that were added to an album */
2162
+ photo_ids?: string[];
2163
+ /** The links to any attached photos */
2164
+ photos?: string[];
2165
+ /** The post ID */
2166
+ post_id?: string;
2167
+ /** The story—only logged for a milestone item */
2168
+ story?: string;
2169
+ /** The title—only logged for a milestone item */
2170
+ title?: string;
2171
+ /** The link to an attached video */
2172
+ video?: string;
2173
+ /** The code why the video is flagged */
2174
+ video_flag_reason?: number;
2175
+ /** The type of action taken */
2176
+ action?: string;
2177
+ /** The album ID */
2178
+ album_id?: string;
2179
+ /** The comment ID */
2180
+ comment_id?: string;
2181
+ /** The timestamp of when the object was created */
2182
+ created_time?: string;
2183
+ /** The ID of the event, if the feed post is an event creation story */
2184
+ event_id?: string;
2185
+ /** The type of item */
2186
+ item?: FeedItemType;
2187
+ /** The ID of the open graph object */
2188
+ open_graph_story_id?: string;
2189
+ /** The parent ID */
2190
+ parent_id?: string;
2191
+ /** The photo ID */
2192
+ photo_id?: string;
2193
+ /** The type of the user reaction */
2194
+ reaction_type?: string;
2195
+ /** Whether the post is published */
2196
+ published?: number;
2197
+ /** The recipient ID */
2198
+ recipient_id?: string;
2199
+ /** The share ID */
2200
+ share_id?: string;
2201
+ /** The type of action taken */
2202
+ verb?: FeedActionVerb;
2203
+ /** The video ID */
2204
+ video_id?: string;
2205
+ }
2206
+ /**
2207
+ * Main webhook event structure for feed events
2208
+ *
2209
+ * This event is triggered when there are changes to a Page's feed.
2210
+ * The webhook provides information about posts, comments, likes, shares, etc.
2211
+ *
2212
+ * @example Post created:
2213
+ * ```json
2214
+ * {
2215
+ * "field": "feed",
2216
+ * "value": {
2217
+ * "from": {
2218
+ * "id": "123456789",
2219
+ * "name": "Page Name"
2220
+ * },
2221
+ * "post_id": "123456789_987654321",
2222
+ * "verb": "add",
2223
+ * "item": "post",
2224
+ * "created_time": "1234567890",
2225
+ * "message": "Hello World!"
2226
+ * }
2227
+ * }
2228
+ * ```
2229
+ */
2230
+ interface FeedWebhookEvent {
2231
+ /** Name of the updated field */
2232
+ field: 'feed';
2233
+ /** The contents of the update */
2234
+ value: FeedEventValue;
2235
+ }
2236
+ /**
2237
+ * Complete webhook payload structure for feed events
2238
+ */
2239
+ interface FeedWebhookPayload extends PageWebhookPayload<FeedWebhookEvent> {
2240
+ }
2241
+ /**
2242
+ * Type guard to check if a webhook event is a feed event
2243
+ *
2244
+ * @param event - The webhook event to check
2245
+ * @returns True if the event is a feed event
2246
+ *
2247
+ * @example
2248
+ * ```typescript
2249
+ * if (isFeedEvent(event)) {
2250
+ * console.log(`Feed event: ${event.value.verb} ${event.value.item}`);
2251
+ * }
2252
+ * ```
2253
+ */
2254
+ declare function isFeedEvent(event: any): event is FeedWebhookEvent;
2255
+ /**
2256
+ * Type guard to check if a feed event is a post creation
2257
+ *
2258
+ * @param value - The feed event value to check
2259
+ * @returns True if the event is a post creation
2260
+ */
2261
+ declare function isPostCreated(value: FeedEventValue): boolean;
2262
+ /**
2263
+ * Type guard to check if a feed event is a comment
2264
+ *
2265
+ * @param value - The feed event value to check
2266
+ * @returns True if the event is a comment
2267
+ */
2268
+ declare function isComment(value: FeedEventValue): boolean;
2269
+ /**
2270
+ * Type guard to check if a feed event is a photo
2271
+ *
2272
+ * @param value - The feed event value to check
2273
+ * @returns True if the event is a photo
2274
+ */
2275
+ declare function isPhoto(value: FeedEventValue): boolean;
2276
+ /**
2277
+ * Type guard to check if a feed event is a video
2278
+ *
2279
+ * @param value - The feed event value to check
2280
+ * @returns True if the event is a video
2281
+ */
2282
+ declare function isVideo(value: FeedEventValue): boolean;
2283
+ /**
2284
+ * Type guard to check if a feed event is a reaction
2285
+ *
2286
+ * @param value - The feed event value to check
2287
+ * @returns True if the event is a reaction
2288
+ */
2289
+ declare function isReaction(value: FeedEventValue): boolean;
2290
+ /**
2291
+ * Type guard to check if a feed event has a message
2292
+ *
2293
+ * @param value - The feed event value to check
2294
+ * @returns True if the event has a message
2295
+ */
2296
+ declare function hasMessage(value: FeedEventValue): value is FeedEventValue & {
2297
+ message: string;
2298
+ };
2299
+ /**
2300
+ * Utility type for extracting just the feed event data
2301
+ */
2302
+ type FeedEventData = FeedEventValue;
2303
+ /**
2304
+ * Processing context for feed events
2305
+ */
2306
+ interface FeedProcessingContext {
2307
+ /** The page ID */
2308
+ pageId: string;
2309
+ /** When the event occurred */
2310
+ timestamp: number;
2311
+ /** Human-readable datetime for the event timestamp */
2312
+ eventDate: Date;
2313
+ /** The sender information */
2314
+ sender?: FeedSender;
2315
+ /** Post ID if available */
2316
+ postId?: string;
2317
+ /** Comment ID if available */
2318
+ commentId?: string;
2319
+ /** The action verb */
2320
+ verb?: FeedActionVerb;
2321
+ /** The item type */
2322
+ item?: FeedItemType;
2323
+ /** Message content if available */
2324
+ message?: string;
2325
+ /** Whether this is a post creation */
2326
+ isPostCreated: boolean;
2327
+ /** Whether this is a comment */
2328
+ isComment: boolean;
2329
+ /** Whether this is a photo */
2330
+ isPhoto: boolean;
2331
+ /** Whether this is a video */
2332
+ isVideo: boolean;
2333
+ /** Whether this is a reaction */
2334
+ isReaction: boolean;
2335
+ }
2336
+ /**
2337
+ * Helper function to extract processing context from a feed event
2338
+ *
2339
+ * @param pageId - The page ID from the webhook entry
2340
+ * @param timestamp - The timestamp from the webhook entry
2341
+ * @param event - The feed webhook event
2342
+ * @returns Simplified processing context
2343
+ *
2344
+ * @example
2345
+ * ```typescript
2346
+ * const context = extractFeedContext(entry.id, entry.time, event);
2347
+ * console.log(`Feed event: ${context.verb} ${context.item}`);
2348
+ * if (context.isPostCreated) {
2349
+ * console.log(`New post created: ${context.message}`);
2350
+ * }
2351
+ * ```
2352
+ */
2353
+ declare function extractFeedContext(pageId: string, timestamp: number, event: FeedWebhookEvent): FeedProcessingContext;
2354
+ /**
2355
+ * Helper function to extract all photos from a feed event
2356
+ *
2357
+ * @param value - The feed event value
2358
+ * @returns Array of photo URLs and IDs
2359
+ *
2360
+ * @example
2361
+ * ```typescript
2362
+ * const photos = extractPhotos(event.value);
2363
+ * console.log(`Found ${photos.length} photo(s)`);
2364
+ * ```
2365
+ */
2366
+ declare function extractPhotos(value: FeedEventValue): Array<{
2367
+ url?: string;
2368
+ id?: string;
2369
+ }>;
2370
+ /**
2371
+ * Constants related to feed events
2372
+ */
2373
+ declare const FEED_CONSTANTS: {
2374
+ /** Webhook field name */
2375
+ readonly FIELD_NAME: "feed";
2376
+ /** Maximum Page likes threshold for notifications */
2377
+ readonly MAX_PAGE_LIKES_FOR_NOTIFICATIONS: 10000;
2378
+ };
2379
+
2380
+ /**
2381
+ * Facebook Page - Videos Webhook Types
2382
+ *
2383
+ * These types represent the webhook event structure for video encoding events.
2384
+ * Triggered when there are changes to the encoding status of a video on a page.
2385
+ *
2386
+ * @see https://developers.facebook.com/docs/graph-api/webhooks/reference/page/#videos
2387
+ */
2388
+
2389
+ /**
2390
+ * Enumeration of video encoding statuses
2391
+ */
2392
+ declare enum VideoStatus {
2393
+ /** Video encoding is in progress */
2394
+ PROCESSING = "processing",
2395
+ /** Video encoding is complete and ready */
2396
+ READY = "ready",
2397
+ /** Video encoding failed */
2398
+ ERROR = "error"
2399
+ }
2400
+ /**
2401
+ * Video status information
2402
+ */
2403
+ interface VideoStatusInfo {
2404
+ /** Current status of the video encoding */
2405
+ video_status: VideoStatus;
2406
+ }
2407
+ /**
2408
+ * Video event value data
2409
+ */
2410
+ interface VideoEventValue {
2411
+ /** The ID of the video */
2412
+ id: string;
2413
+ /** Status information of the video encoding */
2414
+ status: VideoStatusInfo;
2415
+ }
2416
+ /**
2417
+ * Main webhook event structure for videos
2418
+ *
2419
+ * This event is triggered when there are changes to a video's encoding status.
2420
+ * The webhook provides information about the video processing state.
2421
+ *
2422
+ * @example Video processing:
2423
+ * ```json
2424
+ * {
2425
+ * "field": "videos",
2426
+ * "value": {
2427
+ * "id": "123456789",
2428
+ * "status": {
2429
+ * "video_status": "processing"
2430
+ * }
2431
+ * }
2432
+ * }
2433
+ * ```
2434
+ *
2435
+ * @example Video ready:
2436
+ * ```json
2437
+ * {
2438
+ * "field": "videos",
2439
+ * "value": {
2440
+ * "id": "123456789",
2441
+ * "status": {
2442
+ * "video_status": "ready"
2443
+ * }
2444
+ * }
2445
+ * }
2446
+ * ```
2447
+ *
2448
+ * @example Video error:
2449
+ * ```json
2450
+ * {
2451
+ * "field": "videos",
2452
+ * "value": {
2453
+ * "id": "123456789",
2454
+ * "status": {
2455
+ * "video_status": "error"
2456
+ * }
2457
+ * }
2458
+ * }
2459
+ * ```
2460
+ */
2461
+ interface VideoWebhookEvent {
2462
+ /** Name of the updated field */
2463
+ field: 'videos';
2464
+ /** The contents of the update */
2465
+ value: VideoEventValue;
2466
+ }
2467
+ /**
2468
+ * Complete webhook payload structure for video events
2469
+ */
2470
+ interface VideoWebhookPayload extends PageWebhookPayload<VideoWebhookEvent> {
2471
+ }
2472
+ /**
2473
+ * Type guard to check if a webhook event is a video event
2474
+ *
2475
+ * @param event - The webhook event to check
2476
+ * @returns True if the event is a video event
2477
+ *
2478
+ * @example
2479
+ * ```typescript
2480
+ * if (isVideoEvent(event)) {
2481
+ * console.log(`Video ${event.value.id} status: ${event.value.status.video_status}`);
2482
+ * }
2483
+ * ```
2484
+ */
2485
+ declare function isVideoEvent(event: any): event is VideoWebhookEvent;
2486
+ /**
2487
+ * Type guard to check if a video is processing
2488
+ *
2489
+ * @param value - The video event value to check
2490
+ * @returns True if the video is being processed
2491
+ */
2492
+ declare function isProcessing$1(value: VideoEventValue): boolean;
2493
+ /**
2494
+ * Type guard to check if a video is ready
2495
+ *
2496
+ * @param value - The video event value to check
2497
+ * @returns True if the video encoding is complete
2498
+ */
2499
+ declare function isReady(value: VideoEventValue): boolean;
2500
+ /**
2501
+ * Type guard to check if a video encoding failed
2502
+ *
2503
+ * @param value - The video event value to check
2504
+ * @returns True if the video encoding failed
2505
+ */
2506
+ declare function hasError(value: VideoEventValue): boolean;
2507
+ /**
2508
+ * Utility type for extracting just the video event data
2509
+ */
2510
+ type VideoEventData = VideoEventValue;
2511
+ /**
2512
+ * Processing context for video events
2513
+ */
2514
+ interface VideoProcessingContext {
2515
+ /** The page ID */
2516
+ pageId: string;
2517
+ /** When the event occurred */
2518
+ timestamp: number;
2519
+ /** Human-readable datetime for the event timestamp */
2520
+ eventDate: Date;
2521
+ /** The video ID */
2522
+ videoId: string;
2523
+ /** Current video status */
2524
+ status: VideoStatus;
2525
+ /** Whether the video is being processed */
2526
+ isProcessing: boolean;
2527
+ /** Whether the video is ready */
2528
+ isReady: boolean;
2529
+ /** Whether the video encoding failed */
2530
+ hasError: boolean;
2531
+ }
2532
+ /**
2533
+ * Helper function to extract processing context from a video event
2534
+ *
2535
+ * @param pageId - The page ID from the webhook entry
2536
+ * @param timestamp - The timestamp from the webhook entry
2537
+ * @param event - The video webhook event
2538
+ * @returns Simplified processing context
2539
+ *
2540
+ * @example
2541
+ * ```typescript
2542
+ * const context = extractVideoContext(entry.id, entry.time, event);
2543
+ * console.log(`Video ${context.videoId} is ${context.status}`);
2544
+ * if (context.isReady) {
2545
+ * console.log('Video is ready to play!');
2546
+ * } else if (context.hasError) {
2547
+ * console.log('Video encoding failed');
2548
+ * }
2549
+ * ```
2550
+ */
2551
+ declare function extractVideoContext(pageId: string, timestamp: number, event: VideoWebhookEvent): VideoProcessingContext;
2552
+ /**
2553
+ * Helper function to determine if a status change is a transition to ready
2554
+ *
2555
+ * @param fromStatus - The previous status
2556
+ * @param toStatus - The new status
2557
+ * @returns True if this represents completing encoding
2558
+ *
2559
+ * @example
2560
+ * ```typescript
2561
+ * if (isCompletingEncoding(previousStatus, event.value.status.video_status)) {
2562
+ * console.log('Video encoding just completed!');
2563
+ * }
2564
+ * ```
2565
+ */
2566
+ declare function isCompletingEncoding(fromStatus: VideoStatus | undefined, toStatus: VideoStatus): boolean;
2567
+ /**
2568
+ * Helper function to determine if a status change is a transition to error
2569
+ *
2570
+ * @param fromStatus - The previous status
2571
+ * @param toStatus - The new status
2572
+ * @returns True if this represents encoding failure
2573
+ *
2574
+ * @example
2575
+ * ```typescript
2576
+ * if (isEncodingFailed(previousStatus, event.value.status.video_status)) {
2577
+ * console.log('Video encoding failed');
2578
+ * }
2579
+ * ```
2580
+ */
2581
+ declare function isEncodingFailed(fromStatus: VideoStatus | undefined, toStatus: VideoStatus): boolean;
2582
+ /**
2583
+ * Constants related to video events
2584
+ */
2585
+ declare const VIDEO_CONSTANTS: {
2586
+ /** Webhook field name */
2587
+ readonly FIELD_NAME: "videos";
2588
+ /** All possible video statuses */
2589
+ readonly STATUSES: VideoStatus[];
2590
+ };
2591
+
2592
+ /**
2593
+ * Facebook Messenger Platform - Live Videos Webhook Types
2594
+ *
2595
+ * These types represent the webhook event structure for live video events.
2596
+ * Triggered when there are changes to a page's live video status, such as
2597
+ * when a live video starts, ends, or has status updates.
2598
+ *
2599
+ * @see https://developers.facebook.com/docs/graph-api/webhooks/reference/page/#live_videos
2600
+ */
2601
+
2602
+ /**
2603
+ * Enumeration of live video broadcast statuses
2604
+ * Based on Facebook Graph API BroadcastStatus enum
2605
+ *
2606
+ * @see https://developers.facebook.com/docs/graph-api/reference/live-video/
2607
+ */
2608
+ declare enum LiveVideoStatus {
2609
+ /** Live broadcast is currently streaming */
2610
+ LIVE = "LIVE",
2611
+ /** Live broadcast has stopped */
2612
+ LIVE_STOPPED = "LIVE_STOPPED",
2613
+ /** Live broadcast is currently being processed */
2614
+ PROCESSING = "PROCESSING",
2615
+ /** Scheduled broadcast was canceled */
2616
+ SCHEDULED_CANCELED = "SCHEDULED_CANCELED",
2617
+ /** Scheduled broadcast has expired */
2618
+ SCHEDULED_EXPIRED = "SCHEDULED_EXPIRED",
2619
+ /** Live broadcast is scheduled and published */
2620
+ SCHEDULED_LIVE = "SCHEDULED_LIVE",
2621
+ /** Live broadcast is scheduled but unpublished */
2622
+ SCHEDULED_UNPUBLISHED = "SCHEDULED_UNPUBLISHED",
2623
+ /** Live broadcast is unpublished */
2624
+ UNPUBLISHED = "UNPUBLISHED",
2625
+ /** Live broadcast video on demand (VOD) is ready */
2626
+ VOD = "VOD"
2627
+ }
2628
+ /**
2629
+ * Live video event value data
2630
+ */
2631
+ interface LiveVideoEventValue {
2632
+ /** The ID of the live video */
2633
+ id: string;
2634
+ /** Status of the live video (enum value directly) */
2635
+ status: LiveVideoStatus;
2636
+ }
2637
+ /**
2638
+ * Main webhook event structure for live videos
2639
+ *
2640
+ * This event is triggered when there are changes to a page's live video status.
2641
+ * The webhook provides information about the live video state changes.
2642
+ *
2643
+ * @example Live video started:
2644
+ * ```json
2645
+ * {
2646
+ * "field": "live_videos",
2647
+ * "value": {
2648
+ * "id": "123456789",
2649
+ * "status": "LIVE"
2650
+ * }
2651
+ * }
2652
+ * ```
2653
+ *
2654
+ * @example Live video ended:
2655
+ * ```json
2656
+ * {
2657
+ * "field": "live_videos",
2658
+ * "value": {
2659
+ * "id": "123456789",
2660
+ * "status": "LIVE_STOPPED"
2661
+ * }
2662
+ * }
2663
+ * ```
2664
+ */
2665
+ interface LiveVideoWebhookEvent {
2666
+ /** Name of the updated field */
2667
+ field: 'live_videos';
2668
+ /** The contents of the update */
2669
+ value: LiveVideoEventValue;
2670
+ }
2671
+ /**
2672
+ * Complete webhook payload structure for live video events
2673
+ */
2674
+ interface LiveVideoWebhookPayload extends PageWebhookPayload<LiveVideoWebhookEvent> {
2675
+ }
2676
+ /**
2677
+ * Type guard to check if a webhook event is a live video event
2678
+ *
2679
+ * @param event - The webhook event to check
2680
+ * @returns True if the event is a live video event
2681
+ *
2682
+ * @example
2683
+ * ```typescript
2684
+ * if (isLiveVideoEvent(event)) {
2685
+ * console.log(`Live video ${event.value.id} status: ${event.value.status}`);
2686
+ * }
2687
+ * ```
2688
+ */
2689
+ declare function isLiveVideoEvent(event: any): event is LiveVideoWebhookEvent;
2690
+ /**
2691
+ * Type guard to check if a live video is currently live
2692
+ *
2693
+ * @param value - The live video event value to check
2694
+ * @returns True if the live video is currently streaming
2695
+ */
2696
+ declare function isLive(value: LiveVideoEventValue): boolean;
2697
+ /**
2698
+ * Type guard to check if a live video is scheduled
2699
+ *
2700
+ * @param value - The live video event value to check
2701
+ * @returns True if the live video is scheduled
2702
+ */
2703
+ declare function isScheduled(value: LiveVideoEventValue): boolean;
2704
+ /**
2705
+ * Type guard to check if a live video is processing
2706
+ *
2707
+ * @param value - The live video event value to check
2708
+ * @returns True if the live video is being processed
2709
+ */
2710
+ declare function isProcessing(value: LiveVideoEventValue): boolean;
2711
+ /**
2712
+ * Type guard to check if a live video has ended
2713
+ *
2714
+ * @param value - The live video event value to check
2715
+ * @returns True if the live video has stopped, was cancelled, or expired
2716
+ */
2717
+ declare function hasEnded(value: LiveVideoEventValue): boolean;
2718
+ /**
2719
+ * Type guard to check if a live video VOD is ready
2720
+ *
2721
+ * @param value - The live video event value to check
2722
+ * @returns True if the video on demand is ready
2723
+ */
2724
+ declare function isVODReady(value: LiveVideoEventValue): boolean;
2725
+ /**
2726
+ * Utility type for extracting just the live video event data
2727
+ */
2728
+ type LiveVideoEventData = LiveVideoEventValue;
2729
+ /**
2730
+ * Processing context for live video events
2731
+ */
2732
+ interface LiveVideoProcessingContext {
2733
+ /** The page ID */
2734
+ pageId: string;
2735
+ /** When the event occurred */
2736
+ timestamp: number;
2737
+ /** Human-readable datetime for the event timestamp */
2738
+ eventDate: Date;
2739
+ /** The live video ID */
2740
+ videoId: string;
2741
+ /** Current video status */
2742
+ status: LiveVideoStatus;
2743
+ /** Whether the video is currently live */
2744
+ isLive: boolean;
2745
+ /** Whether the video is scheduled */
2746
+ isScheduled: boolean;
2747
+ /** Whether the video is being processed */
2748
+ isProcessing: boolean;
2749
+ /** Whether the video has ended */
2750
+ hasEnded: boolean;
2751
+ /** Whether the VOD is ready */
2752
+ isVODReady: boolean;
2753
+ }
2754
+ /**
2755
+ * Helper function to extract processing context from a live video event
2756
+ *
2757
+ * @param pageId - The page ID from the webhook entry
2758
+ * @param timestamp - The timestamp from the webhook entry
2759
+ * @param event - The live video webhook event
2760
+ * @returns Simplified processing context
2761
+ *
2762
+ * @example
2763
+ * ```typescript
2764
+ * const context = extractLiveVideoContext(entry.id, entry.time, event);
2765
+ * console.log(`Live video ${context.videoId} is ${context.status}`);
2766
+ * if (context.isLive) {
2767
+ * console.log('Stream is currently live!');
2768
+ * } else if (context.hasEnded) {
2769
+ * console.log('Stream has ended');
2770
+ * }
2771
+ * ```
2772
+ */
2773
+ declare function extractLiveVideoContext(pageId: string, timestamp: number, event: LiveVideoWebhookEvent): LiveVideoProcessingContext;
2774
+ /**
2775
+ * Helper function to determine if a status change is a transition to live
2776
+ *
2777
+ * @param fromStatus - The previous status
2778
+ * @param toStatus - The new status
2779
+ * @returns True if this represents going live
2780
+ *
2781
+ * @example
2782
+ * ```typescript
2783
+ * if (isGoingLive(previousStatus, event.value.status)) {
2784
+ * console.log('Video just went live!');
2785
+ * }
2786
+ * ```
2787
+ */
2788
+ declare function isGoingLive(fromStatus: LiveVideoStatus | undefined, toStatus: LiveVideoStatus): boolean;
2789
+ /**
2790
+ * Helper function to determine if a status change is a transition from live to ended
2791
+ *
2792
+ * @param fromStatus - The previous status
2793
+ * @param toStatus - The new status
2794
+ * @returns True if this represents ending a live stream
2795
+ *
2796
+ * @example
2797
+ * ```typescript
2798
+ * if (isEndingLive(previousStatus, event.value.status)) {
2799
+ * console.log('Live stream has ended');
2800
+ * }
2801
+ * ```
2802
+ */
2803
+ declare function isEndingLive(fromStatus: LiveVideoStatus | undefined, toStatus: LiveVideoStatus): boolean;
2804
+ /**
2805
+ * Constants related to live video events
2806
+ */
2807
+ declare const LIVE_VIDEO_CONSTANTS: {
2808
+ /** Webhook field name */
2809
+ readonly FIELD_NAME: "live_videos";
2810
+ /** All possible video statuses */
2811
+ readonly STATUSES: LiveVideoStatus[];
2812
+ };
2813
+
1499
2814
  /**
1500
2815
  * Facebook Messenger Platform - Messages Webhook Types
1501
2816
  *
@@ -1979,6 +3294,26 @@ type MessengerWebhookPayload = MessageEditWebhookPayload | MessageReactionWebhoo
1979
3294
  * ```
1980
3295
  */
1981
3296
  declare function getWebhookEventType(event: MessengerWebhookEvent | any): WebhookEventType | null;
3297
+ /**
3298
+ * Extract event types from a complete webhook payload.
3299
+ * This is the correct function to use when processing the full webhook payload.
3300
+ *
3301
+ * @param payload - The complete webhook payload from Facebook
3302
+ * @returns Array of unique event types found in the payload
3303
+ *
3304
+ * @example
3305
+ * ```typescript
3306
+ * app.post('/webhook', (req, res) => {
3307
+ * const payload = req.body;
3308
+ * const eventTypes = getWebhookPayloadEventTypes(payload);
3309
+ *
3310
+ * if (eventTypes.includes(WebhookEventType.MESSAGE)) {
3311
+ * // Process message events
3312
+ * }
3313
+ * });
3314
+ * ```
3315
+ */
3316
+ declare function getWebhookPayloadEventTypes(payload: WebhookPayload): WebhookEventType[];
1982
3317
  /**
1983
3318
  * Extract all events from a webhook payload.
1984
3319
  * This properly extracts individual events from the nested structure.
@@ -2035,6 +3370,13 @@ interface WebhookVerificationParams {
2035
3370
  'hub.verify_token': string;
2036
3371
  'hub.challenge': string;
2037
3372
  }
3373
+ /**
3374
+ * Webhook signature verification result
3375
+ */
3376
+ interface WebhookSignatureVerificationResult {
3377
+ isValid: boolean;
3378
+ error?: string;
3379
+ }
2038
3380
  /**
2039
3381
  * Verify webhook subscription during initial setup
2040
3382
  *
@@ -2055,6 +3397,37 @@ interface WebhookVerificationParams {
2055
3397
  * ```
2056
3398
  */
2057
3399
  declare function verifyWebhookSubscription(params: WebhookVerificationParams, verifyToken: string): string | null;
3400
+ /**
3401
+ * Verify webhook signature from Facebook
3402
+ *
3403
+ * **Note**: This function requires Node.js crypto module and is only supported in server-side environments.
3404
+ * For browser environments, you should handle signature verification on your backend.
3405
+ *
3406
+ * @param rawBody - The raw request body as Buffer
3407
+ * @param signature - The X-Hub-Signature-256 header value from Facebook
3408
+ * @param appSecret - Your Facebook app secret
3409
+ * @returns Promise that resolves to verification result with validity and optional error message
3410
+ *
3411
+ * @example
3412
+ * ```typescript
3413
+ * import express from 'express';
3414
+ * import { verifyWebhookSignature } from '@warriorteam/messenger-sdk';
3415
+ *
3416
+ * app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
3417
+ * const signature = req.get('X-Hub-Signature-256');
3418
+ * const result = await verifyWebhookSignature(req.body, signature, process.env.APP_SECRET);
3419
+ *
3420
+ * if (!result.isValid) {
3421
+ * return res.status(401).json({error: result.error});
3422
+ * }
3423
+ *
3424
+ * // Process webhook...
3425
+ * const payload = JSON.parse(req.body.toString());
3426
+ * // Handle webhook events...
3427
+ * });
3428
+ * ```
3429
+ */
3430
+ declare function verifyWebhookSignature(rawBody: Buffer, signature: string | undefined, appSecret: string): Promise<WebhookSignatureVerificationResult>;
2058
3431
 
2059
3432
  declare class MessengerAPIError extends Error {
2060
3433
  readonly code: number;
@@ -2106,4 +3479,4 @@ declare const TEMPLATE_LIMITS: {
2106
3479
  readonly MEDIA_BUTTONS_MAX_COUNT: 3;
2107
3480
  };
2108
3481
 
2109
- 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 };
3482
+ 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 Conversation, type ConversationDetail, type ConversationFolder, type Message$1 as ConversationMessage, type MessageAttachment$1 as ConversationMessageAttachment, type MessageReaction as ConversationMessageReaction, type ConversationParticipant, type ConversationPlatform, ConversationsAPI, type DefaultAction, type ErrorResponse, FEED_CONSTANTS, type FallbackAttachmentPayload, FeedActionVerb, type FeedEventData, type FeedEventValue, FeedItemType, type FeedPagePost, type FeedProcessingContext, type FeedSender, type FeedWebhookEvent, type FeedWebhookPayload, type FeedbackFollowUp, type FeedbackQuestion, type FeedbackScreen, FeedbackType, FollowUpType, type GenericTemplate, type GenericTemplateElement, type GenericTemplatePayload, type WebhookPayload as GenericWebhookPayload, type GetConversationParams, type GetMessageParams, type GetProfileRequest, type ImageData, LIVE_VIDEO_CONSTANTS, type ListConversationsParams, type ListConversationsResponse, type ListMessagesResponse, type LiveVideoEventData, type LiveVideoEventValue, type LiveVideoProcessingContext, LiveVideoStatus, type LiveVideoWebhookEvent, type LiveVideoWebhookPayload, MESSAGE_CONSTANTS, MESSAGE_EDIT_CONSTANTS, MESSAGE_LIMITS, MESSAGE_READS_CONSTANTS, MESSAGING_FEEDBACK_CONSTANTS, type MediaAttachmentPayload, type MediaTemplateElement, type MediaTemplatePayload, type Message$2 as Message, type MessageAttachment, type MessageAttachmentType, type MessageBasic, type MessageCommand, type MessageEdit, type MessageEditProcessingContext, type WebhookRecipient as MessageEditRecipient, type WebhookSender as MessageEditSender, type MessageEditWebhookEvent, type MessageEditWebhookPayload, type MessageParticipant, 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, type MessageShare, type MessageTag, 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 PageWebhookEntry, type PageWebhookPayload, 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 ReplyInfo, type ReplyTo, SendAPI, type SendMessageRequest, type SendMessageResponse, type SenderAction, type ShareTemplatePayload, type SharedProduct, type StickerAttachmentPayload, type StoryShare, TEMPLATE_LIMITS, TemplateValidationError, TemplatesAPI, type UserId, type UserProfile, VIDEO_CONSTANTS, type VideoData, type VideoEventData, type VideoEventValue, type VideoProcessingContext, VideoStatus, type VideoStatusInfo, type VideoWebhookEvent, type VideoWebhookPayload, type WatermarkTimestamp, AttachmentType as WebhookAttachmentType, type WebhookEntry, type WebhookEventHandlers, WebhookEventType, type Message as WebhookMessage, type QuickReply as WebhookQuickReply, type WebhookSignatureVerificationResult, type WebhookVerificationParams, extractFeedContext, extractLiveVideoContext, extractMessageContext, extractMessageEditContext, extractMessageReadsContext, extractMessagingFeedbackContext, extractPageEvents, extractPhotos, extractPostbackContext, extractTextFeedback, extractVideoContext, extractWebhookEvents, getAttachmentUrls, getAttachmentsByType, getFeedbackScoresByType, getReadMessageCount, getReadMessages, getWebhookEventType, getWebhookPayloadEventTypes, hasAttachments, hasEnded, hasMessage, hasQuickReply, hasReferral, hasReferralData, isAttachmentType, isComment, isCompletingEncoding, isEncodingFailed, isEndingLive, isFeedEvent, isVideo as isFeedVideo, isGoingLive, isIdentifiedSender, isLive, isLiveVideoEvent, isProcessing as isLiveVideoProcessing, isMessageEditEvent, isMessageEvent, isMessageRead, isMessageReadsEvent, isMessagingFeedbackEvent, isMessagingPostbackEvent, isPhoto, isPostCreated, isReaction, isReplyMessage, isScheduled, isTextMessage, isVODReady, isValidFeedbackScore, isValidQuestionId, isValidTextFeedback, isVideoEvent, isProcessing$1 as isVideoProcessing, isReady as isVideoReady, processWebhookEvents, verifyWebhookSignature, verifyWebhookSubscription, hasError as videoHasError };