@vllnt/convex-email 0.1.0-canary.63aca6b

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bntvllnt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,171 @@
+<!-- Badges -->
+[![convex-component](https://img.shields.io/badge/convex-component-EE342F.svg)](https://www.convex.dev/components)
+[![npm](https://img.shields.io/npm/v/@vllnt/convex-email.svg)](https://www.npmjs.com/package/@vllnt/convex-email)
+[![CI](https://github.com/vllnt/convex-email/actions/workflows/ci.yml/badge.svg)](https://github.com/vllnt/convex-email/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@vllnt/convex-email.svg)](./LICENSE)
+
+# @vllnt/convex-email
+
+A durable, transport-agnostic outbound transactional email queue, as a Convex component — the host enqueues a message, its own transport sends it, and clients poll the delivery status.
+
+```ts
+const email = new Email(components.email);
+await email.enqueue(ctx, messageId, to, from, "smtp", { idempotencyKey });
+await email.markSending(ctx, messageId); // host sends, then:
+await email.markSent(ctx, messageId, { providerId }); // or markFailed → auto-retry
+```
+
+## Features
+
+- **Enqueue-and-return** — insert a `queued` message, get its id back; the caller never blocks on the send.
+- **Host-driven transport** — the host claims (`markSending`), sends, and reports (`markSent`/`markFailed`); the component never reaches a provider.
+- **Optional generic SMTP adapter** — `@vllnt/convex-email/smtp` sends through any SMTP server; `nodemailer` is an optional peer dep.
+- **Optional generic JMAP adapter** — `@vllnt/convex-email/jmap` sends over any JMAP server's HTTP API (Stalwart, Fastmail, Cyrus) from a plain action — `fetch`-based, no `"use node"`, no extra dep.
+- **Idempotent enqueue** — an `idempotencyKey` dedups a re-enqueue so a retry can't double-send.
+- **Retry with budget** — `markFailed` re-queues until `attempts` hit `maxAttempts`, then lands in terminal `failed`.
+- **Terminal states are final** — a late or duplicate delivery callback can never overwrite a recorded outcome.
+- **Poll or subscribe** — `get` / `listByStatus` update live in a reactive Convex query.
+- **Server-sourced time, typed opaque payload, bounded prune cron, mount-safe.**
+
+## Installation
+
+```bash
+pnpm add @vllnt/convex-email
+```
+
+Peer dependency: `convex@^1.41.0`. The queue core has zero third-party runtime deps. `nodemailer@^8.0.4` is an optional peer dep — only for the SMTP transport. The JMAP transport (`@vllnt/convex-email/jmap`) is `fetch`-based and needs no extra dependency.
+
+## Usage
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import email from "@vllnt/convex-email/convex.config";
+
+const app = defineApp();
+app.use(email);
+export default app;
+```
+
+```ts
+// convex/notify.ts — host owns auth AND the transport; pass opaque refs in.
+import { components } from "./_generated/api";
+import { mutation, internalAction } from "./_generated/server";
+import { v } from "convex/values";
+import { Email } from "@vllnt/convex-email";
+
+const email = new Email<{ subject: string; html: string }>(components.email, {
+  payloadValidator: v.object({ subject: v.string(), html: v.string() }).parse,
+});
+
+// 1) Enqueue (records intent only) and schedule the send.
+export const sendWelcome = mutation({
+  args: { userId: v.string(), to: v.string() },
+  handler: async (ctx, { userId, to }) => {
+    const messageId = crypto.randomUUID();
+    await email.enqueue(ctx, messageId, to, "no-reply@app.com", "jmap", {
+      payload: { subject: "Welcome", html: "<p>Hello</p>" },
+      idempotencyKey: `welcome:${userId}`, // a retry never double-sends
+    });
+    await ctx.scheduler.runAfter(0, internal.notify.flush, { messageId });
+    return { messageId };
+  },
+});
+
+// 2) The host's transport sender claims, dispatches, and reports the outcome.
+export const flush = internalAction({
+  args: { messageId: v.string() },
+  handler: async (ctx, { messageId }) => {
+    await email.markSending(ctx, messageId);
+    try {
+      const providerId = await sendOverJmap(messageId); // your transport
+      await email.markSent(ctx, messageId, { providerId });
+    } catch (e) {
+      const { retried } = await email.markFailed(ctx, messageId, { error: String(e) });
+      if (retried) await ctx.scheduler.runAfter(backoffMs(), internal.notify.flush, { messageId });
+    }
+  },
+});
+```
+
+## API Reference
+
+| Method | Kind | Result |
+|--------|------|--------|
+| `enqueue(ctx, messageId, to, from, transport, opts?)` | mutation | `{ messageId, deduplicated }` |
+| `markSending(ctx, messageId)` | mutation | `{ attempts }` |
+| `markSent(ctx, messageId, opts?)` | mutation | `null` |
+| `markFailed(ctx, messageId, opts?)` | mutation | `{ status, retried }` |
+| `get(ctx, messageId)` | query | `MessageView \| null` |
+| `listByStatus(ctx, status, paginationOpts)` | query | `PaginationResult<MessageView>` |
+| `prune(ctx, opts?)` | mutation | `number` |
+
+Full reference: [docs/API.md](docs/API.md).
+
+## SMTP transport (optional)
+
+A generic SMTP adapter ships at `@vllnt/convex-email/smtp` — it sends through any SMTP server (Stalwart, Postfix, any relay). The real send runs in the host's own `"use node"` action; the component never sends.
+
+```ts
+import { createSmtpSender } from "@vllnt/convex-email/smtp";
+
+const send = createSmtpSender({
+  host: process.env.SMTP_HOST!,
+  port: 465,
+  secure: true,
+  auth: { user: process.env.SMTP_USER!, pass: process.env.SMTP_PASS! },
+});
+```
+
+Full queue-to-SMTP wiring in [docs/API.md](docs/API.md).
+
+## JMAP transport (optional)
+
+A generic JMAP adapter ships at `@vllnt/convex-email/jmap` — it sends over any JMAP server's HTTP API (Stalwart, Fastmail, Cyrus, Apache James). JMAP is HTTP, so it runs in a **plain Convex action** — no `"use node"`, no `nodemailer`, zero extra deps. It's a protocol, not a vendor: `./jmap`, never `./stalwart`.
+
+```ts
+import { createJmapSender, discoverJmapSession } from "@vllnt/convex-email/jmap";
+
+// Resolve account / identity / Sent mailbox once, then bind a sender over your `fetch`.
+const config = await discoverJmapSession((u, i) => fetch(u, i), {
+  sessionUrl: "https://mail.example.com/.well-known/jmap", // e.g. a Stalwart host
+  token: process.env.JMAP_TOKEN!,
+  from: "no-reply@app.com",
+});
+const send = createJmapSender(config, (u, i) => fetch(u, i));
+```
+
+To send some mail over SMTP and some over Stalwart's HTTP (JMAP), keep **one queue** and route per message by its stored `transport` tag (a `senders` map keyed by `"smtp"` / `"jmap"`). Full JMAP wiring + routing in [docs/API.md](docs/API.md).
+
+## Security
+
+- Auth-agnostic and provider-neutral — the host gates access and drives the transport; the component never authenticates or contacts a provider.
+- Tables are sandboxed (reached only via exported functions); the stored `payload` is opaque.
+- Terminal states are final, enqueue is idempotent, and time is server-sourced.
+
+See [docs/API.md](docs/API.md).
+
+## Testing
+
+```bash
+pnpm test           # single run
+pnpm test:coverage  # enforced 100% on covered files
+```
+
+Tests run against the real component runtime via `convex-test` (`@edge-runtime/vm`), not mocks.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Author
+
+Built by [bntvllnt](https://github.com/bntvllnt) · [bntvllnt.com](https://bntvllnt.com) · [X @bntvllnt](https://x.com/bntvllnt)
+
+Part of the [@vllnt](https://github.com/vllnt) Convex component fleet — [vllnt.com](https://vllnt.com)
+
+If this is useful, [sponsor the work](https://github.com/sponsors/bntvllnt).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client/index.d.ts

@@ -0,0 +1,174 @@
+import type { FunctionArgs, FunctionReference, FunctionReturnType, PaginationOptions, PaginationResult } from "convex/server";
+import type { EmailOptions, EnqueueOptions, EnqueueResult, MarkFailedResult, MessageStatus, MessageView, Parser } from "./types.js";
+/**
+ * The component's raw message view, before the client narrows the opaque host
+ * payload. `payload` is `unknown` here; the {@link Email} client runs the host
+ * validator over it at its typed boundary.
+ */
+type RawView = {
+    messageId: string;
+    to: string;
+    from: string;
+    transport: string;
+    status: MessageStatus;
+    payload?: unknown;
+    subjectRef?: string;
+    idempotencyKey?: string;
+    providerId?: string;
+    attempts: number;
+    maxAttempts: number;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+/**
+ * The email component's function references, as exposed on the host via
+ * `components.email`. The host's stored `payload` is opaque here (`unknown`); the
+ * {@link Email} client narrows it at its own typed boundary.
+ */
+export interface EmailComponent {
+    mutations: {
+        enqueue: FunctionReference<"mutation", "internal", {
+            messageId: string;
+            to: string;
+            from: string;
+            transport: string;
+            payload?: unknown;
+            subjectRef?: string;
+            idempotencyKey?: string;
+            maxAttempts: number;
+        }, {
+            messageId: string;
+            deduplicated: boolean;
+        }>;
+        markSending: FunctionReference<"mutation", "internal", {
+            messageId: string;
+        }, {
+            attempts: number;
+        }>;
+        markSent: FunctionReference<"mutation", "internal", {
+            messageId: string;
+            providerId?: string;
+        }, null>;
+        markFailed: FunctionReference<"mutation", "internal", {
+            messageId: string;
+            error?: string;
+        }, {
+            status: "queued" | "failed";
+            retried: boolean;
+        }>;
+        prune: FunctionReference<"mutation", "internal", {
+            before?: number;
+            batch: number;
+        }, number>;
+    };
+    queries: {
+        get: FunctionReference<"query", "internal", {
+            messageId: string;
+        }, RawView | null>;
+        listByStatus: FunctionReference<"query", "internal", {
+            status: MessageStatus;
+            paginationOpts: PaginationOptions;
+        }, PaginationResult<RawView>>;
+    };
+}
+interface RunQueryCtx {
+    runQuery<Q extends FunctionReference<"query", "internal">>(reference: Q, args: FunctionArgs<Q>): Promise<FunctionReturnType<Q>>;
+}
+interface RunMutationCtx {
+    runMutation<M extends FunctionReference<"mutation", "internal">>(reference: M, args: FunctionArgs<M>): Promise<FunctionReturnType<M>>;
+}
+/**
+ * Consumer-facing client for the durable, transport-agnostic outbound email
+ * queue. A host mutation enqueues a message with `enqueue` and gets its id back;
+ * the host's own transport sender (JMAP, an HTTP API, an SMTP-relay shim — never
+ * a vendor baked into this component) claims it (`markSending`), dispatches it,
+ * and reports the outcome (`markSent` / `markFailed`); `markFailed` retries until
+ * the attempt budget is spent. The component records intent and status — it never
+ * calls a provider. The host owns meaning and auth: it passes opaque `to`/`from`
+ * addresses, a `transport` adapter name, and an opaque `payload` the component
+ * stores without inspecting. Pass `payloadValidator` to narrow that opaque data
+ * to `TPayload` at the boundary — there is no unchecked cast.
+ *
+ * @typeParam TPayload - The host's rendered message payload type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const email = new Email(components.email, {
+ *   payloadValidator: v.object({ subject: v.string(), html: v.string() }).parse,
+ * });
+ * const { messageId } = await email.enqueue(ctx, id, "user@x.com", "no-reply@app.com", "jmap", {
+ *   payload: { subject: "Hi", html: "<p>Welcome</p>" },
+ *   idempotencyKey: `welcome:${userId}`,
+ * });
+ * // ... the host's transport sender:
+ * await email.markSending(ctx, messageId);
+ * await email.markSent(ctx, messageId, { providerId: "jmap-123" });
+ * // ... clients poll:
+ * const msg = await email.get(ctx, messageId);   // typed payload
+ * ```
+ */
+export declare class Email<TPayload = unknown> {
+    private readonly component;
+    private readonly payloadValidator;
+    private readonly maxAttempts;
+    constructor(component: EmailComponent, options?: EmailOptions<TPayload>);
+    /** Narrow an opaque value through the host parser; pass `undefined` and an unset parser through. */
+    private parse;
+    /** Project a raw component view into the typed, validated client view. */
+    private view;
+    /**
+     * Enqueue an outbound message and return its id immediately. `messageId` is
+     * host-supplied and must be unique; `to`/`from` are opaque addresses;
+     * `transport` names the host-configured adapter. `opts.payload` is opaque host
+     * data validated against `payloadValidator` before storage. When
+     * `opts.idempotencyKey` matches an existing message the existing id is returned
+     * (`deduplicated: true`) and no new row is inserted. The message starts
+     * `queued`.
+     */
+    enqueue(ctx: RunMutationCtx, messageId: string, to: string, from: string, transport: string, opts?: EnqueueOptions<TPayload>): Promise<EnqueueResult>;
+    /**
+     * Claim a `queued` message for a send attempt (move it to `sending`, increment
+     * `attempts`). Returns the new attempt count. Rejects a missing id, a terminal
+     * message, and an already-`sending` message (claimed by another sender).
+     */
+    markSending(ctx: RunMutationCtx, messageId: string): Promise<{
+        attempts: number;
+    }>;
+    /**
+     * Record a successful send — the message moves to terminal `sent`, recording
+     * the transport's `opts.providerId`. Idempotent against a replayed callback.
+     * Rejects a missing id and an already-`failed` message.
+     */
+    markSent(ctx: RunMutationCtx, messageId: string, opts?: {
+        providerId?: string;
+    }): Promise<null>;
+    /**
+     * Record a failed send attempt, recording `opts.error`. The message returns to
+     * `queued` for another attempt while attempts remain, or lands in terminal
+     * `failed` once exhausted (see the returned `retried` flag). Rejects a missing
+     * id and an already-terminal message.
+     */
+    markFailed(ctx: RunMutationCtx, messageId: string, opts?: {
+        error?: string;
+    }): Promise<MarkFailedResult>;
+    /** The current envelope for `messageId`, or `null` if no such message is held. */
+    get(ctx: RunQueryCtx, messageId: string): Promise<MessageView<TPayload> | null>;
+    /**
+     * Page messages in one `status`, oldest first. Returns the standard Convex
+     * pagination envelope with each row narrowed to the typed view.
+     */
+    listByStatus(ctx: RunQueryCtx, status: MessageStatus, paginationOpts: PaginationOptions): Promise<PaginationResult<MessageView<TPayload>>>;
+    /**
+     * Delete terminal messages whose `updatedAt < before` in bounded batches,
+     * oldest first. `before` defaults to the server clock; `batch` caps each pass
+     * and the sweep self-reschedules until the tail is clean. Returns the count
+     * removed in the first pass. The built-in daily cron drives this automatically.
+     */
+    prune(ctx: RunMutationCtx, opts?: {
+        before?: number;
+        batch?: number;
+    }): Promise<number>;
+}
+export type { EmailOptions, EnqueueOptions, EnqueueResult, MarkFailedResult, MessageStatus, MessageView, Parser, };
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/index.js

@@ -0,0 +1,151 @@
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_PRUNE_BATCH } from "../shared.js";
+/**
+ * Consumer-facing client for the durable, transport-agnostic outbound email
+ * queue. A host mutation enqueues a message with `enqueue` and gets its id back;
+ * the host's own transport sender (JMAP, an HTTP API, an SMTP-relay shim — never
+ * a vendor baked into this component) claims it (`markSending`), dispatches it,
+ * and reports the outcome (`markSent` / `markFailed`); `markFailed` retries until
+ * the attempt budget is spent. The component records intent and status — it never
+ * calls a provider. The host owns meaning and auth: it passes opaque `to`/`from`
+ * addresses, a `transport` adapter name, and an opaque `payload` the component
+ * stores without inspecting. Pass `payloadValidator` to narrow that opaque data
+ * to `TPayload` at the boundary — there is no unchecked cast.
+ *
+ * @typeParam TPayload - The host's rendered message payload type (defaults to `unknown`).
+ *
+ * @example
+ * ```ts
+ * const email = new Email(components.email, {
+ *   payloadValidator: v.object({ subject: v.string(), html: v.string() }).parse,
+ * });
+ * const { messageId } = await email.enqueue(ctx, id, "user@x.com", "no-reply@app.com", "jmap", {
+ *   payload: { subject: "Hi", html: "<p>Welcome</p>" },
+ *   idempotencyKey: `welcome:${userId}`,
+ * });
+ * // ... the host's transport sender:
+ * await email.markSending(ctx, messageId);
+ * await email.markSent(ctx, messageId, { providerId: "jmap-123" });
+ * // ... clients poll:
+ * const msg = await email.get(ctx, messageId);   // typed payload
+ * ```
+ */
+export class Email {
+    component;
+    payloadValidator;
+    maxAttempts;
+    constructor(component, options = {}) {
+        this.component = component;
+        this.payloadValidator = options.payloadValidator;
+        this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    }
+    /** Narrow an opaque value through the host parser; pass `undefined` and an unset parser through. */
+    parse(value) {
+        if (value === undefined) {
+            return undefined;
+        }
+        if (this.payloadValidator === undefined) {
+            return value;
+        }
+        return this.payloadValidator(value);
+    }
+    /** Project a raw component view into the typed, validated client view. */
+    view(raw) {
+        return {
+            messageId: raw.messageId,
+            to: raw.to,
+            from: raw.from,
+            transport: raw.transport,
+            status: raw.status,
+            payload: this.parse(raw.payload),
+            subjectRef: raw.subjectRef,
+            idempotencyKey: raw.idempotencyKey,
+            providerId: raw.providerId,
+            attempts: raw.attempts,
+            maxAttempts: raw.maxAttempts,
+            error: raw.error,
+            createdAt: raw.createdAt,
+            updatedAt: raw.updatedAt,
+        };
+    }
+    /**
+     * Enqueue an outbound message and return its id immediately. `messageId` is
+     * host-supplied and must be unique; `to`/`from` are opaque addresses;
+     * `transport` names the host-configured adapter. `opts.payload` is opaque host
+     * data validated against `payloadValidator` before storage. When
+     * `opts.idempotencyKey` matches an existing message the existing id is returned
+     * (`deduplicated: true`) and no new row is inserted. The message starts
+     * `queued`.
+     */
+    enqueue(ctx, messageId, to, from, transport, opts = {}) {
+        return ctx.runMutation(this.component.mutations.enqueue, {
+            messageId,
+            to,
+            from,
+            transport,
+            payload: opts.payload === undefined ? undefined : this.parse(opts.payload),
+            subjectRef: opts.subjectRef,
+            idempotencyKey: opts.idempotencyKey,
+            maxAttempts: opts.maxAttempts ?? this.maxAttempts,
+        });
+    }
+    /**
+     * Claim a `queued` message for a send attempt (move it to `sending`, increment
+     * `attempts`). Returns the new attempt count. Rejects a missing id, a terminal
+     * message, and an already-`sending` message (claimed by another sender).
+     */
+    markSending(ctx, messageId) {
+        return ctx.runMutation(this.component.mutations.markSending, { messageId });
+    }
+    /**
+     * Record a successful send — the message moves to terminal `sent`, recording
+     * the transport's `opts.providerId`. Idempotent against a replayed callback.
+     * Rejects a missing id and an already-`failed` message.
+     */
+    markSent(ctx, messageId, opts = {}) {
+        return ctx.runMutation(this.component.mutations.markSent, {
+            messageId,
+            providerId: opts.providerId,
+        });
+    }
+    /**
+     * Record a failed send attempt, recording `opts.error`. The message returns to
+     * `queued` for another attempt while attempts remain, or lands in terminal
+     * `failed` once exhausted (see the returned `retried` flag). Rejects a missing
+     * id and an already-terminal message.
+     */
+    markFailed(ctx, messageId, opts = {}) {
+        return ctx.runMutation(this.component.mutations.markFailed, {
+            messageId,
+            error: opts.error,
+        });
+    }
+    /** The current envelope for `messageId`, or `null` if no such message is held. */
+    async get(ctx, messageId) {
+        const raw = await ctx.runQuery(this.component.queries.get, { messageId });
+        return raw === null ? null : this.view(raw);
+    }
+    /**
+     * Page messages in one `status`, oldest first. Returns the standard Convex
+     * pagination envelope with each row narrowed to the typed view.
+     */
+    async listByStatus(ctx, status, paginationOpts) {
+        const result = await ctx.runQuery(this.component.queries.listByStatus, {
+            status,
+            paginationOpts,
+        });
+        return { ...result, page: result.page.map((raw) => this.view(raw)) };
+    }
+    /**
+     * Delete terminal messages whose `updatedAt < before` in bounded batches,
+     * oldest first. `before` defaults to the server clock; `batch` caps each pass
+     * and the sweep self-reschedules until the tail is clean. Returns the count
+     * removed in the first pass. The built-in daily cron drives this automatically.
+     */
+    prune(ctx, opts = {}) {
+        return ctx.runMutation(this.component.mutations.prune, {
+            before: opts.before,
+            batch: opts.batch ?? DEFAULT_PRUNE_BATCH,
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/types.d.ts

@@ -0,0 +1,84 @@
+/** Public TypeScript surface for the email client. */
+/** The four lifecycle states a message moves through. */
+export type MessageStatus = "queued" | "sending" | "sent" | "failed";
+/**
+ * Validates and narrows the opaque stored `payload` to a host type `T` at the
+ * client boundary. Receives the raw value the component returned (`unknown`) and
+ * MUST return a typed `T` or throw. A `convex/values` validator's `.parse` (or a
+ * Zod `.parse`) fits directly; omit it to keep the value unvalidated.
+ *
+ * @typeParam T - The host's stored message `payload` type.
+ */
+export type Parser<T> = (value: unknown) => T;
+/** The public envelope returned by {@link Email.get}. */
+export interface MessageView<TPayload = unknown> {
+    /** The host-supplied id naming this message. */
+    messageId: string;
+    /** The opaque destination address. */
+    to: string;
+    /** The opaque sender address. */
+    from: string;
+    /** The host-configured transport adapter this message is routed through. */
+    transport: string;
+    /** The current lifecycle status. */
+    status: MessageStatus;
+    /** The opaque rendered message payload (narrowed if a `payloadValidator` is set). */
+    payload?: TPayload;
+    /** An opaque host ref for subject-centric listing (e.g. the addressee subject). */
+    subjectRef?: string;
+    /** The dedup key, if the message was enqueued with one. */
+    idempotencyKey?: string;
+    /** The transport's own message handle, recorded once `sent`. */
+    providerId?: string;
+    /** The number of send attempts made so far. */
+    attempts: number;
+    /** The maximum send attempts before a failure is terminal. */
+    maxAttempts: number;
+    /** The host-supplied failure reason from the last failed attempt. */
+    error?: string;
+    /** Absolute ms timestamp the message was enqueued. */
+    createdAt: number;
+    /** Absolute ms timestamp of the last transition. */
+    updatedAt: number;
+}
+/** The result of {@link Email.enqueue}. */
+export interface EnqueueResult {
+    /** The id of the queued message — the existing one when `deduplicated`. */
+    messageId: string;
+    /** True when an existing `idempotencyKey` matched and no new row was inserted. */
+    deduplicated: boolean;
+}
+/** Per-call options for {@link Email.enqueue}. */
+export interface EnqueueOptions<TPayload> {
+    /** The opaque rendered message payload (validated against `payloadValidator` before storage). */
+    payload?: TPayload;
+    /** An opaque host ref recorded for subject-centric listing. */
+    subjectRef?: string;
+    /** A dedup key — a second enqueue carrying the same key returns the existing message. */
+    idempotencyKey?: string;
+    /** Override the client-level `maxAttempts` for this message. */
+    maxAttempts?: number;
+}
+/** The result of {@link Email.markFailed}. */
+export interface MarkFailedResult {
+    /** `queued` when the message was re-queued for retry, `failed` when terminal. */
+    status: "queued" | "failed";
+    /** True when the message was re-queued (attempts remained), false when terminal. */
+    retried: boolean;
+}
+/** Construction options for the {@link Email} client. */
+export interface EmailOptions<TPayload> {
+    /**
+     * Validates/narrows a stored `payload` to `TPayload` at the boundary — applied
+     * to the `payload` passed into `enqueue` (before storage) and the `payload`
+     * returned by `get` / `listByStatus`. Throws on a mismatch. Omit to leave the
+     * payload unvalidated.
+     */
+    payloadValidator?: Parser<TPayload>;
+    /**
+     * The default maximum send attempts before a `markFailed` is terminal. Per-call
+     * `enqueue` `maxAttempts` overrides it. Defaults to `DEFAULT_MAX_ATTEMPTS` (5).
+     */
+    maxAttempts?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AAEtD,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;AAE9C,yDAAyD;AACzD,MAAM,WAAW,WAAW,CAAC,QAAQ,GAAG,OAAO;IAC7C,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,qFAAqF;IACrF,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc,CAAC,QAAQ;IACtC,iGAAiG;IACjG,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY,CAAC,QAAQ;IACpC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/client/types.js

@@ -0,0 +1,3 @@
+/** Public TypeScript surface for the email client. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,sDAAsD"}