@xenterprises/fastify-xemail 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# @xenterprises/fastify-xemail
+
+Fastify plugin for SendGrid email integration.
+
+## Features
+
+- Send simple emails
+- Send template-based emails
+- Send emails with attachments
+- Bulk sending (simple and personalized)
+- Email validation
+- Contact management (add, search, delete)
+- List management
+
+## Installation
+
+```bash
+npm install @xenterprises/fastify-xemail
+```
+
+## Usage
+
+```javascript
+import Fastify from 'fastify';
+import xEmail from '@xenterprises/fastify-xemail';
+
+const fastify = Fastify();
+
+await fastify.register(xEmail, {
+  apiKey: process.env.SENDGRID_API_KEY,
+  fromEmail: 'noreply@yourdomain.com'
+});
+
+// Usage example
+fastify.get('/send-welcome', async (request, reply) => {
+  const { email, name } = request.query;
+  
+  await fastify.email.send(
+    email,
+    'Welcome!',
+    `<h1>Welcome ${name}!</h1>`,
+    `Welcome ${name}!`
+  );
+  
+  return { success: true };
+});
+```
+
+## API
+
+### `fastify.email.send(to, subject, html, text, extraOptions)`
+Send a single email.
+
+### `fastify.email.sendTemplate(to, subject, templateId, dynamicData, extraOptions)`
+Send an email using a SendGrid dynamic template.
+
+### `fastify.email.sendWithAttachments(to, subject, html, attachments)`
+Send an email with attachments.
+
+### `fastify.email.validate(email)`
+Validate an email address using SendGrid's Validation API.
+
+## License
+
+ISC

package/index.d.ts

@@ -0,0 +1,325 @@
+/**
+ * xEmail - Fastify Plugin for SendGrid Email
+ * TypeScript Type Definitions
+ *
+ * @module @xenterprises/fastify-xemail
+ * @version 1.0.0
+ */
+
+import { FastifyPluginAsync } from 'fastify';
+
+/**
+ * Email Options
+ */
+export interface EmailOptions {
+  /** Email priority */
+  priority?: 'low' | 'normal' | 'high';
+
+  /** Custom headers */
+  headers?: Record<string, string>;
+
+  /** Reply-to address */
+  replyTo?: string;
+
+  /** BCC recipients */
+  bcc?: string[];
+
+  /** Custom categories for tracking */
+  categories?: string[];
+
+  /** Custom metadata */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Email with Attachments Options
+ */
+export interface EmailWithAttachmentsOptions extends EmailOptions {
+  /** Attachments array */
+  attachments: Array<{
+    /** Attachment content (base64) */
+    content: string;
+
+    /** File name */
+    filename: string;
+
+    /** MIME type */
+    type: string;
+
+    /** Content disposition */
+    disposition?: 'inline' | 'attachment';
+
+    /** Content ID for inline attachments */
+    contentId?: string;
+  }>;
+}
+
+/**
+ * Email Send Result
+ */
+export interface EmailSendResult {
+  /** SendGrid message ID */
+  messageId: string;
+
+  /** Send status */
+  status: 'success' | 'failed' | 'bounced' | 'spam' | 'blocked';
+
+  /** Recipient email */
+  to: string;
+
+  /** Subject line */
+  subject: string;
+
+  /** Timestamp of send */
+  timestamp: Date;
+
+  /** Error details if failed */
+  error?: {
+    code: number;
+    message: string;
+  };
+}
+
+/**
+ * Email Contact
+ */
+export interface EmailContact {
+  /** Contact ID */
+  id: string;
+
+  /** Email address */
+  email: string;
+
+  /** First name */
+  firstName?: string;
+
+  /** Last name */
+  lastName?: string;
+
+  /** Phone number */
+  phone?: string;
+
+  /** Company */
+  company?: string;
+
+  /** Custom fields */
+  customFields?: Record<string, string>;
+
+  /** Date added */
+  createdAt: Date;
+
+  /** Unsubscribed status */
+  isUnsubscribed?: boolean;
+}
+
+/**
+ * Email Contact List
+ */
+export interface EmailContactList {
+  /** List ID */
+  id: string;
+
+  /** List name */
+  name: string;
+
+  /** Contact count */
+  contactCount: number;
+
+  /** Date created */
+  createdAt: Date;
+
+  /** Date modified */
+  modifiedAt: Date;
+}
+
+/**
+ * Email Service Methods
+ */
+export interface EmailService {
+  /**
+   * Send email
+   * @param to Recipient email address
+   * @param subject Email subject
+   * @param html HTML content
+   * @param text Plain text content
+   * @param options Optional email options
+   * @returns Send result
+   */
+  send(
+    to: string,
+    subject: string,
+    html: string,
+    text?: string,
+    options?: EmailOptions
+  ): Promise<EmailSendResult>;
+
+  /**
+   * Send email from template
+   * @param to Recipient email address
+   * @param subject Email subject
+   * @param templateId SendGrid template ID
+   * @param dynamicData Template variable data
+   * @param options Optional email options
+   * @returns Send result
+   */
+  sendTemplate(
+    to: string,
+    subject: string,
+    templateId: string,
+    dynamicData: Record<string, any>,
+    options?: EmailOptions
+  ): Promise<EmailSendResult>;
+
+  /**
+   * Send email with attachments
+   * @param to Recipient email address
+   * @param subject Email subject
+   * @param html HTML content
+   * @param attachments Array of attachments
+   * @param options Optional email options
+   * @returns Send result
+   */
+  sendWithAttachments(
+    to: string,
+    subject: string,
+    html: string,
+    attachments: Array<{ content: string; filename: string; type: string }>,
+    options?: EmailOptions
+  ): Promise<EmailSendResult>;
+
+  /**
+   * Send bulk email to multiple recipients
+   * @param to Array of recipient emails
+   * @param subject Email subject
+   * @param html HTML content
+   * @param options Optional email options
+   * @returns Array of send results
+   */
+  sendBulk(
+    to: string[],
+    subject: string,
+    html: string,
+    options?: EmailOptions
+  ): Promise<EmailSendResult[]>;
+
+  /**
+   * Send personalized bulk email
+   * @param messages Array of personalized messages
+   * @returns Array of send results
+   */
+  sendPersonalizedBulk(
+    messages: Array<{
+      to: string;
+      subject: string;
+      html: string;
+      personalData?: Record<string, string>;
+    }>
+  ): Promise<EmailSendResult[]>;
+
+  /**
+   * Validate email address
+   * @param email Email to validate
+   * @returns Validation result
+   */
+  validate(
+    email: string
+  ): Promise<{ isValid: boolean; suggestion?: string; error?: string }>;
+
+  /**
+   * Add contact to SendGrid
+   * @param email Contact email
+   * @param data Contact data
+   * @param listIds Optional list IDs
+   * @returns Contact info
+   */
+  addContact(
+    email: string,
+    data: Record<string, string>,
+    listIds?: string[]
+  ): Promise<EmailContact>;
+
+  /**
+   * Search for contact
+   * @param email Contact email
+   * @returns Contact info or null
+   */
+  searchContact(email: string): Promise<EmailContact | null>;
+
+  /**
+   * Delete contact
+   * @param contactId Contact ID
+   * @returns Deletion result
+   */
+  deleteContact(contactId: string): Promise<{ success: boolean }>;
+
+  /**
+   * Create contact list
+   * @param name List name
+   * @returns List info
+   */
+  createList(name: string): Promise<EmailContactList>;
+
+  /**
+   * Get all contact lists
+   * @returns Array of lists
+   */
+  getLists(): Promise<EmailContactList[]>;
+
+  /**
+   * Delete contact list
+   * @param listId List ID
+   * @returns Deletion result
+   */
+  deleteList(listId: string): Promise<{ success: boolean }>;
+}
+
+/**
+ * Plugin Configuration Options
+ */
+export interface XEmailPluginOptions {
+  /** SendGrid API Key */
+  apiKey: string;
+
+  /** From email address */
+  fromEmail: string;
+
+  /** From name */
+  fromName?: string;
+
+  /** Enable SendGrid service */
+  active?: boolean;
+}
+
+/**
+ * Fastify Instance with xEmail Decoration
+ */
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** Email service methods */
+    email: EmailService;
+  }
+}
+
+/**
+ * xEmail Plugin
+ * Registers SendGrid Email service with Fastify
+ *
+ * @example
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import xEmail from '@xenterprises/fastify-xemail';
+ *
+ * const fastify = Fastify();
+ *
+ * await fastify.register(xEmail, {
+ *   apiKey: process.env.SENDGRID_API_KEY,
+ *   fromEmail: process.env.SENDGRID_FROM_EMAIL,
+ * });
+ *
+ * // Send email
+ * await fastify.email.send('user@example.com', 'Welcome', '<h1>Hello</h1>');
+ * ```
+ */
+declare const xEmail: FastifyPluginAsync<XEmailPluginOptions>;
+
+export default xEmail;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xenterprises/fastify-xemail",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for SendGrid email integration.",
+  "main": "src/xEmail.js",
+  "exports": {
+    ".": "./src/xEmail.js"
+  },
+  "scripts": {
+    "test": "node --test test/xEmail.test.js"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "keywords": [
+    "fastify",
+    "sendgrid",
+    "email",
+    "plugin"
+  ],
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "fastify": "^5.1.0",
+    "fastify-plugin": "^5.0.0"
+  },
+  "dependencies": {
+    "@sendgrid/client": "^8.1.3",
+    "@sendgrid/mail": "^8.1.3",
+    "fastify-plugin": "^5.0.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}

package/src/xEmail.js

@@ -0,0 +1,368 @@
+import fp from "fastify-plugin";
+import sgMail from "@sendgrid/mail";
+import sgClient from "@sendgrid/client";
+
+async function xEmail(fastify, options) {
+  const { active = true, apiKey, fromEmail } = options;
+
+  if (active === false) return;
+
+  // Validate required credentials
+  if (!apiKey) {
+    throw new Error("SendGrid apiKey must be provided for Email service.");
+  }
+
+  if (!fromEmail) {
+    throw new Error("fromEmail must be provided for Email service.");
+  }
+
+  // Initialize SendGrid clients
+  sgMail.setApiKey(apiKey);
+  sgClient.setApiKey(apiKey);
+
+  console.info("\n 📧 Email Service (SendGrid) Initialized\n");
+
+  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: 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: 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: 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: 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: 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.");
+      }
+    },
+  });
+}
+
+export default fp(xEmail, {
+  name: "xEmail",
+});