@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/mail.js

@@ -13,15 +13,33 @@
  *     .html("<h1>Hi</h1>")
  *     .send();
  *
- * In tests, register an `ArrayTransport` and assert on `transport.sent`.
+ * Sending is slow and it fails — which is exactly what a queue is for. `sendLater()`
+ * puts the message on the queue instead of holding the request open for an SMTP
+ * round trip:
+ *
+ *   await mail().to(user.email).subject("Welcome").html(body).sendLater();
+ *
+ * In tests, `fakeMail()` swaps the transport for one that records and asserts.
+ */
+import { logger, emit, hasApplication } from "./helpers.js";
+import { dispatch, Job } from "./queue.js";
+import { contentTypeFor } from "./storage.js";
+/**
+ * Fire a mail lifecycle event, but only if there's an application to fire it on —
+ * the mailer has to work in a unit test that never bootstrapped one. A listener
+ * that throws still surfaces; it's only the missing-app case we skip.
  */
-import { logger } from "./helpers.js";
+async function notify(event, message) {
+    if (hasApplication())
+        await emit(event, message);
+}
 function list(value) {
     if (value === undefined)
         return [];
     return Array.isArray(value) ? value : [value];
 }
-/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+/* --------------------------------- builder -------------------------------- */
+/** A fluent, immutable-ish builder — chain setters, then `send()` or `sendLater()`. */
 export class PendingMail {
     mailer;
     message = { to: [], subject: "" };
@@ -64,6 +82,29 @@ export class PendingMail {
         (this.message.headers ??= {})[name] = value;
         return this;
     }
+    /** Attach a file. The content type is inferred from the extension if omitted. */
+    attach(filename, content, contentType) {
+        (this.message.attachments ??= []).push({
+            filename,
+            content,
+            contentType: contentType ?? contentTypeFor(filename),
+        });
+        return this;
+    }
+    /**
+     * Attach an image and give it a content id, so the HTML body can show it inline:
+     *
+     *   .embed("logo", bytes, "logo.png").html(`<img src="cid:logo">`)
+     */
+    embed(cid, content, filename = cid, contentType) {
+        (this.message.attachments ??= []).push({
+            filename,
+            content,
+            contentType: contentType ?? contentTypeFor(filename),
+            cid,
+        });
+        return this;
+    }
     /** Seed several fields at once (merges into what's been chained). */
     fill(partial) {
         const { to, cc, bcc, ...rest } = partial;
@@ -76,25 +117,79 @@ export class PendingMail {
         Object.assign(this.message, rest);
         return this;
     }
+    /** The message as composed so far — before the mailer applies its defaults. */
+    toMessage() {
+        return { ...this.message };
+    }
     /** Freeze and hand the message to the mailer. */
     async send() {
         return this.mailer.send(this.message);
     }
+    /**
+     * Queue the message instead of sending it now — the request returns without
+     * waiting on the provider, and a failed send retries on the queue rather than
+     * failing the user's action.
+     *
+     * With the default `SyncDriver` this still sends inline; register a real queue
+     * driver to actually defer it.
+     */
+    async sendLater() {
+        await this.mailer.sendLater(this.message);
+    }
+}
+/* ------------------------------- class mails ------------------------------ */
+/**
+ * A reusable, testable email as a class — the mail equivalent of a `Job`.
+ * Implement `build()` to compose the message; the mailer calls it for you.
+ *
+ *   export class WelcomeEmail extends BaseMail {
+ *     constructor(private user: User) { super(); }
+ *
+ *     build(message: PendingMail) {
+ *       message.to(this.user.email).subject("Welcome").html(`<h1>Hi ${this.user.name}</h1>`);
+ *     }
+ *   }
+ *
+ *   await send(new WelcomeEmail(user));       // or sendLater(new WelcomeEmail(user))
+ */
+export class BaseMail {
+}
+/** The job that carries a queued message. Exported so a driver can recognize it. */
+export class SendMailJob extends Job {
+    message;
+    mailerName;
+    constructor(message, mailerName) {
+        super();
+        this.message = message;
+        this.mailerName = mailerName;
+    }
+    async handle() {
+        await mailer(this.mailerName).send(this.message);
+    }
 }
+/* --------------------------------- mailer --------------------------------- */
 export class Mailer {
     transport;
     options;
-    constructor(transport, options = {}) {
+    name;
+    constructor(transport, options = {}, 
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    name = "default") {
         this.transport = transport;
         this.options = options;
+        this.name = name;
     }
     /** 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 };
+    /** Apply this mailer's defaults and check the message is sendable. */
+    prepare(message) {
+        const final = {
+            ...message,
+            from: message.from ?? this.options.from,
+            replyTo: message.replyTo ?? this.options.replyTo,
+        };
         if (!final.to.length)
             throw new Error("Mail: at least one recipient (to) is required.");
         if (!final.subject)
@@ -103,9 +198,29 @@ export class Mailer {
             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).");
+        return final;
+    }
+    /** Validate, apply defaults, and dispatch through the transport. */
+    async send(message) {
+        const final = this.prepare(message);
+        await notify("mail.sending", final);
         await this.transport.send(final);
+        await notify("mail.sent", final);
+        return final;
+    }
+    /** Validate, apply defaults, and put the message on the queue. */
+    async sendLater(message) {
+        // Validate *now*, not on the worker: a malformed message should blow up at
+        // the call site, where the stack trace means something.
+        const final = this.prepare(message);
+        await dispatch(new SendMailJob(final, this.name));
+        await notify("mail.queued", final);
         return final;
     }
+    /** The underlying transport, for provider-specific operations. */
+    get driver() {
+        return this.transport;
+    }
 }
 /* ------------------------------- transports ------------------------------- */
 /** Collects sent messages in memory — the default, and ideal for tests. */
@@ -140,18 +255,151 @@ export function fetchTransport(options) {
         },
     };
 }
+/**
+ * A `Mailer` that records instead of delivering, with assertions — what
+ * `fakeMail()` installs so tests never talk to a provider.
+ */
+export class FakeMailer extends Mailer {
+    mails = [];
+    constructor(name = "default", options = {}) {
+        // A from address so a fake never trips the "from is required" check.
+        super(new ArrayTransport(), { from: "fake@example.com", ...options }, name);
+    }
+    async send(message) {
+        const final = await super.send(message);
+        this.mails.push({ message: final, queued: false });
+        return final;
+    }
+    async sendLater(message) {
+        // Validate exactly as a real mailer would, but don't touch the queue —
+        // recording the intent *is* the point.
+        const final = this.prepare(message);
+        this.mails.push({ message: final, queued: true });
+        await notify("mail.queued", final);
+        return final;
+    }
+    /** Everything sent immediately. */
+    sent() {
+        return this.mails.filter((m) => !m.queued).map((m) => m.message);
+    }
+    /** Everything queued with `sendLater()`. */
+    queued() {
+        return this.mails.filter((m) => m.queued).map((m) => m.message);
+    }
+    assertSent(where) {
+        const matches = this.sent().filter((m) => where?.(m) ?? true);
+        if (matches.length)
+            return;
+        throw new Error(where && this.sent().length
+            ? `Expected a sent mail matching the predicate. ${this.sent().length} were sent, but none matched.`
+            : `Expected a mail to be sent, but none was. ${this.summary()}`);
+    }
+    assertNotSent(where) {
+        const found = this.sent().filter((m) => where?.(m) ?? true).length;
+        if (found)
+            throw new Error(`Expected no matching mail to be sent, but ${found} was.`);
+    }
+    assertSentCount(expected) {
+        const found = this.sent().length;
+        if (found !== expected) {
+            throw new Error(`Expected ${expected} mail(s) to be sent, but ${found} were.`);
+        }
+    }
+    assertQueued(where) {
+        const matches = this.queued().filter((m) => where?.(m) ?? true);
+        if (matches.length)
+            return;
+        throw new Error(where && this.queued().length
+            ? `Expected a queued mail matching the predicate. ${this.queued().length} were queued, but none matched.`
+            : `Expected a mail to be queued, but none was. ${this.summary()}`);
+    }
+    assertNotQueued(where) {
+        const found = this.queued().filter((m) => where?.(m) ?? true).length;
+        if (found)
+            throw new Error(`Expected no matching mail to be queued, but ${found} was.`);
+    }
+    assertQueuedCount(expected) {
+        const found = this.queued().length;
+        if (found !== expected) {
+            throw new Error(`Expected ${expected} mail(s) to be queued, but ${found} were.`);
+        }
+    }
+    /** Nothing sent and nothing queued. */
+    assertNothingSent() {
+        if (this.mails.length) {
+            throw new Error(`Expected no mail at all, but ${this.mails.length} were recorded. ${this.summary()}`);
+        }
+    }
+    summary() {
+        if (!this.mails.length)
+            return "No mail was sent or queued.";
+        const subjects = this.mails.map((m) => `"${m.message.subject}"`).join(", ");
+        return `Recorded: ${subjects}.`;
+    }
+}
 /* --------------------------------- 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;
+const mailers = new Map([["default", new Mailer(new ArrayTransport())]]);
+/** Mailers displaced by `fakeMail()`, so `restoreMail()` can put them back. */
+const realMailers = new Map();
+/** Register a mailer, optionally under a name (default: `"default"`). */
+export function setMailer(transport, options = {}, name = "default") {
+    const instance = new Mailer(transport, options, name);
+    mailers.set(name, instance);
+    return instance;
+}
+/** The default mailer, or a named one registered with `setMailer(…, …, name)`. */
+export function mailer(name = "default") {
+    const instance = mailers.get(name);
+    if (!instance)
+        throw new Error(`No mailer named "${name}". Register it with setMailer().`);
+    return instance;
 }
 /** The default mailer instance. */
 export function getMailer() {
-    return mailer;
+    return mailer();
+}
+/** Start a message on a mailer: `mail().to(…).subject(…).send()`. */
+export function mail(name = "default") {
+    return mailer(name).message();
+}
+/** Build a `BaseMail` into a message on the given mailer. */
+async function build(email, name) {
+    const pending = mailer(name).message();
+    await email.build(pending);
+    return pending.toMessage();
 }
-/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
-export function mail() {
-    return mailer.message();
+/** Send a class-based mail now. */
+export async function send(email, name = "default") {
+    return mailer(name).send(await build(email, name));
+}
+/** Queue a class-based mail. */
+export async function sendLater(email, name = "default") {
+    return mailer(name).sendLater(await build(email, name));
+}
+/**
+ * Swap a mailer for a `FakeMailer` so tests never talk to a provider, and assert
+ * on what was sent or queued. Undo with `restoreMail()`.
+ *
+ *   const mail = fakeMail();
+ *   await registerUser();
+ *   mail.assertQueued((m) => m.subject === "Welcome");
+ */
+export function fakeMail(name = "default") {
+    const existing = mailers.get(name);
+    // Only remember the *real* mailer — faking twice must not stash a fake.
+    if (existing && !realMailers.has(name))
+        realMailers.set(name, existing);
+    const fake = new FakeMailer(name);
+    mailers.set(name, fake);
+    return fake;
+}
+/** Restore the real mailer after `fakeMail()`. With no name, restores them all. */
+export function restoreMail(name) {
+    const names = name ? [name] : [...realMailers.keys()];
+    for (const key of names) {
+        const real = realMailers.get(key);
+        if (real)
+            mailers.set(key, real);
+        realMailers.delete(key);
+    }
 }

package/dist/core/notification.js

@@ -20,6 +20,7 @@
 import { db } from "./database.js";
 import { getMailer } from "./mail.js";
 import { dispatch } from "./queue.js";
+import { instrument, currentRequestId } from "./instrumentation.js";
 export class Notification {
     /** Deliver from a queued job instead of inline. */
     shouldQueue = false;
@@ -103,8 +104,16 @@ export class Notifier {
     async send(notifiables, notification) {
         const recipients = Array.isArray(notifiables) ? notifiables : [notifiables];
         const run = async () => {
-            for (const recipient of recipients)
+            for (const recipient of recipients) {
                 await this.deliver(recipient, notification);
+                const requestId = currentRequestId();
+                instrument("notification.sent", {
+                    notification: notification.constructor.name,
+                    channels: notification.via(recipient),
+                    notifiable: recipient,
+                    ...(requestId ? { requestId } : {}),
+                });
+            }
         };
         if (notification.shouldQueue)
             await dispatch(run);

package/dist/core/package.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The package system. Keel's `ServiceProvider` is already its plugin unit —
+ * `PackageProvider` is the same thing with batteries for the jobs a *shippable*
+ * package does over and over: merge its config defaults, register its routes and
+ * bundled UI assets, contribute migrations and console commands, and declare
+ * files a consuming app can publish. Each helper is a thin wrapper over an
+ * existing Keel primitive; the value is the convention, not new machinery.
+ *
+ *   export class WatchServiceProvider extends PackageProvider {
+ *     readonly name = "watch";
+ *     register() {
+ *       this.mergeConfig("watch", defaultConfig);
+ *       this.migrations([watchMigration]);
+ *       this.publishes({ [stub]: "config/watch.ts" }, "watch-config");
+ *     }
+ *     boot() {
+ *       this.assets("watch/assets", uiDir, { immutable: true });
+ *       this.routes((r) => registerWatchRoutes(r), { prefix: "watch", as: "watch" });
+ *     }
+ *   }
+ *
+ * A note on lifecycle: register/boot run *before* the app's HTTP kernel is bound
+ * (see `bootstrap/app.ts`), so a package must not reach for the kernel. That's
+ * why `routes()` and `assets()` go through the `Router` (bound in the
+ * Application constructor) — routes are compiled onto the kernel later, at build.
+ */
+import type { MiddlewareHandler } from "hono";
+import type { Command } from "commander";
+import { ServiceProvider } from "./provider.js";
+import type { Application } from "./application.js";
+import type { Router, RouteGroup, MiddlewareRef } from "./http/router.js";
+import type { Migration } from "./migrations.js";
+/**
+ * Every migration a package contributes, gathered in one place so `keel migrate`
+ * can run them alongside the app's own. Bound as a singleton on the Application.
+ */
+export declare class MigrationRegistry {
+    private list;
+    add(migrations: Migration[]): void;
+    all(): Migration[];
+}
+/** A console command a package adds to `keel`. */
+export interface PackageCommand {
+    /** The command name, e.g. `"watch:prune"`. */
+    name: string;
+    description?: string;
+    /** Add arguments/options to the commander command before its action. */
+    configure?: (cmd: Command) => void;
+    /** What the command does. Receives parsed options and the command. */
+    action: (opts: Record<string, unknown>, cmd: Command) => void | Promise<void>;
+}
+/** Package-contributed console commands, mounted by the CLI after boot. */
+export declare class CommandRegistry {
+    private list;
+    add(commands: PackageCommand[]): void;
+    all(): PackageCommand[];
+}
+/** One `publishes()` declaration: source→destination files, optionally tagged. */
+export interface PublishEntry {
+    package: string;
+    tag?: string;
+    /** Absolute-or-package source path → app-relative destination path. */
+    files: Record<string, string>;
+}
+/** What `keel vendor:publish` copies into a consuming app. */
+export declare class PublishRegistry {
+    private entries;
+    add(entry: PublishEntry): void;
+    all(tag?: string): PublishEntry[];
+    tags(): string[];
+}
+export interface PackageRouteOptions {
+    /** Mount every route under this path prefix. */
+    prefix?: string;
+    /** Middleware to run before every route in the group. */
+    middleware?: MiddlewareRef | MiddlewareRef[];
+    /** Prefix every named route with `<as>.`. */
+    as?: string;
+}
+export interface PackageAssetOptions {
+    /** Cache-Control max-age (seconds). */
+    maxAge?: number;
+    /** Add `immutable` — for content-hashed filenames. */
+    immutable?: boolean;
+}
+export declare abstract class PackageProvider<O = Record<string, unknown>> extends ServiceProvider<O> {
+    /** The package's short name — used for publish grouping and diagnostics. */
+    abstract readonly name: string;
+    constructor(app: Application, options?: O);
+    /**
+     * Set config defaults under `key` without clobbering what the app already
+     * configured. Config files load before providers, so the app's `config/<key>.ts`
+     * (if any) is deep-merged *over* these defaults — the app always wins.
+     */
+    protected mergeConfig(key: string, defaults: Record<string, unknown>): void;
+    /**
+     * Register a group of routes. The callback receives the `Router`; the returned
+     * `RouteGroup` is already prefixed/guarded/named per `options`, and chainable
+     * for anything more.
+     */
+    protected routes(register: (router: Router) => void, options?: PackageRouteOptions): RouteGroup;
+    /**
+     * Serve a directory of static files (a bundled UI, images, …) under a URL
+     * prefix. Node-only. Mounts one wildcard route on the `Router`.
+     */
+    protected assets(urlPrefix: string, dir: string, options?: PackageAssetOptions): void;
+    /** Contribute migrations, run by `keel migrate` with the app's own. */
+    protected migrations(list: Migration[]): void;
+    /** Contribute console commands, mounted on `keel` after the app boots. */
+    protected commands(list: PackageCommand[]): void;
+    /**
+     * Declare files a consuming app can copy into itself with
+     * `keel vendor:publish` (optionally `--tag <tag>`): config stubs, views, etc.
+     * Keys are source paths (usually inside the package), values app-relative
+     * destinations.
+     */
+    protected publishes(files: Record<string, string>, tag?: string): void;
+}
+/** A middleware alias, re-exported so packages needn't reach into `hono`. */
+export type PackageMiddleware = MiddlewareHandler;

package/dist/core/package.js

@@ -0,0 +1,169 @@
+/**
+ * The package system. Keel's `ServiceProvider` is already its plugin unit —
+ * `PackageProvider` is the same thing with batteries for the jobs a *shippable*
+ * package does over and over: merge its config defaults, register its routes and
+ * bundled UI assets, contribute migrations and console commands, and declare
+ * files a consuming app can publish. Each helper is a thin wrapper over an
+ * existing Keel primitive; the value is the convention, not new machinery.
+ *
+ *   export class WatchServiceProvider extends PackageProvider {
+ *     readonly name = "watch";
+ *     register() {
+ *       this.mergeConfig("watch", defaultConfig);
+ *       this.migrations([watchMigration]);
+ *       this.publishes({ [stub]: "config/watch.ts" }, "watch-config");
+ *     }
+ *     boot() {
+ *       this.assets("watch/assets", uiDir, { immutable: true });
+ *       this.routes((r) => registerWatchRoutes(r), { prefix: "watch", as: "watch" });
+ *     }
+ *   }
+ *
+ * A note on lifecycle: register/boot run *before* the app's HTTP kernel is bound
+ * (see `bootstrap/app.ts`), so a package must not reach for the kernel. That's
+ * why `routes()` and `assets()` go through the `Router` (bound in the
+ * Application constructor) — routes are compiled onto the kernel later, at build.
+ */
+import { getMimeType } from "hono/utils/mime";
+import { ServiceProvider } from "./provider.js";
+import { NotFoundException } from "./exceptions.js";
+/* ------------------------------- registries ------------------------------- */
+/**
+ * Every migration a package contributes, gathered in one place so `keel migrate`
+ * can run them alongside the app's own. Bound as a singleton on the Application.
+ */
+export class MigrationRegistry {
+    list = [];
+    add(migrations) {
+        this.list.push(...migrations);
+    }
+    all() {
+        return [...this.list];
+    }
+}
+/** Package-contributed console commands, mounted by the CLI after boot. */
+export class CommandRegistry {
+    list = [];
+    add(commands) {
+        this.list.push(...commands);
+    }
+    all() {
+        return [...this.list];
+    }
+}
+/** What `keel vendor:publish` copies into a consuming app. */
+export class PublishRegistry {
+    entries = [];
+    add(entry) {
+        this.entries.push(entry);
+    }
+    all(tag) {
+        return tag ? this.entries.filter((e) => e.tag === tag) : [...this.entries];
+    }
+    tags() {
+        return [...new Set(this.entries.map((e) => e.tag).filter((t) => !!t))];
+    }
+}
+/* --------------------------------- helpers -------------------------------- */
+/** Deep-merge two plain objects; `override` wins, arrays are replaced wholesale. */
+function deepMerge(base, override) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const existing = out[key];
+        if (isPlainObject(existing) && isPlainObject(value)) {
+            out[key] = deepMerge(existing, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A route handler that serves files from `dir` for requests under `prefix`. Used
+ * by `PackageProvider.assets()` so a package can ship a built UI without the
+ * consuming app copying anything into `public/`. Node-only (uses `node:fs`);
+ * a miss becomes a 404 so it doesn't shadow real routes.
+ */
+function packageAssetHandler(prefix, dir, options) {
+    const root = dir.replace(/\/+$/, "");
+    return async (c) => {
+        const pathname = decodeURIComponent(new URL(c.req.url).pathname);
+        const rel = pathname.slice(prefix.length).replace(/^\/+/, "");
+        if (rel.includes(".."))
+            throw new NotFoundException();
+        const { stat, readFile } = await import("node:fs/promises");
+        const filePath = `${root}/${rel}`;
+        const stats = await stat(filePath).catch(() => null);
+        if (!stats?.isFile())
+            throw new NotFoundException();
+        const headers = {
+            "Content-Type": getMimeType(filePath) ?? "application/octet-stream",
+        };
+        if (options.maxAge != null) {
+            headers["Cache-Control"] =
+                `public, max-age=${options.maxAge}${options.immutable ? ", immutable" : ""}`;
+        }
+        return new Response(await readFile(filePath), { headers });
+    };
+}
+/* ----------------------------- PackageProvider ---------------------------- */
+export class PackageProvider extends ServiceProvider {
+    constructor(app, options) {
+        super(app, options);
+    }
+    /**
+     * Set config defaults under `key` without clobbering what the app already
+     * configured. Config files load before providers, so the app's `config/<key>.ts`
+     * (if any) is deep-merged *over* these defaults — the app always wins.
+     */
+    mergeConfig(key, defaults) {
+        const cfg = this.app.config();
+        const existing = cfg.get(key);
+        cfg.set(key, isPlainObject(existing) ? deepMerge(defaults, existing) : defaults);
+    }
+    /**
+     * Register a group of routes. The callback receives the `Router`; the returned
+     * `RouteGroup` is already prefixed/guarded/named per `options`, and chainable
+     * for anything more.
+     */
+    routes(register, options = {}) {
+        const router = this.app.router();
+        const group = router.group(() => register(router));
+        if (options.prefix)
+            group.prefix(options.prefix);
+        if (options.middleware)
+            group.middleware(options.middleware);
+        if (options.as)
+            group.as(options.as);
+        return group;
+    }
+    /**
+     * Serve a directory of static files (a bundled UI, images, …) under a URL
+     * prefix. Node-only. Mounts one wildcard route on the `Router`.
+     */
+    assets(urlPrefix, dir, options = {}) {
+        const prefix = "/" + urlPrefix.replace(/^\/|\/$/g, "");
+        this.app.router().get(`${prefix}/*`, packageAssetHandler(prefix, dir, options));
+    }
+    /** Contribute migrations, run by `keel migrate` with the app's own. */
+    migrations(list) {
+        this.app.make(MigrationRegistry).add(list);
+    }
+    /** Contribute console commands, mounted on `keel` after the app boots. */
+    commands(list) {
+        this.app.make(CommandRegistry).add(list);
+    }
+    /**
+     * Declare files a consuming app can copy into itself with
+     * `keel vendor:publish` (optionally `--tag <tag>`): config stubs, views, etc.
+     * Keys are source paths (usually inside the package), values app-relative
+     * destinations.
+     */
+    publishes(files, tag) {
+        this.app.make(PublishRegistry).add({ package: this.name, ...(tag ? { tag } : {}), files });
+    }
+}