@warriorteam/messenger-sdk 1.5.7 → 1.5.8

package/README.md

@@ -1,886 +1,886 @@
-# @warriorteam/messenger-sdk
-
-A modern TypeScript SDK for the Facebook Messenger Platform API, designed with simplicity and type safety in mind.
-
-## Features
-
-- 🚀 **Zero runtime dependencies** - Built with native fetch
-- 📝 **Full TypeScript support** - Complete type definitions with discriminated unions
-- 🔄 **Dual module support** - ESM and CommonJS
-- ✅ **Comprehensive validation** - Built-in message and template validation
-- 🛡️ **Error handling** - Detailed error types and messages
-- 📚 **Complete API coverage** - Send API, Templates, Attachments, Moderation, Profile, Conversations
-- 💬 **Conversations API** - Retrieve conversation history and messages for Messenger & Instagram
-- 🔐 **Webhook utilities** - Complete webhook type system and signature verification
-- 🎯 **Token override** - Per-method access token override support
-- 🔧 **Type-safe webhooks** - Discriminated unions for proper TypeScript narrowing
-
-## Installation
-
-```bash
-npm install @warriorteam/messenger-sdk
-```
-
-## Requirements
-
-- Node.js 18+ (for native fetch support)
-- A Facebook Page Access Token
-
-## Quick Start
-
-```typescript
-import { Messenger } from '@warriorteam/messenger-sdk';
-
-const messenger = new Messenger({
-  accessToken: 'YOUR_PAGE_ACCESS_TOKEN',
-  version: 'v23.0'
-});
-
-// Send a text message
-const result = await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: { text: 'Hello from RedAI Messenger SDK!' }
-});
-
-console.log('Message sent:', result.message_id);
-```
-
-## API Reference
-
-### Client Configuration
-
-```typescript
-const messenger = new Messenger({
-  accessToken?: string;   // Optional: Default page access token
-  version?: string;       // Optional: API version (default: 'v23.0')
-  baseUrl?: string;       // Optional: Custom base URL
-  timeout?: number;       // Optional: Request timeout in ms (default: 30000)
-  maxRetries?: number;    // Optional: Max retry attempts (default: 3)
-});
-```
-
-### Token Override Support
-
-Every API method supports per-call access token override, perfect for multi-tenant applications:
-
-```typescript
-const messenger = new Messenger({
-  accessToken: 'default_page_token'
-});
-
-// Use default token
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: { text: 'Hello from default page!' }
-});
-
-// Override token for this specific call
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: { text: 'Hello from different page!' }
-}, {
-  accessToken: 'other_page_token'
-});
-
-// Works with all API methods
-const profile = await messenger.profile.getBasic('USER_PSID', {
-  accessToken: 'specific_token'
-});
-```
-
-### Send API
-
-#### Send Text Message
-
-```typescript
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: { text: 'Hello World!' }
-});
-```
-
-#### Send Message with Quick Replies
-
-```typescript
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: {
-    text: 'Pick a color:',
-    quick_replies: [
-      { content_type: 'text', title: 'Red', payload: 'PICKED_RED' },
-      { content_type: 'text', title: 'Blue', payload: 'PICKED_BLUE' }
-    ]
-  }
-});
-```
-
-#### Sender Actions
-
-Manage conversation state and reactions:
-
-```typescript
-// Typing indicators
-await messenger.send.typingOn('USER_PSID');
-await messenger.send.typingOff('USER_PSID');
-
-// Helper to toggle typing based on boolean
-await messenger.send.setTyping('USER_PSID', true);
-
-// Mark as read/seen
-await messenger.send.markRead('USER_PSID');
-
-// React to a message
-await messenger.send.addReaction('USER_PSID', {
-  messageId: 'MESSAGE_ID',
-  emoji: '❤️'
-});
-
-// Remove reaction
-await messenger.send.removeReaction('USER_PSID', 'MESSAGE_ID');
-```
-
-#### Response Format
-
-The Send API response includes a `message_id` and optionally a `recipient_id`:
-
-```typescript
-const result = await messenger.send.message({...});
-console.log('Message ID:', result.message_id); // Always present
-console.log('Recipient ID:', result.recipient_id || 'Not provided'); // Optional
-```
-
-**Note**: `recipient_id` is only included when using `recipient.id` (PSID). It's not included when using `recipient.user_ref` or `recipient.phone_number`.
-
-### Attachments API
-
-#### Upload Attachment from URL
-
-```typescript
-const attachment = await messenger.attachments.upload({
-  type: 'image',
-  url: 'https://example.com/image.jpg',
-  is_reusable: true
-});
-
-// Use the attachment ID to send
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: {
-    attachment: {
-      type: 'image',
-      payload: { attachment_id: attachment.attachment_id }
-    }
-  }
-});
-```
-
-#### Send Attachment Directly
-
-```typescript
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  message: {
-    attachment: {
-      type: 'image',
-      payload: { url: 'https://example.com/image.jpg' }
-    }
-  }
-});
-```
-
-### Templates API
-
-#### Generic Template
-
-```typescript
-await messenger.templates.generic({
-  recipient: { id: 'USER_PSID' },
-  elements: [{
-    title: 'Welcome',
-    subtitle: 'Check out our products',
-    image_url: 'https://example.com/image.jpg',
-    buttons: [{
-      type: 'web_url',
-      title: 'Shop Now',
-      url: 'https://example.com/shop'
-    }]
-  }]
-});
-```
-
-#### Button Template
-
-```typescript
-await messenger.templates.button({
-  recipient: { id: 'USER_PSID' },
-  text: 'What would you like to do?',
-  buttons: [{
-    type: 'postback',
-    title: 'Get Started',
-    payload: 'GET_STARTED'
-  }]
-});
-```
-
-### Moderation API
-
-#### User Moderation
-
-```typescript
-// Block a user from messaging (can still see page content)
-await messenger.moderation.blockUser('USER_PSID');
-
-// Ban a user completely (no messaging + no Facebook interactions)
-await messenger.moderation.banUser('USER_PSID');
-
-// Move conversation to spam folder
-await messenger.moderation.moveToSpam('USER_PSID');
-
-// Block and spam (common combo)
-await messenger.moderation.blockAndSpam('USER_PSID');
-
-// Multiple users at once
-await messenger.moderation.blockUser(['USER_1', 'USER_2', 'USER_3']);
-
-// Unblock/unban users
-await messenger.moderation.unblockUser('USER_PSID');
-await messenger.moderation.unbanUser('USER_PSID');
-```
-
-### Profile API
-
-#### Get User Profile Information
-
-```typescript
-// Get basic profile info (first_name, last_name, profile_pic)
-const profile = await messenger.profile.getBasic('USER_PSID');
-console.log(`Hello ${profile.first_name}!`);
-
-// Get comprehensive profile with all fields
-const fullProfile = await messenger.profile.getFull('USER_PSID');
-console.log('Profile:', fullProfile);
-// Returns: { id, name, first_name, last_name, profile_pic, locale, timezone, gender }
-
-// Get specific fields only
-const customProfile = await messenger.profile.get({
-  psid: 'USER_PSID',
-  fields: ['first_name', 'locale', 'timezone']
-});
-
-// Helper methods for common use cases
-const nameInfo = await messenger.profile.getName('USER_PSID');
-const profilePic = await messenger.profile.getProfilePicture('USER_PSID');
-```
-
-#### Personalize Messages
-
-```typescript
-// Use profile info to personalize messages
-const profile = await messenger.profile.getName('USER_PSID');
-const greeting = profile.first_name 
-  ? `Hello ${profile.first_name}! Welcome back!`
-  : 'Hello! Welcome back!';
-
-await messenger.send.message({
-  recipient: { id: 'USER_PSID' },
-  messaging_type: 'RESPONSE',
-  message: { text: greeting }
-});
-```
-
-**Note**: Profile API requires "Advanced User Profile Access" feature and user interaction to grant permissions.
-
-### Conversations API
-
-Retrieve conversation history and messages between users and your Page or Instagram Business Account.
-
-#### Permissions Required
-
-**For Messenger conversations:**
-- `pages_manage_metadata`
-- `pages_read_engagement`
-- `pages_messaging`
-
-**For Instagram conversations:**
-- `instagram_basic`
-- `instagram_manage_messages`
-- `pages_manage_metadata`
-- Your app must be owned by a verified business
-
-#### List Conversations
-
-```typescript
-// List Messenger conversations
-const conversations = await messenger.conversations.list('PAGE_ID', {
-  platform: 'messenger',
-  limit: 25
-});
-
-// List Instagram conversations
-const igConversations = await messenger.conversations.list('PAGE_ID', {
-  platform: 'instagram',
-  limit: 25
-});
-
-// Find conversation with specific user
-const conversationId = await messenger.conversations.findByUser(
-  'PAGE_ID',
-  'USER_INSTAGRAM_SCOPED_ID',
-  'instagram'
-);
-```
-
-#### Get Conversation Details
-
-```typescript
-// Get conversation with messages and participants
-const conversation = await messenger.conversations.get('CONVERSATION_ID', {
-  fields: ['messages', 'participants'],
-  limit: 20
-});
-
-// Access participants
-conversation.participants?.data.forEach(participant => {
-  console.log(`${participant.name || participant.username} (${participant.id})`);
-});
-
-// Access messages
-conversation.messages?.data.forEach(msg => {
-  console.log(`Message ID: ${msg.id}, Created: ${msg.created_time}`);
-});
-```
-
-#### Get Message Details
-
-```typescript
-// Get full message details
-const message = await messenger.conversations.getMessage('MESSAGE_ID', {
-  fields: ['id', 'created_time', 'from', 'to', 'message', 'attachments', 'reactions', 'reply_to']
-});
-
-console.log(`From: ${message.from?.username}`);
-console.log(`Text: ${message.message}`);
-
-// Check attachments
-if (message.attachments?.data) {
-  message.attachments.data.forEach(att => {
-    console.log(`Attachment: ${att.file_url || att.image_data?.url}`);
-  });
-}
-
-// Check reactions
-if (message.reactions?.data) {
-  message.reactions.data.forEach(reaction => {
-    console.log(`${reaction.reaction} (${reaction.users.length} users)`);
-  });
-}
-```
-
-#### Get Recent Messages (Convenience Method)
-
-```typescript
-// Get the 20 most recent messages with full details
-const messages = await messenger.conversations.getRecentMessages('CONVERSATION_ID');
-
-messages.forEach(msg => {
-  const sender = msg.from?.name || msg.from?.username;
-  const text = msg.message || '(attachment)';
-  console.log(`${sender}: ${text}`);
-});
-```
-
-#### Pagination
-
-```typescript
-// Paginate through conversations
-let after: string | undefined;
-let hasMore = true;
-
-while (hasMore) {
-  const conversations = await messenger.conversations.list('PAGE_ID', {
-    platform: 'messenger',
-    limit: 25,
-    after
-  });
-
-  // Process conversations
-  console.log(`Fetched ${conversations.data.length} conversations`);
-
-  // Check for next page
-  if (conversations.paging?.cursors?.after) {
-    after = conversations.paging.cursors.after;
-  } else {
-    hasMore = false;
-  }
-}
-```
-
-#### Important Limitations
-
-- **20 Message Limit**: You can only retrieve full details for the **20 most recent messages** in a conversation. Older messages will return an error.
-- **Pending Messages**: Conversations in the "pending" folder that are inactive for 30+ days are not returned.
-- **Private Keys**: Accounts linked with private keys (email/phone) require Advanced Access approval to retrieve conversations.
-
-## Webhook Support
-
-The SDK provides comprehensive webhook support with full TypeScript safety through discriminated unions.
-
-### Webhook Types and Processing
-
-```typescript
-import {
-  processWebhookEvents,
-  extractWebhookEvents,
-  getWebhookEventType,
-  getWebhookPayloadEventTypes,
-  getPageWebhookEventTypes,
-  WebhookEventType,
-  GenericWebhookPayload,
-  PageWebhookPayload
-} from '@warriorteam/messenger-sdk';
-
-// Process webhook with type-safe handlers
-app.post('/webhook', express.json(), async (req, res) => {
-  const payload: GenericWebhookPayload = req.body;
-  
-  await processWebhookEvents(payload, {
-    onMessage: async (event) => {
-      // TypeScript knows this is MessageWebhookEvent
-      console.log(`Received message: ${event.message.text}`);
-    },
-    onMessageEdit: async (event) => {
-      // TypeScript knows this is MessageEditWebhookEvent
-      console.log(`Message edited to: ${event.message_edit.text}`);
-    },
-    onMessageReaction: async (event) => {
-      // TypeScript knows this is MessageReactionWebhookEvent
-      console.log(`Reaction: ${event.reaction.reaction}`);
-    },
-    onMessagingPostback: async (event) => {
-      // TypeScript knows this is MessagingPostbackWebhookEvent
-      console.log(`Postback: ${event.postback.payload}`);
-    }
-  });
-  
-  res.sendStatus(200);
-});
-```
-
-### Manual Event Processing
-
-```typescript
-// Extract events manually
-const events = extractWebhookEvents(payload);
-for (const event of events) {
-  const eventType = getWebhookEventType(event);
-  
-  switch (eventType) {
-    case WebhookEventType.MESSAGE:
-      // Handle message event
-      break;
-    case WebhookEventType.MESSAGE_EDIT:
-      // Handle edit event
-      break;
-    // ... other cases
-  }
-}
-
-// Check what event types are in the payload (Messenger events)
-const eventTypes = getWebhookPayloadEventTypes(payload);
-console.log('Received Messenger event types:', eventTypes); // e.g., ['message', 'postback']
-
-// For Page webhooks, use getPageWebhookEventTypes instead:
-// const pagePayload: PageWebhookPayload = req.body;
-// const pageEventTypes = getPageWebhookEventTypes(pagePayload);
-// console.log('Received Page event types:', pageEventTypes); // e.g., [WebhookEventType.FEED, WebhookEventType.VIDEOS]
-```
-
-### Webhook Verification
-
-The SDK provides utilities for both subscription verification and signature validation:
-
-```typescript
-import { 
-  verifyWebhookSubscription, 
-  verifyWebhookSignature 
-} from '@warriorteam/messenger-sdk';
-
-// Subscription verification (GET request)
-app.get('/webhook', (req, res) => {
-  const challenge = verifyWebhookSubscription(
-    req.query as any, 
-    process.env.VERIFY_TOKEN!
-  );
-  
-  if (challenge) {
-    res.send(challenge);
-  } else {
-    res.status(403).send('Forbidden');
-  }
-});
-
-// Signature verification (POST request)
-app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
-  const signature = req.get('X-Hub-Signature-256');
-  const result = await verifyWebhookSignature(
-    req.body, 
-    signature, 
-    process.env.APP_SECRET!
-  );
-  
-  if (!result.isValid) {
-    return res.status(401).json({error: result.error});
-  }
-  
-  // Process webhook events...
-  const payload = JSON.parse(req.body.toString());
-  // ... handle events
-});
-```
-
-### Type-Safe Event Handling
-
-The SDK uses discriminated unions for perfect TypeScript support:
-
-```typescript
-import { 
-  MessengerWebhookEvent,
-  isMessageEvent,
-  isMessageEditEvent,
-  isMessagingPostbackEvent 
-} from '@warriorteam/messenger-sdk';
-
-function handleWebhookEvent(event: MessengerWebhookEvent) {
-  if (isMessageEvent(event)) {
-    // TypeScript knows event.message exists
-    console.log(`Message: ${event.message.text}`);
-  } else if (isMessageEditEvent(event)) {
-    // TypeScript knows event.message_edit exists
-    console.log(`Edit: ${event.message_edit.text}`);
-  } else if (isMessagingPostbackEvent(event)) {
-    // TypeScript knows event.postback exists
-    console.log(`Postback: ${event.postback.payload}`);
-  }
-}
-```
-
-### Supported Webhook Event Types
-
-#### Messenger Platform Events
-- `MESSAGE` - User sends a message
-- `MESSAGE_EDIT` - User edits a sent message
-- `MESSAGE_REACTION` - User reacts to a message
-- `MESSAGE_READ` - User reads messages (read receipts)
-- `MESSAGING_FEEDBACK` - User submits feedback via templates
-- `MESSAGING_POSTBACK` - User clicks buttons/quick replies
-
-#### Page Webhook Events
-- `FEED` - Page feed changes (posts, photos, videos, status updates)
-- `VIDEOS` - Video encoding status changes (processing, ready, error)
-- `LIVE_VIDEOS` - Live video status changes (live, stopped, scheduled, VOD ready)
-
-### Page Webhook Type Helpers
-
-The SDK provides specialized type guards and helpers for Page webhook events:
-
-```typescript
-import {
-  isFeedEvent,
-  isVideoEvent,
-  isLiveVideoEvent,
-  isVideoProcessing,
-  isVideoReady,
-  isLiveVideoProcessing,
-  isLive,
-  extractVideoContext,
-  extractLiveVideoContext,
-  getPageWebhookEventTypes,
-  FeedActionVerb,
-  VideoStatus,
-  LiveVideoStatus,
-  PageWebhookPayload
-} from '@warriorteam/messenger-sdk';
-
-// Handle Page webhooks
-app.post('/webhook/page', express.json(), async (req, res) => {
-  const payload: PageWebhookPayload = req.body;
-
-  // Check what types of Page events are in this payload
-  const eventTypes = getPageWebhookEventTypes(payload);
-  console.log('Received Page event types:', eventTypes); // e.g., [WebhookEventType.FEED, WebhookEventType.VIDEOS]
-
-  for (const entry of payload.entry) {
-    for (const change of entry.changes || []) {
-      // Feed events (posts, photos, videos, status)
-      if (isFeedEvent(change)) {
-        console.log(`Feed ${change.value.verb}: ${change.value.item} by ${change.value.from.id}`);
-        if (change.value.verb === FeedActionVerb.ADD) {
-          console.log('New post created!');
-        }
-      }
-
-      // Video encoding events
-      if (isVideoEvent(change)) {
-        const context = extractVideoContext(entry.id, entry.time, change);
-        if (context.isReady) {
-          console.log(`Video ${context.videoId} is ready!`);
-        } else if (context.isProcessing) {
-          console.log(`Video ${context.videoId} is still processing...`);
-        }
-      }
-
-      // Live video events
-      if (isLiveVideoEvent(change)) {
-        const context = extractLiveVideoContext(entry.id, entry.time, change);
-        if (context.isLive) {
-          console.log(`Live stream ${context.videoId} is now live!`);
-        } else if (context.isVODReady) {
-          console.log(`Live stream ${context.videoId} VOD is ready!`);
-        }
-      }
-    }
-  }
-
-  res.sendStatus(200);
-});
-```
-
-**Note**: Page webhooks use a different structure (`entry[].changes[]`) compared to Messenger webhooks (`entry[].messaging[]`). The SDK provides helpers for both.
-
-### Complete Controller Example (NestJS/Express)
-
-Here's a complete TypeScript controller for handling webhooks with proper types:
-
-```typescript
-import { Controller, Post, Body, Headers, Res, Get, Query } from '@nestjs/common';
-import { Response } from 'express';
-import {
-  GenericWebhookPayload,
-  PageWebhookPayload,
-  verifyWebhookSignature,
-  verifyWebhookSubscription,
-  processWebhookEvents,
-  isFeedEvent,
-  isVideoEvent,
-  isLiveVideoEvent,
-} from '@warriorteam/messenger-sdk';
-
-@Controller('webhook')
-export class WebhookController {
-  // Subscription verification (GET)
-  @Get()
-  verifyWebhook(@Query() query: any, @Res() res: Response) {
-    const challenge = verifyWebhookSubscription(
-      query,
-      process.env.VERIFY_TOKEN!
-    );
-
-    if (challenge) {
-      return res.send(challenge);
-    }
-    return res.status(403).send('Forbidden');
-  }
-
-  // Messenger webhooks (POST)
-  @Post('messenger')
-  async handleMessenger(
-    @Body() payload: GenericWebhookPayload,  // ← Correct type for Messenger
-    @Headers('x-hub-signature-256') signature: string,
-    @Res() res: Response
-  ) {
-    // Verify signature
-    const verification = await verifyWebhookSignature(
-      JSON.stringify(payload),
-      signature,
-      process.env.APP_SECRET!
-    );
-
-    if (!verification.isValid) {
-      return res.status(401).json({ error: 'Invalid signature' });
-    }
-
-    // Process events with type-safe handlers
-    await processWebhookEvents(payload, {
-      onMessage: async (event) => {
-        // event is MessageWebhookEvent - fully typed!
-        console.log(`From ${event.sender.id}: ${event.message.text}`);
-      },
-      onMessagingPostback: async (event) => {
-        // event is MessagingPostbackWebhookEvent
-        console.log(`Button clicked: ${event.postback.payload}`);
-      },
-      onMessageReaction: async (event) => {
-        // event is MessageReactionWebhookEvent
-        console.log(`Reaction: ${event.reaction.reaction}`);
-      },
-    });
-
-    return res.sendStatus(200);
-  }
-
-  // Page webhooks (POST)
-  @Post('page')
-  async handlePage(
-    @Body() payload: PageWebhookPayload,  // ← Correct type for Page webhooks
-    @Headers('x-hub-signature-256') signature: string,
-    @Res() res: Response
-  ) {
-    // Verify signature
-    const verification = await verifyWebhookSignature(
-      JSON.stringify(payload),
-      signature,
-      process.env.APP_SECRET!
-    );
-
-    if (!verification.isValid) {
-      return res.status(401).json({ error: 'Invalid signature' });
-    }
-
-    // Process Page events
-    for (const entry of payload.entry) {
-      for (const change of entry.changes || []) {
-        if (isFeedEvent(change)) {
-          console.log(`Page feed: ${change.value.verb} ${change.value.item}`);
-        }
-
-        if (isVideoEvent(change)) {
-          console.log(`Video status: ${change.value.status.video_status}`);
-        }
-
-        if (isLiveVideoEvent(change)) {
-          console.log(`Live video status: ${change.value.status}`);
-        }
-      }
-    }
-
-    return res.sendStatus(200);
-  }
-}
-```
-
-**Key Types to Use:**
-- `GenericWebhookPayload` - For Messenger Platform webhooks (`entry[].messaging[]`)
-- `PageWebhookPayload` - For Page webhooks (`entry[].changes[]`)
-
-## Error Handling
-
-The SDK provides specific error types for different scenarios:
-
-```typescript
-import { 
-  MessengerAPIError, 
-  MessengerNetworkError, 
-  MessengerTimeoutError,
-  MessengerConfigError 
-} from '@warriorteam/messenger-sdk';
-
-try {
-  await messenger.send.message({
-    recipient: { id: 'USER_PSID' },
-    message: { text: 'Hello!' }
-  });
-} catch (error) {
-  if (error instanceof MessengerAPIError) {
-    console.error('API Error:', error.message, error.code);
-  } else if (error instanceof MessengerNetworkError) {
-    console.error('Network Error:', error.message);
-  } else if (error instanceof MessengerTimeoutError) {
-    console.error('Timeout Error:', error.timeout);
-  }
-}
-```
-
-## Examples
-
-Check the `examples/` directory for complete usage examples:
-
-- `send-message.ts` - Basic message sending
-- `upload-attachment.ts` - Attachment handling
-- `send-template.ts` - Template messages
-- `user-profile.ts` - Profile API usage
-- `moderation.ts` - User moderation
-- `conversations.ts` - Retrieve conversations and messages
-- `webhook-handler.ts` - Complete webhook setup with type safety
-- `multi-tenant.ts` - Token override for multi-tenant applications
-- `signature-verification.ts` - Webhook security implementation
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run tests
-npm test
-
-# Lint code
-npm run lint
-
-# Format code
-npm run format
-```
-
-## Changelog
-
-### v1.5.2 (Latest)
-- **Added**: `getPageWebhookEventTypes()` utility function for extracting event types from Page webhooks
-  - Returns `WebhookEventType[]` array with proper enum values (e.g., `[WebhookEventType.FEED, WebhookEventType.VIDEOS]`)
-  - Maps Page webhook `field` values to `WebhookEventType` enum for type safety
-  - Similar to `getWebhookPayloadEventTypes()` but for `PageWebhookPayload` structure
-  - Properly exported from main package
-- **Improved**: Documentation with usage examples for Page webhook event type extraction
-
-### v1.5.1
-- **Added**: Complete NestJS/Express webhook controller example in README
-- **Updated**: WebhookEventType enum to include FEED, VIDEOS, LIVE_VIDEOS
-- **Improved**: Documentation with clear type usage for webhook handlers and Page webhook utilities
-
-### v1.5.0
-- **Added**: Conversations API for retrieving conversation history and messages
-  - List conversations for Messenger and Instagram
-  - Get conversation details with participants and messages
-  - Retrieve individual message details with attachments, reactions, and replies
-  - Convenience method for getting recent messages with full details
-  - Find conversations by user ID
-  - Full pagination support
-  - Support for both Messenger and Instagram platforms
-  - Token override support for multi-tenant applications
-- **Added**: Comprehensive TypeScript types for Conversations API
-  - `Conversation`, `ConversationDetail`, `Message` types
-  - Message attachments, reactions, shares, story replies
-  - Image/video data types for media attachments
-  - Request/response types for all operations
-
-### v1.4.2
-- **Fixed**: Resolved export naming conflicts for `isProcessing` function between video and live video webhooks
-  - `isProcessing` from videos module now exported as `isVideoProcessing`
-  - `isProcessing` from live-videos module now exported as `isLiveVideoProcessing`
-  - Added explicit exports for all video and live video helper functions with unique names
-  - Similar to existing pattern used for `ReferralType` and `ReferralSource` conflicts
-- **Improved**: Better TypeScript type safety with no export ambiguities
-
-### v1.4.x
-- **Added**: Comprehensive Facebook Page webhook types
-  - Feed webhook events (posts, photos, videos, status updates)
-  - Video encoding webhook events (processing, ready, error states)
-  - Live video webhook events (live, stopped, scheduled, VOD ready)
-- **Added**: Type guards and helper functions for all Page webhook events
-- **Added**: Context extraction utilities for video events
-
-### v1.3.x
-- **Added**: Token override support for multi-tenant applications
-- **Improved**: All API methods now accept optional `RequestOptions` parameter
-
-### v1.1.0
-- **Added**: User Profile API support
-
-## License
-
-MIT
-
-## Support
-
+# @warriorteam/messenger-sdk
+
+A modern TypeScript SDK for the Facebook Messenger Platform API, designed with simplicity and type safety in mind.
+
+## Features
+
+- 🚀 **Zero runtime dependencies** - Built with native fetch
+- 📝 **Full TypeScript support** - Complete type definitions with discriminated unions
+- 🔄 **Dual module support** - ESM and CommonJS
+- ✅ **Comprehensive validation** - Built-in message and template validation
+- 🛡️ **Error handling** - Detailed error types and messages
+- 📚 **Complete API coverage** - Send API, Templates, Attachments, Moderation, Profile, Conversations
+- 💬 **Conversations API** - Retrieve conversation history and messages for Messenger & Instagram
+- 🔐 **Webhook utilities** - Complete webhook type system and signature verification
+- 🎯 **Token override** - Per-method access token override support
+- 🔧 **Type-safe webhooks** - Discriminated unions for proper TypeScript narrowing
+
+## Installation
+
+```bash
+npm install @warriorteam/messenger-sdk
+```
+
+## Requirements
+
+- Node.js 18+ (for native fetch support)
+- A Facebook Page Access Token
+
+## Quick Start
+
+```typescript
+import { Messenger } from '@warriorteam/messenger-sdk';
+
+const messenger = new Messenger({
+  accessToken: 'YOUR_PAGE_ACCESS_TOKEN',
+  version: 'v23.0'
+});
+
+// Send a text message
+const result = await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: { text: 'Hello from RedAI Messenger SDK!' }
+});
+
+console.log('Message sent:', result.message_id);
+```
+
+## API Reference
+
+### Client Configuration
+
+```typescript
+const messenger = new Messenger({
+  accessToken?: string;   // Optional: Default page access token
+  version?: string;       // Optional: API version (default: 'v23.0')
+  baseUrl?: string;       // Optional: Custom base URL
+  timeout?: number;       // Optional: Request timeout in ms (default: 30000)
+  maxRetries?: number;    // Optional: Max retry attempts (default: 3)
+});
+```
+
+### Token Override Support
+
+Every API method supports per-call access token override, perfect for multi-tenant applications:
+
+```typescript
+const messenger = new Messenger({
+  accessToken: 'default_page_token'
+});
+
+// Use default token
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: { text: 'Hello from default page!' }
+});
+
+// Override token for this specific call
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: { text: 'Hello from different page!' }
+}, {
+  accessToken: 'other_page_token'
+});
+
+// Works with all API methods
+const profile = await messenger.profile.getBasic('USER_PSID', {
+  accessToken: 'specific_token'
+});
+```
+
+### Send API
+
+#### Send Text Message
+
+```typescript
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: { text: 'Hello World!' }
+});
+```
+
+#### Send Message with Quick Replies
+
+```typescript
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: {
+    text: 'Pick a color:',
+    quick_replies: [
+      { content_type: 'text', title: 'Red', payload: 'PICKED_RED' },
+      { content_type: 'text', title: 'Blue', payload: 'PICKED_BLUE' }
+    ]
+  }
+});
+```
+
+#### Sender Actions
+
+Manage conversation state and reactions:
+
+```typescript
+// Typing indicators
+await messenger.send.typingOn('USER_PSID');
+await messenger.send.typingOff('USER_PSID');
+
+// Helper to toggle typing based on boolean
+await messenger.send.setTyping('USER_PSID', true);
+
+// Mark as read/seen
+await messenger.send.markRead('USER_PSID');
+
+// React to a message
+await messenger.send.addReaction('USER_PSID', {
+  messageId: 'MESSAGE_ID',
+  emoji: '❤️'
+});
+
+// Remove reaction
+await messenger.send.removeReaction('USER_PSID', 'MESSAGE_ID');
+```
+
+#### Response Format
+
+The Send API response includes a `message_id` and optionally a `recipient_id`:
+
+```typescript
+const result = await messenger.send.message({...});
+console.log('Message ID:', result.message_id); // Always present
+console.log('Recipient ID:', result.recipient_id || 'Not provided'); // Optional
+```
+
+**Note**: `recipient_id` is only included when using `recipient.id` (PSID). It's not included when using `recipient.user_ref` or `recipient.phone_number`.
+
+### Attachments API
+
+#### Upload Attachment from URL
+
+```typescript
+const attachment = await messenger.attachments.upload({
+  type: 'image',
+  url: 'https://example.com/image.jpg',
+  is_reusable: true
+});
+
+// Use the attachment ID to send
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: {
+    attachment: {
+      type: 'image',
+      payload: { attachment_id: attachment.attachment_id }
+    }
+  }
+});
+```
+
+#### Send Attachment Directly
+
+```typescript
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  message: {
+    attachment: {
+      type: 'image',
+      payload: { url: 'https://example.com/image.jpg' }
+    }
+  }
+});
+```
+
+### Templates API
+
+#### Generic Template
+
+```typescript
+await messenger.templates.generic({
+  recipient: { id: 'USER_PSID' },
+  elements: [{
+    title: 'Welcome',
+    subtitle: 'Check out our products',
+    image_url: 'https://example.com/image.jpg',
+    buttons: [{
+      type: 'web_url',
+      title: 'Shop Now',
+      url: 'https://example.com/shop'
+    }]
+  }]
+});
+```
+
+#### Button Template
+
+```typescript
+await messenger.templates.button({
+  recipient: { id: 'USER_PSID' },
+  text: 'What would you like to do?',
+  buttons: [{
+    type: 'postback',
+    title: 'Get Started',
+    payload: 'GET_STARTED'
+  }]
+});
+```
+
+### Moderation API
+
+#### User Moderation
+
+```typescript
+// Block a user from messaging (can still see page content)
+await messenger.moderation.blockUser('USER_PSID');
+
+// Ban a user completely (no messaging + no Facebook interactions)
+await messenger.moderation.banUser('USER_PSID');
+
+// Move conversation to spam folder
+await messenger.moderation.moveToSpam('USER_PSID');
+
+// Block and spam (common combo)
+await messenger.moderation.blockAndSpam('USER_PSID');
+
+// Multiple users at once
+await messenger.moderation.blockUser(['USER_1', 'USER_2', 'USER_3']);
+
+// Unblock/unban users
+await messenger.moderation.unblockUser('USER_PSID');
+await messenger.moderation.unbanUser('USER_PSID');
+```
+
+### Profile API
+
+#### Get User Profile Information
+
+```typescript
+// Get basic profile info (first_name, last_name, profile_pic)
+const profile = await messenger.profile.getBasic('USER_PSID');
+console.log(`Hello ${profile.first_name}!`);
+
+// Get comprehensive profile with all fields
+const fullProfile = await messenger.profile.getFull('USER_PSID');
+console.log('Profile:', fullProfile);
+// Returns: { id, name, first_name, last_name, profile_pic, locale, timezone, gender }
+
+// Get specific fields only
+const customProfile = await messenger.profile.get({
+  psid: 'USER_PSID',
+  fields: ['first_name', 'locale', 'timezone']
+});
+
+// Helper methods for common use cases
+const nameInfo = await messenger.profile.getName('USER_PSID');
+const profilePic = await messenger.profile.getProfilePicture('USER_PSID');
+```
+
+#### Personalize Messages
+
+```typescript
+// Use profile info to personalize messages
+const profile = await messenger.profile.getName('USER_PSID');
+const greeting = profile.first_name 
+  ? `Hello ${profile.first_name}! Welcome back!`
+  : 'Hello! Welcome back!';
+
+await messenger.send.message({
+  recipient: { id: 'USER_PSID' },
+  messaging_type: 'RESPONSE',
+  message: { text: greeting }
+});
+```
+
+**Note**: Profile API requires "Advanced User Profile Access" feature and user interaction to grant permissions.
+
+### Conversations API
+
+Retrieve conversation history and messages between users and your Page or Instagram Business Account.
+
+#### Permissions Required
+
+**For Messenger conversations:**
+- `pages_manage_metadata`
+- `pages_read_engagement`
+- `pages_messaging`
+
+**For Instagram conversations:**
+- `instagram_basic`
+- `instagram_manage_messages`
+- `pages_manage_metadata`
+- Your app must be owned by a verified business
+
+#### List Conversations
+
+```typescript
+// List Messenger conversations
+const conversations = await messenger.conversations.list('PAGE_ID', {
+  platform: 'messenger',
+  limit: 25
+});
+
+// List Instagram conversations
+const igConversations = await messenger.conversations.list('PAGE_ID', {
+  platform: 'instagram',
+  limit: 25
+});
+
+// Find conversation with specific user
+const conversationId = await messenger.conversations.findByUser(
+  'PAGE_ID',
+  'USER_INSTAGRAM_SCOPED_ID',
+  'instagram'
+);
+```
+
+#### Get Conversation Details
+
+```typescript
+// Get conversation with messages and participants
+const conversation = await messenger.conversations.get('CONVERSATION_ID', {
+  fields: ['messages', 'participants'],
+  limit: 20
+});
+
+// Access participants
+conversation.participants?.data.forEach(participant => {
+  console.log(`${participant.name || participant.username} (${participant.id})`);
+});
+
+// Access messages
+conversation.messages?.data.forEach(msg => {
+  console.log(`Message ID: ${msg.id}, Created: ${msg.created_time}`);
+});
+```
+
+#### Get Message Details
+
+```typescript
+// Get full message details
+const message = await messenger.conversations.getMessage('MESSAGE_ID', {
+  fields: ['id', 'created_time', 'from', 'to', 'message', 'attachments', 'reactions', 'reply_to']
+});
+
+console.log(`From: ${message.from?.username}`);
+console.log(`Text: ${message.message}`);
+
+// Check attachments
+if (message.attachments?.data) {
+  message.attachments.data.forEach(att => {
+    console.log(`Attachment: ${att.file_url || att.image_data?.url}`);
+  });
+}
+
+// Check reactions
+if (message.reactions?.data) {
+  message.reactions.data.forEach(reaction => {
+    console.log(`${reaction.reaction} (${reaction.users.length} users)`);
+  });
+}
+```
+
+#### Get Recent Messages (Convenience Method)
+
+```typescript
+// Get the 20 most recent messages with full details
+const messages = await messenger.conversations.getRecentMessages('CONVERSATION_ID');
+
+messages.forEach(msg => {
+  const sender = msg.from?.name || msg.from?.username;
+  const text = msg.message || '(attachment)';
+  console.log(`${sender}: ${text}`);
+});
+```
+
+#### Pagination
+
+```typescript
+// Paginate through conversations
+let after: string | undefined;
+let hasMore = true;
+
+while (hasMore) {
+  const conversations = await messenger.conversations.list('PAGE_ID', {
+    platform: 'messenger',
+    limit: 25,
+    after
+  });
+
+  // Process conversations
+  console.log(`Fetched ${conversations.data.length} conversations`);
+
+  // Check for next page
+  if (conversations.paging?.cursors?.after) {
+    after = conversations.paging.cursors.after;
+  } else {
+    hasMore = false;
+  }
+}
+```
+
+#### Important Limitations
+
+- **20 Message Limit**: You can only retrieve full details for the **20 most recent messages** in a conversation. Older messages will return an error.
+- **Pending Messages**: Conversations in the "pending" folder that are inactive for 30+ days are not returned.
+- **Private Keys**: Accounts linked with private keys (email/phone) require Advanced Access approval to retrieve conversations.
+
+## Webhook Support
+
+The SDK provides comprehensive webhook support with full TypeScript safety through discriminated unions.
+
+### Webhook Types and Processing
+
+```typescript
+import {
+  processWebhookEvents,
+  extractWebhookEvents,
+  getWebhookEventType,
+  getWebhookPayloadEventTypes,
+  getPageWebhookEventTypes,
+  WebhookEventType,
+  GenericWebhookPayload,
+  PageWebhookPayload
+} from '@warriorteam/messenger-sdk';
+
+// Process webhook with type-safe handlers
+app.post('/webhook', express.json(), async (req, res) => {
+  const payload: GenericWebhookPayload = req.body;
+  
+  await processWebhookEvents(payload, {
+    onMessage: async (event) => {
+      // TypeScript knows this is MessageWebhookEvent
+      console.log(`Received message: ${event.message.text}`);
+    },
+    onMessageEdit: async (event) => {
+      // TypeScript knows this is MessageEditWebhookEvent
+      console.log(`Message edited to: ${event.message_edit.text}`);
+    },
+    onMessageReaction: async (event) => {
+      // TypeScript knows this is MessageReactionWebhookEvent
+      console.log(`Reaction: ${event.reaction.reaction}`);
+    },
+    onMessagingPostback: async (event) => {
+      // TypeScript knows this is MessagingPostbackWebhookEvent
+      console.log(`Postback: ${event.postback.payload}`);
+    }
+  });
+  
+  res.sendStatus(200);
+});
+```
+
+### Manual Event Processing
+
+```typescript
+// Extract events manually
+const events = extractWebhookEvents(payload);
+for (const event of events) {
+  const eventType = getWebhookEventType(event);
+  
+  switch (eventType) {
+    case WebhookEventType.MESSAGE:
+      // Handle message event
+      break;
+    case WebhookEventType.MESSAGE_EDIT:
+      // Handle edit event
+      break;
+    // ... other cases
+  }
+}
+
+// Check what event types are in the payload (Messenger events)
+const eventTypes = getWebhookPayloadEventTypes(payload);
+console.log('Received Messenger event types:', eventTypes); // e.g., ['message', 'postback']
+
+// For Page webhooks, use getPageWebhookEventTypes instead:
+// const pagePayload: PageWebhookPayload = req.body;
+// const pageEventTypes = getPageWebhookEventTypes(pagePayload);
+// console.log('Received Page event types:', pageEventTypes); // e.g., [WebhookEventType.FEED, WebhookEventType.VIDEOS]
+```
+
+### Webhook Verification
+
+The SDK provides utilities for both subscription verification and signature validation:
+
+```typescript
+import { 
+  verifyWebhookSubscription, 
+  verifyWebhookSignature 
+} from '@warriorteam/messenger-sdk';
+
+// Subscription verification (GET request)
+app.get('/webhook', (req, res) => {
+  const challenge = verifyWebhookSubscription(
+    req.query as any, 
+    process.env.VERIFY_TOKEN!
+  );
+  
+  if (challenge) {
+    res.send(challenge);
+  } else {
+    res.status(403).send('Forbidden');
+  }
+});
+
+// Signature verification (POST request)
+app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
+  const signature = req.get('X-Hub-Signature-256');
+  const result = await verifyWebhookSignature(
+    req.body, 
+    signature, 
+    process.env.APP_SECRET!
+  );
+  
+  if (!result.isValid) {
+    return res.status(401).json({error: result.error});
+  }
+  
+  // Process webhook events...
+  const payload = JSON.parse(req.body.toString());
+  // ... handle events
+});
+```
+
+### Type-Safe Event Handling
+
+The SDK uses discriminated unions for perfect TypeScript support:
+
+```typescript
+import { 
+  MessengerWebhookEvent,
+  isMessageEvent,
+  isMessageEditEvent,
+  isMessagingPostbackEvent 
+} from '@warriorteam/messenger-sdk';
+
+function handleWebhookEvent(event: MessengerWebhookEvent) {
+  if (isMessageEvent(event)) {
+    // TypeScript knows event.message exists
+    console.log(`Message: ${event.message.text}`);
+  } else if (isMessageEditEvent(event)) {
+    // TypeScript knows event.message_edit exists
+    console.log(`Edit: ${event.message_edit.text}`);
+  } else if (isMessagingPostbackEvent(event)) {
+    // TypeScript knows event.postback exists
+    console.log(`Postback: ${event.postback.payload}`);
+  }
+}
+```
+
+### Supported Webhook Event Types
+
+#### Messenger Platform Events
+- `MESSAGE` - User sends a message
+- `MESSAGE_EDIT` - User edits a sent message
+- `MESSAGE_REACTION` - User reacts to a message
+- `MESSAGE_READ` - User reads messages (read receipts)
+- `MESSAGING_FEEDBACK` - User submits feedback via templates
+- `MESSAGING_POSTBACK` - User clicks buttons/quick replies
+
+#### Page Webhook Events
+- `FEED` - Page feed changes (posts, photos, videos, status updates)
+- `VIDEOS` - Video encoding status changes (processing, ready, error)
+- `LIVE_VIDEOS` - Live video status changes (live, stopped, scheduled, VOD ready)
+
+### Page Webhook Type Helpers
+
+The SDK provides specialized type guards and helpers for Page webhook events:
+
+```typescript
+import {
+  isFeedEvent,
+  isVideoEvent,
+  isLiveVideoEvent,
+  isVideoProcessing,
+  isVideoReady,
+  isLiveVideoProcessing,
+  isLive,
+  extractVideoContext,
+  extractLiveVideoContext,
+  getPageWebhookEventTypes,
+  FeedActionVerb,
+  VideoStatus,
+  LiveVideoStatus,
+  PageWebhookPayload
+} from '@warriorteam/messenger-sdk';
+
+// Handle Page webhooks
+app.post('/webhook/page', express.json(), async (req, res) => {
+  const payload: PageWebhookPayload = req.body;
+
+  // Check what types of Page events are in this payload
+  const eventTypes = getPageWebhookEventTypes(payload);
+  console.log('Received Page event types:', eventTypes); // e.g., [WebhookEventType.FEED, WebhookEventType.VIDEOS]
+
+  for (const entry of payload.entry) {
+    for (const change of entry.changes || []) {
+      // Feed events (posts, photos, videos, status)
+      if (isFeedEvent(change)) {
+        console.log(`Feed ${change.value.verb}: ${change.value.item} by ${change.value.from.id}`);
+        if (change.value.verb === FeedActionVerb.ADD) {
+          console.log('New post created!');
+        }
+      }
+
+      // Video encoding events
+      if (isVideoEvent(change)) {
+        const context = extractVideoContext(entry.id, entry.time, change);
+        if (context.isReady) {
+          console.log(`Video ${context.videoId} is ready!`);
+        } else if (context.isProcessing) {
+          console.log(`Video ${context.videoId} is still processing...`);
+        }
+      }
+
+      // Live video events
+      if (isLiveVideoEvent(change)) {
+        const context = extractLiveVideoContext(entry.id, entry.time, change);
+        if (context.isLive) {
+          console.log(`Live stream ${context.videoId} is now live!`);
+        } else if (context.isVODReady) {
+          console.log(`Live stream ${context.videoId} VOD is ready!`);
+        }
+      }
+    }
+  }
+
+  res.sendStatus(200);
+});
+```
+
+**Note**: Page webhooks use a different structure (`entry[].changes[]`) compared to Messenger webhooks (`entry[].messaging[]`). The SDK provides helpers for both.
+
+### Complete Controller Example (NestJS/Express)
+
+Here's a complete TypeScript controller for handling webhooks with proper types:
+
+```typescript
+import { Controller, Post, Body, Headers, Res, Get, Query } from '@nestjs/common';
+import { Response } from 'express';
+import {
+  GenericWebhookPayload,
+  PageWebhookPayload,
+  verifyWebhookSignature,
+  verifyWebhookSubscription,
+  processWebhookEvents,
+  isFeedEvent,
+  isVideoEvent,
+  isLiveVideoEvent,
+} from '@warriorteam/messenger-sdk';
+
+@Controller('webhook')
+export class WebhookController {
+  // Subscription verification (GET)
+  @Get()
+  verifyWebhook(@Query() query: any, @Res() res: Response) {
+    const challenge = verifyWebhookSubscription(
+      query,
+      process.env.VERIFY_TOKEN!
+    );
+
+    if (challenge) {
+      return res.send(challenge);
+    }
+    return res.status(403).send('Forbidden');
+  }
+
+  // Messenger webhooks (POST)
+  @Post('messenger')
+  async handleMessenger(
+    @Body() payload: GenericWebhookPayload,  // ← Correct type for Messenger
+    @Headers('x-hub-signature-256') signature: string,
+    @Res() res: Response
+  ) {
+    // Verify signature
+    const verification = await verifyWebhookSignature(
+      JSON.stringify(payload),
+      signature,
+      process.env.APP_SECRET!
+    );
+
+    if (!verification.isValid) {
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    // Process events with type-safe handlers
+    await processWebhookEvents(payload, {
+      onMessage: async (event) => {
+        // event is MessageWebhookEvent - fully typed!
+        console.log(`From ${event.sender.id}: ${event.message.text}`);
+      },
+      onMessagingPostback: async (event) => {
+        // event is MessagingPostbackWebhookEvent
+        console.log(`Button clicked: ${event.postback.payload}`);
+      },
+      onMessageReaction: async (event) => {
+        // event is MessageReactionWebhookEvent
+        console.log(`Reaction: ${event.reaction.reaction}`);
+      },
+    });
+
+    return res.sendStatus(200);
+  }
+
+  // Page webhooks (POST)
+  @Post('page')
+  async handlePage(
+    @Body() payload: PageWebhookPayload,  // ← Correct type for Page webhooks
+    @Headers('x-hub-signature-256') signature: string,
+    @Res() res: Response
+  ) {
+    // Verify signature
+    const verification = await verifyWebhookSignature(
+      JSON.stringify(payload),
+      signature,
+      process.env.APP_SECRET!
+    );
+
+    if (!verification.isValid) {
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    // Process Page events
+    for (const entry of payload.entry) {
+      for (const change of entry.changes || []) {
+        if (isFeedEvent(change)) {
+          console.log(`Page feed: ${change.value.verb} ${change.value.item}`);
+        }
+
+        if (isVideoEvent(change)) {
+          console.log(`Video status: ${change.value.status.video_status}`);
+        }
+
+        if (isLiveVideoEvent(change)) {
+          console.log(`Live video status: ${change.value.status}`);
+        }
+      }
+    }
+
+    return res.sendStatus(200);
+  }
+}
+```
+
+**Key Types to Use:**
+- `GenericWebhookPayload` - For Messenger Platform webhooks (`entry[].messaging[]`)
+- `PageWebhookPayload` - For Page webhooks (`entry[].changes[]`)
+
+## Error Handling
+
+The SDK provides specific error types for different scenarios:
+
+```typescript
+import { 
+  MessengerAPIError, 
+  MessengerNetworkError, 
+  MessengerTimeoutError,
+  MessengerConfigError 
+} from '@warriorteam/messenger-sdk';
+
+try {
+  await messenger.send.message({
+    recipient: { id: 'USER_PSID' },
+    message: { text: 'Hello!' }
+  });
+} catch (error) {
+  if (error instanceof MessengerAPIError) {
+    console.error('API Error:', error.message, error.code);
+  } else if (error instanceof MessengerNetworkError) {
+    console.error('Network Error:', error.message);
+  } else if (error instanceof MessengerTimeoutError) {
+    console.error('Timeout Error:', error.timeout);
+  }
+}
+```
+
+## Examples
+
+Check the `examples/` directory for complete usage examples:
+
+- `send-message.ts` - Basic message sending
+- `upload-attachment.ts` - Attachment handling
+- `send-template.ts` - Template messages
+- `user-profile.ts` - Profile API usage
+- `moderation.ts` - User moderation
+- `conversations.ts` - Retrieve conversations and messages
+- `webhook-handler.ts` - Complete webhook setup with type safety
+- `multi-tenant.ts` - Token override for multi-tenant applications
+- `signature-verification.ts` - Webhook security implementation
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Changelog
+
+### v1.5.2 (Latest)
+- **Added**: `getPageWebhookEventTypes()` utility function for extracting event types from Page webhooks
+  - Returns `WebhookEventType[]` array with proper enum values (e.g., `[WebhookEventType.FEED, WebhookEventType.VIDEOS]`)
+  - Maps Page webhook `field` values to `WebhookEventType` enum for type safety
+  - Similar to `getWebhookPayloadEventTypes()` but for `PageWebhookPayload` structure
+  - Properly exported from main package
+- **Improved**: Documentation with usage examples for Page webhook event type extraction
+
+### v1.5.1
+- **Added**: Complete NestJS/Express webhook controller example in README
+- **Updated**: WebhookEventType enum to include FEED, VIDEOS, LIVE_VIDEOS
+- **Improved**: Documentation with clear type usage for webhook handlers and Page webhook utilities
+
+### v1.5.0
+- **Added**: Conversations API for retrieving conversation history and messages
+  - List conversations for Messenger and Instagram
+  - Get conversation details with participants and messages
+  - Retrieve individual message details with attachments, reactions, and replies
+  - Convenience method for getting recent messages with full details
+  - Find conversations by user ID
+  - Full pagination support
+  - Support for both Messenger and Instagram platforms
+  - Token override support for multi-tenant applications
+- **Added**: Comprehensive TypeScript types for Conversations API
+  - `Conversation`, `ConversationDetail`, `Message` types
+  - Message attachments, reactions, shares, story replies
+  - Image/video data types for media attachments
+  - Request/response types for all operations
+
+### v1.4.2
+- **Fixed**: Resolved export naming conflicts for `isProcessing` function between video and live video webhooks
+  - `isProcessing` from videos module now exported as `isVideoProcessing`
+  - `isProcessing` from live-videos module now exported as `isLiveVideoProcessing`
+  - Added explicit exports for all video and live video helper functions with unique names
+  - Similar to existing pattern used for `ReferralType` and `ReferralSource` conflicts
+- **Improved**: Better TypeScript type safety with no export ambiguities
+
+### v1.4.x
+- **Added**: Comprehensive Facebook Page webhook types
+  - Feed webhook events (posts, photos, videos, status updates)
+  - Video encoding webhook events (processing, ready, error states)
+  - Live video webhook events (live, stopped, scheduled, VOD ready)
+- **Added**: Type guards and helper functions for all Page webhook events
+- **Added**: Context extraction utilities for video events
+
+### v1.3.x
+- **Added**: Token override support for multi-tenant applications
+- **Improved**: All API methods now accept optional `RequestOptions` parameter
+
+### v1.1.0
+- **Added**: User Profile API support
+
+## License
+
+MIT
+
+## Support
+
 For issues and questions, please visit our [GitHub repository](https://github.com/warriorteam/messenger-sdk).