@xenterprises/fastify-xtwilio 1.0.0

package/API.md

@@ -0,0 +1,973 @@
+# xTwilio API Reference
+
+Complete API documentation for xTwilio - the Fastify plugin for Twilio communications (SMS, Conversations, RCS) and SendGrid email services.
+
+## Table of Contents
+
+1. [SMS Service](#sms-service)
+2. [Conversations Service](#conversations-service)
+3. [RCS Service](#rcs-service)
+4. [Email Service](#email-service)
+5. [Configuration](#configuration)
+6. [Error Handling](#error-handling)
+7. [Usage Examples](#usage-examples)
+8. [Rate Limiting](#rate-limiting)
+9. [Webhook Handling](#webhook-handling)
+
+---
+
+## SMS Service
+
+The SMS service allows you to send text messages, multimedia messages (MMS), and manage message history via Twilio.
+
+### Methods Overview
+
+| Method | Description |
+|--------|-------------|
+| `send()` | Send SMS message |
+| `sendMMS()` | Send multimedia message |
+| `schedule()` | Schedule message for future delivery |
+| `cancelScheduled()` | Cancel scheduled message |
+| `get()` | Get message details |
+| `getStatus()` | Get message delivery status |
+| `list()` | List messages with filters |
+| `delete()` | Delete message |
+| `getMedia()` | Get media from MMS |
+| `validatePhoneNumber()` | Validate phone number |
+| `sendBulk()` | Send bulk SMS |
+
+### send()
+
+Send a text message to a phone number.
+
+**Signature:**
+```typescript
+send(to: string, body: string, options?: SMSOptions): Promise<SMSResult>
+```
+
+**Parameters:**
+- `to` (string, required) - Recipient phone number in E.164 format (+1234567890)
+- `body` (string, required) - Message content (max 160 characters for single SMS)
+- `options` (object, optional) - Additional options
+
+**Options:**
+```typescript
+{
+  accountSid?: string;        // Override default account SID
+  mediaUrls?: string[];       // Media URLs for MMS (if needed)
+  attributes?: {};            // Custom attributes
+  attemptNumber?: number;     // Retry attempt number
+}
+```
+
+**Response:**
+```typescript
+{
+  sid: string;                // Twilio message SID
+  status: string;             // Message status (queued, sending, sent, failed, etc.)
+  to: string;                 // Recipient phone number
+  body: string;               // Message text
+  numSegments: number;        // Number of SMS segments
+  price?: number;             // Message price
+  priceUnit?: string;         // Currency (e.g., USD)
+  errorCode?: string;         // Error code if failed
+  errorMessage?: string;      // Error message if failed
+  dateCreated: Date;          // When message was created
+}
+```
+
+**Example:**
+```javascript
+const result = await fastify.sms.send(
+  '+1234567890',
+  'Hello! Your verification code is 123456'
+);
+
+console.log(result.sid);    // SM1234567890abcdef1234567890abcdef
+console.log(result.status); // queued
+```
+
+### sendMMS()
+
+Send a multimedia message (image, video, etc.).
+
+**Signature:**
+```typescript
+sendMMS(
+  to: string,
+  body: string,
+  mediaUrl: string,
+  options?: SMSOptions
+): Promise<SMSResult>
+```
+
+**Parameters:**
+- `to` (string, required) - Recipient phone number
+- `body` (string, required) - Message text
+- `mediaUrl` (string, required) - URL of media file (must be HTTPS)
+- `options` (object, optional) - Additional options
+
+**Supported Media Types:**
+- Images: JPEG, PNG, GIF, WEBP
+- Video: MP4, 3GP
+- Audio: WAV, MP3, OGG
+
+**Example:**
+```javascript
+const result = await fastify.sms.sendMMS(
+  '+1234567890',
+  'Check out this photo!',
+  'https://example.com/photo.jpg'
+);
+```
+
+### schedule()
+
+Schedule an SMS for future delivery.
+
+**Signature:**
+```typescript
+schedule(
+  to: string,
+  body: string,
+  sendAt: Date | string,
+  options?: SMSOptions
+): Promise<SMSResult>
+```
+
+**Parameters:**
+- `to` (string, required) - Recipient phone number
+- `body` (string, required) - Message content
+- `sendAt` (Date | string, required) - When to send (ISO 8601 format or Date object)
+- `options` (object, optional) - Additional options
+
+**Example:**
+```javascript
+// Schedule for 1 hour from now
+const futureDate = new Date(Date.now() + 3600000);
+
+const result = await fastify.sms.schedule(
+  '+1234567890',
+  'Reminder: Your appointment is tomorrow',
+  futureDate
+);
+
+// Or using ISO 8601 string
+const result = await fastify.sms.schedule(
+  '+1234567890',
+  'Reminder: Your appointment is tomorrow',
+  '2024-12-31T10:00:00Z'
+);
+```
+
+### cancelScheduled()
+
+Cancel a previously scheduled message.
+
+**Signature:**
+```typescript
+cancelScheduled(messageSid: string): Promise<{ success: boolean }>
+```
+
+**Parameters:**
+- `messageSid` (string, required) - SID of the scheduled message to cancel
+
+**Example:**
+```javascript
+const result = await fastify.sms.cancelScheduled('SMxxxxxxxxxxxxxxxxxxxxxxxxxx');
+console.log(result.success); // true
+```
+
+### getStatus()
+
+Get the delivery status of a message.
+
+**Signature:**
+```typescript
+getStatus(messageSid: string): Promise<SMSStatus>
+```
+
+**Response:**
+```typescript
+{
+  sid: string;                // Message SID
+  status: string;             // Current status
+  errorCode?: number;         // Error code if failed
+  errorMessage?: string;      // Error message if failed
+}
+```
+
+**Status Values:**
+- `queued` - Message is queued for delivery
+- `sending` - Message is being sent
+- `sent` - Message was sent successfully
+- `delivered` - Message was delivered to recipient
+- `failed` - Message delivery failed
+- `undelivered` - Message could not be delivered
+
+**Example:**
+```javascript
+const status = await fastify.sms.getStatus('SMxxxxxxxxxxxxxxxxxxxxxxxxxx');
+console.log(status.status); // "delivered"
+```
+
+### list()
+
+List SMS messages with optional filters.
+
+**Signature:**
+```typescript
+list(filters?: {
+  to?: string;
+  from?: string;
+  status?: string;
+  limit?: number;
+}): Promise<SMSResult[]>
+```
+
+**Example:**
+```javascript
+// Get last 10 messages to a phone number
+const messages = await fastify.sms.list({
+  to: '+1234567890',
+  limit: 10
+});
+
+// Get failed messages
+const failedMessages = await fastify.sms.list({
+  status: 'failed',
+  limit: 50
+});
+```
+
+### validatePhoneNumber()
+
+Validate and get information about a phone number.
+
+**Signature:**
+```typescript
+validatePhoneNumber(
+  phoneNumber: string,
+  options?: { countryCode?: string }
+): Promise<PhoneValidationResult>
+```
+
+**Response:**
+```typescript
+{
+  phoneNumber: string;        // Validated phone in E.164 format
+  isValid: boolean;           // Is the number valid?
+  countryCode?: string;       // Country code (e.g., US)
+  numberType?: string;        // mobile, fixed-line, voip, etc.
+  carrier?: string;           // Carrier name
+  error?: string;             // Error message if invalid
+}
+```
+
+**Example:**
+```javascript
+const validation = await fastify.sms.validatePhoneNumber('+14155552671');
+
+if (validation.isValid) {
+  console.log(`${validation.carrier} - ${validation.numberType}`);
+  // Output: Verizon - mobile
+}
+```
+
+### sendBulk()
+
+Send SMS to multiple recipients in a single operation.
+
+**Signature:**
+```typescript
+sendBulk(messages: BulkSMSMessage[]): Promise<SMSResult[]>
+```
+
+**Parameters:**
+```typescript
+messages: Array<{
+  to: string;                 // Recipient phone number
+  body: string;               // Message body
+  mediaUrls?: string[];       // Optional media for MMS
+  options?: SMSOptions;       // Optional per-message options
+}>
+```
+
+**Example:**
+```javascript
+const results = await fastify.sms.sendBulk([
+  {
+    to: '+1234567890',
+    body: 'Hello Alice! Your code: 111111'
+  },
+  {
+    to: '+0987654321',
+    body: 'Hello Bob! Your code: 222222'
+  },
+  {
+    to: '+1111111111',
+    body: 'Hello Charlie! Your code: 333333'
+  }
+]);
+
+results.forEach(result => {
+  console.log(`${result.to}: ${result.status}`);
+});
+```
+
+---
+
+## Conversations Service
+
+Conversations provide multi-channel messaging combining SMS, Email, WhatsApp, and more.
+
+### Methods Overview
+
+| Method | Description |
+|--------|-------------|
+| `create()` | Create new conversation |
+| `get()` | Get conversation details |
+| `update()` | Update conversation |
+| `list()` | List conversations |
+| `delete()` | Delete conversation |
+| `addParticipant()` | Add participant |
+| `listParticipants()` | List participants |
+| `removeParticipant()` | Remove participant |
+| `sendMessage()` | Send message to conversation |
+| `sendMediaMessage()` | Send media message |
+| `getMessages()` | Get conversation messages |
+| `getMessage()` | Get specific message |
+| `deleteMessage()` | Delete message |
+| `getWebhooks()` | Get webhook configuration |
+| `updateWebhooks()` | Update webhooks |
+
+### create()
+
+Create a new conversation.
+
+**Signature:**
+```typescript
+create(
+  friendlyName: string,
+  attributes?: Record<string, any>
+): Promise<ConversationInfo>
+```
+
+**Example:**
+```javascript
+const conversation = await fastify.conversations.create(
+  'Support Chat - Order #12345',
+  {
+    order_id: '12345',
+    customer_id: 'CUST_789',
+    priority: 'high'
+  }
+);
+
+console.log(conversation.sid); // IV1234567890abcdef1234567890abcdef
+```
+
+### addParticipant()
+
+Add a participant to a conversation.
+
+**Signature:**
+```typescript
+addParticipant(
+  conversationSid: string,
+  identity?: string,
+  messagingBindingAddress?: string
+): Promise<ConversationParticipant>
+```
+
+**Parameters:**
+- `conversationSid` (string, required) - Conversation ID
+- `identity` (string, optional) - Participant identity (user ID, email, etc.)
+- `messagingBindingAddress` (string, optional) - SMS number, email, WhatsApp ID
+
+**Example:**
+```javascript
+// Add customer via SMS
+const participant1 = await fastify.conversations.addParticipant(
+  'IV1234567890abcdef1234567890abcdef',
+  'customer_user_123',
+  '+1234567890'  // SMS number
+);
+
+// Add agent via email
+const participant2 = await fastify.conversations.addParticipant(
+  'IV1234567890abcdef1234567890abcdef',
+  'agent_support_456',
+  'support@example.com'  // Email
+);
+```
+
+### sendMessage()
+
+Send a message to a conversation.
+
+**Signature:**
+```typescript
+sendMessage(
+  conversationSid: string,
+  body: string,
+  author: string,
+  attributes?: Record<string, any>
+): Promise<ConversationMessage>
+```
+
+**Example:**
+```javascript
+const message = await fastify.conversations.sendMessage(
+  'IV1234567890abcdef1234567890abcdef',
+  'Thank you for contacting support. How can we help?',
+  'agent_support_456',
+  { message_type: 'greeting' }
+);
+```
+
+### getMessages()
+
+Get all messages in a conversation.
+
+**Signature:**
+```typescript
+getMessages(
+  conversationSid: string,
+  options?: { limit?: number; index?: number }
+): Promise<ConversationMessage[]>
+```
+
+**Example:**
+```javascript
+const messages = await fastify.conversations.getMessages(
+  'IV1234567890abcdef1234567890abcdef',
+  { limit: 50 }
+);
+
+messages.forEach(msg => {
+  console.log(`${msg.author}: ${msg.body}`);
+});
+```
+
+---
+
+## RCS Service
+
+RCS (Rich Communication Services) provides rich messaging capabilities with cards, buttons, and media.
+
+### Methods Overview
+
+| Method | Description |
+|--------|-------------|
+| `send()` | Send basic RCS message |
+| `sendMedia()` | Send with media |
+| `sendTemplate()` | Send from template |
+| `sendRichCard()` | Send rich card |
+| `sendCarousel()` | Send carousel of cards |
+| `sendQuickReplies()` | Send with quick replies |
+| `getStatus()` | Get message status |
+| `listTemplates()` | List templates |
+| `getTemplate()` | Get template details |
+| `deleteTemplate()` | Delete template |
+
+### sendRichCard()
+
+Send a rich card with title, description, image, and actions.
+
+**Signature:**
+```typescript
+sendRichCard(to: string, card: RCSRichCard): Promise<RCSSendResult>
+```
+
+**Card Structure:**
+```typescript
+{
+  title: string;              // Card title
+  description: string;        // Card description
+  mediaUrl?: string;          // Image/video URL
+  actions?: Array<{
+    type: 'url' | 'phone' | 'open_app' | 'create_calendar_event' | 'reply';
+    text: string;             // Button text
+    url?: string;             // For url action
+    phoneNumber?: string;     // For phone action
+    payload?: string;         // For reply action
+  }>;
+}
+```
+
+**Example:**
+```javascript
+const result = await fastify.rcs.sendRichCard(
+  '+1234567890',
+  {
+    title: 'Summer Sale',
+    description: '50% off all items this weekend only',
+    mediaUrl: 'https://example.com/sale-banner.jpg',
+    actions: [
+      {
+        type: 'url',
+        text: 'Shop Now',
+        url: 'https://example.com/sale'
+      },
+      {
+        type: 'phone',
+        text: 'Call Us',
+        phoneNumber: '+1234567890'
+      },
+      {
+        type: 'reply',
+        text: 'More Info',
+        payload: 'sale_info'
+      }
+    ]
+  }
+);
+```
+
+### sendCarousel()
+
+Send multiple rich cards in a carousel.
+
+**Signature:**
+```typescript
+sendCarousel(to: string, cards: RCSRichCard[]): Promise<RCSSendResult>
+```
+
+**Example:**
+```javascript
+const result = await fastify.rcs.sendCarousel(
+  '+1234567890',
+  [
+    {
+      title: 'Product 1',
+      description: '$29.99',
+      mediaUrl: 'https://example.com/product1.jpg',
+      actions: [{
+        type: 'url',
+        text: 'View',
+        url: 'https://example.com/product/1'
+      }]
+    },
+    {
+      title: 'Product 2',
+      description: '$39.99',
+      mediaUrl: 'https://example.com/product2.jpg',
+      actions: [{
+        type: 'url',
+        text: 'View',
+        url: 'https://example.com/product/2'
+      }]
+    }
+  ]
+);
+```
+
+### sendQuickReplies()
+
+Send a message with quick reply options.
+
+**Signature:**
+```typescript
+sendQuickReplies(
+  to: string,
+  body: string,
+  replies: RCSQuickReply[]
+): Promise<RCSSendResult>
+```
+
+**Example:**
+```javascript
+const result = await fastify.rcs.sendQuickReplies(
+  '+1234567890',
+  'How can we help you today?',
+  [
+    { text: 'Product Question', payload: 'product_q' },
+    { text: 'Order Status', payload: 'order_status' },
+    { text: 'Complaint', payload: 'complaint' }
+  ]
+);
+```
+
+---
+
+## Email Service
+
+Send emails via SendGrid with templates, attachments, and contact management.
+
+### Methods Overview
+
+| Method | Description |
+|--------|-------------|
+| `send()` | Send email |
+| `sendTemplate()` | Send from template |
+| `sendWithAttachments()` | Send with file attachments |
+| `sendBulk()` | Send bulk email |
+| `sendPersonalizedBulk()` | Send personalized bulk |
+| `validate()` | Validate email address |
+| `addContact()` | Add contact |
+| `searchContact()` | Search contact |
+| `deleteContact()` | Delete contact |
+| `createList()` | Create contact list |
+| `getLists()` | Get contact lists |
+| `deleteList()` | Delete list |
+
+### send()
+
+Send a simple email.
+
+**Signature:**
+```typescript
+send(
+  to: string,
+  subject: string,
+  html: string,
+  text?: string,
+  options?: EmailOptions
+): Promise<EmailSendResult>
+```
+
+**Example:**
+```javascript
+const result = await fastify.email.send(
+  'customer@example.com',
+  'Welcome to Our Service!',
+  `<h1>Welcome</h1>
+   <p>Thank you for signing up!</p>
+   <a href="https://example.com/get-started">Get Started</a>`,
+  'Welcome to Our Service! Thank you for signing up.'
+);
+
+console.log(result.messageId); // Message ID from SendGrid
+```
+
+### sendTemplate()
+
+Send email using a SendGrid template.
+
+**Signature:**
+```typescript
+sendTemplate(
+  to: string,
+  subject: string,
+  templateId: string,
+  dynamicData: Record<string, any>,
+  options?: EmailOptions
+): Promise<EmailSendResult>
+```
+
+**Example:**
+```javascript
+const result = await fastify.email.sendTemplate(
+  'user@example.com',
+  'Welcome Email',
+  'd-1234567890abcdef1234567890abcdef',  // Template ID from SendGrid
+  {
+    first_name: 'John',
+    activation_link: 'https://example.com/activate/abc123'
+  }
+);
+```
+
+### sendWithAttachments()
+
+Send email with file attachments.
+
+**Signature:**
+```typescript
+sendWithAttachments(
+  to: string,
+  subject: string,
+  html: string,
+  attachments: Array<{
+    content: string;       // Base64 encoded
+    filename: string;
+    type: string;         // MIME type
+  }>,
+  options?: EmailOptions
+): Promise<EmailSendResult>
+```
+
+**Example:**
+```javascript
+const fs = require('fs');
+
+const pdfContent = fs.readFileSync('invoice.pdf').toString('base64');
+
+const result = await fastify.email.sendWithAttachments(
+  'customer@example.com',
+  'Your Invoice',
+  '<p>Your invoice is attached.</p>',
+  [
+    {
+      content: pdfContent,
+      filename: 'invoice_12345.pdf',
+      type: 'application/pdf'
+    }
+  ]
+);
+```
+
+### validate()
+
+Check if an email address is valid and deliverable.
+
+**Signature:**
+```typescript
+validate(email: string): Promise<{
+  isValid: boolean;
+  suggestion?: string;
+  error?: string;
+}>
+```
+
+**Example:**
+```javascript
+const validation = await fastify.email.validate('user@example.com');
+
+if (validation.isValid) {
+  console.log('Email is valid and deliverable');
+} else {
+  console.log('Validation error:', validation.error);
+  if (validation.suggestion) {
+    console.log('Did you mean:', validation.suggestion);
+  }
+}
+```
+
+### addContact()
+
+Add a contact to SendGrid.
+
+**Signature:**
+```typescript
+addContact(
+  email: string,
+  data: Record<string, string>,
+  listIds?: string[]
+): Promise<EmailContact>
+```
+
+**Example:**
+```javascript
+const contact = await fastify.email.addContact(
+  'john@example.com',
+  {
+    firstName: 'John',
+    lastName: 'Doe',
+    phone: '+1234567890',
+    company: 'Acme Inc'
+  },
+  ['list_id_123']  // Add to lists
+);
+```
+
+### sendBulk()
+
+Send email to multiple recipients.
+
+**Signature:**
+```typescript
+sendBulk(
+  to: string[],
+  subject: string,
+  html: string,
+  options?: EmailOptions
+): Promise<EmailSendResult[]>
+```
+
+**Example:**
+```javascript
+const recipients = [
+  'user1@example.com',
+  'user2@example.com',
+  'user3@example.com'
+];
+
+const results = await fastify.email.sendBulk(
+  recipients,
+  'Newsletter - December',
+  '<h1>December Newsletter</h1><p>...'
+);
+
+results.forEach((result, idx) => {
+  console.log(`${recipients[idx]}: ${result.status}`);
+});
+```
+
+---
+
+## Configuration
+
+### Plugin Registration
+
+```javascript
+import Fastify from 'fastify';
+import xTwilio from '@xenterprises/fastify-xtwilio';
+
+const fastify = Fastify();
+
+await fastify.register(xTwilio, {
+  twilio: {
+    accountSid: process.env.TWILIO_ACCOUNT_SID,
+    authToken: process.env.TWILIO_AUTH_TOKEN,
+    phoneNumber: process.env.TWILIO_PHONE_NUMBER,
+    messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
+    active: true,  // Enable Twilio
+  },
+  sendgrid: {
+    apiKey: process.env.SENDGRID_API_KEY,
+    fromEmail: process.env.SENDGRID_FROM_EMAIL,
+    active: true,  // Enable SendGrid
+  },
+  logRequests: process.env.NODE_ENV === 'development',
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+---
+
+## Error Handling
+
+All methods throw errors with descriptive messages. Use try-catch blocks:
+
+```javascript
+try {
+  await fastify.sms.send('+1234567890', 'Hello');
+} catch (error) {
+  console.error('SMS failed:', error.message);
+  // Handle specific error
+}
+```
+
+---
+
+## Usage Examples
+
+### Complete SMS Flow
+
+```javascript
+// 1. Validate phone number
+const validation = await fastify.sms.validatePhoneNumber('+1234567890');
+if (!validation.isValid) {
+  throw new Error('Invalid phone number');
+}
+
+// 2. Send SMS
+const result = await fastify.sms.send(
+  '+1234567890',
+  'Your verification code is 123456'
+);
+
+// 3. Check status
+const status = await fastify.sms.getStatus(result.sid);
+console.log('Status:', status.status);
+
+// 4. List recent messages
+const messages = await fastify.sms.list({ limit: 10 });
+```
+
+### Customer Conversation
+
+```javascript
+// 1. Create conversation
+const conversation = await fastify.conversations.create('Customer Support');
+
+// 2. Add customer (SMS)
+await fastify.conversations.addParticipant(
+  conversation.sid,
+  'customer_123',
+  '+1234567890'
+);
+
+// 3. Add agent (Email)
+await fastify.conversations.addParticipant(
+  conversation.sid,
+  'agent_456',
+  'support@company.com'
+);
+
+// 4. Send greeting
+await fastify.conversations.sendMessage(
+  conversation.sid,
+  'Hello! How can we help you?',
+  'agent_456'
+);
+
+// 5. Get conversation history
+const messages = await fastify.conversations.getMessages(
+  conversation.sid
+);
+```
+
+### Email Campaign with Personaliz ation
+
+```javascript
+const customers = [
+  { email: 'alice@example.com', name: 'Alice', orderAmount: '$100' },
+  { email: 'bob@example.com', name: 'Bob', orderAmount: '$250' }
+];
+
+const results = await fastify.email.sendPersonalizedBulk(
+  customers.map(customer => ({
+    to: customer.email,
+    subject: `Thank you for your ${customer.orderAmount} order, ${customer.name}!`,
+    html: `<p>Hi ${customer.name},</p><p>Thank you for ordering ${customer.orderAmount}!</p>`,
+    personalData: {
+      name: customer.name,
+      amount: customer.orderAmount
+    }
+  }))
+);
+```
+
+---
+
+## Rate Limiting
+
+Implement rate limiting to prevent abuse:
+
+```bash
+# Environment variables
+SMS_RATE_LIMIT_PER_MINUTE=10
+EMAIL_RATE_LIMIT_PER_MINUTE=5
+```
+
+---
+
+## Webhook Handling
+
+Configure webhooks in your Twilio account to receive delivery status updates, inbound messages, and conversation events.
+
+**Webhook Signature Validation:**
+```javascript
+import crypto from 'crypto';
+
+fastify.post('/webhooks/twilio', async (request, reply) => {
+  const signature = request.headers['x-twilio-signature'];
+  const body = request.rawBody || JSON.stringify(request.body);
+
+  const expectedSignature = crypto
+    .createHmac('sha1', process.env.TWILIO_AUTH_TOKEN)
+    .update(`${process.env.WEBHOOK_URL}${body}`)
+    .digest('base64');
+
+  if (signature !== expectedSignature) {
+    return reply.code(403).send({ error: 'Unauthorized' });
+  }
+
+  // Process webhook
+  console.log('Webhook received:', request.body);
+  reply.code(200).send({ status: 'received' });
+});
+```
+
+---
+
+## Related Documentation
+
+- [Twilio API Docs](https://www.twilio.com/docs/api)
+- [SendGrid Email API](https://docs.sendgrid.com/api-reference/mail-send)
+- [SECURITY.md](./SECURITY.md) - Security best practices
+- [CHANGELOG.md](./CHANGELOG.md) - Version history and changes