@xenterprises/fastify-xemail 1.1.1 → 1.3.0

package/src/providers/postmark.js

@@ -0,0 +1,223 @@
+import postmark from "postmark";
+
+const BATCH_LIMIT = 500;
+
+function mapExtraOptions(extraOptions) {
+  const { replyTo, cc, bcc, headers, messageStream, ...rest } = extraOptions;
+  return {
+    ...(replyTo && { ReplyTo: replyTo }),
+    ...(cc && { Cc: Array.isArray(cc) ? cc.join(", ") : cc }),
+    ...(bcc && { Bcc: Array.isArray(bcc) ? bcc.join(", ") : bcc }),
+    ...(headers && {
+      Headers: Object.entries(headers).map(([Name, Value]) => ({ Name, Value })),
+    }),
+    ...(messageStream && { MessageStream: messageStream }),
+    ...rest,
+  };
+}
+
+function unsupported(method) {
+  return async () => {
+    throw new Error(`[xEmail] '${method}()' is not supported by provider 'postmark'.`);
+  };
+}
+
+/**
+ * Create the Postmark-backed xEmail service.
+ * @param {object} config
+ * @param {string} config.apiKey - Postmark server API token
+ * @param {string} config.fromEmail - Verified sender email address
+ * @param {string} [config.fromName] - Sender display name
+ * @param {import('fastify').FastifyBaseLogger} config.log
+ */
+export function createService({ apiKey, fromEmail, fromName, log }) {
+  const client = new postmark.ServerClient(apiKey);
+
+  const from = fromName ? `${fromName} <${fromEmail}>` : fromEmail;
+  const toAddresses = (to) => (Array.isArray(to) ? to.join(", ") : to);
+
+  return {
+    /**
+     * 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 options (replyTo, cc, bcc, headers, messageStream)
+     * @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 response = await client.sendEmail({
+          From: from,
+          To: toAddresses(to),
+          Subject: subject,
+          HtmlBody: html,
+          TextBody: text || html.replace(/<[^>]*>/g, ""),
+          ...mapExtraOptions(extraOptions),
+        });
+        return { success: true, statusCode: 200, messageId: response.MessageID };
+      } catch (error) {
+        log.error({ err: error }, "xEmail send failed");
+        throw new Error(`[xEmail] Failed to send email: ${error.message}`);
+      }
+    },
+
+    /**
+     * Send an email using a Postmark template.
+     * @param {string|string[]} to - Recipient email(s)
+     * @param {string} subject - Email subject (passed to the template model)
+     * @param {string|number} templateId - Postmark template alias (string) or ID (number)
+     * @param {object} [dynamicData] - Template variables
+     * @param {object} [extraOptions] - Additional options (replyTo, cc, bcc, headers, messageStream)
+     * @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().");
+
+      const templateKey =
+        typeof templateId === "number" ? { TemplateId: templateId } : { TemplateAlias: templateId };
+
+      try {
+        const response = await client.sendEmailWithTemplate({
+          From: from,
+          To: toAddresses(to),
+          ...templateKey,
+          TemplateModel: { ...dynamicData, subject },
+          ...mapExtraOptions(extraOptions),
+        });
+        return { success: true, statusCode: 200, messageId: response.MessageID };
+      } catch (error) {
+        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 response = await client.sendEmail({
+          From: from,
+          To: toAddresses(to),
+          Subject: subject,
+          HtmlBody: html,
+          Attachments: attachments.map((att) => ({
+            Name: att.filename,
+            Content: att.content,
+            ContentType: att.type,
+            ...(att.disposition === "inline" && { ContentID: `cid:${att.filename}` }),
+          })),
+        });
+        return { success: true, statusCode: 200, messageId: response.MessageID };
+      } catch (error) {
+        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).
+     * Postmark has no shared-body multi-recipient endpoint, so one email is
+     * sent per recipient, in chunks of 500 concurrent requests.
+     * @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 {
+        for (let i = 0; i < to.length; i += BATCH_LIMIT) {
+          const chunk = to.slice(i, i + BATCH_LIMIT);
+          await Promise.all(
+            chunk.map((To) =>
+              client.sendEmail({ From: from, To, Subject: subject, HtmlBody: html })
+            )
+          );
+        }
+        return { success: true, count: to.length, statusCode: 200 };
+      } catch (error) {
+        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) via the
+     * Postmark batch endpoint. Never throws for per-recipient failures.
+     * @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 results = [];
+      for (let i = 0; i < messages.length; i += BATCH_LIMIT) {
+        const chunk = messages.slice(i, i + BATCH_LIMIT);
+        let batchResults;
+        try {
+          batchResults = await client.sendEmailBatch(
+            chunk.map((msg) => ({
+              From: from,
+              To: msg.to,
+              Subject: msg.subject,
+              HtmlBody: msg.html,
+              TextBody: msg.text,
+            }))
+          );
+        } catch (error) {
+          log.error({ err: error }, "xEmail sendPersonalizedBulk batch failed");
+          batchResults = chunk.map(() => ({ ErrorCode: -1, Message: error.message }));
+        }
+
+        for (let j = 0; j < chunk.length; j++) {
+          const result = batchResults[j];
+          if (result.ErrorCode === 0) {
+            results.push({ success: true, to: chunk[j].to, statusCode: 200 });
+          } else {
+            results.push({ success: false, to: chunk[j].to, error: result.Message });
+          }
+        }
+      }
+      return results;
+    },
+
+    // The following features are SendGrid-only; Postmark has no equivalent APIs.
+    validate: unsupported("validate"),
+    addContact: unsupported("addContact"),
+    searchContact: unsupported("searchContact"),
+    deleteContact: unsupported("deleteContact"),
+    createList: unsupported("createList"),
+    getLists: unsupported("getLists"),
+    deleteList: unsupported("deleteList"),
+  };
+}

package/src/providers/sendgrid.js

@@ -0,0 +1,389 @@
+import sgClient from "@sendgrid/client";
+import sgMail from "@sendgrid/mail";
+
+/**
+ * Create the SendGrid-backed xEmail service.
+ * @param {object} config
+ * @param {string} config.apiKey - SendGrid API key
+ * @param {string} config.fromEmail - Verified sender email address
+ * @param {string} [config.fromName] - Sender display name
+ * @param {import('fastify').FastifyBaseLogger} config.log
+ */
+export function createService({ apiKey, fromEmail, fromName, log }) {
+  sgMail.setApiKey(apiKey);
+  sgClient.setApiKey(apiKey);
+
+  const from = fromName ? { email: fromEmail, name: fromName } : fromEmail;
+
+  return {
+    /**
+     * 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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        log.error({ err: error }, "xEmail getLists failed");
+        throw new Error(`[xEmail] Failed to get lists: ${error.message}`);
+      }
+    },
+
+    /**
+     * 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().");
+      }
+
+      try {
+        const [response] = await sgClient.request({
+          url: `/v3/marketing/lists/${listId}`,
+          method: "DELETE",
+        });
+        return [200, 202, 204].includes(response.statusCode);
+      } catch (error) {
+        log.error({ err: error }, "xEmail deleteList failed");
+        throw new Error(`[xEmail] Failed to delete list: ${error.message}`);
+      }
+    },
+  };
+}