@c9up/rover 0.1.3

package/dist/templating/SimpleTemplate.js

@@ -0,0 +1,192 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { RoverError } from "../RoverError.js";
+import { getNative, toReamError } from "./loadNapi.js";
+// The compile + interpret hot path now runs in Rust via napi-rs
+// (`rover-template-engine`). This TS facade keeps the byte-identical public
+// surface — `render` / `renderFile` / `setViewsRoot` / `getViewsRoot` /
+// `resetCache` — and owns everything that touches the filesystem: path
+// resolution (incl. the `viewsRoot` traversal guard), the FS read, the
+// compiled-IR cache, and the transitive partial pre-resolution (D55.2.1). The
+// engine never reads disk (ADR-007). Render-time `{{> partial}}` recursion is
+// detected Rust-side (D55.2.2) and surfaces here as `MAIL_TEMPLATE_RECURSION`.
+let viewsRoot = "resources/views/emails";
+// Resolved-absolute-path -> compiled Rust IR handle. Content-blind: an entry is
+// reused verbatim until `resetCache()` (D55.2.3 — NO mtime/content invalidation;
+// locked by `simple-template.test.ts:109-122`).
+const cache = new Map();
+export function setViewsRoot(rootDir) {
+    viewsRoot = rootDir;
+}
+export function getViewsRoot() {
+    return viewsRoot;
+}
+/** Reset cached compiled templates (test helper). */
+export function resetCache() {
+    cache.clear();
+}
+export async function render(source, data) {
+    const ir = compileSource(source);
+    const partials = await buildPartialMap(ir);
+    return renderNative(ir, data, partials);
+}
+export async function renderFile(viewPath, data, _visited = new Set()) {
+    const ir = await loadIr(viewPath);
+    const partials = await buildPartialMap(ir);
+    return renderNative(ir, data, partials);
+}
+/** Compile inline source to an IR handle, mapping native errors to `RoverError`. */
+function compileSource(source) {
+    try {
+        return getNative().compile(source);
+    }
+    catch (err) {
+        throw toReamError(err);
+    }
+}
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+/**
+ * JSON replacer reconciling JS values the pre-migration engine rendered via
+ * `String(raw)` but that `JSON.stringify` drops or rejects at the NAPI boundary:
+ *   - bigint: widen to Number when it round-trips exactly, else refuse (a raw
+ *     `JSON.stringify` would throw a bare TypeError → opaque error).
+ *   - NaN / ±Infinity: JSON encodes both as null, so they would render empty and
+ *     Infinity would silently flip from truthy to falsy. Refuse loudly instead.
+ * Note: a `Date` is serialised by its `toJSON` (ISO-8601), a deliberate change
+ * from the old engine's locale `String(date)` — ISO is the stable mail format.
+ */
+function dataReplacer(_key, value) {
+    if (typeof value === "bigint") {
+        if (value >= MIN_SAFE_BIGINT && value <= MAX_SAFE_BIGINT) {
+            return Number(value);
+        }
+        throw new RoverError("MAIL_TEMPLATE_SYNTAX", `Cannot render bigint ${value} — it exceeds Number.MAX_SAFE_INTEGER and cannot cross the template engine boundary without precision loss; format it to a string before rendering`);
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new RoverError("MAIL_TEMPLATE_SYNTAX", `Cannot render non-finite number ${value} — NaN and Infinity have no representation across the template engine boundary; format it to a string before rendering`);
+    }
+    return value;
+}
+/** Render a compiled IR, mapping native errors (syntax/recursion) to `RoverError`. */
+function renderNative(ir, data, partials) {
+    try {
+        // `data` crosses as a JSON string: `JSON.stringify` is own-enumerable-only,
+        // preserving the engine's `Object.hasOwn` dot-path contract (inherited
+        // prototype-chain props stay invisible — the own-property-only parity test).
+        // `dataReplacer` reconciles bigint / NaN / Infinity (see above).
+        return getNative().renderIr(ir, JSON.stringify(data, dataReplacer), partials);
+    }
+    catch (err) {
+        throw toReamError(err);
+    }
+}
+/** Extract a Node `fs` errno string (e.g. `"ENOENT"`) without an `as` cast. */
+function errnoCode(err) {
+    if (err !== null && typeof err === "object") {
+        const code = Reflect.get(err, "code");
+        if (typeof code === "string")
+            return code;
+    }
+    return "";
+}
+/**
+ * Resolve + read + compile one template path, caching the compiled IR by its
+ * resolved absolute path. Owns the `MAIL_TEMPLATE_NOT_FOUND` / `_READ_ERROR`
+ * raising (unchanged from the pre-migration engine).
+ */
+async function loadIr(viewPath) {
+    const { resolved, tried } = resolveTemplatePath(viewPath);
+    const cached = cache.get(resolved);
+    if (cached !== undefined)
+        return cached;
+    let source;
+    try {
+        source = await readFile(resolved, "utf8");
+    }
+    catch (err) {
+        const code = errnoCode(err);
+        // Only ENOENT maps to NOT_FOUND; permission/io errors surface distinctly.
+        if (code !== "ENOENT") {
+            throw new RoverError("MAIL_TEMPLATE_READ_ERROR", `Template read failed at ${resolved} (${code || "unknown"})`, {
+                hint: "Check filesystem permissions and file descriptor limits.",
+                context: { path: resolved, code, viewsRoot },
+            });
+        }
+        throw new RoverError("MAIL_TEMPLATE_NOT_FOUND", `Template not found at ${resolved}`, {
+            hint: "Create the file or update config.mail.viewsRoot.",
+            context: {
+                path: resolved,
+                paths: tried.join(", "),
+                viewsRoot,
+            },
+        });
+    }
+    const ir = compileSource(source);
+    cache.set(resolved, ir);
+    return ir;
+}
+/**
+ * Transitively pre-resolve every `{{> name}}` partial reachable from `rootIr`
+ * into a `name -> IR handle` map (D55.2.1). Stops re-descending once a name is
+ * mapped, so a cyclic partial graph terminates here WITHOUT erroring — the
+ * actual `MAIL_TEMPLATE_RECURSION` is raised Rust-side only when the cycle is
+ * really rendered (D55.2.2). Partials read here are cached by resolved path
+ * (content-blind), exactly as the pre-migration recursive `renderFile` did.
+ */
+async function buildPartialMap(rootIr) {
+    const map = {};
+    const stack = [rootIr];
+    while (stack.length > 0) {
+        const ir = stack.pop();
+        if (ir === undefined)
+            break;
+        for (const name of ir.partialNames) {
+            if (Object.hasOwn(map, name))
+                continue;
+            let partialIr;
+            try {
+                partialIr = await loadIr(`partials/${name}`);
+            }
+            catch (err) {
+                // A partial referenced only inside a falsy `{{#if}}` is never
+                // rendered. The pre-migration engine loaded partials lazily, so a
+                // missing such partial did not error. Skip it here; if it IS reached
+                // at render time the Rust renderer raises MAIL_TEMPLATE_NOT_FOUND.
+                if (err instanceof RoverError &&
+                    err.code === "MAIL_TEMPLATE_NOT_FOUND") {
+                    continue;
+                }
+                throw err;
+            }
+            map[name] = partialIr;
+            stack.push(partialIr);
+        }
+    }
+    return map;
+}
+/**
+ * Resolve a template path under `viewsRoot`, rejecting any attempt to escape
+ * the root (absolute path outside, or `../` traversal after normalisation).
+ * Returns the resolved absolute path plus the set of candidates tried.
+ */
+function resolveTemplatePath(viewPath) {
+    const rootAbs = path.resolve(viewsRoot);
+    const startingPoint = path.isAbsolute(viewPath)
+        ? viewPath
+        : path.resolve(rootAbs, viewPath);
+    const withoutExt = startingPoint;
+    const withExt = startingPoint.endsWith(".html")
+        ? startingPoint
+        : `${startingPoint}.html`;
+    const candidate = path.resolve(withExt);
+    const rel = path.relative(rootAbs, candidate);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new RoverError("MAIL_TEMPLATE_NOT_FOUND", `Template path "${viewPath}" resolves outside of viewsRoot`, {
+            hint: "Template names must stay under viewsRoot. Absolute paths and `..` traversals are rejected.",
+            context: { path: candidate, viewsRoot: rootAbs },
+        });
+    }
+    return { resolved: candidate, tried: [withExt, withoutExt] };
+}
+//# sourceMappingURL=SimpleTemplate.js.map

package/dist/templating/SimpleTemplate.js.map

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

package/dist/templating/loadNapi.d.ts

@@ -0,0 +1,21 @@
+import { RoverError } from "../RoverError.js";
+/** Opaque handle to a compiled template IR (Rust `RoverIr`). */
+export interface NativeRoverIr {
+    /** Referenced partial names, in document order (descends into if-bodies). */
+    readonly partialNames: readonly string[];
+}
+interface NativeExports {
+    readonly engineVersion: () => string;
+    readonly compile: (source: string) => NativeRoverIr;
+    readonly renderIr: (ir: NativeRoverIr, dataJson: string, partials: Record<string, NativeRoverIr>) => string;
+}
+export declare function getNative(): NativeExports;
+/**
+ * Translate a thrown value from a native call into a `RoverError`.
+ * Already a `RoverError` (e.g. the loader threw) → pass through. A `napi::Error`
+ * carrying our `{code,message}` JSON envelope → reconstruct typed (line numbers
+ * preserved in `message`). Anything else → wrap as a syntax error.
+ */
+export declare function toReamError(err: unknown): RoverError;
+export {};
+//# sourceMappingURL=loadNapi.d.ts.map

package/dist/templating/loadNapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadNapi.d.ts","sourceRoot":"","sources":["../../src/templating/loadNapi.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAyB9C,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,UAAU,aAAa;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,CAClB,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACnC,MAAM,CAAC;CACZ;AAaD,wBAAgB,SAAS,IAAI,aAAa,CA6CzC;AA6BD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAwBpD"}

package/dist/templating/loadNapi.js

@@ -0,0 +1,115 @@
+// Loads the native `rover-template-engine-napi` binary built by
+// `scripts/copy-napi.mjs` and re-throws load failures as
+// `MAIL_TEMPLATE_NAPI_REQUIRED` (D55.2.4) — actionable hint points at
+// `pnpm --filter @c9up/rover build:napi`.
+//
+// Per cerebrum 2026-04-15 there is NO JS fallback. If the binary fails to load,
+// consumers get a typed `RoverError`. Zero `as` / `any` per `feedback_no_any_types`
+// — every boundary is narrowed with a `Reflect.get` type guard.
+import { createRequire } from "node:module";
+import { arch, platform } from "node:process";
+import { fileURLToPath } from "node:url";
+import { RoverError } from "../RoverError.js";
+const SUFFIX_MAP = {
+    "linux-x64": "linux-x64-gnu",
+    "linux-arm64": "linux-arm64-gnu",
+    "darwin-x64": "darwin-x64",
+    "darwin-arm64": "darwin-arm64",
+    "win32-x64": "win32-x64-msvc",
+};
+function platformSuffix() {
+    const key = `${platform}-${arch}`;
+    const suffix = SUFFIX_MAP[key];
+    if (typeof suffix !== "string") {
+        throw new RoverError("MAIL_TEMPLATE_NAPI_REQUIRED", `Unsupported platform/arch '${key}' for @c9up/rover native binary. Supported: ${Object.keys(SUFFIX_MAP).join(", ")}.`, {
+            hint: "Build the native binary on a supported platform with 'pnpm --filter @c9up/rover build:napi'.",
+        });
+    }
+    return suffix;
+}
+function isNativeExports(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return (typeof Reflect.get(value, "engineVersion") === "function" &&
+        typeof Reflect.get(value, "compile") === "function" &&
+        typeof Reflect.get(value, "renderIr") === "function");
+}
+let cachedNative;
+export function getNative() {
+    if (cachedNative !== undefined)
+        return cachedNative;
+    const require = createRequire(import.meta.url);
+    const here = fileURLToPath(import.meta.url);
+    // `here` is `…/packages/rover/src/templating/loadNapi.ts` (or `dist/…`). The
+    // `.node` lives at the package root `…/packages/rover/index.<suffix>.node`,
+    // two levels up from `src/templating` / `dist/templating`.
+    const suffix = platformSuffix();
+    const candidate = `../../index.${suffix}.node`;
+    let loaded;
+    let lastErr;
+    try {
+        loaded = require(candidate);
+    }
+    catch (err) {
+        lastErr = err;
+    }
+    if (loaded === undefined) {
+        const causeMessage = lastErr instanceof Error ? lastErr.message : String(lastErr);
+        // The prebuilt linux binaries target glibc (`-gnu`). On musl hosts (Alpine
+        // containers) the `-gnu` binary fails to dlopen with a libc symbol error —
+        // surface that explicitly rather than only pointing at the build step.
+        const muslHint = suffix.endsWith("-gnu")
+            ? " If you are on Alpine/musl, note the prebuilt binaries target glibc (musl is not a supported target)."
+            : "";
+        throw new RoverError("MAIL_TEMPLATE_NAPI_REQUIRED", `@c9up/rover native binary 'index.${suffix}.node' not found or failed to load near ${here} — run 'pnpm --filter @c9up/rover build:napi' to build it.${muslHint} Cause: ${causeMessage}`, {
+            hint: "Run 'pnpm --filter @c9up/rover build:napi' to compile the native template engine.",
+        });
+    }
+    if (!isNativeExports(loaded)) {
+        throw new RoverError("MAIL_TEMPLATE_NAPI_REQUIRED", "@c9up/rover native binary loaded but missing expected exports (engineVersion / compile / renderIr). Rebuild with 'pnpm --filter @c9up/rover build:napi'.", {
+            hint: "The native binary is stale — rebuild with 'pnpm --filter @c9up/rover build:napi'.",
+        });
+    }
+    cachedNative = loaded;
+    return cachedNative;
+}
+function isNapiErrorPayload(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return (typeof Reflect.get(value, "code") === "string" &&
+        typeof Reflect.get(value, "message") === "string");
+}
+/** Codes the Rust engine legitimately emits, with their actionable hints. */
+const CODE_HINTS = {
+    MAIL_TEMPLATE_SYNTAX: "Check the template grammar: {{ var }}, {{{ raw }}}, {{#if x}}...{{/if}}, {{> partial}}.",
+    MAIL_TEMPLATE_RECURSION: "Break the cycle — a template cannot include itself (directly or via partials).",
+    MAIL_TEMPLATE_NOT_FOUND: "Create the referenced partial file or remove the {{> name}} reference.",
+};
+/**
+ * Translate a thrown value from a native call into a `RoverError`.
+ * Already a `RoverError` (e.g. the loader threw) → pass through. A `napi::Error`
+ * carrying our `{code,message}` JSON envelope → reconstruct typed (line numbers
+ * preserved in `message`). Anything else → wrap as a syntax error.
+ */
+export function toReamError(err) {
+    if (err instanceof RoverError)
+        return err;
+    if (err instanceof Error) {
+        let parsed;
+        try {
+            parsed = JSON.parse(err.message);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (isNapiErrorPayload(parsed)) {
+            const hint = CODE_HINTS[parsed.code];
+            if (hint !== undefined) {
+                return new RoverError(parsed.code, parsed.message, { hint });
+            }
+        }
+        return new RoverError("MAIL_TEMPLATE_SYNTAX", `Native template call failed: ${err.message}`);
+    }
+    return new RoverError("MAIL_TEMPLATE_SYNTAX", `Native template call failed with non-Error: ${String(err)}`);
+}
+//# sourceMappingURL=loadNapi.js.map

package/dist/templating/loadNapi.js.map

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

package/dist/testing/FakeMail.d.ts

@@ -0,0 +1,31 @@
+import type { MailMessage, MailSendOutcome, MailTransport } from "../Mail.js";
+export interface FakeMailPredicate {
+    from?: string;
+    to?: string;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    subject?: string;
+    containing?: string;
+}
+export type FakeMailPredicateArg = FakeMailPredicate | ((m: MailMessage) => boolean);
+/**
+ * In-memory transport for tests — captures every `send(message)` call and
+ * exposes Adonis/Laravel-style `assertSent` / `assertNotSent` helpers.
+ *
+ * Not re-exported from the main barrel; reach via `@c9up/rover/testing`.
+ */
+export declare class FakeMail implements MailTransport {
+    #private;
+    send(message: MailMessage): Promise<MailSendOutcome>;
+    /**
+     * Return a defensive snapshot of captured messages. Each message is cloned
+     * (shallow-per-field with array copies) so test-side mutations can't bleed
+     * back into the internal capture store — avoids cross-test contamination.
+     */
+    getSent(): MailMessage[];
+    reset(): void;
+    assertSent(predicate: FakeMailPredicateArg): void;
+    assertNotSent(predicate: FakeMailPredicateArg): void;
+}
+//# sourceMappingURL=FakeMail.d.ts.map

package/dist/testing/FakeMail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeMail.d.ts","sourceRoot":"","sources":["../../src/testing/FakeMail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9E,MAAM,WAAW,iBAAiB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,oBAAoB,GAC7B,iBAAiB,GACjB,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,qBAAa,QAAS,YAAW,aAAa;;IAGvC,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAK1D;;;;OAIG;IACH,OAAO,IAAI,WAAW,EAAE;IAexB,KAAK,IAAI,IAAI;IAIb,UAAU,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI;IAQjD,aAAa,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI;CAQpD"}

package/dist/testing/FakeMail.js

@@ -0,0 +1,90 @@
+/**
+ * In-memory transport for tests — captures every `send(message)` call and
+ * exposes Adonis/Laravel-style `assertSent` / `assertNotSent` helpers.
+ *
+ * Not re-exported from the main barrel; reach via `@c9up/rover/testing`.
+ */
+export class FakeMail {
+    #captured = [];
+    async send(message) {
+        this.#captured.push(message);
+        return undefined;
+    }
+    /**
+     * Return a defensive snapshot of captured messages. Each message is cloned
+     * (shallow-per-field with array copies) so test-side mutations can't bleed
+     * back into the internal capture store — avoids cross-test contamination.
+     */
+    getSent() {
+        return this.#captured.map((m) => ({
+            from: m.from,
+            to: m.to.slice(),
+            cc: m.cc.slice(),
+            bcc: m.bcc.slice(),
+            replyTo: m.replyTo,
+            subject: m.subject,
+            html: m.html,
+            text: m.text,
+            attachments: m.attachments.slice(),
+            headers: { ...m.headers },
+        }));
+    }
+    reset() {
+        this.#captured = [];
+    }
+    assertSent(predicate) {
+        const match = makeMatcher(predicate);
+        if (this.#captured.some(match))
+            return;
+        throw new Error(`mail.assertSent() failed — no captured message matches ${describePredicate(predicate)}.\n${describeCaptured(this.#captured)}`);
+    }
+    assertNotSent(predicate) {
+        const match = makeMatcher(predicate);
+        const found = this.#captured.find(match);
+        if (!found)
+            return;
+        throw new Error(`mail.assertNotSent() failed — at least one captured message matches ${describePredicate(predicate)}.\n${describeCaptured(this.#captured)}`);
+    }
+}
+function makeMatcher(predicate) {
+    if (typeof predicate === "function")
+        return predicate;
+    const p = predicate;
+    if (p.containing !== undefined && p.containing === "") {
+        throw new Error("FakeMail: `containing` predicate cannot be an empty string — it would match every captured message. Pass a non-empty needle.");
+    }
+    return (m) => {
+        if (p.from !== undefined && m.from !== p.from)
+            return false;
+        if (p.replyTo !== undefined && m.replyTo !== p.replyTo)
+            return false;
+        if (p.subject !== undefined && m.subject !== p.subject)
+            return false;
+        if (p.to !== undefined && !m.to.includes(p.to))
+            return false;
+        if (p.cc !== undefined && !m.cc.includes(p.cc))
+            return false;
+        if (p.bcc !== undefined && !m.bcc.includes(p.bcc))
+            return false;
+        if (p.containing !== undefined) {
+            const needle = p.containing;
+            const inHtml = m.html?.includes(needle) ?? false;
+            const inText = m.text?.includes(needle) ?? false;
+            if (!inHtml && !inText)
+                return false;
+        }
+        return true;
+    };
+}
+function describePredicate(predicate) {
+    if (typeof predicate === "function")
+        return "<function predicate>";
+    return JSON.stringify(predicate);
+}
+function describeCaptured(captured) {
+    if (captured.length === 0)
+        return "Captured: (none)";
+    const lines = captured.map((m, i) => `  [${i}] to=[${m.to.join(", ")}] subject="${m.subject}" from="${m.from}"`);
+    return `Captured (${captured.length}):\n${lines.join("\n")}`;
+}
+//# sourceMappingURL=FakeMail.js.map

package/dist/testing/FakeMail.js.map

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

package/dist/transports/MailgunTransport.d.ts

@@ -0,0 +1,7 @@
+import { type MailMessage, type MailSendOutcome, type MailTransport } from "../Mail.js";
+export declare class MailgunTransport implements MailTransport {
+    #private;
+    constructor(config: Record<string, unknown>);
+    send(message: MailMessage): Promise<MailSendOutcome>;
+}
+//# sourceMappingURL=MailgunTransport.d.ts.map

package/dist/transports/MailgunTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MailgunTransport.d.ts","sourceRoot":"","sources":["../../src/transports/MailgunTransport.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,aAAa,EAElB,MAAM,YAAY,CAAC;AAyBpB,qBAAa,gBAAiB,YAAW,aAAa;;gBAIzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IA6DrC,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAmD1D"}

package/dist/transports/MailgunTransport.js

@@ -0,0 +1,149 @@
+import { RoverError } from "../RoverError.js";
+import formData from "form-data";
+// mailgun.js is UMD-bundled; the class lives on `.default` under NodeNext.
+import MailgunModule from "mailgun.js";
+import { registerTransport, } from "../Mail.js";
+const stripCrlf = (v) => v.replace(/[\r\n]/g, "");
+const normalizeConfig = (v) => stripCrlf(v).trim();
+const MAX_PROVIDER_MESSAGE = 16 * 1024;
+const capMessage = (s) => s.length <= MAX_PROVIDER_MESSAGE
+    ? s
+    : `${s.slice(0, MAX_PROVIDER_MESSAGE)}...[truncated]`;
+const redactSecrets = (s) => s
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, "Bearer [REDACTED]")
+    .replace(/Basic\s+[A-Za-z0-9+/=]+/g, "Basic [REDACTED]");
+export class MailgunTransport {
+    #client;
+    #domain;
+    constructor(config) {
+        const apiKey = typeof config.apiKey === "string" ? normalizeConfig(config.apiKey) : "";
+        const domain = typeof config.domain === "string" ? normalizeConfig(config.domain) : "";
+        if (!apiKey || !domain) {
+            throw new RoverError("MAIL_PROVIDER_CONFIG", "Mailgun transport requires apiKey and domain", { hint: "Set { apiKey, domain } in your mail config." });
+        }
+        this.#domain = domain;
+        // Region: reject non-string when *defined* (wrong type signals a config
+        // bug — defaulting to "us" under those conditions is a compliance risk).
+        if (config.region !== undefined && typeof config.region !== "string") {
+            throw new RoverError("MAIL_PROVIDER_CONFIG", `Mailgun region must be a string ("us" or "eu"), got ${typeof config.region}`, { hint: "Set config.region explicitly as 'us' or 'eu'." });
+        }
+        const rawRegion = typeof config.region === "string"
+            ? normalizeConfig(config.region).toLowerCase()
+            : "us";
+        if (rawRegion !== "us" && rawRegion !== "eu") {
+            throw new RoverError("MAIL_PROVIDER_CONFIG", `Mailgun region must be "us" or "eu", got "${rawRegion}"`, {
+                hint: "Use { region: 'us' } or { region: 'eu' }. A typo silently routing EU traffic to US infrastructure is a compliance risk.",
+            });
+        }
+        const url = rawRegion === "eu"
+            ? "https://api.eu.mailgun.net"
+            : "https://api.mailgun.net";
+        // Dependency injection for tests: `_client` wins over real SDK. Guarded
+        // against non-object and non-shape inputs so a typo'd config can't
+        // silently bypass the real client.
+        const injected = config._client;
+        if (injected &&
+            typeof injected === "object" &&
+            "messages" in injected &&
+            typeof injected.messages?.create === "function") {
+            this.#client = injected;
+        }
+        else {
+            // mailgun.js ships a UMD-style default export; the class constructor
+            // lives on `.default` in the typings (`static get default`).
+            const MailgunCtor = MailgunModule.default;
+            const mailgun = new MailgunCtor(formData);
+            this.#client = mailgun.client({ username: "api", key: apiKey, url });
+        }
+    }
+    async send(message) {
+        if (message.to.length === 0 &&
+            message.cc.length === 0 &&
+            message.bcc.length === 0) {
+            throw new RoverError("MAIL_PROVIDER_CONFIG", "Mail message has no recipients", { hint: "Set at least one `to`, `cc`, or `bcc` before sending." });
+        }
+        // CRLF stripping is applied at the wire boundary regardless of SDK
+        // promises — defence-in-depth. Anti-pattern from spec Dev Notes:
+        // "never skip CRLF sanitisation because the provider will handle it".
+        const data = {
+            from: stripCrlf(message.from),
+            to: message.to.map(stripCrlf),
+            subject: stripCrlf(message.subject),
+        };
+        if (message.cc.length)
+            data.cc = message.cc.map(stripCrlf);
+        if (message.bcc.length)
+            data.bcc = message.bcc.map(stripCrlf);
+        if (message.text)
+            data.text = message.text;
+        if (message.html)
+            data.html = message.html;
+        if (message.replyTo)
+            data["h:Reply-To"] = stripCrlf(message.replyTo);
+        for (const [k, v] of Object.entries(message.headers)) {
+            data[`h:${stripCrlf(k)}`] = stripCrlf(v);
+        }
+        if (message.attachments.length > 0) {
+            data.attachment = message.attachments.map((att) => {
+                const entry = {
+                    filename: stripCrlf(att.filename),
+                    data: Buffer.from(att.content),
+                };
+                if (att.contentType) {
+                    entry.contentType = stripCrlf(att.contentType);
+                }
+                return entry;
+            });
+        }
+        try {
+            const res = await this.#client.messages.create(this.#domain, data);
+            if (res.id)
+                return { providerId: res.id };
+            return undefined;
+        }
+        catch (err) {
+            throw wrapMailgunError(err);
+        }
+    }
+}
+/**
+ * mailgun.js's own error shape is `{ status, details | message, ... }`.
+ * Map it to our uniform `MAIL_PROVIDER_ERROR` so retry + observability
+ * consumers don't need to branch on provider.
+ *
+ * Bare `Error` (no `status`) — typical for network/ECONNRESET failures from
+ * mailgun.js — surface the original errno (`code`) in context so the retry
+ * predicate can still classify it as transient.
+ */
+function wrapMailgunError(err) {
+    if (err instanceof RoverError)
+        return err;
+    const anyErr = err;
+    // Coerce string-typed status ("401") into number — mailgun.js is
+    // inconsistent across versions.
+    const statusNum = Number(anyErr.status);
+    const status = Number.isFinite(statusNum) ? statusNum : 0;
+    const providerMessage = redactSecrets(capMessage(anyErr.details ?? anyErr.message ?? "unknown"));
+    const ctx = {
+        provider: "mailgun",
+        upstreamStatus: String(status),
+        providerMessage,
+    };
+    if (typeof anyErr.code === "string") {
+        ctx.networkCode = anyErr.code;
+    }
+    // Retry-After may arrive either as a header (`retry-after`) or as a JSON
+    // body field — pass both upstream so `computeBackoffMs` can honour it.
+    const retryAfterHeader = anyErr.headers?.["retry-after"];
+    if (retryAfterHeader) {
+        ctx.retryAfter = Array.isArray(retryAfterHeader)
+            ? (retryAfterHeader[0] ?? "")
+            : retryAfterHeader;
+    }
+    return new RoverError("MAIL_PROVIDER_ERROR", `Mailgun returned ${status || "unknown"}`, {
+        hint: "Inspect `context.upstreamStatus` (HTTP) or `context.networkCode` (ECONNRESET/etc.) to decide retry eligibility.",
+        context: ctx,
+    });
+}
+registerTransport("mailgun", (config) => new MailgunTransport(config));
+//# sourceMappingURL=MailgunTransport.js.map