@xenterprises/fastify-xtwilio 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+All notable changes to xTwilio will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+
+- Webhook event retry logic with exponential backoff
+- Batch API operations for bulk SMS/email
+- Message queue integration (Bull, RabbitMQ)
+- Advanced analytics and reporting dashboard
+- Multi-tenant support for messaging services
+- Real-time delivery tracking with webhooks
+- SMS campaign management tools
+- Email list segmentation features
+- A/B testing for email campaigns
+- WhatsApp Business API integration
+- Facebook Messenger integration
+- Message template versioning and rollback
+
+---
+
+## [1.0.0] - 2024-12-29
+
+### Added
+
+#### SMS Service
+- `send()` - Send SMS messages
+- `sendMMS()` - Send multimedia messages
+- `schedule()` - Schedule messages for future delivery
+- `cancelScheduled()` - Cancel scheduled messages
+- `get()` - Retrieve message details
+- `getStatus()` - Get message delivery status
+- `list()` - List messages with filters
+- `delete()` - Delete messages
+- `getMedia()` - Get MMS media URLs
+- `validatePhoneNumber()` - Validate and lookup phone numbers
+- `sendBulk()` - Send bulk SMS to multiple recipients
+
+#### Conversations Service
+- `create()` - Create new conversations
+- `get()` - Retrieve conversation details
+- `update()` - Update conversation properties
+- `list()` - List conversations with filters
+- `delete()` - Delete conversations
+- `addParticipant()` - Add participants to conversations
+- `listParticipants()` - List conversation participants
+- `removeParticipant()` - Remove participants
+- `sendMessage()` - Send messages to conversations
+- `sendMediaMessage()` - Send media in conversations
+- `getMessages()` - Retrieve conversation messages
+- `getMessage()` - Get specific message
+- `deleteMessage()` - Delete conversation messages
+- `getWebhooks()` - Get webhook configuration
+- `updateWebhooks()` - Update webhook settings
+
+#### RCS Service
+- `send()` - Send RCS messages
+- `sendMedia()` - Send RCS with media
+- `sendTemplate()` - Send from templates
+- `sendRichCard()` - Send rich card messages
+- `sendCarousel()` - Send carousel of cards
+- `sendQuickReplies()` - Send messages with quick reply options
+- `getStatus()` - Get message status
+- `listTemplates()` - List content templates
+- `getTemplate()` - Get template details
+- `deleteTemplate()` - Delete templates
+
+#### Email Service
+- `send()` - Send emails
+- `sendTemplate()` - Send from SendGrid templates
+- `sendWithAttachments()` - Send with file attachments
+- `sendBulk()` - Send bulk emails
+- `sendPersonalizedBulk()` - Send personalized bulk emails
+- `validate()` - Validate email addresses
+- `addContact()` - Add contacts to SendGrid
+- `searchContact()` - Search contacts by email
+- `deleteContact()` - Delete contacts
+- `createList()` - Create contact lists
+- `getLists()` - List contact lists
+- `deleteList()` - Delete contact lists
+
+#### Plugin Features
+- Fastify plugin integration with decorator pattern
+- TypeScript definitions for all services
+- Environment-based configuration
+- Service enablement toggles (Twilio, SendGrid)
+- Request/response logging (opt-in)
+- Comprehensive error handling
+- Rate limiting ready (via Fastify plugins)
+- Webhook support for Twilio events
+
+### Documentation
+- Comprehensive README with usage examples
+- Detailed API reference for all services
+- TypeScript type definitions (index.d.ts)
+- Security guidelines and best practices
+- Environment configuration documentation
+- QUICK_START guide for new users
+
+### Testing
+- Unit tests for all services
+- Integration test examples
+- Mock implementations for testing
+- Test fixtures and helpers
+
+### Configuration
+- `.env.example` with comprehensive options
+- Support for multiple environments
+- Flexible credential management
+- Feature flags for services
+
+### Infrastructure
+- Docker support (Dockerfile, docker-compose.yml)
+- CI/CD pipeline ready (.gitlab-ci.yml)
+- Health check endpoints
+- Logging and monitoring hooks
+
+---
+
+## Versioning
+
+- **Major**: Breaking changes to API
+- **Minor**: New features (backwards compatible)
+- **Patch**: Bug fixes and improvements
+
+## Support
+
+- **LTS**: Versions will be supported for 12 months from release
+- **Current**: Latest version receives active development
+- **Maintenance**: Critical security fixes only
+
+## Migration Guides
+
+Future major versions will include migration guides in this changelog.
+
+---
+
+## Notes for Developers
+
+### Using RCS Service
+
+The RCS service requires:
+- Twilio Messaging Service SID
+- Messaging Service configured for RCS in Twilio dashboard
+- Supported recipient countries (check Twilio RCS availability)
+
+### Using Conversations Service
+
+Conversations provide multi-channel messaging (SMS, Email, WhatsApp, etc.).
+
+### Using SendGrid Templates
+
+Create templates in SendGrid dashboard and reference by ID:
+- Get template IDs from SendGrid dashboard
+- Store IDs in environment variables for easy management
+
+### Webhook Validation
+
+Always validate webhook signatures in production:
+- Use X-Twilio-Signature header
+- Implement HMAC-SHA1 validation
+- Log failed validations for security monitoring
+
+---
+
+## Related Projects
+
+- [xStorage](https://github.com/xenterprises/fastify-xstorage) - File storage integration
+- [xStripe](https://github.com/xenterprises/fastify-xstripe) - Payment processing
+- [xPDF](https://github.com/xenterprises/fastify-xpdf) - PDF generation and manipulation
+
+---
+
+## Security Updates
+
+Security vulnerabilities should be reported to security@xenterprises.com
+
+## License
+
+ISC
+
+---
+
+**Last Updated**: 2024-12-29

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024 Tim Mushen
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# xTwilio
+
+Fastify v5 plugin for Twilio communications (SMS, Conversations, RCS) and SendGrid email services.
+
+## Requirements
+
+- **Fastify v5.0.0+**
+- **Node.js v20+**
+
+## Installation
+
+```bash
+npm install @xenterprises/fastify-xtwilio fastify@5
+```
+
+## Usage
+
+```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, // For RCS
+  },
+  sendgrid: {
+    apiKey: process.env.SENDGRID_API_KEY,
+    fromEmail: process.env.SENDGRID_FROM_EMAIL,
+  },
+});
+```
+
+## Services
+
+### SMS Service (`fastify.sms`)
+
+```javascript
+// Send SMS
+await fastify.sms.send('+1234567890', 'Hello World');
+
+// Send MMS
+await fastify.sms.sendMMS('+1234567890', 'Check this out!', 'https://example.com/image.jpg');
+
+// Schedule SMS
+await fastify.sms.schedule('+1234567890', 'Reminder', new Date('2024-12-31T10:00:00Z'));
+
+// Send bulk SMS
+await fastify.sms.sendBulk([
+  { to: '+1234567890', body: 'Message 1' },
+  { to: '+0987654321', body: 'Message 2' },
+]);
+
+// Get message status
+await fastify.sms.getStatus('SMXXXXXXXX');
+
+// Validate phone number
+await fastify.sms.validatePhoneNumber('+1234567890');
+```
+
+### Conversations Service (`fastify.conversations`)
+
+```javascript
+// Create conversation
+const conversation = await fastify.conversations.create('Support Chat');
+
+// Add participants
+await fastify.conversations.addParticipant(conversation.sid, 'user@example.com');
+await fastify.conversations.addParticipant(conversation.sid, null, '+1234567890');
+
+// Send message
+await fastify.conversations.sendMessage(conversation.sid, 'Hello!', 'user@example.com');
+
+// Get messages
+const messages = await fastify.conversations.getMessages(conversation.sid);
+
+// List participants
+const participants = await fastify.conversations.listParticipants(conversation.sid);
+```
+
+### RCS Service (`fastify.rcs`)
+
+```javascript
+// Send basic RCS message
+await fastify.rcs.send('+1234567890', 'Hello from RCS!');
+
+// Send rich card
+await fastify.rcs.sendRichCard('+1234567890', {
+  title: 'Summer Sale',
+  description: '50% off all items',
+  mediaUrl: 'https://example.com/banner.jpg',
+  actions: [
+    { type: 'url', text: 'Shop Now', url: 'https://example.com/shop' },
+  ],
+});
+
+// Send carousel
+await fastify.rcs.sendCarousel('+1234567890', [
+  { title: 'Product 1', description: 'Description 1', mediaUrl: 'url1.jpg' },
+  { title: 'Product 2', description: 'Description 2', mediaUrl: 'url2.jpg' },
+]);
+
+// Send with quick replies
+await fastify.rcs.sendQuickReplies('+1234567890', 'How can we help?', [
+  { text: 'Support', payload: 'support' },
+  { text: 'Sales', payload: 'sales' },
+]);
+
+// Use content template
+await fastify.rcs.sendTemplate('+1234567890', 'HXXXXXXXC', { name: 'John' });
+```
+
+### Email Service (`fastify.email`)
+
+```javascript
+// Send email
+await fastify.email.send(
+  'user@example.com',
+  'Welcome!',
+  '<h1>Welcome to our service</h1>',
+  'Welcome to our service'
+);
+
+// Send with template
+await fastify.email.sendTemplate(
+  'user@example.com',
+  'Welcome Email',
+  'd-1234567890abcdef',
+  { firstName: 'John', code: '123456' }
+);
+
+// Send with attachments
+await fastify.email.sendWithAttachments(
+  'user@example.com',
+  'Invoice',
+  '<p>Your invoice is attached</p>',
+  [
+    {
+      content: 'base64EncodedContent',
+      filename: 'invoice.pdf',
+      type: 'application/pdf',
+    },
+  ]
+);
+
+// Send bulk emails
+await fastify.email.sendBulk(
+  ['user1@example.com', 'user2@example.com'],
+  'Newsletter',
+  '<h1>This months updates</h1>'
+);
+
+// Validate email
+const validation = await fastify.email.validate('test@example.com');
+
+// Contact management
+await fastify.email.addContact('user@example.com', {
+  firstName: 'John',
+  lastName: 'Doe',
+});
+
+await fastify.email.searchContact('user@example.com');
+
+// List management
+const list = await fastify.email.createList('Newsletter Subscribers');
+const lists = await fastify.email.getLists();
+```
+
+## Configuration Options
+
+### Twilio Options
+
+```javascript
+{
+  twilio: {
+    accountSid: 'ACXXXXXXXX',           // Required
+    authToken: 'your_auth_token',       // Required
+    phoneNumber: '+1234567890',         // Required for SMS (or use messagingServiceSid)
+    messagingServiceSid: 'MGXXXXXXXX',  // Required for RCS, optional for SMS
+    active: true,                       // Optional, default true
+  }
+}
+```
+
+### SendGrid Options
+
+```javascript
+{
+  sendgrid: {
+    apiKey: 'SG.XXXXXXXX',              // Required
+    fromEmail: 'noreply@example.com',   // Required
+    active: true,                       // Optional, default true
+  }
+}
+```
+
+## API Reference
+
+### SMS Methods
+- `send(to, body, options)` - Send SMS
+- `sendMMS(to, body, mediaUrl, options)` - Send MMS
+- `schedule(to, body, sendAt)` - Schedule message
+- `cancelScheduled(messageSid)` - Cancel scheduled message
+- `get(messageSid)` - Get message details
+- `getStatus(messageSid)` - Get message status
+- `list(filters)` - List messages
+- `delete(messageSid)` - Delete message
+- `getMedia(messageSid)` - Get media from MMS
+- `validatePhoneNumber(phoneNumber, options)` - Validate phone
+- `sendBulk(messages)` - Send bulk SMS
+
+### Conversations Methods
+- `create(friendlyName, attributes)` - Create conversation
+- `get(conversationSid)` - Get conversation
+- `update(conversationSid, updates)` - Update conversation
+- `list(filters)` - List conversations
+- `delete(conversationSid)` - Delete conversation
+- `addParticipant(conversationSid, identity, messagingBindingAddress)` - Add participant
+- `listParticipants(conversationSid)` - List participants
+- `removeParticipant(conversationSid, participantSid)` - Remove participant
+- `sendMessage(conversationSid, body, author, attributes)` - Send message
+- `sendMediaMessage(conversationSid, mediaUrl, body, author)` - Send media
+- `getMessages(conversationSid, options)` - Get messages
+- `getMessage(conversationSid, messageSid)` - Get specific message
+- `deleteMessage(conversationSid, messageSid)` - Delete message
+- `getWebhooks(conversationSid)` - Get webhooks
+- `updateWebhooks(conversationSid, webhookConfig)` - Update webhooks
+
+### RCS Methods
+- `send(to, body, options)` - Send basic RCS
+- `sendMedia(to, body, mediaUrl)` - Send with media
+- `sendTemplate(to, contentSid, contentVariables)` - Send template
+- `sendRichCard(to, card)` - Send rich card
+- `sendCarousel(to, cards)` - Send carousel
+- `sendQuickReplies(to, body, replies)` - Send quick replies
+- `getStatus(messageSid)` - Get status
+- `listTemplates(options)` - List templates
+- `getTemplate(contentSid)` - Get template
+- `deleteTemplate(contentSid)` - Delete template
+
+### Email Methods
+- `send(to, subject, html, text, options)` - Send email
+- `sendTemplate(to, subject, templateId, dynamicData, options)` - Send template
+- `sendWithAttachments(to, subject, html, attachments)` - Send with attachments
+- `sendBulk(to, subject, html)` - Send bulk
+- `sendPersonalizedBulk(messages)` - Send personalized bulk
+- `validate(email)` - Validate email
+- `addContact(email, data, listIds)` - Add contact
+- `searchContact(email)` - Search contact
+- `deleteContact(contactId)` - Delete contact
+- `createList(name)` - Create list
+- `getLists()` - Get lists
+- `deleteList(listId)` - Delete list
+
+## License
+
+ISC