@xenterprises/fastify-xtwilio 1.0.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@xenterprises/fastify-xtwilio",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for Twilio communications (SMS, Conversations, RCS) and SendGrid email.",
+  "main": "src/xTwilio.js",
+  "exports": {
+    ".": "./src/xTwilio.js"
+  },
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/xTwilio.test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "keywords": [
+    "fastify",
+    "twilio",
+    "sms",
+    "rcs",
+    "conversations",
+    "sendgrid",
+    "email",
+    "communications",
+    "messaging",
+    "plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xenterprises/fastify-xtwilio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xenterprises/fastify-xtwilio/issues"
+  },
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "fastify": "^5.1.0",
+    "fastify-plugin": "^5.0.0",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "@sendgrid/client": "^8.1.3",
+    "@sendgrid/mail": "^8.1.3",
+    "fastify-plugin": "^5.0.0",
+    "twilio": "^5.3.2"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}

package/server/app.js

@@ -0,0 +1,88 @@
+// server/app.js - Example Fastify server using xTwilio
+import Fastify from 'fastify';
+import xTwilio from '../src/xTwilio.js';
+
+const fastify = Fastify({
+  logger: true,
+});
+
+// Register xTwilio plugin
+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,
+  },
+  sendgrid: {
+    apiKey: process.env.SENDGRID_API_KEY,
+    fromEmail: process.env.SENDGRID_FROM_EMAIL,
+  },
+});
+
+// Example SMS route
+fastify.post('/sms/send', async (request, reply) => {
+  const { to, body } = request.body;
+
+  try {
+    const result = await fastify.sms.send(to, body);
+    return { success: true, messageSid: result.sid };
+  } catch (error) {
+    reply.code(500);
+    return { success: false, error: error.message };
+  }
+});
+
+// Example Conversation route
+fastify.post('/conversations/create', async (request, reply) => {
+  const { friendlyName } = request.body;
+
+  try {
+    const conversation = await fastify.conversations.create(friendlyName);
+    return { success: true, conversationSid: conversation.sid };
+  } catch (error) {
+    reply.code(500);
+    return { success: false, error: error.message };
+  }
+});
+
+// Example RCS route
+fastify.post('/rcs/send-card', async (request, reply) => {
+  const { to, card } = request.body;
+
+  try {
+    const result = await fastify.rcs.sendRichCard(to, card);
+    return { success: true, messageSid: result.sid };
+  } catch (error) {
+    reply.code(500);
+    return { success: false, error: error.message };
+  }
+});
+
+// Example Email route
+fastify.post('/email/send', async (request, reply) => {
+  const { to, subject, html } = request.body;
+
+  try {
+    const result = await fastify.email.send(to, subject, html);
+    return { success: true, messageId: result.messageId };
+  } catch (error) {
+    reply.code(500);
+    return { success: false, error: error.message };
+  }
+});
+
+// Health check route
+fastify.get('/health', async () => {
+  return {
+    status: 'ok',
+    services: {
+      sms: !!fastify.sms,
+      conversations: !!fastify.conversations,
+      rcs: !!fastify.rcs,
+      email: !!fastify.email,
+    }
+  };
+});
+
+export default fastify;

package/src/services/conversations.js

@@ -0,0 +1,328 @@
+// src/services/conversations.js
+import Twilio from "twilio";
+
+export async function setupConversations(fastify, options) {
+  if (options.active === false) return;
+
+  // Validate required credentials
+  if (!options.accountSid || !options.authToken) {
+    throw new Error("Twilio accountSid and authToken must be provided for Conversations.");
+  }
+
+  // Initialize Twilio client
+  const twilioClient = Twilio(options.accountSid, options.authToken);
+
+  fastify.decorate("conversations", {
+    /**
+     * Create a new conversation
+     * @param {string} friendlyName - Human-readable name
+     * @param {object} attributes - Optional custom attributes (JSON object)
+     * @returns {Promise<object>} Conversation object
+     */
+    create: async (friendlyName, attributes = {}) => {
+      try {
+        const conversation = await twilioClient.conversations.v1.conversations.create({
+          friendlyName,
+          attributes: JSON.stringify(attributes),
+        });
+        return conversation;
+      } catch (error) {
+        fastify.log.error("Conversations create failed:", error);
+        throw new Error("Failed to create conversation.");
+      }
+    },
+
+    /**
+     * Get a conversation by SID
+     * @param {string} conversationSid - Conversation SID
+     * @returns {Promise<object>} Conversation object
+     */
+    get: async (conversationSid) => {
+      try {
+        const conversation = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .fetch();
+        return conversation;
+      } catch (error) {
+        fastify.log.error("Conversations get failed:", error);
+        throw new Error("Failed to get conversation.");
+      }
+    },
+
+    /**
+     * Update a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {object} updates - Fields to update (friendlyName, attributes, etc.)
+     * @returns {Promise<object>} Updated conversation object
+     */
+    update: async (conversationSid, updates) => {
+      try {
+        const conversation = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .update(updates);
+        return conversation;
+      } catch (error) {
+        fastify.log.error("Conversations update failed:", error);
+        throw new Error("Failed to update conversation.");
+      }
+    },
+
+    /**
+     * List all conversations
+     * @param {object} filters - Filter options (limit)
+     * @returns {Promise<object[]>} List of conversations
+     */
+    list: async (filters = {}) => {
+      try {
+        const conversations = await twilioClient.conversations.v1.conversations.list({
+          limit: filters.limit || 50,
+        });
+        return conversations;
+      } catch (error) {
+        fastify.log.error("Conversations list failed:", error);
+        throw new Error("Failed to list conversations.");
+      }
+    },
+
+    /**
+     * Delete a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @returns {Promise<boolean>} Success status
+     */
+    delete: async (conversationSid) => {
+      try {
+        await twilioClient.conversations.v1.conversations(conversationSid).remove();
+        return true;
+      } catch (error) {
+        fastify.log.error("Conversations delete failed:", error);
+        throw new Error("Failed to delete conversation.");
+      }
+    },
+
+    /**
+     * Add a participant to a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {string} identity - Participant identity (for chat users)
+     * @param {string} messagingBindingAddress - Phone number (for SMS participants, e.g., "+1234567890")
+     * @returns {Promise<object>} Participant object
+     */
+    addParticipant: async (conversationSid, identity = null, messagingBindingAddress = null) => {
+      try {
+        const participantData = {};
+
+        if (identity) {
+          participantData.identity = identity;
+        }
+
+        if (messagingBindingAddress) {
+          participantData["messagingBinding.address"] = messagingBindingAddress;
+          participantData["messagingBinding.proxyAddress"] = options.phoneNumber || options.messagingServiceSid;
+        }
+
+        const participant = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .participants.create(participantData);
+
+        return participant;
+      } catch (error) {
+        fastify.log.error("Conversations addParticipant failed:", error);
+        throw new Error("Failed to add participant.");
+      }
+    },
+
+    /**
+     * List participants in a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @returns {Promise<object[]>} List of participants
+     */
+    listParticipants: async (conversationSid) => {
+      try {
+        const participants = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .participants.list();
+        return participants;
+      } catch (error) {
+        fastify.log.error("Conversations listParticipants failed:", error);
+        throw new Error("Failed to list participants.");
+      }
+    },
+
+    /**
+     * Remove a participant from a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {string} participantSid - Participant SID
+     * @returns {Promise<boolean>} Success status
+     */
+    removeParticipant: async (conversationSid, participantSid) => {
+      try {
+        await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .participants(participantSid)
+          .remove();
+        return true;
+      } catch (error) {
+        fastify.log.error("Conversations removeParticipant failed:", error);
+        throw new Error("Failed to remove participant.");
+      }
+    },
+
+    /**
+     * Send a message to a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {string} body - Message content
+     * @param {string} author - Message author (optional, identity or participant SID)
+     * @param {object} attributes - Optional custom attributes
+     * @returns {Promise<object>} Message object
+     */
+    sendMessage: async (conversationSid, body, author = null, attributes = {}) => {
+      try {
+        const messageData = { body };
+
+        if (author) {
+          messageData.author = author;
+        }
+
+        if (Object.keys(attributes).length > 0) {
+          messageData.attributes = JSON.stringify(attributes);
+        }
+
+        const message = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .messages.create(messageData);
+
+        return message;
+      } catch (error) {
+        fastify.log.error("Conversations sendMessage failed:", error);
+        throw new Error("Failed to send message.");
+      }
+    },
+
+    /**
+     * Send a media message to a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {string} mediaUrl - URL of the media file
+     * @param {string} body - Optional message body
+     * @param {string} author - Message author (optional)
+     * @returns {Promise<object>} Message object
+     */
+    sendMediaMessage: async (conversationSid, mediaUrl, body = "", author = null) => {
+      try {
+        const messageData = {
+          body,
+          mediaUrl: [mediaUrl],
+        };
+
+        if (author) {
+          messageData.author = author;
+        }
+
+        const message = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .messages.create(messageData);
+
+        return message;
+      } catch (error) {
+        fastify.log.error("Conversations sendMediaMessage failed:", error);
+        throw new Error("Failed to send media message.");
+      }
+    },
+
+    /**
+     * Get messages from a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {object} options - Pagination options (limit, order)
+     * @returns {Promise<object[]>} List of messages
+     */
+    getMessages: async (conversationSid, options = {}) => {
+      try {
+        const messages = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .messages.list({
+            limit: options.limit || 50,
+            order: options.order || "desc",
+          });
+        return messages;
+      } catch (error) {
+        fastify.log.error("Conversations getMessages failed:", error);
+        throw new Error("Failed to get messages.");
+      }
+    },
+
+    /**
+     * Get a specific message
+     * @param {string} conversationSid - Conversation SID
+     * @param {string} messageSid - Message SID
+     * @returns {Promise<object>} Message object
+     */
+    getMessage: async (conversationSid, messageSid) => {
+      try {
+        const message = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .messages(messageSid)
+          .fetch();
+        return message;
+      } catch (error) {
+        fastify.log.error("Conversations getMessage failed:", error);
+        throw new Error("Failed to get message.");
+      }
+    },
+
+    /**
+     * Delete a message from a conversation
+     * @param {string} conversationSid - Conversation SID
+     * @param {string} messageSid - Message SID
+     * @returns {Promise<boolean>} Success status
+     */
+    deleteMessage: async (conversationSid, messageSid) => {
+      try {
+        await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .messages(messageSid)
+          .remove();
+        return true;
+      } catch (error) {
+        fastify.log.error("Conversations deleteMessage failed:", error);
+        throw new Error("Failed to delete message.");
+      }
+    },
+
+    /**
+     * Get conversation webhooks configuration
+     * @param {string} conversationSid - Conversation SID
+     * @returns {Promise<object>} Webhooks configuration
+     */
+    getWebhooks: async (conversationSid) => {
+      try {
+        const webhooks = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .webhooks()
+          .fetch();
+        return webhooks;
+      } catch (error) {
+        fastify.log.error("Conversations getWebhooks failed:", error);
+        throw new Error("Failed to get webhooks.");
+      }
+    },
+
+    /**
+     * Update conversation webhooks
+     * @param {string} conversationSid - Conversation SID
+     * @param {object} webhookConfig - Webhook configuration
+     * @returns {Promise<object>} Updated webhooks configuration
+     */
+    updateWebhooks: async (conversationSid, webhookConfig) => {
+      try {
+        const webhooks = await twilioClient.conversations.v1
+          .conversations(conversationSid)
+          .webhooks()
+          .update(webhookConfig);
+        return webhooks;
+      } catch (error) {
+        fastify.log.error("Conversations updateWebhooks failed:", error);
+        throw new Error("Failed to update webhooks.");
+      }
+    },
+  });
+
+  console.info("   ✅ Conversations Service Enabled");
+}