@visulima/email 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## @visulima/email [4.1.0](https://github.com/visulima/visulima/compare/@visulima/email@4.0.0...@visulima/email@4.1.0) (2026-10-23)
+
+### Features
+
+* **email:** add extractLinks test helper ([#984](https://github.com/visulima/visulima/issues/984)) ([183c91f](https://github.com/visulima/visulima/commit/183c91f1e192b364773515da2ce8dbe8deafaa6d))
+* **email:** add file provider for .eml output ([#983](https://github.com/visulima/visulima/issues/983)) ([9768708](https://github.com/visulima/visulima/commit/97687081ff5ac190b0d63a4f0f7442cc64ab0f55))
+* **email:** dead-letter permanent failures early ([#985](https://github.com/visulima/visulima/issues/985)) ([b42d51d](https://github.com/visulima/visulima/commit/b42d51d61e4ab1e4277e4d85e28e877912920651))
+* **email:** load locale-specific template files ([#986](https://github.com/visulima/visulima/issues/986)) ([cfdc461](https://github.com/visulima/visulima/commit/cfdc461091566a46168122096dade10a37477c59))
+
 ## @visulima/email [4.0.0](https://github.com/visulima/visulima/compare/@visulima/email@3.0.28...@visulima/email@4.0.0) (2026-10-15)
 
 ### ⚠ BREAKING CHANGES

package/README.md

@@ -1122,6 +1122,27 @@ mock.reset();
 - `waitForMessage(predicate, timeout)` - Wait for matching message
 - `reset()` - Reset to initial state
 
+### Extracting Links in Tests
+
+`extractLinks` from `@visulima/email/test` returns the http(s) URLs in a message, so a test can follow a verification or reset link. It returns `href` targets from the HTML, then bare URLs from the visible HTML text and from the plain text, without duplicates. Only `a` and `area` elements contribute `href` targets, so image sources, stylesheet and base links, CSS URLs, and the contents of `script`, `style` and comments are ignored. Entities are decoded in HTML, including the hexadecimal entities that template engines use to escape `=`.
+
+Pass markup as `{ html }`. A bare string is always treated as plain text.
+
+```typescript
+import { createTestEmail, extractLinks } from "@visulima/email/test";
+
+const email = createTestEmail();
+
+await email.mail.send({
+    from: { email: "app@example.com" },
+    html: '<a href="https://app.example.com/verify?token=abc&amp;lang=en">Verify</a>',
+    subject: "Verify",
+    to: { email: "user@example.com" },
+});
+
+const [verifyUrl] = extractLinks(email.sent()[0]!.options);
+```
+
 ### MailCrab Provider (for Development)
 
 MailCrab is a local SMTP server for testing emails during development. This provider is a convenience wrapper around the SMTP provider with MailCrab defaults.
@@ -1148,6 +1169,23 @@ const result = await mail.send(message);
 
 **Note:** Make sure MailCrab is running locally before using this provider. MailCrab can be installed via Docker or as a standalone application.
 
+### File Provider (for Development and Testing)
+
+The file provider writes each message to an `.eml` file in a directory instead of sending it. Use it to inspect the exact MIME output during development or in tests.
+
+```typescript
+import { createMail, MailMessage } from "@visulima/email";
+import { fileProvider } from "@visulima/email/providers/file";
+
+const mail = createMail(fileProvider({ directory: "./tmp/emails" }));
+
+const result = await mail.send(new MailMessage().to("user@example.com").from("sender@example.com").subject("Test Email").html("<h1>Test</h1>"));
+
+// result.data.response.path is the written file
+```
+
+Files are named `<epoch-ms>-<message-id>.eml` and are never overwritten. A Message-ID that contains path separators is sanitised before it becomes part of the filename. Bcc recipients are written into the file, since nothing is delivered.
+
 ## Supported Providers
 
 - **AWS SES** - Amazon Simple Email Service
@@ -1155,6 +1193,7 @@ const result = await mail.send(message);
 - **Failover** - Automatic failover between multiple providers
 - **HTTP** - Generic HTTP API provider
 - **MailCrab** - Local development email testing (SMTP wrapper)
+- **File** - Writes messages to `.eml` files instead of sending (Node.js only)
 - **Mailgun** - Developer-friendly email API service
 - **Mailjet** - Email marketing and transactional email platform
 - **MailerSend** - Modern email API for developers
@@ -1225,6 +1264,7 @@ These providers require Node.js built-in modules and only work in **Node.js**:
 - ⚠️ **AWS SES** - Requires `node:crypto` for AWS Signature V4 signing
 - ⚠️ **SMTP** - Requires `node:net` and `node:tls` for SMTP connections
 - ⚠️ **MailCrab** - Wraps SMTP provider (requires Node.js)
+- ⚠️ **File** - Writes to the local filesystem (requires Node.js)
 - ⚠️ **Nodemailer** - Requires the `nodemailer` package (Node.js only)
 
 ### Template Engines
@@ -1237,6 +1277,21 @@ Template engines are optional peer dependencies and work where their underlying
 - **Vue Email** - Works in Node.js and Bun (where `@vue-email/render` package is available)
 - **HTML-to-Text** - Works in Node.js and Bun (where `html-to-text` package is available)
 
+### Locale Template Files (Node.js)
+
+`@visulima/email/template/locale-files` loads templates from a directory, one file per locale. For a template named `welcome`, `welcome.de.html` is used for `de` (and `de-AT`), and `welcome.html` is the fallback, registered under `defaultLocale`:
+
+```typescript
+import { renderHandlebars } from "@visulima/email/template/handlebars";
+import { createLocaleFileRenderer } from "@visulima/email/template/locale-files";
+
+const render = createLocaleFileRenderer("./emails", renderHandlebars, { defaultLocale: "en" });
+
+const html = await render("welcome", "de-AT", { name: "Ada" });
+```
+
+Only file names from the directory listing are read, and a requested locale only selects a key, so a locale from user input never becomes a path. Templates are read on every call; cache the result if they do not change at runtime. Layouts are not part of this loader.
+
 ### Runtime Requirements Summary
 
 | Provider      | Node.js | Bun  | Cloudflare Workers |
@@ -1265,6 +1320,7 @@ Template engines are optional peer dependencies and work where their underlying
 | AWS SES       | ✅      | ❌   | ❌                 |
 | SMTP          | ✅      | ❌   | ❌                 |
 | MailCrab      | ✅      | ❌   | ❌                 |
+| File          | ✅      | ❌   | ❌                 |
 | Nodemailer    | ✅      | ❌   | ❌                 |
 | Failover      | ✅\*    | ✅\* | ✅\*               |
 | Round Robin   | ✅\*    | ✅\* | ✅\*               |
@@ -1386,7 +1442,7 @@ See [Middleware](https://visulima.com/docs/package/email/middleware/introduction
 
 ## Queue & Worker
 
-Durable background sending via the `EmailQueue` interface: an in-memory `MemoryQueue`, an `UnstorageQueue` (`@visulima/email/queue/unstorage`) backed by any [unstorage](https://unstorage.unjs.io/) store (Redis/FS/KV/Postgres), and a `createWorker(...)` with bounded concurrency, retry/backoff and dead-lettering.
+Durable background sending via the `EmailQueue` interface: an in-memory `MemoryQueue`, an `UnstorageQueue` (`@visulima/email/queue/unstorage`) backed by any [unstorage](https://unstorage.unjs.io/) store (Redis/FS/KV/Postgres), and a `createWorker(...)` with bounded concurrency, retry/backoff and dead-lettering. Permanent failures, such as HTTP 4xx responses other than `408`, `409` and `429`, are dead-lettered on their first attempt.
 
 ```typescript
 import { createMail } from "@visulima/email";

package/dist/deliverability/dmarc-report.js

@@ -1 +1 @@
-import c from"../packem_shared/EmailError-BIaHK1Uw.js";const g=r=>r==null?[]:Array.isArray(r)?r:[r],e=r=>{if(typeof r=="string")return r;if(typeof r=="number"||typeof r=="boolean")return String(r)},u=r=>{const a=e(r);if(a===void 0)return;const i=Number(a);return Number.isNaN(i)?void 0:i},f=r=>g(r).map(a=>({domain:e(a.domain),result:e(a.result)})),_=async r=>{let a;try{({XMLParser:a}=await import("fast-xml-parser"))}catch(t){throw t instanceof Error&&(t.code==="ERR_MODULE_NOT_FOUND"||t.message.includes("Cannot find module")||t.message.includes("Cannot find package"))?new c("deliverability","fast-xml-parser is not installed. Please install it: pnpm add fast-xml-parser",{cause:t}):new c("deliverability",`Failed to load fast-xml-parser: ${t.message}`,{cause:t})}let i;try{i=new a({ignoreAttributes:!0,parseTagValue:!1}).parse(r)}catch(t){throw new c("deliverability",`Failed to parse DMARC report: ${t.message}`,{cause:t})}const n=i.feedback??{},o=n.report_metadata??{},m=o.date_range??{},s=n.policy_published??{},y=g(n.record).map(t=>{const d=t.row??{},p=d.policy_evaluated??{},b=t.identifiers??{},l=t.auth_results??{};return{authResults:{dkim:f(l.dkim),spf:f(l.spf)},count:u(d.count)??0,disposition:e(p.disposition),dkim:e(p.dkim),headerFrom:e(b.header_from),sourceIp:e(d.source_ip),spf:e(p.spf)}});return{dateRangeBegin:e(m.begin),dateRangeEnd:e(m.end),email:e(o.email),organizationName:e(o.org_name),policyPublished:{adkim:e(s.adkim),aspf:e(s.aspf),domain:e(s.domain),p:e(s.p),pct:u(s.pct),sp:e(s.sp)},records:y,reportId:e(o.report_id)}};export{_ as parseDmarcReport};
+import c from"../packem_shared/EmailError-SXEFQEyA.js";const g=r=>r==null?[]:Array.isArray(r)?r:[r],e=r=>{if(typeof r=="string")return r;if(typeof r=="number"||typeof r=="boolean")return String(r)},u=r=>{const a=e(r);if(a===void 0)return;const i=Number(a);return Number.isNaN(i)?void 0:i},f=r=>g(r).map(a=>({domain:e(a.domain),result:e(a.result)})),_=async r=>{let a;try{({XMLParser:a}=await import("fast-xml-parser"))}catch(t){throw t instanceof Error&&(t.code==="ERR_MODULE_NOT_FOUND"||t.message.includes("Cannot find module")||t.message.includes("Cannot find package"))?new c("deliverability","fast-xml-parser is not installed. Please install it: pnpm add fast-xml-parser",{cause:t}):new c("deliverability",`Failed to load fast-xml-parser: ${t.message}`,{cause:t})}let i;try{i=new a({ignoreAttributes:!0,parseTagValue:!1}).parse(r)}catch(t){throw new c("deliverability",`Failed to parse DMARC report: ${t.message}`,{cause:t})}const n=i.feedback??{},o=n.report_metadata??{},m=o.date_range??{},s=n.policy_published??{},y=g(n.record).map(t=>{const d=t.row??{},p=d.policy_evaluated??{},b=t.identifiers??{},l=t.auth_results??{};return{authResults:{dkim:f(l.dkim),spf:f(l.spf)},count:u(d.count)??0,disposition:e(p.disposition),dkim:e(p.dkim),headerFrom:e(b.header_from),sourceIp:e(d.source_ip),spf:e(p.spf)}});return{dateRangeBegin:e(m.begin),dateRangeEnd:e(m.end),email:e(o.email),organizationName:e(o.org_name),policyPublished:{adkim:e(s.adkim),aspf:e(s.aspf),domain:e(s.domain),p:e(s.p),pct:u(s.pct),sp:e(s.sp)},records:y,reportId:e(o.report_id)}};export{_ as parseDmarcReport};

package/dist/index.d.ts

@@ -65,10 +65,16 @@ declare class VisulimaError extends Error {
 declare class EmailError extends VisulimaError {
   readonly component: string;
   readonly code?: string;
+  /**
+   * True when repeating the same request would fail the same way, so a queue worker should
+   * dead-letter the job instead of retrying it.
+   */
+  readonly permanent: boolean;
   constructor(component: string, message: string, options?: {
     cause?: Error | unknown;
     code?: string;
     hint?: string | string[];
+    permanent?: boolean;
   });
 }
 /**

package/dist/index.js

@@ -1 +1 @@
-import{detectMimeType as a,generateContentId as t,readFileAsBuffer as o}from"./packem_shared/detectMimeType-BRz3Qjyz.js";import{default as p}from"./packem_shared/DraftMailMessage-B0gwf8n_.js";import{default as m}from"./packem_shared/EmailError-BIaHK1Uw.js";import{default as l}from"./packem_shared/RequiredOptionError-ctDEEB1s.js";import{Mail as u,createMail as x}from"./packem_shared/Mail-DmYNQ0KK.js";import{default as M}from"./packem_shared/MailMessage-DmmaNHHc.js";import{defineProvider as E}from"./packem_shared/defineProvider-C9q-7iwt.js";import{default as g}from"./utils/parse-eml.js";import{isErr as y,isOk as w,mapOk as A,tryAsync as F,unwrap as h,unwrapOr as q}from"./utils/result.js";import{default as B}from"./utils/validation/check-feature-support.js";export{p as DraftMailMessage,m as EmailError,u as Mail,M as MailMessage,l as RequiredOptionError,B as checkFeatureSupport,x as createMail,E as defineProvider,a as detectMimeType,t as generateContentId,y as isErr,w as isOk,A as mapOk,g as parseEml,o as readFileAsBuffer,F as tryAsync,h as unwrap,q as unwrapOr};
+import{detectMimeType as a,generateContentId as t,readFileAsBuffer as o}from"./packem_shared/detectMimeType-BRz3Qjyz.js";import{default as p}from"./packem_shared/DraftMailMessage-B0gwf8n_.js";import{default as m}from"./packem_shared/EmailError-SXEFQEyA.js";import{default as l}from"./packem_shared/RequiredOptionError-C2wWqmiE.js";import{Mail as u,createMail as x}from"./packem_shared/Mail-0cxS6jre.js";import{default as M}from"./packem_shared/MailMessage-DmmaNHHc.js";import{defineProvider as E}from"./packem_shared/defineProvider-C9q-7iwt.js";import{default as g}from"./utils/parse-eml.js";import{isErr as y,isOk as w,mapOk as A,tryAsync as F,unwrap as h,unwrapOr as q}from"./utils/result.js";import{default as B}from"./utils/validation/check-feature-support.js";export{p as DraftMailMessage,m as EmailError,u as Mail,M as MailMessage,l as RequiredOptionError,B as checkFeatureSupport,x as createMail,E as defineProvider,a as detectMimeType,t as generateContentId,y as isErr,w as isOk,A as mapOk,g as parseEml,o as readFileAsBuffer,F as tryAsync,h as unwrap,q as unwrapOr};

package/dist/middleware/index.js

@@ -1 +1 @@
-import{circuitBreakerMiddleware as o}from"../packem_shared/circuitBreakerMiddleware-DcBN7K6H.js";import{dedupeMiddleware as i}from"../packem_shared/dedupeMiddleware-BTo8Qjje.js";import{withEvents as p}from"../packem_shared/withEvents-BinK2hMw.js";import{loggingMiddleware as f}from"../packem_shared/loggingMiddleware-DNVf8O1B.js";import{withMetrics as w}from"../packem_shared/withMetrics-i3mZVfeE.js";import{oauth2Middleware as l}from"../packem_shared/oauth2Middleware-C0M1w3_2.js";import{RATE_LIMIT_PRESETS as h,rateLimitMiddleware as s}from"../packem_shared/RATE_LIMIT_PRESETS-BIFmRuh2.js";import{default as c}from"../packem_shared/withRender-Ce6leoYE.js";import{retryMiddleware as E}from"../packem_shared/retryMiddleware-CaTv0UIm.js";import{withSuppression as g}from"../packem_shared/withSuppression-B0eZ2xNQ.js";import{withTelemetry as S}from"../packem_shared/withTelemetry-DEKTis1I.js";import{composeMiddleware as I}from"../packem_shared/composeMiddleware-B3RCDFsy.js";export{h as RATE_LIMIT_PRESETS,o as circuitBreakerMiddleware,I as composeMiddleware,i as dedupeMiddleware,f as loggingMiddleware,l as oauth2Middleware,s as rateLimitMiddleware,E as retryMiddleware,p as withEvents,w as withMetrics,c as withRender,g as withSuppression,S as withTelemetry};
+import{circuitBreakerMiddleware as o}from"../packem_shared/circuitBreakerMiddleware-Cm0m75qi.js";import{dedupeMiddleware as i}from"../packem_shared/dedupeMiddleware-BTo8Qjje.js";import{withEvents as p}from"../packem_shared/withEvents-BinK2hMw.js";import{loggingMiddleware as f}from"../packem_shared/loggingMiddleware-DNVf8O1B.js";import{withMetrics as w}from"../packem_shared/withMetrics-i3mZVfeE.js";import{oauth2Middleware as l}from"../packem_shared/oauth2Middleware-C0M1w3_2.js";import{RATE_LIMIT_PRESETS as h,rateLimitMiddleware as s}from"../packem_shared/RATE_LIMIT_PRESETS-BIFmRuh2.js";import{default as c}from"../packem_shared/withRender-Ce6leoYE.js";import{retryMiddleware as E}from"../packem_shared/retryMiddleware-CaTv0UIm.js";import{withSuppression as g}from"../packem_shared/withSuppression-COCHL9Zx.js";import{withTelemetry as S}from"../packem_shared/withTelemetry-DEKTis1I.js";import{composeMiddleware as I}from"../packem_shared/composeMiddleware-B3RCDFsy.js";export{h as RATE_LIMIT_PRESETS,o as circuitBreakerMiddleware,I as composeMiddleware,i as dedupeMiddleware,f as loggingMiddleware,l as oauth2Middleware,s as rateLimitMiddleware,E as retryMiddleware,p as withEvents,w as withMetrics,c as withRender,g as withSuppression,S as withTelemetry};