@shaferllc/keel 0.83.1 → 0.83.3

package/docs/changelog.md

@@ -4,6 +4,37 @@ All notable changes to Keel are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
 adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.83.3] — 2026-07-12
+
+### Added
+
+- **`@shaferllc/keel/gates`** — signup gating for private alpha / waitlist:
+  email allowlist + invite codes (`canRegister` / `redeemInvite`), shipped as a
+  package with a migration. Used by Keel Cloud; not the same as team invitations
+  or authorization gates.
+- **`@shaferllc/keel/hosting`** — Cloudflare client, hostname helpers, SQL dump,
+  and secrets encryption helpers for hosted Workers/D1 apps.
+
+[0.83.3]: https://github.com/shaferllc/keel/releases/tag/v0.83.3
+
+## [0.83.2] — 2026-07-12
+
+### Added
+
+- **More runnable doc examples.** Billing, ORM, query builder, CORS, security,
+  social auth, OpenAPI, Watch, packages, Hono, and starter kits now have
+  typechecked harnesses under `docs/examples/` — the same ones
+  `npm run typecheck:docs` compiles against the published surface.
+- **Worked examples in the guides** — a complete billing subscribe flow (with
+  `FakeGateway`), an ORM CRUD+eager-load walkthrough, a production CORS recipe,
+  and a clearer starter-kit picker.
+
+### Changed
+
+- Watch no longer describes itself by another product's name.
+
+[0.83.2]: https://github.com/shaferllc/keel/releases/tag/v0.83.2
+
 ## [0.83.0] — 2026-07-12
 
 ### Added

package/docs/cors.md

@@ -21,6 +21,34 @@ router.group(() => { /* … */ }).use(cors({ origin: ["https://app.example.com"]
 With no options, `cors()` reflects the caller's origin — convenient in
 development. **Lock it down in production** with an explicit allowlist.
 
+## A production API group
+
+Typical setup for a JSON API served from `api.example.com` and called from a
+SPA on `app.example.com`:
+
+```ts
+// app/Http/Kernel.ts
+import { cors } from "@shaferllc/keel/core";
+
+this.use(
+  cors({
+    origin: ["https://app.example.com"],
+    credentials: true,          // cookies / Authorization
+    exposeHeaders: ["X-Request-Id"],
+  }),
+);
+```
+
+During local development, allow any localhost port with a predicate:
+
+```ts
+cors({
+  origin: (origin) =>
+    origin.startsWith("http://localhost:") || origin === "https://app.example.com",
+  credentials: true,
+});
+```
+
 ## Options
 
 ```ts

package/docs/examples/billing.ts

@@ -0,0 +1,128 @@
+// Type-check harness for docs/billing.md. Compile-only — never executed.
+import { Model, listen } from "@shaferllc/keel/core";
+import {
+  Billable,
+  BillingServiceProvider,
+  BillingManager,
+  FakeGateway,
+  setBilling,
+  resolveBillableUsing,
+  type CheckoutSession,
+  type GatewayCharge,
+} from "@shaferllc/keel/billing";
+
+export class User extends Billable(Model) {
+  static override table = "users";
+  declare id: number;
+  declare email: string;
+  declare name: string;
+}
+
+declare const user: User;
+declare const paymentMethodId: string;
+declare const successUrl: string;
+declare const cancelUrl: string;
+
+export const providers = [BillingServiceProvider];
+
+/* -------------------------------- customers ------------------------------- */
+
+export async function customers() {
+  await user.createAsCustomer();
+  user.hasBillingId();
+  await user.getCustomerId();
+}
+
+/* ------------------------------ subscriptions ----------------------------- */
+
+export async function subscribe() {
+  await user
+    .newSubscription("default", "price_pro")
+    .trialDays(14)
+    .quantity(3)
+    .create(paymentMethodId);
+
+  const session: CheckoutSession = await user
+    .newSubscription("default", "price_pro")
+    .checkout({ successUrl, cancelUrl });
+  return session;
+}
+
+export async function status() {
+  await user.subscribed();
+  await user.subscribedToPrice("price_pro");
+  await user.onTrial();
+  const sub = await user.subscription();
+  if (!sub) return;
+
+  sub.active();
+  sub.onTrial();
+  sub.recurring();
+  sub.canceled();
+  sub.onGracePeriod();
+  sub.ended();
+  sub.paused();
+  sub.valid();
+  sub.hasIncompletePayment();
+
+  await sub.swap("price_enterprise");
+  await sub.updateQuantity(10);
+  await sub.incrementQuantity(2);
+  await sub.decrementQuantity();
+  await sub.cancel();
+  await sub.resume();
+  await sub.cancelNow();
+  await sub.endTrial();
+  await sub.extendTrial(new Date("2026-01-01"));
+}
+
+/* -------------------------------- charges --------------------------------- */
+
+export async function charges() {
+  const charge: GatewayCharge = await user.charge(2000, {
+    paymentMethod: "pm_1",
+    description: "Credits",
+  });
+  await user.refund(charge.id);
+  await user.refund(charge.id, 500);
+  await user.checkout("price_onetime", { successUrl, cancelUrl });
+  await user.createSetupIntent();
+  await user.paymentMethods();
+  await user.invoices();
+}
+
+/* -------------------------------- webhooks -------------------------------- */
+
+export function webhooks() {
+  listen("billing.subscription.updated", (e) => {
+    void e.gateway;
+    void e.subscriptionId;
+  });
+  listen("billing.webhook.received", (e) => {
+    void e.gateway;
+    void e.type;
+  });
+  resolveBillableUsing(async (customerId, _gateway) => {
+    return { id: user.id, type: "User" };
+  });
+}
+
+/* --------------------------------- testing -------------------------------- */
+
+export function fakeGateway() {
+  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);
+  return fake;
+}

package/docs/examples/cors.ts

@@ -0,0 +1,29 @@
+// Type-check harness for docs/cors.md. Compile-only — never executed.
+import type { MiddlewareHandler } from "hono";
+import { cors, type CorsOptions } from "@shaferllc/keel/core";
+
+export function kernel(): MiddlewareHandler {
+  return cors();
+}
+
+export function apiGroup(): MiddlewareHandler {
+  return cors({ origin: ["https://app.example.com"] });
+}
+
+export function production(): MiddlewareHandler {
+  const options: CorsOptions = {
+    origin: ["https://app.example.com"],
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+    headers: true,
+    exposeHeaders: ["X-Request-Id"],
+    credentials: true,
+    maxAge: 86400,
+  };
+  return cors(options);
+}
+
+export function dynamicOrigin(): MiddlewareHandler {
+  return cors({
+    origin: (origin) => origin.endsWith(".example.com") || origin.startsWith("http://localhost"),
+  });
+}

package/docs/examples/gates.ts

@@ -0,0 +1,30 @@
+// Type-check harness for docs/gates.md. Compile-only — never executed.
+import { Application, json } from "@shaferllc/keel/core";
+import {
+  GatesServiceProvider,
+  InviteCode,
+  EmailAllowlist,
+  canRegister,
+  redeemInvite,
+} from "@shaferllc/keel/gates";
+
+export function install() {
+  const app = new Application();
+  app.register(GatesServiceProvider);
+  return app;
+}
+
+export async function register(email: string, inviteCode?: string) {
+  const gate = await canRegister(email, inviteCode);
+  if (!gate.ok) return json({ error: gate.reason }, 403);
+
+  if (gate.via === "code" && gate.invite) {
+    await redeemInvite(gate.invite);
+  }
+  return json({ ok: true, via: gate.via });
+}
+
+export async function seed() {
+  await InviteCode.create({ code: "ALPHA-42", max_uses: 10, uses: 0, expires_at: null });
+  await EmailAllowlist.create({ email: "ada@example.com" });
+}

package/docs/examples/hono.ts

@@ -0,0 +1,29 @@
+// Type-check harness for docs/hono.md. Compile-only — never executed.
+import type { Ctx } from "@shaferllc/keel/core";
+import { Router, json } from "@shaferllc/keel/core";
+
+export function withContext(router: Router) {
+  router.get("/users/:id", async (c: Ctx) => {
+    const id = c.req.param("id");
+    const q = c.req.query("q");
+    const auth = c.req.header("authorization");
+    void q;
+    void auth;
+    return c.json({ id });
+  });
+
+  router.get("/ping", (c) => c.text("pong"));
+  router.get("/go", (c) => c.redirect("/"));
+}
+
+export function ambientHelpers() {
+  return json({ ok: true });
+}
+
+export function keelContext(c: Ctx) {
+  return {
+    app: c.get("app"),
+    route: c.get("route"),
+    subdomains: c.get("subdomains"),
+  };
+}

package/docs/examples/openapi.ts

@@ -0,0 +1,35 @@
+// Type-check harness for docs/openapi.md. Compile-only — never executed.
+import { z } from "zod";
+import { Application, Router, validateRequest, type Ctx } from "@shaferllc/keel/core";
+import { OpenApiServiceProvider, apiDoc, OpenApi } from "@shaferllc/keel/openapi";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+const UserShape = z.object({ id: z.number(), email: z.string().email() });
+
+class Users {
+  store(_c: Ctx) {
+    return { id: 1, email: "a@b.com" };
+  }
+}
+
+export function install() {
+  const app = new Application();
+  app.register(OpenApiServiceProvider);
+  OpenApi.auth((c) => c.req.header("x-docs-key") === "secret");
+  return app;
+}
+
+export function document(router: Router) {
+  router
+    .post("/users", [Users, "store"])
+    .name("users.store")
+    .config(
+      apiDoc({
+        summary: "Create a user",
+        tags: ["users"],
+        request: { body: NewUser },
+        responses: { 201: { description: "The created user", schema: UserShape } },
+      }),
+    )
+    .middleware([validateRequest({ body: NewUser })]);
+}

package/docs/examples/orm.ts

@@ -0,0 +1,30 @@
+// Type-check harness for docs/orm.md. Compile-only — never executed.
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static override table = "posts";
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+}
+
+export class User extends Model {
+  static override table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() {
+    return this.hasMany(Post);
+  }
+}
+
+export async function map() {
+  const user = await User.find(1);
+  if (!user) return;
+  await user.posts();
+  await User.with("posts").where("email", user.email).first();
+  await User.create({ email: "ada@example.com" });
+  user.email = "grace@example.com";
+  await user.save();
+  await user.delete();
+}

package/docs/examples/packages.ts

@@ -0,0 +1,26 @@
+// Type-check harness for docs/packages.md. Compile-only — never executed.
+import { PackageProvider, type Router, type Migration, type PackageCommand } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+declare const createInvoicesTable: Migration;
+declare const syncInvoicesCommand: PackageCommand;
+declare function registerBillingRoutes(r: Router): void;
+
+export class BillingServiceProvider extends PackageProvider {
+  readonly name = "billing";
+
+  register(): void {
+    this.mergeConfig("billing", { enabled: true, path: "billing" });
+    this.migrations([createInvoicesTable]);
+    this.publishes({ [join(here, "config.stub")]: "config/billing.ts" }, "billing-config");
+    this.commands([syncInvoicesCommand]);
+  }
+
+  boot(): void {
+    this.assets("billing/assets", join(here, "ui/dist"), { maxAge: 3600 });
+    this.routes((r: Router) => registerBillingRoutes(r), { prefix: "billing", as: "billing" });
+  }
+}

package/docs/examples/query-builder.ts

@@ -0,0 +1,118 @@
+// Type-check harness for docs/query-builder.md. Compile-only — never executed.
+import { db, type Row } from "@shaferllc/keel/core";
+
+declare const email: string;
+declare const name: string;
+declare const id: number;
+declare const now: number;
+declare const search: string | undefined;
+declare const includeArchived: boolean;
+declare const key: string;
+declare const value: string;
+
+export async function retrieving() {
+  await db("users").get();
+  await db("users").where("id", 1).first();
+  await db("users").where("id", 1).firstOrFail();
+  await db("users").find(1);
+  await db("users").where("email", email).sole();
+  await db("users").where("id", 1).value("email");
+  await db("posts").pluck("title");
+  await db("tags").orderBy("name").implode("name", ", ");
+
+  await db("users")
+    .orderBy("id")
+    .chunk(500, async (rows) => {
+      for (const _row of rows) {
+        /* process */
+      }
+    });
+}
+
+export async function aggregates() {
+  await db("orders").count();
+  await db("orders").where("paid", true).sum("total");
+  await db("orders").avg("total");
+  await db("orders").min("total");
+  await db("orders").max("total");
+  await db("users").where("email", email).exists();
+  await db("users").where("banned", true).doesntExist();
+}
+
+export async function selectsAndWheres() {
+  db("users").select("id", "email");
+  db("users").select("id").addSelect("email");
+  db("orders").selectRaw("SUM(total) AS revenue");
+  db("users").distinct().select("country");
+
+  db("users").where("votes", 100);
+  db("users").where("votes", ">=", 100);
+  db("users").where("name", "like", "T%");
+  db("users").where("votes", 100).orWhere("name", "John");
+  db("users").whereNot("status", "cancelled");
+  db("users").whereIn("id", [1, 2, 3]).whereNotIn("id", [4]);
+  db("users").whereNull("deleted_at").whereNotNull("email_verified_at");
+  db("products").whereBetween("price", [10, 100]).whereNotBetween("stock", [0, 5]);
+  db("posts").whereLike("title", "%keel%");
+  db("events").whereColumn("updated_at", ">", "created_at");
+  db("users").whereRaw("score >= ? AND score <= ?", [10, 90]);
+
+  await db("users")
+    .where("active", true)
+    .where((q) => q.where("role", "admin").orWhere("role", "owner"))
+    .get();
+}
+
+export async function orderingJoinsWhen() {
+  db("users").orderBy("name").orderByDesc("created_at");
+  db("posts").latest();
+  db("posts").oldest();
+  db("posts").orderByRaw("LENGTH(title) DESC");
+  db("users").inRandomOrder();
+  db("users").reorder("name");
+  db("users").limit(10).offset(20);
+  db("users").take(10).skip(20);
+  db("users").forPage(3, 15);
+
+  await db("orders")
+    .select("user_id")
+    .selectRaw("SUM(total) AS spent")
+    .groupBy("user_id")
+    .having("spent", ">", 1000)
+    .get();
+
+  await db("posts")
+    .join("users", "posts.user_id", "users.id")
+    .leftJoin("images", "images.post_id", "posts.id")
+    .select("posts.title", "users.name")
+    .get();
+
+  await db("users")
+    .when(search, (q, term) => q.whereLike("name", `%${term}%`))
+    .unless(includeArchived, (q) => q.whereNull("archived_at"))
+    .get();
+}
+
+export async function writes() {
+  await db("users").insert({ email, name });
+  await db("users").insertGetId({ email, name });
+  await db("logs").insertOrIgnore({ key, value });
+  await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
+
+  await db("users").where("id", id).update({ name: "Grace" });
+  await db("users").updateOrInsert({ email }, { name });
+  await db("posts").where("id", id).increment("views");
+  await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+  await db("counters").incrementEach({ hits: 1, misses: 2 });
+
+  await db("sessions").where("expires_at", "<", now).delete();
+  await db("cache").truncate();
+}
+
+export async function typed() {
+  type User = { id: number; email: string };
+  const row: User | null = await db<User>("users").where("id", 1).first();
+  const rows: User[] = await db<User>("users").get();
+  const raw: Row[] = await db("users").get();
+  return { row, rows, raw };
+}

package/docs/examples/security.ts

@@ -0,0 +1,31 @@
+// Type-check harness for docs/security.md. Compile-only — never executed.
+import type { MiddlewareHandler } from "hono";
+import {
+  securityHeaders,
+  csrf,
+  csrfField,
+  csrfToken,
+  sessionMiddleware,
+} from "@shaferllc/keel/core";
+
+export function headers(): MiddlewareHandler[] {
+  return [
+    securityHeaders(),
+    securityHeaders({
+      csp: { defaultSrc: ["'self'"], scriptSrc: ["'self'", "https://cdn.example.com"] },
+      hsts: { maxAge: 15552000, includeSubDomains: true },
+      frameGuard: "DENY",
+    }),
+  ];
+}
+
+export function csrfStack(): MiddlewareHandler[] {
+  return [sessionMiddleware(), csrf(), csrf({ except: ["/billing/webhook/*"] })];
+}
+
+export function forms() {
+  return {
+    field: csrfField(),
+    token: csrfToken(),
+  };
+}

package/docs/examples/social-auth.ts

@@ -0,0 +1,76 @@
+// Type-check harness for docs/social-auth.md. Compile-only — never executed.
+import {
+  social,
+  session,
+  redirect,
+  request,
+  auth,
+  ForbiddenException,
+  Model,
+  config,
+} from "@shaferllc/keel/core";
+
+class User extends Model {
+  static override table = "users";
+  declare id: number;
+  declare email: string | null;
+  declare name: string | null;
+  declare github_id: string;
+  declare twitter_id: string;
+}
+
+const github = social.github({
+  clientId: config("services.github.id") as string,
+  clientSecret: config("services.github.secret") as string,
+  redirectUri: "https://app.example.com/auth/github/callback",
+});
+
+const twitter = social.twitter({
+  clientId: config("services.twitter.key") as string,
+  clientSecret: config("services.twitter.secret") as string,
+  redirectUri: "https://app.example.com/auth/twitter/callback",
+});
+
+export function redirectToGithub() {
+  const state = social.state();
+  session().put("oauth_state", state);
+  return redirect(github.redirect({ state }));
+}
+
+export async function githubCallback() {
+  const state = String(request.query("state") ?? "");
+  if (state !== session().pull("oauth_state")) {
+    throw new ForbiddenException("Invalid OAuth state");
+  }
+
+  const code = String(request.query("code") ?? "");
+  const gh = await github.user(code);
+  const existing = await User.query().where("github_id", gh.id).first();
+  const user =
+    existing ??
+    (await User.create({ github_id: gh.id, email: gh.email, name: gh.name }));
+
+  auth().login(user.id as number);
+  return redirect("/dashboard");
+}
+
+export async function twitterFlow() {
+  const requestToken = await twitter.requestToken();
+  session().put("twitter_secret", requestToken.tokenSecret);
+  const toProvider = redirect(twitter.redirect(requestToken));
+
+  const tw = await twitter.user(
+    String(request.query("oauth_token") ?? ""),
+    String(request.query("oauth_verifier") ?? ""),
+    String(session().pull("twitter_secret") ?? ""),
+  );
+  const user = await User.firstOrCreate({ twitter_id: tw.id }, { name: tw.name });
+  auth().login(user.id as number);
+  return { toProvider, user };
+}
+
+export async function tokenReuse() {
+  const code = String(request.query("code") ?? "");
+  const token = await github.exchangeCode(code);
+  return github.userFromToken(token);
+}

package/docs/examples/starter-kits.ts

@@ -0,0 +1,14 @@
+// Type-check harness for docs/starter-kits.md. Compile-only — never executed.
+import { TenantModel } from "@shaferllc/keel/teams";
+
+class Project extends TenantModel {
+  static override table = "projects";
+  declare id: number;
+  declare name: string;
+}
+
+export async function tenantScoped() {
+  await Project.all();
+  await Project.create({ name: "Hi" });
+  await Project.find(1); // null if another team's
+}

package/docs/examples/watch.ts

@@ -0,0 +1,10 @@
+// Type-check harness for docs/watch.md. Compile-only — never executed.
+import { Application } from "@shaferllc/keel/core";
+import { WatchServiceProvider, Watch } from "@shaferllc/keel/watch";
+
+export function install() {
+  const app = new Application();
+  app.register(WatchServiceProvider);
+  Watch.auth((c) => c.req.header("x-watch-key") === "secret");
+  return app;
+}