@xenterprises/fastify-xtwilio 1.0.0

package/src/services/email.js

@@ -0,0 +1,362 @@
+// src/services/email.js
+import sgMail from "@sendgrid/mail";
+import sgClient from "@sendgrid/client";
+
+export async function setupEmail(fastify, options) {
+  if (options.active === false) return;
+
+  // Validate required credentials
+  if (!options.apiKey) {
+    throw new Error("SendGrid apiKey must be provided for Email service.");
+  }
+
+  if (!options.fromEmail) {
+    throw new Error("fromEmail must be provided for Email service.");
+  }
+
+  // Initialize SendGrid clients
+  sgMail.setApiKey(options.apiKey);
+  sgClient.setApiKey(options.apiKey);
+
+  fastify.decorate("email", {
+    /**
+     * Send an email
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @param {string} text - Plain text content (optional)
+     * @param {object} extraOptions - Additional SendGrid options
+     * @returns {Promise<object>} Send result
+     */
+    send: async (to, subject, html, text = null, extraOptions = {}) => {
+      try {
+        const msg = {
+          to,
+          from: options.fromEmail,
+          subject,
+          html,
+          text: text || html.replace(/<[^>]*>/g, ""), // Strip HTML tags if no text provided
+          ...extraOptions,
+        };
+
+        const response = await sgMail.send(msg);
+        return { success: true, statusCode: response[0].statusCode, messageId: response[0].headers["x-message-id"] };
+      } catch (error) {
+        fastify.log.error("Email send failed:", error);
+        throw new Error("Failed to send email.");
+      }
+    },
+
+    /**
+     * Send an email using a template
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} templateId - SendGrid template ID
+     * @param {object} dynamicData - Template variables
+     * @param {object} extraOptions - Additional SendGrid options
+     * @returns {Promise<object>} Send result
+     */
+    sendTemplate: async (to, subject, templateId, dynamicData = {}, extraOptions = {}) => {
+      try {
+        const msg = {
+          to,
+          from: options.fromEmail,
+          subject,
+          templateId,
+          dynamicTemplateData: { ...dynamicData, subject },
+          ...extraOptions,
+        };
+
+        const response = await sgMail.send(msg);
+        return { success: true, statusCode: response[0].statusCode, messageId: response[0].headers["x-message-id"] };
+      } catch (error) {
+        fastify.log.error("Email sendTemplate failed:", error);
+        throw new Error("Failed to send template email.");
+      }
+    },
+
+    /**
+     * Send an email with attachments
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @param {Array<{content: string, filename: string, type: string}>} attachments - Attachments
+     * @returns {Promise<object>} Send result
+     */
+    sendWithAttachments: async (to, subject, html, attachments) => {
+      try {
+        const msg = {
+          to,
+          from: options.fromEmail,
+          subject,
+          html,
+          attachments: attachments.map((att) => ({
+            content: att.content, // Base64 encoded
+            filename: att.filename,
+            type: att.type,
+            disposition: att.disposition || "attachment",
+          })),
+        };
+
+        const response = await sgMail.send(msg);
+        return { success: true, statusCode: response[0].statusCode };
+      } catch (error) {
+        fastify.log.error("Email sendWithAttachments failed:", error);
+        throw new Error("Failed to send email with attachments.");
+      }
+    },
+
+    /**
+     * Send bulk emails (multiple recipients, same content)
+     * @param {string[]} to - Array of recipient emails
+     * @param {string} subject - Email subject
+     * @param {string} html - HTML content
+     * @returns {Promise<object>} Bulk send result
+     */
+    sendBulk: async (to, subject, html) => {
+      try {
+        const msg = {
+          to,
+          from: options.fromEmail,
+          subject,
+          html,
+        };
+
+        const response = await sgMail.sendMultiple(msg);
+        return { success: true, count: to.length, statusCode: response[0].statusCode };
+      } catch (error) {
+        fastify.log.error("Email sendBulk failed:", error);
+        throw new Error("Failed to send bulk emails.");
+      }
+    },
+
+    /**
+     * Send personalized bulk emails (different content per recipient)
+     * @param {Array<{to: string, subject: string, html: string}>} messages - Array of message objects
+     * @returns {Promise<object[]>} Array of send results
+     */
+    sendPersonalizedBulk: async (messages) => {
+      try {
+        const mailMessages = messages.map((msg) => ({
+          to: msg.to,
+          from: options.fromEmail,
+          subject: msg.subject,
+          html: msg.html,
+          text: msg.text,
+        }));
+
+        const responses = await Promise.allSettled(mailMessages.map((msg) => sgMail.send(msg)));
+
+        return responses.map((result, index) => {
+          if (result.status === "fulfilled") {
+            return {
+              success: true,
+              to: messages[index].to,
+              statusCode: result.value[0].statusCode,
+            };
+          } else {
+            return {
+              success: false,
+              to: messages[index].to,
+              error: result.reason.message,
+            };
+          }
+        });
+      } catch (error) {
+        fastify.log.error("Email sendPersonalizedBulk failed:", error);
+        throw new Error("Failed to send personalized bulk emails.");
+      }
+    },
+
+    /**
+     * Validate an email address using SendGrid Validation API
+     * @param {string} email - Email to validate
+     * @returns {Promise<object>} Validation result
+     */
+    validate: async (email) => {
+      try {
+        const request = {
+          url: `/v3/validations/email`,
+          method: "POST",
+          body: { email },
+        };
+
+        const [response, body] = await sgClient.request(request);
+
+        if (response.statusCode === 200) {
+          return {
+            email,
+            valid: body.result?.verdict === "Valid",
+            verdict: body.result?.verdict,
+            score: body.result?.score,
+            result: body.result,
+          };
+        } else {
+          throw new Error(body.errors ? body.errors.map((err) => err.message).join(", ") : "Validation failed");
+        }
+      } catch (error) {
+        fastify.log.error("Email validation failed:", error);
+        return {
+          email,
+          valid: false,
+          verdict: "Unknown",
+          error: error.message,
+        };
+      }
+    },
+
+    /**
+     * Add or update a contact in SendGrid
+     * @param {string} email - Contact email
+     * @param {object} data - Contact data (first_name, last_name, custom fields)
+     * @param {string[]} listIds - Array of list IDs to add contact to
+     * @returns {Promise<object>} Contact result
+     */
+    addContact: async (email, data = {}, listIds = []) => {
+      try {
+        const request = {
+          url: `/v3/marketing/contacts`,
+          method: "PUT",
+          body: {
+            list_ids: listIds,
+            contacts: [
+              {
+                email,
+                first_name: data.firstName || data.first_name,
+                last_name: data.lastName || data.last_name,
+                ...data.customFields,
+              },
+            ],
+          },
+        };
+
+        const [response, body] = await sgClient.request(request);
+
+        if (response.statusCode === 200 || response.statusCode === 202) {
+          return {
+            success: true,
+            jobId: body.job_id,
+            email,
+          };
+        } else {
+          throw new Error("Failed to add contact");
+        }
+      } catch (error) {
+        fastify.log.error("Email addContact failed:", error);
+        throw new Error("Failed to add contact.");
+      }
+    },
+
+    /**
+     * Search for a contact by email
+     * @param {string} email - Contact email
+     * @returns {Promise<object>} Contact data
+     */
+    searchContact: async (email) => {
+      try {
+        const request = {
+          url: `/v3/marketing/contacts/search/emails`,
+          method: "POST",
+          body: { emails: [email] },
+        };
+
+        const [response, body] = await sgClient.request(request);
+
+        if (response.statusCode === 200 && body.result && body.result[email]) {
+          return {
+            found: true,
+            contact: body.result[email].contact,
+          };
+        } else {
+          return { found: false };
+        }
+      } catch (error) {
+        fastify.log.error("Email searchContact failed:", error);
+        throw new Error("Failed to search contact.");
+      }
+    },
+
+    /**
+     * Delete a contact by ID
+     * @param {string} contactId - Contact ID
+     * @returns {Promise<boolean>} Success status
+     */
+    deleteContact: async (contactId) => {
+      try {
+        const request = {
+          url: `/v3/marketing/contacts`,
+          method: "DELETE",
+          qs: { ids: contactId },
+        };
+
+        const [response] = await sgClient.request(request);
+        return response.statusCode === 202 || response.statusCode === 200;
+      } catch (error) {
+        fastify.log.error("Email deleteContact failed:", error);
+        throw new Error("Failed to delete contact.");
+      }
+    },
+
+    /**
+     * Create a new contact list
+     * @param {string} name - List name
+     * @returns {Promise<object>} List object
+     */
+    createList: async (name) => {
+      try {
+        const request = {
+          url: `/v3/marketing/lists`,
+          method: "POST",
+          body: { name },
+        };
+
+        const [response, body] = await sgClient.request(request);
+        return { success: true, list: body };
+      } catch (error) {
+        fastify.log.error("Email createList failed:", error);
+        throw new Error("Failed to create list.");
+      }
+    },
+
+    /**
+     * Get all contact lists
+     * @returns {Promise<object[]>} Array of lists
+     */
+    getLists: async () => {
+      try {
+        const request = {
+          url: `/v3/marketing/lists`,
+          method: "GET",
+        };
+
+        const [response, body] = await sgClient.request(request);
+        return body.result || [];
+      } catch (error) {
+        fastify.log.error("Email getLists failed:", error);
+        throw new Error("Failed to get lists.");
+      }
+    },
+
+    /**
+     * Delete a contact list
+     * @param {string} listId - List ID
+     * @returns {Promise<boolean>} Success status
+     */
+    deleteList: async (listId) => {
+      try {
+        const request = {
+          url: `/v3/marketing/lists/${listId}`,
+          method: "DELETE",
+        };
+
+        const [response] = await sgClient.request(request);
+        return response.statusCode === 202 || response.statusCode === 200 || response.statusCode === 204;
+      } catch (error) {
+        fastify.log.error("Email deleteList failed:", error);
+        throw new Error("Failed to delete list.");
+      }
+    },
+  });
+
+  console.info("   ✅ Email Service (SendGrid) Enabled");
+}

package/src/services/rcs.js

@@ -0,0 +1,284 @@
+// src/services/rcs.js
+import Twilio from "twilio";
+
+export async function setupRCS(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 RCS.");
+  }
+
+  if (!options.messagingServiceSid) {
+    throw new Error("messagingServiceSid is required for RCS messaging.");
+  }
+
+  // Initialize Twilio client
+  const twilioClient = Twilio(options.accountSid, options.authToken);
+
+  fastify.decorate("rcs", {
+    /**
+     * Send a basic RCS text message
+     * @param {string} to - Recipient phone number (E.164 format)
+     * @param {string} body - Message content
+     * @param {object} extraOptions - Optional parameters
+     * @returns {Promise<object>} Message result
+     */
+    send: async (to, body, extraOptions = {}) => {
+      try {
+        const message = await twilioClient.messages.create({
+          body,
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          contentRetention: "retain",
+          ...extraOptions,
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("RCS send failed:", error);
+        throw new Error("Failed to send RCS message.");
+      }
+    },
+
+    /**
+     * Send an RCS message with media
+     * @param {string} to - Recipient phone number
+     * @param {string} body - Message content
+     * @param {string|string[]} mediaUrl - Media URL(s)
+     * @returns {Promise<object>} Message result
+     */
+    sendMedia: async (to, body, mediaUrl) => {
+      try {
+        const message = await twilioClient.messages.create({
+          body,
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          mediaUrl: Array.isArray(mediaUrl) ? mediaUrl : [mediaUrl],
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("RCS sendMedia failed:", error);
+        throw new Error("Failed to send RCS media message.");
+      }
+    },
+
+    /**
+     * Send an RCS message using Content Template
+     * @param {string} to - Recipient phone number
+     * @param {string} contentSid - Twilio Content Template SID
+     * @param {object} contentVariables - Template variables
+     * @returns {Promise<object>} Message result
+     */
+    sendTemplate: async (to, contentSid, contentVariables = {}) => {
+      try {
+        const message = await twilioClient.messages.create({
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          contentSid,
+          contentVariables: JSON.stringify(contentVariables),
+        });
+        return message;
+      } catch (error) {
+        fastify.log.error("RCS sendTemplate failed:", error);
+        throw new Error("Failed to send RCS template message.");
+      }
+    },
+
+    /**
+     * Send an RCS rich card message
+     * @param {string} to - Recipient phone number
+     * @param {object} card - Rich card configuration
+     * @param {string} card.title - Card title
+     * @param {string} card.description - Card description
+     * @param {string} card.mediaUrl - Card media URL
+     * @param {Array} card.actions - Card actions/buttons
+     * @returns {Promise<object>} Message result
+     */
+    sendRichCard: async (to, card) => {
+      try {
+        // Build content for rich card using Twilio Content API
+        const contentData = {
+          types: {
+            "twilio/card": {
+              title: card.title,
+              subtitle: card.description,
+              media: card.mediaUrl ? [card.mediaUrl] : [],
+              actions: card.actions || [],
+            },
+          },
+        };
+
+        // Create content template if contentSid not provided
+        let contentSid = card.contentSid;
+        if (!contentSid) {
+          const content = await twilioClient.content.v1.contents.create({
+            friendly_name: `RCS Card ${Date.now()}`,
+            types: contentData.types,
+          });
+          contentSid = content.sid;
+        }
+
+        const message = await twilioClient.messages.create({
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          contentSid,
+        });
+
+        return message;
+      } catch (error) {
+        fastify.log.error("RCS sendRichCard failed:", error);
+        throw new Error("Failed to send RCS rich card.");
+      }
+    },
+
+    /**
+     * Send an RCS carousel message
+     * @param {string} to - Recipient phone number
+     * @param {object[]} cards - Array of card objects
+     * @returns {Promise<object>} Message result
+     */
+    sendCarousel: async (to, cards) => {
+      try {
+        const contentData = {
+          types: {
+            "twilio/list-picker": {
+              body: "Please select an option",
+              items: cards.map((card) => ({
+                id: card.id || `card_${Date.now()}`,
+                title: card.title,
+                description: card.description,
+                media: card.mediaUrl,
+              })),
+            },
+          },
+        };
+
+        const content = await twilioClient.content.v1.contents.create({
+          friendly_name: `RCS Carousel ${Date.now()}`,
+          types: contentData.types,
+        });
+
+        const message = await twilioClient.messages.create({
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          contentSid: content.sid,
+        });
+
+        return message;
+      } catch (error) {
+        fastify.log.error("RCS sendCarousel failed:", error);
+        throw new Error("Failed to send RCS carousel.");
+      }
+    },
+
+    /**
+     * Send an RCS message with suggested quick replies
+     * @param {string} to - Recipient phone number
+     * @param {string} body - Message content
+     * @param {Array<{text: string, payload: string}>} replies - Quick reply options
+     * @returns {Promise<object>} Message result
+     */
+    sendQuickReplies: async (to, body, replies) => {
+      try {
+        const contentData = {
+          types: {
+            "twilio/quick-reply": {
+              body,
+              actions: replies.map((reply) => ({
+                type: "quick-reply",
+                title: reply.text,
+                id: reply.payload || reply.text,
+              })),
+            },
+          },
+        };
+
+        const content = await twilioClient.content.v1.contents.create({
+          friendly_name: `RCS Quick Reply ${Date.now()}`,
+          types: contentData.types,
+        });
+
+        const message = await twilioClient.messages.create({
+          to,
+          messagingServiceSid: options.messagingServiceSid,
+          contentSid: content.sid,
+        });
+
+        return message;
+      } catch (error) {
+        fastify.log.error("RCS sendQuickReplies failed:", error);
+        throw new Error("Failed to send RCS quick replies.");
+      }
+    },
+
+    /**
+     * Get RCS message status
+     * @param {string} messageSid - 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,
+          channel: message.channel,
+        };
+      } catch (error) {
+        fastify.log.error("RCS getStatus failed:", error);
+        throw new Error("Failed to get RCS message status.");
+      }
+    },
+
+    /**
+     * List RCS content templates
+     * @param {object} options - List options
+     * @returns {Promise<object[]>} List of content templates
+     */
+    listTemplates: async (listOptions = {}) => {
+      try {
+        const contents = await twilioClient.content.v1.contents.list({
+          limit: listOptions.limit || 50,
+        });
+        return contents;
+      } catch (error) {
+        fastify.log.error("RCS listTemplates failed:", error);
+        throw new Error("Failed to list RCS templates.");
+      }
+    },
+
+    /**
+     * Get a content template by SID
+     * @param {string} contentSid - Content template SID
+     * @returns {Promise<object>} Content template
+     */
+    getTemplate: async (contentSid) => {
+      try {
+        const content = await twilioClient.content.v1.contents(contentSid).fetch();
+        return content;
+      } catch (error) {
+        fastify.log.error("RCS getTemplate failed:", error);
+        throw new Error("Failed to get RCS template.");
+      }
+    },
+
+    /**
+     * Delete a content template
+     * @param {string} contentSid - Content template SID
+     * @returns {Promise<boolean>} Success status
+     */
+    deleteTemplate: async (contentSid) => {
+      try {
+        await twilioClient.content.v1.contents(contentSid).remove();
+        return true;
+      } catch (error) {
+        fastify.log.error("RCS deleteTemplate failed:", error);
+        throw new Error("Failed to delete RCS template.");
+      }
+    },
+  });
+
+  console.info("   ✅ RCS Service Enabled");
+}