@palbase/backend 2.0.2 → 4.0.0

package/docs/errors.md

@@ -1,48 +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 endpoint; 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 { defineEndpoint, z, Database } from "@palbase/backend";
-
-export default defineEndpoint({
-  method: "POST",
-  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/events.md

@@ -1,8 +1,10 @@
 # Hooks & Webhooks
 
-Like workers/jobs, hooks and webhooks use the **`ctx` model** (`ctx.db`,
-`ctx.log`, `ctx.cache`, `ctx.queue`, `ctx.env`) — not `req`, and not imported
-singletons.
+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)
 
@@ -11,21 +13,24 @@ are imported from `@palbase/backend`: `auth`, `storage`, `documents`.
 
 ```ts
 // hooks/auth.ts
-import { auth } from "@palbase/backend";
+import { auth, Database, Log } from "@palbase/backend";
 
-export const onUserCreated = auth.onUserCreated(async (ctx, event) => {
-  ctx.log.info(`new user: ${event.user.email}`);
-  await ctx.db.insert("profiles", {
+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 (ctx, event) => {
-  ctx.log.info(`sign in: ${event.user.email} via ${event.provider}`);
+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`,
@@ -38,22 +43,25 @@ Receive and verify webhooks from third-party providers. Files live under
 
 ```ts
 // webhooks/stripe.ts
-import { defineWebhook } from "@palbase/backend";
+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 (ctx, event) => {
-      await ctx.db.insert("orders", { status: "paid", data: event });
+    "checkout.session.completed": async (event, meta) => {
+      await Database.insert("orders", { status: "paid", data: event });
     },
-    "payment_intent.payment_failed": async (ctx, event) => {
-      ctx.log.error("payment failed");
-      await ctx.db.insert("payment_failures", { data: event });
+    "payment_intent.payment_failed": async (event, meta) => {
+      Log.error("payment failed");
+      await Database.insert("payment_failures", { data: event });
     },
   },
 });
 ```
 
-The signing secret is read from the project's env/secrets (`{ env: "NAME" }`);
-the runtime verifies the signature before dispatching to your event handlers.
+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 }`.

package/docs/getting-started.md

@@ -13,7 +13,6 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
   "private": true,
   "scripts": {
     "dev": "palbase serve",
-    "deploy": "palbase push",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": { "@palbase/backend": "latest" },
@@ -23,27 +22,48 @@ Your project depends on the SDK and uses the Palbase CLI for the dev loop:
 
 ## Local dev loop
 
-- `palbase serve` — run your backend locally with hot reload.
-- `palbase push` — deploy the current directory to your project's backend runtime.
-- `palbase push --branch <name>` — deploy to a branch instead of `main`.
+- `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
 
-Create `endpoints/hello/get.ts`:
+An endpoint is a method on a class controller. Declare the schemas in `models/`:
 
 ```ts
-import { defineEndpoint, z } from "@palbase/backend";
-
-export default defineEndpoint({
-  method: "GET",
-  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,
-  }),
-});
+// models/hello/greet.ts
+import { z } from "@palbase/backend";
+
+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 write the controller in `controllers/hello.controller.ts`:
+
+```ts
+import { Controller, Get, Returns, Query, OptionalUser } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { GreetQuery, HelloResponse } from "../models/hello/greet.js";
+
+@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.
+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.