@palbase/backend 17.4.0 → 18.0.0

package/template/AGENTS.md

@@ -0,0 +1,261 @@
+# Palbase backend project
+
+This project runs inside the Palbase backend runtime. You author TypeScript; the
+runtime discovers it and serves it as a typed HTTP API, and generates the client
+SDKs your apps call. Routing is explicit: a controller is a **class** whose
+methods are routes.
+
+Everything comes from one package:
+
+```ts
+import { Controller, Get, Post, Patch, Delete, Body, QueryParams, Param, User, z, Database, Secrets, Conflict, NotFound } from "@palbase/backend";
+```
+
+> Needs `experimentalDecorators: true` — already set in this scaffold's
+> `tsconfig.json`. They are legacy decorators; there is no `reflect-metadata`.
+
+## What is here
+
+```
+controllers/<name>.controller.ts   a @Controller class; each method is a route
+db/schema.ts                       the database: tables, columns, RLS policies
+config/secrets.ts                  the secrets this backend needs (names only)
+```
+
+Two folders appear as the project grows, and both are conventions the tooling
+already understands:
+
+```
+models/<controller>/<endpoint>.ts  zod schemas, once they outgrow the controller
+services/<name>.service.ts         business logic, calls Database/Cache/Storage
+```
+
+Put logic in a service. Keep controller methods thin — they validate through the
+decorator schemas and delegate. Do not call `Database` from a controller.
+
+## Controllers — a class of routes
+
+`@Controller("/base", { auth? })` sets the base path and an optional default auth
+for every route in the class. Each route is a method decorated with
+`@Get/@Post/@Put/@Patch/@Delete/@Query("<subpath>", { auth? })`. The served path
+is `base + subpath`.
+
+**The class does not have to be exported.** `@Controller` records the class, so
+importing the file IS the registration — there is no module to list it in.
+
+The generated clients name a call `<class minus "Controller", lowercased>.<method>`:
+`TodosController.list` is `pb.todos.list()`. The verb and the path do not affect
+it, so restructure paths freely — but renaming a class or a method renames the
+call in every app. Those two names are your public API.
+
+```ts
+// controllers/todos.controller.ts
+import { Controller, Get, Post, Patch, Delete, Body, Param, User, NotFound } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+import { todoService } from "../services/todo.service";
+import { TodoSchema } from "../models/todos/shared";
+import { CreateTodoBody } from "../models/todos/create";
+
+@Controller("/todos")
+class TodosController {
+  private todos = todoService;
+
+  @Get("")
+  list(@User() user: UserT): Promise<TodoSchema[]> {
+    return this.todos.list(user.id);
+  }
+
+  @Post("")
+  create(@Body(CreateTodoBody) body: CreateTodoBody, @User() user: UserT): Promise<TodoSchema> {
+    return this.todos.create(user.id, body.title);
+  }
+
+  @Get("/{id}")
+  async get(@Param("id") id: string, @User() user: UserT): Promise<TodoSchema> {
+    const todo = await this.todos.get(user.id, id);
+    if (!todo) throw new NotFound("no todo with that id");
+    return todo;
+  }
+
+  @Delete("/{id}")
+  remove(@Param("id") id: string, @User() user: UserT): Promise<void> {
+    return this.todos.remove(user.id, id);
+  }
+}
+```
+
+### Parameter decorators — each request piece, injected
+
+| Decorator | Injects | Notes |
+|---|---|---|
+| `@Body(schema)` | request body | annotate `: T` (the same-named `z.infer` type) |
+| `@QueryParams(schema)` | query string | typed + validated → OpenAPI query params |
+| `@Param("id")` | one path param | typed `string` |
+| `@Headers(schema?)` | request headers | raw `Record<string,string>`; pass a schema to type + validate |
+| `@User()` | the signed-in user (`: UserT`, non-null) | `@OptionalUser()` (`UserT \| null`) on `auth: false` routes |
+| `@Client()` | parsed client info | name / version / platform |
+| `@RequestId()` / `@TraceId()` | ids | `: string` |
+| `@Req()` | the raw request | escape hatch |
+
+> `@User()` (value) and `UserT` (type) are imported separately —
+> `import { User } from "@palbase/backend"` and
+> `import type { UserT } from "@palbase/backend"` — because the value name
+> `User` is the decorator. Write `@User() user: UserT`.
+
+`@Query(subpath)` is the HTTP **QUERY** method (RFC 10008): a read that is safe
+and idempotent but carries a body. Its input goes in `@Body` — never combine it
+with `@QueryParams`.
+
+### Output and errors
+
+The 200 response **is** the method's return type, and it must NAME a zod schema.
+There is no response decorator: both the runtime's output validation and the
+client codegen read the annotation.
+
+```ts
+@Get("")        list(): Promise<TodoSchema[]>              // array (auto-wrapped in z.array)
+@Get("/{id}")   one(): Promise<TodoSchema>                 // one object
+@Get("/ping")   ping(): void                               // no response body
+```
+
+`: TodoSchema` (non-Promise) and `: Promise<z.infer<typeof TodoSchema>>` are
+equally valid. A **missing** annotation, an inline object (`Promise<{ ok: boolean }>`),
+a union, or a name with no matching zod schema in scope is a hard build error —
+name the schema.
+
+Throw a global error class from anywhere; no request object needed:
+
+```ts
+import { NotFound, Conflict, Forbidden, Unauthorized, BadRequest, TooManyRequests } from "@palbase/backend";
+
+throw new Conflict("title already taken");              // → 409, standard envelope
+throw new BadRequest({ fields: ["title"] });            // data-first: the data, then an optional message
+throw new TooManyRequests({ retryAfter: 30 });          // data-first
+```
+
+### Auth is on unless you opt out
+
+Every route requires a signed-in user by default. `@Controller("/x", { auth: false })`
+opens all of a class's routes; `@Get("", { auth: true })` overrides it for one.
+Resolution is route → controller → default `true`.
+
+## Models — schemas, one file per endpoint
+
+```ts
+// models/todos/create.ts
+import { z } from "@palbase/backend";
+export const CreateTodoBody = z.object({ title: z.string().min(1) });
+export type  CreateTodoBody = z.infer<typeof CreateTodoBody>;
+```
+
+Each name is a zod **value** (passed to `@Body`/`@QueryParams`, named by a return
+type) plus an optional same-named `z.infer` **type**, which is what lets the
+annotation read `Promise<TodoSchema>` instead of `Promise<z.infer<typeof TodoSchema>>`.
+Shared response schemas go in `models/<controller>/shared.ts`.
+
+## Services — business logic
+
+Plain classes exported as a singleton. No DI container, no decorators.
+
+```ts
+// services/todo.service.ts
+import { Database } from "@palbase/backend";
+
+export class TodoService {
+  list(userId: string) {
+    return Database.tables.todos.findMany({ user_id: userId });
+  }
+  create(userId: string, title: string) {
+    return Database.tables.todos.insert({ user_id: userId, title });
+  }
+}
+
+export const todoService = new TodoService();
+```
+
+`Database.tables.<name>` gives `insert`, `update(id, data)`, `delete(id)`,
+`findById(id)`, `findMany(filter?)`, and `Database.transaction(fn)` for a plan
+that commits or rolls back as one.
+
+## The database — declared, not migrated
+
+`db/schema.ts` is the database. There are no migration files to write, order, or
+reconcile; three verbs share one engine:
+
+- **plan** — what it would take to make the live database match the declaration
+- **apply** — make it match, in one transaction
+- **push** — ship the code, and REFUSE while the two still disagree
+
+That refusal is the point: code and schema move at different speeds, and a deploy
+that lands a handler against a column that does not exist yet fails at the first
+request, in production. So: edit `db/schema.ts`, plan, apply, then push.
+
+RLS is on by default and a table with no policies is deny-all. Add
+`policies: [policy(...)]` so Postgres enforces ownership — a query that forgets
+its `where user_id = …` still cannot read another user's rows.
+
+After a schema change, regenerate the typed surface so `Database.tables.*` keeps
+matching what is actually there (`palbase --help` names the command).
+
+## Config as code
+
+`config/*.ts` declares module configuration the same git-authoritative way the
+schema does, applied on deploy:
+
+- `config/secrets.ts` — `defineSecrets({ secrets: [secret("NAME", …)] })`
+- `config/storage.ts` — `defineStorage(...)` buckets
+- `config/notifications.ts` — `defineNotifications(...)` providers
+- `config/flags.ts` — `defineFlags(...)` feature flags
+
+### Secrets
+
+A secret's **value** never enters this repository. `config/secrets.ts` declares
+the NAME and whether it is required; the value lives in the environment's vault
+and reaches the process through `Secrets.get("NAME")`:
+
+```ts
+import { Secrets } from "@palbase/backend";
+const dsn = await Secrets.get("SENTRY_DSN"); // string | null
+```
+
+Declaring it is what turns a missing secret into a refused push that names it,
+instead of a 500 on the first request that touches it. Never read
+`process.env` for one, and never commit a `.env`.
+
+Provider certs and keys are the same rule: author them with the guided CLI,
+which uploads the file to the vault and writes only the non-secret fields into
+`config/notifications.ts`.
+
+## Tests
+
+`npm test` runs Node's own test runner over every `*.test.ts`. Nothing to
+install and nothing to configure — Node discovers the files and strips the types
+itself.
+
+Test the **service** layer. Controllers are thin by construction, so the logic
+that can be wrong lives in a service, which is a plain class you construct
+directly. A service that needs `Database` takes it as a constructor argument
+instead of importing the singleton, and the test passes a stand-in.
+
+Node **strips** types, it never emits code, so TypeScript features that require
+emitted code are refused outright: parameter properties (`constructor(private x: T)`),
+`enum`, and `namespace` all fail with `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. The
+refusal is per FILE, so one parameter property anywhere in a test's import graph
+takes down every test in that file at once — it reads like a dozen broken tests
+and is one keyword. Assign fields in the constructor body; use a `const` object
+or a union instead of `enum`; use a module instead of `namespace`.
+
+Node's ESM resolver wants the extension on relative imports, so a test imports
+`./todo.service.ts`, not `./todo.service`. This scaffold's `tsconfig.json`
+allows that.
+
+`npm test` answers "is the logic right". It is not the deploy's own validation —
+decorators, return types, SDK major — which answers "would this ship".
+
+## Commands and the full reference
+
+This file deliberately does not list the CLI surface: commands change, and a copy
+inside your repository goes stale silently. `palbase --help` is authoritative.
+
+The complete SDK reference — controllers, models, schema, services, errors,
+jobs, hooks, webhooks — lives at <https://app.dev.palbase.studio/docs/backend>.

package/template/config/secrets.ts

@@ -0,0 +1,24 @@
+import { defineSecrets, secret } from "@palbase/backend";
+
+// The secrets this backend needs, declared next to the code that needs them.
+//
+// This file holds NAMES, never values. A value lives only in the environment's
+// vault and reaches the process through `Secrets.get("NAME")`; nothing here —
+// and nothing in the repository this is committed to — ever holds one.
+//
+// Declaring the requirement is what makes a missing secret a sentence on your
+// terminal instead of a 500 on the first request that touches it: `push`
+// compares this list against the target environment's vault and refuses,
+// naming what is missing, before anything ships.
+//
+// `required` defaults to true. The example below is optional because the
+// backend genuinely runs without it — a required secret in a fresh scaffold
+// would just block your first deploy. Delete it and declare your own.
+export default defineSecrets({
+  secrets: [
+    secret("SENTRY_DSN", {
+      required: false,
+      description: "crash reporting endpoint — errors go unreported without it",
+    }),
+  ],
+});

package/template/controllers/health.controller.ts

@@ -0,0 +1,30 @@
+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.
+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.
+//
+// The full path is the controller base + the method subpath, so this serves
+// `GET /health`. The generated clients call it `pb.health.check()` —
+// `<class minus "Controller", lowercased>.<method>`, never the verb or the
+// path. Renaming either renames the call in every app, so treat those two
+// names as your public API.
+//
+// Auth is required unless a route opts out. A health check is the rare route
+// that genuinely has no caller identity, hence `auth: false`.
+@Controller("/health", { auth: false })
+class HealthController {
+  @Get("")
+  check(): HealthResponse {
+    return { status: "ok" };
+  }
+}

package/template/db/schema.ts

@@ -0,0 +1,35 @@
+import { defineSchema, policy, text, timestamp, uuid } from "@palbase/backend";
+
+// `db/schema.ts` IS the database. There are no migration files to write, order,
+// or reconcile: the CLI diffs this declaration against the live database, shows
+// you what it would take to make them match, applies it in one transaction, and
+// REFUSES to push code while the two still disagree.
+//
+// Row-Level Security is on by default. A table with RLS and no policies is
+// deny-all — the correct starting state, because nothing reads a table until a
+// policy says who may. `notes` below is scoped to its owner; delete it and
+// declare your own.
+export default defineSchema({
+  tables: {
+    notes: {
+      columns: {
+        id: uuid().primaryKey().defaultRandom(),
+        // A real foreign key to the tenant's own `auth.users`, so deleting an
+        // account takes its rows with it instead of leaving orphans an erasure
+        // request cannot reach. The referenced id is text, so this column is.
+        user_id: text().notNull().referencesAuthUser("cascade"),
+        body: text().notNull(),
+        created_at: timestamp().defaultNow(),
+      },
+      policies: [
+        // Postgres enforces ownership, not the handler: a query that forgets
+        // its `where user_id = …` still cannot see another user's rows.
+        policy("notes_owner")
+          .for("all")
+          .to("authenticated")
+          .using("user_id = (select auth.uid())")
+          .withCheck("user_id = (select auth.uid())"),
+      ],
+    },
+  },
+});

package/template/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "palbase-backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A Palbase backend — class controllers, a declared database, and the secrets it needs.",
+  "scripts": {
+    "test": "node --test --experimental-strip-types",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@palbase/backend": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node"],
+    // The route decorators are legacy parameter decorators — no reflect-metadata,
+    // but they do not compile without this.
+    "experimentalDecorators": true,
+    // `npm test` runs Node's own test runner, whose ESM resolver requires the
+    // .ts extension on relative imports. This permits it; it does not require
+    // it, so imports elsewhere stay extensionless.
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "controllers/**/*.ts",
+    "models/**/*.ts",
+    "services/**/*.ts",
+    "config/**/*.ts",
+    "db/**/*.ts",
+    "*.d.ts"
+  ]
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024-present Palbase
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.