@shaferllc/keel 0.83.1 → 0.83.3

package/docs/gates.md

@@ -0,0 +1,75 @@
+# Gates
+
+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?". It ships as `@shaferllc/keel/gates`.
+
+This is **not** authorization (`can` / policies in [authorization](./authorization.md))
+and **not** team invitations ([teams](./teams.md)). Those answer different
+questions. Gates answers only: *is this email allowed to create an account?*
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { GatesServiceProvider } from "@shaferllc/keel/gates";
+
+export const providers = [AppServiceProvider, GatesServiceProvider];
+```
+
+Then migrate — the provider contributes `invite_codes` and `email_allowlist`
+tables (`CREATE TABLE IF NOT EXISTS`, so existing apps stay safe):
+
+```bash
+keel migrate
+```
+
+## Checking registration
+
+```ts
+import { canRegister, redeemInvite } from "@shaferllc/keel/gates";
+
+const gate = await canRegister(email, inviteCode);
+if (!gate.ok) {
+  return json({ error: gate.reason }, 403);
+}
+
+// …create the user…
+
+if (gate.via === "code" && gate.invite) {
+  await redeemInvite(gate.invite); // increments uses
+}
+```
+
+`canRegister` returns:
+
+| Result | Meaning |
+|--------|---------|
+| `{ ok: true, via: "allowlist" }` | Email is on `email_allowlist` |
+| `{ ok: true, via: "code", invite }` | Valid invite code (not expired, uses left) |
+| `{ ok: false, reason }` | Rejected — show `reason` to the user |
+
+Allowlist wins over codes: if the email is allowlisted, the code is ignored.
+
+## Managing codes and allowlist
+
+The models are ordinary Keel models — create rows from an admin UI or a seeder:
+
+```ts
+import { InviteCode, EmailAllowlist } from "@shaferllc/keel/gates";
+
+await InviteCode.create({
+  code: "ALPHA-42",
+  max_uses: 10,
+  uses: 0,
+  expires_at: null,
+});
+
+await EmailAllowlist.create({ email: "ada@example.com" });
+```
+
+## Related
+
+- [Accounts](./accounts.md) — register / login flows that call `canRegister` first
+- [Teams](./teams.md) — invitations *into* a team, after the user already exists
+- [Authorization](./authorization.md) — ability checks once they're signed in

package/docs/orm.md

@@ -55,3 +55,42 @@ The ORM is deliberately small — enough for CRUD, relationships, and the common
 query shapes without an ORM dependency. For a gnarly one-off report, reach for
 the [query builder](./query-builder.md) or a raw `connection().select(sql)`; the
 model layer never gets in the way.
+
+## A worked example
+
+A blog with authors and posts — enough to see CRUD, a relation, and eager loading
+together:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "body"];
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+
+  author() { return this.belongsTo(User); }
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() { return this.hasMany(Post); }
+}
+
+const ada = await User.create({ email: "ada@example.com" });
+await ada.posts().create({ title: "Notes on engines", body: "…" });
+
+const withPosts = await User.with("posts").where("id", ada.id).first();
+for (const post of (withPosts as User & { posts: Post[] }).posts) {
+  console.log(post.title);
+}
+```
+
+For the full surface — casts, soft deletes, scopes, polymorphic relations —
+see [Models](./models.md).
+

package/docs/starter-kits.md

@@ -14,6 +14,20 @@ to finish.
 | `app` *(default)* | Full-stack: views, sessions, register/login, password reset, two-factor. |
 | `saas` | `app` plus teams, roles, invitations, billing, and multi-tenancy. |
 
+## Pick a kit
+
+```bash
+npm create keeljs@latest my-app                 # app (default)
+npm create keeljs@latest my-api  -- --preset api
+npm create keeljs@latest my-saas -- --preset saas
+npm create keeljs@latest bare    -- --preset minimal
+cd my-app && npm install && npm run dev
+```
+
+Then open `http://localhost:3000`. The SaaS kit already has a team switcher,
+invites, and a billing stub wired through [teams](./teams.md) and
+[billing](./billing.md) — start by editing `app/Models` and `routes/web.ts`.
+
 ## Every database, Cloudflare first
 
 Each kit ships with all four drivers wired. Switching is `DB_CONNECTION` and nothing

package/docs/watch.md

@@ -1,6 +1,6 @@
 # Watch
 
-Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+Keel Watch is a debug dashboard for Keel apps. It records the requests,
 queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
 scheduled tasks flowing through your app, and shows them in a single-page UI at
 `/watch`, with every request linked to the queries and logs it produced.

package/llms-full.txt

@@ -5764,6 +5764,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 |
@@ -7611,6 +7651,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
@@ -9361,6 +9429,88 @@ definition function.
 
 
 
+---
+
+<!-- source: docs/gates.md -->
+
+# Gates
+
+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?". It ships as `@shaferllc/keel/gates`.
+
+This is **not** authorization (`can` / policies in [authorization](./authorization.md))
+and **not** team invitations ([teams](./teams.md)). Those answer different
+questions. Gates answers only: *is this email allowed to create an account?*
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { GatesServiceProvider } from "@shaferllc/keel/gates";
+
+export const providers = [AppServiceProvider, GatesServiceProvider];
+```
+
+Then migrate — the provider contributes `invite_codes` and `email_allowlist`
+tables (`CREATE TABLE IF NOT EXISTS`, so existing apps stay safe):
+
+```bash
+keel migrate
+```
+
+## Checking registration
+
+```ts
+import { canRegister, redeemInvite } from "@shaferllc/keel/gates";
+
+const gate = await canRegister(email, inviteCode);
+if (!gate.ok) {
+  return json({ error: gate.reason }, 403);
+}
+
+// …create the user…
+
+if (gate.via === "code" && gate.invite) {
+  await redeemInvite(gate.invite); // increments uses
+}
+```
+
+`canRegister` returns:
+
+| Result | Meaning |
+|--------|---------|
+| `{ ok: true, via: "allowlist" }` | Email is on `email_allowlist` |
+| `{ ok: true, via: "code", invite }` | Valid invite code (not expired, uses left) |
+| `{ ok: false, reason }` | Rejected — show `reason` to the user |
+
+Allowlist wins over codes: if the email is allowlisted, the code is ignored.
+
+## Managing codes and allowlist
+
+The models are ordinary Keel models — create rows from an admin UI or a seeder:
+
+```ts
+import { InviteCode, EmailAllowlist } from "@shaferllc/keel/gates";
+
+await InviteCode.create({
+  code: "ALPHA-42",
+  max_uses: 10,
+  uses: 0,
+  expires_at: null,
+});
+
+await EmailAllowlist.create({ email: "ada@example.com" });
+```
+
+## Related
+
+- [Accounts](./accounts.md) — register / login flows that call `canRegister` first
+- [Teams](./teams.md) — invitations *into* a team, after the user already exists
+- [Authorization](./authorization.md) — ability checks once they're signed in
+
+
+
 ---
 
 <!-- source: docs/hashing.md -->
@@ -14934,6 +15084,44 @@ query shapes without an ORM dependency. For a gnarly one-off report, reach for
 the [query builder](./query-builder.md) or a raw `connection().select(sql)`; the
 model layer never gets in the way.
 
+## A worked example
+
+A blog with authors and posts — enough to see CRUD, a relation, and eager loading
+together:
+
+```ts
+import { Model } from "@shaferllc/keel/core";
+
+class Post extends Model {
+  static table = "posts";
+  static fillable = ["title", "body"];
+  declare id: number;
+  declare title: string;
+  declare user_id: number;
+
+  author() { return this.belongsTo(User); }
+}
+
+class User extends Model {
+  static table = "users";
+  declare id: number;
+  declare email: string;
+
+  posts() { return this.hasMany(Post); }
+}
+
+const ada = await User.create({ email: "ada@example.com" });
+await ada.posts().create({ title: "Notes on engines", body: "…" });
+
+const withPosts = await User.with("posts").where("id", ada.id).first();
+for (const post of (withPosts as User & { posts: Post[] }).posts) {
+  console.log(post.title);
+}
+```
+
+For the full surface — casts, soft deletes, scopes, polymorphic relations —
+see [Models](./models.md).
+
 
 
 ---
@@ -17630,6 +17818,20 @@ to finish.
 | `app` *(default)* | Full-stack: views, sessions, register/login, password reset, two-factor. |
 | `saas` | `app` plus teams, roles, invitations, billing, and multi-tenancy. |
 
+## Pick a kit
+
+```bash
+npm create keeljs@latest my-app                 # app (default)
+npm create keeljs@latest my-api  -- --preset api
+npm create keeljs@latest my-saas -- --preset saas
+npm create keeljs@latest bare    -- --preset minimal
+cd my-app && npm install && npm run dev
+```
+
+Then open `http://localhost:3000`. The SaaS kit already has a team switcher,
+invites, and a billing stub wired through [teams](./teams.md) and
+[billing](./billing.md) — start by editing `app/Models` and `routes/web.ts`.
+
 ## Every database, Cloudflare first
 
 Each kit ships with all four drivers wired. Switching is `DB_CONNECTION` and nothing
@@ -21244,7 +21446,7 @@ Vite's `manifest.json`, as produced by the build. You rarely touch it directly
 
 # Watch
 
-Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+Keel Watch is a debug dashboard for Keel apps. It records the requests,
 queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
 scheduled tasks flowing through your app, and shows them in a single-page UI at
 `/watch`, with every request linked to the queries and logs it produced.

package/llms.txt

@@ -30,6 +30,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Errors & Exceptions](https://github.com/shaferllc/keel/blob/main/docs/errors.md): Throw an exception anywhere — a handler, middleware, or a service deep in the container — and Keel's HTTP kernel turns it into the right response.
 - [Events](https://github.com/shaferllc/keel/blob/main/docs/events.md): A tiny event emitter for decoupling — fire an event in one place, handle it in another.
 - [Factories & Seeders](https://github.com/shaferllc/keel/blob/main/docs/factories.md): Populate the database with realistic fixtures for tests and demos.
+- [Gates](https://github.com/shaferllc/keel/blob/main/docs/gates.md): 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?".
 - [Getting Started](https://github.com/shaferllc/keel/blob/main/docs/getting-started.md): Keel is a house framework for Node.js — a small, legible MVC layer over Hono.
 - [Hashing & Encryption](https://github.com/shaferllc/keel/blob/main/docs/hashing.md): Password hashing and value encryption, both built on the Web Crypto API — so they run identically on Node and the edge, with no native bindings (no bcrypt to compile).
 - [Health Checks](https://github.com/shaferllc/keel/blob/main/docs/health.md): Two endpoints, answering the two questions an orchestrator — Kubernetes, Fly, Railway, a load balancer — actually asks:
@@ -72,7 +73,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 - [Validation](https://github.com/shaferllc/keel/blob/main/docs/validation.md): validate() parses request input against a schema and returns typed data.
 - [Views](https://github.com/shaferllc/keel/blob/main/docs/views.md): Keel renders HTML with Hono JSX — type-safe components that run identically on Node and on Cloudflare Workers (no filesystem templating, so it ports anywhere).
 - [Vite](https://github.com/shaferllc/keel/blob/main/docs/vite.md): Wire a modern frontend build — bundling, hashed filenames, hot module reload — to Keel's server-rendered HTML, the way modern full-stack frameworks do.
-- [Watch](https://github.com/shaferllc/keel/blob/main/docs/watch.md): Keel Watch is a debug dashboard — a Telescope for Keel.
+- [Watch](https://github.com/shaferllc/keel/blob/main/docs/watch.md): Keel Watch is a debug dashboard for Keel apps.
 
 ## Examples
 
@@ -82,6 +83,7 @@ Every topic has a runnable, type-checked example:
 - [API Resources example](https://github.com/shaferllc/keel/blob/main/docs/examples/api-resources.ts)
 - [Authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/authentication.ts)
 - [Authorization example](https://github.com/shaferllc/keel/blob/main/docs/examples/authorization.ts)
+- [Billing example](https://github.com/shaferllc/keel/blob/main/docs/examples/billing.ts)
 - [Broadcasting example](https://github.com/shaferllc/keel/blob/main/docs/examples/broadcasting.ts)
 - [Service Broker example](https://github.com/shaferllc/keel/blob/main/docs/examples/broker.ts)
 - [Cache example](https://github.com/shaferllc/keel/blob/main/docs/examples/cache.ts)
@@ -89,15 +91,18 @@ Every topic has a runnable, type-checked example:
 - [The Console example](https://github.com/shaferllc/keel/blob/main/docs/examples/console.ts)
 - [The Service Container example](https://github.com/shaferllc/keel/blob/main/docs/examples/container.ts)
 - [Controllers example](https://github.com/shaferllc/keel/blob/main/docs/examples/controllers.ts)
+- [CORS example](https://github.com/shaferllc/keel/blob/main/docs/examples/cors.ts)
 - [Database example](https://github.com/shaferllc/keel/blob/main/docs/examples/database.ts)
 - [Debugging example](https://github.com/shaferllc/keel/blob/main/docs/examples/debugging.ts)
 - [Request Decorators example](https://github.com/shaferllc/keel/blob/main/docs/examples/decorators.ts)
 - [Errors & Exceptions example](https://github.com/shaferllc/keel/blob/main/docs/examples/errors.ts)
 - [Events example](https://github.com/shaferllc/keel/blob/main/docs/examples/events.ts)
 - [Factories & Seeders example](https://github.com/shaferllc/keel/blob/main/docs/examples/factories.ts)
+- [Gates example](https://github.com/shaferllc/keel/blob/main/docs/examples/gates.ts)
 - [Hashing & Encryption example](https://github.com/shaferllc/keel/blob/main/docs/examples/hashing.ts)
 - [Health Checks example](https://github.com/shaferllc/keel/blob/main/docs/examples/health.ts)
 - [Helpers example](https://github.com/shaferllc/keel/blob/main/docs/examples/helpers.ts)
+- [Built on Hono example](https://github.com/shaferllc/keel/blob/main/docs/examples/hono.ts)
 - [Lifecycle Hooks example](https://github.com/shaferllc/keel/blob/main/docs/examples/hooks.ts)
 - [Internationalization example](https://github.com/shaferllc/keel/blob/main/docs/examples/i18n.ts)
 - [Inertia example](https://github.com/shaferllc/keel/blob/main/docs/examples/inertia.ts)
@@ -108,15 +113,22 @@ Every topic has a runnable, type-checked example:
 - [Migrations example](https://github.com/shaferllc/keel/blob/main/docs/examples/migrations.ts)
 - [Models example](https://github.com/shaferllc/keel/blob/main/docs/examples/models.ts)
 - [Notifications example](https://github.com/shaferllc/keel/blob/main/docs/examples/notification.ts)
+- [OpenAPI example](https://github.com/shaferllc/keel/blob/main/docs/examples/openapi.ts)
+- [ORM example](https://github.com/shaferllc/keel/blob/main/docs/examples/orm.ts)
+- [Packages example](https://github.com/shaferllc/keel/blob/main/docs/examples/packages.ts)
 - [Pages example](https://github.com/shaferllc/keel/blob/main/docs/examples/pages.ts)
 - [Service Providers example](https://github.com/shaferllc/keel/blob/main/docs/examples/providers.ts)
+- [Query Builder example](https://github.com/shaferllc/keel/blob/main/docs/examples/query-builder.ts)
 - [Queues & Jobs example](https://github.com/shaferllc/keel/blob/main/docs/examples/queues.ts)
 - [Rate Limiting example](https://github.com/shaferllc/keel/blob/main/docs/examples/rate-limiting.ts)
 - [Redis example](https://github.com/shaferllc/keel/blob/main/docs/examples/redis.ts)
 - [Request & Response example](https://github.com/shaferllc/keel/blob/main/docs/examples/request-response.ts)
 - [Routing example](https://github.com/shaferllc/keel/blob/main/docs/examples/routing.ts)
 - [Task Scheduling example](https://github.com/shaferllc/keel/blob/main/docs/examples/scheduling.ts)
+- [Securing SSR apps example](https://github.com/shaferllc/keel/blob/main/docs/examples/security.ts)
 - [Sessions example](https://github.com/shaferllc/keel/blob/main/docs/examples/sessions.ts)
+- [Social authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/social-auth.ts)
+- [Starter kits example](https://github.com/shaferllc/keel/blob/main/docs/examples/starter-kits.ts)
 - [Static Files example](https://github.com/shaferllc/keel/blob/main/docs/examples/static-files.ts)
 - [Storage example](https://github.com/shaferllc/keel/blob/main/docs/examples/storage.ts)
 - [Teams example](https://github.com/shaferllc/keel/blob/main/docs/examples/teams.ts)
@@ -128,6 +140,7 @@ Every topic has a runnable, type-checked example:
 - [Validation example](https://github.com/shaferllc/keel/blob/main/docs/examples/validation.ts)
 - [Views example](https://github.com/shaferllc/keel/blob/main/docs/examples/views.tsx)
 - [Vite example](https://github.com/shaferllc/keel/blob/main/docs/examples/vite.ts)
+- [Watch example](https://github.com/shaferllc/keel/blob/main/docs/examples/watch.ts)
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.83.1",
+  "version": "0.83.3",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -77,6 +77,14 @@
       "types": "./dist/billing/index.d.ts",
       "import": "./dist/billing/index.js"
     },
+    "./gates": {
+      "types": "./dist/gates/index.d.ts",
+      "import": "./dist/gates/index.js"
+    },
+    "./hosting": {
+      "types": "./dist/hosting/index.d.ts",
+      "import": "./dist/hosting/index.js"
+    },
     "./cli": {
       "types": "./dist/core/cli/index.d.ts",
       "import": "./dist/core/cli/index.js"