@palbase/backend 3.0.0 → 4.0.0

package/docs/endpoints.md

@@ -1,105 +1,126 @@
 # 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)).
+An endpoint is a **method on a class controller** — a class decorated with
+`@Controller(basePath)` whose methods are decorated with `@Get`/`@Post`/`@Put`/
+`@Patch`/`@Delete`. Controller files live under `controllers/` and are mounted
+automatically (see [routing.md](./routing.md)). Request input + context are
+injected into the method via **parameter decorators** (`@Body`/`@Query`/`@Param`/
+`@User`/…), each piece direct — no `req` god-object. Services are reached via the
+imported singletons (see [services.md](./services.md)).
 
-## `defineHandler` config
+## A controller
 
 ```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
-});
+// controllers/rooms.controller.ts
+import { Controller, Get, Post, Returns, 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";
+
+@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");
+    return { id: room.id as string, name: room.name as string, capacity: (room.capacity as number) ?? null };
+  }
+}
 ```
 
-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`.
+## Method decorators
+
+`@Get`/`@Post`/`@Put`/`@Patch`/`@Delete` take `(subpath, options?)`:
 
-## `req` (PBRequest)
+```ts
+interface RouteOptions {
+  auth?: boolean | { required?: boolean; role?: string };  // overrides controller default
+  rateLimit?: { max: number; window: number };             // optional, per route
+}
+```
 
-| 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) |
+Input and output are NOT method-decorator options: input comes from the
+parameter decorators, output from the method's return type. The method decorator
+only carries route concerns (path, auth, rateLimit).
 
-`User` is `{ id: string; email?: string; role: string; metadata: Record<string, unknown> }`.
+## Parameter decorators
 
-## Auth
+| Decorator | Injects | Typed by | OpenAPI |
+|---|---|---|---|
+| `@Body(schema)` | request body | `: T` (`z.infer<schema>`, same name) | requestBody |
+| `@Query(schema)` | query params | `: T` | query parameters |
+| `@Param("id")` | one path param | `: string` | path parameter |
+| `@Headers(schema?)` | request headers | `Record<string,string>` (+ typed with schema) | header parameters |
+| `@User()` | authenticated user | `: UserT` | — (from token) |
+| `@OptionalUser()` | user, possibly anon | `: UserT \| null` | — |
+| `@Client()` | parsed client info | `: ClientInfo` | — |
+| `@RequestId()` / `@TraceId()` | correlation ids | `: string` | — |
+| `@Req()` | raw request (escape hatch) | `: PBRequest` | — |
 
-**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 }`.
+`@Body`/`@Query`/`@Headers` take a zod schema (validation + codegen source); the
+developer writes the matching type annotation (same name). `UserT` is the
+authenticated-user type (`{ id: string; email?: string; role: string; metadata:
+Record<string, unknown> }`) — exported under the alias `UserT` because the value
+name `User` is the `@User()` decorator.
 
-```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)
-```
+## Output = return type
 
-Whether `req.user` is non-null is computed from the `auth` config at the type
-level (and matches the runtime exactly):
+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`.
 
-| `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` |
+## Auth — controller default + route override cascade
 
-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.
+**Secure by default:** a route requires authentication UNLESS it explicitly opts
+out. Resolution order (most specific wins):
 
-## Typed input/output
+1. Route-level `@Post("", { auth })` — wins if present.
+2. Controller-level `@Controller("/x", { auth })` — applies to routes without
+   their own `auth`.
+3. Default `true` (secure-by-default).
 
 ```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 };
-  },
-});
+@Controller("/public", { auth: false })          // all routes default public
+export default class PublicController {
+  @Get("/open") open(): Info { ... }              // inherits → public
+  @Get("/secret", { auth: true })                 // OVERRIDES → authed
+  secret(@User() u: UserT): Secret { ... }
+}
 ```
 
-A controller then mounts it with a method + path:
+| effective `auth` | `@User()` type to annotate |
+|------------------|----------------------------|
+| required (omitted / `true` / `{ required: true }` / role-only) | `@User() u: UserT` |
+| public (`false` / `{ required: false }`) | `@OptionalUser() u: UserT \| null` |
+
+The runtime always applies the resolved effective auth; the static type you
+annotate is best-effort (a parameter decorator cannot see the controller default
+at the type level).
+
+## Errors — global throw classes
+
+Throw an error class anywhere (controller OR service) — no `req`, no per-route
+map. The runtime catches it and emits the standard envelope:
 
 ```ts
-// controllers/rooms.controller.ts
-import { defineController, route } from "@palbase/backend";
-import create from "../handlers/rooms/create.js";
+import { Conflict, NotFound, BadRequest, Unauthorized, Forbidden, TooManyRequests, PalError } from "@palbase/backend";
 
-export default defineController("/rooms", {
-  create: route.post("/", create),
-});
+throw new Conflict("title taken");            // → 409
+throw new NotFound();                         // → 404 ("Not found")
+throw new PalError(418, "teapot", "custom");  // → custom status/code
 ```
 
+See [errors.md](./errors.md) for the full set + the wire envelope shape.
+
 ## Middleware
 
 A middleware wraps a request. Define one in `middleware/<name>.ts`:
@@ -116,19 +137,4 @@ export default defineMiddleware(async (ctx, next) => {
 ```
 
 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 }),
-});
-```
+rest of the chain (other middleware, then the endpoint method).

package/docs/errors.md

@@ -1,47 +1,54 @@
 # Errors
 
-Two ways to fail a request. Both serialize to the standard Palbase error
-envelope:
+Throw an error class to fail a request. Every one serializes 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)
+Throw anywhere — in a controller method OR in a `services/` class. No `req`, no
+per-route error map: the runtime catches any thrown error class and emits the
+envelope.
+
+## Named status classes
 
 ```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 });
+import { BadRequest, Unauthorized, Forbidden, NotFound, Conflict, TooManyRequests } from "@palbase/backend";
+
+throw new Conflict("title taken");      // → 409  ("conflict" code by default)
+throw new NotFound();                   // → 404  ("not_found", "Not found")
+throw new BadRequest("missing field");  // → 400
+throw new Unauthorized();               // → 401
+throw new Forbidden();                  // → 403
+throw new TooManyRequests();            // → 429
 ```
 
-`new HttpError(status, code, description, data?)`.
+Each class fixes its HTTP status. The constructor is
+`new <Class>(message?, code?, data?)`:
 
-## 2. Declared errors (typed)
+- `message` overrides the human-readable `error_description` (defaults to a label
+  derived from the class name).
+- `code` overrides the wire `error` code (defaults to the class's snake_case
+  code, e.g. `not_found`).
+- `data` rides along under the envelope's `data` field for structured context.
 
-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
+throw new NotFound("Room does not exist", "room_not_found");
+throw new Conflict("locked", "title_locked", { retryAfter: 30 });
+```
+
+## `PalError` / `HttpError` (custom status)
+
+For a status/code not covered by a named class:
 
 ```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 };
-  },
-});
+import { PalError } from "@palbase/backend";
+throw new PalError(418, "teapot", "I'm a teapot");
+// optional structured payload (4th arg) rides along under `data`:
+throw new PalError(423, "todo_locked", "Locked", { retryAfter: 30 });
 ```
 
-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.
+`PalError` (and its base `HttpError`) take `(status, code, description, data?)`.
+The named classes all extend `HttpError`, so `catch (e) { if (e instanceof
+HttpError) … }` matches any of them.

package/docs/getting-started.md

@@ -33,33 +33,37 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
 ## Your first endpoint
 
-A handler is one endpoint unit; a controller maps method+path to it. Create
-`handlers/hello.ts`:
+An endpoint is a method on a class controller. Declare the schemas in `models/`:
 
 ```ts
-import { defineHandler, z } from "@palbase/backend";
+// models/hello/greet.ts
+import { 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,
-  }),
-});
+export const GreetQuery = z.object({ name: z.string().optional() });
+export type GreetQuery = z.infer<typeof GreetQuery>;
+
+export const HelloResponse = z.object({ message: z.string(), user: z.string().nullable() });
+export type HelloResponse = z.infer<typeof HelloResponse>;
 ```
 
-Then mount it in `controllers/hello.controller.ts`:
+Then write the controller in `controllers/hello.controller.ts`:
 
 ```ts
-import { defineController, route } from "@palbase/backend";
-import hello from "../handlers/hello.js";
+import { Controller, Get, Returns, Query, OptionalUser } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { GreetQuery, HelloResponse } from "../models/hello/greet.js";
 
-export default defineController("/hello", {
-  hello: route.get("/", hello),
-});
+@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 };
+  }
+}
 ```
 
-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.
+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.