@shaferllc/keel 0.83.0 → 0.83.2

package/README.md

@@ -160,7 +160,7 @@ src/core/            The framework
 src/db/              Database adapters (D1, Postgres, libSQL)
 src/api/             CRUD REST resources from a model
 src/openapi/         Generates an OpenAPI spec from the routes
-src/billing/         Subscription billing — Stripe + Paddle (Cashier port)
+src/billing/         Subscription billing — Stripe + Paddle
 src/watch/           The debug dashboard
 src/mcp/             The MCP server (docs + API for AI agents)
 src/vite/            The Vite plugin
@@ -228,7 +228,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Internationalization](./docs/i18n.md) | ICU messages, `Intl` formatters, locale detection |
 | [Pages](./docs/pages.md) | Page-based routing — a file is a route |
 | [Packages](./docs/packages.md) | Redistributable slices of an app: routes, migrations, commands |
-| [Billing](./docs/billing.md) | Subscriptions, charges & webhooks — Stripe + Paddle (Cashier port) |
+| [Billing](./docs/billing.md) | Subscriptions, charges & webhooks — Stripe + Paddle |
 | [Watch](./docs/watch.md) | Debug dashboard — requests, queries, jobs, logs at `/watch` |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
 | [Templates](./docs/templates.md) | `{{ }}` + `@`-tag templating engine, edge-safe |

package/dist/billing/billable.d.ts

@@ -1,7 +1,6 @@
 /**
- * The `Billable` mixin — Cashier's Billable trait, as a TypeScript mixin. Apply
- * it to a model to give that model a gateway customer, subscriptions, charges,
- * and checkout:
+ * The `Billable` mixin — apply it to a model to give that model a gateway
+ * customer, subscriptions, charges, and checkout:
  *
  *   class User extends Billable(Model) {
  *     static table = "users";

package/dist/billing/billable.js

@@ -1,7 +1,6 @@
 /**
- * The `Billable` mixin — Cashier's Billable trait, as a TypeScript mixin. Apply
- * it to a model to give that model a gateway customer, subscriptions, charges,
- * and checkout:
+ * The `Billable` mixin — apply it to a model to give that model a gateway
+ * customer, subscriptions, charges, and checkout:
  *
  *   class User extends Billable(Model) {
  *     static table = "users";

package/dist/billing/billing.config.stub

@@ -1,7 +1,7 @@
 import { env } from "@shaferllc/keel/core";
 
 /**
- * Billing configuration — a Cashier-style port covering Stripe and Paddle.
+ * Billing configuration — subscriptions and charges, covering Stripe and Paddle.
  * Published with `keel vendor:publish --tag billing-config`.
  */
 export default {

package/dist/billing/builder.d.ts

@@ -1,6 +1,6 @@
 /**
- * The fluent subscription builder — Cashier's `newSubscription(...)->create()`.
- * The `Billable` mixin hands it a small `BillableTarget` (so this file needn't
+ * The fluent subscription builder — `newSubscription(...).create()`. The
+ * `Billable` mixin hands it a small `BillableTarget` (so this file needn't
  * import the mixin, avoiding a cycle); the builder shapes the request, calls the
  * gateway, and persists a local `Subscription` synced from the result.
  *

package/dist/billing/builder.js

@@ -1,6 +1,6 @@
 /**
- * The fluent subscription builder — Cashier's `newSubscription(...)->create()`.
- * The `Billable` mixin hands it a small `BillableTarget` (so this file needn't
+ * The fluent subscription builder — `newSubscription(...).create()`. The
+ * `Billable` mixin hands it a small `BillableTarget` (so this file needn't
  * import the mixin, avoiding a cycle); the builder shapes the request, calls the
  * gateway, and persists a local `Subscription` synced from the result.
  *

package/dist/billing/provider.d.ts

@@ -1,5 +1,5 @@
 /**
- * Keel Billing — a Cashier-style port covering Stripe and Paddle, shipped as a
+ * Keel Billing — subscription billing covering Stripe and Paddle, shipped as a
  * Keel package. One line in `bootstrap/providers.ts` turns it on:
  *
  *   app.register(BillingServiceProvider)

package/dist/billing/provider.js

@@ -1,5 +1,5 @@
 /**
- * Keel Billing — a Cashier-style port covering Stripe and Paddle, shipped as a
+ * Keel Billing — subscription billing covering Stripe and Paddle, shipped as a
  * Keel package. One line in `bootstrap/providers.ts` turns it on:
  *
  *   app.register(BillingServiceProvider)
@@ -29,7 +29,7 @@ export class BillingServiceProvider extends PackageProvider {
         registerDefaultGateways(this.manager);
         setBilling(this.manager);
         this.app.instance(BillingManager, this.manager);
-        // Cashier targets the standard `users` billable table.
+        // Default billable table is `users`.
         this.migrations([billingMigration("users")]);
         this.publishes({ [join(here, "billing.config.stub")]: "config/billing.ts" }, "billing-config");
     }

package/dist/billing/subscription-item.d.ts

@@ -1,7 +1,6 @@
 /**
  * One line of a subscription — a single price and its quantity. A single-price
  * subscription has exactly one item; a multi-product subscription has several.
- * Mirrors Cashier's `subscription_items` table.
  */
 import { Model } from "../core/model.js";
 import type { Casts } from "../core/casts.js";

package/dist/billing/subscription-item.js

@@ -1,7 +1,6 @@
 /**
  * One line of a subscription — a single price and its quantity. A single-price
  * subscription has exactly one item; a multi-product subscription has several.
- * Mirrors Cashier's `subscription_items` table.
  */
 import { Model } from "../core/model.js";
 export class SubscriptionItem extends Model {

package/dist/core/decorators.d.ts

@@ -1,10 +1,9 @@
 /**
  * Request decorators — attach named, computed values to the current request,
- * resolved lazily and memoized for the life of that request. Inspired by
- * Fastify's `decorateRequest`, but without its footguns: you register a resolver
- * once, and Keel computes it on first access and caches it per request (keyed off
- * the Hono context via a WeakMap, so there's no shared-state leak between
- * requests and no V8 shape deopt to design around).
+ * resolved lazily and memoized for the life of that request. You register a
+ * resolver once, and Keel computes it on first access and caches it per request
+ * (keyed off the Hono context via a WeakMap, so there's no shared-state leak
+ * between requests and no V8 shape deopt to design around).
  *
  *   decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
  *
@@ -18,8 +17,7 @@ import type { Context } from "hono";
 /** Resolves a decorator's value from the current request context. */
 export type RequestResolver<T = unknown> = (c: Context) => T | Promise<T>;
 /**
- * Register a request decorator. Throws if `name` is already registered — a
- * collision guard, like Fastify's.
+ * Register a request decorator. Throws if `name` is already registered.
  */
 export declare function decorateRequest<T>(name: string, resolver: RequestResolver<T>): void;
 /** Whether a request decorator has been registered. */

package/dist/core/decorators.js

@@ -1,10 +1,9 @@
 /**
  * Request decorators — attach named, computed values to the current request,
- * resolved lazily and memoized for the life of that request. Inspired by
- * Fastify's `decorateRequest`, but without its footguns: you register a resolver
- * once, and Keel computes it on first access and caches it per request (keyed off
- * the Hono context via a WeakMap, so there's no shared-state leak between
- * requests and no V8 shape deopt to design around).
+ * resolved lazily and memoized for the life of that request. You register a
+ * resolver once, and Keel computes it on first access and caches it per request
+ * (keyed off the Hono context via a WeakMap, so there's no shared-state leak
+ * between requests and no V8 shape deopt to design around).
  *
  *   decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
  *
@@ -27,8 +26,7 @@ function bag(c) {
     return b;
 }
 /**
- * Register a request decorator. Throws if `name` is already registered — a
- * collision guard, like Fastify's.
+ * Register a request decorator. Throws if `name` is already registered.
  */
 export function decorateRequest(name, resolver) {
     if (resolvers.has(name)) {

package/dist/core/exceptions.d.ts

@@ -92,9 +92,8 @@ export declare class ServiceUnavailableException extends HttpException {
 }
 /**
  * Mint a reusable, coded `HttpException` subclass — the ergonomic way to define
- * app-specific errors with a stable, machine-readable `code`. Inspired by
- * `@fastify/error`. The `message` may carry `%s` placeholders, filled in order
- * from the constructor arguments.
+ * app-specific errors with a stable, machine-readable `code`. The `message` may
+ * carry `%s` placeholders, filled in order from the constructor arguments.
  *
  *   const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
  *   throw new InsufficientFunds("$40");

package/dist/core/exceptions.js

@@ -196,9 +196,8 @@ export class ServiceUnavailableException extends HttpException {
 }
 /**
  * Mint a reusable, coded `HttpException` subclass — the ergonomic way to define
- * app-specific errors with a stable, machine-readable `code`. Inspired by
- * `@fastify/error`. The `message` may carry `%s` placeholders, filled in order
- * from the constructor arguments.
+ * app-specific errors with a stable, machine-readable `code`. The `message` may
+ * carry `%s` placeholders, filled in order from the constructor arguments.
  *
  *   const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
  *   throw new InsufficientFunds("$40");

package/dist/core/model-query.d.ts

@@ -1,7 +1,7 @@
 /**
  * A model-aware query builder — what `Model.query()` sugar and eager loading are
  * built on. It wraps the plain `QueryBuilder`, hydrates rows into models (firing
- * `retrieved`), and adds the relationship-aware operations Eloquent has and a raw
+ * `retrieved`), and adds the relationship-aware operations a query builder lacks and a raw
  * builder can't: `with()` (nested eager loading), `withCount()`, and existence
  * filters `has()` / `whereHas()` / `doesntHave()`.
  *

package/dist/core/model-query.js

@@ -1,7 +1,7 @@
 /**
  * A model-aware query builder — what `Model.query()` sugar and eager loading are
  * built on. It wraps the plain `QueryBuilder`, hydrates rows into models (firing
- * `retrieved`), and adds the relationship-aware operations Eloquent has and a raw
+ * `retrieved`), and adds the relationship-aware operations a query builder lacks and a raw
  * builder can't: `with()` (nested eager loading), `withCount()`, and existence
  * filters `has()` / `whereHas()` / `doesntHave()`.
  *

package/dist/core/request-logger.d.ts

@@ -1,8 +1,8 @@
 /**
  * Per-request logging. `requestLogger()` middleware binds a child logger to each
  * request with a generated `reqId`, so every log line within that request
- * correlates — Fastify's `request.log`, built on Keel's `Logger.child()`. It can
- * also log the request start and completion (method, path, status, duration).
+ * correlates — built on Keel's `Logger.child()`. It can also log the request
+ * start and completion (method, path, status, duration).
  *
  *   kernel.use(requestLogger());          // in app/Http/Kernel.ts
  *   requestLog().info("charging card");   // anywhere in the request → carries reqId

package/dist/core/request-logger.js

@@ -1,8 +1,8 @@
 /**
  * Per-request logging. `requestLogger()` middleware binds a child logger to each
  * request with a generated `reqId`, so every log line within that request
- * correlates — Fastify's `request.log`, built on Keel's `Logger.child()`. It can
- * also log the request start and completion (method, path, status, duration).
+ * correlates — built on Keel's `Logger.child()`. It can also log the request
+ * start and completion (method, path, status, duration).
  *
  *   kernel.use(requestLogger());          // in app/Http/Kernel.ts
  *   requestLog().info("charging card");   // anywhere in the request → carries reqId

package/dist/core/request.js

@@ -112,7 +112,7 @@ export function html(body, status) {
 }
 export function redirect(location, status) {
     const c = maybeCtx();
-    // Koa-style `redirect("back")`: bounce to the Referer, or "/" if there isn't one.
+    // `redirect("back")`: bounce to the Referer, or "/" if there isn't one.
     if (location === "back")
         location = c?.req.header("referer") ?? "/";
     return c

package/dist/core/testing.d.ts

@@ -1,8 +1,8 @@
 /**
  * A test client for Keel apps — inject requests without a live server and assert
- * on the response, the way Fastify's `inject()` does. Wraps the app's Hono
- * instance (which already does fetch-style request injection), adding verb
- * helpers with JSON bodies and fluent response assertions.
+ * on the response. Wraps the app's Hono instance (which already does fetch-style
+ * request injection), adding verb helpers with JSON bodies and fluent response
+ * assertions.
  *
  *   const client = await testClient(app);
  *   const res = await client.post("/users", { email: "a@b.com" });

package/dist/core/testing.js

@@ -1,8 +1,8 @@
 /**
  * A test client for Keel apps — inject requests without a live server and assert
- * on the response, the way Fastify's `inject()` does. Wraps the app's Hono
- * instance (which already does fetch-style request injection), adding verb
- * helpers with JSON bodies and fluent response assertions.
+ * on the response. Wraps the app's Hono instance (which already does fetch-style
+ * request injection), adding verb helpers with JSON bodies and fluent response
+ * assertions.
  *
  *   const client = await testClient(app);
  *   const res = await client.post("/users", { email: "a@b.com" });

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.0",
+  "version": "0.83.2",
   "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",
@@ -50,9 +50,9 @@
     {
       "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.",
+      "summary": "Keel Billing is a subscription-billing layer for charging customers, managing subscriptions, and reconciling gateway state through webhooks.",
       "path": "docs/billing.md",
-      "example": null
+      "example": "docs/examples/billing.ts"
     },
     {
       "slug": "broadcasting",
@@ -115,7 +115,7 @@
       "title": "CORS",
       "summary": "Cross-Origin Resource Sharing lets browsers on other origins call your API.",
       "path": "docs/cors.md",
-      "example": null
+      "example": "docs/examples/cors.ts"
     },
     {
       "slug": "database",
@@ -192,7 +192,7 @@
       "title": "Built on Hono",
       "summary": "Keel's HTTP layer is Hono — an ultrafast, web-standard router that runs on Node, Cloudflare Workers, Deno, Bun, and more.",
       "path": "docs/hono.md",
-      "example": null
+      "example": "docs/examples/hono.ts"
     },
     {
       "slug": "hooks",
@@ -269,21 +269,21 @@
       "title": "OpenAPI",
       "summary": "Keel OpenAPI generates an OpenAPI 3 spec from your routes and serves Swagger UI to explore it.",
       "path": "docs/openapi.md",
-      "example": null
+      "example": "docs/examples/openapi.ts"
     },
     {
       "slug": "orm",
       "title": "ORM",
       "summary": "Keel's ORM is a compact active record over the query builder: a model is a class pointed at a table, and its rows come back as typed objects with methods.",
       "path": "docs/orm.md",
-      "example": null
+      "example": "docs/examples/orm.ts"
     },
     {
       "slug": "packages",
       "title": "Packages",
       "summary": "A package is a redistributable slice of a Keel app — routes, a UI, config, migrations, console commands — that installs with a single app.register(...).",
       "path": "docs/packages.md",
-      "example": null
+      "example": "docs/examples/packages.ts"
     },
     {
       "slug": "pages",
@@ -304,7 +304,7 @@
       "title": "Query Builder",
       "summary": "Keel's driver-agnostic query builder — build and run SQL by chaining methods off db(table).",
       "path": "docs/query-builder.md",
-      "example": null
+      "example": "docs/examples/query-builder.ts"
     },
     {
       "slug": "queues",
@@ -353,7 +353,7 @@
       "title": "Securing SSR apps",
       "summary": "Two middlewares harden server-rendered apps: securityHeaders() sets the defensive HTTP headers browsers act on, and csrf() blocks cross-site form submissions.",
       "path": "docs/security.md",
-      "example": null
+      "example": "docs/examples/security.ts"
     },
     {
       "slug": "sessions",
@@ -367,14 +367,14 @@
       "title": "Social authentication",
       "summary": "\"Sign in with GitHub / Google / Discord\" — OAuth 2.0, without an SDK.",
       "path": "docs/social-auth.md",
-      "example": null
+      "example": "docs/examples/social-auth.ts"
     },
     {
       "slug": "starter-kits",
       "title": "Starter kits",
       "summary": "",
       "path": "docs/starter-kits.md",
-      "example": null
+      "example": "docs/examples/starter-kits.ts"
     },
     {
       "slug": "static-files",
@@ -456,9 +456,9 @@
     {
       "slug": "watch",
       "title": "Watch",
-      "summary": "Keel Watch is a debug dashboard — a Telescope for Keel.",
+      "summary": "Keel Watch is a debug dashboard for Keel apps.",
       "path": "docs/watch.md",
-      "example": null
+      "example": "docs/examples/watch.ts"
     }
   ],
   "api": [

package/docs/billing.md

@@ -1,9 +1,8 @@
 # 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:
+Keel Billing is a subscription-billing layer 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
@@ -206,6 +205,46 @@ resolveBillableUsing(async (customerId) => {
 });
 ```
 
+## A complete flow
+
+From "user signs up" to "they're subscribed", with the fake gateway for tests:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+} from "@shaferllc/keel/billing";
+
+class User extends Billable(Model) {
+  static table = "users";
+  declare email: string;
+}
+
+// In a test bootstrap:
+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);
+
+const user = await User.create({ email: "ada@example.com" });
+await user.newSubscription("default", "price_pro").trialDays(14).create();
+
+await user.subscribed(); // true
+fake.calls.some((c) => c.method === "createSubscription"); // true
+```
+
+In production you skip the fake manager — `BillingServiceProvider` wires the
+real gateway from `config/billing.ts` and `.env`.
+
 ## Gateway differences
 
 | Concern | Stripe | Paddle |
@@ -221,8 +260,8 @@ resolveBillableUsing(async (customerId) => {
 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.
+`billing_customer_id`, `pm_type`, `pm_last_four`, `trial_ends_at`). The default
+migration targets the standard `users` billable table.
 
 ## Testing