@shaferllc/keel 0.83.0 → 0.83.2

package/docs/changelog.md

@@ -4,6 +4,110 @@ All notable changes to Keel are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
 adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.83.2] — 2026-07-12
+
+### Added
+
+- **More runnable doc examples.** Billing, ORM, query builder, CORS, security,
+  social auth, OpenAPI, Watch, packages, Hono, and starter kits now have
+  typechecked harnesses under `docs/examples/` — the same ones
+  `npm run typecheck:docs` compiles against the published surface.
+- **Worked examples in the guides** — a complete billing subscribe flow (with
+  `FakeGateway`), an ORM CRUD+eager-load walkthrough, a production CORS recipe,
+  and a clearer starter-kit picker.
+
+### Changed
+
+- Watch no longer describes itself by another product's name.
+
+[0.83.2]: https://github.com/shaferllc/keel/releases/tag/v0.83.2
+
+## [0.83.0] — 2026-07-12
+
+### Added
+
+- **Starter kits, and a generator that can't fall behind.** Four curated
+  applications — `minimal`, `api`, `app` (views, sessions, register/login, password
+  reset, two-factor), and `saas` (teams, roles, invitations, billing,
+  multi-tenancy):
+
+  ```bash
+  npm create keeljs@latest my-app -- --preset saas
+  ```
+
+  The templates ship **inside this package**, so the version a kit is generated from
+  is, by construction, the version it was written for. The old standalone starter
+  drifted to five releases behind and nothing noticed; CI now generates all four kits
+  on every push and typechecks, migrates, boots, serves a request, bundles the
+  Worker, and runs their tests.
+
+- **Teams (`@shaferllc/keel/teams`)** — multi-tenancy, membership, roles, and
+  invitations. `TenantModel` makes isolation the default rather than a habit: reads
+  are constrained by an inherited global scope (so even `find(id)` returns `null` for
+  another team's row — not a filter you can forget), and writes are stamped with the
+  current team, so a row can't be born ownerless.
+
+  Outside a team context a tenant query **throws**. A job, console command, or
+  webhook has no request and therefore no team; returning everything is how one
+  customer's data reaches another, and `team_id = NULL` means jobs quietly do
+  nothing. So work says which team it is for — `runForTeam(team, fn)` — or says out
+  loud that it spans all of them — `withoutTenant(fn)`. Both are greppable at audit
+  time.
+
+- **Accounts (`@shaferllc/keel/accounts`)** — password reset, email verification, and
+  two-factor, mounted with one provider. A correct password on a 2FA account yields a
+  short-lived, single-purpose **challenge, not a session**, so there is no
+  half-authenticated state for a route to forget to check. TOTP is RFC 6238, verified
+  against the RFC's published vectors, WebCrypto-only, and therefore edge-safe. No
+  tokens table: reset links carry their own purpose and expiry and are bound to a
+  fingerprint of the current password hash, so spending one kills it.
+
+- **D1 over HTTP (`@shaferllc/keel/db/d1-http`).** The D1 binding only exists inside a
+  Worker, so `keel migrate` had nowhere to point and you could not create your
+  tables. The same `Connection` over D1's HTTP API closes that: migrations run from a
+  laptop and from CI. It treats an error in the response *body* as an error even when
+  the status is 200 — which is how Cloudflare often reports them, and trusting the
+  status would let a failed migration look like it succeeded.
+
+- **`Model.withoutGlobalScope(...)` / `withoutGlobalScopes()`** — escaping a scope
+  should be typed out and greppable, never something you arrive at by forgetting a
+  `where`.
+
+### Fixed
+
+- **Global scopes and model hooks now inherit.** Both were keyed by the exact class,
+  so a scope or a `creating` hook declared on a *base* class was silently ignored by
+  every subclass. The models guide advertises global scopes as "the base for
+  multi-tenancy", and that was precisely the case that didn't work: the scope did
+  nothing, the query returned every tenant's rows, and nothing complained. It failed
+  **open**. Both now walk the prototype chain, and a scope is passed the model it is
+  scoping so a base class can read each subclass's own configuration.
+
+- **The official `@libsql/client` no longer needs a cast.** Under
+  `strictFunctionTypes` the narrower parameter types made the real `Client`
+  unassignable to `LibSqlLike`, so wiring libSQL the obvious way required
+  `client as unknown as LibSqlLike` — a cast even Keel's own tests carried.
+
+- **`createTeam()` could not give two people with the same name a team.** It slugged
+  the name into a `UNIQUE` column, so the second "Ada" to sign up got a 500. Looking
+  for a free slug first is check-then-act and loses the race anyway; the unique index
+  is the only real arbiter, so it now arbitrates and the insert retries.
+
+## [0.82.0] — 2026-07-12
+
+### Added
+
+- **Query builder: the methods people actually reach for.** `join`/`leftJoin`,
+  `groupBy`/`having`/`distinct`, `whereColumn`/`whereRaw`/`orderByRaw`, `when`,
+  `increment`/`decrement`, `upsert`/`insertOrIgnore`, and `chunk`, with docs.
+
+## [0.81.2] — 2026-07-12
+
+### Documentation
+
+- **The changelog is published to the docs site** (`docs/changelog.md`), so releases
+  are readable at keeljs.com rather than only in the repository.
+
 ## [0.81.1] — 2026-07-12
 
 ### Documentation
@@ -25,8 +129,8 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
-- **ORM: Eloquent-parity features.** The active-record `Model` grows most of the
-  Eloquent surface people reach for, all backward-compatible and still on the
+- **ORM: the features people reach for.** The active-record `Model` grows the
+  surface a real ORM needs, all backward-compatible and still on the
   driver-agnostic query builder (no JOINs, edge-safe):
 
   - **Lifecycle events & observers** — `creating`/`created`, `updating`/
@@ -91,8 +195,8 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
-- **Billing** — a new `@shaferllc/keel/billing` package: a Cashier-style
-  subscription layer with **one gateway-neutral API over Stripe and Paddle**
+- **Billing** — a new `@shaferllc/keel/billing` package: a subscription
+  layer with **one gateway-neutral API over Stripe and Paddle**
   (switching gateways is a config change). `class User extends Billable(Model)`
   gives a gateway customer, subscriptions (create/swap/quantity/trials/cancel/
   resume + status checks), single charges + refunds, invoices, hosted checkout,
@@ -286,7 +390,7 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
-- **Removed the Remult references** from the API-resources guide and source
+- **Removed comparisons to other frameworks** from the API-resources guide and source
   comments. Keel isn't that, and the docs shouldn't read as a comparison to another
   framework. The surrounding sentences are rewritten so they still say what the
   feature does rather than leaving a hole. No behavior change.
@@ -960,7 +1064,7 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   connection. They honor `X-Forwarded-Proto` / `X-Forwarded-Host` over the raw
   URL, so an app behind a TLS-terminating proxy or load balancer sees the
   client's real scheme and host — use `origin` to build absolute links and
-  `secure` to gate insecure requests. (Koa-inspired.)
+  `secure` to gate insecure requests.
 - **`response.back(fallback?)` and `redirect("back")`.** Redirect to the
   request's `Referer`, falling back to `fallback` (default `"/"`) when it's
   absent — the "return where you came from" shortcut for post-form flows.
@@ -1189,7 +1293,7 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Route config / metadata.** Attach arbitrary data to a route or group with
   `.config({ … })` and read it in the handler or route middleware via
   `request.route.config` — per-route flags like an auth scope, rate tier, or
-  layout choice (Fastify's route `config`). Group config merges into every route,
+  layout choice. Group config merges into every route,
   with a route's own keys winning. The matched-route context is now set *before*
   a route's middleware, so route/group middleware can branch on `request.route`.
   See [docs/routing.md](./docs/routing.md#route-config).
@@ -1236,7 +1340,7 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Response header helpers.** The `response` accessor gains `headers({...})` (set
   several at once), `getHeader(name)`, and `hasHeader(name)` — so middleware can
   inspect and conditionally set what a handler already put on the response (e.g.
-  a default `cache-control`). Brings `response` to parity with Fastify's Reply.
+  a default `cache-control`).
   See [docs/request-response.md](./docs/request-response.md).
 - **Design principles** documented in
   [docs/architecture.md](./docs/architecture.md#design-principles) — edge-safe /
@@ -1253,9 +1357,9 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   options at registration: `app.register(RateLimitProvider, { max: 100 })`, typed
   via `ServiceProvider<{ max: number }>` and read as `this.options`. The same
   provider class can register more than once with different options, so a provider
-  is now genuinely reusable (Fastify's `register(plugin, options)`). Backward
-  compatible — options default to `{}`. (Keel providers stay un-encapsulated by
-  design; per-request scoping is [middleware](./docs/middleware.md).) See
+  is now genuinely reusable. Backward compatible — options default to `{}`.
+  (Keel providers stay un-encapsulated by design; per-request scoping is
+  [middleware](./docs/middleware.md).) See
   [docs/providers.md](./docs/providers.md#providers-are-keels-plugin-system).
 
 [0.50.0]: https://github.com/shaferllc/keel/releases/tag/v0.50.0
@@ -1350,8 +1454,8 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   a bad request with a `422` `ValidationException` (errors from every part
   aggregated, keyed `body.field` / `query.field` / `params.field`) so the handler
   only ever sees valid input. `validated(part)` returns the parsed, typed value.
-  The declarative counterpart to Fastify's route schemas, built on the same
-  schema-agnostic `validate()` engine (bring your own Zod-style schema). See
+  Built on the same schema-agnostic `validate()` engine (bring your own
+  Zod-style schema). See
   [docs/validation.md](./docs/validation.md#declarative-validation-before-the-handler).
 
 [0.44.0]: https://github.com/shaferllc/keel/releases/tag/v0.44.0
@@ -1362,7 +1466,7 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - **Per-request logging.** `requestLogger()` middleware binds a child logger with
   a generated `reqId` to each request, so every log line within a request
-  correlates (Fastify's `request.log`). It logs request start/completion
+  correlates. It logs request start/completion
   (method, path, status, ms) by default; options for `genReqId`, reusing an
   incoming `idHeader` (distributed tracing), and disabling the auto lines.
   `requestLog()` reaches the current request's logger anywhere (falls back to the
@@ -1400,8 +1504,8 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   through the default path (with `code` in the JSON body) and passes
   `instanceof HttpException`. The built-in exceptions now carry stable codes too
   (`E_NOT_FOUND`, `E_UNAUTHORIZED`, `E_FORBIDDEN`, `E_VALIDATION`), so `code`
-  surfaces without any work. Inspired by Fastify's `@fastify/error`. Also
-  documented: serving over **HTTP/2** needs no framework code — it's a transport
+  surfaces without any work. Also documented: serving over **HTTP/2** needs no
+  framework code — it's a transport
   concern handled by the edge platform, a reverse proxy, or a `@hono/node-server`
   `node:http2` option. See [docs/errors.md](./docs/errors.md#coded-errors-with-createerror)
   and [docs/hono.md](./docs/hono.md#serving-over-http2).
@@ -1435,8 +1539,8 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Raw request-body accessors.** `request.text()`, `request.arrayBuffer()`, and
   `request.blob()` read the body for content types `json()` / `all()` don't
   handle — XML, CSV, protobuf, msgpack, or any custom format — which you then
-  parse yourself. Keel keeps body parsing explicit (no Fastify-style content-type
-  parser registry): you call the accessor you want. See
+  parse yourself. Keel keeps body parsing explicit (no content-type parser
+  registry): you call the accessor you want. See
   [docs/request-response.md](./docs/request-response.md#other-content-types).
 
 [0.40.1]: https://github.com/shaferllc/keel/releases/tag/v0.40.1
@@ -1450,9 +1554,8 @@ adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   life of the request. `decorateRequest(name, resolver)` registers a resolver
   (sync or async), `decorated(name)` reads it (computed once, then cached),
   `setRequestValue(name, value)` sets it imperatively (e.g. from middleware), and
-  `hasRequestDecorator(name)` checks. Inspired by Fastify's `decorateRequest`,
-  but without the null-placeholder/`onRequest`-hook dance — the per-request memo
-  is keyed off the context via a WeakMap, so nothing leaks between requests.
+  `hasRequestDecorator(name)` checks. The per-request memo is keyed off the
+  context via a WeakMap, so nothing leaks between requests.
   (Decorating the *app* is already the container's job.) See
   [docs/decorators.md](./docs/decorators.md).
 

package/docs/cors.md

@@ -21,6 +21,34 @@ router.group(() => { /* … */ }).use(cors({ origin: ["https://app.example.com"]
 With no options, `cors()` reflects the caller's origin — convenient in
 development. **Lock it down in production** with an explicit allowlist.
 
+## A production API group
+
+Typical setup for a JSON API served from `api.example.com` and called from a
+SPA on `app.example.com`:
+
+```ts
+// app/Http/Kernel.ts
+import { cors } from "@shaferllc/keel/core";
+
+this.use(
+  cors({
+    origin: ["https://app.example.com"],
+    credentials: true,          // cookies / Authorization
+    exposeHeaders: ["X-Request-Id"],
+  }),
+);
+```
+
+During local development, allow any localhost port with a predicate:
+
+```ts
+cors({
+  origin: (origin) =>
+    origin.startsWith("http://localhost:") || origin === "https://app.example.com",
+  credentials: true,
+});
+```
+
 ## Options
 
 ```ts

package/docs/decorators.md

@@ -2,10 +2,9 @@
 
 Attach named, computed values to the current request — `request.user`,
 `request.tenant`, `request.locale` — resolved **lazily** and **memoized for the
-life of the request**. Inspired by [Fastify's decorators](https://fastify.dev/docs/latest/Reference/Decorators/),
-but without the footguns: you register a resolver once, and Keel computes it on
+life of the request**. You register a resolver once, and Keel computes it on
 first access and caches it per request. No null-placeholder declaration, no
-`onRequest` hook to remember, no shared-state leak between requests.
+shared-state leak between requests.
 
 > Decorating the **application** is already the [service container's](./container.md)
 > job — `bind` / `singleton` / `instance` / `make`, with `bound()` as
@@ -53,9 +52,6 @@ setRequestValue("user", theAuthenticatedUser);
 const user = await decorated("user"); // returns the value set above, no re-lookup
 ```
 
-This is the clean version of Fastify's "declare a placeholder, set it in an
-`onRequest` hook" pattern.
-
 ## Why lazy + memoized
 
 Resolving the current user (or tenant, or locale, or a feature-flag set) is the

package/docs/errors.md

@@ -185,7 +185,7 @@ subclasses don't define either — they render through the default path.
 
 When all you want is a coded error class — a stable `code`, a message, a status —
 skip the boilerplate and mint one with `createError`. It's the ergonomic shortcut
-for the common case, inspired by Fastify's `@fastify/error`:
+for the common case:
 
 ```ts
 import { createError } from "@shaferllc/keel/core";

package/docs/examples/billing.ts

@@ -0,0 +1,128 @@
+// Type-check harness for docs/billing.md. Compile-only — never executed.
+import { Model, listen } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingServiceProvider,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+  resolveBillableUsing,
+  type CheckoutSession,
+  type GatewayCharge,
+} from "@shaferllc/keel/billing";
+
+export class User extends Billable(Model) {
+  static override table = "users";
+  declare id: number;
+  declare email: string;
+  declare name: string;
+}
+
+declare const user: User;
+declare const paymentMethodId: string;
+declare const successUrl: string;
+declare const cancelUrl: string;
+
+export const providers = [BillingServiceProvider];
+
+/* -------------------------------- customers ------------------------------- */
+
+export async function customers() {
+  await user.createAsCustomer();
+  user.hasBillingId();
+  await user.getCustomerId();
+}
+
+/* ------------------------------ subscriptions ----------------------------- */
+
+export async function subscribe() {
+  await user
+    .newSubscription("default", "price_pro")
+    .trialDays(14)
+    .quantity(3)
+    .create(paymentMethodId);
+
+  const session: CheckoutSession = await user
+    .newSubscription("default", "price_pro")
+    .checkout({ successUrl, cancelUrl });
+  return session;
+}
+
+export async function status() {
+  await user.subscribed();
+  await user.subscribedToPrice("price_pro");
+  await user.onTrial();
+  const sub = await user.subscription();
+  if (!sub) return;
+
+  sub.active();
+  sub.onTrial();
+  sub.recurring();
+  sub.canceled();
+  sub.onGracePeriod();
+  sub.ended();
+  sub.paused();
+  sub.valid();
+  sub.hasIncompletePayment();
+
+  await sub.swap("price_enterprise");
+  await sub.updateQuantity(10);
+  await sub.incrementQuantity(2);
+  await sub.decrementQuantity();
+  await sub.cancel();
+  await sub.resume();
+  await sub.cancelNow();
+  await sub.endTrial();
+  await sub.extendTrial(new Date("2026-01-01"));
+}
+
+/* -------------------------------- charges --------------------------------- */
+
+export async function charges() {
+  const charge: GatewayCharge = await user.charge(2000, {
+    paymentMethod: "pm_1",
+    description: "Credits",
+  });
+  await user.refund(charge.id);
+  await user.refund(charge.id, 500);
+  await user.checkout("price_onetime", { successUrl, cancelUrl });
+  await user.createSetupIntent();
+  await user.paymentMethods();
+  await user.invoices();
+}
+
+/* -------------------------------- webhooks -------------------------------- */
+
+export function webhooks() {
+  listen("billing.subscription.updated", (e) => {
+    void e.gateway;
+    void e.subscriptionId;
+  });
+  listen("billing.webhook.received", (e) => {
+    void e.gateway;
+    void e.type;
+  });
+  resolveBillableUsing(async (customerId, _gateway) => {
+    return { id: user.id, type: "User" };
+  });
+}
+
+/* --------------------------------- testing -------------------------------- */
+
+export function fakeGateway() {
+  const fake = new FakeGateway();
+  const manager = new BillingManager({
+    default: "fake",
+    currency: "usd",
+    billableModel: "User",
+    webhook: { path: "billing/webhook" },
+    gateways: {
+      stripe: { key: "", webhookSecret: "" },
+      paddle: { key: "", webhookSecret: "" },
+      fake: {},
+    },
+  });
+  manager.register("fake", () => fake);
+  setBilling(manager);
+  return fake;
+}

package/docs/examples/cors.ts

@@ -0,0 +1,29 @@
+// Type-check harness for docs/cors.md. Compile-only — never executed.
+import type { MiddlewareHandler } from "hono";
+import { cors, type CorsOptions } from "@shaferllc/keel/core";
+
+export function kernel(): MiddlewareHandler {
+  return cors();
+}
+
+export function apiGroup(): MiddlewareHandler {
+  return cors({ origin: ["https://app.example.com"] });
+}
+
+export function production(): MiddlewareHandler {
+  const options: CorsOptions = {
+    origin: ["https://app.example.com"],
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+    headers: true,
+    exposeHeaders: ["X-Request-Id"],
+    credentials: true,
+    maxAge: 86400,
+  };
+  return cors(options);
+}
+
+export function dynamicOrigin(): MiddlewareHandler {
+  return cors({
+    origin: (origin) => origin.endsWith(".example.com") || origin.startsWith("http://localhost"),
+  });
+}

package/docs/examples/hono.ts

@@ -0,0 +1,29 @@
+// Type-check harness for docs/hono.md. Compile-only — never executed.
+import type { Ctx } from "@shaferllc/keel/core";
+import { Router, json } from "@shaferllc/keel/core";
+
+export function withContext(router: Router) {
+  router.get("/users/:id", async (c: Ctx) => {
+    const id = c.req.param("id");
+    const q = c.req.query("q");
+    const auth = c.req.header("authorization");
+    void q;
+    void auth;
+    return c.json({ id });
+  });
+
+  router.get("/ping", (c) => c.text("pong"));
+  router.get("/go", (c) => c.redirect("/"));
+}
+
+export function ambientHelpers() {
+  return json({ ok: true });
+}
+
+export function keelContext(c: Ctx) {
+  return {
+    app: c.get("app"),
+    route: c.get("route"),
+    subdomains: c.get("subdomains"),
+  };
+}

package/docs/examples/openapi.ts

@@ -0,0 +1,35 @@
+// Type-check harness for docs/openapi.md. Compile-only — never executed.
+import { z } from "zod";
+import { Application, Router, validateRequest, type Ctx } from "@shaferllc/keel/core";
+import { OpenApiServiceProvider, apiDoc, OpenApi } from "@shaferllc/keel/openapi";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+const UserShape = z.object({ id: z.number(), email: z.string().email() });
+
+class Users {
+  store(_c: Ctx) {
+    return { id: 1, email: "a@b.com" };
+  }
+}
+
+export function install() {
+  const app = new Application();
+  app.register(OpenApiServiceProvider);
+  OpenApi.auth((c) => c.req.header("x-docs-key") === "secret");
+  return app;
+}
+
+export function document(router: Router) {
+  router
+    .post("/users", [Users, "store"])
+    .name("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 })]);
+}

package/docs/examples/orm.ts

@@ -0,0 +1,30 @@
+// Type-check harness for docs/orm.md. Compile-only — never executed.
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static override table = "posts";
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+}
+
+export class User extends Model {
+  static override table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() {
+    return this.hasMany(Post);
+  }
+}
+
+export async function map() {
+  const user = await User.find(1);
+  if (!user) return;
+  await user.posts();
+  await User.with("posts").where("email", user.email).first();
+  await User.create({ email: "ada@example.com" });
+  user.email = "grace@example.com";
+  await user.save();
+  await user.delete();
+}

package/docs/examples/packages.ts

@@ -0,0 +1,26 @@
+// Type-check harness for docs/packages.md. Compile-only — never executed.
+import { PackageProvider, type Router, type Migration, type PackageCommand } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+declare const createInvoicesTable: Migration;
+declare const syncInvoicesCommand: PackageCommand;
+declare function registerBillingRoutes(r: Router): void;
+
+export class BillingServiceProvider extends PackageProvider {
+  readonly name = "billing";
+
+  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" });
+  }
+}