@visulima/email 1.0.0-alpha.34 → 1.0.0-alpha.35

package/dist/queue/bullmq-queue.d.ts

@@ -0,0 +1,46 @@
+import { E as EmailOptions, a as EmailResult, R as Result } from "../packem_shared/types.d-ejzh-xBP.js";
+import { E as EnqueueOptions } from "../packem_shared/types.d-lcJZmwRK.js";
+import 'node:buffer';
+/**
+* The subset of a [BullMQ](https://docs.bullmq.io/) `Queue` this adapter uses.
+*/
+interface BullmqQueueLike {
+  add: (name: string, data: unknown, options?: {
+    delay?: number;
+  }) => Promise<{
+    id?: string;
+  }>;
+}
+/**
+* A BullMQ job, narrowed to its `data` payload.
+*/
+interface BullmqJobLike {
+  data: EmailOptions;
+}
+/**
+* A BullMQ `Worker` processor that sends a job's message and resolves with the send result.
+*/
+type BullmqProcessor = (job: BullmqJobLike) => Promise<EmailResult>;
+/**
+* Adds a message to a BullMQ queue.
+*
+* BullMQ is push-based — jobs are consumed by a BullMQ `Worker`, not the pull-based reserve/ack model
+* of `EmailQueue`. Use this to enqueue and {@link createBullmqProcessor} to consume.
+* @param queue A BullMQ `Queue` instance to add the job to (optional peer).
+* @param message The email payload stored as the BullMQ job data.
+* @param options Optional scheduling — `scheduledAt` maps to a BullMQ `delay`.
+* @param jobName The name to enqueue the job under.
+* @returns The id of the created BullMQ job.
+*/
+declare const enqueueToBullmq: (queue: BullmqQueueLike, message: EmailOptions, options?: EnqueueOptions, jobName?: string) => Promise<string>;
+/**
+* Builds a BullMQ `Worker` processor that sends each job's message via the given send function.
+*
+* Pass it to `new Worker(queueName, createBullmqProcessor(mail.send.bind(mail)), { concurrency })`.
+* BullMQ then handles concurrency, retries (via the job's `attempts`/`backoff`) and dead-lettering. A
+* failed send throws so BullMQ records the attempt.
+* @param send The send function — typically `mail.send.bind(mail)`.
+* @returns A BullMQ processor function.
+*/
+declare const createBullmqProcessor: (send: (message: EmailOptions) => Promise<Result<EmailResult>>) => BullmqProcessor;
+export { BullmqJobLike, BullmqProcessor, BullmqQueueLike, createBullmqProcessor, enqueueToBullmq };

package/dist/queue/bullmq-queue.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var o=(a,r)=>c(a,"name",{value:r,configurable:!0});var n=Object.defineProperty,d=o((a,r)=>n(a,"name",{value:r,configurable:!0}),"i");const i=d(async(a,r,e={},l="email")=>{let t;if(e.scheduledAt!==void 0){const s=e.scheduledAt instanceof Date?e.scheduledAt.getTime():e.scheduledAt;t=Math.max(0,s-Date.now())}return(await a.add(l,r,t===void 0?void 0:{delay:t})).id??""},"enqueueToBullmq"),m=d(a=>async r=>{const e=await a(r.data);if(!e.success||!e.data)throw e.error instanceof Error?e.error:new Error("Email send failed");return e.data},"createBullmqProcessor");export{m as createBullmqProcessor,i as enqueueToBullmq};

package/dist/queue/index.d.ts

@@ -0,0 +1,148 @@
+import { E as EmailOptions, a as EmailResult, R as Result } from "../packem_shared/types.d-ejzh-xBP.js";
+import { E as EnqueueOptions, Q as QueueJob, a as EmailQueue } from "../packem_shared/types.d-lcJZmwRK.js";
+export { UnstorageQueue, type UnstorageQueueOptions, createUnstorageQueue } from "./unstorage-queue.js";
+import 'node:buffer';
+import 'unstorage';
+/**
+* Options for {@link MemoryQueue}.
+*/
+interface MemoryQueueOptions {
+  /**
+  * Time source in milliseconds — injectable for tests. Defaults to `Date.now`.
+  */
+  now?: () => number;
+  /**
+  * How long, in milliseconds, a reserved job stays hidden before it becomes deliverable again
+  * (in case the worker crashed mid-process).
+  * @default 30000
+  */
+  visibilityTimeout?: number;
+}
+/**
+* An in-memory {@link EmailQueue} with `scheduledAt` support and a reservation visibility timeout.
+*
+* Suitable for tests, single-process apps, and as a reference for adapter authors. Jobs do not survive
+* a process restart — use a durable adapter in production.
+*/
+declare class MemoryQueue implements EmailQueue {
+  private readonly jobs;
+  private readonly visibilityTimeout;
+  private readonly now;
+  private sequence;
+  /**
+  * @param options Queue options. See {@link MemoryQueueOptions}.
+  */
+  constructor(options?: MemoryQueueOptions);
+  /**
+  * Adds a message to the queue.
+  * @param message The message to send later.
+  * @param options Optional scheduling. See {@link EnqueueOptions}.
+  * @returns The new job id.
+  */
+  enqueue(message: EmailOptions, options?: EnqueueOptions): string;
+  /**
+  * Reserves the next ready job, hiding it for the visibility window.
+  * @returns The next deliverable job, or `undefined` when none is ready.
+  */
+  reserve(): QueueJob | undefined;
+  /**
+  * Marks a reserved job as processed and removes it.
+  * @param id The job id.
+  */
+  ack(id: string): void;
+  /**
+  * Returns a job to the queue after a delay, incrementing its attempt count.
+  * @param id The job id.
+  * @param delayMs Milliseconds to wait before the job becomes ready again.
+  */
+  retry(id: string, delayMs?: number): void;
+  /**
+  * Reports how many jobs remain (ready plus reserved).
+  * @returns The count of ready and reserved jobs.
+  */
+  size(): number;
+}
+/**
+* Options for {@link createWorker}.
+*/
+interface WorkerOptions {
+  /**
+  * Retry backoff: returns the delay (ms) before re-attempting after `attempts` failures.
+  * @default attempts => 1000 * 2 ** (attempts - 1)
+  */
+  backoff?: (attempts: number) => number;
+  /**
+  * How many jobs to process concurrently.
+  * @default 1
+  */
+  concurrency?: number;
+  /**
+  * Maximum delivery attempts before a job is dead-lettered.
+  * @default 3
+  */
+  maxAttempts?: number;
+  /**
+  * Called when a job exhausts its attempts and is dropped.
+  * @param job The dead-lettered job.
+  * @param result The final failed result.
+  */
+  onDeadLetter?: (job: QueueJob, result: Result<EmailResult>) => void;
+  /**
+  * Called on every failed attempt (before any retry).
+  * @param job The job that failed.
+  * @param result The failed result (or thrown error wrapped).
+  */
+  onError?: (job: QueueJob, result: Result<EmailResult>) => void;
+  /**
+  * Called when `queue.reserve()` itself rejects (e.g. a transient store error). The poll loop keeps
+  * running regardless; this hook just surfaces the failure.
+  * @param error The reserve error.
+  */
+  onReserveError?: (error: Error) => void;
+  /**
+  * Idle poll interval, in milliseconds, when no job is ready.
+  * @default 1000
+  */
+  pollInterval?: number;
+  /**
+  * The queue to consume.
+  */
+  queue: EmailQueue;
+  /**
+  * The send function — typically `mail.send.bind(mail)`.
+  */
+  send: (message: EmailOptions) => Promise<Result<EmailResult>>;
+}
+/**
+* A running queue worker.
+*/
+interface Worker {
+  /**
+  * Processes ready jobs until the queue has none currently deliverable, then resolves.
+  *
+  * Does not wait for future-scheduled jobs. Useful in tests and one-shot drains.
+  */
+  drain: () => Promise<void>;
+  /**
+  * Begins polling and processing jobs in the background.
+  */
+  start: () => void;
+  /**
+  * Stops polling. In-flight jobs are allowed to finish.
+  */
+  stop: () => void;
+}
+/**
+* Creates a worker that durably processes queued messages with bounded concurrency, retry/backoff, and
+* dead-lettering.
+* @param options Worker configuration. See {@link WorkerOptions}.
+* @returns The worker handle. See {@link Worker}.
+* @example
+* ```ts
+* const queue = new MemoryQueue();
+* const worker = createWorker({ queue, send: mail.send.bind(mail), concurrency: 5 });
+* worker.start();
+* ```
+*/
+declare const createWorker: (options: WorkerOptions) => Worker;
+export { type EmailQueue, type EnqueueOptions, MemoryQueue, type MemoryQueueOptions, type QueueJob, type Worker, type WorkerOptions, createWorker };

package/dist/queue/index.js

@@ -0,0 +1 @@
+import{MemoryQueue as o}from"../packem_shared/MemoryQueue-C-CtRRG7.js";import{UnstorageQueue as u,createUnstorageQueue as a}from"./unstorage-queue.js";import{createWorker as f}from"../packem_shared/createWorker-Nkc1GHet.js";export{o as MemoryQueue,u as UnstorageQueue,a as createUnstorageQueue,f as createWorker};

package/dist/queue/pg-boss-queue.d.ts

@@ -0,0 +1,41 @@
+import { a as EmailQueue } from "../packem_shared/types.d-lcJZmwRK.js";
+import "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
+interface PgBossJob {
+  data: unknown;
+  id: string;
+  /** pg-boss retry count (present when fetched with `includeMetadata`). */
+  retryCount?: number;
+}
+/**
+* The subset of a [pg-boss](https://github.com/timgit/pg-boss) instance this adapter uses (v10 API).
+*/
+interface PgBossLike {
+  complete: (name: string, id: string) => Promise<unknown>;
+  fail: (name: string, id: string) => Promise<unknown>;
+  fetch: (name: string, options?: {
+    batchSize?: number;
+    includeMetadata?: boolean;
+  }) => Promise<PgBossJob[] | PgBossJob | null>;
+  getQueueSize: (name: string) => Promise<number>;
+  send: (name: string, data: object, options?: {
+    startAfter?: Date | number | string;
+  }) => Promise<null | string>;
+}
+/**
+* Options for {@link createPgBossQueue}.
+*/
+interface PgBossQueueOptions {
+  /**
+  * The pg-boss queue name.
+  */
+  queueName: string;
+}
+/**
+* Creates an {@link EmailQueue} backed by pg-boss.
+* @param boss A started pg-boss instance (optional peer).
+* @param options Queue options. See {@link PgBossQueueOptions}.
+* @returns The pg-boss-backed queue.
+*/
+declare const createPgBossQueue: (boss: PgBossLike, options: PgBossQueueOptions) => EmailQueue;
+export { type PgBossLike, type PgBossQueueOptions, createPgBossQueue };

package/dist/queue/pg-boss-queue.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var a=(t,e)=>r(t,"name",{value:e,configurable:!0});var c=Object.defineProperty,i=a((t,e)=>c(t,"name",{value:e,configurable:!0}),"i");class o{static{a(this,"o")}static{i(this,"PgBossQueue")}boss;queueName;constructor(e,s){this.boss=e,this.queueName=s.queueName}async enqueue(e,s={}){const u=s.scheduledAt;return await this.boss.send(this.queueName,e,u===void 0?void 0:{startAfter:u})??""}async reserve(){const e=await this.boss.fetch(this.queueName,{batchSize:1,includeMetadata:!0});if(!e)return;const s=Array.isArray(e)?e[0]:e;if(s)return{attempts:s.retryCount??0,id:s.id,message:s.data,scheduledAt:0}}async ack(e){await this.boss.complete(this.queueName,e)}async retry(e){await this.boss.fail(this.queueName,e)}async size(){return this.boss.getQueueSize(this.queueName)}}const h=i((t,e)=>new o(t,e),"createPgBossQueue");export{h as createPgBossQueue};

package/dist/queue/sqs-queue.d.ts

@@ -0,0 +1,72 @@
+import { a as EmailQueue } from "../packem_shared/types.d-lcJZmwRK.js";
+import "../packem_shared/types.d-ejzh-xBP.js";
+import 'node:buffer';
+/**
+* The subset of the `@aws-sdk/client-sqs` `SQS` client this adapter uses. The `SQS` class (not the
+* lower-level `SQSClient`) exposes these operation methods directly.
+*/
+interface SqsClientLike {
+  changeMessageVisibility: (input: {
+    QueueUrl: string;
+    ReceiptHandle: string;
+    VisibilityTimeout: number;
+  }) => Promise<unknown>;
+  deleteMessage: (input: {
+    QueueUrl: string;
+    ReceiptHandle: string;
+  }) => Promise<unknown>;
+  getQueueAttributes: (input: {
+    AttributeNames: string[];
+    QueueUrl: string;
+  }) => Promise<{
+    Attributes?: Record<string, string>;
+  }>;
+  receiveMessage: (input: {
+    AttributeNames?: string[];
+    MaxNumberOfMessages?: number;
+    QueueUrl: string;
+    VisibilityTimeout?: number;
+    WaitTimeSeconds?: number;
+  }) => Promise<{
+    Messages?: {
+      Attributes?: Record<string, string>;
+      Body?: string;
+      MessageId?: string;
+      ReceiptHandle?: string;
+    }[];
+  }>;
+  sendMessage: (input: {
+    DelaySeconds?: number;
+    MessageBody: string;
+    QueueUrl: string;
+  }) => Promise<{
+    MessageId?: string;
+  }>;
+}
+/**
+* Options for {@link createSqsQueue}.
+*/
+interface SqsQueueOptions {
+  /**
+  * The SQS queue URL.
+  */
+  queueUrl: string;
+  /**
+  * Visibility timeout (seconds) applied when reserving a message.
+  * @default 30
+  */
+  visibilityTimeout?: number;
+  /**
+  * Long-poll wait time (seconds) for `reserve`.
+  * @default 0
+  */
+  waitTimeSeconds?: number;
+}
+/**
+* Creates an {@link EmailQueue} backed by Amazon SQS.
+* @param client An `@aws-sdk/client-sqs` `SQS` instance (optional peer).
+* @param options Queue options. See {@link SqsQueueOptions}.
+* @returns The SQS-backed queue.
+*/
+declare const createSqsQueue: (client: SqsClientLike, options: SqsQueueOptions) => EmailQueue;
+export { type SqsClientLike, type SqsQueueOptions, createSqsQueue };

package/dist/queue/sqs-queue.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var a=(t,e)=>c(t,"name",{value:e,configurable:!0});var l=Object.defineProperty,u=a((t,e)=>l(t,"name",{value:e,configurable:!0}),"n");const r="ApproximateNumberOfMessages",n="ApproximateNumberOfMessagesNotVisible",o=u((t,e)=>{if(t===void 0)return 0;const i=t instanceof Date?t.getTime():t,s=Math.ceil((i-e)/1e3);return Math.max(0,s)},"toDelaySeconds");class m{static{a(this,"m")}static{u(this,"SqsQueue")}client;queueUrl;visibilityTimeout;waitTimeSeconds;constructor(e,i){this.client=e,this.queueUrl=i.queueUrl,this.visibilityTimeout=i.visibilityTimeout??30,this.waitTimeSeconds=i.waitTimeSeconds??0}async enqueue(e,i={}){const s=o(i.scheduledAt,Date.now());if(s>900)throw new RangeError(`SQS supports a maximum scheduling delay of ${String(900)}s (15 minutes); use a scheduler for longer delays`);return(await this.client.sendMessage({DelaySeconds:s,MessageBody:JSON.stringify(e),QueueUrl:this.queueUrl})).MessageId??""}async reserve(){const e=(await this.client.receiveMessage({AttributeNames:["ApproximateReceiveCount"],MaxNumberOfMessages:1,QueueUrl:this.queueUrl,VisibilityTimeout:this.visibilityTimeout,WaitTimeSeconds:this.waitTimeSeconds})).Messages?.[0];if(!e?.ReceiptHandle)return;const i=Number(e.Attributes?.ApproximateReceiveCount??"1");let s;try{s=JSON.parse(e.Body??"{}")}catch{await this.client.deleteMessage({QueueUrl:this.queueUrl,ReceiptHandle:e.ReceiptHandle});return}return{attempts:Math.max(0,i-1),id:e.ReceiptHandle,message:s,scheduledAt:0}}async ack(e){await this.client.deleteMessage({QueueUrl:this.queueUrl,ReceiptHandle:e})}async retry(e,i=0){await this.client.changeMessageVisibility({QueueUrl:this.queueUrl,ReceiptHandle:e,VisibilityTimeout:Math.min(900,Math.max(0,Math.ceil(i/1e3)))})}async size(){const e=await this.client.getQueueAttributes({AttributeNames:[r,n],QueueUrl:this.queueUrl});return Number(e.Attributes?.[r]??0)+Number(e.Attributes?.[n]??0)}}const d=u((t,e)=>new m(t,e),"createSqsQueue");export{d as createSqsQueue};

package/dist/queue/unstorage-queue.d.ts

@@ -0,0 +1,81 @@
+import { Storage } from 'unstorage';
+import { E as EmailOptions } from "../packem_shared/types.d-ejzh-xBP.js";
+import { E as EnqueueOptions, Q as QueueJob, a as EmailQueue } from "../packem_shared/types.d-lcJZmwRK.js";
+import 'node:buffer';
+/**
+* Options for {@link UnstorageQueue}.
+*/
+interface UnstorageQueueOptions {
+  /**
+  * Time source in milliseconds — injectable for tests. Defaults to `Date.now`.
+  */
+  now?: () => number;
+  /**
+  * Key prefix under which jobs are stored.
+  * @default "email:queue"
+  */
+  prefix?: string;
+  /**
+  * How long, in milliseconds, a reserved job stays hidden before becoming deliverable again.
+  * @default 30000
+  */
+  visibilityTimeout?: number;
+}
+/**
+* A durable {@link EmailQueue} backed by an [unstorage](https://unstorage.unjs.io/) `Storage`.
+*
+* Because unstorage abstracts many backends (memory, filesystem, Redis, Cloudflare KV, Postgres, …),
+* a single adapter persists the queue across all of them. The stored `message` must be
+* JSON-serializable (avoid `Buffer` attachments — pass `path`/`href`/base64 `content` instead).
+*
+* Note: unstorage has no transactions, so {@link UnstorageQueue.reserve} is best-effort under
+* concurrent workers; the visibility timeout bounds duplicate delivery on a crash.
+*/
+declare class UnstorageQueue implements EmailQueue {
+  private readonly storage;
+  private readonly prefix;
+  private readonly visibilityTimeout;
+  private readonly now;
+  /**
+  * @param storage The unstorage instance to persist jobs in.
+  * @param options Adapter options. See {@link UnstorageQueueOptions}.
+  */
+  constructor(storage: Storage, options?: UnstorageQueueOptions);
+  /**
+  * Persists a message to the store.
+  * @param message The message to send later.
+  * @param options Optional scheduling. See {@link EnqueueOptions}.
+  * @returns The new job id.
+  */
+  enqueue(message: EmailOptions, options?: EnqueueOptions): Promise<string>;
+  /**
+  * Reserves the next ready job, hiding it for the visibility window.
+  * @returns The next deliverable job, or `undefined` when none is ready.
+  */
+  reserve(): Promise<QueueJob | undefined>;
+  /**
+  * Removes a processed job from the store.
+  * @param id The job id.
+  */
+  ack(id: string): Promise<void>;
+  /**
+  * Requeues a job after a delay, incrementing its attempt count.
+  * @param id The job id.
+  * @param delayMs Milliseconds to wait before the job becomes ready again.
+  */
+  retry(id: string, delayMs?: number): Promise<void>;
+  /**
+  * Counts the jobs currently in the store.
+  * @returns The number of stored (ready plus reserved) jobs.
+  */
+  size(): Promise<number>;
+  private keyOf;
+}
+/**
+* Creates an {@link UnstorageQueue}.
+* @param storage The unstorage instance to persist jobs in.
+* @param options Adapter options. See {@link UnstorageQueueOptions}.
+* @returns A new {@link UnstorageQueue}.
+*/
+declare const createUnstorageQueue: (storage: Storage, options?: UnstorageQueueOptions) => UnstorageQueue;
+export { UnstorageQueue, UnstorageQueueOptions, createUnstorageQueue };

package/dist/queue/unstorage-queue.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var a=(i,e)=>u(i,"name",{value:e,configurable:!0});import{createRequire as d}from"node:module";const h=d(import.meta.url),o=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,l=a(i=>{if(typeof o<"u"&&o.versions&&o.versions.node){const[e,s]=o.versions.node.split(".").map(Number);if(e>22||e===22&&s>=3||e===20&&s>=16)return o.getBuiltinModule(i)}return h(i)},"__cjs_getBuiltinModule"),{randomUUID:g}=l("node:crypto");var m=Object.defineProperty,n=a((i,e)=>m(i,"name",{value:e,configurable:!0}),"o");class f{static{a(this,"UnstorageQueue")}static{n(this,"UnstorageQueue")}storage;prefix;visibilityTimeout;now;constructor(e,s={}){this.storage=e,this.prefix=s.prefix??"email:queue",this.visibilityTimeout=s.visibilityTimeout??3e4,this.now=s.now??Date.now}async enqueue(e,s={}){const r=g(),t=s.scheduledAt instanceof Date?s.scheduledAt.getTime():s.scheduledAt??this.now(),c={attempts:0,id:r,message:e,reservedUntil:0,scheduledAt:t};return await this.storage.setItem(this.keyOf(r),c),r}async reserve(){const e=this.now(),s=await this.storage.getKeys(this.prefix);for(const r of s){const t=await this.storage.getItem(r);if(t&&t.scheduledAt<=e&&t.reservedUntil<=e)return t.reservedUntil=e+this.visibilityTimeout,await this.storage.setItem(r,t),{attempts:t.attempts,id:t.id,message:t.message,scheduledAt:t.scheduledAt}}}async ack(e){await this.storage.removeItem(this.keyOf(e))}async retry(e,s=0){const r=this.keyOf(e),t=await this.storage.getItem(r);t&&(t.attempts+=1,t.reservedUntil=0,t.scheduledAt=this.now()+s,await this.storage.setItem(r,t))}async size(){return(await this.storage.getKeys(this.prefix)).length}keyOf(e){return`${this.prefix}:${e}`}}const v=n((i,e)=>new f(i,e),"createUnstorageQueue");export{f as UnstorageQueue,v as createUnstorageQueue};

package/dist/render/index.d.ts

@@ -0,0 +1,107 @@
+/**
+* Rewrites `cid:` references in `src`/`href` attributes using a resolver.
+*
+* Useful for turning inline (Content-ID) image references into hosted URLs for previews/webmail, or
+* for normalizing them. Returning `undefined` from the resolver leaves that reference unchanged.
+* @param html The HTML email.
+* @param resolver Maps a Content-ID to a replacement URL (or `undefined` to keep it).
+* @returns The rewritten HTML.
+*/
+declare const rewriteCidLinks: (html: string, resolver: (cid: string) => string | undefined) => string;
+/**
+* Collects the Content-IDs referenced via `cid:` in `src`/`href` attributes.
+* @param html The HTML email.
+* @returns The referenced Content-IDs (de-duplicated, in first-seen order).
+*/
+declare const extractCidReferences: (html: string) => string[];
+/**
+* Inlines `<style>`/linked CSS into element `style` attributes for maximum email-client
+* compatibility, via [juice](https://github.com/Automattic/juice).
+*
+* `juice` is an optional peer dependency — install it (`pnpm add juice`) to use this. It is loaded
+* lazily (via `createRequire`) so importing the render entry point doesn't fail when `juice` is absent.
+* @param html The HTML email.
+* @param options Options forwarded to `juice` (e.g. `preserveImportant`, `removeStyleTags`).
+* @returns The HTML with CSS inlined.
+* @throws {EmailError} When `juice` is not installed or inlining fails.
+*/
+declare const inlineCss: (html: string, options?: Record<string, unknown>) => string;
+/**
+* Options for {@link addDarkModeSupport}.
+*/
+interface DarkModeOptions {
+  /**
+  * Extra CSS to wrap in a `@media (prefers-color-scheme: dark)` block (the dark-mode overrides).
+  */
+  styles?: string;
+}
+/**
+* Adds dark-mode hooks to an HTML email: the `color-scheme` / `supported-color-schemes` meta tags and,
+* when provided, a `@media (prefers-color-scheme: dark)` style block.
+*
+* Injected into `&lt;head>` (created after `&lt;html>` if absent, otherwise prepended).
+* @param html The HTML email.
+* @param options Dark-mode options. See {@link DarkModeOptions}.
+* @returns The HTML with dark-mode support added.
+*/
+declare const addDarkModeSupport: (html: string, options?: DarkModeOptions) => string;
+/**
+* Options for {@link injectPreheader}.
+*/
+interface PreheaderOptions {
+  /**
+  * Append invisible padding characters so the preheader text isn't followed by leaked body content
+  * in the inbox preview.
+  * @default true
+  */
+  spacer?: boolean;
+}
+/**
+* Injects a hidden preheader (inbox preview text) at the start of the HTML body.
+*
+* The preheader is wrapped in a `display:none` element with `mso-hide:all`, followed by zero-width
+* padding so the preview shows only your text. Inserted right after `&lt;body>` (or prepended if no
+* body tag is present).
+* @param html The HTML email.
+* @param preheader The preview text.
+* @param options Injection options. See {@link PreheaderOptions}.
+* @returns The HTML with the preheader injected.
+*/
+declare const injectPreheader: (html: string, preheader: string, options?: PreheaderOptions) => string;
+/**
+* Options for {@link postProcessHtml}. Each step runs only when its option is set; the order is
+* CSS-inline → preheader → dark-mode → CID rewrite.
+*/
+interface PostProcessOptions {
+  /**
+  * Rewrite `cid:` references using this resolver (see {@link rewriteCidLinks}).
+  */
+  cidResolver?: (cid: string) => string | undefined;
+  /**
+  * Add dark-mode hooks. `true` adds the meta tags only; an object also injects dark CSS.
+  */
+  darkMode?: DarkModeOptions | boolean;
+  /**
+  * Inline CSS via `juice`. `true` uses defaults; an object forwards options to `juice`.
+  */
+  inlineCss?: Record<string, unknown> | boolean;
+  /**
+  * Inject hidden preview text at the top of the body.
+  */
+  preheader?: string;
+  /**
+  * Options for the preheader injection.
+  */
+  preheaderOptions?: PreheaderOptions;
+}
+/**
+* Runs an HTML email through the selected post-processing steps.
+*
+* A convenience pipeline over {@link inlineCss}, {@link injectPreheader}, {@link addDarkModeSupport} and
+* {@link rewriteCidLinks}. Only the steps whose options are provided run.
+* @param html The HTML email.
+* @param options Which steps to apply. See {@link PostProcessOptions}.
+* @returns The processed HTML.
+*/
+declare const postProcessHtml: (html: string, options?: PostProcessOptions) => string;
+export { type DarkModeOptions, type PostProcessOptions, type PreheaderOptions, addDarkModeSupport, extractCidReferences, injectPreheader, inlineCss, postProcessHtml, rewriteCidLinks };

package/dist/render/index.js

@@ -0,0 +1 @@
+import{extractCidReferences as o,rewriteCidLinks as t}from"../packem_shared/rewriteCidLinks-B-Sd5XHs.js";import{default as s}from"../packem_shared/inlineCss-BLaEi337.js";import{addDarkModeSupport as f}from"../packem_shared/addDarkModeSupport-Ys9U2-GH.js";import{postProcessHtml as a}from"../packem_shared/postProcessHtml-C73e0b9H.js";import{injectPreheader as x}from"../packem_shared/injectPreheader-BxPjb0eJ.js";export{f as addDarkModeSupport,o as extractCidReferences,x as injectPreheader,s as inlineCss,a as postProcessHtml,t as rewriteCidLinks};

package/dist/template-engines/i18n.d.ts

@@ -0,0 +1,61 @@
+import { T as TemplateRenderer } from "../packem_shared/types.d-nyR1ty1Q.js";
+/**
+* A map of locale code (e.g. `en`, `en-US`, `de`) to that locale's template.
+*
+* The template value is whatever the underlying {@link TemplateRenderer} accepts (a string for
+* Handlebars/MJML/Liquid, a component for react-email/jsx-email, etc.).
+*/
+type LocaleTemplates = Record<string, unknown>;
+/**
+* Options for {@link renderI18n} and {@link createI18nRenderer}.
+*/
+interface I18nRenderOptions {
+  /**
+  * Locale to fall back to when the requested locale (and its language root) is missing.
+  */
+  defaultLocale?: string;
+  /**
+  * Options forwarded to the underlying renderer.
+  */
+  rendererOptions?: Record<string, unknown>;
+}
+/**
+* Resolves the best-matching available locale key: exact match, then the language subtag
+* (`en-US` → `en`), then the default locale.
+* @param templates The available locale templates.
+* @param locale The requested locale.
+* @param defaultLocale Optional fallback locale.
+* @returns The matching key, or `undefined` when nothing matches.
+*/
+declare const resolveLocale: (templates: LocaleTemplates, locale: string, defaultLocale?: string) => string | undefined;
+/**
+* Renders the template for a given locale using the supplied engine, with locale fallback.
+* @param templates The per-locale templates. See {@link LocaleTemplates}.
+* @param locale The requested locale (e.g. `de-AT`).
+* @param renderer The underlying template engine (Handlebars, MJML, Liquid, react-email, …).
+* @param data Data/variables passed to the renderer.
+* @param options Fallback locale and renderer options. See {@link I18nRenderOptions}.
+* @returns The rendered output for the resolved locale.
+* @throws {EmailError} When no template matches the locale or the fallback.
+*/
+declare const renderI18n: (templates: LocaleTemplates, locale: string, renderer: TemplateRenderer, data?: Record<string, unknown>, options?: I18nRenderOptions) => Promise<string>;
+/**
+* A locale-resolving renderer produced by {@link createI18nRenderer}.
+*/
+type LocalizedRenderer = (templates: LocaleTemplates, locale: string, data?: Record<string, unknown>, rendererOptions?: Record<string, unknown>) => Promise<string>;
+/**
+* Creates a reusable localized renderer bound to an engine and default locale.
+* @param renderer The underlying template engine.
+* @param defaultLocale Optional default/fallback locale applied to every call.
+* @returns A {@link LocalizedRenderer}.
+* @example
+* ```ts
+* import { renderHandlebars } from "@visulima/email/template/handlebars";
+* import { createI18nRenderer } from "@visulima/email/template/i18n";
+*
+* const render = createI18nRenderer(renderHandlebars, "en");
+* await render({ en: "Hello {{name}}", de: "Hallo {{name}}" }, "de", { name: "Ada" });
+* ```
+*/
+declare const createI18nRenderer: (renderer: TemplateRenderer, defaultLocale?: string) => LocalizedRenderer;
+export { I18nRenderOptions, LocaleTemplates, LocalizedRenderer, createI18nRenderer, renderI18n, resolveLocale };

package/dist/template-engines/i18n.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var c=(r,e)=>d(r,"name",{value:e,configurable:!0});import i from"../packem_shared/EmailError-zm2ffVav.js";var s=Object.defineProperty,l=c((r,e)=>s(r,"name",{value:e,configurable:!0}),"d");const u=l((r,e,a)=>{const n=new Map(Object.keys(r).map(t=>[t.toLowerCase(),t])),o=l(t=>{if(t!==void 0)return n.get(t.toLowerCase())},"lookup");return o(e)??o(e.split("-")[0])??o(a)},"resolveLocale"),f=l(async(r,e,a,n,o)=>{const t=u(r,e,o?.defaultLocale);if(t===void 0)throw new i("i18n",`No template found for locale "${e}"${o?.defaultLocale?` or default "${o.defaultLocale}"`:""}`);return await a(r[t],n,o?.rendererOptions)},"renderI18n"),v=l((r,e)=>(a,n,o,t)=>f(a,n,r,o,{defaultLocale:e,rendererOptions:t}),"createI18nRenderer");export{v as createI18nRenderer,f as renderI18n,u as resolveLocale};

package/dist/template-engines/jsx-email.d.ts

@@ -0,0 +1,11 @@
+import { T as TemplateRenderer } from "../packem_shared/types.d-nyR1ty1Q.js";
+/**
+* Renders a [jsx-email](https://jsx.email/) component to HTML.
+* @param template The jsx-email component element to render.
+* @param _data Data object (unused; jsx-email components receive props directly).
+* @param options Render options (`plainText`, `pretty`).
+* @returns The rendered HTML (or plain text) string.
+* @throws {EmailError} When `jsx-email` is not installed or rendering fails.
+*/
+declare const jsxEmail: TemplateRenderer;
+export { jsxEmail as default };

package/dist/template-engines/jsx-email.js

@@ -0,0 +1 @@
+var r=Object.defineProperty;var i=(a,t)=>r(a,"name",{value:t,configurable:!0});import s from"../packem_shared/EmailError-zm2ffVav.js";var l=Object.defineProperty,o=i((a,t)=>l(a,"name",{value:t,configurable:!0}),"t");const d=o(async(a,t,n)=>{try{const{render:e}=await import("jsx-email");return await e(a,{plainText:n?.plainText,pretty:n?.pretty})}catch(e){throw e instanceof Error&&(e.code==="ERR_MODULE_NOT_FOUND"||e.message.includes("Cannot find module")||e.message.includes("Cannot find package"))?new s("jsx-email","jsx-email is not installed. Please install it: pnpm add jsx-email",{cause:e}):new s("jsx-email",`Failed to render jsx-email component: ${e.message}`,{cause:e})}},"jsxEmail");export{d as default};

package/dist/template-engines/liquid.d.ts

@@ -0,0 +1,12 @@
+import { T as TemplateRenderer } from "../packem_shared/types.d-nyR1ty1Q.js";
+/**
+* Renders a [LiquidJS](https://liquidjs.com/) template to a string.
+* @param template The Liquid template string.
+* @param data The data/variables exposed to the template.
+* @param options LiquidJS engine options (passed to the `Liquid` constructor).
+* @returns The rendered output.
+* @throws {TypeError} When the template is not a string.
+* @throws {EmailError} When `liquidjs` is not installed or rendering fails.
+*/
+declare const liquid: TemplateRenderer;
+export { liquid as default };

package/dist/template-engines/liquid.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var t=(i,a)=>s(i,"name",{value:a,configurable:!0});import n from"../packem_shared/EmailError-zm2ffVav.js";var d=Object.defineProperty,o=t((i,a)=>d(i,"name",{value:a,configurable:!0}),"i");const c=o(async(i,a,r)=>{try{if(typeof i!="string")throw new TypeError("Liquid template must be a string");const{Liquid:e}=await import("liquidjs");return await new e(r??{}).parseAndRender(i,a??{})}catch(e){throw e instanceof TypeError?e:e instanceof Error&&(e.code==="ERR_MODULE_NOT_FOUND"||e.message.includes("Cannot find module")||e.message.includes("Cannot find package"))?new n("liquid","liquidjs is not installed. Please install it: pnpm add liquidjs",{cause:e}):new n("liquid",`Failed to render Liquid template: ${e.message}`,{cause:e})}},"liquid");export{c as default};