@shaferllc/keel 0.78.2 → 0.80.0

package/dist/core/binding.js

@@ -0,0 +1,159 @@
+/**
+ * Route model binding — a `:user` in the path arrives as a `User`, not a string.
+ *
+ *   bindModel("user", User);
+ *
+ *   router.get("/users/:user", (c) => {
+ *     const user = boundModel(User);   // already fetched. Not a string, not null.
+ *     return c.json(user);
+ *   });
+ *
+ * The row is looked up **before the handler runs**, and a miss is a 404 there and
+ * then. That's the whole value: the handler never sees a null, so it never has to
+ * remember to check for one — and "forgot the 404" stops being a bug you can write.
+ *
+ * Bind by another column when the URL isn't the id:
+ *
+ *   bindModel("post", Post, { key: "slug" });     // /posts/hello-world
+ *
+ * Constrain what's reachable (row-level security — a row outside the scope 404s,
+ * so it can't be reached by guessing an id):
+ *
+ *   bindModel("post", Post, { scope: (q, c) => q.where("authorId", currentUserId(c)) });
+ *
+ * Or resolve it yourself, for anything that isn't a model:
+ *
+ *   bindRoute("tenant", (slug) => tenants.get(slug));
+ */
+import { NotFoundException } from "./exceptions.js";
+import { ctx } from "./request.js";
+const bindings = new Map();
+/**
+ * Bind a route parameter to a model. `:user` becomes a `User`; a row that doesn't
+ * exist (or is outside `scope`) is a 404 before your handler runs.
+ */
+export function bindModel(param, model, options = {}) {
+    const column = options.key ?? model.primaryKey;
+    bindings.set(param, {
+        model: model,
+        resolve: async (value, c) => {
+            let query = model.query().where(column, value);
+            if (options.scope)
+                query = options.scope(query, c) ?? query;
+            const row = await query.first();
+            if (row)
+                return new model(row);
+            // A miss is a 404 *here*, not a null the handler has to remember to check.
+            if (options.missing)
+                return options.missing(value, c);
+            throw new NotFoundException(`No ${model.name} for "${value}".`);
+        },
+    });
+}
+/**
+ * Bind a route parameter to anything at all — a tenant from a map, a feature flag,
+ * a value from an API. Returning `undefined` or `null` is a 404.
+ */
+export function bindRoute(param, resolve) {
+    bindings.set(param, {
+        resolve: async (value, c) => {
+            const resolved = await resolve(value, c);
+            if (resolved === undefined || resolved === null) {
+                throw new NotFoundException(`No match for "${value}".`);
+            }
+            return resolved;
+        },
+    });
+}
+/** Whether a parameter has a binding registered. */
+export function hasBinding(param) {
+    return bindings.has(param);
+}
+/** Drop every binding — a clean slate between tests. */
+export function clearBindings() {
+    bindings.clear();
+}
+/** The parameter names in a route pattern: `/users/:user/posts/:post` → both. */
+export function paramNames(pattern) {
+    return [...pattern.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1]);
+}
+/**
+ * Resolve this route's bound parameters and stash them on the request. Installed
+ * by the HTTP kernel for any route whose pattern has a bound parameter — so the
+ * work is skipped entirely for routes that don't.
+ *
+ * @internal
+ */
+export function resolveBindings(params, c) {
+    const present = params.filter((p) => bindings.has(p));
+    if (!present.length)
+        return;
+    return (async () => {
+        const resolved = {};
+        // In series, on purpose: a scoped binding usually depends on one resolved
+        // before it (`/users/:user/posts/:post`, where the post is scoped to the user).
+        for (const param of present) {
+            const value = c.req.param(param);
+            if (value === undefined)
+                continue;
+            resolved[param] = await bindings.get(param).resolve(value, c);
+        }
+        c.set("bindings", { ...c.get("bindings"), ...resolved });
+    })();
+}
+/** Middleware that resolves the bound params of a route pattern. @internal */
+export function bindingMiddleware(pattern) {
+    const params = paramNames(pattern);
+    if (!params.length)
+        return undefined;
+    return async (c, next) => {
+        await resolveBindings(params, c);
+        await next();
+    };
+}
+/* -------------------------------- accessors ------------------------------- */
+/** The raw bound value for a parameter, if any. */
+export function boundValue(param, c) {
+    const store = (c ?? currentCtx())?.get("bindings");
+    return store?.[param];
+}
+/**
+ * The model bound to this route — already fetched, never null.
+ *
+ *   router.get("/posts/:post", () => {
+ *     const post = boundModel(Post);   // a Post, guaranteed
+ *   });
+ *
+ * Pass the parameter name when one model is bound to several (`/users/:user/friends/:friend`).
+ */
+export function boundModel(model, param, c) {
+    const ctx = c ?? currentCtx();
+    const store = ctx?.get("bindings") ?? {};
+    if (param) {
+        const value = store[param];
+        if (value === undefined) {
+            throw new Error(`Nothing is bound to ":${param}". Register it with bindModel("${param}", ${model.name}).`);
+        }
+        return value;
+    }
+    // No name given: find the one param bound to this model.
+    const matches = Object.entries(store).filter(([name]) => bindings.get(name)?.model === model);
+    if (!matches.length) {
+        throw new Error(`No route parameter is bound to ${model.name}. Register one with bindModel("<param>", ${model.name}).`);
+    }
+    if (matches.length > 1) {
+        // Two params, same model — we can't guess which one you meant.
+        throw new Error(`${matches.length} parameters are bound to ${model.name} (${matches.map(([n]) => `":${n}"`).join(", ")}). ` +
+            `Say which: boundModel(${model.name}, "${matches[0][0]}").`);
+    }
+    return matches[0][1];
+}
+/** The request in scope, or undefined outside one. */
+function currentCtx() {
+    try {
+        return ctx();
+    }
+    catch {
+        return undefined; // called outside a request
+    }
+}

package/dist/core/http/kernel.js

@@ -6,6 +6,7 @@
 import { Hono } from "hono";
 import { contextStorage } from "hono/context-storage";
 import { Config } from "../config.js";
+import { bindingMiddleware } from "../binding.js";
 import { HttpException, NotFoundException, ValidationException, STATUS_TEXT, } from "../exceptions.js";
 import { Router } from "./router.js";
 import { instrument, runRequest, newRequestId, currentRequestId } from "../instrumentation.js";
@@ -142,7 +143,15 @@ export class HttpKernel {
             for (const [param, rgx] of Object.entries(route.wheres)) {
                 path = path.replace(new RegExp(`:${param}(\\??)`), `:${param}{${rgx}}$1`);
             }
-            const middleware = [setRoute, ...route.middleware.map((m) => router.resolveMiddleware(m))];
+            // Route model binding: resolve `:user` into a User *before* the handler (and
+            // before route middleware, so a policy check can read the bound model). Only
+            // routes that actually have params pay for it.
+            const binding = bindingMiddleware(route.path);
+            const middleware = [
+                setRoute,
+                ...(binding ? [binding] : []),
+                ...route.middleware.map((m) => router.resolveMiddleware(m)),
+            ];
             hono.on(route.methods, [path], ...middleware, honoHandler);
         }
         hono.notFound((c) => this.handle(new NotFoundException(`No route for ${c.req.method} ${c.req.path}`), c));

package/dist/core/index.d.ts

@@ -76,6 +76,8 @@ export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher, MiddlewareRef
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export type { InertiaPage, InertiaOptions } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
+export { bindModel, bindRoute, boundModel, boundValue, hasBinding, clearBindings } from "./binding.js";
+export type { BindingOptions, ModelClass } from "./binding.js";
 export { defineCommand, arg, flag, ConsoleKernel, ConsoleError, parseArgv } from "./console.js";
 export type { CommandDefinition, CommandContext, AnyCommand, ArgSpec, FlagSpec, ArgsSpec, FlagsSpec, ConsoleKernelOptions, } from "./console.js";
 export { createUi, stripAnsi } from "./console-ui.js";

package/dist/core/index.js

@@ -41,6 +41,7 @@ export { instrument, runRequest, currentRequestId, newRequestId, } from "./instr
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
+export { bindModel, bindRoute, boundModel, boundValue, hasBinding, clearBindings } from "./binding.js";
 export { defineCommand, arg, flag, ConsoleKernel, ConsoleError, parseArgv } from "./console.js";
 export { createUi, stripAnsi } from "./console-ui.js";
 export { createPrompt } from "./console-prompt.js";

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.78.2",
+  "version": "0.80.0",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -40,6 +40,13 @@
       "path": "docs/authorization.md",
       "example": "docs/examples/authorization.ts"
     },
+    {
+      "slug": "billing",
+      "title": "Billing",
+      "summary": "Keel Billing is a subscription-billing layer — a port of Laravel Cashier — for charging customers, managing subscriptions, and reconciling gateway state through webhooks.",
+      "path": "docs/billing.md",
+      "example": null
+    },
     {
       "slug": "broadcasting",
       "title": "Broadcasting",
@@ -643,6 +650,21 @@
       "kind": "value",
       "module": "helpers"
     },
+    {
+      "name": "BindingOptions",
+      "kind": "type",
+      "module": "binding"
+    },
+    {
+      "name": "bindModel",
+      "kind": "value",
+      "module": "binding"
+    },
+    {
+      "name": "bindRoute",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "body",
       "kind": "value",
@@ -658,6 +680,16 @@
       "kind": "value",
       "module": "helpers"
     },
+    {
+      "name": "boundModel",
+      "kind": "value",
+      "module": "binding"
+    },
+    {
+      "name": "boundValue",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "broadcast",
       "kind": "value",
@@ -783,6 +815,11 @@
       "kind": "value",
       "module": "authorization"
     },
+    {
+      "name": "clearBindings",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "clearChannels",
       "kind": "value",
@@ -1413,6 +1450,11 @@
       "kind": "value",
       "module": "social"
     },
+    {
+      "name": "hasBinding",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "hash",
       "kind": "value",
@@ -1843,6 +1885,11 @@
       "kind": "value",
       "module": "model"
     },
+    {
+      "name": "ModelClass",
+      "kind": "type",
+      "module": "binding"
+    },
     {
       "name": "ModelFactory",
       "kind": "value",

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/examples/binding.ts

@@ -0,0 +1,83 @@
+// Type-check harness for the route-model-binding section of docs/routing.md.
+// Compile-only — never executed.
+import {
+  bindModel,
+  bindRoute,
+  boundModel,
+  boundValue,
+  hasBinding,
+  clearBindings,
+  Model,
+  Router,
+  make,
+  ForbiddenException,
+  type Ctx,
+  type BindingOptions,
+} from "@shaferllc/keel/core";
+import type { MiddlewareHandler } from "hono";
+
+class Post extends Model {
+  static override table = "posts";
+  declare id: number;
+  declare slug: string;
+  declare authorId: number;
+}
+
+interface Tenant {
+  id: number;
+  name: string;
+}
+
+declare const tenants: Map<string, Tenant>;
+declare function currentUserId(c: Ctx): number;
+declare function edit(c: Ctx): Response;
+
+export function basic() {
+  bindModel("post", Post);
+
+  make(Router).get("/posts/:post", (c) => {
+    const post: Post = boundModel(Post); // a Post, guaranteed
+    return c.json({ id: post.id });
+  });
+}
+
+export function byAnotherColumn() {
+  bindModel("post", Post, { key: "slug" });
+}
+
+/** scope is row-level security: a row outside it 404s. */
+export function scoped() {
+  const options: BindingOptions<Post> = {
+    key: "slug",
+    scope: (query, c) => query.where("authorId", currentUserId(c)),
+    missing: () => new Post({ id: 0 }),
+  };
+  bindModel("post", Post, options);
+}
+
+export function middlewareSeesTheModel() {
+  const mustOwn: MiddlewareHandler = async (c, next) => {
+    if (boundModel(Post).authorId !== currentUserId(c)) throw new ForbiddenException();
+    await next();
+  };
+
+  make(Router).get("/posts/:post/edit", edit).middleware(mustOwn);
+}
+
+export function anythingAtAll() {
+  bindRoute("tenant", (slug) => tenants.get(slug));
+
+  make(Router).get("/t/:tenant", (c) => {
+    const tenant = boundValue<Tenant>("tenant");
+    return c.json({ name: tenant?.name });
+  });
+}
+
+export function disambiguate(): [Post, Post] {
+  return [boundModel(Post, "post"), boundModel(Post, "original")];
+}
+
+export function registry(): boolean {
+  clearBindings();
+  return hasBinding("post");
+}

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