@shaferllc/keel 0.12.0 → 0.36.0

package/dist/core/http/router.d.ts

@@ -7,6 +7,13 @@
  */
 import type { Context as HonoContext, MiddlewareHandler } from "hono";
 import type { Container, Constructor } from "../container.js";
+export interface UrlOptions {
+    qs?: Record<string, string | number>;
+}
+export interface SignedUrlOptions extends UrlOptions {
+    /** Expiry in seconds from now. */
+    expiresIn?: number;
+}
 /** The request context handed to every route handler and middleware. */
 export type Ctx = HonoContext;
 /** A route-parameter constraint: a regex, a source string, or `{ match }`. */
@@ -34,13 +41,15 @@ export type ControllerRef = Constructor | LazyController;
 export type ControllerAction = [ControllerRef] | [ControllerRef, string];
 /** A function, a controller action, or a ready-made Response. */
 export type RouteHandler = HandlerFn | ControllerAction | Response;
+/** A middleware handler, or the name of one registered with `router.named()`. */
+export type MiddlewareRef = MiddlewareHandler | string;
 export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
 export interface RouteDefinition {
     methods: Method[];
     path: string;
     handler: RouteHandler;
     name?: string;
-    middleware: MiddlewareHandler[];
+    middleware: MiddlewareRef[];
     wheres: Record<string, string>;
     /** Host pattern this route is bound to, e.g. ":tenant.example.com". */
     domain?: string;
@@ -54,9 +63,9 @@ export declare class Route {
     /** Alias for name(). */
     as(name: string): this;
     /** Attach middleware that runs only for this route (after group middleware). */
-    middleware(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    middleware(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Alias for middleware(), matching AdonisJS. */
-    use(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    use(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Constrain a route parameter with a regex, source string, or matcher. */
     where(param: string, matcher: Matcher): this;
     /** Bind this route to a host pattern (supports `:subdomain` segments). */
@@ -67,9 +76,9 @@ export declare class RouteGroup {
     private routes;
     constructor(routes: RouteDefinition[]);
     prefix(prefix: string): this;
-    middleware(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    middleware(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Alias for middleware(), matching AdonisJS. */
-    use(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    use(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Constrain a parameter across every route in the group. */
     where(param: string, matcher: Matcher): this;
     as(namePrefix: string): this;
@@ -91,7 +100,7 @@ export declare class RouteResource {
     /** Rename a route parameter, e.g. `.params({ posts: "post" })`. */
     params(map: Record<string, string>): this;
     /** Attach middleware to specific actions (or "*" for all). */
-    use(actions: string[] | "*", mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    use(actions: string[] | "*", mw: MiddlewareRef | MiddlewareRef[]): this;
 }
 /** Fluent matcher for `on(path)` convenience routes. */
 declare class RouteMatcher {
@@ -118,6 +127,7 @@ export declare class Router {
     private group_prefix;
     private group_mw;
     private globalWheres;
+    private namedMiddleware;
     /** Built-in parameter matchers: `router.matchers.number()`. */
     readonly matchers: {
         number: () => RegExp;
@@ -126,6 +136,13 @@ export declare class Router {
         alpha: () => RegExp;
     };
     constructor(container: Container);
+    /**
+     * Register named middleware, referenceable by name in `.middleware()` /
+     * `.use()`: `router.named({ auth, admin })` then `route.use("auth")`.
+     */
+    named(map: Record<string, MiddlewareHandler>): this;
+    /** Resolve a middleware reference (name or function) to a handler. */
+    resolveMiddleware(ref: MiddlewareRef): MiddlewareHandler;
     get(path: string, handler: RouteHandler): Route;
     post(path: string, handler: RouteHandler): Route;
     put(path: string, handler: RouteHandler): Route;
@@ -152,8 +169,15 @@ export declare class Router {
     where(param: string, matcher: Matcher): this;
     /** All registered routes (excluding those trimmed to zero methods). */
     all(): RouteDefinition[];
-    /** Generate a URL for a named route, substituting `:params`. */
-    url(name: string, params?: Record<string, string | number>): string;
+    /** Generate a URL for a named route, substituting `:params` and query string. */
+    url(name: string, params?: Record<string, string | number>, options?: UrlOptions): string;
+    /**
+     * A tamper-proof URL for a named route, signed with `config('app.key')`.
+     * Verify the incoming request with `router.hasValidSignature()`.
+     */
+    signedUrl(name: string, params?: Record<string, string | number>, options?: SignedUrlOptions): Promise<string>;
+    /** Whether the current request carries a valid (unexpired) signature. */
+    hasValidSignature(): Promise<boolean>;
     /** Turn a route handler into an executable function, resolving controllers. */
     resolve(handler: RouteHandler): HandlerFn;
 }

package/dist/core/http/router.js

@@ -5,9 +5,22 @@
  * Fluent, AdonisJS-inspired API: named routes, per-route and group middleware,
  * prefixes, param constraints, resource routes, and URL generation.
  */
-import { view } from "../helpers.js";
-import { redirect as makeRedirect } from "../request.js";
+import { view, config } from "../helpers.js";
+import { redirect as makeRedirect, request } from "../request.js";
 import { inertia } from "../inertia.js";
+/** HMAC-SHA256 hex signature (Web Crypto — works on Node and the edge). */
+async function hmac(key, data) {
+    const enc = new TextEncoder();
+    const cryptoKey = await crypto.subtle.importKey("raw", enc.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", cryptoKey, enc.encode(data));
+    return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function appKey() {
+    const key = config("app.key", "");
+    if (!key)
+        throw new Error("Signed URLs require config('app.key'). Set APP_KEY.");
+    return key;
+}
 function matcherSource(m) {
     if (typeof m === "string")
         return m;
@@ -206,11 +219,30 @@ export class Router {
     group_prefix = "";
     group_mw = [];
     globalWheres = {};
+    namedMiddleware = {};
     /** Built-in parameter matchers: `router.matchers.number()`. */
     matchers = matchers;
     constructor(container) {
         this.container = container;
     }
+    /**
+     * Register named middleware, referenceable by name in `.middleware()` /
+     * `.use()`: `router.named({ auth, admin })` then `route.use("auth")`.
+     */
+    named(map) {
+        Object.assign(this.namedMiddleware, map);
+        return this;
+    }
+    /** Resolve a middleware reference (name or function) to a handler. */
+    resolveMiddleware(ref) {
+        if (typeof ref !== "string")
+            return ref;
+        const mw = this.namedMiddleware[ref];
+        if (!mw) {
+            throw new Error(`No named middleware [${ref}]. Register it with router.named({ ${ref}: … }).`);
+        }
+        return mw;
+    }
     get(path, handler) {
         return this.add(["GET"], path, handler);
     }
@@ -305,8 +337,8 @@ export class Router {
         }
         return this.routes.filter((r) => r.methods.length > 0);
     }
-    /** Generate a URL for a named route, substituting `:params`. */
-    url(name, params = {}) {
+    /** Generate a URL for a named route, substituting `:params` and query string. */
+    url(name, params = {}, options = {}) {
         const def = this.routes.find((r) => r.name === name);
         if (!def)
             throw new Error(`No route named [${name}].`);
@@ -314,7 +346,44 @@ export class Router {
         for (const [k, v] of Object.entries(params)) {
             path = path.replace(new RegExp(`:${k}\\??`), encodeURIComponent(String(v)));
         }
-        return path.replace(/\/:[^/]+\?/g, "").replace(/:[^/]+/g, "");
+        path = path.replace(/\/:[^/]+\?/g, "").replace(/:[^/]+/g, "");
+        if (options.qs && Object.keys(options.qs).length) {
+            const qs = new URLSearchParams(Object.fromEntries(Object.entries(options.qs).map(([k, v]) => [k, String(v)])));
+            return `${path}?${qs}`;
+        }
+        return path;
+    }
+    /**
+     * A tamper-proof URL for a named route, signed with `config('app.key')`.
+     * Verify the incoming request with `router.hasValidSignature()`.
+     */
+    async signedUrl(name, params = {}, options = {}) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(options.qs ?? {}))
+            qs.set(k, String(v));
+        if (options.expiresIn) {
+            qs.set("expires", String(Math.floor(Date.now() / 1000) + options.expiresIn));
+        }
+        let url = this.url(name, params);
+        const query = qs.toString();
+        if (query)
+            url += `?${query}`;
+        const signature = await hmac(appKey(), url);
+        return `${url}${query ? "&" : "?"}signature=${signature}`;
+    }
+    /** Whether the current request carries a valid (unexpired) signature. */
+    async hasValidSignature() {
+        const url = new URL(request.raw.url);
+        const signature = url.searchParams.get("signature");
+        if (!signature)
+            return false;
+        url.searchParams.delete("signature");
+        const expires = url.searchParams.get("expires");
+        if (expires && Number(expires) < Math.floor(Date.now() / 1000))
+            return false;
+        const base = url.pathname + (url.search || "");
+        const expected = await hmac(appKey(), base);
+        return signature.length === expected.length && signature === expected;
     }
     /** Turn a route handler into an executable function, resolving controllers. */
     resolve(handler) {

package/dist/core/index.d.ts

@@ -4,7 +4,34 @@ export type { Token, Constructor, Factory } from "./container.js";
 export { Application } from "./application.js";
 export type { BootOptions } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, } from "./helpers.js";
+export { Logger } from "./logger.js";
+export type { LogLevel, LoggerOptions } from "./logger.js";
+export { Events } from "./events.js";
+export type { Listener } from "./events.js";
+export { Cache, MemoryStore } from "./cache.js";
+export type { CacheStore } from "./cache.js";
+export { serveStatic } from "./static.js";
+export type { StaticOptions } from "./static.js";
+export { dump, dd } from "./debug.js";
+export { hash, encryption } from "./crypto.js";
+export { rateLimiter } from "./rate-limit.js";
+export type { RateLimiterOptions } from "./rate-limit.js";
+export { db, setConnection, QueryBuilder } from "./database.js";
+export type { Connection, WriteResult, Row, Dialect, Operator } from "./database.js";
+export { Model } from "./model.js";
+export type { CastType, Casts } from "./casts.js";
+export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
+export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
+export type { Definition } from "./factory.js";
+export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
+export type { Message, Transport, MailerOptions, FetchTransportOptions } from "./mail.js";
+export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
+export type { Dispatchable, JobOptions, QueueDriver, Drainable, QueuedJob } from "./queue.js";
+export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
+export type { Notifiable, MailContent, Channel } from "./notification.js";
+export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
+export type { Migration } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
 export type { ConfigData } from "./config.js";
 export { View } from "./view.js";
@@ -12,10 +39,14 @@ export type { Renderable, ViewConfig } from "./view.js";
 export { ServiceProvider } from "./provider.js";
 export type { ProviderClass } from "./provider.js";
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
-export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher } from "./http/router.js";
+export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher, MiddlewareRef, UrlOptions, SignedUrlOptions, } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export type { InertiaPage, InertiaOptions } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
 export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
 export { validate } from "./validation.js";
 export type { Schema } from "./validation.js";
+export { Session, session, sessionMiddleware } from "./session.js";
+export type { SessionOptions } from "./session.js";
+export { Auth, auth, authGuard, setUserProvider } from "./auth.js";
+export type { UserProvider } from "./auth.js";

package/dist/core/index.js

@@ -2,7 +2,22 @@
 export { Container } from "./container.js";
 export { Application } from "./application.js";
 export { Config, env } from "./config.js";
-export { app, config, view, bind, singleton, instance, make, bound, } from "./helpers.js";
+export { app, config, view, bind, singleton, instance, make, bound, events, emit, listen, cache, logger, } from "./helpers.js";
+export { Logger } from "./logger.js";
+export { Events } from "./events.js";
+export { Cache, MemoryStore } from "./cache.js";
+export { serveStatic } from "./static.js";
+export { dump, dd } from "./debug.js";
+export { hash, encryption } from "./crypto.js";
+export { rateLimiter } from "./rate-limit.js";
+export { db, setConnection, QueryBuilder } from "./database.js";
+export { Model } from "./model.js";
+export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
+export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
+export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
+export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
+export { Notification, Notifier, MailChannel, DatabaseChannel, ArrayChannel, routeFor, notify, setNotifier, getNotifier, } from "./notification.js";
+export { SchemaBuilder, Migrator, TableBuilder, Column } from "./migrations.js";
 export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
 export { View } from "./view.js";
 export { ServiceProvider } from "./provider.js";
@@ -11,3 +26,5 @@ export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
 export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
 export { validate } from "./validation.js";
+export { Session, session, sessionMiddleware } from "./session.js";
+export { Auth, auth, authGuard, setUserProvider } from "./auth.js";

package/dist/core/logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A small leveled logger. Structured JSON by default (one line per event, ready
+ * for log aggregators); pretty single-line output in debug. Bound as a
+ * singleton on the application — reach it with the global `logger()` helper.
+ *
+ *   logger().info("user registered", { userId: user.id });
+ *   logger().error("payment failed", { orderId, error });
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LoggerOptions {
+    /** Minimum level to emit. Default: "info". */
+    level?: LogLevel;
+    /** Pretty single-line output instead of JSON. Default: false. */
+    pretty?: boolean;
+    /** Fields merged into every log line. */
+    bindings?: Record<string, unknown>;
+}
+export declare class Logger {
+    private options;
+    private threshold;
+    constructor(options?: LoggerOptions);
+    private write;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    /** A child logger with additional bound fields (e.g. a request id). */
+    child(bindings: Record<string, unknown>): Logger;
+}

package/dist/core/logger.js

@@ -0,0 +1,49 @@
+/**
+ * A small leveled logger. Structured JSON by default (one line per event, ready
+ * for log aggregators); pretty single-line output in debug. Bound as a
+ * singleton on the application — reach it with the global `logger()` helper.
+ *
+ *   logger().info("user registered", { userId: user.id });
+ *   logger().error("payment failed", { orderId, error });
+ */
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+export class Logger {
+    options;
+    threshold;
+    constructor(options = {}) {
+        this.options = options;
+        this.threshold = LEVELS[options.level ?? "info"];
+    }
+    write(level, message, context) {
+        if (LEVELS[level] < this.threshold)
+            return;
+        const time = new Date().toISOString();
+        if (this.options.pretty) {
+            const extra = context ? " " + JSON.stringify(context) : "";
+            const fn = level === "warn" ? console.warn : level === "error" ? console.error : console.log;
+            fn(`[${time}] ${level.toUpperCase().padEnd(5)} ${message}${extra}`);
+        }
+        else {
+            console.log(JSON.stringify({ level, time, msg: message, ...this.options.bindings, ...context }));
+        }
+    }
+    debug(message, context) {
+        this.write("debug", message, context);
+    }
+    info(message, context) {
+        this.write("info", message, context);
+    }
+    warn(message, context) {
+        this.write("warn", message, context);
+    }
+    error(message, context) {
+        this.write("error", message, context);
+    }
+    /** A child logger with additional bound fields (e.g. a request id). */
+    child(bindings) {
+        return new Logger({
+            ...this.options,
+            bindings: { ...this.options.bindings, ...bindings },
+        });
+    }
+}

package/dist/core/mail.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A small, edge-safe mailer. You compose a message with a fluent builder and
+ * send it through a pluggable `Transport` — the same shape as the database
+ * layer (`setMailer` / `mail()` mirror `setConnection` / `db()`). The core
+ * imports no SDK: the built-in transports use `fetch`, `console`, or memory, so
+ * it runs on Node and the edge.
+ *
+ *   setMailer(fetchTransport({ url, headers }), { from: "hi@app.com" });
+ *
+ *   await mail()
+ *     .to("ada@example.com")
+ *     .subject("Welcome")
+ *     .html("<h1>Hi</h1>")
+ *     .send();
+ *
+ * In tests, register an `ArrayTransport` and assert on `transport.sent`.
+ */
+/** A normalized, ready-to-send message. */
+export interface Message {
+    to: string[];
+    from?: string;
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    headers?: Record<string, string>;
+}
+/** The bridge to your email provider. */
+export interface Transport {
+    send(message: Message): Promise<void>;
+}
+export interface MailerOptions {
+    /** Default `from` address for messages that don't set one. */
+    from?: string;
+}
+/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+export declare class PendingMail {
+    private mailer;
+    private message;
+    constructor(mailer: Mailer);
+    to(...addresses: string[]): this;
+    from(address: string): this;
+    cc(...addresses: string[]): this;
+    bcc(...addresses: string[]): this;
+    replyTo(address: string): this;
+    subject(subject: string): this;
+    text(text: string): this;
+    html(html: string): this;
+    header(name: string, value: string): this;
+    /** Seed several fields at once (merges into what's been chained). */
+    fill(partial: Partial<{
+        to: string | string[];
+        cc: string | string[];
+        bcc: string | string[];
+    } & Omit<Message, "to" | "cc" | "bcc">>): this;
+    /** Freeze and hand the message to the mailer. */
+    send(): Promise<Message>;
+}
+export declare class Mailer {
+    private transport;
+    private options;
+    constructor(transport: Transport, options?: MailerOptions);
+    /** Start composing a message. */
+    message(): PendingMail;
+    /** Validate, apply defaults, and dispatch through the transport. */
+    send(message: Message): Promise<Message>;
+}
+/** Collects sent messages in memory — the default, and ideal for tests. */
+export declare class ArrayTransport implements Transport {
+    readonly sent: Message[];
+    send(message: Message): Promise<void>;
+}
+/** Logs each message instead of delivering it — handy in local development. */
+export declare class LogTransport implements Transport {
+    send(message: Message): Promise<void>;
+}
+export interface FetchTransportOptions {
+    /** Provider endpoint to POST to. */
+    url: string;
+    /** Extra headers (e.g. `Authorization`). `Content-Type: application/json` is added. */
+    headers?: Record<string, string>;
+    /** Map a message to the provider's request body. Defaults to the message itself. */
+    body?: (message: Message) => unknown;
+}
+/** A generic HTTP transport for provider APIs (Resend, Postmark, …), via `fetch`. */
+export declare function fetchTransport(options: FetchTransportOptions): Transport;
+/** Register the default mailer used by `mail()`. */
+export declare function setMailer(transport: Transport, options?: MailerOptions): Mailer;
+/** The default mailer instance. */
+export declare function getMailer(): Mailer;
+/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
+export declare function mail(): PendingMail;

package/dist/core/mail.js

@@ -0,0 +1,157 @@
+/**
+ * A small, edge-safe mailer. You compose a message with a fluent builder and
+ * send it through a pluggable `Transport` — the same shape as the database
+ * layer (`setMailer` / `mail()` mirror `setConnection` / `db()`). The core
+ * imports no SDK: the built-in transports use `fetch`, `console`, or memory, so
+ * it runs on Node and the edge.
+ *
+ *   setMailer(fetchTransport({ url, headers }), { from: "hi@app.com" });
+ *
+ *   await mail()
+ *     .to("ada@example.com")
+ *     .subject("Welcome")
+ *     .html("<h1>Hi</h1>")
+ *     .send();
+ *
+ * In tests, register an `ArrayTransport` and assert on `transport.sent`.
+ */
+import { logger } from "./helpers.js";
+function list(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+export class PendingMail {
+    mailer;
+    message = { to: [], subject: "" };
+    constructor(mailer) {
+        this.mailer = mailer;
+    }
+    to(...addresses) {
+        this.message.to.push(...addresses);
+        return this;
+    }
+    from(address) {
+        this.message.from = address;
+        return this;
+    }
+    cc(...addresses) {
+        (this.message.cc ??= []).push(...addresses);
+        return this;
+    }
+    bcc(...addresses) {
+        (this.message.bcc ??= []).push(...addresses);
+        return this;
+    }
+    replyTo(address) {
+        this.message.replyTo = address;
+        return this;
+    }
+    subject(subject) {
+        this.message.subject = subject;
+        return this;
+    }
+    text(text) {
+        this.message.text = text;
+        return this;
+    }
+    html(html) {
+        this.message.html = html;
+        return this;
+    }
+    header(name, value) {
+        (this.message.headers ??= {})[name] = value;
+        return this;
+    }
+    /** Seed several fields at once (merges into what's been chained). */
+    fill(partial) {
+        const { to, cc, bcc, ...rest } = partial;
+        if (to)
+            this.message.to.push(...list(to));
+        if (cc)
+            (this.message.cc ??= []).push(...list(cc));
+        if (bcc)
+            (this.message.bcc ??= []).push(...list(bcc));
+        Object.assign(this.message, rest);
+        return this;
+    }
+    /** Freeze and hand the message to the mailer. */
+    async send() {
+        return this.mailer.send(this.message);
+    }
+}
+export class Mailer {
+    transport;
+    options;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.options = options;
+    }
+    /** Start composing a message. */
+    message() {
+        return new PendingMail(this);
+    }
+    /** Validate, apply defaults, and dispatch through the transport. */
+    async send(message) {
+        const final = { ...message, from: message.from ?? this.options.from };
+        if (!final.to.length)
+            throw new Error("Mail: at least one recipient (to) is required.");
+        if (!final.subject)
+            throw new Error("Mail: a subject is required.");
+        if (!final.text && !final.html)
+            throw new Error("Mail: a text or html body is required.");
+        if (!final.from)
+            throw new Error("Mail: a from address is required (set one or a default).");
+        await this.transport.send(final);
+        return final;
+    }
+}
+/* ------------------------------- transports ------------------------------- */
+/** Collects sent messages in memory — the default, and ideal for tests. */
+export class ArrayTransport {
+    sent = [];
+    async send(message) {
+        this.sent.push(message);
+    }
+}
+/** Logs each message instead of delivering it — handy in local development. */
+export class LogTransport {
+    async send(message) {
+        logger().info("mail sent", {
+            to: message.to,
+            from: message.from,
+            subject: message.subject,
+        });
+    }
+}
+/** A generic HTTP transport for provider APIs (Resend, Postmark, …), via `fetch`. */
+export function fetchTransport(options) {
+    return {
+        async send(message) {
+            const res = await fetch(options.url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", ...options.headers },
+                body: JSON.stringify(options.body ? options.body(message) : message),
+            });
+            if (!res.ok) {
+                throw new Error(`Mail: transport responded ${res.status} ${res.statusText}`);
+            }
+        },
+    };
+}
+/* --------------------------------- global --------------------------------- */
+let mailer = new Mailer(new ArrayTransport());
+/** Register the default mailer used by `mail()`. */
+export function setMailer(transport, options = {}) {
+    mailer = new Mailer(transport, options);
+    return mailer;
+}
+/** The default mailer instance. */
+export function getMailer() {
+    return mailer;
+}
+/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
+export function mail() {
+    return mailer.message();
+}