@palbase/backend 23.0.0 → 24.0.0

package/template/AGENTS.md

@@ -18,10 +18,19 @@ import { Controller, Get, Post, Patch, Delete, Body, QueryParams, Param, User, z
 
 ```
 controllers/<name>.controller.ts   a @Controller class; each method is a route
+services/<name>.service.ts         the logic, as a plain class
 db/schema.ts                       the database: tables, columns, RLS policies
-config/secrets.ts                  the secrets this backend needs (names only)
+palbase-stack.d.ts                 GENERATED — the names your stack actually holds
+palbase-env.d.ts                   GENERATED — your tables, as types
 ```
 
+Both generated files are written by `palbase build` and **committed**. They are
+what makes `Secrets.get("X")`, `Flags.isEnabled("y")`, `@Upload({ bucket })` and
+`Database.tables.*` compile: the names come from the stack and the schema, so
+there is no second list in this repo to drift out of date. A project that has
+never run `palbase build` has no valid names and those calls will not compile —
+that is the gate working, not a rough edge. Run it once and commit both files.
+
 Two folders appear as the project grows, and both are conventions the tooling
 already understands:
 
@@ -137,7 +146,18 @@ throw new TooManyRequests({ retryAfter: 30 });          // data-first
 
 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`.
+
+An application-wide default sits under those two:
+
+```ts
+import { defineDefaultAuth } from "@palbase/backend";
+defineDefaultAuth({ verifiedEmail: true });   // every route, unless it says otherwise
+```
+
+Put that call in `auth.ts` at the project root — the bundler imports that file by
+name, so the declaration cannot be silently left out of the build. Resolution is
+route → controller → application → `true`. Writing the same auth setting on ten
+controllers is how the eleventh one gets forgotten.
 
 ## Models — schemas, one file per endpoint
 
@@ -155,27 +175,53 @@ Shared response schemas go in `models/<controller>/shared.ts`.
 
 ## Services — business logic
 
-Plain classes exported as a singleton. No DI container, no decorators.
+Plain classes wired as a module-level singleton. No DI container, no decorators
+— and this is the ONLY supported way to hold a dependency anywhere in this
+runtime. A controller, hook, job or webhook is constructed with **no arguments**;
+one that declares a constructor parameter is refused at build with the class
+named, because there is no injector to fill it and the field would simply be
+`undefined` in production.
 
-```ts
-// services/todo.service.ts
-import { Database } from "@palbase/backend";
+`services/note.service.ts` in this scaffold is the worked example. The shape:
 
-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 });
-  }
+```ts
+export class NoteService {
+  private readonly notes: typeof Database.tables.notes;
+  // Assigned in the BODY — `constructor(private notes: …)` is a parameter
+  // property, and Node's type-stripping test runner refuses those per FILE.
+  constructor(notes: typeof Database.tables.notes) { this.notes = notes; }
+  list(userId: string) { return this.notes.findMany({ user_id: userId }); }
 }
 
-export const todoService = new TodoService();
+/** Controllers import THIS, never the class. */
+export const noteService = new NoteService(Database.tables.notes);
 ```
 
-`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 constructor is the seam: the class is handed the table rather than reaching
+for the singleton, so a test constructs it with a stand-in and never needs a
+database. `fakeDatabase()` from `@palbase/backend/test` is that stand-in when you
+want the whole surface instead of one table.
+
+`Database.tables.<name>` gives:
+
+| | |
+|---|---|
+| `insert(row)` · `upsert(row, { onConflict })` | write one |
+| `update(id, data)` · `delete(id)` | write one, by id |
+| `updateMany(where, set)` · `deleteMany(where)` | write every row the filter matches, in ONE statement |
+| `findById(id)` · `findMany(where?, opts?)` | read |
+| `count(where?)` | how many match |
+
+`where` takes a plain value for equality or an operator object —
+`{ n: { gte: 3 } }`, `{ id: { in: [...] } }`, also `gt` / `lt` / `lte` / `neq`.
+`opts` takes `{ orderBy: { column, direction }, limit, offset }`, so ordering and
+paging happen in SQL rather than in JavaScript after fetching everything.
+`updateMany`/`deleteMany` REFUSE an empty filter — a whole-table write is not
+something to reach by accident.
+
+`Database.transaction(fn)` runs a plan that commits or rolls back as one, and
+`Database.attempt(fn)` opens a savepoint so one failed write does not poison the
+rest of the request.
 
 ## The database — declared, not migrated
 
@@ -194,37 +240,62 @@ 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).
+After a schema change run `palbase build`: it regenerates BOTH generated files —
+`palbase-env.d.ts` (your tables) and `palbase-stack.d.ts` (the stack's names) —
+so `Database.tables.*` keeps matching what is actually there. Commit them.
 
-## Config as code
+## Secrets, flags, buckets — read from the stack
 
-`config/*.ts` declares module configuration the same git-authoritative way the
-schema does, applied on deploy:
+There is no `config/` directory and nothing to declare in this repo. Settings are
+written to the STACK with the CLI, and the code READS them:
 
-- `config/secrets.ts` — `defineSecrets({ secrets: [secret("NAME", …)] })`
-- `config/storage.ts` — `defineStorage(...)` buckets
-- `config/notifications.ts` — `defineNotifications(...)` providers
-- `config/flags.ts` — `defineFlags(...)` feature flags
+```ts
+import { Secrets, Flags } from "@palbase/backend";
+const dsn = await Secrets.get("SENTRY_DSN");     // compiles only if the stack holds it
+if (await Flags.isEnabled("newCheckout")) { … }  // same
+```
+
+The name in the quotes is checked by the compiler against `palbase-stack.d.ts`,
+which `palbase build` generates from the stack. A secret's VALUE never enters
+this repository, and you never read `process.env` for one.
+
+Writing a setting is a CLI job, not a code job — `palbase --help` names the
+commands (`secret`, `flags`, `storage`, `notifications`, `auth`). Settings have
+one door; a second one is how the two come to disagree.
 
-### Secrets
+## Lifecycle — for things that are expensive to build
 
-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")`:
+Most handlers need nothing here: the SDK's singletons are already pooled. But a
+long-lived object you build yourself needs somewhere to close, and a process that
+never closes one leaks it per deploy:
 
 ```ts
-import { Secrets } from "@palbase/backend";
-const dsn = await Secrets.get("SENTRY_DSN"); // string | null
+import { onStart, onShutdown } from "@palbase/backend";
+
+let client: SomeClient | undefined;
+onStart("graph", () => { client = SomeClient.create({ maxPoolSize: 8 }); });
+onShutdown("graph", async () => { await client?.close(); });
 ```
 
-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`.
+The NAME is the first argument, and it is what a failure is reported by — a stack
+trace through an anonymous closure names nothing. `onStart` runs ONCE as the app
+comes up, and a hook that throws refuses the boot rather than letting the app
+serve traffic with a half-built dependency. `onShutdown` hooks run in reverse
+order and are best-effort: one that throws is reported and the rest still run.
 
-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`.
+**These hooks run OUTSIDE a request, so no Palbase service is reachable from
+them** — `Secrets`, `Database`, `Log` and the rest all throw "accessed outside a
+request scope". If your object needs a secret, build it lazily on first use
+inside a handler instead:
+
+```ts
+let client: SomeClient | undefined;
+async function graph() {
+  client ??= SomeClient.create({ url: await Secrets.get("GRAPH_URL") });
+  return client;
+}
+onShutdown("graph", async () => { await client?.close(); });
+```
 
 ## Tests
 
@@ -233,9 +304,18 @@ install and nothing to configure — Node discovers the files and strips the typ
 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.
+that can be wrong lives in a service — a plain class you construct directly with
+a stand-in, exactly as `services/note.service.ts` is written. For a stand-in
+covering the whole database surface rather than one table:
+
+```ts
+import { fakeDatabase } from "@palbase/backend/test";
+const { db, queries } = fakeDatabase();
+```
+
+It answers `tables.*` from memory and records the `query` calls made. What it
+does NOT do is enforce RLS, constraints or unique violations — those are real
+database behaviour, and the test that proves them runs against a real one.
 
 Node **strips** types, it never emits code, so TypeScript features that require
 emitted code are refused outright: parameter properties (`constructor(private x: T)`),

package/template/controllers/notes.controller.ts

@@ -0,0 +1,64 @@
+import { Body, Controller, Delete, Get, NotFound, Param, Post, User, z } from "@palbase/backend";
+import type { UserT } from "@palbase/backend";
+
+import { noteService } from "../services/note.service";
+
+// The other half of the vertical that starts in `services/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
+// status. The logic — which rows, whose, in what order — lives in the service,
+// which is why the service is the thing worth testing and this class has
+// nothing in it to get wrong.
+//
+// So there is one rule, and it is the whole reason the layer exists: a
+// controller does not import `Database`. If a method here starts reaching for a
+// table, the logic has leaked into the layer that is hardest to test.
+//
+// The dependency is a MODULE-LEVEL SINGLETON, imported. It is not a constructor
+// parameter: the runtime constructs this class with no arguments, and a
+// controller that declares one is refused at build with the class named rather
+// than handed `undefined` in production.
+
+export const NoteSchema = z.object({
+  id: z.string(),
+  user_id: z.string(),
+  body: z.string(),
+  created_at: z.string(),
+});
+export type NoteSchema = z.infer<typeof NoteSchema>;
+
+export const CreateNoteBody = z.object({
+  body: z.string().min(1),
+});
+export type CreateNoteBody = z.infer<typeof CreateNoteBody>;
+
+// Auth is required unless a route opts out, so `@User()` is non-null here and
+// every method below acts as somebody.
+@Controller("/notes")
+class NotesController {
+  @Get("")
+  list(@User() user: UserT): Promise<NoteSchema[]> {
+    return noteService.list(user.id);
+  }
+
+  @Post("")
+  create(@Body(CreateNoteBody) body: CreateNoteBody, @User() user: UserT): Promise<NoteSchema> {
+    return noteService.create(user.id, body.body);
+  }
+
+  @Get("/{id}")
+  async get(@Param("id") id: string): Promise<NoteSchema> {
+    // `null` covers both "no such note" and "not yours" — the second is not
+    // distinguishable from the outside on purpose, because telling a caller
+    // that a row they may not read exists is itself a leak.
+    const note = await noteService.get(id);
+    if (!note) throw new NotFound("no note with that id");
+    return note;
+  }
+
+  @Delete("/{id}")
+  remove(@Param("id") id: string): Promise<void> {
+    return noteService.remove(id);
+  }
+}

package/template/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^23.0.0"
+    "@palbase/backend": "^24.0.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/template/services/note.service.ts

@@ -0,0 +1,74 @@
+import { Database } from "@palbase/backend";
+import type { Tables } from "@palbase/backend/env";
+
+// A SERVICE is where the logic lives. It is a plain class — no decorator, no DI
+// container, nothing to register. What makes the layer real is the two lines at
+// the bottom of this file, not the folder name.
+//
+// THE SEAM IS THE CONSTRUCTOR. The class is handed the table it works on rather
+// than reaching for the singleton itself, so a test constructs it with a
+// stand-in and never needs a database:
+//
+//   const svc = new NoteService(fakeNotesTable);
+//   assert.deepEqual(await svc.list("u_1"), []);
+//
+// The module then wires the real one ONCE, on the last line, and that instance
+// is what a controller imports. That module-level singleton is also the
+// supported way to hold a dependency ANYWHERE in this runtime: a controller,
+// hook, job or webhook is constructed with no arguments, and one that declares
+// a constructor parameter is refused at build with the class named — there is
+// no injector to fill it, so the field would simply be `undefined` in
+// production.
+//
+// `Database.tables.notes` is typed from `db/schema.ts` through the generated
+// `palbase-env.d.ts`, which `palbase build` writes. Before the first build that
+// file does not exist yet and the table is unknown to the type checker; build
+// once and the whole surface below is typed with no import and no generic.
+
+/** One row of `notes`, exactly as `db/schema.ts` declares it. */
+export type Note = Tables["notes"]["row"];
+
+/** The typed surface of one table: `insert`, `update`, `delete`, `findById`,
+ * `findMany`. Naming it here is what keeps the seam ONE table wide — a test
+ * fake implements five methods, not the whole `Database`. */
+type NotesTable = typeof Database.tables.notes;
+
+export class NoteService {
+  private readonly notes: NotesTable;
+
+  // Assigned in the BODY, never as a parameter property (`constructor(private
+  // notes: NotesTable)`). `npm test` runs Node's type-stripping test runner,
+  // which refuses parameter properties — and refuses them for the whole FILE,
+  // so one of them anywhere in a test's import graph reads like a dozen broken
+  // tests and is one keyword.
+  constructor(notes: NotesTable) {
+    this.notes = notes;
+  }
+
+  /** The caller's notes. The filter is written out even though the table's RLS
+   * policy already scopes the read to `auth.uid()`: the policy is the backstop
+   * that holds when a query forgets, not a reason to stop writing the query. */
+  list(userId: string): Promise<Note[]> {
+    return this.notes.findMany({ user_id: userId });
+  }
+
+  /** `user_id` is `notNull` with no default, so ownership is written here —
+   * it is not something the request body may carry. */
+  create(userId: string, body: string): Promise<Note> {
+    return this.notes.insert({ user_id: userId, body });
+  }
+
+  /** No `userId` argument, and that is not an oversight: another user's note is
+   * invisible to this read, so it comes back `null` exactly as a missing id
+   * does. Postgres enforces it, not this method. */
+  get(id: string): Promise<Note | null> {
+    return this.notes.findById(id);
+  }
+
+  remove(id: string): Promise<void> {
+    return this.notes.delete(id);
+  }
+}
+
+/** The wired instance. Controllers import THIS, never the class. */
+export const noteService = new NoteService(Database.tables.notes);

package/template/tsconfig.json

@@ -19,12 +19,22 @@
     // it, so imports elsewhere stay extensionless.
     "allowImportingTsExtensions": true
   },
+  // Every directory the deploy path compiles has to be in here, or a file in it
+  // is type-checked by nothing until it is already running: `jobs/`, `hooks/`
+  // and `webhooks/` are read straight off disk by the bundler (one default-
+  // exported class per file), and `middleware/` only reaches a build through
+  // whichever controller imports it. `config/` is gone — 23.0.0 removed the
+  // declarations it held, and the settings it used to declare are written to the
+  // stack with the CLI.
   "include": [
     "controllers/**/*.ts",
     "models/**/*.ts",
     "services/**/*.ts",
-    "config/**/*.ts",
     "db/**/*.ts",
+    "jobs/**/*.ts",
+    "hooks/**/*.ts",
+    "webhooks/**/*.ts",
+    "middleware/**/*.ts",
     "*.d.ts"
   ]
 }

package/dist/chunk-FSGSB42K.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["/**\n * runtime.ts — request-scoped service singletons.\n *\n * The backend SDK no longer threads a `ctx` god-object through every handler.\n * Instead, controller methods import PascalCase service singletons directly:\n *\n *   import { Controller, Post, Body, Database } from \"@palbase/backend\";\n *\n *   \\@Controller(\"/todos\")\n *   export default class TodosController {\n *     \\@Post(\"\") create(\\@Body(CreateTodoBody) body: CreateTodoBody): unknown {\n *       return Database.insert(\"todos\", { title: body.title });\n *     }\n *   }\n *\n * The singletons are thin Proxies. Every property access forwards to the live\n * client for the CURRENT request scope, resolved through {@link __getRuntime}.\n *\n * # Request-scope resolution (persistent app-server)\n *\n * The runtime is a long-running Node process that serves many concurrent\n * requests on one event loop (NOT a fresh subprocess per request). A single\n * module-global slot would let one in-flight request's services bleed into\n * another's. So the services are carried in an {@link AsyncLocalStorage} store\n * ({@link __requestALS}) that the runtime sets per request with\n * {@link __runWithRuntime}; every async continuation of that request reads its\n * own store. `__getRuntime` reads the ALS store first; the module-global slot\n * (set by {@link __setRuntime}) is only a fallback for callers that run OUTSIDE\n * an ALS scope (dev-server, unit tests, the legacy single-shot path). Because\n * each `br-<ref>` pod is single-tenant, there is no cross-tenant leakage; the\n * ALS store is what prevents cross-REQUEST leakage within the shared process.\n *\n * The seam that makes `import { Database } from \"@palbase/backend\"` resolve to\n * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL\n * when the tenant bundle is built, and the package is installed globally in the\n * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's\n * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared\n * module instance — the ALS store and `__setRuntime` slot on that instance are\n * visible to the singletons the bundle imported.\n */\n\nimport type { PalbaseFlagKey } from \"./stack.js\";\nimport type { Buckets, BucketTypes } from \"./db/env.js\";\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport type {\n  DBClient,\n  DBOps,\n  CacheClient,\n  Logger,\n  PalbaseDocsClient,\n  SecretsService,\n} from \"./endpoint.js\";\nimport type {\n  PalbaseStorageClient,\n  PalbaseBucketClient,\n  PalbaseNotificationsClient,\n  PalbaseFlagsClient,\n  PalbaseFlagsServiceClient,\n  PalbaseFlagContext,\n  PalbaseFlagVariant,\n  PalbaseFlag,\n  PalbaseFlagValue,\n  PalbaseSetOverrideResult,\n  PalbaseRealtimeClient,\n} from \"./clients.js\";\nimport type { PalbaseResult } from \"./endpoint.js\";\nimport type {\n  EnvTypedDatabase,\n  EnvServiceDatabase,\n  EnvTables,\n  TxPlan,\n  TxTables,\n} from \"./db/typed-db.js\";\nimport type { Materialized } from \"./db/tx-plan.js\";\nimport { TxPlanBuilder, runTxPlan } from \"./db/tx-plan.js\";\n\n/** The set of live clients the runtime injects per request scope.\n *\n * Realtime is BROADCAST-ONLY here (a stateless handler can push an event but\n * cannot hold a subscription socket — `subscribe()` lives on the client SDK).\n *\n * EXCLUDED on purpose: Functions, Links, Analytics, Auth. They are not\n * exposed as backend handler singletons (auth lives on the client SDK; the rest\n * are out of scope for backend endpoints). */\nexport interface RuntimeServices {\n  Database: DBClient;\n  Secrets: SecretsService;\n  Documents: PalbaseDocsClient;\n  Storage: PalbaseStorageClient;\n  Cache: CacheClient;\n  Log: Logger;\n  Notifications: PalbaseNotificationsClient;\n  Flags: PalbaseFlagsClient;\n  Realtime: PalbaseRealtimeClient;\n}\n\n/**\n * The per-request ALS box.\n *\n * `runtime` is the service bundle. `userId` is the request's authenticated user\n * id, written by the runtime immediately after it assembles the request object\n * (worker.js: `requestALS.getStore().userId = pbReq.user?.id || null`) and\n * `null` on an anonymous request. It was already being written there for the\n * Flags client's auto-bind; declaring it here makes the existing contract typed\n * instead of implicit, which is what lets `currentSubjectId()` read a\n * server-owned identity rather than trusting anything the caller sent.\n */\nexport interface RequestStore {\n  runtime: RuntimeServices;\n  userId?: string | null;\n  /** This request's id (`req_…`), written by the runtime. Used as the spend\n   * idempotency scope when the caller supplied no `Idempotency-Key`. */\n  requestId?: string;\n  /** The caller's `Idempotency-Key` header, or `null` when absent. What makes a\n   * client's retry replay its first result instead of charging twice. */\n  idempotencyKey?: string | null;\n}\n\n/**\n * Per-request store. The persistent runtime runs each request inside\n * {@link __runWithRuntime}, so every async continuation of that request reads\n * its OWN `runtime` (and any other request-scoped fields the runtime adds).\n *\n * Exported with a `__` prefix so the runtime (worker.js) shares the SAME ALS\n * instance across the one module instance — two ALS instances would silently\n * not see each other's stores. NOT part of the public author-facing API.\n */\nexport const __requestALS = new AsyncLocalStorage<RequestStore>();\n\n/** Process-global fallback slot. Used only OUTSIDE an ALS scope (dev-server,\n * unit tests, legacy single-shot worker). Inside the persistent server every\n * request runs in {@link __requestALS}, which takes precedence. */\nlet runtime: RuntimeServices | null = null;\n\n/** Install the live clients in the process-global fallback slot.\n *\n * Persistent-server requests should use {@link __runWithRuntime} instead; this\n * remains for dev-server / tests / the legacy single-shot path that run without\n * an ALS scope. NOT part of the public author-facing API. */\nexport function __setRuntime(services: RuntimeServices): void {\n  runtime = services;\n}\n\n/** Run `fn` with `services` bound as the request-scoped runtime.\n *\n * The persistent worker calls this once per request so concurrent requests\n * never share a services slot. NOT part of the public author-facing API. */\nexport function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T {\n  return __requestALS.run({ runtime: services }, fn);\n}\n\n/** Read the live clients, throwing if accessed outside a request scope.\n *\n * Resolves the ALS store first (persistent server, per-request), then the\n * process-global fallback (dev-server / tests). NOT part of the public\n * author-facing API — used by the runtime and the singleton Proxies. */\nexport function __getRuntime(): RuntimeServices {\n  const scoped = __requestALS.getStore();\n  if (scoped) return scoped.runtime;\n  if (runtime === null) {\n    throw new Error(\n      \"Palbase services accessed outside a request scope. The Database/Documents/… \" +\n        \"singletons are only available inside an endpoint handler (or after the \" +\n        \"runtime has called __runWithRuntime / __setRuntime).\",\n    );\n  }\n  return runtime;\n}\n\n/**\n * Build a Proxy singleton that forwards every property access to the live\n * client named `key` on the current runtime.\n *\n * The single `as RuntimeServices[K]` is the only contained cast in the surface:\n * `Reflect.get` on a typed object returns `unknown` for a `string | symbol`\n * key, but `prop` is constrained to keys of the client interface at the call\n * sites (the exported singletons are typed below), so the forward is sound.\n */\nfunction makeServiceProxy<K extends keyof RuntimeServices>(key: K): RuntimeServices[K] {\n  const handler: ProxyHandler<RuntimeServices[K]> = {\n    get(_target, prop, receiver) {\n      const client = __getRuntime()[key];\n      const value = Reflect.get(client as object, prop, receiver) as unknown;\n      // Bind methods to their owning client so `this` stays correct when the\n      // author destructures or calls `Database.query(...)`.\n      return typeof value === \"function\" ? value.bind(client) : value;\n    },\n  };\n  // The Proxy target is irrelevant (all access goes through `get`); the cast\n  // names the surface type the singleton presents to authors.\n  return new Proxy({} as RuntimeServices[K], handler);\n}\n\n/**\n * Build the `.tables` accessor for the top-level `Database`. Each\n * `tables.<name>` access returns a small object that forwards the five CRUD ops\n * to the underlying client using `name` as the string table identifier. The\n * shapes are typed against the generated `palbase-env.d.ts` (`EnvTables`); at\n * runtime they are plain string-keyed calls, so no schema value is needed here.\n *\n * Returns `EnvTables` — TS cannot infer the mapped type through the Proxy, so\n * a single structural narrowing names the surface (the proxy returns a\n * correctly-shaped accessor for whatever string member is read).\n */\n/** T018 (C-8): similar/recommend'in string-keyed yüzü. DBOps'a (endpoint.ts)\n * BİLEREK eklenmedi — search-param imza üçlüsü (engine/db + typed-db +\n * endpoint) büyümesin: proxy dispatch runtime'da engine ops'una zaten ulaşır,\n * derleme güvenliğini typed yüzey (EnvTypedTable) verir. */\ninterface RecoOps {\n  similar(table: string, id: string, params?: Record<string, unknown>): Promise<Record<string, unknown>[]>;\n  recommend(table: string, params: Record<string, unknown>): Promise<Record<string, unknown>[]>;\n}\n\nfunction makeTablesAccessor(ops: () => DBOps & RecoOps): EnvTables {\n  const tablesProxy = new Proxy(\n    {},\n    {\n      get(_t, prop: string | symbol) {\n        if (typeof prop !== \"string\") return undefined;\n        const name = prop;\n        return {\n          insert: (data: Record<string, unknown>) => ops().insert(name, data),\n          update: (id: string, data: Record<string, unknown>) => ops().update(name, id, data),\n          delete: (id: string) => ops().delete(name, id),\n          findById: (id: string) => ops().findById(name, id),\n          findMany: (query?: Record<string, unknown>) => ops().findMany(name, query),\n          search: (params?: Record<string, unknown>) => ops().search(name, params),\n          similar: (id: string, params?: Record<string, unknown>) => ops().similar(name, id, params),\n          recommend: (params: Record<string, unknown>) => ops().recommend(name, params),\n          supersede: (id: string, row: Record<string, unknown>) => ops().supersede(name, id, row),\n        };\n      },\n    },\n  );\n  return tablesProxy as EnvTables;\n}\n\n/** The raw string-keyed `DBClient` for the current request scope. */\nconst rawDatabase: DBClient = makeServiceProxy(\"Database\");\n\n/**\n * Wrap a raw `DBClient` into the typed `{ ...ops, tables, transaction }`\n * surface. The five string ops forward straight through; `tables` is the\n * env-typed accessor; `transaction` yields typed tables. Reused for both the\n * default (RLS-enforced) `Database` and the `asService()` sibling — each is\n * fed its own raw client (the default proxy vs `rawDatabase.asService()`).\n *\n * The `satisfies` pins the op surface so a missing/renamed op is a compile\n * error; the assembled object carries `tables`/`transaction` alongside.\n */\nfunction makeTypedSurface(raw: Omit<DBClient, \"asService\">): EnvServiceDatabase {\n  // Proxy dispatch her üyeyi taşır; RecoOps tipi DBClient'a eklenmediğinden\n  // (yukarıdaki karar) similar/recommend erişimi bu daraltmadan geçer.\n  const reco = raw as Omit<DBClient, \"asService\"> & RecoOps;\n  const ops = {\n    query: (sql: string, params?: unknown[]) => raw.query(sql, params),\n    insert: (table: string, data: Record<string, unknown>) => raw.insert(table, data),\n    update: (table: string, id: string, data: Record<string, unknown>) =>\n      raw.update(table, id, data),\n    delete: (table: string, id: string) => raw.delete(table, id),\n    findById: (table: string, id: string) => raw.findById(table, id),\n    findMany: (table: string, query?: Record<string, unknown>) => raw.findMany(table, query),\n    search: (table: string, params?: Record<string, unknown>) => raw.search(table, params),\n    similar: (table: string, id: string, params?: Record<string, unknown>) =>\n      reco.similar(table, id, params),\n    recommend: (table: string, params: Record<string, unknown>) => reco.recommend(table, params),\n    supersede: (table: string, id: string, row: Record<string, unknown>) =>\n      raw.supersede(table, id, row),\n  } satisfies DBOps & RecoOps;\n  return Object.assign(ops, {\n    tables: makeTablesAccessor(() => reco),\n    transaction<T>(\n      fn: (tx: TxPlan) => T extends Promise<unknown> ? never : T,\n    ): Promise<Materialized<T>> {\n      // A FRESH builder per call: it holds this transaction's ops and its error\n      // slot table, and the runtime serves concurrent requests on one event loop.\n      // A shared builder would splice one request's writes into another's plan.\n      const builder = new TxPlanBuilder();\n      return runTxPlan(raw, makeTxTablesAccessor(builder), builder, fn) as Promise<\n        Materialized<T>\n      >;\n    },\n  });\n}\n\n/**\n * The transaction twin of {@link makeTablesAccessor}: `tables.<name>` yields the\n * table's PLAN operations, recorded into `builder` instead of sent one by one.\n *\n * Same Proxy shape and same reason for the single narrowing — TS cannot infer a\n * mapped type through a Proxy, so the cast names what the trap returns.\n */\nfunction makeTxTablesAccessor(builder: TxPlanBuilder): TxTables {\n  const tablesProxy = new Proxy(\n    {},\n    {\n      get(_t, prop: string | symbol) {\n        if (typeof prop !== \"string\") return undefined;\n        return builder.table(prop);\n      },\n    },\n  );\n  return tablesProxy as TxTables;\n}\n\n/**\n * The project's own Postgres (pgx, schema `env_<envId>`).\n *\n * Typed by default: `Database.tables.<name>.insert({...})` is typed against\n * the project's generated `palbase-env.d.ts` with NO import and NO generic.\n * The raw string ops (`query`/`insert`/`update`/`delete`/`findById`/`findMany`)\n * are also available for dynamic table names and read-only SQL.\n *\n * RLS is enforced by default (the runtime runs each op as `authenticated` with\n * the verified user's claims). To bypass RLS, call `Database.asService()` —\n * explicit and greppable — which runs as the `service_role` (BYPASSRLS).\n *\n * @example\n * import { Database } from \"@palbase/backend\";\n *\n * const todo = await Database.tables.todos.insert({ title: req.input.title });\n * todo.id; // string ✓\n * const rows = await Database.query(\"SELECT id FROM todos WHERE done = $1\", [false]);\n * const all  = await Database.asService().tables.todos.findMany({}); // RLS bypass\n */\nexport const Database: EnvTypedDatabase = Object.assign(makeTypedSurface(rawDatabase), {\n  /**\n   * Lazily resolve the runtime's service-role sibling on each call. We do NOT\n   * cache it: `rawDatabase.asService()` reads the CURRENT request scope through\n   * the runtime proxy, and the per-request runtime injects a service client\n   * bound to that request's identity headers — caching would leak one request's\n   * sibling into another concurrent request.\n   */\n  asService(): EnvServiceDatabase {\n    return makeTypedSurface(rawDatabase.asService());\n  },\n});\n\n/** Firestore-like document client (PalDocs). */\nexport const Documents: PalbaseDocsClient = makeServiceProxy(\"Documents\");\n\n/**\n * `buckets.<name>` — the storage twin of `Database.tables.<name>`, and the same\n * mechanism: `config/storage.ts` generates a `Buckets` augmentation into\n * `palbase-env.d.ts`, so a bucket name is a property with no import and no\n * generic, and a typo is a compile error.\n *\n * The intermediate `.buckets` is there for the reason `.tables` is: bucket\n * names must not share a namespace with the client's own methods, or the day\n * somebody declares a bucket called `bucket` the surface breaks.\n */\nexport type EnvBuckets = {\n  [K in keyof Buckets]: TypedBucketClient<Buckets[K] extends BucketTypes ? Buckets[K] : BucketTypes>;\n};\n\n/** One bucket, with its declared variant names in the type. */\nexport interface TypedBucketClient<B extends BucketTypes> extends Omit<PalbaseBucketClient, \"getPublicUrl\"> {\n  /** The public URL for the object, or for one of THIS bucket's declared\n   * renditions. A name the bucket does not declare is a compile error. */\n  getPublicUrl(path: string, options?: { variant?: B[\"variants\"] }): string;\n}\n\nfunction makeBucketsAccessor(storage: () => PalbaseStorageClient): EnvBuckets {\n  return new Proxy(\n    {},\n    {\n      get(_t, prop: string | symbol) {\n        if (typeof prop !== \"string\") return undefined;\n        return storage().bucket(prop);\n      },\n    },\n  ) as EnvBuckets;\n}\n\nconst rawStorage: PalbaseStorageClient = makeServiceProxy(\"Storage\");\n\n/**\n * Object storage: buckets, objects, renditions and signed URLs.\n *\n * `Storage.buckets.posts.upload(...)` is the typed path. `Storage.bucket(name)`\n * remains for a name computed at runtime — rare, and it gives up the typing,\n * which is the honest trade rather than a second blessed way to do it.\n */\nexport const Storage: PalbaseStorageClient & { buckets: EnvBuckets } = Object.assign(\n  {\n    // FORWARDED explicitly, not assigned onto the service proxy.\n    //\n    // `Object.assign(rawStorage, {buckets})` writes onto the proxy's TARGET, and\n    // the proxy's only trap is `get`, which forwards every read to the module\n    // client — so the property landed somewhere nothing reads and\n    // `Storage.buckets.docs` was `undefined` in a deployed handler. It\n    // typechecked, every test passed, and the live call answered\n    // \"TypeError: undefined is not an object\". `Database` never had the bug\n    // because it builds a plain surface the same way this now does.\n    bucket: (name: string) => rawStorage.bucket(name),\n  },\n  { buckets: makeBucketsAccessor(() => rawStorage) },\n);\n\n/** JSON-typed cache (get/set/incr/getOrSet). */\nexport const Cache: CacheClient = makeServiceProxy(\"Cache\");\n\n\n/**\n * This tenant's secrets — API keys, provider credentials, signing material the\n * BACKEND owns.\n *\n * `await Secrets.get(\"STRIPE_KEY\")` in a handler. There is no `.env` to read\n * and no file to mount: a secret is written through the vault's authenticated\n * API (or the CLI/MCP that calls it), and this is how the deployed code reads\n * it back. A name this tenant has not set answers null — as does every name\n * the STACK holds, because no route returns a platform secret's value at all.\n */\nexport const Secrets: SecretsService = makeServiceProxy(\"Secrets\");\n\n/** Structured logger. */\nexport const Log: Logger = makeServiceProxy(\"Log\");\n\n/** Push / email / SMS / in-app notifications. */\nexport const Notifications: PalbaseNotificationsClient = makeServiceProxy(\"Notifications\");\n\n\n/**\n * The raw runtime Flags client for the current request scope. Carries the\n * default-surface reads + `setOverride` AND the runtime's `asService()` sibling\n * (the br-pod's `buildFlagsClient` returns both). The default `Flags` singleton\n * below forwards reads + `setOverride` through here; `Flags.asService()`\n * forwards to this client's own `asService()`.\n */\nconst rawFlags: PalbaseFlagsClient = makeServiceProxy(\"Flags\");\n\n/**\n * Feature flags.\n *\n * Mirrors the `Database` / `Database.asService()` model. The default surface is\n * RLS-equivalent for flags: reads resolve against the CURRENT request user and\n * `Flags.setOverride(key, value)` writes an override for that same signed-in\n * user (no userId argument, no admin power). Cross-user admin writes\n * (`setOverrideForUser`, …) live behind `Flags.asService()` — explicit and\n * greppable, just like `Database.asService()`.\n *\n * @example\n * import { Flags } from \"@palbase/backend\";\n *\n * if (await Flags.isEnabled(\"new_checkout\")) { ... }            // current user\n * await Flags.setOverride(\"new_checkout\", true);                // current user\n * await Flags.asService().setOverrideForUser(\"u_9\", \"x\", true); // cross-user\n */\nexport const Flags: PalbaseFlagsClient = Object.assign(\n  {\n    isEnabled(\n      flagName: PalbaseFlagKey,\n      context?: PalbaseFlagContext,\n    ): Promise<PalbaseResult<boolean>> {\n      return rawFlags.isEnabled(flagName, context);\n    },\n    getVariant(\n      flagName: PalbaseFlagKey,\n      context?: PalbaseFlagContext,\n    ): Promise<PalbaseResult<PalbaseFlagVariant>> {\n      return rawFlags.getVariant(flagName, context);\n    },\n    getAll(context?: PalbaseFlagContext): Promise<PalbaseResult<PalbaseFlag[]>> {\n      return rawFlags.getAll(context);\n    },\n    /**\n     * Resolve a flag's value, with an optional fallback.\n     *\n     * FORWARDED as of 2026-08-15. This surface is written out by hand, method\n     * by method, and `get` was missing from it — so the client implemented it,\n     * thirty assertions covered it, and `Flags.get(\"x\")` was `undefined` in a\n     * deployed handler. Exactly the shape of the `Storage.buckets` defect found\n     * the same day: a hand-maintained forwarding list is a list somebody has to\n     * remember to update.\n     */\n    get(\n      flagName: PalbaseFlagKey,\n      defaultOrContext?: PalbaseFlagValue | PalbaseFlagContext,\n      maybeContext?: PalbaseFlagContext,\n    ): Promise<PalbaseResult<PalbaseFlagValue>> {\n      return rawFlags.get(flagName, defaultOrContext, maybeContext);\n    },\n    setOverride(\n      key: PalbaseFlagKey,\n      value: PalbaseFlagValue,\n    ): Promise<PalbaseResult<PalbaseSetOverrideResult>> {\n      return rawFlags.setOverride(key, value);\n    },\n  },\n  {\n    /**\n     * Lazily resolve the runtime's cross-user sibling on each call. We do NOT\n     * cache it: `rawFlags.asService()` reads the CURRENT request scope through\n     * the runtime proxy, so caching would leak one request's sibling into\n     * another concurrent request. Mirrors `Database.asService()`.\n     */\n    asService(): PalbaseFlagsServiceClient {\n      return rawFlags.asService();\n    },\n  },\n);\n\n/**\n * The Realtime broadcast singleton for the current request scope. Backend-side\n * Realtime is BROADCAST-ONLY (a stateless handler can push but not subscribe —\n * `subscribe()` lives on the client SDK's `pb.realtime`). Fire-and-forget:\n * `broadcast` resolves once accepted (or with an `error`), never blocking the\n * handler on subscribers.\n *\n * @example\n * import { Realtime } from \"@palbase/backend\";\n *\n * await Realtime.broadcast(\"room:42\", \"message\", { text, from: user.id });\n */\nexport const Realtime: PalbaseRealtimeClient = makeServiceProxy(\"Realtime\");\n"],"mappings":"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","names":[]}