@xenterprises/fastify-xtwilio 1.0.0

package/src/services/sms.js

@@ -0,0 +1,268 @@
+// src/services/sms.js
+import Twilio from "twilio";
+
+export async function setupSMS(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 SMS.");
+  }
+
+  if (!options.phoneNumber && !options.messagingServiceSid) {
+    throw new Error("Either phoneNumber or messagingServiceSid must be provided for SMS.");
+  }
+
+  // Initialize Twilio client
+  const twilioClient = Twilio(options.accountSid, options.authToken);
+
+  fastify.decorate("sms", {
+    /**
+     * Send an SMS message
+     * @param {string} to - Recipient phone number (E.164 format recommended)
+     * @param {string} body - Message content
+     * @param {object} options - Optional parameters (statusCallback, etc.)
+     * @returns {Promise<object>} Message result
+     */
+    send: async (to, body, extraOptions = {}) => {
+      try {
+        const message = await twilioClient.messages.create({
+          body,
+          to,
+          from: options.phoneNumber,
+          messagingServiceSid: options.messagingServiceSid,
+          ...extraOptions,
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("SMS send failed:", error);
+        throw new Error("Failed to send SMS.");
+      }
+    },
+
+    /**
+     * Send an MMS message with media
+     * @param {string} to - Recipient phone number
+     * @param {string} body - Message content
+     * @param {string|string[]} mediaUrl - Media URL(s)
+     * @param {object} options - Optional parameters
+     * @returns {Promise<object>} Message result
+     */
+    sendMMS: async (to, body, mediaUrl, extraOptions = {}) => {
+      try {
+        const message = await twilioClient.messages.create({
+          body,
+          to,
+          from: options.phoneNumber,
+          messagingServiceSid: options.messagingServiceSid,
+          mediaUrl: Array.isArray(mediaUrl) ? mediaUrl : [mediaUrl],
+          ...extraOptions,
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("MMS send failed:", error);
+        throw new Error("Failed to send MMS.");
+      }
+    },
+
+    /**
+     * Schedule an SMS message (requires Messaging Service)
+     * @param {string} to - Recipient phone number
+     * @param {string} body - Message content
+     * @param {Date|string} sendAt - When to send the message (ISO 8601 format)
+     * @returns {Promise<object>} Message result
+     */
+    schedule: async (to, body, sendAt) => {
+      try {
+        if (!options.messagingServiceSid) {
+          throw new Error("messagingServiceSid is required for scheduled messages.");
+        }
+
+        const message = await twilioClient.messages.create({
+          body,
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          scheduleType: "fixed",
+          sendAt: sendAt instanceof Date ? sendAt.toISOString() : sendAt,
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("SMS schedule failed:", error);
+        throw new Error("Failed to schedule SMS.");
+      }
+    },
+
+    /**
+     * Cancel a scheduled message
+     * @param {string} messageSid - Message SID
+     * @returns {Promise<object>} Updated message
+     */
+    cancelScheduled: async (messageSid) => {
+      try {
+        const message = await twilioClient.messages(messageSid).update({
+          status: "canceled",
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("SMS cancel scheduled failed:", error);
+        throw new Error("Failed to cancel scheduled SMS.");
+      }
+    },
+
+    /**
+     * Get message by SID
+     * @param {string} messageSid - Twilio message SID
+     * @returns {Promise<object>} Message object
+     */
+    get: async (messageSid) => {
+      try {
+        const message = await twilioClient.messages(messageSid).fetch();
+        return message;
+      } catch (error) {
+        fastify.log.error("SMS get failed:", error);
+        throw new Error("Failed to get SMS.");
+      }
+    },
+
+    /**
+     * Get message status
+     * @param {string} messageSid - Twilio message SID
+     * @returns {Promise<object>} Message status
+     */
+    getStatus: async (messageSid) => {
+      try {
+        const message = await twilioClient.messages(messageSid).fetch();
+        return {
+          sid: message.sid,
+          status: message.status,
+          errorCode: message.errorCode,
+          errorMessage: message.errorMessage,
+          dateCreated: message.dateCreated,
+          dateUpdated: message.dateUpdated,
+          dateSent: message.dateSent,
+        };
+      } catch (error) {
+        fastify.log.error("SMS getStatus failed:", error);
+        throw new Error("Failed to get SMS status.");
+      }
+    },
+
+    /**
+     * List messages
+     * @param {object} filters - Filter options (dateSent, from, to, limit)
+     * @returns {Promise<object[]>} List of messages
+     */
+    list: async (filters = {}) => {
+      try {
+        const messages = await twilioClient.messages.list({
+          from: filters.from,
+          to: filters.to,
+          dateSentAfter: filters.dateSentAfter,
+          dateSentBefore: filters.dateSentBefore,
+          limit: filters.limit || 50,
+        });
+        return messages;
+      } catch (error) {
+        fastify.log.error("SMS list failed:", error);
+        throw new Error("Failed to list SMS messages.");
+      }
+    },
+
+    /**
+     * Delete a message
+     * @param {string} messageSid - Message SID
+     * @returns {Promise<boolean>} Success status
+     */
+    delete: async (messageSid) => {
+      try {
+        await twilioClient.messages(messageSid).remove();
+        return true;
+      } catch (error) {
+        fastify.log.error("SMS delete failed:", error);
+        throw new Error("Failed to delete SMS.");
+      }
+    },
+
+    /**
+     * Get media from a message
+     * @param {string} messageSid - Message SID
+     * @returns {Promise<object[]>} List of media items
+     */
+    getMedia: async (messageSid) => {
+      try {
+        const media = await twilioClient.messages(messageSid).media.list();
+        return media;
+      } catch (error) {
+        fastify.log.error("SMS getMedia failed:", error);
+        throw new Error("Failed to get media.");
+      }
+    },
+
+    /**
+     * Validate a phone number using Lookup API
+     * @param {string} phoneNumber - Phone number to validate
+     * @param {object} options - Lookup options (type, addOns)
+     * @returns {Promise<object>} Validation result
+     */
+    validatePhoneNumber: async (phoneNumber, lookupOptions = {}) => {
+      try {
+        const validation = await twilioClient.lookups.v2
+          .phoneNumbers(phoneNumber)
+          .fetch(lookupOptions);
+
+        const isValid = validation.valid !== undefined ? validation.valid : true;
+
+        return {
+          phoneNumber: validation.phoneNumber,
+          nationalFormat: validation.nationalFormat,
+          countryCode: validation.countryCode,
+          valid: isValid,
+          validation,
+        };
+      } catch (error) {
+        fastify.log.error("Phone number validation failed:", error);
+        return {
+          phoneNumber,
+          valid: false,
+          validation: {},
+        };
+      }
+    },
+
+    /**
+     * Send bulk SMS messages
+     * @param {Array<{to: string, body: string}>} messages - Array of messages to send
+     * @returns {Promise<object[]>} Array of message results
+     */
+    sendBulk: async (messages) => {
+      try {
+        const promises = messages.map((msg) =>
+          twilioClient.messages.create({
+            body: msg.body,
+            to: msg.to,
+            from: options.phoneNumber,
+            messagingServiceSid: options.messagingServiceSid,
+          })
+        );
+
+        const results = await Promise.allSettled(promises);
+        return results.map((result, index) => {
+          if (result.status === "fulfilled") {
+            return { success: true, message: result.value };
+          } else {
+            return {
+              success: false,
+              error: result.reason.message,
+              to: messages[index].to,
+            };
+          }
+        });
+      } catch (error) {
+        fastify.log.error("SMS sendBulk failed:", error);
+        throw new Error("Failed to send bulk SMS.");
+      }
+    },
+  });
+
+  console.info("   ✅ SMS Service Enabled");
+}

package/src/xTwilio.js

@@ -0,0 +1,37 @@
+// src/xTwilio.js
+import fp from "fastify-plugin";
+
+/*
+ * Services
+ */
+import { setupSMS } from "./services/sms.js";
+import { setupConversations } from "./services/conversations.js";
+import { setupRCS } from "./services/rcs.js";
+import { setupEmail } from "./services/email.js";
+
+async function xTwilio(fastify, options) {
+  const {
+    twilio: twilioOptions = {},
+    sendgrid: sendgridOptions = {},
+  } = options;
+
+  console.info("\n 📱 Starting xTwilio...\n");
+
+  /*
+   * Twilio Services
+   */
+  await setupSMS(fastify, twilioOptions);
+  await setupConversations(fastify, twilioOptions);
+  await setupRCS(fastify, twilioOptions);
+
+  /*
+   * SendGrid Email
+   */
+  await setupEmail(fastify, sendgridOptions);
+
+  console.info("\n 📱 xTwilio Ready!\n");
+}
+
+export default fp(xTwilio, {
+  name: "xTwilio",
+});