@schemavaults/send-email 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @schemavaults/send-email
 
-TypeScript client for sending emails via the `@schemavaults/mail-server` API. Provides request body validation (via Zod), environment-aware server URL resolution, and helpers for sending to individual recipients, mailing lists, and listing available email templates.
+TypeScript client for sending emails via the `@schemavaults/mail-server` API. Provides request body validation (via Zod), environment-aware server URL resolution, and helpers for sending to individual recipients, mailing lists, attaching files, and listing available email templates.
 
 ## Installation
 
@@ -81,6 +81,59 @@ bunx schemavaults-send-email --transport smtp-primary send \
 
 Transport names are defined by whoever configures the mail-server; this package only validates that the value looks like an identifier. An unknown transport name is rejected by the mail-server, not by the client.
 
+### Attach files
+
+Request bodies are JSON, so each attachment's bytes travel as a base64 string under `body.attachments`. You rarely need to encode anything yourself: the `attachments` option on `sendEmail()` (and `sendEmailToMailingList()`) accepts raw bytes, plain text, or already-encoded attachments and base64-encodes them for you before appending them to `body.attachments`.
+
+```ts
+import { sendEmail } from "@schemavaults/send-email";
+// Node/Bun only -- reads from disk, so it lives on its own subpath
+import { createEmailAttachmentFromFile } from "@schemavaults/send-email/create-email-attachment-from-file";
+
+await sendEmail({
+  body: {
+    to: "user@example.com",
+    subject: "Your invoice",
+    message: { text: "Invoice attached.", html: "<p>Invoice attached.</p>" },
+  },
+  attachments: [
+    // Binary: any Uint8Array / Buffer / ArrayBuffer
+    { filename: "invoice.pdf", content: pdfBytes, contentType: "application/pdf" },
+    // Plain text: say so, otherwise a string is assumed to be base64 already
+    { filename: "summary.txt", content: "Thanks for your order!", encoding: "utf8" },
+    // A file on disk; the basename becomes the attachment filename
+    await createEmailAttachmentFromFile("./reports/q3.csv"),
+  ],
+});
+```
+
+To build the wire shape yourself -- for example to validate it up front or to put it in `body.attachments` directly -- use `createEmailAttachment()`, which takes the same input and returns a validated `EmailAttachment`:
+
+```ts
+import { createEmailAttachment } from "@schemavaults/send-email";
+
+const attachment = createEmailAttachment({
+  filename: "logo.png",
+  content: logoBytes,
+  contentType: "image/png",
+  contentId: "logo", // inline image: reference it as <img src="cid:logo"> in the HTML body
+});
+// => { filename: "logo.png", content: "iVBORw0KGgo...", contentType: "image/png", contentId: "logo" }
+```
+
+Setting `contentId` marks the attachment as inline so the HTML body can embed it via a `cid:` URL; pass the bare identifier without angle brackets. `contentType` is optional -- when omitted, the mail-server's transport derives it from the filename's extension.
+
+Limits enforced client-side (and exported as `MAX_ATTACHMENTS_PER_EMAIL` / `MAX_TOTAL_ATTACHMENT_BYTES`): at most 20 attachments per email, totalling at most 25 MiB once decoded. Filenames may not contain path separators or control characters. The mail-server, its hosting platform, and the receiving mail systems may enforce lower limits of their own.
+
+From the CLI, `--attach <path>` is repeatable on both `send` and `send-to-mailing-list`, and may be combined with `--body-file` (the files are appended to any `attachments` already in the JSON):
+
+```bash
+bunx schemavaults-send-email send \
+  --to user@example.com --subject "Your invoice" \
+  --text "Invoice attached." --html "<p>Invoice attached.</p>" \
+  --attach ./invoice.pdf --attach ./reports/q3.csv
+```
+
 ### Send to a mailing list
 
 ```ts
@@ -141,6 +194,7 @@ interface ISendEmailOpts {
   environment?: "production" | "development" | "staging";
   dryRun?: boolean;           // convenience; sets body.dryRun
   transport?: string;         // convenience; sets body.transport
+  attachments?: EmailAttachmentInput[]; // convenience; encoded + appended to body.attachments
 }
 ```
 
@@ -157,9 +211,30 @@ interface ISendEmailToMailingListOpts {
   environment?: "production" | "development" | "staging";
   dryRun?: boolean;           // convenience; sets body.dryRun
   transport?: string;         // convenience; sets body.transport
+  attachments?: EmailAttachmentInput[]; // convenience; encoded + appended to body.attachments
+}
+```
+
+### `createEmailAttachment(input)`
+
+Builds a validated `EmailAttachment` (the wire shape used in `body.attachments`), base64-encoding the content for you. Throws a `TypeError` describing the problem when the result is invalid.
+
+```ts
+interface EmailAttachmentInput {
+  filename: string;                             // shown to the recipient; no path separators
+  content: string | Uint8Array | ArrayBuffer;   // bytes, or a string (see `encoding`)
+  encoding?: "base64" | "utf8";                 // how to read a string `content`; default "base64"
+  contentType?: string;                         // MIME type; derived from the filename when omitted
+  contentId?: string;                           // set to embed inline via cid: in the HTML body
 }
 ```
 
+An `EmailAttachment` is itself valid `EmailAttachmentInput` (its `content` is base64), so pre-built attachments and raw inputs can be mixed freely.
+
+### `createEmailAttachmentFromFile(path, opts?)`
+
+Node/Bun only. Reads a file from disk and returns a validated `EmailAttachment`; the file's basename is the attachment filename unless `opts.filename` overrides it. `opts` may also set `contentType` and `contentId`. Imported from the `@schemavaults/send-email/create-email-attachment-from-file` subpath so the package's main entry stays free of filesystem imports.
+
 ### `listEmailTemplates(opts?)`
 
 Returns the list of registered email templates from the mail-server catalog.
@@ -197,6 +272,10 @@ Zod schema for validating template IDs: lowercase alphanumeric with hyphens/unde
 
 Zod schema for validating transport names: lowercase alphanumeric with hyphens/underscores, 1-64 characters, must start with a lowercase letter and end with a lowercase alphanumeric character. Whether a well-formed name corresponds to a transport the mail-server actually has configured is decided server-side.
 
+### `emailAttachmentSchema` / `emailAttachmentsSchema`
+
+Zod schemas for a single attachment and for the `attachments` array respectively. The array schema enforces the count (`MAX_ATTACHMENTS_PER_EMAIL`, 20) and total decoded size (`MAX_TOTAL_ATTACHMENT_BYTES`, 25 MiB) limits; both constants are exported.
+
 ## Request body shape
 
 The `message` field accepts either a template reference or raw content:
@@ -206,6 +285,13 @@ type Message =
   | { template_id: string; template_props?: unknown }
   | { text: string; html: string }; // both required
 
+type EmailAttachment = {
+  filename: string;            // 1-255 chars; no path separators or control characters
+  content: string;             // base64-encoded bytes (standard alphabet, padded)
+  contentType?: string;        // MIME type; derived from the filename when omitted
+  contentId?: string;          // marks the attachment inline; reference as cid:<contentId>
+};
+
 type SendEmailRequestBody = {
   to: string | string[];       // email address(es) or mailing list UUID
   subject: string;
@@ -216,6 +302,7 @@ type SendEmailRequestBody = {
   bcc?: string | string[];
   dryRun?: boolean;            // server validates without dispatching
   transport?: string;          // which mail-server transport delivers this email
+  attachments?: EmailAttachment[]; // 1-20 files, at most 25 MiB in total once decoded
 };
 ```
 
@@ -228,3 +315,9 @@ bun test
 bun run typecheck
 bun run lint
 ```
+
+### Keeping the package root browser-safe
+
+Consumers bundle the package root for the browser (the mail-server's admin UI imports `sendEmail` from a client component), so nothing reachable from `src/index.ts` may need a Node/Bun runtime. `src/browser-compatibility.test.ts` enforces this on every `bun test`: it bundles the root with esbuild for the browser platform, asserts no Node built-in is imported anywhere in the graph, and evaluates the bundle in a `node:vm` context with no `process` / `Buffer` / `require` before exercising the public API.
+
+Anything that does need Node or Bun -- filesystem access, for example -- goes in its own module exposed through a package subpath (as `create-email-attachment-from-file` is) and is added to that test's `NODE_ONLY_MODULES` list, which both checks the root never imports it and confirms it really is not browser-safe.

package/bun.lock

@@ -5,8 +5,8 @@
     "": {
       "name": "@schemavaults/send-email",
       "dependencies": {
-        "commander": "^14.0.1",
-        "zod": "3.25.8",
+        "commander": "14.0.1",
+        "zod": "4.4.3",
       },
       "devDependencies": {
         "@eslint/js": "9.39.1",
@@ -168,7 +168,7 @@
 
     "color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
 
-    "commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="],
+    "commander": ["commander@14.0.1", "", {}, "sha512-2JkV3gUZUVrbNA+1sjBOYLsMZ5cEEl8GTFP2a4AVz5hvasAMCQ1D2l2le/cX+pV4N6ZU17zjUahLpIXRrnWL8A=="],
 
     "concat-map": ["concat-map@0.0.1", "", {}, "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="],
 
@@ -352,7 +352,7 @@
 
     "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
 
-    "zod": ["zod@3.25.8", "", {}, "sha512-iJPWX8HoZ2VE21VrhHGU9jVo/kVDUQyqM9vF0MxDhW/fp2sAl1eVwGJgiYZdHGiMwQJImXIW80lKk0MnfDxqiQ=="],
+    "zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
 
     "@eslint-community/eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],