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

package/dist/smtp/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Public TypeScript surface for the optional generic-SMTP transport adapter.
+ *
+ * Import this from your own `"use node"` action to send queued messages over any
+ * SMTP server. The component itself never sends — it records the message and its
+ * status; the SMTP server is host config.
+ */
+/**
+ * Generic SMTP connection config — works with Stalwart, Postfix, or any SMTP
+ * server. Host-supplied; mirrors the subset of nodemailer's transport options
+ * this adapter drives.
+ */
+export interface SmtpConfig {
+    /** SMTP server hostname (e.g. `"smtp.example.com"`, a Stalwart host, a Postfix relay). */
+    host: string;
+    /** SMTP server port (commonly 465 for implicit TLS, 587 for STARTTLS, 25 for relay). */
+    port: number;
+    /**
+     * Use implicit TLS on connect (`true` ⇒ typically port 465). When `false`,
+     * nodemailer upgrades via STARTTLS if the server offers it. Defaults to `true`
+     * when the port is 465, else `false` — set it explicitly to be unambiguous.
+     */
+    secure?: boolean;
+    /** SMTP AUTH credentials. Omit for an unauthenticated relay (e.g. a localhost MTA). */
+    auth?: {
+        /** SMTP AUTH username. */
+        user: string;
+        /** SMTP AUTH password (a secret — keep it server-side; never ships to a client). */
+        pass: string;
+    };
+    /**
+     * Default `From` address used when a {@link SmtpMessage} omits `from`. The host
+     * supplies the opaque address; the adapter never invents one.
+     */
+    from?: string;
+}
+/**
+ * A single outbound message handed to the SMTP transport. Mirrors the queue's
+ * stored fields (`to`/`from` plus the rendered body) without coupling to the
+ * component's storage shape — the host maps a {@link MessageView} payload onto it.
+ */
+export interface SmtpMessage {
+    /** The recipient address (one address or a comma-separated list). */
+    to: string;
+    /** The sender address; falls back to {@link SmtpConfig.from} when omitted. */
+    from?: string;
+    /** The message subject line. */
+    subject?: string;
+    /** The plain-text body. At least one of `text`/`html` should be set. */
+    text?: string;
+    /** The HTML body. At least one of `text`/`html` should be set. */
+    html?: string;
+    /** Optional `Reply-To` address. */
+    replyTo?: string;
+    /** Optional extra SMTP headers (host-supplied, opaque to the adapter). */
+    headers?: Record<string, string>;
+}
+/**
+ * The injected transport seam — the minimal surface {@link sendViaSmtp} drives.
+ * The real implementation is a `nodemailer` transporter; a fake one satisfies the
+ * same shape in tests, so the pure send logic is 100%-coverable with no network.
+ */
+export interface SmtpTransport {
+    /**
+     * Dispatch one message. Returns the transport's own send result; `sendViaSmtp`
+     * normalizes it to a {@link SmtpSendResult}. Throws on a send failure (the host
+     * catches it and calls `markFailed`).
+     */
+    sendMail(options: SmtpMailOptions): Promise<SmtpSendInfo>;
+}
+/**
+ * The mail options passed to {@link SmtpTransport.sendMail} — the nodemailer
+ * `sendMail` argument shape, narrowed to the fields this adapter sets. Declared
+ * locally so the public surface stays dependency-free (no `@types/nodemailer` in
+ * the published types).
+ */
+export interface SmtpMailOptions {
+    to: string;
+    from: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+    replyTo?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * The raw result a transport's `sendMail` resolves with — the nodemailer
+ * `SentMessageInfo` subset this adapter reads. `accepted`/`rejected` are address
+ * lists; `messageId` is the SMTP message handle recorded as the queue's `providerId`.
+ */
+export interface SmtpSendInfo {
+    /** The SMTP message id assigned by the server (recorded as `providerId`). */
+    messageId?: string;
+    /** Addresses the server accepted. */
+    accepted?: ReadonlyArray<string | {
+        address: string;
+    }>;
+    /** Addresses the server rejected. */
+    rejected?: ReadonlyArray<string | {
+        address: string;
+    }>;
+}
+/**
+ * The normalized result of {@link sendViaSmtp}. `messageId` is the transport's
+ * own handle (store it as the queue's `providerId` on `markSent`); `accepted` /
+ * `rejected` are flattened address lists.
+ */
+export interface SmtpSendResult {
+    /** The SMTP message handle, or `""` when the transport returned none. */
+    messageId: string;
+    /** Addresses the server accepted. */
+    accepted: string[];
+    /** Addresses the server rejected (non-empty even on a resolved send is a partial failure). */
+    rejected: string[];
+}
+/**
+ * A bound sender: a function that sends one {@link SmtpMessage} through a
+ * preconfigured transport. {@link createSmtpSender} returns one over a real
+ * `nodemailer` transport; the host calls it inside its own `"use node"` action.
+ */
+export type SmtpSender = (message: SmtpMessage) => Promise<SmtpSendResult>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/smtp/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,IAAI,CAAC,EAAE;QACL,0BAA0B;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,oFAAoF;QACpF,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC3D;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC"}

package/dist/smtp/types.js

@@ -0,0 +1,9 @@
+/**
+ * Public TypeScript surface for the optional generic-SMTP transport adapter.
+ *
+ * Import this from your own `"use node"` action to send queued messages over any
+ * SMTP server. The component itself never sends — it records the message and its
+ * status; the SMTP server is host config.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/smtp/types.js.map

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

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@vllnt/convex-email",
+  "version": "0.1.0-canary.63aca6b",
+  "description": "Durable, transport-agnostic outbound transactional email queue — enqueue, retry, idempotent send, and per-message delivery status as a Convex component",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./smtp": {
+      "types": "./dist/smtp/index.d.ts",
+      "default": "./dist/smtp/index.js"
+    },
+    "./jmap": {
+      "types": "./dist/jmap/index.d.ts",
+      "default": "./dist/jmap/index.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "pnpm convex codegen --component-dir ./src/component && pnpm build",
+    "build:clean": "rm -rf dist *.tsbuildinfo && pnpm build:codegen",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "tsc --noEmit --project tsconfig.ci.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "generate:llms": "node scripts/generate-llms.mjs",
+    "preversion": "pnpm install --frozen-lockfile && pnpm build && pnpm test:coverage && pnpm typecheck && pnpm generate:llms",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "convex": "^1.41.0",
+    "nodemailer": "^8.0.4"
+  },
+  "peerDependenciesMeta": {
+    "nodemailer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "@types/nodemailer": "^8.0.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "@vllnt/eslint-config": "^1.0.0",
+    "@vllnt/typescript": "^1.0.0",
+    "convex": "^1.41.0",
+    "convex-test": "^0.0.53",
+    "eslint": "^9.0.0",
+    "nodemailer": "^8.0.11",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "homepage": "https://github.com/vllnt/convex-email#readme",
+  "bugs": {
+    "url": "https://github.com/vllnt/convex-email/issues"
+  },
+  "author": {
+    "name": "bntvllnt",
+    "url": "https://bntvllnt.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/bntvllnt"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vllnt/convex-email"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "convex",
+    "convex-component",
+    "email",
+    "transactional-email",
+    "email-queue",
+    "transport-agnostic",
+    "smtp",
+    "jmap",
+    "nodemailer"
+  ]
+}

package/src/client/index.ts

@@ -0,0 +1,312 @@
+import type {
+  FunctionArgs,
+  FunctionReference,
+  FunctionReturnType,
+  PaginationOptions,
+  PaginationResult,
+} from "convex/server";
+import type {
+  EmailOptions,
+  EnqueueOptions,
+  EnqueueResult,
+  MarkFailedResult,
+  MessageStatus,
+  MessageView,
+  Parser,
+} from "./types.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_PRUNE_BATCH } from "../shared.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 class Email<TPayload = unknown> {
+  private readonly payloadValidator: Parser<TPayload> | undefined;
+  private readonly maxAttempts: number;
+
+  constructor(
+    private readonly component: EmailComponent,
+    options: EmailOptions<TPayload> = {},
+  ) {
+    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. */
+  private parse(value: unknown): TPayload | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    if (this.payloadValidator === undefined) {
+      return value as TPayload;
+    }
+    return this.payloadValidator(value);
+  }
+
+  /** Project a raw component view into the typed, validated client view. */
+  private view(raw: RawView): MessageView<TPayload> {
+    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: RunMutationCtx,
+    messageId: string,
+    to: string,
+    from: string,
+    transport: string,
+    opts: EnqueueOptions<TPayload> = {},
+  ): Promise<EnqueueResult> {
+    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: RunMutationCtx, messageId: string): Promise<{ attempts: number }> {
+    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: RunMutationCtx,
+    messageId: string,
+    opts: { providerId?: string } = {},
+  ): Promise<null> {
+    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: RunMutationCtx,
+    messageId: string,
+    opts: { error?: string } = {},
+  ): Promise<MarkFailedResult> {
+    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: RunQueryCtx,
+    messageId: string,
+  ): Promise<MessageView<TPayload> | null> {
+    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: RunQueryCtx,
+    status: MessageStatus,
+    paginationOpts: PaginationOptions,
+  ): Promise<PaginationResult<MessageView<TPayload>>> {
+    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: RunMutationCtx,
+    opts: { before?: number; batch?: number } = {},
+  ): Promise<number> {
+    return ctx.runMutation(this.component.mutations.prune, {
+      before: opts.before,
+      batch: opts.batch ?? DEFAULT_PRUNE_BATCH,
+    });
+  }
+}
+
+export type {
+  EmailOptions,
+  EnqueueOptions,
+  EnqueueResult,
+  MarkFailedResult,
+  MessageStatus,
+  MessageView,
+  Parser,
+};

package/src/client/types.ts

@@ -0,0 +1,90 @@
+/** 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;
+}