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

package/dist/jmap/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Public TypeScript surface for the optional generic-JMAP transport adapter.
+ *
+ * Import this from your own Convex action to send queued messages over any JMAP
+ * server's HTTP API — Stalwart, Fastmail, Cyrus, Apache James. JMAP is an open
+ * protocol (RFC 8620 core + 8621 mail/submission), so this adapter is generic
+ * over any JMAP server: the server is host config, never baked in. The component
+ * itself never sends — it records the message and its status.
+ *
+ * Unlike the SMTP adapter, this layer is **pure**: it drives an injected
+ * {@link JmapFetch} (the host's runtime `fetch`), so it needs no Node runtime,
+ * no `"use node"` action, and no third-party dependency, and is 100%-coverable
+ * with a fake `fetch`.
+ */
+/** The minimal `Response` subset {@link JmapFetch} resolves with. */
+export interface JmapResponse {
+    /** Whether the HTTP status is in the 2xx range. */
+    ok: boolean;
+    /** The HTTP status code. */
+    status: number;
+    /** Parse the response body as JSON. */
+    json(): Promise<unknown>;
+}
+/** The minimal `RequestInit` subset the adapter passes to {@link JmapFetch}. */
+export interface JmapRequestInit {
+    /** HTTP method (`"GET"` for session discovery, `"POST"` for the JMAP API). */
+    method: string;
+    /** Request headers — always carries `Authorization` and (for POST) `Content-Type`. */
+    headers: Record<string, string>;
+    /** The JSON request body (POST only). */
+    body?: string;
+}
+/**
+ * The injected `fetch` seam — the minimal surface the adapter drives. The host
+ * passes its runtime `fetch` (`(url, init) => fetch(url, init)` in a Convex
+ * action); a fake one satisfies the same shape in tests, so the whole adapter is
+ * 100%-coverable with no network.
+ */
+export type JmapFetch = (url: string, init: JmapRequestInit) => Promise<JmapResponse>;
+/**
+ * Resolved JMAP connection config — everything {@link sendViaJmap} needs to send.
+ * Host-supplied, or produced by {@link discoverJmapSession}. Generic over any
+ * JMAP server: Stalwart is one configured endpoint, never baked in.
+ */
+export interface JmapConfig {
+    /** The JMAP API endpoint the method calls POST to (the session's `apiUrl`, e.g. `https://mail.example.com/jmap`). */
+    endpoint: string;
+    /** The bearer access token (a secret — keep it server-side; never ships to a client). */
+    token: string;
+    /** The JMAP account id that owns the mailbox/identity (the `urn:ietf:params:jmap:mail` primary account). */
+    accountId: string;
+    /** The sending identity id (an `Identity` whose address matches `from`). */
+    identityId: string;
+    /** The mailbox the sent copy is filed in (typically the Sent mailbox; a JMAP `Email` must belong to a mailbox). */
+    mailboxId: string;
+    /** Default `From` address used when a {@link JmapMessage} omits `from`. */
+    from?: string;
+}
+/**
+ * A single outbound message handed to the JMAP 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 stored payload onto it. Identical
+ * shape to the SMTP adapter's message so a host can target either transport.
+ */
+export interface JmapMessage {
+    /** The recipient address (one address or a comma-separated list). */
+    to: string;
+    /** The sender address; falls back to {@link JmapConfig.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 headers (host-supplied, set as JMAP `header:Name:asText` properties). */
+    headers?: Record<string, string>;
+}
+/**
+ * The normalized result of {@link sendViaJmap}. `messageId` is the JMAP
+ * `EmailSubmission` id (store it as the queue's `providerId` on `markSent`);
+ * `emailId` is the created `Email` object id.
+ */
+export interface JmapSendResult {
+    /** The `EmailSubmission` id (or the `Email` id if the server returned no submission id) — store as the queue `providerId`. */
+    messageId: string;
+    /** The created `Email` object id. */
+    emailId: string;
+}
+/**
+ * A bound sender: a function that sends one {@link JmapMessage} through a
+ * preconfigured endpoint + `fetch`. {@link createJmapSender} returns one; the
+ * host calls it inside its own Convex action.
+ */
+export type JmapSender = (message: JmapMessage) => Promise<JmapSendResult>;
+/** Options for {@link discoverJmapSession} — resolve a {@link JmapConfig} from a JMAP session. */
+export interface JmapDiscoverOptions {
+    /** The JMAP session resource URL (e.g. `https://mail.example.com/.well-known/jmap`). */
+    sessionUrl: string;
+    /** The bearer access token. */
+    token: string;
+    /** Pick the sending identity whose address matches this `from`; otherwise the first identity is used (and becomes the config default `from`). */
+    from?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jmap/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,EAAE,EAAE,OAAO,CAAC;IACZ,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,eAAe,KAClB,OAAO,CAAC,YAAY,CAAC,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,qHAAqH;IACrH,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,4GAA4G;IAC5G,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,mHAAmH;IACnH,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;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,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,8HAA8H;IAC9H,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAE3E,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,iJAAiJ;IACjJ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/jmap/types.js

@@ -0,0 +1,16 @@
+/**
+ * Public TypeScript surface for the optional generic-JMAP transport adapter.
+ *
+ * Import this from your own Convex action to send queued messages over any JMAP
+ * server's HTTP API — Stalwart, Fastmail, Cyrus, Apache James. JMAP is an open
+ * protocol (RFC 8620 core + 8621 mail/submission), so this adapter is generic
+ * over any JMAP server: the server is host config, never baked in. The component
+ * itself never sends — it records the message and its status.
+ *
+ * Unlike the SMTP adapter, this layer is **pure**: it drives an injected
+ * {@link JmapFetch} (the host's runtime `fetch`), so it needs no Node runtime,
+ * no `"use node"` action, and no third-party dependency, and is 100%-coverable
+ * with a fake `fetch`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jmap/types.js.map

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

package/dist/shared.d.ts

@@ -0,0 +1,32 @@
+/** Shared constants used by both `client/` and `component/`. */
+export declare const COMPONENT_NAME = "email";
+/**
+ * The standard message lifecycle states. `queued` is the freshly-enqueued state;
+ * the host's transport sender claims it (`sending`), then records a terminal
+ * `sent` or `failed`. A `sending` message can return to `queued` for a retry
+ * while attempts remain. Terminal states are final — once `sent`, or `failed`
+ * with attempts exhausted, the message never transitions again.
+ */
+export declare const MESSAGE_STATUSES: readonly ["queued", "sending", "sent", "failed"];
+/** A single message lifecycle status. */
+export type MessageStatus = (typeof MESSAGE_STATUSES)[number];
+/** The two terminal states — once reached, a message never transitions again. */
+export declare const TERMINAL_STATUSES: ReadonlySet<MessageStatus>;
+/**
+ * Default maximum send attempts before a `markFailed` is permanent (the message
+ * lands in terminal `failed` instead of returning to `queued` for another
+ * attempt). The host owns the actual transport send and reports each outcome; the
+ * component only counts attempts and decides retry-vs-terminal. A per-message
+ * override is accepted at `enqueue`; this is the client-level default.
+ */
+export declare const DEFAULT_MAX_ATTEMPTS = 5;
+/**
+ * Default retention (ms) for terminal messages before the prune cron sweeps them:
+ * 30 days. Bounds unbounded growth of the `messages` table while leaving a
+ * generous audit window for delivery records. A host that wants a different
+ * window drives `prune` from its own scheduler with an explicit `before` cutoff.
+ */
+export declare const DEFAULT_RETENTION_MS = 2592000000;
+/** Default page size for a `prune` pass before the sweep self-reschedules. */
+export declare const DEFAULT_PRUNE_BATCH = 200;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,kDAAmD,CAAC;AAEjF,yCAAyC;AACzC,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,aAAa,CAGvD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,aAAgB,CAAC;AAElD,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/shared.js

@@ -0,0 +1,33 @@
+/** Shared constants used by both `client/` and `component/`. */
+export const COMPONENT_NAME = "email";
+/**
+ * The standard message lifecycle states. `queued` is the freshly-enqueued state;
+ * the host's transport sender claims it (`sending`), then records a terminal
+ * `sent` or `failed`. A `sending` message can return to `queued` for a retry
+ * while attempts remain. Terminal states are final — once `sent`, or `failed`
+ * with attempts exhausted, the message never transitions again.
+ */
+export const MESSAGE_STATUSES = ["queued", "sending", "sent", "failed"];
+/** The two terminal states — once reached, a message never transitions again. */
+export const TERMINAL_STATUSES = new Set([
+    "sent",
+    "failed",
+]);
+/**
+ * Default maximum send attempts before a `markFailed` is permanent (the message
+ * lands in terminal `failed` instead of returning to `queued` for another
+ * attempt). The host owns the actual transport send and reports each outcome; the
+ * component only counts attempts and decides retry-vs-terminal. A per-message
+ * override is accepted at `enqueue`; this is the client-level default.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 5;
+/**
+ * Default retention (ms) for terminal messages before the prune cron sweeps them:
+ * 30 days. Bounds unbounded growth of the `messages` table while leaving a
+ * generous audit window for delivery records. A host that wants a different
+ * window drives `prune` from its own scheduler with an explicit `before` cutoff.
+ */
+export const DEFAULT_RETENTION_MS = 2_592_000_000;
+/** Default page size for a `prune` pass before the sweep self-reschedules. */
+export const DEFAULT_PRUNE_BATCH = 200;
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAKjF,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAA+B,IAAI,GAAG,CAAC;IACnE,MAAM;IACN,QAAQ;CACT,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAElD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC"}

package/dist/smtp/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The optional generic-SMTP transport adapter — a host-side `./smtp` entry the
+ * host imports into its OWN `"use node"` action to actually send queued messages
+ * over SMTP (Stalwart, Postfix, any server). It is NOT part of the sandboxed
+ * component: a Convex component runs in V8 and cannot open a raw SMTP socket or
+ * ship a `"use node"` action, so the real send is host-side glue.
+ *
+ * Tree-shake boundary: a backend-only consumer importing `@vllnt/convex-email`
+ * (the `.` entry) pulls ZERO SMTP code and no `nodemailer`. Importing this `./smtp`
+ * entry is the explicit opt-in; `nodemailer` is an optional peer dep loaded only
+ * by {@link createSmtpTransport} / {@link createSmtpSender} here.
+ *
+ * Two layers:
+ * - pure + 100%-covered: {@link sendViaSmtp}, {@link validateSmtpConfig},
+ *   {@link toMailOptions} — driven by an injected transport, unit-tested with a fake.
+ * - thin Node wrapper (coverage-excluded): {@link createSmtpTransport},
+ *   {@link createSmtpSender} — the real `nodemailer.createTransport`, consumer-E2E verified.
+ */
+export { sendViaSmtp, validateSmtpConfig, toMailOptions } from "./send.js";
+export { createSmtpTransport, createSmtpSender } from "./transport.js";
+export type { SmtpConfig, SmtpMessage, SmtpMailOptions, SmtpSendInfo, SmtpSendResult, SmtpSender, SmtpTransport, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/smtp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvE,YAAY,EACV,UAAU,EACV,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/smtp/index.js

@@ -0,0 +1,21 @@
+/**
+ * The optional generic-SMTP transport adapter — a host-side `./smtp` entry the
+ * host imports into its OWN `"use node"` action to actually send queued messages
+ * over SMTP (Stalwart, Postfix, any server). It is NOT part of the sandboxed
+ * component: a Convex component runs in V8 and cannot open a raw SMTP socket or
+ * ship a `"use node"` action, so the real send is host-side glue.
+ *
+ * Tree-shake boundary: a backend-only consumer importing `@vllnt/convex-email`
+ * (the `.` entry) pulls ZERO SMTP code and no `nodemailer`. Importing this `./smtp`
+ * entry is the explicit opt-in; `nodemailer` is an optional peer dep loaded only
+ * by {@link createSmtpTransport} / {@link createSmtpSender} here.
+ *
+ * Two layers:
+ * - pure + 100%-covered: {@link sendViaSmtp}, {@link validateSmtpConfig},
+ *   {@link toMailOptions} — driven by an injected transport, unit-tested with a fake.
+ * - thin Node wrapper (coverage-excluded): {@link createSmtpTransport},
+ *   {@link createSmtpSender} — the real `nodemailer.createTransport`, consumer-E2E verified.
+ */
+export { sendViaSmtp, validateSmtpConfig, toMailOptions } from "./send.js";
+export { createSmtpTransport, createSmtpSender } from "./transport.js";
+//# sourceMappingURL=index.js.map

package/dist/smtp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/smtp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/smtp/send.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure, injectable generic-SMTP send logic. Everything here is runtime-neutral
+ * and network-free: {@link sendViaSmtp} drives an injected {@link SmtpTransport},
+ * so a fake transport gives full coverage with no socket. The only piece that
+ * needs Node is the thin real-`nodemailer` wrapper in `./transport` (excluded
+ * from coverage, consumer-E2E verified).
+ */
+import type { SmtpConfig, SmtpMailOptions, SmtpMessage, SmtpSendResult, SmtpTransport } from "./types.js";
+/**
+ * Validate and normalize a host-supplied {@link SmtpConfig}, returning a config
+ * with `secure` resolved (defaults to `true` for port 465, else `false`). Throws
+ * a plain `Error` on an invalid config — the host surfaces it. Pure: no I/O.
+ *
+ * @param config - The raw host SMTP config.
+ * @returns The same config with `secure` resolved to a concrete boolean.
+ */
+export declare function validateSmtpConfig(config: SmtpConfig): SmtpConfig & {
+    secure: boolean;
+};
+/**
+ * Build the transport `sendMail` options from a {@link SmtpMessage} and the
+ * resolved config, resolving `from` (message → config default) and guarding the
+ * address/subject/header fields against SMTP header (CRLF) injection. Pure.
+ *
+ * @param message - The outbound message.
+ * @param config - The resolved SMTP config (for the `from` default).
+ * @returns The mail options to hand to {@link SmtpTransport.sendMail}.
+ */
+export declare function toMailOptions(message: SmtpMessage, config: Pick<SmtpConfig, "from">): SmtpMailOptions;
+/**
+ * Send one {@link SmtpMessage} through an injected {@link SmtpTransport} and
+ * return a normalized {@link SmtpSendResult}. This is the pure, testable core:
+ * pass a real `nodemailer` transport in the host's `"use node"` action, or a fake
+ * one in a unit test. Throws when the transport throws (the host catches it and
+ * calls `markFailed`).
+ *
+ * @param transport - The injected transport (real nodemailer or a fake).
+ * @param message - The message to send.
+ * @param config - The resolved config, for the `from` default.
+ * @returns The normalized send result — store `messageId` as the queue `providerId`.
+ *
+ * @example
+ * ```ts
+ * // host "use node" action:
+ * const transport = createSmtpTransport(config);   // real nodemailer
+ * const { messageId } = await sendViaSmtp(transport, { to, html }, config);
+ * await email.markSent(ctx, id, { providerId: messageId });
+ * ```
+ */
+export declare function sendViaSmtp(transport: SmtpTransport, message: SmtpMessage, config?: Pick<SmtpConfig, "from">): Promise<SmtpSendResult>;
+//# sourceMappingURL=send.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../src/smtp/send.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,WAAW,EAEX,cAAc,EACd,aAAa,EACd,MAAM,YAAY,CAAC;AAKpB;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,GACjB,UAAU,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAsBlC;AASD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,GAC/B,eAAe,CAoCjB;AAgBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,WAAW,EACpB,MAAM,GAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAM,GACpC,OAAO,CAAC,cAAc,CAAC,CAIzB"}

package/dist/smtp/send.js

@@ -0,0 +1,124 @@
+/**
+ * Pure, injectable generic-SMTP send logic. Everything here is runtime-neutral
+ * and network-free: {@link sendViaSmtp} drives an injected {@link SmtpTransport},
+ * so a fake transport gives full coverage with no socket. The only piece that
+ * needs Node is the thin real-`nodemailer` wrapper in `./transport` (excluded
+ * from coverage, consumer-E2E verified).
+ */
+/** A control character (CR/LF) that must never reach a raw SMTP header. */
+const CRLF = /[\r\n]/;
+/**
+ * Validate and normalize a host-supplied {@link SmtpConfig}, returning a config
+ * with `secure` resolved (defaults to `true` for port 465, else `false`). Throws
+ * a plain `Error` on an invalid config — the host surfaces it. Pure: no I/O.
+ *
+ * @param config - The raw host SMTP config.
+ * @returns The same config with `secure` resolved to a concrete boolean.
+ */
+export function validateSmtpConfig(config) {
+    if (typeof config.host !== "string" || config.host.trim() === "") {
+        throw new Error("smtp config: `host` must be a non-empty string");
+    }
+    if (typeof config.port !== "number" ||
+        !Number.isInteger(config.port) ||
+        config.port <= 0 ||
+        config.port > 65535) {
+        throw new Error("smtp config: `port` must be an integer in 1..65535");
+    }
+    if (config.auth !== undefined) {
+        if (typeof config.auth.user !== "string" ||
+            typeof config.auth.pass !== "string") {
+            throw new Error("smtp config: `auth` requires string `user` and `pass`");
+        }
+    }
+    const secure = config.secure ?? config.port === 465;
+    return { ...config, secure };
+}
+/** Guard a single address-like header value against CRLF injection. */
+function assertNoCrlf(label, value) {
+    if (CRLF.test(value)) {
+        throw new Error(`smtp message: \`${label}\` must not contain CR or LF`);
+    }
+}
+/**
+ * Build the transport `sendMail` options from a {@link SmtpMessage} and the
+ * resolved config, resolving `from` (message → config default) and guarding the
+ * address/subject/header fields against SMTP header (CRLF) injection. Pure.
+ *
+ * @param message - The outbound message.
+ * @param config - The resolved SMTP config (for the `from` default).
+ * @returns The mail options to hand to {@link SmtpTransport.sendMail}.
+ */
+export function toMailOptions(message, config) {
+    if (typeof message.to !== "string" || message.to.trim() === "") {
+        throw new Error("smtp message: `to` must be a non-empty string");
+    }
+    const from = message.from ?? config.from;
+    if (from === undefined || from.trim() === "") {
+        throw new Error("smtp message: `from` is required (pass `message.from` or `config.from`)");
+    }
+    if (message.text === undefined && message.html === undefined) {
+        throw new Error("smtp message: one of `text` or `html` is required");
+    }
+    assertNoCrlf("to", message.to);
+    assertNoCrlf("from", from);
+    if (message.replyTo !== undefined) {
+        assertNoCrlf("replyTo", message.replyTo);
+    }
+    if (message.subject !== undefined) {
+        assertNoCrlf("subject", message.subject);
+    }
+    if (message.headers !== undefined) {
+        for (const [key, value] of Object.entries(message.headers)) {
+            assertNoCrlf(`headers.${key}`, key);
+            assertNoCrlf(`headers.${key}`, value);
+        }
+    }
+    return {
+        to: message.to,
+        from,
+        subject: message.subject,
+        text: message.text,
+        html: message.html,
+        replyTo: message.replyTo,
+        headers: message.headers,
+    };
+}
+/** Flatten a nodemailer address entry (string or `{ address }`) to a string. */
+function addressOf(entry) {
+    return typeof entry === "string" ? entry : entry.address;
+}
+/** Normalize a transport's raw send info into the public {@link SmtpSendResult}. */
+function toSendResult(info) {
+    return {
+        messageId: info.messageId ?? "",
+        accepted: (info.accepted ?? []).map(addressOf),
+        rejected: (info.rejected ?? []).map(addressOf),
+    };
+}
+/**
+ * Send one {@link SmtpMessage} through an injected {@link SmtpTransport} and
+ * return a normalized {@link SmtpSendResult}. This is the pure, testable core:
+ * pass a real `nodemailer` transport in the host's `"use node"` action, or a fake
+ * one in a unit test. Throws when the transport throws (the host catches it and
+ * calls `markFailed`).
+ *
+ * @param transport - The injected transport (real nodemailer or a fake).
+ * @param message - The message to send.
+ * @param config - The resolved config, for the `from` default.
+ * @returns The normalized send result — store `messageId` as the queue `providerId`.
+ *
+ * @example
+ * ```ts
+ * // host "use node" action:
+ * const transport = createSmtpTransport(config);   // real nodemailer
+ * const { messageId } = await sendViaSmtp(transport, { to, html }, config);
+ * await email.markSent(ctx, id, { providerId: messageId });
+ * ```
+ */
+export async function sendViaSmtp(transport, message, config = {}) {
+    const options = toMailOptions(message, config);
+    const info = await transport.sendMail(options);
+    return toSendResult(info);
+}
+//# sourceMappingURL=send.js.map

package/dist/smtp/send.js.map

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

package/dist/smtp/transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The thin real-`nodemailer` wrapper — the ONLY piece that needs Node (raw SMTP
+ * sockets). It builds a real transport from a host {@link SmtpConfig} and binds it
+ * to {@link sendViaSmtp}. The host imports this from its OWN `"use node"` action;
+ * a Convex component runs in V8 and cannot host a Node action, so this never runs
+ * inside the sandboxed component.
+ *
+ * `nodemailer` is an **optional peer dependency** — the queue core installs and
+ * runs with zero third-party runtime deps. This module is import-tested only when
+ * the host opts into SMTP. It is **excluded from `coverage.include`**: it is a
+ * trivial pass-through to the real library, consumer-E2E verified (exactly as the
+ * `./react` live-backend integration is the consuming app's E2E). The pure
+ * {@link sendViaSmtp} + config validation it delegates to ARE covered at 100%.
+ */
+import type { SmtpConfig, SmtpSender, SmtpTransport } from "./types.js";
+/**
+ * Build a real `nodemailer` SMTP transport from a host {@link SmtpConfig}. The
+ * config is validated first (throws on an invalid one). Generic over any SMTP
+ * server — Stalwart, Postfix, anything — the host supplies the connection.
+ *
+ * @param config - The host SMTP connection config.
+ * @returns A {@link SmtpTransport} backed by `nodemailer.createTransport`.
+ */
+export declare function createSmtpTransport(config: SmtpConfig): SmtpTransport;
+/**
+ * Build a bound {@link SmtpSender} over a real `nodemailer` transport: a function
+ * that sends one message and returns the normalized result. This is the one call
+ * a host wires into its `"use node"` flush action.
+ *
+ * @param config - The host SMTP connection config.
+ * @returns A sender that dispatches one {@link SmtpMessage} via the configured server.
+ *
+ * @example
+ * ```ts
+ * "use node";
+ * 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! } });
+ * const { messageId } = await send({ to, from, subject, html });
+ * ```
+ */
+export declare function createSmtpSender(config: SmtpConfig): SmtpSender;
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/smtp/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAQrE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAG/D"}

package/dist/smtp/transport.js

@@ -0,0 +1,55 @@
+/**
+ * The thin real-`nodemailer` wrapper — the ONLY piece that needs Node (raw SMTP
+ * sockets). It builds a real transport from a host {@link SmtpConfig} and binds it
+ * to {@link sendViaSmtp}. The host imports this from its OWN `"use node"` action;
+ * a Convex component runs in V8 and cannot host a Node action, so this never runs
+ * inside the sandboxed component.
+ *
+ * `nodemailer` is an **optional peer dependency** — the queue core installs and
+ * runs with zero third-party runtime deps. This module is import-tested only when
+ * the host opts into SMTP. It is **excluded from `coverage.include`**: it is a
+ * trivial pass-through to the real library, consumer-E2E verified (exactly as the
+ * `./react` live-backend integration is the consuming app's E2E). The pure
+ * {@link sendViaSmtp} + config validation it delegates to ARE covered at 100%.
+ */
+import nodemailer from "nodemailer";
+import { sendViaSmtp, validateSmtpConfig } from "./send.js";
+/**
+ * Build a real `nodemailer` SMTP transport from a host {@link SmtpConfig}. The
+ * config is validated first (throws on an invalid one). Generic over any SMTP
+ * server — Stalwart, Postfix, anything — the host supplies the connection.
+ *
+ * @param config - The host SMTP connection config.
+ * @returns A {@link SmtpTransport} backed by `nodemailer.createTransport`.
+ */
+export function createSmtpTransport(config) {
+    const resolved = validateSmtpConfig(config);
+    return nodemailer.createTransport({
+        host: resolved.host,
+        port: resolved.port,
+        secure: resolved.secure,
+        auth: resolved.auth,
+    });
+}
+/**
+ * Build a bound {@link SmtpSender} over a real `nodemailer` transport: a function
+ * that sends one message and returns the normalized result. This is the one call
+ * a host wires into its `"use node"` flush action.
+ *
+ * @param config - The host SMTP connection config.
+ * @returns A sender that dispatches one {@link SmtpMessage} via the configured server.
+ *
+ * @example
+ * ```ts
+ * "use node";
+ * 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! } });
+ * const { messageId } = await send({ to, from, subject, html });
+ * ```
+ */
+export function createSmtpSender(config) {
+    const transport = createSmtpTransport(config);
+    return (message) => sendViaSmtp(transport, message, config);
+}
+//# sourceMappingURL=transport.js.map

package/dist/smtp/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/smtp/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAG5D;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,UAAU,CAAC,eAAe,CAAC;QAChC,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;KACpB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IACjD,MAAM,SAAS,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC9C,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC"}