@palbase/backend 4.0.0 → 5.1.0

package/docs/README.md

@@ -4,10 +4,202 @@ 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.
+`app.get(...)`, no manual route registration, no `import express`. You author
+**class controllers** with method + parameter decorators (NestJS-style); the
+runtime wires them up.
 
-## Mental model (important)
+## AGENTS / AI codegen guide (read this first)
+
+If you are an AI generating a Palbase backend, this is the contract. Get these
+seven rules right and the deploy succeeds; get them wrong and it fails the
+deploy gate or the TypeScript compile.
+
+### Folder layout
+
+```
+controllers/<name>.controller.ts   # @Controller class + @Get/@Post/… route methods (the API surface)
+models/<controller>/<endpoint>.ts   # zod schemas — one folder per controller, one file per endpoint (+ shared.ts)
+services/<name>.service.ts          # plain class + singleton — the real logic (controllers stay thin)
+db/schema.ts                        # config-as-code Postgres schema (tables, columns, RLS) — auto-migrated on deploy
+```
+
+The four folders above are the daily surface. These also exist (own docs, linked
+below): `resources/` (external connections — [resources.md](./resources.md)),
+`seeds/` (seed data), `jobs/` + `workers/` (background — [background.md](./background.md)),
+`webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
+
+### The 7 rules (checklist)
+
+1. **`export default <ControllerClass>` is REQUIRED.** Every `controllers/*.controller.ts`
+   must default-export its `@Controller` class, or the deploy FAILS with a
+   "not a @Controller / non-controller export" error. Either `export default class X {}`
+   or a trailing `export default X;` — both work.
+2. **Methods that call a service are `async` and return `Promise<T>`.** Services
+   `await Database`, so they return promises; a sync return type on an async body
+   is a tsc error. Annotate `: Promise<TodoSchema>`, not `: TodoSchema`, whenever
+   the body awaits.
+3. **`@User()` (value) vs `UserT` (type) are two different imports.**
+   `import { User } from "@palbase/backend"` (the decorator) +
+   `import type { UserT } from "@palbase/backend"` (the user type). Write
+   `@User() user: UserT`. They are NOT the same symbol.
+4. **The method's RETURN TYPE names the response schema.** Write
+   `: Promise<TodoSchema>` (or `: Promise<z.infer<typeof TodoSchema>>`) — codegen
+   + the runtime read that named type to bind the 200 response zod schema. There
+   is no `@Returns` decorator. A body route with no named return type is a build
+   error; a method with no response body annotates `: Promise<void>` / `: void`.
+5. **Schemas live in `models/<controller>/<endpoint>.ts`,** exported as a zod
+   VALUE and a same-named `z.infer` TYPE. The controller imports them and writes
+   `@Body(CreateTodoBody) body: CreateTodoBody` (value in the decorator, same name
+   as the type annotation).
+6. **Errors are global throw classes.** `throw new Conflict("…")` / `NotFound` /
+   `BadRequest` / `Unauthorized` / `Forbidden` / `TooManyRequests` /
+   `PalError(status, code, msg)` — from a controller OR a service, with no `req`.
+   There is no per-route errors map and no `req.errors`.
+7. **Auth is secure-by-default.** Every route needs a signed-in user unless it
+   opts out: `@Controller("/x", { auth: false })` (whole controller) or
+   `@Get("", { auth: false })` (one route). Cascade: route > controller >
+   default(required). On a public route inject `@OptionalUser() user: UserT | null`.
+
+> **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
+> `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
+> and will not compile against `@palbase/backend` 4.
+
+### Complete CRUD example (copy-pasteable, compiles)
+
+```ts
+// models/todos/shared.ts — the response shape, reused across endpoints.
+import { z } from "@palbase/backend";
+export const TodoSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  completed: z.boolean(),
+});
+export type TodoSchema = z.infer<typeof TodoSchema>;
+```
+
+```ts
+// models/todos/create.ts — the POST body.
+import { z } from "@palbase/backend";
+export const CreateTodoBody = z.object({ title: z.string().min(1) });
+export type CreateTodoBody = z.infer<typeof CreateTodoBody>;
+```
+
+```ts
+// services/todo.service.ts — plain class + singleton. The real work.
+import { Database, NotFound } from "@palbase/backend";
+import type { TodoSchema } from "../models/todos/shared.js";
+
+export class TodoService {
+  list(userId: string): Promise<TodoSchema[]> {
+    return Database.tables.todos.findMany({ user_id: userId });
+  }
+  create(userId: string, title: string): Promise<TodoSchema> {
+    return Database.tables.todos.insert({ user_id: userId, title });
+  }
+  async get(userId: string, id: string): Promise<TodoSchema> {
+    const t = await Database.tables.todos.findById(id);
+    if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
+    return t;
+  }
+  async remove(userId: string, id: string): Promise<void> {
+    const t = await Database.tables.todos.findById(id);
+    if (!t || t.user_id !== userId) throw new NotFound("No todo with that id");
+    await Database.tables.todos.delete(id);
+  }
+}
+export const todoService = new TodoService();
+```
+
+```ts
+// controllers/todos.controller.ts — class controller. Thin: delegates to the service.
+import { Controller, Get, Post, Delete, Body, Param, User } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";       // the user TYPE (@User is the value)
+import { todoService } from "../services/todo.service.js";
+import { TodoSchema } from "../models/todos/shared.js";
+import { CreateTodoBody } from "../models/todos/create.js";
+
+@Controller("/todos")                                  // secure-by-default; { auth: false } opts the whole controller out
+export class TodosController {
+  private todos = todoService;
+
+  @Get("")                                             // GET /todos → operationId getTodos
+  async list(@User() user: UserT): Promise<TodoSchema[]> {  // return type → 200 response schema
+    return this.todos.list(user.id);
+  }
+
+  @Post("")                                            // POST /todos → postTodos
+  async create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.create(user.id, body.title);
+  }
+
+  @Get("/{id}")                                        // GET /todos/{id} → getTodosById
+  async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.get(user.id, id);
+  }
+
+  @Delete("/{id}")                                     // DELETE /todos/{id} → deleteTodosById; no body → : Promise<void>
+  async remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
+    await this.todos.remove(user.id, id);
+  }
+}
+
+export default TodosController;                         // REQUIRED — the runtime loads the default export
+```
+
+```ts
+// db/schema.ts — config-as-code; the deploy auto-migrates additive changes.
+import { defineSchema, uuid, text, boolean, timestamp, policy } from "@palbase/backend";
+export default defineSchema({
+  tables: {
+    todos: {
+      columns: {
+        id:         uuid().primaryKey().defaultRandom(),
+        user_id:    text().notNull(),                  // palauth user id (TEXT, e.g. "usr_…")
+        title:      text().notNull(),
+        completed:  boolean().default(false),
+        created_at: timestamp().defaultNow(),
+      },
+      rls: true,                                       // every Database.* query runs as the request user
+      policies: [
+        policy("pb_owner_all")
+          .for("all")
+          .to("authenticated")
+          .using("user_id = (select auth.uid())")
+          .withCheck("user_id = (select auth.uid())"),
+      ],
+    },
+  },
+});
+```
+
+### operationId — what the generated clients call
+
+The operationId is derived FLAT from the verb + full path (NOT the method name):
+`GET /todos` → `getTodos`, `POST /todos` → `postTodos`, `GET /todos/{id}` →
+`getTodosById`. The generated iOS/TS clients expose these as `pb.getTodos()`,
+`pb.postTodos(...)`, `pb.getTodosById(id:)`. Rename the method freely; the
+operationId is unaffected. Change the verb and the operationId changes — no file
+rename needed.
+
+### CLI workflow
+
+- `palbase serve` — run `controllers/` locally with hot reload (proxies
+  `Database`/services to the deployed branch; runs `gen-types` on startup).
+- `palbase gen-types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
+  `Database.tables.*` is typed (no import, no generic). Standalone version of what
+  `serve` runs.
+- **Deploy is GitHub-native** — `git push` triggers the deploy (there is no
+  `palbase push`). Push a branch to deploy that branch.
+- `palbase secret set NAME=value` / `palbase secret list` — branch-scoped
+  secrets (encrypted at rest), read in code via `process.env.NAME`.
+- `palbase secret pull` / `palbase secret push` — sync the branch's env vars with
+  a local `.env.local` (gitignored). `pull` writes decrypted values for local dev
+  (merging local-only keys); `push` uploads changed keys (new keys default to
+  SECRET and need `--secret`/`--plain` classification, existing secrets are left
+  untouched unless `--force-secrets`).
+- `tsconfig.json` needs `"experimentalDecorators": true` (the scaffold sets it).
+
+## Mental model
 
 Every handler type imports service singletons the same way:
 
@@ -35,6 +227,7 @@ the imported singletons — not from `ctx` or any argument.
 ```
 my-backend/
 ├── package.json            # depends on @palbase/backend
+├── tsconfig.json           # experimentalDecorators: true (required for the decorators)
 ├── controllers/            # @Controller classes: @Get/@Post methods (mount the API)
 │   └── hello.controller.ts # @Controller("/hello") + @Get example
 ├── models/<ctrl>/<ep>.ts   # zod schemas, folder per controller, file per endpoint
@@ -42,6 +235,8 @@ my-backend/
 ├── services/               # plain classes/singletons your controllers call
 ├── db/schema.ts            # table definitions (optional, enables typed DB)
 ├── db/migrations/          # explicit SQL migrations for type changes (optional)
+├── resources/              # external connections, set up once at boot (optional)
+├── seeds/                  # seed data (optional)
 ├── workers/                # background job handlers (optional)
 ├── jobs/                   # cron-scheduled jobs (optional)
 ├── hooks/                  # auth/storage/document event hooks (optional)
@@ -64,9 +259,12 @@ HTTP endpoints are **not** file-path routed. You author a class controller
 | 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) |
+| Resources (external connections) | [resources.md](./resources.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)).
+</content>
+</invoke>

package/docs/config.md

@@ -0,0 +1,100 @@
+# Module Config (config-as-code)
+
+Beyond `db/schema.ts`, three more module surfaces are git-authoritative: storage
+buckets, notification providers, and feature-flag definitions. You declare them
+in `config/*.ts` files (typed, imported from `@palbase/backend`) and on `git
+push` the deploy creates/updates them. Secrets (certs, keys, API tokens) NEVER
+go in git — they live in a reserved encrypted env namespace, uploaded by the
+guided CLI.
+
+You normally author these with `palbase <module> add …` (the CLI writes the
+config file + uploads any secret); the files below are what it generates.
+
+## Storage buckets — `config/storage.ts`
+
+```ts
+import { defineStorage, bucket } from "@palbase/backend";
+
+export default defineStorage({
+  buckets: {
+    avatars: bucket({
+      public: true,                       // served without a signed URL
+      fileSizeLimit: "5MB",               // "5MB"/"20MB"/"1GB" or a byte number
+      allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
+    }),
+    invoices: bucket({ public: false, fileSizeLimit: "20MB", allowedMimeTypes: ["application/pdf"] }),
+  },
+});
+```
+
+Author it: `palbase storage buckets add avatars --public --max-size 5MB --mime image/png,image/jpeg`.
+On deploy, the buckets are created/updated. A bucket REMOVED from the file is
+**never auto-deleted** (its files would be lost) — drop it explicitly in Studio.
+The files inside a bucket are runtime state, not config.
+
+## Notification providers — `config/notifications.ts`
+
+Providers carry secrets (APNs `.p8`, FCM service-account JSON, Twilio token).
+The config file is **structural** — it names the enabled providers + their
+non-secret fields; the secret is bound by convention to a reserved env key and
+NEVER appears in git.
+
+```ts
+import { defineNotifications } from "@palbase/backend";
+
+export default defineNotifications({
+  push: {
+    apns: { enabled: true, teamId: "A1B2C3D4E5", keyId: "XYZ123", bundleId: "net.example.app" },
+    // no p8 key here — it's in the reserved secret PB_NOTIFICATIONS_APNS_P8
+  },
+  sms: {
+    twilio: { enabled: true, accountSid: "AC...", messagingServiceSid: "MG..." },
+  },
+});
+```
+
+Author it with the guided CLI — it knows each provider's fields and uploads the
+secret for you, so you never type a secret-name string:
+
+```bash
+palbase notifications providers          # list the catalog + what's configured
+palbase notifications add apns \
+  --team-id A1B2C3D4E5 --key-id XYZ123 --bundle-id net.example.app \
+  --p8-file ./AuthKey_XYZ123.p8          # → uploads PB_NOTIFICATIONS_APNS_P8 (encrypted)
+palbase notifications add twilio --account-sid AC... --messaging-sid MG...
+                                          # prompts for the auth token (hidden)
+```
+
+The reserved secret env keys (`PB_NOTIFICATIONS_*`) are managed by these
+commands — `palbase secret set PB_*` is refused. Your own custom env
+(`MY_API_KEY` etc.) is unaffected and still flows via `.env.local`. On deploy,
+each enabled provider's reserved secret is resolved and the provider is
+configured; a provider whose secret is missing is skipped (warned, not fatal).
+
+## Feature flags — `config/flags.ts`
+
+Flag DEFINITIONS (key, type, default) are config; the value set for a specific
+user / an A/B assignment is runtime (set via the SDK/Studio, not git).
+
+```ts
+import { defineFlags, flag } from "@palbase/backend";
+
+export default defineFlags({
+  flags: {
+    new_checkout: flag({ type: "boolean", default: false, description: "Gate the redesigned checkout" }),
+    upload_limit: flag({ type: "number", default: 10 }),
+    theme:        flag({ type: "string", default: "system", variants: ["light", "dark", "system"] }),
+  },
+});
+```
+
+Author it: `palbase flags add new_checkout --type boolean --default false`. On
+deploy, the definitions are upserted to the flags service (idempotent). A flag
+removed from the file is **not auto-deleted** (orphan definitions are harmless).
+
+## How it's applied
+
+All three are evaluated + applied **in your backend pod on deploy**, the same
+place `db/schema.ts` migrations run — the pod reaches each module through your
+project's gateway with a service-role key. The apply is fail-soft: a config
+error logs a warning but never aborts the deploy of your code.

package/docs/endpoints.md

@@ -12,22 +12,20 @@ imported singletons (see [services.md](./services.md)).
 
 ```ts
 // controllers/rooms.controller.ts
-import { Controller, Get, Post, Returns, Body, Param, User, NotFound, Database } from "@palbase/backend";
+import { Controller, Get, Post, Body, Param, User, NotFound, Database } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
 import { CreateRoomBody } from "../models/rooms/create.js";
-import { RoomSchema } from "../models/rooms/shared.js";
+import type { RoomSchema } from "../models/rooms/shared.js";  // the return TYPE names the 200 schema
 
 @Controller("/rooms")
 export default class RoomsController {
   @Post("")
-  @Returns(RoomSchema)
   async create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
     const room = await Database.insert("rooms", { name: body.name, capacity: body.capacity ?? null });
     return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
   }
 
   @Get("/{id}")
-  @Returns(RoomSchema)
   async getOne(@Param("id") id: string): Promise<RoomSchema> {
     const room = await Database.findById("rooms", id);
     if (!room) throw new NotFound("Room does not exist", "room_not_found");
@@ -36,6 +34,19 @@ export default class RoomsController {
 }
 ```
 
+**Two non-negotiables** (the most common codegen mistakes):
+
+1. **`export default <Controller>` is REQUIRED.** Above it is
+   `export default class RoomsController`; the trailing form `export class
+   RoomsController {…}` + `export default RoomsController;` is equivalent. Without
+   a default export the deploy aborts with a "not a @Controller / non-controller
+   export" error — the runtime loads the file's default export.
+2. **A method that awaits a service is `async` + `Promise<T>`.** `Database`
+   returns promises, so a body that `await`s it cannot have a sync return type
+   (`: RoomSchema` on an `async` body is a `tsc` error). Both methods above are
+   `async` and return `Promise<RoomSchema>`. (A pure method that returns a literal
+   with no `await` may stay synchronous.)
+
 ## Method decorators
 
 `@Get`/`@Post`/`@Put`/`@Patch`/`@Delete` take `(subpath, options?)`:
@@ -73,10 +84,11 @@ name `User` is the `@User()` decorator.
 
 ## Output = return type
 
-The success response is the method's RETURN TYPE. Pair it with `@Returns(schema)`
-so the zod value drives the OpenAPI 200 response (the type annotation drives
-compile-time checking; the zod value is lossless for codegen). A method that
-returns nothing annotates `: void`.
+The success response is the method's RETURN TYPE — there is no `@Returns`
+decorator. Annotate `: Promise<RoomSchema>` (or `: Promise<z.infer<typeof
+RoomSchema>>`); codegen + the runtime read that named type to bind the OpenAPI
+200 response zod schema. A body route with no named return type is a build
+error. A method that returns nothing annotates `: void` (or `: Promise<void>`).
 
 ## Auth — controller default + route override cascade
 

package/docs/getting-started.md

@@ -3,7 +3,7 @@
 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
+## package.json + tsconfig.json
 
 Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
@@ -20,13 +20,33 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 }
 ```
 
+The controllers use **decorators**, so the `tsconfig.json` must set
+`experimentalDecorators: true` (the scaffold ships it):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "experimentalDecorators": true,
+    "noEmit": true
+  },
+  "include": ["controllers/**/*.ts", "models/**/*.ts", "services/**/*.ts", "db/**/*.ts", "*.d.ts"]
+}
+```
+
 ## 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.
+  `controllers/` locally but proxies `Database` and the service singletons to
+  the **deployed** branch, so the branch must already be deployed (serve tells
+  you to push first if it isn't). On startup it also runs `gen-types`. See
+  [migrations.md](./migrations.md) for the schema/migration side of this.
+- `palbase gen-types` — regenerate `palbase-env.d.ts` from `db/schema.ts` so
+  `Database.tables.*` is typed (no import, no generic). Run it standalone after
+  editing the schema, or rely on `palbase serve` running it for you.
 - **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`.
@@ -49,14 +69,14 @@ export type HelloResponse = z.infer<typeof HelloResponse>;
 Then write the controller in `controllers/hello.controller.ts`:
 
 ```ts
-import { Controller, Get, Returns, Query, OptionalUser } from "@palbase/backend";
+import { Controller, Get, Query, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
-import { GreetQuery, HelloResponse } from "../models/hello/greet.js";
+import { GreetQuery } from "../models/hello/greet.js";
+import type { HelloResponse } from "../models/hello/greet.js";  // the return TYPE names the 200 schema
 
 @Controller("/hello", { auth: false })
 export default class HelloController {
   @Get("")
-  @Returns(HelloResponse)
   greet(@Query(GreetQuery) q: GreetQuery, @OptionalUser() user: UserT | null): HelloResponse {
     return { message: `hello, ${q.name ?? "world"}!`, user: user?.id ?? null };
   }
@@ -64,6 +84,20 @@ export default class HelloController {
 ```
 
 This is served at `GET /hello`. The `@Query` schema validates the query string;
-the method's return type (paired with `@Returns(HelloResponse)`) validates and
-describes the response. See [routing.md](./routing.md) and
-[endpoints.md](./endpoints.md) for the full class-controller model.
+the method's RETURN TYPE (`: HelloResponse`) names the response schema — codegen
++ the runtime read it to validate and describe the 200 response. There is no
+`@Returns` decorator; a body route with no named return type is a build error.
+
+Two things every controller file MUST have:
+
+- **A default export of the `@Controller` class.** Above it is `export default class
+  HelloController` (inline); the equivalent trailing form is `export class
+  HelloController {…}` then `export default HelloController;`. Without a default
+  export the deploy fails ("not a @Controller").
+- **`async` + `Promise<T>` once the method awaits a service.** `greet` above is
+  synchronous (pure), so it returns `HelloResponse` directly. The moment a method
+  calls a service that awaits `Database`, make it `async` and return
+  `Promise<HelloResponse>`.
+
+See [routing.md](./routing.md) and [endpoints.md](./endpoints.md) for the full
+class-controller model.