@shaferllc/keel 0.83.1 → 0.83.3

package/README.md

@@ -161,6 +161,8 @@ 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
+src/gates/           Signup gates — invite codes & email allowlist
+src/hosting/         Cloudflare / dump / secrets helpers for hosted apps
 src/watch/           The debug dashboard
 src/mcp/             The MCP server (docs + API for AI agents)
 src/vite/            The Vite plugin
@@ -203,7 +205,8 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Lifecycle Hooks](./docs/hooks.md) | onReady/onShutdown, graceful shutdown, onRoute |
 | [Sessions](./docs/sessions.md) | Cookie-backed sessions, flash messages |
 | [Authentication](./docs/authentication.md) | Session auth, guards, user provider |
-| [Authorization](./docs/authorization.md) | Gates & policies, `can`/`authorize` |
+| [Gates](./docs/gates.md) | Signup gating — invite codes & email allowlist |
+| [Authorization](./docs/authorization.md) | Ability gates & policies, `can`/`authorize` |
 | [Database](./docs/database.md) | Driver-agnostic query builder |
 | [Models](./docs/models.md) | Active-record: find/create/save, casts, relations |
 | [Migrations](./docs/migrations.md) | Schema builder + migrator, dialect-aware |

package/dist/gates/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Keel Gates — private-alpha / waitlist signup gating.
+ *
+ *   import { GatesServiceProvider, canRegister, redeemInvite } from "@shaferllc/keel/gates";
+ *
+ * Not the same as team invitations in `@shaferllc/keel/teams`.
+ */
+export { GatesServiceProvider } from "./provider.js";
+export { InviteCode, EmailAllowlist, canRegister, redeemInvite, gatesMigration, } from "./models.js";
+export type { GateCheck } from "./models.js";

package/dist/gates/index.js

@@ -0,0 +1,9 @@
+/**
+ * Keel Gates — private-alpha / waitlist signup gating.
+ *
+ *   import { GatesServiceProvider, canRegister, redeemInvite } from "@shaferllc/keel/gates";
+ *
+ * Not the same as team invitations in `@shaferllc/keel/teams`.
+ */
+export { GatesServiceProvider } from "./provider.js";
+export { InviteCode, EmailAllowlist, canRegister, redeemInvite, gatesMigration, } from "./models.js";

package/dist/gates/models.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Signup gates — invite codes + email allowlist for private alpha / waitlist.
+ * Distinct from team invitations (`@shaferllc/keel/teams`).
+ */
+import { Model } from "../core/model.js";
+import type { Migration } from "../core/migrations.js";
+export declare class InviteCode extends Model {
+    static table: string;
+    static fillable: string[];
+    static timestamps: boolean;
+    id: number;
+    code: string;
+    max_uses: number;
+    uses: number;
+    created_by: number | null;
+    expires_at: string | null;
+}
+export declare class EmailAllowlist extends Model {
+    static table: string;
+    static fillable: string[];
+    static timestamps: boolean;
+    id: number;
+    email: string;
+    created_by: number | null;
+}
+export type GateCheck = {
+    ok: true;
+    via: "allowlist" | "code";
+    invite?: InviteCode;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Private alpha: allowlisted email OR a valid invite code. */
+export declare function canRegister(email: string, inviteCode?: string): Promise<GateCheck>;
+export declare function redeemInvite(invite: InviteCode): Promise<void>;
+/**
+ * Schema for invite codes + allowlist.
+ * Uses IF NOT EXISTS so apps that already created these tables (e.g. early
+ * keel-cloud) can still register the provider safely.
+ */
+export declare function gatesMigration(): Migration;

package/dist/gates/models.js

@@ -0,0 +1,76 @@
+/**
+ * Signup gates — invite codes + email allowlist for private alpha / waitlist.
+ * Distinct from team invitations (`@shaferllc/keel/teams`).
+ */
+import { Model } from "../core/model.js";
+export class InviteCode extends Model {
+    static table = "invite_codes";
+    static fillable = ["code", "max_uses", "uses", "created_by", "expires_at"];
+    static timestamps = true;
+}
+export class EmailAllowlist extends Model {
+    static table = "email_allowlist";
+    static fillable = ["email", "created_by"];
+    static timestamps = true;
+}
+/** Private alpha: allowlisted email OR a valid invite code. */
+export async function canRegister(email, inviteCode) {
+    const normalized = email.toLowerCase().trim();
+    const allowed = await EmailAllowlist.newQuery().where("email", normalized).first();
+    if (allowed)
+        return { ok: true, via: "allowlist" };
+    const code = String(inviteCode ?? "").trim();
+    if (!code) {
+        return { ok: false, reason: "Registration requires an invite code or allowlisted email." };
+    }
+    const invite = await InviteCode.newQuery().where("code", code).first();
+    if (!invite)
+        return { ok: false, reason: "That invite code is invalid." };
+    if (invite.expires_at && new Date(invite.expires_at).getTime() < Date.now()) {
+        return { ok: false, reason: "That invite code has expired." };
+    }
+    if (invite.uses >= invite.max_uses) {
+        return { ok: false, reason: "That invite code has already been used up." };
+    }
+    return { ok: true, via: "code", invite };
+}
+export async function redeemInvite(invite) {
+    await invite.update({ uses: invite.uses + 1 });
+}
+/**
+ * Schema for invite codes + allowlist.
+ * Uses IF NOT EXISTS so apps that already created these tables (e.g. early
+ * keel-cloud) can still register the provider safely.
+ */
+export function gatesMigration() {
+    return {
+        name: "gates_00_invite_allowlist",
+        async up(schema) {
+            await schema.raw(`
+        CREATE TABLE IF NOT EXISTS invite_codes (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          code VARCHAR(255) NOT NULL UNIQUE,
+          max_uses INTEGER DEFAULT 1,
+          uses INTEGER DEFAULT 0,
+          created_by INTEGER,
+          expires_at TIMESTAMP,
+          created_at TIMESTAMP,
+          updated_at TIMESTAMP
+        )
+      `);
+            await schema.raw(`
+        CREATE TABLE IF NOT EXISTS email_allowlist (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          email VARCHAR(255) NOT NULL UNIQUE,
+          created_by INTEGER,
+          created_at TIMESTAMP,
+          updated_at TIMESTAMP
+        )
+      `);
+        },
+        async down(schema) {
+            await schema.dropTable("email_allowlist").catch(() => { });
+            await schema.dropTable("invite_codes").catch(() => { });
+        },
+    };
+}

package/dist/gates/provider.d.ts

@@ -0,0 +1,10 @@
+import { PackageProvider } from "../core/package.js";
+/**
+ * Signup gates — invite codes + email allowlist.
+ *
+ *   app.register(GatesServiceProvider)
+ */
+export declare class GatesServiceProvider extends PackageProvider {
+    readonly name = "gates";
+    register(): void;
+}

package/dist/gates/provider.js

@@ -0,0 +1,13 @@
+import { PackageProvider } from "../core/package.js";
+import { gatesMigration } from "./models.js";
+/**
+ * Signup gates — invite codes + email allowlist.
+ *
+ *   app.register(GatesServiceProvider)
+ */
+export class GatesServiceProvider extends PackageProvider {
+    name = "gates";
+    register() {
+        this.migrations([gatesMigration()]);
+    }
+}

package/dist/hosting/cloudflare.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cloudflare REST client — D1 + Workers Custom Domains.
+ * Credentials are constructor args (no app config coupling).
+ */
+export type CloudflareCredentials = {
+    accountId: string;
+    apiToken: string;
+    /** Optional pin for a primary zone name (e.g. sites.example.com). */
+    pinnedZoneId?: string;
+    pinnedZoneName?: string;
+};
+export type WorkerDomain = {
+    id: string;
+    hostname: string;
+    service: string;
+    zone_id?: string;
+    zone_name?: string;
+};
+export declare function cloudflareConfigured(creds: Partial<CloudflareCredentials>): boolean;
+export declare class CloudflareClient {
+    private creds;
+    private baseUrl;
+    constructor(creds: CloudflareCredentials);
+    private accountId;
+    private apiToken;
+    private request;
+    createD1Database(name: string): Promise<{
+        uuid: string;
+        name: string;
+    }>;
+    resolveZoneId(zoneName: string): Promise<{
+        id: string;
+        name: string;
+    } | null>;
+    attachWorkerDomain(input: {
+        hostname: string;
+        service: string;
+        zoneId: string;
+        zoneName: string;
+    }): Promise<WorkerDomain>;
+    detachWorkerDomain(domainId: string): Promise<void>;
+    findWorkerDomain(hostname: string): Promise<WorkerDomain | null>;
+}

package/dist/hosting/cloudflare.js

@@ -0,0 +1,66 @@
+/**
+ * Cloudflare REST client — D1 + Workers Custom Domains.
+ * Credentials are constructor args (no app config coupling).
+ */
+export function cloudflareConfigured(creds) {
+    return Boolean(creds.accountId && creds.apiToken);
+}
+export class CloudflareClient {
+    creds;
+    baseUrl = "https://api.cloudflare.com/client/v4";
+    constructor(creds) {
+        this.creds = creds;
+    }
+    accountId() {
+        return this.creds.accountId;
+    }
+    apiToken() {
+        return this.creds.apiToken;
+    }
+    async request(method, path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.apiToken()}`,
+                "content-type": "application/json",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.success) {
+            const message = payload.errors?.map((e) => `${e.code}: ${e.message}`).join("; ") ??
+                `Cloudflare request failed (${response.status})`;
+            throw new Error(message);
+        }
+        return payload.result;
+    }
+    async createD1Database(name) {
+        return this.request("POST", `/accounts/${this.accountId()}/d1/database`, { name });
+    }
+    async resolveZoneId(zoneName) {
+        const pinned = this.creds.pinnedZoneId;
+        const pinnedName = this.creds.pinnedZoneName;
+        if (pinned && pinnedName && zoneName === pinnedName) {
+            return { id: pinned, name: zoneName };
+        }
+        const result = await this.request("GET", `/zones?name=${encodeURIComponent(zoneName)}&status=active&per_page=1`);
+        const zone = result?.[0];
+        return zone ? { id: zone.id, name: zone.name } : null;
+    }
+    async attachWorkerDomain(input) {
+        return this.request("PUT", `/accounts/${this.accountId()}/workers/domains`, {
+            hostname: input.hostname,
+            service: input.service,
+            environment: "production",
+            zone_id: input.zoneId,
+            zone_name: input.zoneName,
+        });
+    }
+    async detachWorkerDomain(domainId) {
+        await this.request("DELETE", `/accounts/${this.accountId()}/workers/domains/${domainId}`);
+    }
+    async findWorkerDomain(hostname) {
+        const result = await this.request("GET", `/accounts/${this.accountId()}/workers/domains?hostname=${encodeURIComponent(hostname)}`);
+        return result?.[0] ?? null;
+    }
+}

package/dist/hosting/dump.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Dump a SQLite-compatible connection to a portable .sql script.
+ */
+import type { Connection } from "../core/database.js";
+export declare function dumpConnection(conn: Connection, header: string, opts?: {
+    generatedBy?: string;
+}): Promise<string>;

package/dist/hosting/dump.js

@@ -0,0 +1,58 @@
+/**
+ * Dump a SQLite-compatible connection to a portable .sql script.
+ */
+function sqlLiteral(value) {
+    if (value === null || value === undefined)
+        return "NULL";
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value === "bigint")
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "1" : "0";
+    if (value instanceof Uint8Array) {
+        const hex = Array.from(value, (b) => b.toString(16).padStart(2, "0")).join("");
+        return `X'${hex}'`;
+    }
+    const str = String(value);
+    return `'${str.replace(/'/g, "''")}'`;
+}
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+export async function dumpConnection(conn, header, opts = {}) {
+    const by = opts.generatedBy ?? "Keel";
+    const lines = [
+        `-- ${header}`,
+        `-- Generated by ${by} at ${new Date().toISOString()}`,
+        "PRAGMA foreign_keys=OFF;",
+        "BEGIN TRANSACTION;",
+        "",
+    ];
+    const objects = await conn.select("SELECT type, name, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' AND sql IS NOT NULL ORDER BY CASE type WHEN 'table' THEN 0 WHEN 'index' THEN 1 ELSE 2 END, name", []);
+    const tables = objects.filter((o) => o.type === "table" && typeof o.name === "string");
+    for (const table of tables) {
+        const name = String(table.name);
+        if (table.sql) {
+            lines.push(`DROP TABLE IF EXISTS ${quoteIdent(name)};`);
+            lines.push(`${String(table.sql)};`);
+            lines.push("");
+        }
+        const rows = await conn.select(`SELECT * FROM ${quoteIdent(name)}`, []);
+        if (rows.length === 0)
+            continue;
+        const columns = Object.keys(rows[0]);
+        for (const row of rows) {
+            const values = columns.map((col) => sqlLiteral(row[col]));
+            lines.push(`INSERT INTO ${quoteIdent(name)} (${columns.map(quoteIdent).join(", ")}) VALUES (${values.join(", ")});`);
+        }
+        lines.push("");
+    }
+    const indexes = objects.filter((o) => o.type === "index" && o.sql);
+    for (const index of indexes) {
+        lines.push(`${String(index.sql)};`);
+    }
+    lines.push("COMMIT;");
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/hosting/hostname.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hostname helpers for custom domains / Workers Custom Domains.
+ */
+export declare function normalizeHostname(raw: string): string;
+export declare function isValidHostname(hostname: string): boolean;
+/** Zone name candidates from most specific to apex (e.g. app.ex.com → app.ex.com, ex.com). */
+export declare function zoneCandidates(hostname: string): string[];

package/dist/hosting/hostname.js

@@ -0,0 +1,25 @@
+/**
+ * Hostname helpers for custom domains / Workers Custom Domains.
+ */
+const HOSTNAME_RE = /^(?=.{1,253}$)(?!-)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.(?!-)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+export function normalizeHostname(raw) {
+    return raw.trim().toLowerCase().replace(/\.$/, "").replace(/^https?:\/\//, "").split("/")[0];
+}
+export function isValidHostname(hostname) {
+    if (!HOSTNAME_RE.test(hostname))
+        return false;
+    if (hostname.includes(".."))
+        return false;
+    return true;
+}
+/** Zone name candidates from most specific to apex (e.g. app.ex.com → app.ex.com, ex.com). */
+export function zoneCandidates(hostname) {
+    const parts = hostname.split(".").filter(Boolean);
+    if (parts.length < 2)
+        return [];
+    const out = [];
+    for (let i = 0; i <= parts.length - 2; i++) {
+        out.push(parts.slice(i).join("."));
+    }
+    return out;
+}

package/dist/hosting/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Keel Hosting — Cloudflare client, hostname helpers, SQL dump, secrets vault.
+ *
+ *   import { CloudflareClient, dumpConnection, normalizeHostname } from "@shaferllc/keel/hosting";
+ *
+ * This is infrastructure for hosted Workers/D1 apps — not a full control plane.
+ * Product orchestration (sites, plans, deploy loops) stays in the app.
+ */
+export { CloudflareClient, cloudflareConfigured, } from "./cloudflare.js";
+export type { CloudflareCredentials, WorkerDomain } from "./cloudflare.js";
+export { normalizeHostname, isValidHostname, zoneCandidates } from "./hostname.js";
+export { dumpConnection } from "./dump.js";
+export { normalizeSecretKey, encryptSecretValue, decryptSecretValue, resolveSecretRows, } from "./secrets.js";
+export type { SecretRow } from "./secrets.js";

package/dist/hosting/index.js

@@ -0,0 +1,12 @@
+/**
+ * Keel Hosting — Cloudflare client, hostname helpers, SQL dump, secrets vault.
+ *
+ *   import { CloudflareClient, dumpConnection, normalizeHostname } from "@shaferllc/keel/hosting";
+ *
+ * This is infrastructure for hosted Workers/D1 apps — not a full control plane.
+ * Product orchestration (sites, plans, deploy loops) stays in the app.
+ */
+export { CloudflareClient, cloudflareConfigured, } from "./cloudflare.js";
+export { normalizeHostname, isValidHostname, zoneCandidates } from "./hostname.js";
+export { dumpConnection } from "./dump.js";
+export { normalizeSecretKey, encryptSecretValue, decryptSecretValue, resolveSecretRows, } from "./secrets.js";

package/dist/hosting/secrets.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Encrypted key/value secrets vault — purpose-scoped encryption via Keel core.
+ *
+ * Apps supply a table of rows with `owner_id`, `key`, `value_encrypted`.
+ * This helper doesn't own the model; it encrypts/decrypts values.
+ */
+export type SecretRow = {
+    key: string;
+    value_encrypted: string;
+};
+export declare function normalizeSecretKey(key: string): string;
+export declare function encryptSecretValue(value: string, purpose?: string): Promise<string>;
+export declare function decryptSecretValue(payload: string, purpose?: string): Promise<string | null>;
+/** Decrypt a list of encrypted rows into a plain key→value map. */
+export declare function resolveSecretRows(rows: SecretRow[], purpose?: string): Promise<Record<string, string>>;

package/dist/hosting/secrets.js

@@ -0,0 +1,27 @@
+/**
+ * Encrypted key/value secrets vault — purpose-scoped encryption via Keel core.
+ *
+ * Apps supply a table of rows with `owner_id`, `key`, `value_encrypted`.
+ * This helper doesn't own the model; it encrypts/decrypts values.
+ */
+import { encryption } from "../core/crypto.js";
+export function normalizeSecretKey(key) {
+    return key.trim().toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+}
+export async function encryptSecretValue(value, purpose = "app-secret") {
+    return encryption.encrypt(value, { purpose });
+}
+export async function decryptSecretValue(payload, purpose = "app-secret") {
+    const value = await encryption.decrypt(payload, { purpose });
+    return typeof value === "string" ? value : null;
+}
+/** Decrypt a list of encrypted rows into a plain key→value map. */
+export async function resolveSecretRows(rows, purpose = "app-secret") {
+    const out = {};
+    for (const row of rows) {
+        const value = await decryptSecretValue(row.value_encrypted, purpose);
+        if (value !== null)
+            out[row.key] = value;
+    }
+    return out;
+}

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.1",
+  "version": "0.83.3",
   "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",
@@ -52,7 +52,7 @@
       "title": "Billing",
       "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",
@@ -159,6 +159,13 @@
       "path": "docs/factories.md",
       "example": "docs/examples/factories.ts"
     },
+    {
+      "slug": "gates",
+      "title": "Gates",
+      "summary": "Keel Gates is a signup gate for private alpha / waitlist apps: an email allowlist, invite codes with use limits and expiry, and a single check that answers \"may this person register?\".",
+      "path": "docs/gates.md",
+      "example": "docs/examples/gates.ts"
+    },
     {
       "slug": "getting-started",
       "title": "Getting Started",
@@ -192,7 +199,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 +276,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 +311,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 +360,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 +374,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 +463,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

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