@xenterprises/fastify-xtwilio 1.0.0

package/.dockerignore

@@ -0,0 +1,63 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Node
+node_modules
+npm-debug.log
+npm-error.log
+yarn-error.log
+package-lock.json
+yarn.lock
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+.env
+.env.local
+.env.*.local
+
+# Testing
+test
+coverage
+.nyc_output
+.mocha_opts
+
+# CI/CD
+.github
+.gitlab-ci.yml
+.circleci
+.travis.yml
+
+# Build outputs
+dist
+build
+.next
+out
+
+# Documentation
+docs
+README.md
+CHANGELOG.md
+SECURITY.md
+QUICK_START.md
+CONTRIBUTING.md
+
+# Development
+Dockerfile
+docker-compose.yml
+.dockerignore
+.eslintrc
+.prettierrc
+tsconfig.json
+vitest.config.js
+
+# Other
+.env.example
+LICENSE
+NOTES.md

package/.env.example

@@ -0,0 +1,257 @@
+# ============================================================================
+# SERVER CONFIGURATION
+# ============================================================================
+
+# Server port to listen on
+PORT=3000
+
+# Node environment: development, staging, production
+NODE_ENV=development
+
+# Enable detailed logging for debugging
+DEBUG=false
+
+# ============================================================================
+# TWILIO SMS CONFIGURATION
+# ============================================================================
+
+# Twilio Account SID (Find at: https://console.twilio.com/)
+# This is your unique Twilio account identifier
+TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# Twilio Auth Token (Find at: https://console.twilio.com/)
+# Keep this secret! Use environment variables in production
+TWILIO_AUTH_TOKEN=your_auth_token_here
+
+# Twilio Phone Number for SMS (Find at: https://console.twilio.com/phone-numbers/incoming)
+# Format: +1234567890 or +[country_code][number]
+# This is the "FROM" number for SMS messages
+TWILIO_PHONE_NUMBER=+1234567890
+
+# ============================================================================
+# TWILIO RCS (RICH COMMUNICATION SERVICES) CONFIGURATION
+# ============================================================================
+
+# Twilio Messaging Service SID (Find at: https://console.twilio.com/messaging/services)
+# Required for RCS and advanced SMS features
+# A Messaging Service manages multiple phone numbers and templates
+TWILIO_MESSAGING_SERVICE_SID=MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# Messaging Service Fallback Strategy when primary fails
+# Options: none, sms, email
+TWILIO_MESSAGING_FALLBACK_STRATEGY=sms
+
+# Default RCS template region for content delivery
+# Options: us, eu, apac
+TWILIO_RCS_REGION=us
+
+# ============================================================================
+# TWILIO CONVERSATIONS CONFIGURATION
+# ============================================================================
+
+# Enable Conversations service (customer chat, multi-channel messaging)
+TWILIO_CONVERSATIONS_ENABLED=true
+
+# Webhook URL for conversation events (optional)
+# Twilio will POST conversation events to this URL
+TWILIO_CONVERSATIONS_WEBHOOK_URL=https://your-domain.com/webhooks/conversations
+
+# Webhook authentication secret for validating Twilio requests
+TWILIO_CONVERSATIONS_WEBHOOK_SECRET=your_webhook_secret_here
+
+# Default conversation attributes in JSON format
+TWILIO_CONVERSATIONS_DEFAULT_ATTRIBUTES={}
+
+# ============================================================================
+# SENDGRID EMAIL CONFIGURATION
+# ============================================================================
+
+# SendGrid API Key (Get from: https://app.sendgrid.com/settings/api_keys)
+# This is your authentication token for SendGrid API
+# Treat this as sensitive as a password - never commit to version control
+SENDGRID_API_KEY=SG.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# Sender email address for all outgoing emails
+# This email must be verified in your SendGrid account
+SENDGRID_FROM_EMAIL=noreply@example.com
+
+# Sender name to display in "From" field
+# Example: "Support Team" <noreply@example.com>
+SENDGRID_FROM_NAME=Your Application
+
+# Default reply-to email address (optional)
+# If not provided, recipients reply to SENDGRID_FROM_EMAIL
+SENDGRID_REPLY_TO_EMAIL=support@example.com
+
+# ============================================================================
+# SENDGRID ADVANCED CONFIGURATION
+# ============================================================================
+
+# Enable SendGrid contact management
+# If true, emails sent will also add/update contacts in SendGrid
+SENDGRID_MANAGE_CONTACTS=false
+
+# SendGrid list ID for newsletter subscriptions (optional)
+# Contacts can be automatically added to this list
+SENDGRID_NEWSLETTER_LIST_ID=
+
+# Enable email validation before sending
+# Checks email format and deliverability (uses SendGrid validation API)
+SENDGRID_VALIDATE_EMAILS=true
+
+# Enable click and open tracking
+SENDGRID_TRACK_CLICKS=true
+SENDGRID_TRACK_OPENS=true
+
+# Email templates for transactional messages
+# SendGrid Template IDs (create templates in SendGrid dashboard)
+SENDGRID_WELCOME_TEMPLATE_ID=d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+SENDGRID_PASSWORD_RESET_TEMPLATE_ID=d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+SENDGRID_RECEIPT_TEMPLATE_ID=d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+SENDGRID_NOTIFICATION_TEMPLATE_ID=d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# ============================================================================
+# FEATURE FLAGS & SERVICE TOGGLES
+# ============================================================================
+
+# Enable/disable SMS service
+# If false, SMS methods will throw "Service disabled" error
+TWILIO_ENABLED=true
+
+# Enable/disable SendGrid service
+# If false, email methods will throw "Service disabled" error
+SENDGRID_ENABLED=true
+
+# ============================================================================
+# RATE LIMITING & THROTTLING
+# ============================================================================
+
+# Maximum SMS messages per minute per phone number
+# Prevents accidental/malicious spam
+SMS_RATE_LIMIT_PER_MINUTE=10
+
+# Maximum emails per minute per recipient
+# Respects SendGrid's reputation limits
+EMAIL_RATE_LIMIT_PER_MINUTE=5
+
+# ============================================================================
+# RETRY & ERROR HANDLING
+# ============================================================================
+
+# Maximum retries for failed SMS (Twilio will handle automatically)
+SMS_MAX_RETRIES=3
+
+# Maximum retries for failed emails
+EMAIL_MAX_RETRIES=2
+
+# Delay in milliseconds before first retry
+RETRY_INITIAL_DELAY=1000
+
+# Maximum delay in milliseconds between retries (exponential backoff)
+RETRY_MAX_DELAY=30000
+
+# ============================================================================
+# LOGGING & MONITORING
+# ============================================================================
+
+# Log level for xTwilio operations
+# Options: error, warn, info, debug, trace
+LOG_LEVEL=info
+
+# Enable detailed request/response logging for Twilio API calls
+TWILIO_LOG_REQUESTS=false
+
+# Enable detailed request/response logging for SendGrid API calls
+SENDGRID_LOG_REQUESTS=false
+
+# ============================================================================
+# SECURITY & VALIDATION
+# ============================================================================
+
+# Validate phone numbers before sending SMS
+# Uses Twilio Lookup API (may incur additional charges)
+VALIDATE_PHONE_NUMBERS=true
+
+# Country code for default phone number validation
+# Used if no country code provided in phone number
+DEFAULT_COUNTRY_CODE=US
+
+# Maximum message length (SMS standard is 160 characters)
+# Longer messages are split into multiple SMS (multi-part)
+MAX_MESSAGE_LENGTH=160
+
+# Allowed domains for media URLs in RCS messages
+# Comma-separated list: https://domain1.com,https://domain2.com
+# If empty, all HTTPS domains allowed
+ALLOWED_MEDIA_DOMAINS=
+
+# ============================================================================
+# WEBHOOK CONFIGURATION
+# ============================================================================
+
+# Webhook path for Twilio to send status updates
+# Twilio will POST message status updates here
+TWILIO_WEBHOOK_PATH=/webhooks/twilio
+
+# Webhook authentication - require X-Twilio-Signature validation
+VALIDATE_TWILIO_WEBHOOKS=true
+
+# Webhook timeout in milliseconds
+WEBHOOK_TIMEOUT=5000
+
+# ============================================================================
+# DATABASE/PERSISTENCE (Optional)
+# ============================================================================
+
+# If using a database to store message history, conversation state, etc.
+DATABASE_URL=
+
+# Redis connection string for caching, rate limiting, message queue
+# Format: redis://[username:password]@localhost:6379/0
+REDIS_URL=
+
+# ============================================================================
+# DEVELOPMENT & TESTING
+# ============================================================================
+
+# Use Twilio test credentials (for testing without sending real SMS)
+# Only works with Twilio's test phone numbers
+USE_TWILIO_TEST_CREDENTIALS=false
+
+# Twilio test account SID (if using test credentials)
+TWILIO_TEST_ACCOUNT_SID=
+
+# Use mock SendGrid for development (no real emails sent)
+USE_SENDGRID_MOCK=false
+
+# Directory for saving test emails (when using mock SendGrid)
+SENDGRID_MOCK_STORAGE_PATH=./test-emails
+
+# ============================================================================
+# NOTES
+# ============================================================================
+
+# 🔐 SECURITY BEST PRACTICES:
+# 1. Never commit .env file to version control (only commit .env.example)
+# 2. Use strong, unique API keys and tokens
+# 3. Rotate credentials regularly
+# 4. Use different keys for development and production
+# 5. Store sensitive keys in secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)
+#
+# 🚀 DEPLOYMENT:
+# 1. Use environment variables from your hosting provider (Vercel, Railway, etc.)
+# 2. Never log or expose API keys in error messages
+# 3. Enable HTTPS for all webhook endpoints
+# 4. Validate incoming webhooks using Twilio's signature validation
+#
+# 📞 TWILIO RESOURCES:
+# - Console: https://console.twilio.com/
+# - API Docs: https://www.twilio.com/docs/api
+# - Pricing: https://www.twilio.com/pricing
+# - Support: https://www.twilio.com/support/contact
+#
+# 📧 SENDGRID RESOURCES:
+# - Dashboard: https://app.sendgrid.com/
+# - API Docs: https://docs.sendgrid.com/api-reference/
+# - Pricing: https://sendgrid.com/pricing/
+# - Support: https://support.sendgrid.com/