@palbase/backend 33.0.0 → 33.0.1

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 {