@palbase/backend 33.0.1 → 33.0.2

package/dist/openapi/index.js

@@ -7,7 +7,7 @@ import {
   isController,
   resolveController,
   resolveEffectiveAuth
-} from "../chunk-BRLJOXWS.js";
+} from "../chunk-AAT5G7KY.js";
 import {
   __commonJS,
   __name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "33.0.1",
+  "version": "33.0.2",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {

package/template/AGENTS.md

@@ -44,7 +44,7 @@ shape you find there is the shape to copy.
 | A business rule, a calculation, an ordering | the service |
 | Return an HTTP status | `throw new NotFound(…)` in the controller (or the service — no request object needed) |
 | Call another feature | name its class in your constructor — its module must `exports` it and yours must `imports` that module |
-| Scheduled or background work | a `@Job` class in `jobs/` — **there is no queue** |
+| Scheduled or background work | a `@Job` class listed in a module's `providers` — **there is no queue** |
 | Read a setting or a secret | `Secrets.get(name)` / `Flags.isEnabled(name)` — the names are checked by the compiler |
 | Share code between controllers | a plain module they import; not a base class, not middleware |
 
@@ -86,12 +86,12 @@ wrong in this runtime:
 - **An inline return type** — `Promise<{ ok: boolean }>`, a union, or a bare
   `interface`. The deploy REFUSES it; name a zod schema.
 
-**A controller is exported by NAME, and no file is default-exported.** Its module
-imports it (`import { NotesController } from "./notes.controller"`) to
-list it in `controllers` — that list is the registration, and a class no list
-names is refused at build. (`export default` **is** required for `jobs/`,
-`webhooks/`, `hooks/` and `db/public.ts`, one class per file — those are read off
-disk by name, not through a module.)
+**A controller is exported by NAME, and no file is default-exported.** Its module imports
+it (`import { NotesController } from "./notes.controller"`) to list it in `controllers`;
+that list is the registration. `@Job`, `@Webhook`, `@Hook` and `@Room` go in the same
+module's `providers`. There is no `jobs/`, `webhooks/` or `hooks/` directory and nothing
+reads one — a surface class no module lists is never imported, so its decorator never
+runs and nothing says so. Only the schema is read by location: `db/*.ts`, one per schema.
 
 **Class and method names are your public API.** `NotesController.list` generates
 `pb.notes.list()`. Renaming either renames the call in every app; the verb and the

package/template/modules/health/health.controller.ts

@@ -3,15 +3,18 @@ import { Controller, Get, z } from "@palbase/backend";
 // A route's success response IS its return type — a NAMED zod schema, read by
 // both the runtime (output validation) and the client codegen. Small projects
 // declare it beside the route; once a controller grows, move the schemas to
-// `models/<controller>/<endpoint>.ts` and import them.
+// `dto/<endpoint>.ts` inside the same module and import them — the way
+// `modules/notes/dto/create.ts` does.
 export const HealthResponse = z.object({
   status: z.string(),
 });
 export type HealthResponse = z.infer<typeof HealthResponse>;
 
-// A controller is a CLASS whose methods are routes. There is no module to
-// register it in and no export to remember: `@Controller` records the class,
-// and importing the file is the registration.
+// A controller is a CLASS whose methods are routes, and `health.module.ts`
+// beside this file is what REGISTERS it: the module imports the class by name
+// and lists it in `controllers`. That list is the registration — a class no
+// module names is refused at build, by name. `@Controller` describes the class;
+// it does not enrol it, and neither does the folder the file sits in.
 //
 // The full path is the controller base + the method subpath, so this serves
 // `GET /health`. The generated clients call it `pb.health.check()` —

package/template/modules/notes/dto/create.ts

@@ -1,8 +1,9 @@
 import { z } from "@palbase/backend";
 
-// SCHEMAS LIVE HERE once a controller has more than a screen of them:
-// `models/<controller>/<endpoint>.ts`. Nothing discovers this directory — it is
-// an ordinary import path — so the shape is yours. What is NOT optional is the
+// SCHEMAS LIVE HERE once a controller has more than a screen of them: the
+// module's own `dto/<endpoint>.ts`, which is where this file sits. Nothing
+// discovers this directory — it is an ordinary import path — so the shape is
+// yours. What is NOT optional is the
 // double export below.
 //
 // Each name is exported TWICE, under the SAME name:

package/template/modules/notes/notes.controller.ts

@@ -4,7 +4,7 @@ import type { UserT } from "@palbase/backend";
 import { CreateNoteBody, NoteSchema } from "./dto/create";
 import { NoteService } from "./note.service";
 
-// The other half of the vertical that starts in `services/note.service.ts`.
+// The other half of the vertical that starts in `./note.service.ts`.
 //
 // Everything a controller does here is HTTP: validate the body through a named
 // schema, name the 200 shape as the return type, turn a missing row into a
@@ -22,12 +22,14 @@ import { NoteService } from "./note.service";
 // container builds the graph once at boot.
 //
 // A class no module lists does not exist — it is refused at build, by name, and
-// never reaches the route table or the OpenAPI document. Being in `controllers/`
-// grants nothing; being in a module's list is what does.
+// never reaches the route table or the OpenAPI document. WHERE the file sits
+// grants nothing: the bundler walks the tree for `*.module.ts` and reads
+// nothing else, so a class reached by no module is never even imported. Being
+// in a module's list is what does it.
 
-// The schemas are in `models/notes/create.ts`. A controller with one endpoint
-// can keep them beside the routes; the moment there are two, they go to
-// `models/`, and this scaffold ships them already moved — because the shape you
+// The schemas are in `./dto/create.ts`. A controller with one endpoint can keep
+// them beside the routes; the moment there are two, they go to the module's
+// `dto/`, and this scaffold ships them already moved — because the shape you
 // find here is the shape the next file copies.
 
 // Auth is required unless a route opts out, so `@User()` is non-null here and