toiljs 0.0.44 → 0.0.46

package/src/devserver/email/wire.ts

@@ -0,0 +1,55 @@
+/**
+ * Decode the `email_send` request blob the guest writes into wasm memory — the
+ * v2 wire format, byte-for-byte the edge's (`email_send_import.rs::parse_request`
+ * and `server/globals/email.ts`):
+ *
+ *   u16 to_len | u16 subject_len | u16 purpose_len | u32 body_len | u32 html_len
+ *   [to][subject][purpose][body][html]      (14-byte LE header, then UTF-8 payloads)
+ *
+ * `html_len == 0` is a plain-text send. Returns `null` on truncation, a length
+ * that overruns the blob, trailing garbage, or non-UTF-8 — all guest encode bugs
+ * the caller maps to `BadRecipient`.
+ */
+export interface ParsedEmail {
+    readonly to: string;
+    readonly subject: string;
+    readonly purpose: string;
+    readonly body: string;
+    readonly html: string;
+}
+
+const HEADER_LEN = 14;
+
+export function parseEmailBlob(raw: Buffer): ParsedEmail | null {
+    if (raw.length < HEADER_LEN) return null;
+    const toLen = raw.readUInt16LE(0);
+    const subjectLen = raw.readUInt16LE(2);
+    const purposeLen = raw.readUInt16LE(4);
+    const bodyLen = raw.readUInt32LE(6);
+    const htmlLen = raw.readUInt32LE(10);
+
+    const total = toLen + subjectLen + purposeLen + bodyLen + htmlLen;
+    // Exact fit: the five payloads must consume the rest of the blob precisely.
+    if (HEADER_LEN + total !== raw.length) return null;
+
+    let off = HEADER_LEN;
+    const take = (n: number): string | null => {
+        const end = off + n;
+        const slice = raw.subarray(off, end);
+        // Reject invalid UTF-8 (Buffer.toString is lossy, so verify by round-trip).
+        const s = slice.toString('utf8');
+        if (Buffer.byteLength(s, 'utf8') !== n) return null;
+        off = end;
+        return s;
+    };
+
+    const to = take(toLen);
+    const subject = take(subjectLen);
+    const purpose = take(purposeLen);
+    const body = take(bodyLen);
+    const html = take(htmlLen);
+    if (to === null || subject === null || purpose === null || body === null || html === null) {
+        return null;
+    }
+    return { to, subject, purpose, body, html };
+}

package/src/devserver/env.ts

@@ -1,87 +1,30 @@
 /**
  * Dev-only source for `Environment.get` / `getSecure`, mirroring the edge's
- * per-tenant env store. Reads two optional dotenv files at the project root:
+ * per-tenant env store. Reads two optional dotenv files at the project root via
+ * the shared loader (`./dotenv.ts`):
  *
  *   - `.env`          -> plain vars  (`Environment.get`); `process.env` overlays
  *   - `.env.secrets`  -> secrets     (`Environment.getSecure`); keep gitignored
  *
  * DISJOINT like the edge: `get` sees only vars, `getSecure` only secrets, so a
  * secret never comes back through `get`. Framework-reserved `TOIL_*` keys are
- * host-only and stripped from BOTH buckets (a tenant can't read them).
+ * host-only (the email backend config reads them) and never a tenant var/secret.
  *
  * Cached after first read; restart `toiljs dev` to pick up edits. The edge
  * resolves this PER TENANT from `$TOIL_ENV_DIR/<host>.env` + `<host>.env.secrets`
  * (and the edge DB later) through a lazy, bounded cache; dev has a single
  * project, so two files are enough and no eviction is needed.
  */
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** Keys with this prefix are framework-reserved/host-only (never exposed). */
-const RESERVED_PREFIX = 'TOIL_';
-
-interface DevEnv {
-    vars: Map<string, string>;
-    secrets: Map<string, string>;
-}
-
-let cache: DevEnv | null = null;
-
-/** Parse one dotenv value: take inside matching quotes, else cut an inline ` #`. */
-function parseValue(rest: string): string {
-    const q = rest[0];
-    if (q === '"' || q === "'") {
-        const end = rest.indexOf(q, 1);
-        return end < 0 ? rest.slice(1) : rest.slice(1, end);
-    }
-    const hash = rest.indexOf(' #');
-    return (hash < 0 ? rest : rest.slice(0, hash)).trimEnd();
-}
-
-/** Minimal dotenv parser: `KEY=value`, `#` comments, optional `export`, quotes. */
-function parseDotenv(text: string, into: Map<string, string>): void {
-    for (const raw of text.split('\n')) {
-        let line = raw.trim();
-        if (line.length === 0 || line.startsWith('#')) continue;
-        if (line.startsWith('export ')) line = line.slice('export '.length);
-        const eq = line.indexOf('=');
-        if (eq < 0) continue;
-        const key = line.slice(0, eq).trim();
-        if (key.length === 0 || key.startsWith(RESERVED_PREFIX)) continue; // reserved/host-only
-        into.set(key, parseValue(line.slice(eq + 1).trim()));
-    }
-}
-
-function readFileInto(file: string, into: Map<string, string>): void {
-    try {
-        parseDotenv(fs.readFileSync(path.join(process.cwd(), file), 'utf8'), into);
-    } catch {
-        /* file absent: skip */
-    }
-}
-
-function load(): DevEnv {
-    if (cache) return cache;
-    const vars = new Map<string, string>();
-    const secrets = new Map<string, string>();
-    // process.env overlays as plain vars (convenient in dev); never as secrets.
-    for (const [k, v] of Object.entries(process.env)) {
-        if (typeof v === 'string' && !k.startsWith(RESERVED_PREFIX)) vars.set(k, v);
-    }
-    readFileInto('.env', vars);
-    readFileInto('.env.secrets', secrets);
-    cache = { vars, secrets };
-    return cache;
-}
+import { loadEnvFiles } from './dotenv.js';
 
 /** A plain var by exact key, or `null`. Reads ONLY the `.env` (vars) bucket. */
 export function devEnvGet(key: string): string | null {
-    const e = load();
-    return e.vars.has(key) ? (e.vars.get(key) as string) : null;
+    const v = loadEnvFiles(process.cwd()).vars.get(key);
+    return v === undefined ? null : v;
 }
 
 /** A secret by exact key, or `null`. Reads ONLY the `.env.secrets` bucket. */
 export function devEnvGetSecure(key: string): string | null {
-    const e = load();
-    return e.secrets.has(key) ? (e.secrets.get(key) as string) : null;
+    const v = loadEnvFiles(process.cwd()).secrets.get(key);
+    return v === undefined ? null : v;
 }

package/src/devserver/host.ts

@@ -18,6 +18,8 @@
  */
 
 import { buildCryptoImports, freshCryptoState, type CryptoState } from './crypto.js';
+import { EmailStatus, getEmailService } from './email/index.js';
+import { parseEmailBlob } from './email/wire.js';
 import { devEnvGet, devEnvGetSecure } from './env.js';
 import { ratelimitCheck } from './ratelimit.js';
 
@@ -210,21 +212,36 @@ export function buildHostImports(ref: MemoryRef, state: DispatchState): WebAssem
                 return d.allowed ? 1 : -Math.max(1, d.retryAfterSecs);
             },
 
-            // `env::email_send`: the dev server has no email provider, so it
-            // parses the recipient for a log line and reports Sent (0), the same
-            // i32 contract the edge returns. The suspension is a host-side concern
-            // on the edge (call_async); the wasm just sees an i32 either way.
+            // `env::email_send`: the FULL email pipeline in dev (./email): parse +
+            // recipient validation + dedup + per-min/day budget + per-recipient cap
+            // run SYNCHRONOUSLY (exact status — BadRecipient/Deduped/Budget/
+            // RecipientCapped), then the real provider send is FIRE-AND-FORGET (a
+            // sync wasm import can't await it), so the guest gets Sent optimistically
+            // and the true outcome is logged. Unconfigured email stays a log-only
+            // mock returning Sent. Mirrors the edge's `email_send_import.rs`.
             email_send: (reqPtr: number, reqLen: number): number => {
-                // Header: u16 to_len | u16 subj_len | u16 purpose_len | u32 body_len
-                // | u32 html_len (14 bytes), then payloads; `to` is first.
                 const raw = readBytes(ref, reqPtr, reqLen);
-                let to = '<unparsed>';
-                if (raw.length >= 14) {
-                    const toLen = raw.readUInt16LE(0);
-                    if (14 + toLen <= raw.length) to = raw.toString('utf8', 14, 14 + toLen);
+                const svc = getEmailService();
+                if (svc === null) {
+                    const to = parseEmailBlob(raw)?.to ?? '<unparsed>';
+                    process.stdout.write(`  ✉ dev email_send -> ${to} (no email config; not sent)\n`);
+                    return EmailStatus.Sent;
                 }
-                process.stdout.write(`  ✉ dev email_send -> ${to} (not actually sent)\n`);
-                return 0; // EmailStatus.Sent
+                const { status, parsed } = svc.prepare(raw);
+                if (parsed === null) {
+                    process.stdout.write(`  ✉ dev email_send -> ${EmailStatus[status]}\n`);
+                    return status;
+                }
+                void svc
+                    .deliver(parsed)
+                    .then((s) => {
+                        const label = s === EmailStatus.Sent ? 'sent' : EmailStatus[s];
+                        process.stdout.write(`  ✉ dev email_send -> ${parsed.to} (${label})\n`);
+                    })
+                    .catch((e: unknown) => {
+                        process.stdout.write(`  ✉ dev email_send -> ${parsed.to} (error: ${String(e)})\n`);
+                    });
+                return EmailStatus.Sent; // optimistic; sync wasm can't await the send
             },
 
             // `Environment.get` / `getSecure`: copy one tenant env value into the

package/src/devserver/index.ts

@@ -25,7 +25,10 @@ import path from 'node:path';
 import { Server, type Request, type Response } from '@dacely/hyper-express';
 import pc from 'picocolors';
 
+import type { EmailBackendConfig } from 'toiljs/shared';
+
 import { applyCacheRule, lookupCache } from './cache.js';
+import { initEmailService } from './email/index.js';
 import { METHOD_CODES, type EnvelopeRequest } from './envelope.js';
 import { WasmServerModule } from './module.js';
 import { proxyToVite, wireWebsocketProxy, type ViteTarget } from './proxy.js';
@@ -81,6 +84,12 @@ export interface DevServerOptions {
     readonly vite: ViteTarget;
     /** Max request body bytes. Default 8 MB. */
     readonly maxBodyLength?: number;
+    /**
+     * The `toil.config.ts` `server.email` section (non-secret). When set (and the
+     * API key is in `.env.secrets`), `EmailService.send` really sends in dev;
+     * otherwise it stays a log-only mock. See `./email`.
+     */
+    readonly email?: EmailBackendConfig;
 }
 
 /** A running dev server. */
@@ -170,6 +179,17 @@ function sendWasmResponse(
 export async function startDevServer(options: DevServerOptions): Promise<RunningDevServer> {
     const host = options.host ?? '127.0.0.1';
     const root = path.resolve(options.root);
+
+    // Wire the email service from toil.config `server.email` + `.env.secrets`
+    // (TOIL_EMAIL_*). Configured -> real sends; otherwise the import stays a
+    // log-only mock. A partial-but-invalid config logs why it stayed off.
+    const emailInit = initEmailService(root, options.email);
+    if (emailInit.service !== null) {
+        process.stdout.write(pc.dim(`  ✉ email enabled: ${emailInit.note}`) + '\n');
+    } else if (emailInit.note !== null) {
+        process.stdout.write(pc.yellow('  ! ') + pc.dim(`email off: ${emailInit.note}`) + '\n');
+    }
+
     const module = new WasmServerModule(options.wasmFile);
 
     let warnedMissing = false;

package/src/shared/index.ts

@@ -8,3 +8,39 @@ export const FRAMEWORK_NAME = 'toiljs';
 export interface ToilTarget {
     readonly name: 'client' | 'compiler' | 'cli' | 'server';
 }
+
+/** SMTP connection config (non-secret) for the `smtp` / `gmail` providers. */
+export interface SmtpBackendConfig {
+    /** SMTP host. Empty + provider `gmail` defaults to `smtp.gmail.com`. */
+    readonly host?: string;
+    /** Submission port. `0`/unset defaults to 587 (STARTTLS); 465 = implicit TLS. */
+    readonly port?: number;
+    /** SMTP username. Defaults to `from`. */
+    readonly user?: string;
+}
+
+/**
+ * The **non-secret** email backend config — the typed `email` section of
+ * `toil.config.ts` (`server.email`), consumed by the dev server and the future
+ * Node self-host. The provider API key / SMTP password is a SECRET and is NEVER
+ * here: it comes from `.env.secrets` (`TOIL_EMAIL_API_KEY`). Any `TOIL_EMAIL_*`
+ * env var overrides the matching field here.
+ *
+ * Mirrors the edge's `TOIL_EMAIL_*` keys (toil-backend `host/email.rs`
+ * `EmailSection`). Lives in `toiljs/shared` so both the compiler (config schema)
+ * and the dev server (resolver) can reference it regardless of build order.
+ */
+export interface EmailBackendConfig {
+    /** `"resend"` (JSON API) | `"gmail"` | `"smtp"` (SMTP). Default `"resend"`. */
+    readonly provider?: 'resend' | 'gmail' | 'smtp';
+    /** The "from" address. Validated (single address, no CRLF). */
+    readonly from?: string;
+    /** Per-process send ceiling, sends/minute (rolling). `0` = unlimited. Default 60. */
+    readonly maxPerMin?: number;
+    /** Per-process send ceiling, sends/day (rolling). `0` = unlimited. Default 0. */
+    readonly maxPerDay?: number;
+    /** Per-recipient hourly cap (anti-abuse). Default 5. */
+    readonly maxPerRecipientPerHour?: number;
+    /** SMTP connection details (the `gmail` / `smtp` providers). */
+    readonly smtp?: SmtpBackendConfig;
+}

package/test/devserver-email.test.ts

@@ -0,0 +1,241 @@
+/**
+ * The dev / self-host email pipeline (src/devserver/email): wire parse,
+ * recipient validation, in-process caps (dedup + per-recipient + per-min/day
+ * budget), config resolution (toil.config + TOIL_EMAIL_* env), the Resend
+ * transport, and the NodeEmailService prepare/deliver split. Mirrors the edge
+ * (toil-backend host/email.rs, mailer.rs, email_budget.rs).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { EmailCaps } from '../src/devserver/email/caps.js';
+import { resolveEmailConfig, type ResolvedEmailConfig } from '../src/devserver/email/config.js';
+import { NodeEmailService } from '../src/devserver/email/index.js';
+import { sendResend } from '../src/devserver/email/providers.js';
+import { EmailStatus } from '../src/devserver/email/status.js';
+import { validFrom, validRecipient } from '../src/devserver/email/validate.js';
+import { parseEmailBlob } from '../src/devserver/email/wire.js';
+
+/** Encode an `email_send` blob exactly like the guest (`server/globals/email.ts`). */
+function encodeBlob(to: string, subject: string, purpose: string, body: string, html: string): Buffer {
+    const e = (s: string): Buffer => Buffer.from(s, 'utf8');
+    const [t, s, p, b, h] = [e(to), e(subject), e(purpose), e(body), e(html)];
+    const head = Buffer.alloc(14);
+    head.writeUInt16LE(t.length, 0);
+    head.writeUInt16LE(s.length, 2);
+    head.writeUInt16LE(p.length, 4);
+    head.writeUInt32LE(b.length, 6);
+    head.writeUInt32LE(h.length, 10);
+    return Buffer.concat([head, t, s, p, b, h]);
+}
+
+const reserved = (o: Record<string, string>): Map<string, string> => new Map(Object.entries(o));
+
+describe('validate', () => {
+    it('accepts plain addresses, rejects injection / multiple / malformed', () => {
+        expect(validRecipient('user@example.com')).toBe(true);
+        expect(validRecipient('a.b+tag@sub.example.co')).toBe(true);
+        for (const bad of [
+            'a@b.com\r\nBcc: evil@x.com',
+            'a@b.com\nDATA',
+            'a@b.com\0',
+            'a@b.com,c@d.com',
+            'a@b.com;c@d.com',
+            'a@b.com c@d.com',
+            '<a@b.com>',
+            '"a"@b.com',
+            '',
+            'nobody',
+            'a@b@c.com',
+            '@b.com',
+            'a@bcom',
+            'a@.com',
+            'a@b.',
+        ]) {
+            expect(validRecipient(bad), bad).toBe(false);
+        }
+    });
+
+    it('validFrom is lenient but rejects header injection', () => {
+        expect(validFrom('me@example.com')).toBe(true);
+        expect(validFrom('a@b.com\r\nBcc: x')).toBe(false);
+        expect(validFrom('no-at-sign')).toBe(false);
+    });
+});
+
+describe('wire parse', () => {
+    it('round-trips a well-formed blob', () => {
+        const raw = encodeBlob('a@b.com', 'Hi', 'verify', '123456', '<b>x</b>');
+        const p = parseEmailBlob(raw);
+        expect(p).toEqual({ to: 'a@b.com', subject: 'Hi', purpose: 'verify', body: '123456', html: '<b>x</b>' });
+    });
+
+    it('rejects truncated / trailing-garbage / non-UTF8', () => {
+        expect(parseEmailBlob(Buffer.alloc(4))).toBeNull(); // shorter than header
+        const raw = encodeBlob('a@b.com', 's', 'p', 'body', '');
+        expect(parseEmailBlob(raw.subarray(0, raw.length - 1))).toBeNull(); // truncated payload
+        expect(parseEmailBlob(Buffer.concat([raw, Buffer.from([0xff])]))).toBeNull(); // trailing garbage
+        const bad = Buffer.from(raw);
+        bad[bad.length - 1] = 0xff; // corrupt last body byte -> invalid UTF-8
+        expect(parseEmailBlob(bad)).toBeNull();
+    });
+});
+
+describe('caps', () => {
+    it('dedup collapses an identical (recipient, purpose) within the window', () => {
+        const c = new EmailCaps();
+        expect(c.isDuplicate('a@b.com', 'verify', 0)).toBe(false); // first
+        expect(c.isDuplicate('a@b.com', 'verify', 1_000)).toBe(true); // repeat in window
+        expect(c.isDuplicate('a@b.com', 'reset', 1_000)).toBe(false); // different purpose
+        expect(c.isDuplicate('a@b.com', 'verify', 31_000)).toBe(false); // after the 30s window
+    });
+
+    it('per-recipient hourly cap holds then resets', () => {
+        const c = new EmailCaps();
+        expect(c.recipientOk('x@y.com', 2, 0)).toBe(true);
+        expect(c.recipientOk('x@y.com', 2, 10)).toBe(true);
+        expect(c.recipientOk('x@y.com', 2, 20)).toBe(false); // third over the cap
+        expect(c.recipientOk('z@y.com', 2, 20)).toBe(true); // a different recipient is independent
+        expect(c.recipientOk('x@y.com', 2, 3_600_001)).toBe(true); // next hour resets
+    });
+
+    it('per-minute and per-day budgets both gate, 0 = unlimited', () => {
+        const c = new EmailCaps();
+        expect(c.budgetOk(2, 0, 0)).toBe(true);
+        expect(c.budgetOk(2, 0, 0)).toBe(true);
+        expect(c.budgetOk(2, 0, 0)).toBe(false); // minute cap (2) exhausted at the same instant
+        // A separate budget instance with only a day cap.
+        const d = new EmailCaps();
+        expect(d.budgetOk(0, 1, 0)).toBe(true);
+        expect(d.budgetOk(0, 1, 0)).toBe(false); // day cap (1) exhausted
+        // Unlimited (0/0) never blocks.
+        const u = new EmailCaps();
+        for (let i = 0; i < 100; i++) expect(u.budgetOk(0, 0, i)).toBe(true);
+    });
+});
+
+describe('config resolution', () => {
+    it('is unconfigured (silent) with no config + no env', () => {
+        expect(resolveEmailConfig(null, reserved({}))).toEqual({ config: null, warning: null });
+    });
+
+    it('merges toil.config + env, api key from env, env wins', () => {
+        const { config } = resolveEmailConfig(
+            { provider: 'resend', from: 'cfg@x.com', maxPerMin: 10 },
+            reserved({ TOIL_EMAIL_API_KEY: 're_k', TOIL_EMAIL_FROM: 'env@x.com' }),
+        );
+        expect(config).toMatchObject({ provider: 'resend', from: 'env@x.com', apiKey: 're_k', maxPerMin: 10 });
+    });
+
+    it('gmail resolves to smtp with defaults', () => {
+        const { config } = resolveEmailConfig(
+            { provider: 'gmail', from: 'me@gmail.com' },
+            reserved({ TOIL_EMAIL_API_KEY: 'app-pw' }),
+        );
+        expect(config).toMatchObject({ provider: 'smtp', smtp: { host: 'smtp.gmail.com', port: 587, user: 'me@gmail.com' } });
+    });
+
+    it('warns (off) on partial/invalid config', () => {
+        // from but no api key
+        expect(resolveEmailConfig({ from: 'a@b.com' }, reserved({})).warning).toMatch(/API_KEY/);
+        // bad from
+        expect(resolveEmailConfig({ from: 'no-at' }, reserved({ TOIL_EMAIL_API_KEY: 'k' })).warning).toMatch(/from/);
+        // smtp without host
+        expect(
+            resolveEmailConfig({ provider: 'smtp', from: 'a@b.com' }, reserved({ TOIL_EMAIL_API_KEY: 'k' })).warning,
+        ).toMatch(/SMTP_HOST/);
+        // unknown provider
+        expect(
+            resolveEmailConfig({ from: 'a@b.com' }, reserved({ TOIL_EMAIL_API_KEY: 'k', TOIL_EMAIL_PROVIDER: 'mailgun' }))
+                .warning,
+        ).toMatch(/unknown/);
+    });
+
+    it('TOIL_EMAIL_ENABLED=false disables silently', () => {
+        expect(
+            resolveEmailConfig({ provider: 'resend', from: 'a@b.com' }, reserved({ TOIL_EMAIL_API_KEY: 'k', TOIL_EMAIL_ENABLED: 'false' })),
+        ).toEqual({ config: null, warning: null });
+    });
+});
+
+describe('Resend transport', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    const cfg: ResolvedEmailConfig = {
+        provider: 'resend',
+        from: 'noreply@x.com',
+        apiKey: 're_secret',
+        maxPerMin: 0,
+        maxPerDay: 0,
+        maxPerRecipientPerHour: 0,
+    };
+
+    it('2xx -> Sent, with the right payload + Bearer auth', async () => {
+        const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const status = await sendResend(cfg, { from: cfg.from, to: 'a@b.com', subject: 'Hi', body: 'text', html: '<b>h</b>' });
+        expect(status).toBe(EmailStatus.Sent);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+        expect((init.headers as Record<string, string>).authorization).toBe('Bearer re_secret');
+        expect(JSON.parse(init.body as string)).toEqual({ from: 'noreply@x.com', to: ['a@b.com'], subject: 'Hi', text: 'text', html: '<b>h</b>' });
+    });
+
+    it('4xx -> ProviderError, no retry', async () => {
+        const fetchMock = vi.fn(async () => new Response(null, { status: 422 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const status = await sendResend(cfg, { from: cfg.from, to: 'a@b.com', subject: 's', body: 'b', html: '' });
+        expect(status).toBe(EmailStatus.ProviderError);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('NodeEmailService pipeline', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    const base: ResolvedEmailConfig = {
+        provider: 'resend',
+        from: 'noreply@x.com',
+        apiKey: 're_secret',
+        maxPerMin: 0,
+        maxPerDay: 0,
+        maxPerRecipientPerHour: 0,
+    };
+
+    it('prepare returns terminal statuses and a parsed message to deliver', () => {
+        const svc = new NodeEmailService(base);
+        // Bad recipient.
+        expect(svc.prepare(encodeBlob('not-an-email', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.BadRecipient);
+        // Valid -> Sent + parsed.
+        const ok = svc.prepare(encodeBlob('a@b.com', 's', 'verify', 'b', ''), 0);
+        expect(ok.status).toBe(EmailStatus.Sent);
+        expect(ok.parsed?.to).toBe('a@b.com');
+        // Identical (to, purpose) again -> Deduped.
+        expect(svc.prepare(encodeBlob('a@b.com', 's', 'verify', 'b', ''), 1_000).status).toBe(EmailStatus.Deduped);
+    });
+
+    it('enforces the per-minute budget', () => {
+        const svc = new NodeEmailService({ ...base, maxPerMin: 2 });
+        // Distinct recipients so dedup/recipient caps don't fire first.
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('b@x.com', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('c@x.com', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.Budget);
+    });
+
+    it('enforces the per-recipient hourly cap', () => {
+        const svc = new NodeEmailService({ ...base, maxPerRecipientPerHour: 2 });
+        // Same recipient, distinct purposes so dedup doesn't fire.
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p1', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p2', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p3', 'b', ''), 0).status).toBe(EmailStatus.RecipientCapped);
+    });
+
+    it('deliver actually sends via the provider', async () => {
+        const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const svc = new NodeEmailService(base);
+        const { parsed } = svc.prepare(encodeBlob('a@b.com', 's', 'p', 'b', ''), 0);
+        expect(parsed).not.toBeNull();
+        expect(await svc.deliver(parsed!)).toBe(EmailStatus.Sent);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+});

package/test/email-preview.test.ts

@@ -0,0 +1,68 @@
+import path from 'node:path';
+
+import { createServer } from 'vite';
+import { describe, expect, it } from 'vitest';
+
+import { loadConfig } from '../src/compiler/config';
+import {
+    emailsVersion,
+    listEmails,
+    previewShellHtml,
+    renderEmailByName,
+} from '../src/compiler/email-preview';
+import { createViteConfig } from '../src/compiler/vite';
+
+const EXAMPLE = path.resolve(__dirname, '../examples/basic');
+
+describe('email preview end-to-end (examples/basic)', () => {
+    it('lists Welcome and inlines its emails/styles/email.css; client/* alias resolves', async () => {
+        const cfg = await loadConfig({ root: EXAMPLE });
+        const items = listEmails(cfg);
+        expect(items.map((i) => i.name)).toContain('Welcome');
+
+        const server = await createServer({
+            ...(await createViteConfig(cfg)),
+            server: { middlewareMode: true, hmr: false },
+            appType: 'custom',
+            logLevel: 'silent',
+        });
+        try {
+            const r = await renderEmailByName(server, cfg, 'Welcome');
+            if (!r) throw new Error('Welcome did not render');
+            // tokens discovered from props
+            expect(r.tokens).toEqual(['code', 'name']);
+            // subject token template
+            expect(r.subject).toBe('Welcome, {{name}}!');
+            // .email-title { color: #111827 } from emails/styles/email.css inlined onto the <h1>
+            expect(r.html).toMatch(/<h1[^>]*style="[^"]*color:\s*#111827/i);
+            // .email-card backgroundColor inlined onto the <table>
+            expect(r.html).toMatch(/<table[^>]*style="[^"]*background-color:\s*#f6f7f9/i);
+
+            // The `client/*` reuse alias still resolves project CSS (the documented
+            // `import 'client/styles/…'` path), independent of where the demo keeps its styles.
+            const aliased = (await server.ssrLoadModule('client/styles/main.css?inline')) as {
+                default?: unknown;
+            };
+            expect(typeof aliased.default).toBe('string');
+        } finally {
+            await server.close();
+        }
+    }, 30000);
+
+    it('emailsVersion is a non-empty mtime:count fingerprint', async () => {
+        const cfg = await loadConfig({ root: EXAMPLE });
+        const v = emailsVersion(cfg);
+        expect(v).toMatch(/^\d+(\.\d+)?:\d+$/);
+        // at least Welcome.tsx + the client CSS files were counted
+        expect(Number(v.split(':')[1])).toBeGreaterThan(1);
+    });
+
+    it('the preview shell wires the dev endpoints', () => {
+        const html = previewShellHtml();
+        expect(html).toContain("var BASE = '/__toil/emails'");
+        for (const frag of ["BASE + '/list'", "BASE + '/render?name='", "BASE + '/version'"]) {
+            expect(html).toContain(frag);
+        }
+        expect(html).toContain('/__toil/open?file='); // open-in-editor
+    });
+});

package/test/emails.test.ts

@@ -0,0 +1,58 @@
+import { createElement, type ReactElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { __test } from '../src/compiler/emails';
+
+const render = (el: unknown): string => renderToStaticMarkup(el as ReactElement);
+
+describe('renderModule', () => {
+    it('discovers props as {{tokens}} and renders placeholders (alpha-sorted, deduped)', async () => {
+        const mod = {
+            default: (p: { name: string; code: string }) =>
+                createElement('p', null, `Hi ${p.name}, code ${p.code}`),
+        };
+        const r = await __test.renderModule('Welcome', mod, render);
+        if (!r) throw new Error('expected a rendered email');
+        expect(r.tokens).toEqual(['code', 'name']);
+        expect(r.html).toContain('{{name}}');
+        expect(r.html).toContain('{{code}}');
+    });
+
+    it('returns null when there is no default-exported component', async () => {
+        expect(await __test.renderModule('X', { default: 'nope' }, render)).toBeNull();
+    });
+
+    it('inlines imported CSS into element style="" (the reuse path)', async () => {
+        const mod = { default: () => createElement('h1', { className: 'email-title' }, 'Hello') };
+        const css = '.email-title { color: #111827; font-size: 22px; }';
+        const r = await __test.renderModule('Styled', mod, render, css);
+        if (!r) throw new Error('expected a rendered email');
+        // The class rule is moved onto the element as an inline style by the inliner.
+        expect(r.html).toMatch(/<h1[^>]*style="[^"]*color:\s*#111827/i);
+        expect(r.html).toMatch(/font-size:\s*22px/i);
+    });
+});
+
+describe('renderModuleSource', () => {
+    it('generates a typed Emails.<Name>.send with alpha-sorted token params', () => {
+        const src = __test.renderModuleSource([
+            {
+                name: 'Welcome',
+                subject: 'Welcome, {{name}}!',
+                html: '<p>{{code}}</p>',
+                text: 'code {{code}}',
+                tokens: ['code', 'name'],
+                purpose: 'welcome',
+            },
+        ]);
+        expect(src).toContain('export namespace Emails {');
+        expect(src).toContain('export namespace Welcome {');
+        expect(src).toContain(
+            'export function send(to: string, code: string, name: string, purpose: string = "welcome")',
+        );
+        expect(src).toContain(
+            'return new EmailTemplate(SUBJECT, TEXT, HTML).send(to, __v, purpose);',
+        );
+    });
+});