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

package/src/smtp/send.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "vitest";
+import { sendViaSmtp, toMailOptions, validateSmtpConfig } from "./send.js";
+import type { SmtpMailOptions, SmtpSendInfo, SmtpTransport } from "./types.js";
+
+/** A fake transport: records the options it received and returns a canned info. */
+function fakeTransport(info: SmtpSendInfo): {
+  transport: SmtpTransport;
+  calls: SmtpMailOptions[];
+} {
+  const calls: SmtpMailOptions[] = [];
+  const transport: SmtpTransport = {
+    sendMail: (options) => {
+      calls.push(options);
+      return Promise.resolve(info);
+    },
+  };
+  return { calls, transport };
+}
+
+describe("validateSmtpConfig", () => {
+  test("resolves secure=true for port 465 by default", () => {
+    const c = validateSmtpConfig({ host: "smtp.example.com", port: 465 });
+    expect(c.secure).toBe(true);
+  });
+
+  test("resolves secure=false for a non-465 port by default", () => {
+    const c = validateSmtpConfig({ host: "smtp.example.com", port: 587 });
+    expect(c.secure).toBe(false);
+  });
+
+  test("honors an explicit secure flag over the port default", () => {
+    expect(
+      validateSmtpConfig({ host: "h", port: 465, secure: false }).secure,
+    ).toBe(false);
+    expect(
+      validateSmtpConfig({ host: "h", port: 587, secure: true }).secure,
+    ).toBe(true);
+  });
+
+  test("accepts a valid auth block and passes it through", () => {
+    const c = validateSmtpConfig({
+      host: "h",
+      port: 587,
+      auth: { user: "u", pass: "p" },
+    });
+    expect(c.auth).toEqual({ user: "u", pass: "p" });
+  });
+
+  test("rejects an empty or non-string host", () => {
+    expect(() => validateSmtpConfig({ host: "", port: 25 })).toThrow(/host/);
+    expect(() => validateSmtpConfig({ host: "   ", port: 25 })).toThrow(/host/);
+    expect(() =>
+      validateSmtpConfig({ host: 123 as unknown as string, port: 25 }),
+    ).toThrow(/host/);
+  });
+
+  test("rejects an out-of-range, non-integer, or non-number port", () => {
+    expect(() => validateSmtpConfig({ host: "h", port: 0 })).toThrow(/port/);
+    expect(() => validateSmtpConfig({ host: "h", port: 70000 })).toThrow(/port/);
+    expect(() => validateSmtpConfig({ host: "h", port: 5.5 })).toThrow(/port/);
+    expect(() =>
+      validateSmtpConfig({ host: "h", port: "25" as unknown as number }),
+    ).toThrow(/port/);
+  });
+
+  test("rejects an auth block with non-string credentials", () => {
+    expect(() =>
+      validateSmtpConfig({
+        host: "h",
+        port: 25,
+        auth: { user: 1 as unknown as string, pass: "p" },
+      }),
+    ).toThrow(/auth/);
+    expect(() =>
+      validateSmtpConfig({
+        host: "h",
+        port: 25,
+        auth: { user: "u", pass: 2 as unknown as string },
+      }),
+    ).toThrow(/auth/);
+  });
+});
+
+describe("toMailOptions", () => {
+  test("maps every field and uses message.from when present", () => {
+    const opts = toMailOptions(
+      {
+        to: "to@x.com",
+        from: "msg@x.com",
+        subject: "Hi",
+        text: "t",
+        html: "<p>h</p>",
+        replyTo: "r@x.com",
+        headers: { "X-Tag": "welcome" },
+      },
+      { from: "cfg@x.com" },
+    );
+    expect(opts).toEqual({
+      to: "to@x.com",
+      from: "msg@x.com",
+      subject: "Hi",
+      text: "t",
+      html: "<p>h</p>",
+      replyTo: "r@x.com",
+      headers: { "X-Tag": "welcome" },
+    });
+  });
+
+  test("falls back to config.from when the message omits from", () => {
+    const opts = toMailOptions({ to: "to@x.com", text: "t" }, { from: "cfg@x.com" });
+    expect(opts.from).toBe("cfg@x.com");
+  });
+
+  test("rejects an empty or non-string `to`", () => {
+    expect(() => toMailOptions({ to: "", text: "t" }, {})).toThrow(/`to`/);
+    expect(() =>
+      toMailOptions({ to: 5 as unknown as string, text: "t" }, {}),
+    ).toThrow(/`to`/);
+  });
+
+  test("rejects a missing from (neither message nor config supplies one)", () => {
+    expect(() => toMailOptions({ to: "to@x.com", text: "t" }, {})).toThrow(/`from`/);
+    expect(() =>
+      toMailOptions({ to: "to@x.com", from: "  ", text: "t" }, {}),
+    ).toThrow(/`from`/);
+  });
+
+  test("rejects a body with neither text nor html", () => {
+    expect(() => toMailOptions({ to: "to@x.com", from: "f@x.com" }, {})).toThrow(
+      /text.*html/,
+    );
+  });
+
+  test("accepts an html-only and a text-only body", () => {
+    expect(
+      toMailOptions({ to: "t@x.com", from: "f@x.com", html: "<p>x</p>" }, {}).html,
+    ).toBe("<p>x</p>");
+    expect(
+      toMailOptions({ to: "t@x.com", from: "f@x.com", text: "x" }, {}).text,
+    ).toBe("x");
+  });
+
+  test("rejects CRLF injection in to, from, replyTo, subject, and headers", () => {
+    const base = { to: "t@x.com", from: "f@x.com", text: "x" };
+    expect(() => toMailOptions({ ...base, to: "t@x.com\r\nBCC: e" }, {})).toThrow(
+      /`to`/,
+    );
+    expect(() =>
+      toMailOptions({ ...base, from: "f@x.com\nDATA" }, {}),
+    ).toThrow(/`from`/);
+    expect(() =>
+      toMailOptions({ ...base, replyTo: "r@x.com\rX" }, {}),
+    ).toThrow(/`replyTo`/);
+    expect(() =>
+      toMailOptions({ ...base, subject: "Hi\r\nInjected" }, {}),
+    ).toThrow(/`subject`/);
+    expect(() =>
+      toMailOptions({ ...base, headers: { "X-A\nB": "v" } }, {}),
+    ).toThrow(/headers/);
+    expect(() =>
+      toMailOptions({ ...base, headers: { "X-A": "v\r\nC" } }, {}),
+    ).toThrow(/headers/);
+  });
+
+  test("accepts a clean message with optional fields omitted", () => {
+    const opts = toMailOptions({ to: "t@x.com", from: "f@x.com", text: "x" }, {});
+    expect(opts.subject).toBeUndefined();
+    expect(opts.replyTo).toBeUndefined();
+    expect(opts.headers).toBeUndefined();
+  });
+});
+
+describe("sendViaSmtp (injected transport)", () => {
+  test("sends through the transport and normalizes the result", async () => {
+    const { transport, calls } = fakeTransport({
+      messageId: "<smtp-1@server>",
+      accepted: ["to@x.com"],
+      rejected: [],
+    });
+    const result = await sendViaSmtp(
+      transport,
+      { to: "to@x.com", subject: "Hi", html: "<p>x</p>" },
+      { from: "no-reply@app.com" },
+    );
+    expect(result).toEqual({
+      messageId: "<smtp-1@server>",
+      accepted: ["to@x.com"],
+      rejected: [],
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].from).toBe("no-reply@app.com");
+    expect(calls[0].to).toBe("to@x.com");
+  });
+
+  test("flattens object-form accepted/rejected address entries", async () => {
+    const { transport } = fakeTransport({
+      messageId: "<id>",
+      accepted: [{ address: "ok@x.com" }, "two@x.com"],
+      rejected: [{ address: "no@x.com" }],
+    });
+    const result = await sendViaSmtp(
+      transport,
+      { to: "ok@x.com", from: "f@x.com", text: "x" },
+    );
+    expect(result.accepted).toEqual(["ok@x.com", "two@x.com"]);
+    expect(result.rejected).toEqual(["no@x.com"]);
+  });
+
+  test("defaults messageId to '' and accepted/rejected to [] when absent", async () => {
+    const { transport } = fakeTransport({});
+    const result = await sendViaSmtp(
+      transport,
+      { to: "t@x.com", from: "f@x.com", text: "x" },
+    );
+    expect(result).toEqual({ messageId: "", accepted: [], rejected: [] });
+  });
+
+  test("uses the default empty config when none is passed", async () => {
+    const { transport, calls } = fakeTransport({ messageId: "x" });
+    await sendViaSmtp(transport, { to: "t@x.com", from: "msg@x.com", text: "x" });
+    expect(calls[0].from).toBe("msg@x.com");
+  });
+
+  test("propagates a transport send failure to the caller", async () => {
+    const transport: SmtpTransport = {
+      sendMail: () => Promise.reject(new Error("connection refused")),
+    };
+    await expect(
+      sendViaSmtp(transport, { to: "t@x.com", from: "f@x.com", text: "x" }),
+    ).rejects.toThrow(/connection refused/);
+  });
+
+  test("rejects an invalid message before touching the transport", async () => {
+    const { transport, calls } = fakeTransport({ messageId: "x" });
+    await expect(
+      sendViaSmtp(transport, { to: "", from: "f@x.com", text: "x" }),
+    ).rejects.toThrow(/`to`/);
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/smtp/send.ts

@@ -0,0 +1,154 @@
+/**
+ * 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,
+  SmtpSendInfo,
+  SmtpSendResult,
+  SmtpTransport,
+} from "./types.js";
+
+/** 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: SmtpConfig,
+): SmtpConfig & { secure: boolean } {
+  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: string, value: string): void {
+  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: SmtpMessage,
+  config: Pick<SmtpConfig, "from">,
+): SmtpMailOptions {
+  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: string | { address: string }): string {
+  return typeof entry === "string" ? entry : entry.address;
+}
+
+/** Normalize a transport's raw send info into the public {@link SmtpSendResult}. */
+function toSendResult(info: SmtpSendInfo): SmtpSendResult {
+  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: SmtpTransport,
+  message: SmtpMessage,
+  config: Pick<SmtpConfig, "from"> = {},
+): Promise<SmtpSendResult> {
+  const options = toMailOptions(message, config);
+  const info = await transport.sendMail(options);
+  return toSendResult(info);
+}

package/src/smtp/transport.ts

@@ -0,0 +1,58 @@
+/**
+ * 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";
+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 function createSmtpTransport(config: SmtpConfig): SmtpTransport {
+  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: SmtpConfig): SmtpSender {
+  const transport = createSmtpTransport(config);
+  return (message) => sendViaSmtp(transport, message, config);
+}

package/src/smtp/types.ts

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

package/src/test.ts

@@ -0,0 +1,12 @@
+import type { TestConvex } from "convex-test";
+import schema from "./component/schema";
+
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register this component with a `convex-test` instance so consuming apps can
+ * test integration: `import { register } from "@vllnt/convex-email/test"`.
+ */
+export function register(t: TestConvex<typeof schema>, name = "email"): void {
+  t.registerComponent(name, schema, modules);
+}