@palbase/backend 2.0.0 → 3.0.0

package/docs/llms-full.txt

@@ -0,0 +1,1038 @@
+# Palbase Backend SDK (`@palbase/backend`)
+
+> File-based TypeScript backend SDK. All handler types import service singletons (`Database`, `Cache`, …). Trigger arg differs by type: endpoints use `req`, workers `(payload, meta)`, jobs `(meta)`, hooks/webhooks `(event, meta)`. Middleware is the one exception (`ctx`). Not Express, not Supabase Edge Functions.
+
+
+
+<!-- ===== README.md ===== -->
+
+# Palbase Backend SDK (`@palbase/backend`)
+
+Write your backend as TypeScript files. Palbase discovers them by path, runs
+them inside the managed backend runtime, and exposes them as a typed HTTP API.
+
+This is **not** Express, Fastify, or a Supabase Edge Function. There is no
+`app.get(...)`, no manual route registration, no `import express`. You export
+definitions; the runtime wires them up.
+
+## Mental model (important)
+
+Every handler type imports service singletons the same way:
+
+```ts
+import { Database, Log, Cache, Queue } from "@palbase/backend";
+```
+
+The **only difference** is the trigger argument:
+
+| You are writing… | Handler signature | Trigger arg |
+|------------------|-------------------|-------------|
+| **Endpoints** (`controllers/` + `handlers/`) | `(req)` | `req` — [PBRequest](./endpoints.md) |
+| **Workers** (`workers/**`) | `(payload, meta)` | typed payload + `WorkerMeta` |
+| **Jobs** (`jobs/**`) | `(meta)` | `JobMeta` |
+| **Hooks** (`hooks/**`) | `(event, meta)` | typed event + `HookMeta` |
+| **Webhooks** (`webhooks/**`) | `(event, meta)` | typed event + `WebhookMeta` |
+| **Middleware** (`middleware/**`) | `(ctx, next)` | `MiddlewareContext` — the **one exception** |
+
+`meta` carries non-service data: `env` (branch env vars), `projectId`,
+`environmentId`, and for workers/webhooks `requestId`. Services always come from
+the imported singletons — not from `ctx` or any argument.
+
+## Project shape
+
+```
+my-backend/
+├── package.json            # depends on @palbase/backend
+├── controllers/            # route maps: method+path → handler (mounts the API)
+│   └── hello.controller.ts # defineController("/hello", { … })
+├── handlers/               # one endpoint unit each (schema + thin logic)
+│   └── hello.ts            # defineHandler({ auth, input, output, handler })
+├── services/               # plain classes/singletons your handlers call
+├── db/schema.ts            # table definitions (optional, enables typed DB)
+├── db/migrations/          # explicit SQL migrations for type changes (optional)
+├── workers/                # background job handlers (optional)
+├── jobs/                   # cron-scheduled jobs (optional)
+├── hooks/                  # auth/storage/document event hooks (optional)
+├── webhooks/               # inbound provider webhooks (optional)
+└── middleware/             # cross-cutting request middleware (optional)
+```
+
+HTTP endpoints are **not** file-path routed. You author a `handler` (one
+endpoint: `auth`/`input`/`output`/`errors` + logic, no route) and mount it in a
+`controller` (a route map). See [routing.md](./routing.md).
+
+## Documentation
+
+| Topic | File |
+|-------|------|
+| Getting started | [getting-started.md](./getting-started.md) |
+| File-based routing | [routing.md](./routing.md) |
+| Endpoints & `req` | [endpoints.md](./endpoints.md) |
+| Database & transactions | [database.md](./database.md) |
+| Schema & typed DB | [schema.md](./schema.md) |
+| Migrations (additive vs type-change + drift-gate) | [migrations.md](./migrations.md) |
+| Services (Cache, Queue, Storage, …) | [services.md](./services.md) |
+| Errors | [errors.md](./errors.md) |
+| Workers & Jobs | [background.md](./background.md) |
+| Hooks & Webhooks | [events.md](./events.md) |
+
+For AI coding tools: a single concatenated corpus is generated at
+[`llms-full.txt`](./llms-full.txt) (and an index at [`llms.txt`](./llms.txt)).
+
+
+
+<!-- ===== getting-started.md ===== -->
+
+# Getting started
+
+There is no CLI init command. A starter project is created for you when your
+Palbase project is provisioned. You then edit the files locally and deploy them.
+
+## package.json
+
+Your project depends on the SDK and uses the Palbase CLI for the dev loop:
+
+```json
+{
+  "name": "my-backend",
+  "private": true,
+  "scripts": {
+    "dev": "palbase serve",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": { "@palbase/backend": "latest" },
+  "devDependencies": { "@types/node": "^22", "typescript": "^5" }
+}
+```
+
+## Local dev loop
+
+- `palbase serve` — run your backend locally with hot reload. It runs your
+  `controllers/` locally but proxies `Database`/`ctx.*` to the **deployed**
+  branch, so the branch must already be deployed (serve tells you to push first
+  if it isn't). See [migrations.md](./migrations.md) for the schema/migration
+  side of this.
+- **Deploy is GitHub-native** — there is no `palbase push`. Commit and
+  `git push` to your project's repo; the push triggers a deploy of the backend
+  runtime. Push a **branch** to deploy that branch instead of `main`.
+
+## Your first endpoint
+
+A handler is one endpoint unit; a controller maps method+path to it. Create
+`handlers/hello.ts`:
+
+```ts
+import { defineHandler, z } from "@palbase/backend";
+
+export default defineHandler({
+  input: z.object({ name: z.string().optional() }),
+  output: z.object({ message: z.string(), user: z.string().nullable() }),
+  handler: async (req) => ({
+    message: `hello, ${req.input.name ?? "world"}!`,
+    user: req.user?.id ?? null,
+  }),
+});
+```
+
+Then mount it in `controllers/hello.controller.ts`:
+
+```ts
+import { defineController, route } from "@palbase/backend";
+import hello from "../handlers/hello.js";
+
+export default defineController("/hello", {
+  hello: route.get("/", hello),
+});
+```
+
+This is served at `GET /hello`. The Zod `input` schema validates the request and
+flows into `req.input`; the `output` schema validates your return value. See
+[routing.md](./routing.md) for the handler + controller model.
+
+
+
+<!-- ===== routing.md ===== -->
+
+# Routing
+
+Routes are declared in code. A **handler** is one endpoint unit (schema + thin
+logic) with NO route on it; a **controller** is a route map (method+path →
+handler). Putting a controller file under `controllers/` mounts it — there is no
+central router and no manual registration.
+
+```ts
+import { defineController, route } from "@palbase/backend";
+```
+
+## Handlers — one endpoint per file, no route
+
+A handler declares everything that types `req` (`auth`/`input`/`output`/
+`errors`) and the logic; it has no method or path.
+
+```ts
+// handlers/places/import-nearby.ts
+import { defineHandler, z } from "@palbase/backend";
+import { placeService } from "../../services/place.service.js";
+
+export default defineHandler({
+  auth:   { required: true },
+  input:  z.object({ lat: z.number(), lng: z.number() }),
+  output: z.object({ imported: z.number() }),
+  errors: { quotaExceeded: { status: 429, code: "quota_exceeded" } },
+  handler: (req) => placeService.importNearby(req.input.lat, req.input.lng),
+});
+```
+
+## Controllers — the route map
+
+A controller maps method+path to handlers with `route.get|post|put|patch|delete`.
+The route-map KEY is authoring sugar only (it is NOT the operationId).
+
+```ts
+// controllers/places.controller.ts
+import { defineController, route } from "@palbase/backend";
+import importNearby  from "../handlers/places/import-nearby.js";
+import addFavorite   from "../handlers/places/add-favorite.js";
+import listFavorites from "../handlers/places/list-favorites.js";
+
+export default defineController("/places", {
+  importNearby:  route.post("/import",    importNearby),
+  addFavorite:   route.post("/favorites", addFavorite),
+  listFavorites: route.get ("/favorites", listFavorites),
+});
+```
+
+| Map key (sugar) | Method | Full path | operationId (flat) |
+|---|---|---|---|
+| `importNearby`  | POST | `/places/import`    | `postPlacesImport` |
+| `addFavorite`   | POST | `/places/favorites` | `postPlacesFavorites` |
+| `listFavorites` | GET  | `/places/favorites` | `getPlacesFavorites` |
+
+Rules:
+
+- The full path of a route is `basePath + subpath` (`"/places" + "/import"`).
+- A `{segment}` in a path becomes a route param, read via `req.params.segment`.
+- Each route value MUST be a `route.*(...)` result — a bare handler is a
+  compile error, which keeps logic out of controllers.
+- The operationId is derived FLAT from method + full path (`postPlacesImport`),
+  not from the map key. Change a verb with `route.post` → `route.put` — no file
+  rename.
+
+See [endpoints.md](./endpoints.md) for the full `defineHandler` config (`req`,
+auth, input/output, errors, middleware) reference.
+
+
+
+<!-- ===== endpoints.md ===== -->
+
+# Endpoints
+
+An endpoint is a **handler** — `export default defineHandler({...})` in a file
+under `handlers/`. A handler has NO method or path; a **controller** maps
+method+path to it (see [routing.md](./routing.md)). The handler receives **one
+argument**, `req` (a `PBRequest`). Services are NOT on `req` — import them as
+singletons (see [services.md](./services.md)).
+
+## `defineHandler` config
+
+```ts
+defineHandler({
+  auth: { required: true },          // see Auth below. Omitted → AUTH REQUIRED (secure-by-default).
+  rateLimit: { max: 100, window: 60 }, // optional: max requests per window seconds
+  input: z.object({ ... }),          // optional Zod schema → validates & types req.input
+  output: z.object({ ... }),         // optional Zod schema → validates the return value
+  errors: { ... },                   // optional declared errors (see errors.md)
+  middleware: [ ... ],               // optional Middleware[] (see below)
+  handler: async (req) => { ... },   // required
+});
+```
+
+There is no `method` field — the HTTP verb (and path) live in the controller
+that mounts the handler via `route.get|post|put|patch|delete`.
+
+## `req` (PBRequest)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `req.input` | inferred from `input` schema | request body for POST/PUT/PATCH; `{}` otherwise |
+| `req.params` | `Record<string,string>` | route params, e.g. `req.params.id` |
+| `req.query` | `Record<string,string>` | parsed query string |
+| `req.headers` | `Record<string,string>` | lowercase keys |
+| `req.user` | `User` when authenticated; `User \| null` when `auth` is omitted or `required: false` | see Auth below |
+| `req.client` | `ClientInfo` | calling SDK/app/platform/os version (all nullable) |
+| `req.file` | `FileContext \| null` | uploaded file, if any |
+| `req.method` | `string` | the HTTP method |
+| `req.requestId` / `req.traceId` / `req.spanId` | `string` | correlation ids |
+| `req.errors` | typed throwers | present when `errors` is declared (see errors.md) |
+
+`User` is `{ id: string; email?: string; role: string; metadata: Record<string, unknown> }`.
+
+## Auth
+
+**Secure by default:** a handler requires authentication UNLESS it explicitly
+opts out. Omitting `auth` means AUTH REQUIRED — a forgotten `auth` fails safe
+(401), never silently public. Mark a route PUBLIC with `auth: { required: false }`.
+
+```ts
+// auth omitted entirely                 // AUTH REQUIRED → req.user is non-null User
+auth: { required: true }                // same: require any authenticated user
+auth: { required: true, role: "admin" } // require a specific role
+auth: { required: false }               // PUBLIC → req.user may be null (anon key only)
+```
+
+Whether `req.user` is non-null is computed from the `auth` config at the type
+level (and matches the runtime exactly):
+
+| `auth` value | `req.user` type |
+|--------------|-----------------|
+| omitted | `User` (secure-by-default) |
+| `true` | `User` |
+| `false` | `User \| null` (public) |
+| `{ required: true }` | `User` |
+| `{ required: false }` | `User \| null` (public) |
+| `{ role: "admin" }` (object, no `required`) | `User` |
+
+To make a route PUBLIC, set `auth: { required: false }` (or `auth: false`). An
+object with a `role` but no `required` key is treated as authenticated. When
+`auth` is omitted, the endpoint is public and `req.user` may be null.
+
+## Typed input/output
+
+```ts
+import { defineHandler, z, Database } from "@palbase/backend";
+
+export default defineHandler({
+  auth: { required: true },
+  input: z.object({ name: z.string().min(1).max(100), capacity: z.number().int().positive().optional() }),
+  output: z.object({ id: z.string(), name: z.string(), capacity: z.number().nullable() }),
+  handler: async (req) => {
+    const room = await Database.insert("rooms", {
+      name: req.input.name,
+      capacity: req.input.capacity ?? null,
+    });
+    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  },
+});
+```
+
+A controller then mounts it with a method + path:
+
+```ts
+// controllers/rooms.controller.ts
+import { defineController, route } from "@palbase/backend";
+import create from "../handlers/rooms/create.js";
+
+export default defineController("/rooms", {
+  create: route.post("/", create),
+});
+```
+
+## Middleware
+
+A middleware wraps a request. Define one in `middleware/<name>.ts`:
+
+```ts
+// middleware/logger.ts
+import { defineMiddleware } from "@palbase/backend";
+
+export default defineMiddleware(async (ctx, next) => {
+  ctx.log.info(`start ${ctx.requestId}`);
+  await next();
+  ctx.log.info(`done ${ctx.requestId}`);
+});
+```
+
+The middleware handler receives `(ctx, next)` — call `await next()` to run the
+rest of the chain (other middleware, then the endpoint handler). Note this uses
+the `ctx` model, not `req`.
+
+To attach middleware to a specific handler, import it and list it in the
+handler's `middleware` array:
+
+```ts
+import { defineHandler, z } from "@palbase/backend";
+import logger from "../../middleware/logger.js";
+
+export default defineHandler({
+  middleware: [logger],
+  output: z.object({ ok: z.boolean() }),
+  handler: async (req) => ({ ok: true }),
+});
+```
+
+
+
+<!-- ===== database.md ===== -->
+
+# Database
+
+Import the `Database` singleton in every handler type — endpoints, workers,
+jobs, hooks, and webhooks all use the same import:
+
+```ts
+import { Database } from "@palbase/backend";
+```
+
+Only **middleware** still uses `ctx.db` (see [background.md](./background.md)
+and [events.md](./events.md) for worker/job/hook/webhook examples).
+
+## Typed by default — `Database.tables`
+
+When you declare `db/schema.ts`, `Database.tables.<name>` is typed everywhere
+with no import and no generic. `insert` demands the right columns; rows come
+back typed; nullable columns are `T | null`. This is the path you should use:
+
+```ts
+const todo = await Database.tables.todos.insert({ title: "buy milk" });
+todo.id;       // string ✓
+todo.done;     // boolean ✓
+const open = await Database.tables.todos.findMany({ done: false });
+await Database.tables.todos.update(todo.id, { done: true });
+await Database.tables.todos.delete(todo.id);
+// todo.nope ← compile error
+```
+
+See [schema.md](./schema.md) for the full typed-table surface.
+
+## Raw string-keyed operations
+
+For dynamic table names or read-only SQL, the string-keyed ops are still
+available:
+
+| Method | Returns |
+|--------|---------|
+| `Database.insert(table, data)` | the inserted row (`Record<string, unknown>`) |
+| `Database.update(table, id, data)` | the updated row |
+| `Database.delete(table, id)` | `void` |
+| `Database.findById(table, id)` | the row or `null` |
+| `Database.findMany(table, query?)` | matching rows (array) |
+| `Database.query(sql, params?)` | rows from a read-only SQL query (runs in a READ ONLY transaction) |
+| `Database.transaction(fn)` | runs `fn(tx)` in a transaction |
+
+`findMany`'s `query` is an equality filter: keys are ANDed together. For
+anything richer (ranges, ordering, joins) use `Database.query`.
+
+`Database.query` is **read-only** — use it for selects/joins the helpers don't
+cover. Writes must go through `insert`/`update`/`delete` or a transaction.
+
+```ts
+const rows = await Database.query(
+  "SELECT id, title FROM todos WHERE done = $1 ORDER BY created_at DESC LIMIT $2",
+  [false, 20],
+);
+```
+
+## Transactions
+
+`transaction(fn)` gives you a `tx` with the same DB ops (no nested
+transaction). Returning commits; throwing rolls back.
+
+```ts
+await Database.transaction(async (tx) => {
+  const order = await tx.tables.orders.insert({ amount: 1000, status: "pending" });
+  await tx.tables.order_items.insert({ order_id: order.id, sku: "ABC" });
+  // throw here → both inserts roll back
+});
+```
+
+The `tx` carries the same typed `tx.tables.<name>` API as `Database.tables`
+(no nested transaction). See [schema.md](./schema.md) for the full surface.
+
+
+
+<!-- ===== schema.md ===== -->
+
+# Schema & typed database access
+
+Declare your tables in `db/schema.ts` with `defineSchema`. This drives
+[migrations](./migrations.md) (additive changes auto-apply on deploy; type
+changes need an explicit migration) and makes `Database.tables.*` typed
+everywhere — by default, with no import and no generic.
+
+## Defining a schema
+
+The table NAME comes from the object key under `tables` — there is one
+canonical form.
+
+```ts
+import {
+  defineSchema,
+  uuid, text, integer, boolean, timestamp, jsonb, enumType,
+} from "@palbase/backend";
+
+export default defineSchema({
+  tables: {
+    rooms: {
+      id: uuid().primaryKey().defaultRandom(),
+      name: text().notNull(),
+      capacity: integer().nullable(),
+      is_active: boolean().default(true),
+      created_at: timestamp().defaultNow(),
+    },
+    sessions: {
+      id: uuid().primaryKey().defaultRandom(),
+      room_id: uuid().notNull().references("rooms", "id").onDelete("cascade"),
+      user_id: uuid().notNull(),
+      data: jsonb().nullable(),
+      started_at: timestamp().defaultNow(),
+    },
+    orders: {
+      id: uuid().primaryKey().defaultRandom(),
+      status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+      amount: integer().notNull(),
+    },
+  },
+});
+```
+
+## Column builders
+
+| Builder | Postgres type |
+|---------|---------------|
+| `uuid()` | `uuid` |
+| `text()` | `text` |
+| `integer()` | `integer` |
+| `boolean()` | `boolean` |
+| `timestamp()` | `timestamptz` |
+| `jsonb()` | `jsonb` |
+| `enumType(name, values)` | a Postgres enum |
+
+Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
+`.default(value)`, `.defaultRandom()` (uuid → `gen_random_uuid()`),
+`.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
+`.onDelete("cascade" | "set null" | "restrict" | "no action")`.
+
+## Typed DB access — by default
+
+You do **not** wire anything per endpoint. Saving `db/schema.ts` regenerates
+`palbase-env.d.ts`, which types `Database.tables.<name>` everywhere — no import
+of the schema, no generic, no cast:
+
+```ts
+import { defineHandler, z, Database } from "@palbase/backend";
+
+export default defineHandler({
+  input: z.object({ name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+  handler: async (req) => {
+    const room = await Database.tables.rooms.insert({ name: req.input.name });
+    return { id: room.id, name: room.name }; // room.id: string ✓
+    // room.nope ← compile error
+  },
+});
+```
+
+`Database.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
+`findById(id)`, `findMany(query?)`, and `Database.transaction(fn)` yields a `tx`
+with the same typed tables. The raw string-keyed ops
+(`Database.insert("rooms", …)`, `Database.query(…)`) are still available for
+dynamic table names and read-only SQL.
+
+If you want a row type explicitly, import it from the generated env module:
+
+```ts
+import type { Tables } from "@palbase/backend/env";
+type Room = Tables["rooms"]["row"];
+```
+
+
+
+<!-- ===== migrations.md ===== -->
+
+# Migrations
+
+`db/schema.ts` is the single source of truth for your Postgres schema. On every
+deploy, Palbase diffs your declared schema against the live branch database and
+reconciles it — but *how* it reconciles depends on whether the change is safe to
+apply automatically.
+
+## Two kinds of change
+
+### 1. Additive — auto-applied, no migration file
+
+A new table, or a new **nullable** or **defaulted** column, is additive: the
+deploy applies it automatically (`CREATE TABLE` / `ADD COLUMN`) with no manual
+step and no backfill risk. Just edit `db/schema.ts` and deploy.
+
+```ts
+// before
+todos: {
+  id: uuid().primaryKey().defaultRandom(),
+  title: text().notNull(),
+}
+
+// after — additive: `notes` (nullable) + `priority` (defaulted) auto-apply on deploy
+todos: {
+  id: uuid().primaryKey().defaultRandom(),
+  title: text().notNull(),
+  notes: text().nullable(),
+  priority: text().nullable().default("normal"),
+}
+```
+
+> A new **NOT NULL column without a default** is NOT additive-safe on a table
+> that already has rows (there is nothing to put in the existing rows). Make it
+> `.nullable()`, give it a `.default(...)`, or apply it as an explicit migration
+> (add nullable → backfill → set NOT NULL).
+
+### 2. Destructive / type-changing — needs an explicit migration
+
+Renaming or dropping a column, changing a column's type, or adding a NOT NULL
+constraint can lose or corrupt existing data — so the deploy's **drift-gate
+blocks them** and the deploy fails until you provide an explicit migration.
+Write the SQL yourself in `db/migrations/`:
+
+```
+db/migrations/
+  001_user_id_to_text.up.sql
+  001_user_id_to_text.down.sql
+```
+
+```sql
+-- 001_user_id_to_text.up.sql
+ALTER TABLE todos ALTER COLUMN user_id TYPE text USING user_id::text;
+```
+
+```sql
+-- 001_user_id_to_text.down.sql
+ALTER TABLE todos ALTER COLUMN user_id TYPE uuid USING user_id::uuid;
+```
+
+Migrations are golang-migrate style: numbered `NNN_name.up.sql` / `.down.sql`
+pairs, applied in order and tracked so each runs exactly once (idempotent).
+`db/schema.ts` always describes the **end state**; the migration describes **how
+existing data gets there**. Keep the two in sync — after the migration lands,
+`schema.ts` should already reflect the new column type.
+
+## The drift-gate
+
+On deploy, Palbase compares `db/schema.ts` to the live database:
+
+- **Additive** diffs → auto-applied.
+- **Type-changing / destructive** diffs **with** a matching migration → the
+  migration runs.
+- **Type-changing / destructive** diffs **without** a migration → the deploy
+  **aborts** and your currently-running version keeps serving.
+
+This is deliberate: it stops an accidental column-type change from silently
+dropping production data. A blocked deploy is a prompt to write the migration,
+not a failure to work around.
+
+## Local dev: `palbase serve` uses the deployed database
+
+`palbase serve` runs your controllers locally but proxies `Database` and
+`ctx.*` to the **deployed** branch — it does **not** spin up a local Postgres or
+apply migrations locally. So when your local `db/schema.ts` or `db/migrations/`
+is ahead of what's deployed, serve prints a note: new tables/columns won't exist
+until you push. Deploy to apply them.
+
+## Workflow
+
+1. Edit `db/schema.ts`.
+2. **Additive** change? → `git push`. It auto-migrates on deploy.
+3. **Type change / rename / drop?** → add `db/migrations/NNN_*.up.sql` (+
+   `.down.sql`), then `git push`. The runner applies it; without it the
+   drift-gate blocks the deploy.
+4. `palbase serve` warns locally until the change is deployed.
+
+See [schema.md](./schema.md) for the column builders and typed
+`Database.tables.*` access.
+
+
+
+<!-- ===== services.md ===== -->
+
+# Services
+
+Import service singletons from `@palbase/backend` in every handler type —
+endpoints, workers, jobs, hooks, and webhooks all use the same imports. Only
+**middleware** uses a `ctx` argument (`ctx.db`, `ctx.log`, etc.).
+
+Available singletons: `Database`, `Documents`, `Storage`, `Cache`, `Queue`,
+`Log`, `Notifications`, `Flags`.
+
+**Not available to backend handlers** (do not import them here): Realtime,
+Functions, CMS, Links, Analytics, and Auth. Auth runs on the client SDK; the
+others are out of scope for backend endpoints.
+
+## Cache
+
+JSON-typed key/value cache.
+
+```ts
+import { Cache } from "@palbase/backend";
+
+await Cache.set("k", { hits: 1 }, 60);     // value + TTL seconds
+const v = await Cache.get<{ hits: number }>("k"); // typed, null on miss
+await Cache.incr("counter");
+await Cache.del("k");
+
+// Stampede-safe read-through: only one caller across all pods runs fn.
+const profile = await Cache.getOrSet("user:42", 300, async () => {
+  return Database.findById("users", "42");
+});
+```
+
+`getOrSet` caches whatever `fn` returns, including `null` — return a sentinel or
+guard upstream if you don't want misses cached.
+
+## Queue
+
+Enqueue work for a worker (see [background.md](./background.md)).
+
+```ts
+import { Queue } from "@palbase/backend";
+const { jobId } = await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
+```
+
+## Log
+
+```ts
+import { Log } from "@palbase/backend";
+Log.info("created order", { orderId });
+Log.warn("retrying");
+Log.error("failed", err);
+Log.debug("detail");
+```
+
+## Storage
+
+Bucket-scoped file operations.
+
+```ts
+import { Storage } from "@palbase/backend";
+const bucket = Storage.bucket("avatars");
+const { data, error } = await bucket.upload("u/42.png", file);
+const { data: signed } = await bucket.createSignedUrl("u/42.png", 3600);
+const pub = bucket.getPublicUrl("u/42.png");        // sync, no network
+await bucket.remove(["u/42.png"]);
+```
+
+All Storage calls return `{ data, error }` — check `error` before using `data`.
+
+## Documents
+
+Firestore-like document store.
+
+```ts
+import { Documents } from "@palbase/backend";
+const col = Documents.collection("rooms");
+const { data: ref } = await col.add({ name: "Lobby" });
+const snap = await col.where("active", "==", true).orderBy("name").limit(10).get();
+const { data: doc } = await Documents.doc("rooms/abc").get();
+```
+
+## Notifications
+
+```ts
+import { Notifications } from "@palbase/backend";
+await Notifications.email.send({ /* PalbaseEmailSendParams */ });
+await Notifications.push.send({ /* PalbasePushSendParams */ });
+await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
+```
+
+## Flags
+
+```ts
+import { defineHandler, z, Flags } from "@palbase/backend";
+
+export default defineHandler({
+  auth: { required: true },           // req.user is non-null here
+  output: z.object({ enabled: z.boolean() }),
+  handler: async (req) => {
+    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: req.user.id });
+    const { data: variant } = await Flags.getVariant("button-color", { userId: req.user.id });
+    return { enabled: enabled ?? false };
+  },
+});
+```
+
+
+
+<!-- ===== resources.md ===== -->
+
+# Resources
+
+A `Resource` models one external connection — a pooled datastore, a stateless
+API client, or a per-user factory. You put it in `resources/`, export an
+instance, and **do not register it**: the framework discovers it, sets it up
+once at boot, and drains it on shutdown. On top of that lifecycle you expose
+your own clean facade.
+
+```ts
+import { Resource } from "@palbase/backend";
+```
+
+## Lifecycle (boot scope — not per request)
+
+A resource is created once at process boot — NOT per request. The framework:
+
+1. calls `init(env)` **once**, with only the secrets the resource declared;
+2. (optionally) calls `shutdown()` on SIGTERM, in reverse boot order.
+
+The instance lives for the whole process; your facade methods are called
+per-request. This makes "reconnect on every request" structurally impossible.
+
+## Pooled datastore — `init` + `shutdown`
+
+```ts
+import { Resource } from "@palbase/backend";
+import neo4j, { type Driver, type Session } from "neo4j-driver";
+
+export class Neo4jResource extends Resource {
+  static secrets = ["NEO4J_URL", "NEO4J_USER", "NEO4J_PASSWORD"] as const;
+  private driver!: Driver;
+  async init(env: { NEO4J_URL: string; NEO4J_USER: string; NEO4J_PASSWORD: string }) {
+    this.driver = neo4j.driver(env.NEO4J_URL, neo4j.auth.basic(env.NEO4J_USER, env.NEO4J_PASSWORD));
+  }
+  async shutdown() {
+    await this.driver.close();
+  }
+  session(): Session {
+    return this.driver.session();
+  }
+}
+
+export const graph = new Neo4jResource();
+```
+
+## Stateless API client — `init` only
+
+```ts
+import { Resource } from "@palbase/backend";
+import { Client } from "@googlemaps/google-maps-services-js";
+
+export class GoogleResource extends Resource {
+  static secrets = ["GOOGLE_MAPS_KEY"] as const;
+  private client = new Client();
+  private key = "";
+  init(env: { GOOGLE_MAPS_KEY: string }) {
+    this.key = env.GOOGLE_MAPS_KEY;
+  }
+  nearby(lat: number, lng: number) {
+    return this.client.placesNearby({ params: { location: { lat, lng }, radius: 1500, key: this.key } });
+  }
+}
+
+export const google = new GoogleResource();
+```
+
+A per-user (OAuth) resource adds a factory method on the base, e.g.
+`github.forUser(token)` — the same single model covers pooled, stateless, and
+per-user.
+
+## Secrets
+
+`static secrets` is the contract:
+
+- It **types** the `env` passed to `init` — only the declared names are
+  present, each a `string`. An undeclared key is a compile error.
+- A declared secret that is **missing at boot fails the deploy**, naming the
+  secret. Secrets are branch-scoped; set them with `palbase secret set NAME ...`
+  or in Studio. A resource is initialised once at boot, so rotating a secret
+  needs a redeploy/restart.
+
+`secrets` is optional — a resource that needs none simply omits it and gets an
+empty `env`.
+
+## Using a resource
+
+Import the singleton and call your facade — services and handlers reach
+resources the same way they reach `Database`:
+
+```ts
+import { google } from "../resources/google.js";
+
+const results = (await google.nearby(41.0, 29.0)).data.results;
+```
+
+
+
+<!-- ===== errors.md ===== -->
+
+# Errors
+
+Two ways to fail a request. Both serialize to the standard Palbase error
+envelope:
+
+```json
+{ "error": "todo_not_found", "error_description": "No such todo", "status": 404, "request_id": "req_…" }
+```
+
+## 1. `HttpError` (ad-hoc)
+
+```ts
+import { HttpError } from "@palbase/backend";
+throw new HttpError(404, "todo_not_found", "No such todo");
+// optional structured payload (4th arg) rides along under `data`:
+throw new HttpError(423, "todo_locked", "Locked", { retryAfter: 30 });
+```
+
+`new HttpError(status, code, description, data?)`.
+
+## 2. Declared errors (typed)
+
+Declare them on the handler; throw via `req.errors.<name>(...)`. Declared
+errors are described in the endpoint's OpenAPI and codegen'd into a typed enum
+for iOS callers.
+
+```ts
+import { defineHandler, z, Database } from "@palbase/backend";
+
+export default defineHandler({
+  input: z.object({ id: z.string() }),
+  output: z.object({ ok: z.boolean() }),
+  errors: {
+    notFound: { status: 404, code: "todo_not_found", description: "No such todo" },
+    locked: { status: 423, code: "todo_locked", data: z.object({ retryAfter: z.number() }) },
+  },
+  handler: async (req) => {
+    const todo = await Database.findById("todos", req.input.id);
+    if (!todo) throw req.errors.notFound();              // no data → no args
+    if (todo.locked) throw req.errors.locked({ retryAfter: 30 }); // data schema → required arg
+    return { ok: true };
+  },
+});
+```
+
+A declared error with a `data` Zod schema requires that payload as an argument;
+one without `data` takes no arguments. This is enforced by the types.
+
+
+
+<!-- ===== background.md ===== -->
+
+# Workers & Jobs
+
+Workers and jobs use the **singleton model** — the same imported service
+singletons as endpoints (`import { Database, Log } from "@palbase/backend"`).
+They do **not** receive a `req`. Instead, a small `meta` argument carries the
+non-service data (`env`, `user`, correlation ids).
+
+## Workers (queue consumers)
+
+A worker processes jobs pushed via `Queue.push(name, payload)`. File lives under
+`workers/`.
+
+```ts
+// workers/process-order.ts
+import { defineWorker, Database, Log } from "@palbase/backend";
+
+interface OrderPayload { orderId: string; amount: number; }
+
+export default defineWorker<OrderPayload>({
+  name: "process-order",       // must match the Queue.push() name
+  retry: 5,                    // optional, default 3
+  timeout: 60,                 // optional, seconds
+  backoff: "exponential",      // "exponential" | "linear" | "fixed", default exponential
+  handler: async (payload, meta) => {
+    Log.info(`processing ${payload.orderId} (env ${meta.environmentId})`);
+    await Database.update("orders", payload.orderId, { status: "processed" });
+  },
+});
+```
+
+`meta` shape: `{ env, user, requestId, projectId, environmentId }`. Branch env
+vars are in `meta.env`; services come from the imported singletons.
+
+Enqueue from an endpoint:
+
+```ts
+import { Queue } from "@palbase/backend";
+await Queue.push("process-order", { orderId: "ord_1", amount: 1000 });
+```
+
+## Jobs (cron-scheduled)
+
+A job runs on a cron schedule. File lives under `jobs/`.
+
+```ts
+// jobs/cleanup.ts
+import { defineJob, Database, Log } from "@palbase/backend";
+
+export default defineJob({
+  name: "cleanup-expired",
+  schedule: "0 3 * * *",       // standard cron
+  timeout: 120,                // optional, seconds
+  handler: async (meta) => {
+    const expired = await Database.findMany("sessions", { expired: true });
+    for (const s of expired) await Database.delete("sessions", s.id as string);
+    Log.info(`cleaned ${expired.length} sessions in ${meta.projectId}`);
+  },
+});
+```
+
+`meta` shape: `{ env, projectId, environmentId }`. No `user` (jobs are
+system-initiated).
+
+
+
+<!-- ===== events.md ===== -->
+
+# Hooks & Webhooks
+
+Like workers/jobs, hooks and webhooks use the **singleton model** — the same
+imported service singletons as endpoints (`import { Database, Log } from
+"@palbase/backend"`). They do **not** receive a `req`. A second `meta` argument
+carries the non-service data (`env`, `projectId`, `environmentId`; webhooks also
+get `requestId`).
+
+## Hooks (platform events)
+
+React to auth, storage, and document events. Files live under `hooks/`. Builders
+are imported from `@palbase/backend`: `auth`, `storage`, `documents`.
+
+```ts
+// hooks/auth.ts
+import { auth, Database, Log } from "@palbase/backend";
+
+export const onUserCreated = auth.onUserCreated(async (event, meta) => {
+  Log.info(`new user: ${event.user.email}`);
+  await Database.insert("profiles", {
+    user_id: event.user.id,
+    email: event.user.email,
+  });
+});
+
+export const onSignIn = auth.onSignIn(async (event, meta) => {
+  Log.info(`sign in: ${event.user.email} via ${event.provider}`);
+});
+```
+
+`meta` shape: `{ env, projectId, environmentId }`. Branch env vars are in
+`meta.env`; services come from the imported singletons.
+
+Available hook builders: `auth.onUserCreated`, `auth.onSignIn`, `auth.onSignOut`,
+`auth.onPasswordReset`, `storage.onFileUploaded`, `storage.onFileDeleted`,
+`documents.onDocumentCreated`, `documents.onDocumentUpdated`,
+`documents.onDocumentDeleted`.
+
+## Webhooks (inbound provider events)
+
+Receive and verify webhooks from third-party providers. Files live under
+`webhooks/`.
+
+```ts
+// webhooks/stripe.ts
+import { defineWebhook, Database, Log } from "@palbase/backend";
+
+export default defineWebhook({
+  provider: "stripe",
+  secret: { env: "STRIPE_WEBHOOK_SECRET" },   // signing secret resolved from env
+  events: {
+    "checkout.session.completed": async (event, meta) => {
+      await Database.insert("orders", { status: "paid", data: event });
+    },
+    "payment_intent.payment_failed": async (event, meta) => {
+      Log.error("payment failed");
+      await Database.insert("payment_failures", { data: event });
+    },
+  },
+});
+```
+
+The signing secret is resolved by the runtime from `secret: { env: "NAME" }`;
+your handlers access branch env vars via `meta.env`. The runtime verifies the
+signature before dispatching to your event handlers.
+
+`meta` shape: `{ env, requestId, projectId, environmentId }`.