@warriorteam/messenger-sdk 1.4.0 → 1.4.1

package/README.md

@@ -5,11 +5,14 @@ A modern TypeScript SDK for the Facebook Messenger Platform API, designed with s
 ## Features
 
 - 🚀 **Zero runtime dependencies** - Built with native fetch
-- 📝 **Full TypeScript support** - Complete type definitions
+- 📝 **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
+- 🔐 **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
 
@@ -47,7 +50,7 @@ console.log('Message sent:', result.message_id);
 
 ```typescript
 const messenger = new Messenger({
-  accessToken: string;    // Required: Your page access token
+  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)
@@ -55,6 +58,35 @@ const messenger = new Messenger({
 });
 ```
 
+### 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
@@ -240,6 +272,151 @@ await messenger.send.message({
 
 **Note**: Profile API requires "Advanced User Profile Access" feature and user interaction to grant permissions.
 
+## 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,
+  WebhookEventType,
+  GenericWebhookPayload 
+} 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
+const eventTypes = getWebhookPayloadEventTypes(payload);
+console.log('Received event types:', eventTypes);
+```
+
+### 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
+
+- `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
+
 ## Error Handling
 
 The SDK provides specific error types for different scenarios:
@@ -277,6 +454,9 @@ Check the `examples/` directory for complete usage examples:
 - `send-template.ts` - Template messages
 - `user-profile.ts` - Profile API usage
 - `moderation.ts` - User moderation
+- `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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warriorteam/messenger-sdk",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "TypeScript SDK for Facebook Messenger Platform API",
   "type": "module",
   "main": "./dist/index.cjs",