@palbase/backend 2.0.2 → 4.0.0

package/docs/llms.txt

@@ -1,6 +1,6 @@
 # Palbase Backend SDK (`@palbase/backend`)
 
-> File-based TypeScript backend SDK. Endpoints use `req` (PBRequest) + imported service singletons (`Database`, `Cache`, …). Workers/jobs/hooks/webhooks use a `ctx` object. Not Express, not Supabase Edge Functions.
+> 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.
 
 ## Docs
 
@@ -10,7 +10,9 @@
 - [endpoints](./endpoints.md)
 - [database](./database.md)
 - [schema](./schema.md)
+- [migrations](./migrations.md)
 - [services](./services.md)
+- [resources](./resources.md)
 - [errors](./errors.md)
 - [background](./background.md)
 - [events](./events.md)

package/docs/migrations.md

@@ -0,0 +1,98 @@
+# 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.

package/docs/resources.md

@@ -0,0 +1,94 @@
+# 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;
+```

package/docs/routing.md

@@ -1,34 +1,61 @@
-# File-based routing
+# Routing
 
-The path of a file under `endpoints/` plus its filename determine the route.
-The filename is the HTTP method.
+Routes are declared in code with **class controllers**. A controller is a class
+decorated with `@Controller(basePath)`; each route is a method decorated with
+`@Get`/`@Post`/`@Put`/`@Patch`/`@Delete`. Request input + context are injected
+into the method via **parameter decorators** (`@Body`/`@Query`/`@Param`/`@User`/
+…). Putting a controller file under `controllers/` mounts it — there is no
+central router and no manual registration.
 
-| File | Route |
-|------|-------|
-| `endpoints/hello/get.ts` | `GET /hello` |
-| `endpoints/items/post.ts` | `POST /items` |
-| `endpoints/posts/[id]/get.ts` | `GET /posts/:id` |
-| `endpoints/posts/[id]/patch.ts` | `PATCH /posts/:id` |
-| `endpoints/rooms/[id]/sessions/post.ts` | `POST /rooms/:id/sessions` |
+```ts
+import { Controller, Get, Post, Body, Query, Param, User } from "@palbase/backend";
+```
 
-Rules:
+## Controllers — class + method decorators
 
-- The method file name is one of `get`, `post`, `put`, `patch`, `delete` (`.ts`).
-- A `[segment]` directory becomes a `:segment` path param, read via `req.params.segment`.
-- Each method file `export default defineEndpoint({...})` — one endpoint per file.
-- There is no central router file and no manual registration. Adding a file adds a route.
+`@Controller(basePath)` marks the class and sets the mount path. Each route
+method declares its verb + subpath; the real work lives in a `services/` class
+(the controller method is thin).
 
 ```ts
-// endpoints/posts/[id]/get.ts  → GET /posts/:id
-import { defineEndpoint, z, Database, HttpError } from "@palbase/backend";
-
-export default defineEndpoint({
-  method: "GET",
-  output: z.object({ id: z.string(), title: z.string() }),
-  handler: async (req) => {
-    const post = await Database.findById("posts", req.params.id!);
-    if (!post) throw new HttpError(404, "post_not_found", "No such post");
-    return { id: post.id as string, title: post.title as string };
-  },
-});
+// controllers/places.controller.ts
+import { Controller, Get, Post, Returns, Body, User, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { placeService } from "../services/place.service.js";
+import { ImportNearbyBody } from "../models/places/import.js";
+import { PlaceSchema } from "../models/places/shared.js";
+
+@Controller("/places")
+export default class PlacesController {
+  @Post("/import")
+  @Returns(PlaceSchema)
+  importNearby(@Body(ImportNearbyBody) body: ImportNearbyBody, @User() user: UserT): PlaceSchema {
+    return placeService.importNearby(body.lat, body.lng, user.id);
+  }
+
+  @Get("/favorites", { auth: false })
+  @Returns(z.array(PlaceSchema))
+  listFavorites(): PlaceSchema[] {
+    return placeService.listFavorites();
+  }
+}
 ```
+
+| Method name (sugar) | Verb | Full path | operationId (flat) |
+|---|---|---|---|
+| `importNearby`  | POST | `/places/import`    | `postPlacesImport` |
+| `listFavorites` | GET  | `/places/favorites` | `getPlacesFavorites` |
+
+Rules:
+
+- The full path of a route is `basePath + subpath` (`"/places" + "/import"`).
+- A `{segment}` in a path becomes a path param, injected via `@Param("segment")`.
+- Input is declared with the parameter decorators — `@Body(schema)`,
+  `@Query(schema)`, `@Param("id")`, `@Headers(schema?)`. The success response is
+  the method's RETURN TYPE; pair it with `@Returns(schema)` so the zod value
+  drives the OpenAPI 200 response (or annotate `: void` for no body).
+- The operationId is derived FLAT from method + full path (`postPlacesImport`),
+  not from the method name. Change `@Post` → `@Put` — no file rename.
+
+See [endpoints.md](./endpoints.md) for the full decorator reference (`@Controller`
+options, the parameter decorators, auth cascade, and error classes).

package/docs/schema.md

@@ -1,36 +1,50 @@
 # Schema & typed database access
 
 Declare your tables in `db/schema.ts` with `defineSchema`. This drives
-migrations and, via `typedDatabase`, a fully-typed `.tables.*` API.
+[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`. Each table value is an
+object `{ columns, rls?, policies? }` — `columns` is required; `rls` and
+`policies` enable [Row-Level Security](#row-level-security-rls).
+
 ```ts
 import {
-  defineSchema, table,
+  defineSchema,
   uuid, text, integer, boolean, timestamp, jsonb, enumType,
 } from "@palbase/backend";
 
 export default defineSchema({
-  rooms: table("rooms", {
-    id: uuid().primaryKey().defaultRandom(),
-    name: text().notNull(),
-    capacity: integer().nullable(),
-    is_active: boolean().default(true),
-    created_at: timestamp().defaultNow(),
-  }),
-  sessions: table("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: table("orders", {
-    id: uuid().primaryKey().defaultRandom(),
-    status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
-    amount: integer().notNull(),
-  }),
+  tables: {
+    rooms: {
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        name: text().notNull(),
+        capacity: integer().nullable(),
+        is_active: boolean().default(true),
+        created_at: timestamp().defaultNow(),
+      },
+    },
+    sessions: {
+      columns: {
+        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: {
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        status: enumType("order_status", ["pending", "paid", "shipped", "cancelled"]),
+        amount: integer().notNull(),
+      },
+    },
+  },
 });
 ```
 
@@ -51,32 +65,139 @@ Chainable modifiers: `.primaryKey()`, `.notNull()` (default), `.nullable()`,
 `.defaultNow()` (timestamp → `now()`), `.references(table, column)`,
 `.onDelete("cascade" | "set null" | "restrict" | "no action")`.
 
-## Typed DB access
+## 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 { Controller, Post, Returns, Body, Database, z } from "@palbase/backend";
+
+const CreateRoomBody = z.object({ name: z.string() });
+const RoomOut = z.object({ id: z.string(), name: z.string() });
+
+@Controller("/rooms")
+export default class RoomsController {
+  @Post("")
+  @Returns(RoomOut)
+  async create(@Body(CreateRoomBody) body: z.infer<typeof CreateRoomBody>): Promise<z.infer<typeof RoomOut>> {
+    const room = await Database.tables.rooms.insert({ name: body.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.
 
-`typedDatabase(schema)` returns a typed facade. `insert` demands the right
-columns; rows come back typed; nullable columns are `T | null`.
+If you want a row type explicitly, import it from the generated env module:
 
 ```ts
-import { defineEndpoint, z, typedDatabase } from "@palbase/backend";
-import schema from "../../db/schema.js";
-
-const Db = typedDatabase(schema);
-
-export default defineEndpoint({
-  method: "POST",
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string(), name: z.string() }),
-  handler: async (req) => {
-    const room = await Db.tables.rooms.insert({ name: req.input.name });
-    return { id: room.id, name: room.name };
+import type { Tables } from "@palbase/backend/env";
+type Room = Tables["rooms"]["row"];
+```
+
+## Row-Level Security (RLS)
+
+RLS pushes per-user access control **into Postgres**: every `Database.*` query
+runs as the request's verified user (the `authenticated` role with that user's
+claims), and the database itself filters rows your policies don't allow. A
+missing `WHERE user_id = …` in your handler can no longer leak another user's
+rows — the policy enforces it. This is the recommended way to scope data per
+user.
+
+Add `policies` (and optionally `rls`) to a table. `policies` being non-empty
+implies `rls: true` automatically (a table with policies must have RLS enabled
+or the policies are inert). Set `rls: true` with no policies only as a
+deliberate deny-all intermediate step.
+
+### The `policy()` builder
+
+`policy(name)` is a fluent builder, just like the column builders:
+
+```ts
+import { policy } from "@palbase/backend";
+
+policy("pb_owner_all")
+  .for("all")                              // "all" | "select" | "insert" | "update" | "delete"
+  .to("authenticated")                     // one or more DB roles; .to() with no args = PUBLIC
+  .using("owner = (select auth.uid())")    // row-visibility filter (SELECT/UPDATE/DELETE)
+  .withCheck("owner = (select auth.uid())"); // write-validation (INSERT/UPDATE)
+```
+
+| Method | Default | Meaning |
+|--------|---------|---------|
+| `.for(cmd)` | `"all"` | The SQL command the policy governs. |
+| `.to(...roles)` | `["authenticated"]` | DB roles the policy applies to. `.to()` with no args targets PUBLIC. |
+| `.using(sql)` | none | `USING (...)` — which existing rows are visible (SELECT/UPDATE/DELETE). |
+| `.withCheck(sql)` | none | `WITH CHECK (...)` — which rows may be written (INSERT/UPDATE). |
+| `.as(mode)` | `"permissive"` | `"permissive"` (policies OR together) or `"restrictive"` (AND together). |
+
+**`auth.uid()`** returns the verified user's id (palauth user id, TEXT) from the
+request's JWT claims. Wrap it as `(select auth.uid())` — Postgres evaluates that
+once per statement (an initPlan) instead of once per row. `auth.role()` and
+`auth.jwt()` are also available. With no user on the request (anon/public),
+`auth.uid()` is `NULL`, so an `owner = (select auth.uid())` policy matches no
+rows.
+
+> Name policies with a `pb_` prefix. Palbase reconciliation only manages
+> policies it authored (`pb_`-prefixed) and never touches policies created by
+> other modules (storage, cron, …).
+
+### Owner-scoped `todos` example
+
+```ts
+import { defineSchema, policy, uuid, text, boolean, timestamp } from "@palbase/backend";
+
+export default defineSchema({
+  tables: {
+    todos: {
+      columns: {
+        id:         uuid().primaryKey().defaultRandom(),
+        owner:      text().notNull(),        // palauth user id (TEXT)
+        title:      text().notNull(),
+        done:       boolean().default(false),
+        created_at: timestamp().defaultNow(),
+      },
+      // `policies` non-empty ⇒ RLS is enabled + FORCEd automatically.
+      policies: [
+        // Read: a user sees only their own todos.
+        policy("pb_todos_owner_select")
+          .for("select")
+          .to("authenticated")
+          .using("owner = (select auth.uid())"),
+
+        // Write: a user can insert/update/delete only rows they own.
+        policy("pb_todos_owner_write")
+          .for("all")
+          .to("authenticated")
+          .using("owner = (select auth.uid())")
+          .withCheck("owner = (select auth.uid())"),
+      ],
+    },
   },
 });
 ```
 
-Note the `.js` extension on `../../db/schema.js` even though the file is
-`db/schema.ts` — this is standard ESM module resolution; you still author the
-file as `.ts`.
+With this in place, `await Database.tables.todos.findMany({})` returns only the
+calling user's rows — no `WHERE owner = …` needed in the handler. To read or
+write across all users (e.g. an admin job), use the explicit bypass:
+`Database.asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
+
+### How policies are applied
+
+On deploy, Palbase diffs your declared schema against the live database and
+applies RLS **additively**: it emits `ENABLE`/`FORCE ROW LEVEL SECURITY` only
+when the table doesn't already have it, and `CREATE POLICY` only for policies
+that don't already exist (keyed by `(table, name)`). These are non-destructive,
+so they apply without the `acceptDataLoss` confirmation that column drops need.
+
+> Changing a policy's body (its `USING`/`WITH CHECK` SQL) in place is not yet
+> auto-applied — rename the policy (new `(table, name)`) or drop the old one in
+> a hand-written migration. Policy DROP/rewrite churn is a documented TODO.
 
-`Db.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
-`findById(id)`, `findMany(query?)`, and `Db.transaction(fn)` mirrors the
-untyped transaction with typed tables.

package/docs/services.md

@@ -1,8 +1,8 @@
 # Services
 
-In **endpoints**, import service singletons from `@palbase/backend`. In
-**workers/jobs/hooks/webhooks**, the equivalents live on `ctx` (`ctx.cache`,
-`ctx.queue`, `ctx.log`, `ctx.db`).
+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`.
@@ -90,16 +90,19 @@ await Notifications.sms.send({ /* PalbaseSmsSendParams */ });
 ## Flags
 
 ```ts
-import { defineEndpoint, z, Flags } from "@palbase/backend";
-
-export default defineEndpoint({
-  method: "GET",
-  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 });
+import { Controller, Get, Returns, User, Flags, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+
+const FlagsOut = z.object({ enabled: z.boolean() });
+
+@Controller("/checkout")
+export default class CheckoutController {
+  @Get("/flags")                       // auth omitted → required → user is non-null
+  @Returns(FlagsOut)
+  async flags(@User() user: UserT): Promise<z.infer<typeof FlagsOut>> {
+    const { data: enabled } = await Flags.isEnabled("new-checkout", { userId: user.id });
+    const { data: variant } = await Flags.getVariant("button-color", { userId: user.id });
     return { enabled: enabled ?? false };
-  },
-});
+  }
+}
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@palbase/backend",
-  "version": "2.0.2",
-  "description": "Palbase Backend SDK — defineEndpoint, context types, schema DSL",
+  "version": "4.0.0",
+  "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@Query/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -42,6 +42,16 @@
         "types": "./dist/db/index.d.cts",
         "default": "./dist/db/index.cjs"
       }
+    },
+    "./env": {
+      "import": {
+        "types": "./dist/db/env.d.ts",
+        "default": "./dist/db/env.js"
+      },
+      "require": {
+        "types": "./dist/db/env.d.cts",
+        "default": "./dist/db/env.cjs"
+      }
     }
   },
   "files": [