@palbase/backend 32.0.0 → 33.0.1

package/docs/database.md

@@ -7,8 +7,9 @@ jobs, hooks, and webhooks all use the same import:
 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).
+There is no `ctx` and no `ctx.db` anywhere on a path that runs — every handler
+imports `Database` (see [background.md](./background.md) and
+[events.md](./events.md) for the job/hook/webhook examples).
 
 ## Typed by default — `Database.<şema>.<tablo>`
 
@@ -76,7 +77,9 @@ await Database.public.crew_presence.findMany({
     AND: [sqlFragment`expires_at > now()`],
   },
 });
-``` The same filter language works for `updateMany`, `deleteMany`,
+```
+
+The same filter language works for `updateMany`, `deleteMany`,
 `count` and `search` — one language, so two spellings cannot drift apart. An
 empty `in` list means NO rows (written into the SQL as `false`), never a silent
 full scan.
@@ -372,7 +375,7 @@ filter object built from request input that happened to come back empty — is
 exactly the shape that must not silently succeed. `count()` with no filter IS
 allowed: counting is a read.
 
-### `Database.query` — raw SQL
+### `Database.$query` — raw SQL
 
 Use it for shapes the helpers do not cover (joins, aggregates, window functions).
 It runs in **the request's own transaction**, not a read-only one: a write inside
@@ -397,7 +400,7 @@ per row with a `23505` caught around each:
 
 ```ts
 await Database.$transaction((tx) => {
-  tx.tables.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
+  tx.public.merchants.insertMany(rows, { onConflict: ["name"], action: "ignore" });
   return null;
 });
 ```
@@ -454,11 +457,11 @@ middle, so nothing holds a database connection open while your code thinks.
 import { Database, NotFound } from "@palbase/backend";
 
 const { orderId } = await Database.$transaction((tx) => {
-  const order = tx.tables.orders
+  const order = tx.public.orders
     .insert({ amount: 1000, status: "pending" })
     .expectOne(new NotFound("order could not be created"));
 
-  tx.tables.order_items.insertMany(
+  tx.public.order_items.insertMany(
     cart.map((line) => ({ order_id: order.id, sku: line.sku })),
   );
 
@@ -514,7 +517,7 @@ filter plus an expectation — which is also stronger, because the check and the
 write are now the same statement and nothing can slip between them:
 
 ```ts
-tx.tables.invites
+tx.public.invites
   .updateWhere({ token, accepted_at: null }, { accepted_at: now() })
   .expectOne(new Conflict("invite already used", "invite_used"));
 ```
@@ -554,7 +557,7 @@ await Database.public.accounts.updateMany({
 
 // Inside a plan: the same expression, the same meaning.
 await Database.$transaction((tx) => {
-  tx.tables.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
+  tx.public.accounts.updateWhere({ id: accountId }, { balance: decrement("5.00") });
   return null;
 });
 ```
@@ -660,7 +663,8 @@ Sometimes you need to read or write **across all users** — an admin endpoint,
 background job that fans out notifications, a cleanup task. For that, call
 `Database.$asService()`. It returns a sibling client that runs as
 **`backend_service_role`** (the role that carries `BYPASSRLS`), exposing the
-exact same surface — `tables`, the raw string ops, and `transaction`:
+exact same surface — `public` (and every other schema), the `$`-prefixed raw ops,
+and `$transaction`:
 
 ```ts
 import { Database } from "@palbase/backend";
@@ -669,32 +673,32 @@ import { Database } from "@palbase/backend";
 const mine = await Database.public.todos.findMany({});
 
 // Service-role bypass: every user's rows. Explicit and greppable.
-const all  = await Database.$asService().tables.todos.findMany({});
-const rows = await Database.$asService().query("SELECT count(*) FROM todos");
+const all  = await Database.$asService().public.todos.findMany({});
+const rows = await Database.$asService().$query("SELECT count(*) FROM todos");
 
 // A service-role transaction (the role is fixed for the whole plan):
-await Database.$asService().transaction((tx) => {
-  tx.tables.todos.updateWhere({ id }, { done: true });
+await Database.$asService().$transaction((tx) => {
+  tx.public.todos.updateWhere({ id }, { done: true });
   return null;
 });
 ```
 
 Guidelines:
 
-- **Be explicit.** Prefer the default `Database.*` and reach for `asService()`
+- **Be explicit.** Prefer the default `Database.*` and reach for `$asService()`
   only where you genuinely need cross-user access. It is intentionally easy to
   grep for in review.
 - **No double-bypass / no nesting.** The sibling does not re-expose
-  `asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
+  `$asService()`, and `tx` never exposes it — a plan's role is fixed for the whole
   transaction. Use `Database.$transaction(...)` for an authenticated one and
-  `Database.$asService().transaction(...)` for a service-role one; you cannot mix
+  `Database.$asService().$transaction(...)` for a service-role one; you cannot mix
   enforced and bypassed operations inside a single plan.
 - **It is a second transaction, on a second connection.** It has to be: the
   Postgres role is bound once, when the transaction opens, so a sibling sharing
   the request's transaction would run as `backend_authenticated` and silently
   keep filtering. Three consequences worth knowing:
   - The request opens it at most once, however many times you call
-    `asService()`, and never at all if you don't use it.
+    `$asService()`, and never at all if you don't use it.
   - Both settle with the request — commit when your handler returns, roll back
     when it throws — but they settle as two transactions. A row written through
     one surface is **not visible** to the other until the request commits.

package/docs/endpoints.md

@@ -2,36 +2,41 @@
 
 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`/`@Query`. 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`/`@QueryParams`/
-`@Param`/`@User`/…), each piece direct — no `req` god-object. Services are reached via the
-imported singletons (see [services.md](./services.md)).
+`@Patch`/`@Delete`/`@Query`. A controller lives in its domain's folder
+(`modules/<domain>/<name>.controller.ts`) and a `@Module` lists it in
+`controllers` — that list is the registration, not the directory (see
+[routing.md](./routing.md)). Request input + context are injected into the method
+via **parameter decorators** (`@Body`/`@QueryParams`/`@Param`/`@User`/…), each
+piece direct — no `req` god-object. Your own services arrive through the
+CONSTRUCTOR and the container supplies them (see [services.md](./services.md)).
 
 ## A controller
 
 ```ts
-// controllers/rooms.controller.ts
+// modules/rooms/rooms.controller.ts
 import { Controller, Get, Post, Body, Param, User } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
-import { roomService } from "../services/room.service.js";
-import { CreateRoomBody } from "../models/rooms/create.js";
-import type { RoomSchema } from "../models/rooms/shared.js";  // the return TYPE names the 200 schema
+import { RoomService } from "./room.service";
+import { CreateRoomBody } from "./dto/create";
+import { RoomSchema } from "./dto/shared";     // the return TYPE names the 200 schema
 
 // A controller does not import `Database`. Everything here is HTTP: validate the
 // body through a named schema, name the 200 shape as the return type, delegate.
 // Which rows, whose, in what order is the service's job — and the service is the
 // thing worth testing, because it is the thing that can be wrong.
 @Controller("/rooms")
-export default class RoomsController {
+export class RoomsController {
+  // The service arrives through the constructor; `rooms.module.ts` lists both.
+  constructor(private readonly rooms: RoomService) {}
+
   @Post("")
   create(@Body(CreateRoomBody) body: CreateRoomBody, @User() user: UserT): Promise<RoomSchema> {
-    return roomService.create(user.id, body);
+    return this.rooms.create(user.id, body);
   }
 
   @Get("/{id}")
   getOne(@Param("id") id: string): Promise<RoomSchema> {
-    return roomService.get(id);
+    return this.rooms.get(id);
   }
 }
 ```
@@ -41,13 +46,14 @@ export default class RoomsController {
 1. **The controller does not touch the database.** It delegates to a service, as
    above. A method here that reaches for `Database` has moved the logic into the
    layer that is hardest to test. (Export the class by NAME so its module can
-   list it in `controllers`; a class no module lists is refused at build with
-   `unowned class`. Nothing here is default-exported.)
+   import it and list it in `controllers`; a class no module lists is refused at
+   build with `unowned class`. Nothing here is default-exported.)
 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.)
+   (`: RoomSchema` on an `async` body is a `tsc` error). Both methods above hand
+   the service's promise straight back, so they need no `await` — but they still
+   return `Promise<RoomSchema>`. (A pure method that returns a literal and touches
+   no promise may stay synchronous.)
 
 ## Method decorators
 
@@ -73,8 +79,8 @@ a query string — complex search/filter endpoints that would otherwise be a
 
 ```ts
 @Query("/search")
-async search(@Body(SearchTodosBody) body: SearchTodosBody): Promise<TodoSchema[]> {
-  return todoService.search(body);
+search(@Body(SearchTodosBody) body: SearchTodosBody): Promise<TodoSchema[]> {
+  return this.todos.search(body);
 }
 ```
 
@@ -121,7 +127,7 @@ out. Resolution order (most specific wins):
 
 ```ts
 @Controller("/public", { auth: false })          // all routes default public
-export default class PublicController {
+export class PublicController {
   @Get("/open") open(): Info { ... }              // inherits → public
   @Get("/secret", { auth: true })                 // OVERRIDES → authed
   secret(@User() u: UserT): Secret { ... }

package/docs/errors.md

@@ -7,9 +7,8 @@ Palbase error envelope:
 { "error": "todo_not_found", "error_description": "No such todo", "status": 404, "request_id": "req_…" }
 ```
 
-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.
+Throw anywhere — in a controller method OR in a service. No `req`, no per-route
+error map: the runtime catches any thrown error class and emits the envelope.
 
 The runtime refuses some requests before a handler runs, and those refusals use
 the same envelope and the same codes as the classes below — so a client decodes

package/docs/events.md

@@ -1,52 +1,86 @@
 # Hooks & Webhooks
 
-Like 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`, `environmentId`; webhooks also
-get `requestId`).
+Like jobs, `hooks/` and `webhooks/` stay at the ROOT — neither is part of a
+module — and both reach the platform services through the same import as
+everything else (`import { Database, Log } from "@palbase/backend"`). They do
+**not** receive a `req`. A second `meta` argument carries the non-service data
+(`env`, `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`.
+React to events this stack raises — auth, storage, documents. Files live under
+`hooks/`, one **default-exported class** per file, and the handlers are methods
+carrying a decorator. There are no builder functions to import.
+
+Two decorators, and the difference is whether the handler can stop the event:
+
+| | Where the event comes from | Can it block? |
+| --- | --- | --- |
+| `@Hook("before.…")` | this stack | **Yes** — `throw` cancels the operation |
+| `@On("after.…")` | this stack | No — a monitor; a throw reaches only the log |
+| `@Webhook` + `@On` | an OUTSIDE service | No — see the next section |
 
 ```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}`);
-});
+import { Database, Deny, Hook, Log, On } from "@palbase/backend";
+import type { AuthHookEvent, HookMeta } from "@palbase/backend";
+
+export default class AuthHooks {
+  // The gate. A throw CANCELS the signup and the reason reaches the caller.
+  @Hook("before.user.create")
+  async gate(event: AuthHookEvent, _meta: HookMeta): Promise<void> {
+    if ((event.user?.email ?? "").endsWith("@blocked.test")) {
+      throw new Deny("this address is not accepted");
+    }
+  }
+
+  // The monitor. It runs after the fact, so a throw here is logged and the
+  // session is not un-created.
+  @On("after.login.failed")
+  async record(event: AuthHookEvent, meta: HookMeta): Promise<void> {
+    Log.info(`failed login for ${event.user?.email ?? "(no email)"} req=${meta.requestId}`);
+    await Database.$insert("login_failures", { email: event.user?.email ?? null });
+  }
+}
 ```
 
-`meta` shape: `{ env, environmentId }`. Environment variables are in
-`meta.env`; services come from the imported singletons.
+`Deny` is exported for exactly this: any throw denies, but `Deny` carries the
+reason deliberately instead of surfacing whatever a stray `TypeError` said. The
+engine is fail-closed — an unreachable hook denies — so keep a blocking handler
+narrow.
 
-Available hook builders: `auth.onUserCreated`, `auth.onSignIn`, `auth.onSignOut`,
-`auth.onPasswordReset`, `storage.onFileUploaded`, `storage.onFileDeleted`,
-`documents.onDocumentCreated`, `documents.onDocumentUpdated`,
-`documents.onDocumentDeleted`.
+`meta` shape: `{ env, environmentId, requestId? }`. Environment variables are in
+`meta.env`; the platform services (`Database`, `Log`, …) are imported as
+singletons, never passed in.
+
+> **Warning:** `auth`, `storage` and `documents` builder objects —
+> `auth.onUserCreated(handler)`, `storage.onFileUploaded(handler)` and friends —
+> **were removed in 26.0.0** and this page taught them until 33.0.0. They were
+> not merely renamed: nothing in the runtime or the bundler ever read the record
+> they returned, so a project that wrote one got a handler that was **never
+> called and no error said so**. The types went with them for the same reason —
+> `UserCreatedEvent` promised `user.role`, `user.metadata` and `user.createdAt`
+> and the auth engine sends none of the three. If you have such a file, the
+> import now fails to build, which is the point.
 
 ## Webhooks (inbound provider events)
 
 Receive and verify webhooks from third-party providers. Files live under
-`webhooks/` — the URL is `POST /webhooks/<file-name>` (e.g. `webhooks/stripe.ts`
-→ `POST /webhooks/stripe`); there is no `path` option.
+`webhooks/`, one class per file, `export default` required.
+
+**`name` is required and DECLARED.** It is the path segment the webhook is served
+at — `POST /webhooks/<name>` — so `name: "stripe"` answers at
+`POST /webhooks/stripe`. It is not taken from the file name any more: a PUBLIC
+URL, the one a sender is configured with, belongs beside the provider and the
+secret rather than in the file system. Lowercase letters, digits and dashes.
 
 ```ts
 // webhooks/stripe.ts
 import { Database, Log, On, Webhook, type WebhookMeta } from "@palbase/backend";
 
-@Webhook({ provider: "stripe", secret: { env: "STRIPE_WEBHOOK_SECRET" } }) // signing secret resolved from env
+// name: the path segment (POST /webhooks/stripe); secret: the signing secret,
+// resolved by the runtime from the named env var.
+@Webhook({ name: "stripe", provider: "stripe", secret: { env: "STRIPE_WEBHOOK_SECRET" } })
 export default class StripeWebhook {
   @On("checkout.session.completed")
   async checkoutCompleted(event: unknown, meta: WebhookMeta) {

package/docs/getting-started.md

@@ -33,7 +33,8 @@ The controllers use **decorators**, so the `tsconfig.json` must set
     "experimentalDecorators": true,
     "noEmit": true
   },
-  "include": ["controllers/**/*.ts", "models/**/*.ts", "services/**/*.ts", "db/**/*.ts", "*.d.ts"]
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", ".palbase"]
 }
 ```
 
@@ -43,7 +44,7 @@ Your backend runs on Palbase, not on your laptop — there is no local runtime t
 start. The loop is: edit, validate, push to a dev Environment.
 
 - `palbase build` — validate the tree the way the deploy will. It stages and
-  bundles your `controllers/` exactly as the deploy does and runs the deploy's
+  bundles your `modules/` exactly as the deploy does and runs the deploy's
   own metadata extractor over the result, so a bad decorator, an illegal return
   type or an SDK major skew fails here rather than shipping a deploy that
   serves zero endpoints. It is wired into a `pre-push` git hook for you. It also
@@ -57,10 +58,10 @@ start. The loop is: edit, validate, push to a dev Environment.
 
 ## Your first endpoint
 
-An endpoint is a method on a class controller. Declare the schemas in `models/`:
+An endpoint is a method on a class controller. Everything for one domain lives in `modules/<domain>/`; declare the schemas in its `dto/`:
 
 ```ts
-// models/hello/greet.ts
+// modules/hello/dto/greet.ts
 import { z } from "@palbase/backend";
 
 export const GreetQuery = z.object({ name: z.string().optional() });
@@ -70,13 +71,13 @@ export const HelloResponse = z.object({ message: z.string(), user: z.string().nu
 export type HelloResponse = z.infer<typeof HelloResponse>;
 ```
 
-Then write the controller in `controllers/hello.controller.ts`:
+Then write the controller in `modules/hello/hello.controller.ts`:
 
 ```ts
 import { Controller, Get, QueryParams, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";
-import { GreetQuery } from "../models/hello/greet.js";
-import type { HelloResponse } from "../models/hello/greet.js";  // the return TYPE names the 200 schema
+import { GreetQuery } from "./dto/greet.js";
+import type { HelloResponse } from "./dto/greet.js";  // the return TYPE names the 200 schema
 
 @Controller("/hello", { auth: false })
 export default class HelloController {