@shaferllc/keel 0.66.0 → 0.74.0

package/docs/notifications.md

@@ -0,0 +1,474 @@
+# Notifications
+
+Send a message to a recipient over one or more **channels** — mail, database, or
+your own — inline or through the queue. This is where the mail and queue layers
+compose: a notification declares *what* to say and *which channels* carry it,
+and each channel decides *how*. Edge-safe, like everything under it.
+
+## Defining a notification
+
+Subclass `Notification`. `via()` lists the channels; each channel reads from a
+matching method (`toMail`, `toArray`):
+
+```ts
+import { Notification, type Notifiable, type MailContent } from "@shaferllc/keel/core";
+
+export class InvoicePaid extends Notification {
+  constructor(private amount: number) {
+    super();
+  }
+  via(_notifiable: Notifiable) {
+    return ["mail", "database"];
+  }
+  toMail(): MailContent {
+    return { subject: "Payment received", text: `Thanks for $${this.amount}.` };
+  }
+  toArray() {
+    return { amount: this.amount };
+  }
+}
+```
+
+Generate one with `keel make:notification InvoicePaid` (→
+`app/Notifications/InvoicePaidNotification.ts`).
+
+## Sending
+
+```ts
+import { notify } from "@shaferllc/keel/core";
+
+await notify(user, new InvoicePaid(4200));          // one recipient
+await notify([alice, bob], new InvoicePaid(4200));  // many
+```
+
+A recipient is any object with routing info — usually a `User` model. The mail
+channel routes to `notifiable.email`; override per channel with
+`routeNotificationFor`:
+
+```ts
+class User extends Model {
+  static table = "users";
+  routeNotificationFor(channel: string) {
+    return channel === "mail" ? this.billing_email : undefined;
+  }
+}
+```
+
+## Routing
+
+Each channel needs to know *where* a recipient receives it. `routeFor` resolves
+that: it calls the notifiable's `routeNotificationFor(channel)` first, and if
+that returns nothing it falls back to `notifiable.email` for the `mail` channel
+or `notifiable.id` for everything else.
+
+```ts
+import { routeFor } from "@shaferllc/keel/core";
+
+routeFor(user, "mail");     // user.email, unless routeNotificationFor overrides it
+routeFor(user, "database"); // user.id
+```
+
+So the common case needs no routing method at all — a `User` with `email` and
+`id` columns just works. Override `routeNotificationFor` only when a channel
+addresses the recipient differently (a billing address, a Slack id, a phone
+number). Return `undefined` from it to fall back to the default.
+
+The mail channel throws `Notification: no mail route …` if it can't resolve an
+address — set `email`, implement `routeNotificationFor`, or put a `to` on the
+`MailContent`.
+
+## Channels
+
+Register channels on the notifier (typically in a service provider). The `mail`
+channel is registered by default:
+
+```ts
+import { setNotifier, Notifier, DatabaseChannel } from "@shaferllc/keel/core";
+
+setNotifier(new Notifier().channel("database", new DatabaseChannel()));
+```
+
+| Channel | Delivers by |
+|---------|-------------|
+| `MailChannel` (`mail`, default) | The mailer, using the notification's `toMail`. Routes to `email`. |
+| `DatabaseChannel` (`database`) | Inserting `toArray` into a table (`type`, `notifiable_id`, `data`). |
+| `ArrayChannel` (`array`) | Collecting deliveries in `.sent` — for tests. |
+
+The database channel expects a table (default `notifications`) with `type`,
+`notifiable_id`, and a `data` (JSON) column — create it in a migration. Point it
+at another table by passing the name: `new DatabaseChannel("alerts")`.
+
+Delivery walks the channels named by `via()` in order, and each is looked up by
+name. If `via()` names a channel that was never registered, the notifier throws
+`No notification channel "…" registered.` — so register a channel before a
+notification routes to it. Likewise the mail channel throws if the notification
+has no `toMail()`.
+
+## Queued notifications
+
+Set `shouldQueue = true` and delivery happens from a queued job instead of on
+the request path — every channel runs inside the job:
+
+```ts
+export class InvoicePaid extends Notification {
+  shouldQueue = true;
+  // …
+}
+
+await notify(user, new InvoicePaid(4200)); // returns immediately; runs on the worker
+```
+
+With the `SyncDriver` (the default queue) it still runs immediately; with a
+`MemoryDriver` or a real broker it's deferred until a worker drains it.
+
+## A custom channel
+
+A channel is one method — `send`. That's the seam for SMS, Slack, push, or any
+provider:
+
+```ts
+import type { Channel, Notifiable, Notification } from "@shaferllc/keel/core";
+
+const slack: Channel = {
+  async send(notifiable, notification) {
+    const payload = notification.toArray?.(notifiable) ?? {};
+    // POST payload to a Slack webhook via fetch…
+  },
+};
+setNotifier(new Notifier().channel("slack", slack));
+```
+
+## In tests
+
+Register an `ArrayChannel` (or assert on the mail `ArrayTransport`) and check
+what was delivered — no network:
+
+```ts
+import { setNotifier, Notifier, ArrayChannel, notify } from "@shaferllc/keel/core";
+
+const array = new ArrayChannel();
+setNotifier(new Notifier().channel("array", array));
+
+await notify(user, new InvoicePaid(4200)); // a notification whose via() returns ["array"]
+
+assert.equal(array.sent.length, 1);
+assert.ok(array.sent[0].notification instanceof InvoicePaid);
+```
+
+## Related
+
+Notifications compose the [mail](./mail.md) and [queue](./queues.md) layers, and
+the database channel writes through the [query builder](./database.md). Reach for
+those directly when you need a one-off email or an ad-hoc queued job.
+
+---
+
+## API reference
+
+### `notify(notifiables, notification)`
+
+`notify(notifiables: Notifiable | Notifiable[], notification: Notification): Promise<void>`
+
+Sends a notification to one or many recipients through the default notifier.
+
+```ts
+await notify(user, new InvoicePaid(4200));
+await notify([alice, bob], new InvoicePaid(4200));
+```
+
+**Notes:** a thin wrapper over `getNotifier().send(...)`. If the notification's
+`shouldQueue` is `true`, it resolves once the job is *dispatched*, not once
+delivery finishes; otherwise it awaits every channel inline. A single recipient
+is normalized to a one-element list.
+
+### `setNotifier(instance)`
+
+`setNotifier(instance: Notifier): Notifier`
+
+Replaces the global notifier used by `notify()` and returns it.
+
+```ts
+setNotifier(new Notifier().channel("database", new DatabaseChannel()));
+```
+
+**Notes:** global — the last call wins. Because the default notifier only has the
+`mail` channel, this is how you register `database`, `array`, or custom channels
+app-wide (usually in a service provider).
+
+### `getNotifier()`
+
+`getNotifier(): Notifier`
+
+Returns the current global notifier — handy for registering a channel without
+swapping the instance.
+
+```ts
+getNotifier().channel("slack", slack);
+```
+
+**Notes:** returns the same instance every call until `setNotifier` replaces it.
+
+### `routeFor(notifiable, channel)`
+
+`routeFor(notifiable: Notifiable, channel: string): string | number | undefined`
+
+Resolves the address/id a notifiable receives a given channel at.
+
+```ts
+routeFor(user, "mail");     // user.email (string)
+routeFor(user, "database"); // user.id (number)
+```
+
+**Notes:** tries `notifiable.routeNotificationFor(channel)` first (skipped if it
+returns `null`/`undefined`), then falls back to `email` for `"mail"` and `id` for
+any other channel. Returns `undefined` when nothing resolves — channels decide
+whether that's an error.
+
+### `Notification`
+
+The abstract base for a notification. Subclass it, list channels from `via()`,
+and add a `to<Channel>()` builder per channel.
+
+#### `shouldQueue`
+
+`shouldQueue: boolean`
+
+Instance flag — set `true` to deliver from a queued job instead of inline.
+
+```ts
+class InvoicePaid extends Notification {
+  shouldQueue = true;
+}
+```
+
+**Notes:** defaults to `false`. Read by `Notifier.send`; when `true`, all
+channels run inside the dispatched job.
+
+#### `via(notifiable)`
+
+`via(notifiable: Notifiable): string[]`
+
+Returns the channel names to deliver on for this recipient.
+
+```ts
+via(notifiable: Notifiable) {
+  return notifiable.email ? ["mail", "database"] : ["database"];
+}
+```
+
+**Notes:** defaults to `["mail"]`. Called once per recipient, so you can branch
+on the notifiable. Every name it returns must be a registered channel or delivery
+throws.
+
+#### `toMail(notifiable)`
+
+`toMail?(notifiable: Notifiable): MailContent`
+
+Optional. Builds the content the `mail` channel sends. Required if `via()`
+includes `"mail"`.
+
+```ts
+toMail(): MailContent {
+  return { subject: "Payment received", text: "Thanks!" };
+}
+```
+
+**Notes:** the mail channel throws if `via()` names `"mail"` but this is
+undefined. Set `to` on the returned `MailContent` to override the resolved
+recipient address.
+
+#### `toArray(notifiable)`
+
+`toArray?(notifiable: Notifiable): Record<string, unknown>`
+
+Optional. Builds the payload the `database` and `array` channels serialize/store.
+
+```ts
+toArray() {
+  return { amount: this.amount };
+}
+```
+
+**Notes:** the database channel stores `{}` when it's undefined; the array
+channel keeps the whole notification, not this payload, so a missing `toArray`
+still works in tests.
+
+### `Notifier`
+
+Holds the channel registry and drives delivery. `notify()` uses a global one, but
+you can construct your own.
+
+#### `channel(name, channel)`
+
+`channel(name: string, channel: Channel): this`
+
+Registers (or replaces) a channel under a name; returns `this` to chain.
+
+```ts
+new Notifier()
+  .channel("database", new DatabaseChannel())
+  .channel("array", new ArrayChannel());
+```
+
+**Notes:** a fresh `Notifier` already has `mail` → `MailChannel`. Registering the
+same name again replaces it.
+
+#### `send(notifiables, notification)`
+
+`send(notifiables: Notifiable | Notifiable[], notification: Notification): Promise<void>`
+
+Delivers a notification to one or many recipients across the channels its `via()`
+returns.
+
+```ts
+await new Notifier().send(user, new InvoicePaid(4200));
+```
+
+**Notes:** normalizes a single recipient to a list, then delivers to each in
+order. Honors `notification.shouldQueue` (dispatches to the queue when set).
+Throws on the first unregistered channel name.
+
+### `MailChannel`
+
+The default `mail` channel. Registered on every `Notifier`; you rarely construct
+it yourself.
+
+#### `send(notifiable, notification)`
+
+`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+
+Builds a message from `notification.toMail()` and sends it through the mailer.
+
+```ts
+await new MailChannel().send(user, new InvoicePaid(4200));
+```
+
+**Notes:** throws `… has no toMail()` if the notification lacks one, and
+`Notification: no mail route …` if it can't resolve an address (from
+`MailContent.to` or `routeFor(notifiable, "mail")`). Applies `from`, `text`, and
+`html` only when present.
+
+### `DatabaseChannel`
+
+The `database` channel. Persists the `toArray` payload through the query builder.
+
+#### `new DatabaseChannel(table?)`
+
+`new DatabaseChannel(table?: string)`
+
+Creates a channel that writes to `table`.
+
+```ts
+new DatabaseChannel();          // → "notifications"
+new DatabaseChannel("alerts");  // → "alerts"
+```
+
+**Notes:** defaults to the `notifications` table.
+
+#### `send(notifiable, notification)`
+
+`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+
+Inserts one row: `type` (the notification's class name), `notifiable_id`
+(`routeFor(notifiable, "database")`, or `null`), and `data` (JSON of `toArray`).
+
+```ts
+await new DatabaseChannel().send(user, new InvoicePaid(4200));
+```
+
+**Notes:** stores `"{}"` for `data` when the notification has no `toArray`. The
+target table must exist — create it in a migration.
+
+### `ArrayChannel`
+
+An in-memory channel for tests — records deliveries instead of sending them.
+
+#### `sent`
+
+`readonly sent: { notifiable: Notifiable; notification: Notification }[]`
+
+The log of everything this channel received, in delivery order.
+
+```ts
+const array = new ArrayChannel();
+// … after notify …
+array.sent[0].notification; // the Notification instance
+```
+
+**Notes:** it keeps the notification *instance*, so you can `instanceof`-check it
+or read its fields — no serialization through `toArray`.
+
+#### `send(notifiable, notification)`
+
+`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+
+Pushes `{ notifiable, notification }` onto `sent`. Never touches the network.
+
+```ts
+new Notifier().channel("array", new ArrayChannel());
+```
+
+### Interfaces & types
+
+#### `Notifiable`
+
+```ts
+interface Notifiable {
+  routeNotificationFor?(channel: string): string | number | undefined;
+  [key: string]: unknown;
+}
+```
+
+A recipient — anything with routing info, most often a `User` model. Implement
+`routeNotificationFor` to steer specific channels; otherwise `routeFor` reads
+`email`/`id` off the index signature.
+
+```ts
+class User extends Model {
+  routeNotificationFor(channel: string) {
+    return channel === "mail" ? this.billing_email : undefined;
+  }
+}
+```
+
+#### `MailContent`
+
+```ts
+interface MailContent {
+  subject: string;
+  text?: string;
+  html?: string;
+  from?: string;
+  to?: string;
+}
+```
+
+What `toMail()` returns and the `mail` channel consumes. `subject` is required;
+supply `text`, `html`, or both. `to` overrides the resolved recipient; `from`
+overrides the mailer default.
+
+```ts
+toMail(): MailContent {
+  return { subject: "Welcome", html: "<h1>Hi</h1>", to: "override@app.com" };
+}
+```
+
+#### `Channel`
+
+```ts
+interface Channel {
+  send(notifiable: Notifiable, notification: Notification): Promise<void>;
+}
+```
+
+The seam a custom transport implements — SMS, Slack, push, anything. One method:
+`send`. Register your implementation with `Notifier.channel(name, channel)`.
+
+```ts
+const slack: Channel = {
+  async send(notifiable, notification) {
+    const payload = notification.toArray?.(notifiable) ?? {};
+    // POST payload to a Slack webhook via fetch…
+  },
+};
+```

package/docs/openapi.md

@@ -0,0 +1,111 @@
+# OpenAPI
+
+Keel OpenAPI generates an [OpenAPI 3](https://spec.openapis.org/oas/v3.0.3) spec
+from your routes and serves [Swagger UI](https://swagger.io/tools/swagger-ui/) to
+explore it. It's a Keel [package](./packages.md): one `register()` mounts the docs
+at `/docs` and the spec at `/docs/openapi.json`.
+
+Nothing is scraped or guessed. The generator reads Keel's own route table —
+methods, paths, names, and param constraints are always correct — and enriches
+each operation with whatever the route attaches via `.config(apiDoc(...))`.
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+
+export const providers = [AppServiceProvider, OpenApiServiceProvider];
+```
+
+Open `http://localhost:3000/docs`. That's enough for a spec of every route (paths,
+methods, path params). To add summaries, request/response schemas, and tags,
+document the routes.
+
+## Documenting a route
+
+`apiDoc()` returns route config the generator understands. Its `request` field is
+the same `{ body, query, params }` shape you hand `validateRequest`, so one set of
+Zod schemas both validates and documents:
+
+```ts
+import { apiDoc } from "@shaferllc/keel/openapi";
+import { validateRequest } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+
+router
+  .post("/users", [Users, "store"])
+  .config(apiDoc({
+    summary: "Create a user",
+    tags: ["users"],
+    request: { body: NewUser },
+    responses: { 201: { description: "The created user", schema: UserShape } },
+  }))
+  .middleware([validateRequest({ body: NewUser })]);
+```
+
+What the generator does with it:
+
+- **Path params** — `/users/:id` becomes `/users/{id}`; a `.where("id", /\d+/)`
+  constraint becomes a `pattern`.
+- **Query params** — a `request.query` schema's fields expand into query
+  parameters (each `required` per the schema).
+- **Request body** — a `request.body` schema becomes a JSON request body
+  (Zod → JSON Schema via Zod 4's `z.toJSONSchema`).
+- **Responses** — your documented responses, plus an automatic `422` when the
+  route validates input. Undocumented routes get a default `200`.
+- **Tags** — `tags`, or the first path segment.
+- **operationId** — the route's `.name()`, else `method_path`.
+
+Fields on `apiDoc`: `summary`, `description`, `tags`, `operationId`,
+`deprecated`, `request`, `responses`, and `hidden` (leave the route out entirely).
+Response and request schemas accept a Zod schema **or** a plain JSON Schema
+object.
+
+## Configuration
+
+`config/openapi.ts` (publish with `keel vendor:publish --tag openapi-config`):
+
+```ts
+export default {
+  enabled: true,
+  path: "docs",                 // /docs and /docs/openapi.json
+  title: "",                    // defaults to config("app.name")
+  version: "1.0.0",
+  servers: [],                  // e.g. ["https://api.example.com"]
+  public: false,                // serve in production too
+  cdn: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14",
+  ignorePaths: ["/watch"],      // route prefixes to leave out
+};
+```
+
+## Access
+
+Like [Watch](./watch.md), the docs are gated shut in production by default (open
+only when `app.debug` is on or the app isn't in production). Set `public: true` to
+serve them everywhere, or plug in your own check:
+
+```ts
+import { OpenApi } from "@shaferllc/keel/openapi";
+OpenApi.auth((c) => auth().check());
+```
+
+The gate guards the spec endpoint too.
+
+## Exporting the spec
+
+Write the spec to a file — for CI, client generation, or committing it:
+
+```bash
+keel openapi:export --out openapi.json
+```
+
+## On the UI dependency
+
+The spec (`/docs/openapi.json`) is generated with **zero dependencies** and runs
+anywhere Keel does, including the edge. The Swagger **UI** loads its assets from
+the configured `cdn` — the one external dependency, confined to the browser. Pin
+the version (the default is pinned) or point `cdn` at a copy you host if you need
+a fully self-contained deployment.

package/docs/packages.md

@@ -0,0 +1,118 @@
+# Packages
+
+A **package** is a redistributable slice of a Keel app — routes, a UI, config,
+migrations, console commands — that installs with a single `app.register(...)`.
+Keel's `ServiceProvider` is already the unit of composition; `PackageProvider`
+adds the conventions a *shippable* package needs so it can carry its own schema
+and assets instead of asking the app to wire them by hand.
+
+[Keel Watch](./watch.md) — the debug dashboard — is a first-party package and the
+reference implementation of everything below.
+
+## The shape of a package
+
+```ts
+import { PackageProvider, type Router } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export class BillingServiceProvider extends PackageProvider {
+  readonly name = "billing"; // used for publish grouping and diagnostics
+
+  register(): void {
+    this.mergeConfig("billing", { enabled: true, path: "billing" });
+    this.migrations([createInvoicesTable]);
+    this.publishes({ [join(here, "config.stub")]: "config/billing.ts" }, "billing-config");
+    this.commands([syncInvoicesCommand]);
+  }
+
+  boot(): void {
+    this.assets("billing/assets", join(here, "ui/dist"), { maxAge: 3600 });
+    this.routes((r: Router) => registerBillingRoutes(r), { prefix: "billing", as: "billing" });
+  }
+}
+```
+
+Scaffold that skeleton with `keel make:package billing`.
+
+## The helpers
+
+Each is a thin wrapper over an existing Keel primitive — the value is the
+convention, not new machinery.
+
+| Helper | What it does |
+|--------|--------------|
+| `mergeConfig(key, defaults)` | Set config defaults under `key`. The app's `config/<key>.ts` deep-merges **over** them, so the app always wins. |
+| `routes(register, { prefix, middleware, as })` | Register a route group (the callback gets the `Router`), already prefixed/guarded/name-prefixed. |
+| `assets(urlPrefix, dir, { maxAge, immutable })` | Serve a directory of built files (a bundled UI) under a URL prefix. Node-only. |
+| `migrations(list)` | Contribute migrations, run by `keel migrate` alongside the app's own. |
+| `commands(list)` | Add `keel` console commands (e.g. `billing:sync`). |
+| `publishes(map, tag?)` | Declare files a consuming app can copy in with `keel vendor:publish`. |
+
+## Lifecycle: mind the kernel
+
+`register()` and `boot()` run **before** the app's HTTP kernel is bound (see
+`bootstrap/app.ts`). So a package must not reach for `HttpKernel`. That's why
+`routes()` and `assets()` go through the `Router` (bound in the Application
+constructor) — routes are compiled onto the kernel later, at build time. Use
+`register()` for config/bindings and `boot()` for wiring; both are safe for the
+helpers above.
+
+## Migrations
+
+Package migrations join the app's under one command:
+
+```bash
+keel migrate           # run pending (app + package) migrations
+keel migrate:status    # show which have run
+keel migrate:rollback  # roll back the last batch
+```
+
+App migrations are discovered from `database/migrations/*.ts` (each file
+default-exports a `Migration` or `Migration[]`); package migrations come from
+`this.migrations(...)`. Both run against the default connection.
+
+## Publishing files
+
+`publishes()` declares source→destination copies; `keel vendor:publish` performs
+them (skipping files that already exist unless `--force`):
+
+```bash
+keel vendor:publish                     # everything
+keel vendor:publish --tag billing-config # just one tagged group
+```
+
+This is how a package ships an overridable config stub, or copies a starter view
+into the consuming app.
+
+## Observing the framework
+
+A package often wants to *see* what the app is doing — every query, request, or
+job — without patching anything. The framework emits a typed **instrumentation
+event stream** for exactly this; subscribe with `listen()`:
+
+```ts
+import { listen, type QueryEvent } from "@shaferllc/keel/core";
+
+listen<QueryEvent>("db.query", (e) => metrics.timing("db", e.durationMs));
+```
+
+| Event | Fired when |
+|-------|-----------|
+| `db.query` | a query runs (sql, bindings, durationMs, connection, kind) |
+| `request.handled` | a request finishes (method, path, status, durationMs, headers) |
+| `exception` | an error reaches the HTTP kernel |
+| `job.processing` / `job.processed` / `job.failed` | a queued job's lifecycle |
+| `cache.hit` / `cache.miss` | a cache lookup |
+| `notification.sent` | a notification is delivered |
+| `schedule.task.run` | a scheduled task runs |
+| `mail.sending` / `mail.sent` | mail lifecycle |
+
+Every request opens a scope with a **request id** that flows through async work,
+so anything emitted inside a request can attribute itself to it via
+`currentRequestId()` — that's what lets [Watch](./watch.md) tie a request to the
+queries and logs it produced. Emitting is fire-and-forget: a broken listener can
+never break the work it observes.
+```