@shaferllc/keel 0.79.0 → 0.81.0

package/docs/billing.md

@@ -0,0 +1,242 @@
+# 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
+```

package/docs/database.md

@@ -145,6 +145,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
@@ -174,6 +191,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.

package/docs/examples/accounts.ts

@@ -0,0 +1,150 @@
+// Typechecked example for docs/accounts.md.
+import { Application } from "@shaferllc/keel/core";
+import {
+  AccountsServiceProvider,
+  attempt,
+  completeTwoFactor,
+  confirmTwoFactor,
+  disableTwoFactor,
+  enableTwoFactor,
+  hasTwoFactor,
+  regenerateRecoveryCodes,
+  requestPasswordReset,
+  resetPassword,
+  sendVerificationEmail,
+  verifyEmail,
+  accountStore,
+  setAccountStore,
+  type AccountUser,
+} from "@shaferllc/keel/accounts";
+
+const app = new Application();
+
+/* ------------------------------- turning it on ---------------------------- */
+
+app.register(AccountsServiceProvider);
+
+/* ---------------------------------- login --------------------------------- */
+
+async function login(email: string, password: string) {
+  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 };
+  }
+
+  return { user: result.user };
+}
+
+async function finishTwoFactor(challenge: string, code: string) {
+  // Takes an authenticator code or a recovery code.
+  const user = await completeTwoFactor(challenge, code);
+  if (!user) return { error: "That code isn't valid." };
+
+  return { user };
+}
+
+/* ------------------------------ password reset ---------------------------- */
+
+async function forgot(email: string) {
+  await requestPasswordReset(email);
+  // Always the same answer, whether or not that address has an account.
+  return { status: "If that address has an account, a link is on its way." };
+}
+
+async function reset(token: string, password: string) {
+  const ok = await resetPassword(token, password);
+  return ok ? { status: "Password reset." } : { error: "That link is invalid or expired." };
+}
+
+/* --------------------------- email verification --------------------------- */
+
+async function afterRegistration(user: AccountUser) {
+  await sendVerificationEmail(user);
+}
+
+async function confirmEmail(token: string) {
+  const user = await verifyEmail(token);
+  return user ? { status: "Confirmed." } : { error: "That link is invalid or expired." };
+}
+
+/* -------------------------------- two factor ------------------------------ */
+
+async function startTwoFactor(user: AccountUser) {
+  // Step one: a secret and recovery codes — but 2FA is NOT on yet.
+  const setup = await enableTwoFactor(user, { issuer: "Acme" });
+
+  // Render setup.uri to a QR code locally. It contains the secret; never send it
+  // to a third-party QR service.
+  return {
+    uri: setup.uri,
+    secret: setup.secret,
+    recoveryCodes: setup.recoveryCodes, // shown once
+  };
+}
+
+async function finishSetup(user: AccountUser, code: string) {
+  // Step two: a working code turns it on. Without this, a bad scan locks them out.
+  const ok = await confirmTwoFactor(user, code);
+  return ok ? { status: "Two-factor is on." } : { error: "That code isn't valid." };
+}
+
+async function accountSettings(user: AccountUser) {
+  return {
+    twoFactorEnabled: hasTwoFactor(user),
+  };
+}
+
+async function newCodes(user: AccountUser) {
+  return regenerateRecoveryCodes(user); // invalidates the old set
+}
+
+async function turnOff(user: AccountUser) {
+  await disableTwoFactor(user);
+}
+
+/* ------------------------------ a custom store ---------------------------- */
+
+// Users somewhere other than a `users` table? Replace the whole store. (Anything
+// that can find a user and update one will do — here, a map.)
+const people = new Map<string | number, AccountUser>();
+
+setAccountStore({
+  async findById(id) {
+    return people.get(id) ?? null;
+  },
+  async findByEmail(email) {
+    for (const person of people.values()) {
+      if (person.email === email.toLowerCase()) return person;
+    }
+    return null;
+  },
+  async update(id, values) {
+    const person = people.get(id);
+    if (person) people.set(id, { ...person, ...values });
+  },
+});
+
+// The store the rest of the module reads through.
+const store = accountStore();
+
+export {
+  login,
+  finishTwoFactor,
+  forgot,
+  reset,
+  afterRegistration,
+  confirmEmail,
+  startTwoFactor,
+  finishSetup,
+  accountSettings,
+  newCodes,
+  turnOff,
+  app,
+  store,
+};

package/docs/migrations.md

@@ -73,12 +73,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

package/docs/models.md

@@ -173,6 +173,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` /
@@ -222,6 +301,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
@@ -242,11 +344,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.
 
 ---

package/docs/packages.md

@@ -7,7 +7,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