@xenterprises/fastify-xemail 1.0.2 → 1.1.1

package/LICENSE

@@ -0,0 +1,100 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 X Enterprises LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of X Enterprises LLC, a Washington limited liability
+company ("X Enterprises"). The Software is distributed through public
+package registries (including npm) for operational convenience only; such
+distribution does not grant any rights beyond those expressly stated below.
+
+TERMS AND CONDITIONS
+
+1. OWNERSHIP
+   All rights, title, and interest in and to the Software, including all
+   intellectual property rights, are and shall remain the exclusive property
+   of X Enterprises. No rights are granted except as expressly set forth in
+   this License.
+
+2. PERMITTED USE
+   Subject to the restrictions in Section 3, you are permitted to download,
+   install, and execute the Software solely as a dependency of:
+
+   (a) software developed, owned, or operated by X Enterprises;
+
+   (b) software that X Enterprises has developed, delivered, or licensed to
+       a third party ("Client") under a written engagement agreement with
+       X Enterprises, when such use is performed by or on behalf of that
+       Client; or
+
+   (c) end-user access to, or consumption of, a product or service described
+       in (a) or (b), provided that such access does not involve
+       redistribution, modification, or separate use of the Software.
+
+   Permitted Use includes automated installation and execution by continuous
+   integration systems, container builds, hosting platforms, and similar
+   infrastructure, to the extent necessary to support (a), (b), or (c).
+
+3. RESTRICTIONS
+   Except as expressly permitted in Section 2, and without the prior written
+   consent of X Enterprises, you may not:
+
+   (a) copy, modify, adapt, translate, or create derivative works of the
+       Software for any purpose outside the scope of Section 2;
+
+   (b) redistribute, republish, sublicense, sell, lease, rent, or otherwise
+       transfer the Software, in whole or in part, whether standalone or
+       bundled with other software;
+
+   (c) reverse engineer, decompile, disassemble, or attempt to derive the
+       source code or underlying ideas, algorithms, structure, or
+       organization of the Software, except to the extent such activity is
+       expressly permitted by applicable law notwithstanding this
+       restriction;
+
+   (d) use the Software, in whole or in part, to develop, operate, or
+       provide any product or service that competes with or substitutes for
+       any X Enterprises product or service;
+
+   (e) remove, obscure, or alter any copyright, trademark, license, or other
+       proprietary notice contained in or on the Software; or
+
+   (f) use the Software in violation of any applicable law or regulation.
+
+4. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   X ENTERPRISES BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT
+   OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+   THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL X ENTERPRISES BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. GOVERNING LAW
+   This License shall be governed by and construed in accordance with the
+   laws of the State of Washington, United States, without regard to its
+   conflict of law provisions. Exclusive jurisdiction for any dispute
+   arising out of this License shall lie in the state or federal courts
+   located in King County, Washington.
+
+7. TERMINATION
+   This License is effective until terminated. Your rights under this
+   License will terminate automatically and without notice if you fail to
+   comply with any term herein. Upon termination, you must cease all use of
+   the Software and destroy all copies in your possession or control.
+   Sections 1, 3, 4, 5, 6, and 7 survive termination.
+
+For licensing inquiries, contact: legal@x.enterprises
+
+---
+X Enterprises LLC
+Bothell, Washington, United States

package/README.md

@@ -1,16 +1,6 @@
 # @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
+Fastify plugin for SendGrid email — send transactional emails, template emails, bulk messages, validate addresses, and manage marketing contacts and lists.
 
 ## Installation
 
@@ -28,38 +18,180 @@ const fastify = Fastify();
 
 await fastify.register(xEmail, {
   apiKey: process.env.SENDGRID_API_KEY,
-  fromEmail: 'noreply@yourdomain.com'
+  fromEmail: process.env.SENDGRID_FROM_EMAIL,
+  fromName: 'My App', // optional
 });
 
-// Usage example
-fastify.get('/send-welcome', async (request, reply) => {
-  const { email, name } = request.query;
-  
-  await fastify.xEmail.send(
-    email,
-    'Welcome!',
-    `<h1>Welcome ${name}!</h1>`,
-    `Welcome ${name}!`
-  );
-  
-  return { success: true };
-});
+// Send a simple email
+await fastify.xEmail.send(
+  'user@example.com',
+  'Welcome!',
+  '<h1>Welcome!</h1><p>Thanks for signing up.</p>'
+);
+```
+
+## Options
+
+| Name | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `apiKey` | `string` | — | Yes | SendGrid API key |
+| `fromEmail` | `string` | — | Yes | Verified sender email address |
+| `fromName` | `string` | — | No | Sender display name |
+| `active` | `boolean` | `true` | No | Set `false` to disable the plugin entirely |
+
+## Decorated Methods
+
+All methods are available on `fastify.xEmail`.
+
+### `send(to, subject, html, text?, extraOptions?)`
+
+Send an email. Plain text is auto-generated from HTML if omitted.
+
+```javascript
+const result = await fastify.xEmail.send('user@example.com', 'Hello', '<p>Hi</p>');
+// { success: true, statusCode: 202, messageId: 'xxx' }
+```
+
+### `sendTemplate(to, subject, templateId, dynamicData?, extraOptions?)`
+
+Send using a SendGrid dynamic template.
+
+```javascript
+await fastify.xEmail.sendTemplate(
+  'user@example.com',
+  'Welcome',
+  'd-abc123def456',
+  { firstName: 'Tim', actionUrl: 'https://example.com/verify' }
+);
+```
+
+### `sendWithAttachments(to, subject, html, attachments)`
+
+Send an email with file attachments. Each attachment needs `content` (base64), `filename`, and `type` (MIME).
+
+```javascript
+await fastify.xEmail.sendWithAttachments(
+  'user@example.com',
+  'Your Invoice',
+  '<p>See attached.</p>',
+  [{ content: base64String, filename: 'invoice.pdf', type: 'application/pdf' }]
+);
+```
+
+### `sendBulk(to, subject, html)`
+
+Send the same email to multiple recipients at once.
+
+```javascript
+await fastify.xEmail.sendBulk(
+  ['a@example.com', 'b@example.com'],
+  'Announcement',
+  '<p>Big news!</p>'
+);
+// { success: true, count: 2, statusCode: 202 }
+```
+
+### `sendPersonalizedBulk(messages)`
+
+Send different content to each recipient. Returns per-recipient results including partial failures.
+
+```javascript
+const results = await fastify.xEmail.sendPersonalizedBulk([
+  { to: 'a@example.com', subject: 'Hi A', html: '<p>Hello A</p>' },
+  { to: 'b@example.com', subject: 'Hi B', html: '<p>Hello B</p>' },
+]);
+// [{ success: true, to: 'a@example.com', statusCode: 202 }, ...]
 ```
 
-## API
+### `validate(email)`
+
+Validate an email address using the SendGrid Email Validation API. Returns a soft result on API errors instead of throwing.
+
+```javascript
+const result = await fastify.xEmail.validate('user@example.com');
+// { email: '...', valid: true, verdict: 'Valid', score: 0.95, result: {...} }
+```
+
+### `addContact(email, data?, listIds?)`
+
+Add or update a contact in SendGrid Marketing. Accepts both `firstName`/`lastName` and `first_name`/`last_name`.
+
+```javascript
+await fastify.xEmail.addContact('user@example.com', {
+  firstName: 'Tim',
+  lastName: 'Smith',
+  customFields: { w1_T: 'premium' }
+}, ['list-id-1']);
+// { success: true, jobId: '...', email: '...' }
+```
+
+### `searchContact(email)`
+
+Search for a contact by email.
+
+```javascript
+const result = await fastify.xEmail.searchContact('user@example.com');
+// { found: true, contact: { id: '...', email: '...', ... } }
+```
+
+### `deleteContact(contactId)`
+
+Delete a contact by ID. Returns `true` on success.
+
+### `createList(name)`
+
+Create a new marketing contact list.
+
+```javascript
+const result = await fastify.xEmail.createList('Newsletter');
+// { success: true, list: { id: '...', name: 'Newsletter' } }
+```
+
+### `getLists()`
+
+Get all contact lists. Returns an array.
+
+### `deleteList(listId)`
+
+Delete a contact list by ID. Returns `true` on success.
+
+## Environment Variables
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `SENDGRID_API_KEY` | Yes | SendGrid API key with Mail Send permissions |
+| `SENDGRID_FROM_EMAIL` | Yes | Verified sender email address |
+| `SENDGRID_FROM_NAME` | No | Sender display name |
+
+## Error Reference
+
+All errors are prefixed with `[xEmail]` for easy identification in logs.
+
+| Error | When |
+|-------|------|
+| `[xEmail] 'apiKey' (string) is required.` | Missing or non-string `apiKey` at registration |
+| `[xEmail] 'fromEmail' (string) is required.` | Missing or non-string `fromEmail` at registration |
+| `[xEmail] 'to' is required for send().` | Calling `send()` without a recipient |
+| `[xEmail] 'subject' is required for send().` | Calling `send()` without a subject |
+| `[xEmail] 'html' is required for send().` | Calling `send()` without HTML content |
+| `[xEmail] 'templateId' is required for sendTemplate().` | Missing template ID |
+| `[xEmail] 'attachments' must be a non-empty array.` | Empty or non-array attachments |
+| `[xEmail] 'to' must be a non-empty array for sendBulk().` | Non-array or empty array for bulk |
+| `[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk().` | Empty messages array |
+| `[xEmail] 'email' (string) is required for validate().` | Missing email for validation |
+| `[xEmail] Failed to send email: <reason>` | SendGrid API rejection on send |
+| `[xEmail] Failed to add contact: <reason>` | SendGrid API rejection on contact add |
+
+## How It Works
 
-### `fastify.xEmail.send(to, subject, html, text, extraOptions)`
-Send a single email.
+The plugin initializes both `@sendgrid/mail` (for transactional emails) and `@sendgrid/client` (for the Marketing and Validation APIs) with the provided API key. It decorates the Fastify instance with `fastify.xEmail`, an object containing all email and contact management methods.
 
-### `fastify.xEmail.sendTemplate(to, subject, templateId, dynamicData, extraOptions)`
-Send an email using a SendGrid dynamic template.
+Each method validates its required parameters before making any API call. Transactional methods (`send`, `sendTemplate`, `sendWithAttachments`, `sendBulk`) use `sgMail`, while marketing and validation methods (`validate`, `addContact`, `searchContact`, `deleteContact`, `createList`, `getLists`, `deleteList`) use `sgClient` with direct REST calls.
 
-### `fastify.xEmail.sendWithAttachments(to, subject, html, attachments)`
-Send an email with attachments.
+Errors from SendGrid are caught, logged via `fastify.log.error` (with structured error objects, never credentials), and re-thrown with a descriptive `[xEmail]` prefix. The `validate()` method is an exception — it returns a soft error result instead of throwing, since validation failures are expected in normal operation.
 
-### `fastify.xEmail.validate(email)`
-Validate an email address using SendGrid's Validation API.
+Setting `active: false` causes the plugin to return immediately without decorating, which is useful for disabling email in test environments.
 
 ## License
 
-ISC
+UNLICENSED

package/index.d.ts

@@ -1,325 +1,133 @@
 /**
  * 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 */
+/** Additional SendGrid mail options passed through to the API. */
+export interface EmailExtraOptions {
   replyTo?: string;
-
-  /** BCC recipients */
-  bcc?: string[];
-
-  /** Custom categories for tracking */
+  bcc?: string | string[];
+  cc?: string | string[];
   categories?: string[];
-
-  /** Custom metadata */
-  metadata?: Record<string, string>;
+  headers?: Record<string, string>;
+  [key: string]: unknown;
 }
 
-/**
- * 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;
-  }>;
+/** Attachment object for sendWithAttachments(). */
+export interface EmailAttachment {
+  /** Base64-encoded file content */
+  content: string;
+  /** File name */
+  filename: string;
+  /** MIME type (e.g. 'application/pdf') */
+  type: string;
+  /** Content disposition: 'attachment' (default) or 'inline' */
+  disposition?: 'inline' | 'attachment';
 }
 
-/**
- * Email Send Result
- */
+/** Result from send(), sendTemplate(), sendWithAttachments(). */
 export interface EmailSendResult {
-  /** SendGrid message ID */
+  success: boolean;
+  statusCode: number;
   messageId: string;
+}
 
-  /** Send status */
-  status: 'success' | 'failed' | 'bounced' | 'spam' | 'blocked';
+/** Result from sendBulk(). */
+export interface EmailBulkResult {
+  success: boolean;
+  count: number;
+  statusCode: number;
+}
 
-  /** Recipient email */
+/** Per-recipient result from sendPersonalizedBulk(). */
+export interface EmailPersonalizedResult {
+  success: boolean;
   to: string;
+  statusCode?: number;
+  error?: string;
+}
 
-  /** Subject line */
-  subject: string;
-
-  /** Timestamp of send */
-  timestamp: Date;
+/** Result from validate(). */
+export interface EmailValidationResult {
+  email: string;
+  valid: boolean;
+  verdict: string;
+  score?: number;
+  result?: Record<string, unknown>;
+  error?: string;
+}
 
-  /** Error details if failed */
-  error?: {
-    code: number;
-    message: string;
-  };
+/** Result from addContact(). */
+export interface EmailAddContactResult {
+  success: boolean;
+  jobId: string;
+  email: string;
 }
 
-/**
- * Email Contact
- */
-export interface EmailContact {
-  /** Contact ID */
-  id: string;
+/** Result from searchContact(). */
+export interface EmailSearchContactResult {
+  found: boolean;
+  contact?: Record<string, unknown>;
+}
 
-  /** Email address */
-  email: string;
+/** Result from createList(). */
+export interface EmailCreateListResult {
+  success: boolean;
+  list: Record<string, unknown>;
+}
 
-  /** First name */
+/** Contact data for addContact(). */
+export interface ContactData {
   firstName?: string;
-
-  /** Last name */
+  first_name?: string;
   lastName?: string;
-
-  /** Phone number */
-  phone?: string;
-
-  /** Company */
-  company?: string;
-
-  /** Custom fields */
+  last_name?: string;
   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;
+/** Message object for sendPersonalizedBulk(). */
+export interface PersonalizedMessage {
+  to: string;
+  subject: string;
+  html: string;
+  text?: string;
 }
 
-/**
- * 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 }>;
+/** All methods decorated onto fastify.xEmail. */
+export interface XEmailService {
+  send(to: string | string[], subject: string, html: string, text?: string | null, extraOptions?: EmailExtraOptions): Promise<EmailSendResult>;
+  sendTemplate(to: string | string[], subject: string, templateId: string, dynamicData?: Record<string, unknown>, extraOptions?: EmailExtraOptions): Promise<EmailSendResult>;
+  sendWithAttachments(to: string | string[], subject: string, html: string, attachments: EmailAttachment[]): Promise<EmailSendResult>;
+  sendBulk(to: string[], subject: string, html: string): Promise<EmailBulkResult>;
+  sendPersonalizedBulk(messages: PersonalizedMessage[]): Promise<EmailPersonalizedResult[]>;
+  validate(email: string): Promise<EmailValidationResult>;
+  addContact(email: string, data?: ContactData, listIds?: string[]): Promise<EmailAddContactResult>;
+  searchContact(email: string): Promise<EmailSearchContactResult>;
+  deleteContact(contactId: string): Promise<boolean>;
+  createList(name: string): Promise<EmailCreateListResult>;
+  getLists(): Promise<Record<string, unknown>[]>;
+  deleteList(listId: string): Promise<boolean>;
 }
 
-/**
- * Plugin Configuration Options
- */
+/** Plugin configuration options. */
 export interface XEmailPluginOptions {
-  /** SendGrid API Key */
+  /** SendGrid API key (required) */
   apiKey: string;
-
-  /** From email address */
+  /** Verified sender email address (required) */
   fromEmail: string;
-
-  /** From name */
+  /** Sender display name (optional) */
   fromName?: string;
-
-  /** Enable SendGrid service */
+  /** Set to false to disable the plugin (default: true) */
   active?: boolean;
 }
 
-/**
- * Fastify Instance with xEmail Decoration
- */
 declare module 'fastify' {
   interface FastifyInstance {
-    /** Email service methods */
-    xEmail: EmailService;
+    xEmail: XEmailService;
   }
 }
 
-/**
- * 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.xEmail.send('user@example.com', 'Welcome', '<h1>Hello</h1>');
- * ```
- */
 declare const xEmail: FastifyPluginAsync<XEmailPluginOptions>;
-
 export default xEmail;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@xenterprises/fastify-xemail",
   "type": "module",
-  "version": "1.0.2",
-  "description": "Fastify plugin for SendGrid email integration.",
+  "version": "1.1.1",
+  "description": "Fastify plugin for SendGrid email integration — transactional emails, templates, bulk sending, validation, and contact management.",
   "main": "src/xEmail.js",
   "exports": {
     ".": "./src/xEmail.js"
@@ -21,11 +21,10 @@
     "plugin"
   ],
   "author": "Tim Mushen",
-  "license": "ISC",
+  "license": "SEE LICENSE IN LICENSE",
   "devDependencies": {
     "@types/node": "^22.7.4",
-    "fastify": "^5.1.0",
-    "fastify-plugin": "^5.0.0"
+    "fastify": "^5.1.0"
   },
   "dependencies": {
     "@sendgrid/client": "^8.1.3",
@@ -34,5 +33,8 @@
   },
   "peerDependencies": {
     "fastify": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/xEmail.js

@@ -2,69 +2,89 @@ import fp from "fastify-plugin";
 import sgMail from "@sendgrid/mail";
 import sgClient from "@sendgrid/client";
 
+/**
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} options
+ * @param {string} options.apiKey - SendGrid API key
+ * @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 } = options;
+  const { active = true, apiKey, fromEmail, fromName } = options;
 
   if (active === false) return;
 
-  // Validate required credentials
-  if (!apiKey) {
-    throw new Error("SendGrid apiKey must be provided for Email service.");
+  if (!apiKey || typeof apiKey !== "string") {
+    throw new Error("[xEmail] 'apiKey' (string) is required.");
   }
 
-  if (!fromEmail) {
-    throw new Error("fromEmail must be provided for Email service.");
+  if (!fromEmail || typeof fromEmail !== "string") {
+    throw new Error("[xEmail] 'fromEmail' (string) is required.");
   }
 
-  // Initialize SendGrid clients
   sgMail.setApiKey(apiKey);
   sgClient.setApiKey(apiKey);
 
-  console.info("\n 📧 Email Service (SendGrid) Initialized\n");
+  const from = fromName ? { email: fromEmail, name: fromName } : fromEmail;
+
+  fastify.log.info("xEmail (SendGrid) initialized");
 
   fastify.decorate("xEmail", {
     /**
-     * Send an 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
+     * @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: fromEmail,
+          from,
           subject,
           html,
-          text: text || html.replace(/<[^>]*>/g, ""), // Strip HTML tags if no text provided
+          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"] };
+        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.");
+        fastify.log.error({ err: error }, "xEmail send failed");
+        throw new Error(`[xEmail] Failed to send email: ${error.message}`);
       }
     },
 
     /**
-     * Send an email using a template
+     * Send an email using a SendGrid dynamic 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
+     * @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: fromEmail,
+          from,
           subject,
           templateId,
           dynamicTemplateData: { ...dynamicData, subject },
@@ -72,30 +92,41 @@ async function xEmail(fastify, options) {
         };
 
         const response = await sgMail.send(msg);
-        return { success: true, statusCode: response[0].statusCode, messageId: response[0].headers["x-message-id"] };
+        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.");
+        fastify.log.error({ err: error }, "xEmail sendTemplate failed");
+        throw new Error(`[xEmail] Failed to send template email: ${error.message}`);
       }
     },
 
     /**
-     * Send an email with attachments
+     * 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}>} attachments - Attachments
-     * @returns {Promise<object>} Send result
+     * @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: fromEmail,
+          from,
           subject,
           html,
           attachments: attachments.map((att) => ({
-            content: att.content, // Base64 encoded
+            content: att.content,
             filename: att.filename,
             type: att.type,
             disposition: att.disposition || "attachment",
@@ -103,89 +134,93 @@ async function xEmail(fastify, options) {
         };
 
         const response = await sgMail.send(msg);
-        return { success: true, statusCode: response[0].statusCode };
+        return {
+          success: true,
+          statusCode: response[0].statusCode,
+          messageId: response[0].headers["x-message-id"],
+        };
       } catch (error) {
-        fastify.log.error("Email sendWithAttachments failed:", error);
-        throw new Error("Failed to send email with attachments.");
+        fastify.log.error({ err: error }, "xEmail sendWithAttachments failed");
+        throw new Error(`[xEmail] Failed to send email with attachments: ${error.message}`);
       }
     },
 
     /**
-     * Send bulk emails (multiple recipients, same content)
+     * 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<object>} Bulk send result
+     * @returns {Promise<{success: boolean, count: number, statusCode: number}>}
      */
     sendBulk: async (to, subject, html) => {
-      try {
-        const msg = {
-          to,
-          from: fromEmail,
-          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("Email sendBulk failed:", error);
-        throw new Error("Failed to send bulk emails.");
+        fastify.log.error({ err: error }, "xEmail sendBulk failed");
+        throw new Error(`[xEmail] Failed to send bulk emails: ${error.message}`);
       }
     },
 
     /**
-     * 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
+     * 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) => {
-      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.");
+      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 Validation API
+     * Validate an email address using SendGrid Email Validation API.
      * @param {string} email - Email to validate
-     * @returns {Promise<object>} Validation result
+     * @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 request = {
+        const [response, body] = await sgClient.request({
           url: `/v3/validations/email`,
           method: "POST",
           body: { email },
-        };
-
-        const [response, body] = await sgClient.request(request);
+        });
 
         if (response.statusCode === 200) {
           return {
@@ -195,11 +230,11 @@ async function xEmail(fastify, options) {
             score: body.result?.score,
             result: body.result,
           };
-        } else {
-          throw new Error(body.errors ? body.errors.map((err) => err.message).join(", ") : "Validation failed");
         }
+
+        throw new Error(body.errors ? body.errors.map((e) => e.message).join(", ") : "Validation failed");
       } catch (error) {
-        fastify.log.error("Email validation failed:", error);
+        fastify.log.error({ err: error }, "xEmail validate failed");
         return {
           email,
           valid: false,
@@ -210,15 +245,19 @@ async function xEmail(fastify, options) {
     },
 
     /**
-     * Add or update a contact in SendGrid
+     * Add or update a contact in SendGrid Marketing.
      * @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
+     * @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 request = {
+        const [response, body] = await sgClient.request({
           url: `/v3/marketing/contacts`,
           method: "PUT",
           body: {
@@ -232,132 +271,129 @@ async function xEmail(fastify, options) {
               },
             ],
           },
-        };
-
-        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");
+          return { success: true, jobId: body.job_id, email };
         }
+
+        throw new Error("Unexpected status code: " + response.statusCode);
       } catch (error) {
-        fastify.log.error("Email addContact failed:", error);
-        throw new Error("Failed to add contact.");
+        fastify.log.error({ err: error }, "xEmail addContact failed");
+        throw new Error(`[xEmail] Failed to add contact: ${error.message}`);
       }
     },
 
     /**
-     * Search for a contact by email
+     * Search for a contact by email.
      * @param {string} email - Contact email
-     * @returns {Promise<object>} Contact data
+     * @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 request = {
+        const [response, body] = await sgClient.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 };
+        if (response.statusCode === 200 && body.result?.[email]) {
+          return { found: true, contact: body.result[email].contact };
         }
+
+        return { found: false };
       } catch (error) {
-        fastify.log.error("Email searchContact failed:", error);
-        throw new Error("Failed to search contact.");
+        fastify.log.error({ err: error }, "xEmail searchContact failed");
+        throw new Error(`[xEmail] Failed to search contact: ${error.message}`);
       }
     },
 
     /**
-     * Delete a contact by ID
+     * Delete a contact by ID.
      * @param {string} contactId - Contact ID
-     * @returns {Promise<boolean>} Success status
+     * @returns {Promise<boolean>}
      */
     deleteContact: async (contactId) => {
+      if (!contactId || typeof contactId !== "string") {
+        throw new Error("[xEmail] 'contactId' (string) is required for deleteContact().");
+      }
+
       try {
-        const request = {
+        const [response] = await sgClient.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.");
+        fastify.log.error({ err: error }, "xEmail deleteContact failed");
+        throw new Error(`[xEmail] Failed to delete contact: ${error.message}`);
       }
     },
 
     /**
-     * Create a new contact list
+     * Create a new contact list.
      * @param {string} name - List name
-     * @returns {Promise<object>} List object
+     * @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 request = {
+        const [, body] = await sgClient.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.");
+        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[]>} Array of lists
+     * Get all contact lists.
+     * @returns {Promise<object[]>}
      */
     getLists: async () => {
       try {
-        const request = {
+        const [, body] = await sgClient.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.");
+        fastify.log.error({ err: error }, "xEmail getLists failed");
+        throw new Error(`[xEmail] Failed to get lists: ${error.message}`);
       }
     },
 
     /**
-     * Delete a contact list
+     * Delete a contact list.
      * @param {string} listId - List ID
-     * @returns {Promise<boolean>} Success status
+     * @returns {Promise<boolean>}
      */
     deleteList: async (listId) => {
+      if (!listId || typeof listId !== "string") {
+        throw new Error("[xEmail] 'listId' (string) is required for deleteList().");
+      }
+
       try {
-        const request = {
+        const [response] = await sgClient.request({
           url: `/v3/marketing/lists/${listId}`,
           method: "DELETE",
-        };
-
-        const [response] = await sgClient.request(request);
-        return response.statusCode === 202 || response.statusCode === 200 || response.statusCode === 204;
+        });
+        return [200, 202, 204].includes(response.statusCode);
       } catch (error) {
-        fastify.log.error("Email deleteList failed:", error);
-        throw new Error("Failed to delete list.");
+        fastify.log.error({ err: error }, "xEmail deleteList failed");
+        throw new Error(`[xEmail] Failed to delete list: ${error.message}`);
       }
     },
   });
@@ -365,4 +401,5 @@ async function xEmail(fastify, options) {
 
 export default fp(xEmail, {
   name: "xEmail",
+  fastify: ">=5.0.0",
 });