@shaferllc/keel 0.79.0 → 0.81.0

package/llms-full.txt

@@ -4437,6 +4437,227 @@ router.get("/reports", handler).use(guards);
 
 
 
+---
+
+<!-- source: docs/accounts.md -->
+
+# Accounts
+
+Password reset, email verification, and two-factor authentication — the flows every
+app with a login needs, built on primitives already in core (`hash`, `encryption`,
+`mail`, `rate-limit`).
+
+They live in the framework, tested once, rather than being copy-pasted into each new
+app. A password-reset flow written five times is four copies that quietly rot.
+
+```bash
+npm install @shaferllc/keel
+```
+
+```ts
+// bootstrap/providers.ts
+import { AccountsServiceProvider } from "@shaferllc/keel/accounts";
+
+app.register(AccountsServiceProvider);
+```
+
+That merges config, adds four columns to your `users` table via a migration, and
+mounts the JSON endpoints. **Views stay yours** — these are functions and JSON
+endpoints; your controllers render the forms.
+
+## Login
+
+`attempt()` checks a password. What comes back depends on whether the user has 2FA.
+
+```ts
+const result = await attempt(email, password);
+
+if (result.status === "failed") {
+  return { error: "Those credentials don't match." };
+}
+
+if (result.status === "two-factor") {
+  // Nothing is logged in yet. Hold the challenge, ask for a code.
+  return { twoFactor: true, challenge: result.challenge };
+}
+
+auth().login(result.user.id);
+```
+
+A wrong email and a wrong password give the same answer, and take the same time —
+`attempt()` hashes against `hash.dummy` when no user is found, because a fast "no
+such user" tells an attacker which addresses are registered.
+
+## Two-factor
+
+### The challenge is not a session
+
+When 2FA is on, a correct password yields a **challenge**, not a login. Nothing is
+authenticated until the code verifies.
+
+This matters more than it looks. The usual implementation logs the user in and sets a
+`needs_2fa` flag for middleware to check — which means they are holding a real
+authenticated session *before* the second factor. Every route that forgets the
+middleware, and every `auth()` call that only asks "is anyone logged in?", is then
+bypassable with just a password. The second factor becomes advisory.
+
+Here there is no half-authenticated state to forget about, because there is no
+session. The challenge is a short-lived token bound to a single purpose, so it cannot
+be swapped for a session cookie or spent as a password-reset link.
+
+```ts
+const user = await completeTwoFactor(challenge, code);
+if (!user) return { error: "That code isn't valid." };
+
+auth().login(user.id);
+```
+
+`completeTwoFactor()` accepts an authenticator code **or** a recovery code.
+
+### Turning it on takes two steps
+
+```ts
+// Step one: a secret and recovery codes. 2FA is NOT on yet.
+const setup = await enableTwoFactor(user, { issuer: "Acme" });
+```
+
+`setup.uri` is an `otpauth://` URI to render as a QR code. `setup.secret` is for
+manual entry. `setup.recoveryCodes` are shown **once**.
+
+> Render the QR **locally**. The URI contains the shared secret, so posting it to a
+> QR-image service hands your users' second factor to a third party.
+
+```ts
+// Step two: a working code turns it on.
+const ok = await confirmTwoFactor(user, code);
+```
+
+The two-step dance is deliberate. A one-step "enable" locks out every user who scans
+the QR wrong or whose phone clock is off — and what's broken is the very thing they'd
+need to get back in. Until `confirmTwoFactor()` succeeds, `hasTwoFactor()` is false
+and login works as before.
+
+### Recovery codes
+
+Eight by default, hashed at rest, single-use — redeeming one burns it, so a code read
+over your shoulder is one you have already spent.
+
+```ts
+await recoveryCodesRemaining(user);       // worth surfacing when it gets low
+await regenerateRecoveryCodes(user);      // invalidates the old set
+await disableTwoFactor(user);             // destroys the secret and the codes
+```
+
+### What's stored
+
+The TOTP secret is **encrypted** at rest and the recovery codes are **hashed**, so a
+leaked database hands over neither the second factor nor the backdoor.
+
+TOTP itself is RFC 6238, verified against the RFC's published test vectors, and built
+on WebCrypto with no dependencies — so it runs unchanged on the edge.
+
+## Password reset
+
+```ts
+await requestPasswordReset(email);   // emails a link, or quietly does nothing
+```
+
+The answer is the same whether or not that address has an account. "No account with
+that address" is a free enumeration oracle on an unauthenticated endpoint that anyone
+can ask about anyone.
+
+```ts
+const ok = await resetPassword(token, password);
+```
+
+**A reset link works exactly once**, and there is no `password_resets` table. The
+token carries its own purpose and expiry inside the ciphertext, and it is bound to a
+fingerprint of the current password hash — so the moment the password changes, every
+token minted against the old one is dead. Nothing to store, nothing to clean up, and
+no window where a stale row is still redeemable because a cron job didn't run.
+
+## Email verification
+
+```ts
+await sendVerificationEmail(user);
+const user = await verifyEmail(token);   // idempotent
+```
+
+The token is bound to the address it was sent to. A link mailed to an old address
+cannot verify a new one — otherwise changing your email to someone else's and clicking
+an older link would mark *their* address as proven.
+
+## The endpoints
+
+Mounted at `auth` unless you turn them off (`routes.enabled: false`) and call the
+functions from your own controllers instead.
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| POST | `/auth/login` | `{ email, password }` → a user, or `{ twoFactor, challenge }` |
+| POST | `/auth/two-factor` | `{ challenge, code }` — code or recovery code |
+| POST | `/auth/password/forgot` | Always `202`. Never says who exists. |
+| POST | `/auth/password/reset` | `{ token, password }` |
+| POST | `/auth/email/verify` | `{ token }` |
+| POST | `/auth/email/resend` | Always `202` |
+
+Every one is unauthenticated and touches credentials, so the group is rate-limited
+(5 per minute by default). Without a throttle, a six-digit code inside a 30-second
+window is guessable, and forgot-password is an email cannon pointed at whoever the
+caller names.
+
+## Configuration
+
+```bash
+keel vendor:publish --tag accounts-config
+```
+
+```ts
+export default {
+  userTable: "users",
+  routes: { enabled: true, prefix: "auth" },
+  passwordReset: { expiresIn: "60m", url: "/reset-password?token=:token" },
+  verification: { expiresIn: "24h", url: "/verify-email?token=:token" },
+  twoFactor: {
+    issuer: env("APP_NAME", "Keel"),
+    window: 1,               // ±30s of clock drift
+    challengeExpiresIn: "5m",
+    recoveryCodes: 8,
+  },
+  rateLimit: { max: 5, window: 60 },
+};
+```
+
+`twoFactor.challengeExpiresIn` is the window in which a stolen password alone is
+enough. Keep it short.
+
+## A different users table
+
+Accounts talks to a table through the query builder rather than assuming a `Model`.
+If your users live somewhere else — an auth service, a legacy schema — replace the
+store:
+
+```ts
+setAccountStore({
+  async findById(id) { /* … */ },
+  async findByEmail(email) { /* … */ },
+  async update(id, values) { /* … */ },
+});
+```
+
+## The schema
+
+Four columns on your users table, and no tokens table:
+
+| Column | |
+| --- | --- |
+| `email_verified_at` | null until proven |
+| `two_factor_secret` | encrypted at rest |
+| `two_factor_recovery_codes` | hashed, then encrypted |
+| `two_factor_confirmed_at` | null until a working code proves it |
+
+
+
 ---
 
 <!-- source: docs/ai.md -->
@@ -5332,6 +5553,255 @@ all gates/policies/hooks (a test helper).
 
 
 
+---
+
+<!-- source: docs/billing.md -->
+
+# Billing
+
+Keel Billing is a subscription-billing layer — a port of [Laravel
+Cashier](https://laravel.com/docs/13.x/billing) — for charging customers,
+managing subscriptions, and reconciling gateway state through webhooks. It ships
+as a Keel [package](./packages.md) and supports two gateways behind one API:
+**Stripe** and **Paddle**.
+
+It attaches to a model with a mixin. Your `User` becomes billable, gains a
+gateway customer, and can create subscriptions and charges:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+import { Billable } from "@shaferllc/keel/billing";
+
+export class User extends Billable(Model) {
+  static table = "users";
+  declare email: string;
+}
+```
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { BillingServiceProvider } from "@shaferllc/keel/billing";
+
+export const providers = [AppServiceProvider, BillingServiceProvider];
+```
+
+Publish the config and create the tables:
+
+```bash
+keel vendor:publish --tag billing-config   # writes config/billing.ts
+keel migrate                               # creates subscriptions + subscription_items,
+                                           # and adds billing columns to users
+```
+
+Set your keys in `.env`:
+
+```ini
+BILLING_GATEWAY=stripe            # or "paddle"
+STRIPE_SECRET_KEY=sk_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+# Paddle:
+PADDLE_API_KEY=...
+PADDLE_WEBHOOK_SECRET=...
+PADDLE_CLIENT_TOKEN=...
+PADDLE_SANDBOX=true
+```
+
+## One API, two gateways
+
+Everything you call goes through a gateway-neutral interface, so switching from
+Stripe to Paddle is a config change. The active gateway comes from
+`config("billing.default")`; a billable can also carry its own in
+`billing_gateway`. Money is always an integer in the smallest currency unit
+(cents). See [Gateway differences](#gateway-differences) for where Paddle's
+merchant-of-record model diverges.
+
+## Customers
+
+A gateway customer is created lazily the first time you need one, but you can
+create it up front:
+
+```ts
+await user.createAsCustomer();     // creates the customer, stores its id
+user.hasBillingId();               // true
+await user.getCustomerId();        // the id (creates if missing)
+```
+
+Override what gets synced by defining `billingName()` / `billingEmail()` on your
+model. By default they read `name` / `email`.
+
+## Subscriptions
+
+Build a subscription with the fluent builder:
+
+```ts
+await user
+  .newSubscription("default", "price_pro")
+  .trialDays(14)
+  .quantity(3)
+  .create(paymentMethodId);        // paymentMethodId optional if a default is on file
+```
+
+Multiple prices (add-ons) are an array; `withMetadata`, `trialUntil`, and
+`skipTrial` are also available. To send the customer to a hosted checkout
+instead of charging now, swap `.create()` for `.checkout()`:
+
+```ts
+const session = await user
+  .newSubscription("default", "price_pro")
+  .checkout({ successUrl: "...", cancelUrl: "..." });
+// Stripe: redirect to session.url. Paddle: open the overlay with session.clientToken.
+```
+
+### Status
+
+Status questions are answered from local columns — no gateway round-trip:
+
+```ts
+await user.subscribed();                 // valid (active | trial | grace)
+await user.subscribedToPrice("price_pro");
+await user.onTrial();
+const sub = await user.subscription();    // the "default" subscription, or null
+
+sub.active();        sub.onTrial();       sub.recurring();
+sub.canceled();      sub.onGracePeriod(); sub.ended();
+sub.paused();        sub.valid();         sub.hasIncompletePayment();
+```
+
+### Changing a subscription
+
+```ts
+await sub.swap("price_enterprise");       // change price(s)
+await sub.updateQuantity(10);
+await sub.incrementQuantity(2);
+await sub.decrementQuantity();
+```
+
+Each of these calls the gateway and syncs the result back into the local row.
+
+### Cancelling
+
+```ts
+await sub.cancel();       // at period end — access continues through the grace period
+await sub.onGracePeriod();// true
+await sub.resume();       // revive a subscription still in its grace period
+await sub.cancelNow();    // immediately; sub.ended() becomes true
+```
+
+### Trials
+
+```ts
+await sub.endTrial();
+await sub.extendTrial(new Date("2026-01-01"));
+user.onGenericTrial();    // a trial_ends_at on the user, before any subscription
+```
+
+## Single charges
+
+```ts
+const charge = await user.charge(2000, { paymentMethod: "pm_1", description: "Credits" });
+await user.refund(charge.id);          // full refund
+await user.refund(charge.id, 500);     // partial
+
+const session = await user.checkout("price_onetime", { successUrl, cancelUrl });
+```
+
+## Payment methods (Stripe)
+
+Collect a card with a SetupIntent, then create the subscription with the
+resulting payment method:
+
+```ts
+const intent = await user.createSetupIntent();  // return intent.clientSecret to the front end
+const methods = await user.paymentMethods();
+```
+
+These are Stripe-only capabilities; calling them on the Paddle gateway throws a
+`BillingError` (Paddle collects cards in its own hosted checkout).
+
+## Invoices
+
+```ts
+const invoices = await user.invoices();   // GatewayInvoice[] — total, currency, status, url
+```
+
+## Webhooks
+
+The package mounts one webhook endpoint per gateway at
+`config("billing.webhook.path")`:
+
+```
+POST /billing/webhook/stripe
+POST /billing/webhook/paddle
+```
+
+Point your gateway dashboard at the matching URL. Each request is verified
+against the gateway's signing secret (HMAC-SHA256 over the raw body), the local
+subscription is synced, and typed events fire:
+
+```ts
+import { listen } from "@shaferllc/keel/core";
+
+listen("billing.subscription.updated", (e) => {
+  // e.gateway, e.subscriptionId, e.providerId, e.status
+});
+listen("billing.webhook.received", (e) => { /* e.gateway, e.type, e.id */ });
+```
+
+Events: `billing.webhook.received`, `billing.subscription.created` / `.updated`
+/ `.deleted`.
+
+An update to a subscription already in your database is always synced. A brand
+new subscription born from a Paddle checkout has no local row yet — register a
+resolver so the handler can create it:
+
+```ts
+import { resolveBillableUsing } from "@shaferllc/keel/billing";
+
+resolveBillableUsing(async (customerId) => {
+  const user = (await User.query().where("billing_customer_id", customerId).first());
+  return user ? { id: user.id, type: "User" } : null;
+});
+```
+
+## Gateway differences
+
+| Concern | Stripe | Paddle |
+|---------|--------|--------|
+| Create a subscription server-side | `create(pmId)` | Not supported — use `checkout()`; the webhook creates the local row |
+| One-off `charge()` | Confirms a PaymentIntent | Not supported — use `checkout({ mode })` / transactions |
+| SetupIntent / `paymentMethods()` | Supported | Throws `BillingError` (hosted checkout) |
+| Checkout handle | `session.url` (redirect) | `session.clientToken` (overlay/inline) |
+| Webhook signature | `Stripe-Signature: t=…,v1=…` | `Paddle-Signature: ts=…;h1=…` |
+
+## Schema
+
+The migration is gateway-neutral: `subscriptions` (with `gateway`,
+`provider_id`, `provider_status`, `provider_price`, trial/grace timestamps),
+`subscription_items`, and columns on `users` (`billing_gateway`,
+`billing_customer_id`, `pm_type`, `pm_last_four`, `trial_ends_at`). Cashier
+targets the standard `users` billable table.
+
+## Testing
+
+The package ships a `FakeGateway` — an in-memory gateway that records every call
+— so you can drive billing without touching a network:
+
+```ts
+import { BillingManager, setBilling, FakeGateway } from "@shaferllc/keel/billing";
+
+const fake = new FakeGateway();
+const manager = new BillingManager(config);   // config.default = "fake"
+manager.register("fake", () => fake);
+setBilling(manager);
+
+await user.newSubscription("default", "price_pro").create();
+fake.calls.filter((c) => c.method === "createSubscription"); // assert what was asked
+```
+
+
+
 ---
 
 <!-- source: docs/broadcasting.md -->
@@ -7324,6 +7794,23 @@ await db("posts").latest().get();          // ORDER BY created_at DESC
 await db("posts").oldest("published_at").get();
 ```
 
+Joins, grouping, and conditional/raw clauses:
+
+```ts
+await db("posts")
+  .join("users", "posts.user_id", "users.id")   // also leftJoin(...)
+  .select("posts.title", "users.name")
+  .get();
+
+await db("posts").select("user_id").groupBy("user_id").having("COUNT(*)", ">", 5).get();
+await db("users").distinct().select("country").pluck("country");
+
+await db("events").whereColumn("updated_at", ">", "created_at").get();
+await db("users").whereRaw("score >= ?", [10]).orderByRaw("LENGTH(name) DESC").get();
+
+await db("users").when(search, (q, term) => q.whereLike("name", `%${term}%`)).get();
+```
+
 ## Aggregates, single values, and pagination
 
 ```ts
@@ -7353,6 +7840,22 @@ Everything is parameterized — values become bindings, never string-interpolate
 SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
 `insertGetId` unwraps it to just the new id.
 
+Counters, bulk upserts, and paged iteration:
+
+```ts
+await db("posts").where("id", id).increment("views");        // += 1
+await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+
+// Insert, updating the listed columns on a unique-key conflict (dialect-aware).
+await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
+await db("logs").insertOrIgnore({ key, value });             // skip duplicates
+
+// Process a large table a page at a time (return false to stop early).
+await db("users").orderBy("id").chunk(500, async (rows) => {
+  for (const row of rows) await process(row);
+});
+```
+
 > **Guard your writes.** `update()` and `delete()` apply to every row that
 > matches the current `where` clause — with no `where`, that's the whole table.
 > Always scope a write with `where` unless you truly mean to touch every row.
@@ -12496,12 +12999,41 @@ t.boolean("active").default(true);     // sqlite: DEFAULT 1, else DEFAULT true
 t.integer("retries").default(0);       // ... DEFAULT 0
 ```
 
-For anything the builder doesn't cover — indexes, foreign keys, an `ALTER
-TABLE` — `schema.raw(sql, bindings?)` runs arbitrary SQL:
+### Indexes and foreign keys
+
+`createTable` builds indexes and foreign keys alongside the columns:
+
+```ts
+schema.createTable("members", (t) => {
+  t.id();
+  t.integer("team_id");
+  t.string("email");
+  t.uniqueIndex("email");                       // or t.index(["a", "b"]) for composite
+  t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+});
+```
+
+### Altering a table
+
+`schema.alterTable(name, build)` adds, renames, and drops columns and indexes on
+an existing table (dialect-aware SQL). Drop an index before the column it covers:
 
 ```ts
 up: (schema) =>
-  schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
+  schema.alterTable("users", (t) => {
+    t.string("phone").nullable();     // ADD COLUMN
+    t.renameColumn("name", "full_name");
+    t.index("phone");
+    t.dropIndex("users_legacy_index");
+    t.dropColumn("legacy");
+  }),
+```
+
+For anything the builder still doesn't cover, `schema.raw(sql, bindings?)` runs
+arbitrary SQL:
+
+```ts
+up: (schema) => schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
 ```
 
 > `raw()` writes through the connection **without** placeholder conversion, so
@@ -13079,6 +13611,85 @@ return json(user);       // works directly — json() serializes it
 user.fill({ name: "X" }); // merge mass-assignable attributes without saving
 ```
 
+Control what `toJSON()` exposes with three statics. `hidden` strips columns;
+`visible` is an allowlist that wins over everything; `appends` adds computed
+attributes — a getter or a zero-arg method on the model:
+
+```ts
+class User extends Model {
+  static table = "users";
+  static hidden = ["password"];       // never serialized
+  static appends = ["fullName"];      // added to the output
+  get fullName() { return `${this.first} ${this.last}`; }
+}
+```
+
+## Lifecycle events
+
+A model fires events as it is retrieved, saved, and deleted. Hook onto them to
+slug a title, bust a cache, or cascade — without touching every call site. The
+`*ing` events are **cancelable**: a hook returning `false` aborts the write.
+
+```ts
+User.creating((user) => { user.uuid = crypto.randomUUID(); });
+User.saved((user) => cache().forget(`user:${user.id}`));
+User.deleting((user) => (user.isRoot ? false : undefined)); // veto
+
+// Or group them in an observer:
+User.observe({
+  creating: (u) => { u.uuid = crypto.randomUUID(); },
+  deleted:  (u) => audit(`deleted ${u.id}`),
+});
+```
+
+Events: `retrieved`, `creating`/`created`, `updating`/`updated`,
+`saving`/`saved`, `deleting`/`deleted`, `restoring`/`restored`. They're keyed by
+the exact class (subclasses don't inherit a parent's hooks).
+
+## Query scopes
+
+A **global scope** constrains every query a model builds — the base for
+multi-tenancy, published-only reads, and soft deletes:
+
+```ts
+Post.addGlobalScope("published", (q) => q.where("published", true));
+await Post.all();        // only published
+await Post.query().where("author_id", 1).get();  // still only published
+```
+
+A **local scope** is just a static method returning a query — no framework
+feature needed:
+
+```ts
+class Post extends Model {
+  static popular() { return this.query().where("views", ">", 1000); }
+}
+await Post.popular().orderBy("views", "desc").get();
+```
+
+## Soft deletes
+
+Opt in with `static softDeletes = true` and a `deleted_at` column. `delete()`
+then sets the timestamp instead of removing the row, and a global scope hides
+soft-deleted rows from every query.
+
+```ts
+class User extends Model {
+  static table = "users";
+  static softDeletes = true;
+  static casts = { deleted_at: "date" };
+}
+
+await user.delete();          // sets deleted_at; row stays in the table
+user.trashed();               // true
+await User.find(user.id);     // null — hidden by the scope
+
+await User.withTrashed().get();   // include soft-deleted
+await User.onlyTrashed().get();   // only soft-deleted
+await user.restore();             // clear deleted_at
+await user.forceDelete();         // remove the row for good
+```
+
 ## Relationships
 
 Define a relationship as a method that returns one of `hasMany` / `hasOne` /
@@ -13128,6 +13739,29 @@ users[0].toJSON();             // includes `posts` and `roles`
 Loaded relations are stored off the model, so they never leak into `save()`,
 and `toJSON()` serializes them (nested models included).
 
+### Querying relationships (`with`, `withCount`, `whereHas`)
+
+`Model.query()` returns a model-aware builder with the relationship operations a
+raw query can't express. `with()` eager-loads (dotted paths nest), `withCount()`
+adds a `<relation>_count`, and `has`/`whereHas`/`doesntHave` filter by whether a
+related row exists:
+
+```ts
+const users = await User.query()
+  .where("active", true)
+  .with("posts.comments")                       // nested eager load
+  .withCount("posts")                            // users[i].posts_count
+  .whereHas("posts", (q) => q.where("published", true))
+  .get();
+
+await User.has("posts").get();        // users with at least one post
+await User.doesntHave("posts").get(); // users with none
+```
+
+`with`/`withCount`/`whereHas`/`has`/`doesntHave` are also static shortcuts
+(`User.with(...)`, `User.whereHas(...)`). Existence filters use the same
+driver-agnostic two-query strategy as the relations themselves — no JOIN.
+
 ### Many-to-many
 
 `belongsToMany` reads through a pivot table (default name: the two table names
@@ -13148,11 +13782,39 @@ this.belongsTo(User, "owner_id", "id");
 this.belongsToMany(Role, "user_roles", "user_id", "role_id");
 ```
 
+### Polymorphic
+
+A polymorphic relation lets one model belong to more than one type. The related
+rows carry `<name>_id` + `<name>_type`; register each owner type so `morphTo`
+can resolve it:
+
+```ts
+class Post extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Video extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Comment extends Model {
+  commentable() { return this.morphTo("commentable"); } // resolves back to Post or Video
+}
+
+registerMorphType("Post", Post);
+registerMorphType("Video", Video);
+
+await post.comments().create({ body: "nice" }); // sets commentable_id/_type
+const owner = await comment.commentable();       // Post | Video | null
+```
+
+`morphOne` is the one-to-one variant. Eager loading (`Model.load` / `with`) works
+across mixed types.
+
 ## What this is (and isn't)
 
-This is a deliberately small active-record — enough for CRUD, relationships,
-casts, and simple queries without an ORM dependency. Nested eager loading
-(`posts.comments`) and query-time `with()` aren't here yet. For complex schemas
+This is a compact active-record — CRUD, lifecycle events, scopes, soft deletes,
+serialization control, eager loading (including nested `with("posts.comments")`),
+relationship queries (`whereHas`/`withCount`), and polymorphic relations — all on
+a driver-agnostic query builder, no ORM dependency. For complex one-off queries
 you can always drop to `db()` or your driver directly.
 
 ---
@@ -14329,7 +14991,9 @@ 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.
+reference implementation of everything below. [Billing](./billing.md) (a Cashier
+port for Stripe and Paddle) is another, and shows a package contributing models,
+a schema migration, gateway drivers, and verified webhook routes.
 
 ## The shape of a package