@xenterprises/fastify-xemail 1.1.1 → 1.3.0

package/src/xEmail.js

@@ -1,405 +1,66 @@
 import fp from "fastify-plugin";
-import sgMail from "@sendgrid/mail";
-import sgClient from "@sendgrid/client";
+import { createService as createPostmarkService } from "./providers/postmark.js";
+import { createService as createSendGridService } from "./providers/sendgrid.js";
+
+const PROVIDERS = {
+  sendgrid: createSendGridService,
+  postmark: createPostmarkService,
+};
+
+const API_KEY_EXAMPLES = {
+  sendgrid: "SG.your-api-key",
+  postmark: "your-postmark-server-token",
+};
 
 /**
  * @param {import('fastify').FastifyInstance} fastify
  * @param {object} options
- * @param {string} options.apiKey - SendGrid API key
+ * @param {'sendgrid'|'postmark'} [options.provider='sendgrid'] - Email provider ('sendgrid' is legacy; 'postmark' is the migration target)
+ * @param {string} options.apiKey - Provider API key (SendGrid API key or Postmark server token)
  * @param {string} options.fromEmail - Verified sender email address
  * @param {string} [options.fromName] - Sender display name
  * @param {boolean} [options.active=true] - Enable/disable the plugin
  */
 async function xEmail(fastify, options) {
-  const { active = true, apiKey, fromEmail, fromName } = options;
+  const { active = true, provider = "sendgrid", apiKey, fromEmail, fromName } = options;
+
+  if (typeof active !== "boolean") {
+    throw new Error("xemail: option `active` must be a boolean");
+  }
 
   if (active === false) return;
 
+  if (!PROVIDERS[provider]) {
+    throw new Error("xemail: option `provider` must be 'sendgrid' or 'postmark'");
+  }
+
   if (!apiKey || typeof apiKey !== "string") {
-    throw new Error("[xEmail] 'apiKey' (string) is required.");
+    throw new Error(
+      `xemail: option \`apiKey\` must be a string, e.g. \`app.register(xEmail, { apiKey: '${API_KEY_EXAMPLES[provider]}' })\``
+    );
   }
 
   if (!fromEmail || typeof fromEmail !== "string") {
-    throw new Error("[xEmail] 'fromEmail' (string) is required.");
+    throw new Error(
+      `xemail: option \`fromEmail\` must be a string, e.g. \`app.register(xEmail, { apiKey: '${API_KEY_EXAMPLES[provider]}', fromEmail: 'noreply@example.com' })\``
+    );
   }
 
-  sgMail.setApiKey(apiKey);
-  sgClient.setApiKey(apiKey);
-
-  const from = fromName ? { email: fromEmail, name: fromName } : fromEmail;
-
-  fastify.log.info("xEmail (SendGrid) initialized");
-
-  fastify.decorate("xEmail", {
-    /**
-     * 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 fallback (auto-generated from HTML if omitted)
-     * @param {object} [extraOptions] - Additional SendGrid mail options
-     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
-     */
-    send: async (to, subject, html, text = null, extraOptions = {}) => {
-      if (!to) throw new Error("[xEmail] 'to' is required for send().");
-      if (!subject) throw new Error("[xEmail] 'subject' is required for send().");
-      if (!html) throw new Error("[xEmail] 'html' is required for send().");
-
-      try {
-        const msg = {
-          to,
-          from,
-          subject,
-          html,
-          text: text || html.replace(/<[^>]*>/g, ""),
-          ...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({ err: error }, "xEmail send failed");
-        throw new Error(`[xEmail] Failed to send email: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send an email using a SendGrid dynamic template.
-     * @param {string|string[]} to - Recipient email(s)
-     * @param {string} subject - Email subject
-     * @param {string} templateId - SendGrid dynamic template ID (d-xxx)
-     * @param {object} [dynamicData] - Template variables
-     * @param {object} [extraOptions] - Additional SendGrid mail options
-     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
-     */
-    sendTemplate: async (to, subject, templateId, dynamicData = {}, extraOptions = {}) => {
-      if (!to) throw new Error("[xEmail] 'to' is required for sendTemplate().");
-      if (!subject) throw new Error("[xEmail] 'subject' is required for sendTemplate().");
-      if (!templateId) throw new Error("[xEmail] 'templateId' is required for sendTemplate().");
-
-      try {
-        const msg = {
-          to,
-          from,
-          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({ err: error }, "xEmail sendTemplate failed");
-        throw new Error(`[xEmail] Failed to send template email: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send an email with file 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, disposition?: string}>} attachments
-     * @returns {Promise<{success: boolean, statusCode: number, messageId: string}>}
-     */
-    sendWithAttachments: async (to, subject, html, attachments) => {
-      if (!to) throw new Error("[xEmail] 'to' is required for sendWithAttachments().");
-      if (!subject) throw new Error("[xEmail] 'subject' is required for sendWithAttachments().");
-      if (!html) throw new Error("[xEmail] 'html' is required for sendWithAttachments().");
-      if (!Array.isArray(attachments) || attachments.length === 0) {
-        throw new Error("[xEmail] 'attachments' must be a non-empty array.");
-      }
-
-      try {
-        const msg = {
-          to,
-          from,
-          subject,
-          html,
-          attachments: attachments.map((att) => ({
-            content: att.content,
-            filename: att.filename,
-            type: att.type,
-            disposition: att.disposition || "attachment",
-          })),
-        };
-
-        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({ err: error }, "xEmail sendWithAttachments failed");
-        throw new Error(`[xEmail] Failed to send email with attachments: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send bulk emails (same content to multiple recipients).
-     * @param {string[]} to - Array of recipient emails
-     * @param {string} subject - Email subject
-     * @param {string} html - HTML content
-     * @returns {Promise<{success: boolean, count: number, statusCode: number}>}
-     */
-    sendBulk: async (to, subject, html) => {
-      if (!Array.isArray(to) || to.length === 0) {
-        throw new Error("[xEmail] 'to' must be a non-empty array for sendBulk().");
-      }
-      if (!subject) throw new Error("[xEmail] 'subject' is required for sendBulk().");
-      if (!html) throw new Error("[xEmail] 'html' is required for sendBulk().");
-
-      try {
-        const msg = { to, from, subject, html };
-        const response = await sgMail.sendMultiple(msg);
-        return { success: true, count: to.length, statusCode: response[0].statusCode };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail sendBulk failed");
-        throw new Error(`[xEmail] Failed to send bulk emails: ${error.message}`);
-      }
-    },
-
-    /**
-     * Send personalized emails (different content per recipient).
-     * @param {Array<{to: string, subject: string, html: string, text?: string}>} messages
-     * @returns {Promise<Array<{success: boolean, to: string, statusCode?: number, error?: string}>>}
-     */
-    sendPersonalizedBulk: async (messages) => {
-      if (!Array.isArray(messages) || messages.length === 0) {
-        throw new Error("[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk().");
-      }
-
-      const mailMessages = messages.map((msg) => ({
-        to: msg.to,
-        from,
-        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,
-          };
-        }
-        return {
-          success: false,
-          to: messages[index].to,
-          error: result.reason.message,
-        };
-      });
-    },
-
-    /**
-     * Validate an email address using SendGrid Email Validation API.
-     * @param {string} email - Email to validate
-     * @returns {Promise<{email: string, valid: boolean, verdict: string, score?: number, result?: object, error?: string}>}
-     */
-    validate: async (email) => {
-      if (!email || typeof email !== "string") {
-        throw new Error("[xEmail] 'email' (string) is required for validate().");
-      }
-
-      try {
-        const [response, body] = await sgClient.request({
-          url: `/v3/validations/email`,
-          method: "POST",
-          body: { email },
-        });
-
-        if (response.statusCode === 200) {
-          return {
-            email,
-            valid: body.result?.verdict === "Valid",
-            verdict: body.result?.verdict,
-            score: body.result?.score,
-            result: body.result,
-          };
-        }
-
-        throw new Error(body.errors ? body.errors.map((e) => e.message).join(", ") : "Validation failed");
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail validate failed");
-        return {
-          email,
-          valid: false,
-          verdict: "Unknown",
-          error: error.message,
-        };
-      }
-    },
-
-    /**
-     * Add or update a contact in SendGrid Marketing.
-     * @param {string} email - Contact email
-     * @param {object} [data] - Contact data (firstName, lastName, customFields)
-     * @param {string[]} [listIds] - List IDs to add the contact to
-     * @returns {Promise<{success: boolean, jobId: string, email: string}>}
-     */
-    addContact: async (email, data = {}, listIds = []) => {
-      if (!email || typeof email !== "string") {
-        throw new Error("[xEmail] 'email' (string) is required for addContact().");
-      }
-
-      try {
-        const [response, body] = await sgClient.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,
-              },
-            ],
-          },
-        });
-
-        if (response.statusCode === 200 || response.statusCode === 202) {
-          return { success: true, jobId: body.job_id, email };
-        }
-
-        throw new Error("Unexpected status code: " + response.statusCode);
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail addContact failed");
-        throw new Error(`[xEmail] Failed to add contact: ${error.message}`);
-      }
-    },
-
-    /**
-     * Search for a contact by email.
-     * @param {string} email - Contact email
-     * @returns {Promise<{found: boolean, contact?: object}>}
-     */
-    searchContact: async (email) => {
-      if (!email || typeof email !== "string") {
-        throw new Error("[xEmail] 'email' (string) is required for searchContact().");
-      }
-
-      try {
-        const [response, body] = await sgClient.request({
-          url: `/v3/marketing/contacts/search/emails`,
-          method: "POST",
-          body: { emails: [email] },
-        });
-
-        if (response.statusCode === 200 && body.result?.[email]) {
-          return { found: true, contact: body.result[email].contact };
-        }
-
-        return { found: false };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail searchContact failed");
-        throw new Error(`[xEmail] Failed to search contact: ${error.message}`);
-      }
-    },
-
-    /**
-     * Delete a contact by ID.
-     * @param {string} contactId - Contact ID
-     * @returns {Promise<boolean>}
-     */
-    deleteContact: async (contactId) => {
-      if (!contactId || typeof contactId !== "string") {
-        throw new Error("[xEmail] 'contactId' (string) is required for deleteContact().");
-      }
-
-      try {
-        const [response] = await sgClient.request({
-          url: `/v3/marketing/contacts`,
-          method: "DELETE",
-          qs: { ids: contactId },
-        });
-        return response.statusCode === 202 || response.statusCode === 200;
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail deleteContact failed");
-        throw new Error(`[xEmail] Failed to delete contact: ${error.message}`);
-      }
-    },
-
-    /**
-     * Create a new contact list.
-     * @param {string} name - List name
-     * @returns {Promise<{success: boolean, list: object}>}
-     */
-    createList: async (name) => {
-      if (!name || typeof name !== "string") {
-        throw new Error("[xEmail] 'name' (string) is required for createList().");
-      }
-
-      try {
-        const [, body] = await sgClient.request({
-          url: `/v3/marketing/lists`,
-          method: "POST",
-          body: { name },
-        });
-        return { success: true, list: body };
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail createList failed");
-        throw new Error(`[xEmail] Failed to create list: ${error.message}`);
-      }
-    },
-
-    /**
-     * Get all contact lists.
-     * @returns {Promise<object[]>}
-     */
-    getLists: async () => {
-      try {
-        const [, body] = await sgClient.request({
-          url: `/v3/marketing/lists`,
-          method: "GET",
-        });
-        return body.result || [];
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail getLists failed");
-        throw new Error(`[xEmail] Failed to get lists: ${error.message}`);
-      }
-    },
+  if (fromName !== undefined && typeof fromName !== "string") {
+    throw new Error(
+      `xemail: option \`fromName\` must be a string, e.g. \`app.register(xEmail, { apiKey: '${API_KEY_EXAMPLES[provider]}', fromEmail: 'noreply@example.com', fromName: 'My App' })\``
+    );
+  }
 
-    /**
-     * Delete a contact list.
-     * @param {string} listId - List ID
-     * @returns {Promise<boolean>}
-     */
-    deleteList: async (listId) => {
-      if (!listId || typeof listId !== "string") {
-        throw new Error("[xEmail] 'listId' (string) is required for deleteList().");
-      }
+  fastify.log.info(`xEmail (${provider}) initialized`);
 
-      try {
-        const [response] = await sgClient.request({
-          url: `/v3/marketing/lists/${listId}`,
-          method: "DELETE",
-        });
-        return [200, 202, 204].includes(response.statusCode);
-      } catch (error) {
-        fastify.log.error({ err: error }, "xEmail deleteList failed");
-        throw new Error(`[xEmail] Failed to delete list: ${error.message}`);
-      }
-    },
-  });
+  fastify.decorate(
+    "xEmail",
+    PROVIDERS[provider]({ apiKey, fromEmail, fromName, log: fastify.log })
+  );
 }
 
 export default fp(xEmail, {
-  name: "xEmail",
-  fastify: ">=5.0.0",
+  name: "xemail",
+  fastify: "5.x",
 });