@xenterprises/fastify-xemail 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to `@xenterprises/fastify-xemail` are documented here.
+
+## Unreleased
+
+## [1.3.0] - 2026-09-07
+
+### Added
+
+- **Postmark provider** (`provider: 'postmark'`): `send`, `sendTemplate`,
+  `sendWithAttachments`, `sendBulk`, and `sendPersonalizedBulk` are backed by the
+  Postmark API (via the `postmark` package). Postmark is the migration target;
+  SendGrid is now legacy. The default remains `'sendgrid'`, so existing
+  registrations are unchanged.
+- New `provider` registration option (`'sendgrid' | 'postmark'`), validated
+  fail-fast at registration.
+- `messageStream` extra option for Postmark message streams.
+- `test/xEmail.postmark.test.js` — Postmark tests mocking
+  `postmark.ServerClient.prototype` with `mock.method()`, fully offline.
+
+### Changed
+
+- The plugin internals are split into provider modules:
+  `src/providers/sendgrid.js` (existing implementation, unchanged behavior) and
+  `src/providers/postmark.js` (new). `src/xEmail.js` now only validates options
+  and selects the provider.
+- Under `provider: 'postmark'`, the SendGrid-only methods (`validate`,
+  `addContact`, `searchContact`, `deleteContact`, `createList`, `getLists`,
+  `deleteList`) are still present on the decorator but throw
+  `[xEmail] '<method>()' is not supported by provider 'postmark'.`
+
+## [1.2.0] - 2026-07-27
+
+### Breaking changes
+
+- **Registration error messages changed format.** Missing/invalid `apiKey` and
+  `fromEmail` now throw `xemail: option \`<name>\` must be a string, e.g.
+  \`app.register(xEmail, { ... })\`` instead of `[xEmail] '<name>' (string) is required.`
+  (Suite-wide error-format standard; code matching on the old message text must be updated.)
+- **`fp()` metadata changed**: plugin name is now `xemail` (was `xEmail`) and the
+  Fastify constraint is `5.x` (was `>=5.0.0`). Affects duplicate-registration
+  detection and `fastify-plugin` metadata only.
+
+### Added
+
+- TypeScript declarations are now reachable by consumers: `package.json` gains a
+  top-level `"types": "./index.d.ts"` and a `types` condition in `exports["."]`.
+  Declaration content is unchanged.
+- New fail-fast validation: `fromName` must be a string when provided and `active`
+  must be a boolean when provided.
+- Tests asserting the plugin is env-independent (no `process.env` reads; options
+  are the only configuration source).
+
+### Changed
+
+- Tooling migrated to Biome 2.5.5 (`lint`/`format` scripts); test script now uses
+  the `test/**/*.test.js` glob.
+- README rewritten to the suite README contract; `docs/INTEGRATION.md` examples
+  corrected to use the `fastify.xEmail` decorator.
+- Dependency updates via `npm audit fix` — 0 known vulnerabilities.

package/README.md

@@ -1,14 +1,22 @@
 # @xenterprises/fastify-xemail
 
-Fastify plugin for SendGrid email — send transactional emails, template emails, bulk messages, validate addresses, and manage marketing contacts and lists.
+Fastify 5 plugin for email via **Postmark** or **SendGrid** (legacy) — send transactional, template, attachment, and bulk emails through one `fastify.xEmail` decorator. SendGrid additionally supports address validation and Marketing contacts/lists. For Fastify apps that need email with the least possible wiring.
 
-## Installation
+> **Migration note:** SendGrid support is legacy. New integrations should use
+> `provider: 'postmark'`; existing SendGrid registrations keep working unchanged.
+
+## Install
 
 ```bash
-npm install @xenterprises/fastify-xemail
+npm install @xenterprises/fastify-xemail fastify@5
 ```
 
-## Usage
+`fastify@^5.0.0` is a peer dependency.
+
+TypeScript declarations ship with the package — importing the plugin types the
+`fastify.xEmail` decorator automatically (`index.d.ts`).
+
+## Minimal example
 
 ```javascript
 import Fastify from 'fastify';
@@ -17,12 +25,11 @@ 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,
-  fromName: 'My App', // optional
+  provider: 'postmark', // or 'sendgrid' (legacy default)
+  apiKey: 'your-postmark-server-token',
+  fromEmail: 'noreply@example.com',
 });
 
-// Send a simple email
 await fastify.xEmail.send(
   'user@example.com',
   'Welcome!',
@@ -30,168 +37,137 @@ await fastify.xEmail.send(
 );
 ```
 
+The plugin reads **no environment variables**. All configuration arrives via the
+register options object; reading `process.env.POSTMARK_SERVER_TOKEN` and passing
+it in is the consumer's job.
+
+## Providers
+
+| Provider | Status | Sending methods | `validate`, contacts, lists |
+|----------|--------|-----------------|------------------------------|
+| `postmark` | Migration target | `send`, `sendTemplate`, `sendWithAttachments`, `sendBulk`, `sendPersonalizedBulk` | Throw "not supported by provider 'postmark'" |
+| `sendgrid` | Legacy (default) | All sending methods | Fully supported |
+
+Postmark's API has no equivalents for email validation or contact/list
+management, so those methods exist in the decorator under Postmark but throw
+`[xEmail] '<method>()' is not supported by provider 'postmark'.`
+
 ## Options
 
 | Name | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `apiKey` | `string` | — | Yes | SendGrid API key |
+| `provider` | `'sendgrid' \| 'postmark'` | `'sendgrid'` | No | Email provider. `sendgrid` is legacy; `postmark` is the migration target |
+| `apiKey` | `string` | — | Yes | SendGrid API key (needs Mail Send; Marketing APIs for contact/list methods) or Postmark server API token |
 | `fromEmail` | `string` | — | Yes | Verified sender email address |
 | `fromName` | `string` | — | No | Sender display name |
-| `active` | `boolean` | `true` | No | Set `false` to disable the plugin entirely |
+| `active` | `boolean` | `true` | No | Set `false` to disable the plugin entirely (no decorator is added) |
 
-## Decorated Methods
+Invalid options fail fast at registration with errors like:
 
-All methods are available on `fastify.xEmail`.
+```
+xemail: option `apiKey` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key' })`
+```
 
-### `send(to, subject, html, text?, extraOptions?)`
+## Decorators
 
-Send an email. Plain text is auto-generated from HTML if omitted.
+The plugin adds one decorator: `fastify.xEmail`. No request decorators.
 
-```javascript
-const result = await fastify.xEmail.send('user@example.com', 'Hello', '<p>Hi</p>');
-// { success: true, statusCode: 202, messageId: 'xxx' }
-```
+### `send(to, subject, html, text?, extraOptions?)`
 
-### `sendTemplate(to, subject, templateId, dynamicData?, extraOptions?)`
+Send an email. Plain text is auto-generated from the HTML if `text` is omitted.
+Under SendGrid, `extraOptions` is merged into the message (e.g. `replyTo`, `cc`,
+`categories`). Under Postmark, `extraOptions` accepts `replyTo`, `cc`, `bcc`,
+`headers`, and `messageStream` (mapped to Postmark's PascalCase fields).
+Returns `{ success, statusCode, messageId }` (Postmark reports a fixed
+`statusCode: 200` on success and throws on failure).
 
-Send using a SendGrid dynamic template.
+### `sendTemplate(to, subject, templateId, dynamicData?, extraOptions?)`
 
-```javascript
-await fastify.xEmail.sendTemplate(
-  'user@example.com',
-  'Welcome',
-  'd-abc123def456',
-  { firstName: 'Tim', actionUrl: 'https://example.com/verify' }
-);
-```
+Send using a provider template. SendGrid: `templateId` is the dynamic template
+ID (`d-xxx`) and `dynamicData` is sent as `dynamicTemplateData`. Postmark:
+`templateId` is a template alias (string) or numeric template ID and
+`dynamicData` becomes the `TemplateModel`. The subject is always included in the
+template data. Returns `{ success, statusCode, messageId }`.
 
 ### `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' }]
-);
-```
+Send an email with attachments. Each attachment needs `content` (base64), `filename`,
+and `type` (MIME type); `disposition` defaults to `'attachment'`. Returns
+`{ success, statusCode, messageId }`.
 
 ### `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 }
-```
+Send the same email to an array of recipients. SendGrid uses one
+`sgMail.sendMultiple` call; Postmark sends one email per recipient in chunks of
+500 concurrent requests. Returns `{ success, count, statusCode }`.
 
 ### `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 }, ...]
-```
-
-### `validate(email)`
+Send different content per recipient. `messages` is an array of
+`{ to, subject, html, text? }`. Never throws on individual failures — returns
+one result per recipient: `{ success: true, to, statusCode }` or
+`{ success: false, to, error }`. Postmark uses the batch endpoint (chunked at
+500 messages); a failure of the whole batch call marks that chunk's recipients
+as failed instead of throwing.
 
-Validate an email address using the SendGrid Email Validation API. Returns a soft result on API errors instead of throwing.
+### `validate(email)` — SendGrid only
 
-```javascript
-const result = await fastify.xEmail.validate('user@example.com');
-// { email: '...', valid: true, verdict: 'Valid', score: 0.95, result: {...} }
-```
+Validate an address via the SendGrid Email Validation API. Returns
+`{ email, valid, verdict, score, result }`. On API failure it returns a soft result
+`{ email, valid: false, verdict: 'Unknown', error }` instead of throwing.
+Throws under `provider: 'postmark'`.
 
-### `addContact(email, data?, listIds?)`
+### `addContact(email, data?, listIds?)` — SendGrid only
 
-Add or update a contact in SendGrid Marketing. Accepts both `firstName`/`lastName` and `first_name`/`last_name`.
+Add or update a SendGrid Marketing contact. `data` accepts `firstName`/`lastName`
+(or `first_name`/`last_name`) and `customFields` (spread into the contact);
+`listIds` is an array of list IDs. Returns `{ success, jobId, email }`.
 
-```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)` — SendGrid only
 
-### `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' } }
-```
+Search for a contact by email. Returns `{ found: true, contact }` or `{ found: false }`.
 
-### `getLists()`
+### `deleteContact(contactId)` — SendGrid only
 
-Get all contact lists. Returns an array.
+Delete a contact by ID. Returns `true` on success (HTTP 200/202), `false` otherwise.
 
-### `deleteList(listId)`
+### `createList(name)` — SendGrid only
 
-Delete a contact list by ID. Returns `true` on success.
+Create a marketing contact list. Returns `{ success, list }`.
 
-## Environment Variables
+### `getLists()` — SendGrid only
 
-| 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 |
+Get all contact lists. Returns an array (empty when none exist).
 
-## Error Reference
+### `deleteList(listId)` — SendGrid only
 
-All errors are prefixed with `[xEmail]` for easy identification in logs.
+Delete a list by ID. Returns `true` on success (HTTP 200/202/204), `false` otherwise.
 
-| 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 |
+## Routes
 
-## How It Works
+None. This plugin adds no routes.
 
-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.
+## Error behavior
 
-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.
+- **Registration** throws fail-fast `Error`s naming the plugin and the option, with a
+  registration example (see Options above).
+- **Method argument validation** throws synchronously-rejecting `Error`s prefixed with
+  `[xEmail]`, e.g. `[xEmail] 'to' is required for send().`
+- **SendGrid API failures** are logged via `fastify.log.error` (structured error, never
+  the API key) and re-thrown wrapped: `[xEmail] Failed to send email: <reason>`.
+  `validate()` is the exception — it returns a soft result instead of throwing, since
+  validation failures are expected in normal operation. Postmark failures are wrapped
+  the same way.
+- **SendGrid-only methods under Postmark** throw
+  `[xEmail] '<method>()' is not supported by provider 'postmark'.`
+- With `active: false` the plugin returns before registering anything, so
+  `fastify.xEmail` is `undefined`.
 
-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.
+## Requirements
 
-Setting `active: false` causes the plugin to return immediately without decorating, which is useful for disabling email in test environments.
+- Node.js >= 20
+- Fastify ^5.0.0 (peer dependency)
 
 ## License
 
-UNLICENSED
+Proprietary — All Rights Reserved, X Enterprises. See `LICENSE`.

package/index.d.ts

@@ -1,17 +1,19 @@
 /**
- * xEmail - Fastify Plugin for SendGrid Email
+ * xEmail - Fastify Plugin for Email (Postmark + SendGrid legacy)
  * @module @xenterprises/fastify-xemail
  */
 
 import { FastifyPluginAsync } from 'fastify';
 
-/** Additional SendGrid mail options passed through to the API. */
+/** Additional mail options passed through to the provider API. */
 export interface EmailExtraOptions {
   replyTo?: string;
   bcc?: string | string[];
   cc?: string | string[];
   categories?: string[];
   headers?: Record<string, string>;
+  /** Postmark message stream (e.g. 'outbound'); Postmark provider only */
+  messageStream?: string;
   [key: string]: unknown;
 }
 
@@ -98,22 +100,34 @@ export interface PersonalizedMessage {
 /** 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>;
+  sendTemplate(to: string | string[], subject: string, templateId: string | number, 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[]>;
+  /** SendGrid only — throws under provider 'postmark'. */
   validate(email: string): Promise<EmailValidationResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   addContact(email: string, data?: ContactData, listIds?: string[]): Promise<EmailAddContactResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   searchContact(email: string): Promise<EmailSearchContactResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   deleteContact(contactId: string): Promise<boolean>;
+  /** SendGrid only — throws under provider 'postmark'. */
   createList(name: string): Promise<EmailCreateListResult>;
+  /** SendGrid only — throws under provider 'postmark'. */
   getLists(): Promise<Record<string, unknown>[]>;
+  /** SendGrid only — throws under provider 'postmark'. */
   deleteList(listId: string): Promise<boolean>;
 }
 
 /** Plugin configuration options. */
 export interface XEmailPluginOptions {
-  /** SendGrid API key (required) */
+  /**
+   * Email provider: 'sendgrid' (legacy, default) or 'postmark' (migration target).
+   * @default 'sendgrid'
+   */
+  provider?: 'sendgrid' | 'postmark';
+  /** Provider API key: SendGrid API key or Postmark server token (required) */
   apiKey: string;
   /** Verified sender email address (required) */
   fromEmail: string;

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@xenterprises/fastify-xemail",
   "type": "module",
-  "version": "1.1.1",
-  "description": "Fastify plugin for SendGrid email integration — transactional emails, templates, bulk sending, validation, and contact management.",
+  "version": "1.3.0",
+  "description": "Fastify plugin for email via Postmark or SendGrid (legacy) — transactional emails, templates, bulk sending, validation, and contact management.",
   "main": "src/xEmail.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./src/xEmail.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/xEmail.js"
+    }
   },
   "scripts": {
-    "test": "node --test test/xEmail.test.js"
+    "test": "node --test 'test/**/*.test.js'",
+    "lint": "biome check src/ test/",
+    "format": "biome format --write src/ test/"
   },
   "engines": {
     "node": ">=20.0.0",
@@ -16,6 +22,7 @@
   },
   "keywords": [
     "fastify",
+    "postmark",
     "sendgrid",
     "email",
     "plugin"
@@ -23,13 +30,15 @@
   "author": "Tim Mushen",
   "license": "SEE LICENSE IN LICENSE",
   "devDependencies": {
+    "@biomejs/biome": "2.5.5",
     "@types/node": "^22.7.4",
     "fastify": "^5.1.0"
   },
   "dependencies": {
     "@sendgrid/client": "^8.1.3",
     "@sendgrid/mail": "^8.1.3",
-    "fastify-plugin": "^5.0.0"
+    "fastify-plugin": "^5.0.0",
+    "postmark": "^4.0.7"
   },
   "peerDependencies": {
     "fastify": "^5.0.0"