@xenterprises/fastify-xemail 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `@xenterprises/fastify-xemail` are documented here.
+
+## Unreleased
+
+## [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/LICENSE

@@ -4,54 +4,94 @@ 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.
+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 LLC.
+   of X Enterprises. No rights are granted except as expressly set forth in
+   this License.
 
-2. RESTRICTIONS
-   Without the prior written consent of X Enterprises LLC, you may not:
-   - Copy, modify, or distribute the Software
-   - Reverse engineer, decompile, or disassemble the Software
-   - Sublicense, sell, lease, or otherwise transfer the Software
-   - Remove or alter any proprietary notices or labels
+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:
 
-3. AUTHORIZED USE
-   Use of this Software is limited to authorized employees, contractors, and
-   agents of X Enterprises LLC, solely for purposes approved by X Enterprises
-   LLC.
+   (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 LLC 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.
+   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 LLC 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.
+   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.
+   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. X Enterprises LLC may terminate
-   this license at any time without notice. Upon termination, you must destroy
-   all copies of the Software in your possession.
+   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
 

package/README.md

@@ -1,14 +1,19 @@
 # @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 SendGrid — send transactional, template, attachment, and bulk emails, validate addresses, and manage SendGrid Marketing contacts and lists, all through one `fastify.xEmail` decorator. For Fastify apps that need email with the least possible wiring.
 
-## Installation
+## 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 +22,10 @@ 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
+  apiKey: 'SG.your-api-key',
+  fromEmail: 'noreply@example.com',
 });
 
-// Send a simple email
 await fastify.xEmail.send(
   'user@example.com',
   'Welcome!',
@@ -30,168 +33,113 @@ await fastify.xEmail.send(
 );
 ```
 
+The plugin reads **no environment variables**. All configuration arrives via the
+register options object; reading `process.env.SENDGRID_API_KEY` and passing it in
+is the consumer's job.
+
 ## Options
 
 | Name | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `apiKey` | `string` | — | Yes | SendGrid API key |
+| `apiKey` | `string` | — | Yes | SendGrid API key (needs Mail Send; Marketing APIs for contact/list methods) |
 | `fromEmail` | `string` | — | Yes | Verified sender email address |
-| `fromName` | `string` | — | No | Sender display name |
-| `active` | `boolean` | `true` | No | Set `false` to disable the plugin entirely |
+| `fromName` | `string` | — | No | Sender display name; when set, `from` becomes `{ email, name }` |
+| `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.
+`extraOptions` is merged into the SendGrid message (e.g. `replyTo`, `cc`, `categories`).
+Returns `{ success, statusCode, messageId }`.
 
-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 SendGrid dynamic template (`templateId` is the `d-xxx` ID). `dynamicData`
+is sent as `dynamicTemplateData` (the subject is always included). 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 in one call (`sgMail.sendMultiple`).
+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 }, ...]
-```
+Send different content per recipient. `messages` is an array of
+`{ to, subject, html, text? }`. Uses `Promise.allSettled`, so it never throws on
+individual failures — returns one result per recipient:
+`{ success: true, to, statusCode }` or `{ success: false, to, error }`.
 
 ### `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: {...} }
-```
+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.
 
 ### `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: '...' }
-```
+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 }`.
 
 ### `searchContact(email)`
 
-Search for a contact by email.
-
-```javascript
-const result = await fastify.xEmail.searchContact('user@example.com');
-// { found: true, contact: { id: '...', email: '...', ... } }
-```
+Search for a contact by email. Returns `{ found: true, contact }` or `{ found: false }`.
 
 ### `deleteContact(contactId)`
 
-Delete a contact by ID. Returns `true` on success.
+Delete a contact by ID. Returns `true` on success (HTTP 200/202), `false` otherwise.
 
 ### `createList(name)`
 
-Create a new marketing contact list.
-
-```javascript
-const result = await fastify.xEmail.createList('Newsletter');
-// { success: true, list: { id: '...', name: 'Newsletter' } }
-```
+Create a marketing contact list. Returns `{ success, list }`.
 
 ### `getLists()`
 
-Get all contact lists. Returns an array.
+Get all contact lists. Returns an array (empty when none exist).
 
 ### `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.
+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.
+- 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/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@xenterprises/fastify-xemail",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Fastify plugin for SendGrid email integration — 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",
@@ -21,8 +27,9 @@
     "plugin"
   ],
   "author": "Tim Mushen",
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "devDependencies": {
+    "@biomejs/biome": "2.5.5",
     "@types/node": "^22.7.4",
     "fastify": "^5.1.0"
   },
@@ -33,5 +40,8 @@
   },
   "peerDependencies": {
     "fastify": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/xEmail.js

@@ -1,6 +1,6 @@
-import fp from "fastify-plugin";
-import sgMail from "@sendgrid/mail";
 import sgClient from "@sendgrid/client";
+import sgMail from "@sendgrid/mail";
+import fp from "fastify-plugin";
 
 /**
  * @param {import('fastify').FastifyInstance} fastify
@@ -15,12 +15,26 @@ async function xEmail(fastify, options) {
 
   if (active === false) return;
 
+  if (typeof active !== "boolean") {
+    throw new Error("xemail: option `active` must be a boolean");
+  }
+
   if (!apiKey || typeof apiKey !== "string") {
-    throw new Error("[xEmail] 'apiKey' (string) is required.");
+    throw new Error(
+      "xemail: option `apiKey` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key' })`"
+    );
   }
 
   if (!fromEmail || typeof fromEmail !== "string") {
-    throw new Error("[xEmail] 'fromEmail' (string) is required.");
+    throw new Error(
+      "xemail: option `fromEmail` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key', fromEmail: 'noreply@example.com' })`"
+    );
+  }
+
+  if (fromName !== undefined && typeof fromName !== "string") {
+    throw new Error(
+      "xemail: option `fromName` must be a string, e.g. `app.register(xEmail, { apiKey: 'SG.your-api-key', fromEmail: 'noreply@example.com', fromName: 'My App' })`"
+    );
   }
 
   sgMail.setApiKey(apiKey);
@@ -176,7 +190,9 @@ async function xEmail(fastify, options) {
      */
     sendPersonalizedBulk: async (messages) => {
       if (!Array.isArray(messages) || messages.length === 0) {
-        throw new Error("[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk().");
+        throw new Error(
+          "[xEmail] 'messages' must be a non-empty array for sendPersonalizedBulk()."
+        );
       }
 
       const mailMessages = messages.map((msg) => ({
@@ -232,7 +248,9 @@ async function xEmail(fastify, options) {
           };
         }
 
-        throw new Error(body.errors ? body.errors.map((e) => e.message).join(", ") : "Validation failed");
+        throw new Error(
+          body.errors ? body.errors.map((e) => e.message).join(", ") : "Validation failed"
+        );
       } catch (error) {
         fastify.log.error({ err: error }, "xEmail validate failed");
         return {
@@ -277,7 +295,7 @@ async function xEmail(fastify, options) {
           return { success: true, jobId: body.job_id, email };
         }
 
-        throw new Error("Unexpected status code: " + response.statusCode);
+        throw new Error(`Unexpected status code: ${response.statusCode}`);
       } catch (error) {
         fastify.log.error({ err: error }, "xEmail addContact failed");
         throw new Error(`[xEmail] Failed to add contact: ${error.message}`);
@@ -400,6 +418,6 @@ async function xEmail(fastify, options) {
 }
 
 export default fp(xEmail, {
-  name: "xEmail",
-  fastify: ">=5.0.0",
+  name: "xemail",
+  fastify: "5.x",
 });