@shaferllc/keel 0.66.0 → 0.74.0

package/AGENTS.md

@@ -0,0 +1,169 @@
+# AGENTS.md — working in Keel with an AI agent
+
+Guidance for AI coding agents (Claude Code, Cursor, …) editing **Keel** — the
+house framework for Node.js — or an app built on it. Humans: this is also a fast
+orientation. For prose guides see [`docs/`](./docs); for a machine-readable
+surface, run the [MCP server](#mcp-server-recommended).
+
+> **The fastest path:** connect the Keel MCP server (below) and call
+> `keel_overview` first. It returns conventions, the folder map, every doc
+> topic, and the generators. Then `keel_search_docs` / `keel_read_doc` for
+> depth, `keel_search_api` to find exports, `keel_scaffold` to generate code.
+
+---
+
+## What Keel is
+
+A small, legible MVC framework: a real **service container**, **service
+providers**, dot-notation **config**, expressive **routing**, active-record
+**models**, a **queue**, **auth**, and a code-generating **console**.
+[Hono](https://hono.dev) powers HTTP; everything above it is Keel's. The whole
+core is a few hundred lines per file in `src/core/` — read it, nothing is magic.
+
+## The one import rule
+
+Everything userland comes from a single entry point:
+
+```ts
+import { Router, Model, config, ServiceProvider } from "@shaferllc/keel/core";
+```
+
+- **In a consuming app** (the `keel-app` starter, or your own): use
+  `@shaferllc/keel/core`. This is what generated stubs emit.
+- **Inside this framework repo's example app** (`app/`, `routes/`, `bootstrap/`):
+  the code uses the `@keel/core` tsconfig **path alias** that points at
+  `src/core/`. Match the file you're editing — don't "fix" `@keel/core` to the
+  package name inside this repo.
+
+Never deep-import `@shaferllc/keel/core/model.js`. If a symbol isn't exported
+from `/core`, that's intentional. Find exports with `keel_search_api` or read
+`src/core/index.ts`.
+
+## Folder layout of a Keel app
+
+| Path | What lives there |
+|------|------------------|
+| `app/Controllers/` | Controller classes (resolved from the container → DI) |
+| `app/Providers/` | Service providers (`register()` then `boot()`) |
+| `app/Http/Middleware/` | Hono middleware handlers |
+| `app/Http/Kernel.ts` | The HTTP kernel — global middleware, error handling |
+| `app/Models/` | Active-record models extending `Model` |
+| `app/Jobs/`, `app/Notifications/`, `app/Transformers/` | Queue jobs, notifications, API serializers |
+| `config/*.ts` | Config files; read via `config("app.name")` |
+| `routes/web.ts` | Route definitions — default export receives the `Router` |
+| `database/factories/`, `database/seeders/`, `database/migrations/` | Data tooling |
+| `bootstrap/app.ts` | Assembles the `Application`, boots providers, loads routes |
+| `.env` | Environment, loaded into `env(...)` and config |
+
+## Core mental model
+
+1. **Container.** Every service is registered in and resolved out of the
+   container. `bind` (transient), `singleton` (once), `instance` (existing
+   value), `make(Token)` (resolve). Constructor injection: a controller/service
+   with `constructor(private app: Container)` gets it automatically.
+2. **Providers.** `register()` binds things into the container; `boot()` runs
+   after all providers registered, to wire things together. Register providers
+   in `bootstrap/providers.ts`.
+3. **Config.** `config("app.port", 3000)` reads `config/app.ts` merged with
+   `.env`. Dot-notation, with a default.
+4. **Routing.** `router.get("/x", [Controller, "method"])` or a closure. Name
+   routes with `.name()`, group with `.group()`, constrain params with
+   `.where()`, build URLs with `router.url("name", params)`.
+5. **Request context.** Inside a handler, `param()`, `query()`, `body()`,
+   `json()`, `text()` read/write the current request via async-local context —
+   no need to thread `c` everywhere (though the Hono `Ctx` is available).
+
+## How to add things (prefer the generators)
+
+Use `keel_scaffold` (MCP) or the console — both emit the correct stub with the
+right imports and target path. Then wire it up.
+
+| Goal | Command | Then |
+|------|---------|------|
+| Controller | `keel make:controller Post` (`-r` for REST) | add a route in `routes/web.ts` |
+| Provider | `keel make:provider Billing` | register in `bootstrap/providers.ts` |
+| Middleware | `keel make:middleware Auth` | attach in `app/Http/Kernel.ts` or per-route |
+| Model | *(no generator — extend `Model`)* | set `static table`; add relations |
+| Factory | `keel make:factory User` | reference the model |
+| Seeder | `keel make:seeder Database` | call factories in `run()` |
+| Job | `keel make:job SendWelcome` | `dispatch(new SendWelcomeJob())` |
+| Notification | `keel make:notification Paid` | `notify(user, new PaidNotification())` |
+| Transformer | `keel make:transformer User` | return it from a controller |
+| Package | `keel make:package billing` | a `PackageProvider` — see [`docs/packages.md`](./docs/packages.md) |
+
+**Scaffolding does not write files** via MCP — it returns code + path; you write
+it. The console (`keel make:*`) does write, and refuses to overwrite.
+
+A minimal controller and route:
+
+```ts
+// app/Controllers/PostController.ts
+import type { Ctx } from "@shaferllc/keel/core";
+export class PostController {
+  index(c: Ctx) { return c.json({ ok: true }); }
+}
+
+// routes/web.ts
+router.get("/posts", [PostController, "index"]).name("posts.index");
+```
+
+## Commands
+
+```bash
+npm run dev            # example app on http://localhost:3000 (tsx watch)
+npm run serve          # keel serve
+npm run keel -- routes # list registered routes
+npm run keel -- migrate # run pending app + package migrations (also migrate:status, migrate:rollback)
+npm run keel -- make:controller Foo
+npm run mcp            # start the MCP server over stdio (dev)
+npm test               # node --test over tests/*.test.ts
+npm run typecheck      # tsc --noEmit — run before you finish
+npm run build          # regenerate AI artifacts + compile to dist/
+npm run build:ai       # regenerate llms.txt, llms-full.txt, docs/ai-manifest.json
+```
+
+## Conventions & guardrails
+
+- **TypeScript, strict, ESM.** `.js` extensions in relative imports (NodeNext).
+  No default exports except where the pattern already uses them (routes).
+- **Match the surrounding file** — comment density, naming, idioms. Keel prizes
+  legibility; write code that reads like `src/core/`.
+- **Test with the real thing.** `TestClient`/`testClient` drives the HTTP stack
+  in-process; `hash.fake()`, `fakeDisk()`, `ArrayTransport`, `MemoryDriver`, and
+  `EventBuffer` make side-effecting subsystems deterministic. See
+  [`docs/testing.md`](./docs/testing.md).
+- **Run `npm run typecheck` before finishing.** The whole framework is typed end
+  to end; a green `tsc` is the bar.
+- **After editing docs or the export surface, run `npm run build:ai`** so
+  `llms.txt`, `llms-full.txt`, and `docs/ai-manifest.json` stay in sync (the MCP
+  server reads the manifest).
+
+## MCP server (recommended)
+
+Keel ships an MCP server exposing its docs, the full public API surface, the
+generators, and framework conventions to any MCP-capable agent.
+
+**Claude Code:**
+```bash
+claude mcp add keel -- npx -y keel-mcp        # in an app that depends on @shaferllc/keel
+```
+Or, hacking on the framework itself:
+```bash
+claude mcp add keel -- npm --prefix /path/to/keel run mcp
+```
+
+**`.mcp.json` / Cursor / other clients:**
+```json
+{ "mcpServers": { "keel": { "command": "npx", "args": ["-y", "keel-mcp"] } } }
+```
+
+Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
+`keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
+`keel://llms-full`, `keel://docs/<slug>`. See [`docs/ai.md`](./docs/ai.md).
+
+## Where to read next
+
+- [`docs/getting-started.md`](./docs/getting-started.md) — a guided first hour
+- [`docs/architecture.md`](./docs/architecture.md) — a request from socket to response
+- [`docs/container.md`](./docs/container.md) — the DI core everything rests on
+- [`llms-full.txt`](./llms-full.txt) — every guide in one file, for a fresh context

package/README.md

@@ -108,11 +108,41 @@ npm run keel serve --port 8080      # start the server on a chosen port
 npm run keel make:controller Post   # -> app/Controllers/PostController.ts
 npm run keel make:provider Billing  # -> app/Providers/BillingServiceProvider.ts
 npm run keel make:middleware Auth   # -> app/Http/Middleware/authMiddleware.ts
+npm run keel make:page users/[id]   # -> resources/pages/users/[id].tsx
+npm run keel make:command greet     # -> app/Commands/greet.ts
+npm run keel repl                   # a shell with the app booted
+npm run keel mcp                    # start the MCP server (docs + API for AI agents)
 ```
 
 Under the hood the console binary is `bin/keel.ts`; the npm scripts wrap it with
 `tsx`.
 
+## Built for AI ⚓🤖
+
+Keel is designed to be **written with an AI agent**. Alongside the human docs it
+ships a machine-readable surface that stays generated-in-sync, never stale:
+
+- **An MCP server.** `keel-mcp` exposes Keel's docs, its full public API (380+
+  exports), the generators, and its conventions to any [MCP](https://modelcontextprotocol.io)
+  client. Connect it in Claude Code:
+  ```bash
+  claude mcp add keel -- npx -y keel-mcp
+  ```
+  Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
+  `keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
+  `keel://llms-full`, `keel://docs/<slug>`.
+- **[`AGENTS.md`](./AGENTS.md).** The agent playbook — the one import rule, the
+  folder map, the container/provider model, a "how to add X" table, and the
+  guardrails. `CLAUDE.md` points to it.
+- **[`llms.txt`](./llms.txt) + [`llms-full.txt`](./llms-full.txt).** A
+  [spec-compliant](https://llmstxt.org) doc index and a one-file concatenation of
+  every guide, both shipped in the npm package for drop-in context.
+- **Generators an agent can drive.** `keel_scaffold` (or `keel make:*`) emits the
+  correct stub with the right imports and path for every construct.
+
+Full guide: **[docs/ai.md](./docs/ai.md)**. Regenerate the surface after doc or
+export changes with `npm run build:ai` (also runs automatically on `npm run build`).
+
 ## Project layout
 
 ```
@@ -179,8 +209,8 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Models](./docs/models.md) | Active-record: find/create/save, casts, relations |
 | [Migrations](./docs/migrations.md) | Schema builder + migrator, dialect-aware |
 | [Factories & Seeders](./docs/factories.md) | Built-in Faker, model factories, seeders |
-| [Mail](./docs/mail.md) | Fluent mailer, pluggable transports, edge-safe |
-| [Queues & Jobs](./docs/queues.md) | Dispatch jobs, pluggable drivers, workers |
+| [Mail](./docs/mail.md) | Fluent mailer, pluggable transports, `sendLater()`, attachments |
+| [Queues & Jobs](./docs/queues.md) | Dispatch jobs, retries + backoff, dead-letter, workers |
 | [Task Scheduling](./docs/scheduling.md) | Cron-style recurring tasks, one trigger |
 | [Notifications](./docs/notifications.md) | Multi-channel (mail/db), queueable |
 | [Broadcasting](./docs/broadcasting.md) | Real-time channels, pluggable, presence auth |
@@ -188,23 +218,31 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Events](./docs/events.md) | Emit/listen decoupling, async listeners |
 | [Service Broker](./docs/broker.md) | Moleculer-style services, call/emit, pluggable transport |
 | [Cache](./docs/cache.md) | TTLs, the remember pattern, pluggable stores |
+| [Locks](./docs/locks.md) | Distributed locks with ownership + TTL, pluggable stores |
 | [Redis](./docs/redis.md) | Pluggable client, memory driver, cache adapter |
-| [Logger](./docs/logger.md) | Structured logging, per-request `reqId`, redaction |
+| [Logger](./docs/logger.md) | Structured logging, sinks, per-request `reqId`, redaction |
 | [Static Files](./docs/static-files.md) | serveStatic(), caching, dot-file safety |
-| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), edge-safe |
+| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), signed URLs, direct uploads |
+| [Health Checks](./docs/health.md) | `/health/live` + `/health/ready`, pluggable checks |
+| [Telemetry](./docs/telemetry.md) | Tracing, W3C context, OTLP export — no SDK |
+| [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 |
+| [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 |
 | [Middleware](./docs/middleware.md) | Global middleware, writing your own |
 | [Rate Limiting](./docs/rate-limiting.md) | rateLimiter() middleware, per-key buckets |
 | [Errors](./docs/errors.md) | HTTP exceptions, debug page, custom handlers |
-| [Testing](./docs/testing.md) | Inject requests, fluent response assertions |
+| [Testing](./docs/testing.md) | Inject requests, fakes, spies, time travel, db assertions |
 | [Debugging](./docs/debugging.md) | dump() and dd() (dump-and-die) |
 | [Validation](./docs/validation.md) | `validate()` with Zod, auto-422 field errors |
 | [Inertia](./docs/inertia.md) | Server-side Inertia.js adapter |
 | [Vite](./docs/vite.md) | Frontend build: HMR in dev, hashed manifest in prod |
-| [The Console](./docs/console.md) | `serve`, `routes`, `make:*` generators |
+| [The Console](./docs/console.md) | Typed commands, prompts, terminal UI, REPL, `make:*` |
 | [Architecture](./docs/architecture.md) | Container, kernel, request lifecycle |
 | [Built on Hono](./docs/hono.md) | The Hono layer underneath, and using it directly |
+| [Building with AI](./docs/ai.md) | MCP server, `AGENTS.md`, `llms.txt`, agent workflow |
 
 ## Testing
 

package/bin/keel-mcp.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Published entry for the Keel MCP server. Registered as the `keel-mcp` bin,
+// so an installed app can wire it up with `npx keel-mcp` (see docs/ai.md).
+import { runMcpServer } from "../dist/mcp/server.js";
+
+runMcpServer().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/api/api.config.stub

@@ -0,0 +1,9 @@
+/**
+ * Keel API-resource defaults.
+ * Published with `keel vendor:publish --tag api-config`.
+ */
+export default {
+  // Default list page size, and the hard ceiling on ?perPage=.
+  perPage: 25,
+  maxPerPage: 100,
+};

package/dist/api/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * API-resource defaults. Read off `config("api")`, so an app can set global
+ * pagination limits in `config/api.ts`; every `apiResource()` inherits them and
+ * can override per-resource.
+ */
+export interface ApiConfig {
+    /** Default page size for list endpoints. */
+    perPage: number;
+    /** Hard ceiling on `?perPage=` — the guard against "give me everything". */
+    maxPerPage: number;
+}
+export declare const defaultConfig: ApiConfig;
+export declare function apiDefaults(): ApiConfig;

package/dist/api/config.js

@@ -0,0 +1,14 @@
+/**
+ * API-resource defaults. Read off `config("api")`, so an app can set global
+ * pagination limits in `config/api.ts`; every `apiResource()` inherits them and
+ * can override per-resource.
+ */
+import { config } from "../core/helpers.js";
+export const defaultConfig = {
+    perPage: 25,
+    maxPerPage: 100,
+};
+export function apiDefaults() {
+    const raw = config("api", {});
+    return { ...defaultConfig, ...raw };
+}

package/dist/api/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Keel API resources — a full CRUD REST API from a model, imported from
+ * `@shaferllc/keel/api`.
+ *
+ *   import { apiResource } from "@shaferllc/keel/api";
+ *   apiResource(router, Post, { filter: ["status"], body: PostSchema, access: { read: true } });
+ *
+ * The generated routes are documented automatically by `@shaferllc/keel/openapi`.
+ */
+export { apiResource } from "./resource.js";
+export type { ApiResourceOptions, ApiAccess, Access, ApiAction, ApiTransform, ModelStatic, } from "./resource.js";
+export { ApiServiceProvider } from "./provider.js";
+export { defaultConfig, apiDefaults } from "./config.js";
+export type { ApiConfig } from "./config.js";
+export { parseListParams, applyListParams } from "./query.js";
+export type { ListParams, ListQueryOptions } from "./query.js";

package/dist/api/index.js

@@ -0,0 +1,13 @@
+/**
+ * Keel API resources — a full CRUD REST API from a model, imported from
+ * `@shaferllc/keel/api`.
+ *
+ *   import { apiResource } from "@shaferllc/keel/api";
+ *   apiResource(router, Post, { filter: ["status"], body: PostSchema, access: { read: true } });
+ *
+ * The generated routes are documented automatically by `@shaferllc/keel/openapi`.
+ */
+export { apiResource } from "./resource.js";
+export { ApiServiceProvider } from "./provider.js";
+export { defaultConfig, apiDefaults } from "./config.js";
+export { parseListParams, applyListParams } from "./query.js";

package/dist/api/provider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Optional provider for the API-resource layer. `apiResource()` works without it —
+ * it just reads sensible defaults. Register this to override the pagination
+ * defaults in `config/api.ts` and to publish that stub.
+ */
+import { PackageProvider } from "../core/package.js";
+export declare class ApiServiceProvider extends PackageProvider {
+    readonly name = "api";
+    register(): void;
+}

package/dist/api/provider.js

@@ -0,0 +1,17 @@
+/**
+ * Optional provider for the API-resource layer. `apiResource()` works without it —
+ * it just reads sensible defaults. Register this to override the pagination
+ * defaults in `config/api.ts` and to publish that stub.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { PackageProvider } from "../core/package.js";
+import { defaultConfig } from "./config.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export class ApiServiceProvider extends PackageProvider {
+    name = "api";
+    register() {
+        this.mergeConfig("api", defaultConfig);
+        this.publishes({ [join(here, "api.config.stub")]: "config/api.ts" }, "api-config");
+    }
+}

package/dist/api/query.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turn the query string of a list request into filters, sorting, and a page —
+ * safely. The cardinal rule of an auto-generated API: **never** let the client
+ * filter or sort by an arbitrary column. Everything here is checked against an
+ * allow-list; anything not on it is silently ignored, not passed to SQL. That's
+ * what keeps `?password=…` or `?sort=secret_column` from doing anything.
+ */
+import type { Ctx } from "../core/http/router.js";
+import type { QueryBuilder } from "../core/database.js";
+export interface ListQueryOptions {
+    /** Columns a client may filter on (`?status=published`). */
+    filter: string[];
+    /** Columns a client may sort by (`?sort=title,-createdAt`). */
+    sort: string[];
+    /** Default page size. */
+    perPage: number;
+    /** Maximum `?perPage=`. */
+    maxPerPage: number;
+}
+export interface ListParams {
+    page: number;
+    perPage: number;
+    filters: Array<{
+        column: string;
+        value: string;
+    }>;
+    sort: Array<{
+        column: string;
+        direction: "asc" | "desc";
+    }>;
+}
+/** Parse (and allow-list) the list query params. */
+export declare function parseListParams(c: Ctx, opts: ListQueryOptions): ListParams;
+/** Apply parsed filters and sorting to a query builder. */
+export declare function applyListParams(query: QueryBuilder, params: ListParams): QueryBuilder;

package/dist/api/query.js

@@ -0,0 +1,42 @@
+/**
+ * Turn the query string of a list request into filters, sorting, and a page —
+ * safely. The cardinal rule of an auto-generated API: **never** let the client
+ * filter or sort by an arbitrary column. Everything here is checked against an
+ * allow-list; anything not on it is silently ignored, not passed to SQL. That's
+ * what keeps `?password=…` or `?sort=secret_column` from doing anything.
+ */
+/** Query keys that control pagination/sorting, never treated as filters. */
+const RESERVED = new Set(["page", "perPage", "per_page", "sort", "q", "limit", "offset"]);
+function toInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.trunc(n) : fallback;
+}
+/** Parse (and allow-list) the list query params. */
+export function parseListParams(c, opts) {
+    const q = c.req.query();
+    const page = Math.max(1, toInt(q.page, 1));
+    const perPage = Math.min(Math.max(1, toInt(q.perPage ?? q.per_page, opts.perPage)), opts.maxPerPage);
+    const allowFilter = new Set(opts.filter);
+    const filters = Object.entries(q)
+        .filter(([key]) => !RESERVED.has(key) && allowFilter.has(key))
+        .map(([column, value]) => ({ column, value }));
+    const allowSort = new Set(opts.sort);
+    const sort = (q.sort ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => s.startsWith("-")
+        ? { column: s.slice(1), direction: "desc" }
+        : { column: s, direction: "asc" })
+        .filter((s) => allowSort.has(s.column));
+    return { page, perPage, filters, sort };
+}
+/** Apply parsed filters and sorting to a query builder. */
+export function applyListParams(query, params) {
+    let q = query;
+    for (const f of params.filters)
+        q = q.where(f.column, f.value);
+    for (const s of params.sort)
+        q = q.orderBy(s.column, s.direction);
+    return q;
+}

package/dist/api/resource.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `apiResource(router, Model, options)` — a full CRUD REST API from a Keel model,
+ * the Remult idea done the Keel way: explicit, server-side, and composed from
+ * pieces you already have. It registers real routes (so the OpenAPI package
+ * documents them for free), runs writes through the model's mass-assignment guard
+ * and your Zod schema, paginates and allow-list-filters reads, and gates every
+ * action.
+ *
+ *   apiResource(router, Post, {
+ *     filter: ["status", "authorId"],
+ *     sort: ["createdAt", "title"],
+ *     body: PostSchema,
+ *     access: { read: true, write: (c) => isEditor(c) },
+ *     scope: (q) => q.where("deleted", false),
+ *   });
+ *
+ * Access is **deny by default**: an action with no `access` rule returns 403.
+ * That's the safe default for a generated API — you opt routes open, never shut.
+ */
+import type { Router, Ctx } from "../core/http/router.js";
+import type { QueryBuilder, Row } from "../core/database.js";
+import type { Model } from "../core/model.js";
+import type { Schema } from "../core/validation.js";
+/** A Model subclass (the class itself, with its statics). */
+export type ModelStatic = typeof Model;
+/** A CRUD action. */
+export type ApiAction = "list" | "read" | "create" | "update" | "delete";
+/** An access rule: a flat allow/deny, or a per-request predicate. */
+export type Access = boolean | ((c: Ctx) => boolean | Promise<boolean>);
+/**
+ * Access rules per action, with shorthands. Resolution for an action prefers its
+ * own key, then the read/write shorthand, then `all`; absent → denied.
+ */
+export interface ApiAccess {
+    /** Fallback for every action. */
+    all?: Access;
+    /** Shorthand for `list` + `get`. */
+    read?: Access;
+    /** Shorthand for `create` + `update` + `delete`. */
+    write?: Access;
+    list?: Access;
+    /** The single-item read (GET /:id). */
+    get?: Access;
+    create?: Access;
+    update?: Access;
+    delete?: Access;
+}
+/** How a model is turned into API output — a function, or a Keel Transformer. */
+export type ApiTransform = ((model: Model, c: Ctx) => unknown) | {
+    item(value: Model): unknown;
+    collection(values: Model[]): unknown[];
+};
+export interface ApiResourceOptions {
+    /** Base path. Default: the model's table name. */
+    path?: string;
+    /** Route-name prefix. Default: the path. */
+    name?: string;
+    /** Only expose these actions. */
+    only?: ApiAction[];
+    /** Expose everything except these. */
+    except?: ApiAction[];
+    /** Columns clients may filter on. Empty = no filtering. */
+    filter?: string[];
+    /** Columns clients may sort by. Empty = no sorting. */
+    sort?: string[];
+    /** Default page size (overrides `config("api.perPage")`). */
+    perPage?: number;
+    /** Max page size (overrides `config("api.maxPerPage")`). */
+    maxPerPage?: number;
+    /** Zod (or Zod-like) schema validating create + update bodies. */
+    body?: Schema<unknown>;
+    /** Schema for create only (overrides `body`). */
+    createBody?: Schema<unknown>;
+    /** Schema for update only (overrides `body`). */
+    updateBody?: Schema<unknown>;
+    /** Access rules. Deny by default. */
+    access?: ApiAccess;
+    /**
+     * Constrain the base query for **every** row operation — list, read, update,
+     * delete. This is row-level security: a row outside the scope reads as 404, so
+     * it can't be fetched, changed, or removed.
+     */
+    scope?: (query: QueryBuilder, c: Ctx) => QueryBuilder | void;
+    /** Shape the output. Default: `model.toJSON()`. */
+    transform?: ApiTransform;
+    /** Mutate the write payload before it's saved (set an owner id, timestamps…). */
+    beforeWrite?: (data: Row, c: Ctx, action: "create" | "update") => Row | Promise<Row>;
+    /** OpenAPI tags for these routes. Default: `[path]`. */
+    tags?: string[];
+}
+export declare function apiResource(router: Router, model: ModelStatic, options?: ApiResourceOptions): void;