@palbase/backend 3.0.0 → 5.0.0

package/dist/db/index.d.cts

@@ -1,4 +1,4 @@
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, I as InsertShape, O as OnDeleteAction, R as RowShape, S as SchemaDef, g as SchemaInput, T as TableDef, h as TypedDB, i as TypedTable, j as TypedTx, k as boolean, l as defineSchema, m as enumType, n as integer, o as jsonb, p as makeTypedDB, t as text, q as timestamp, u as uuid } from '../index-CZAwpQE1.cjs';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, E as EnvTypedDatabase, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RowShape, S as SchemaDef, n as SchemaInput, T as TableDef, o as TableInput, p as TypedDB, q as TypedTable, r as TypedTx, s as boolean, t as defineSchema, u as enumType, v as integer, w as isPalbaseExtension, x as jsonb, y as makeTypedDB, z as policy, A as text, B as timestamp, D as uuid } from '../index-mr3Co63T.cjs';
 import './env.cjs';
-import '../endpoint-DJ98tQd6.cjs';
+import '../endpoint-BEHjfvFH.cjs';
 import 'zod';

package/dist/db/index.d.ts

@@ -1,4 +1,4 @@
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, I as InsertShape, O as OnDeleteAction, R as RowShape, S as SchemaDef, g as SchemaInput, T as TableDef, h as TypedDB, i as TypedTable, j as TypedTx, k as boolean, l as defineSchema, m as enumType, n as integer, o as jsonb, p as makeTypedDB, t as text, q as timestamp, u as uuid } from '../index-CXUs9iTQ.js';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, E as EnvTypedDatabase, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RowShape, S as SchemaDef, n as SchemaInput, T as TableDef, o as TableInput, p as TypedDB, q as TypedTable, r as TypedTx, s as boolean, t as defineSchema, u as enumType, v as integer, w as isPalbaseExtension, x as jsonb, y as makeTypedDB, z as policy, A as text, B as timestamp, D as uuid } from '../index-BTVdhfsb.js';
 import './env.js';
-import '../endpoint-DJ98tQd6.js';
+import '../endpoint-BEHjfvFH.js';
 import 'zod';

package/dist/db/index.js

@@ -1,21 +1,31 @@
 import {
+  EXTENSION_DEPENDENCIES,
+  PALBASE_EXTENSIONS,
+  PolicyBuilder,
   boolean,
   defineSchema,
   enumType,
   integer,
+  isPalbaseExtension,
   jsonb,
   makeTypedDB,
+  policy,
   text,
   timestamp,
   uuid
-} from "../chunk-B7EUJP5W.js";
+} from "../chunk-2N4YNN6F.js";
 export {
+  EXTENSION_DEPENDENCIES,
+  PALBASE_EXTENSIONS,
+  PolicyBuilder,
   boolean,
   defineSchema,
   enumType,
   integer,
+  isPalbaseExtension,
   jsonb,
   makeTypedDB,
+  policy,
   text,
   timestamp,
   uuid

package/dist/{endpoint-DJ98tQd6.d.cts → endpoint-BEHjfvFH.d.cts}

@@ -49,20 +49,17 @@ declare function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler;
 
 /** HTTP error with structured error response format.
  *
- * Two ways to construct one:
- *
- *   1. Directly: `throw new HttpError(404, "todo_not_found", "No such todo")`.
- *      Surfaces on the wire (and to iOS) as `BackendError.server(code, status,
- *      message, requestId)`.
- *   2. Via `req.errors.<name>(data?)` for declared errors — see a handler's
- *      `errors` map (`defineHandler`). The endpoint's OpenAPI spec describes
- *      each one, and the CLI codegen emits a typed `<Endpoint>.Error` enum so
- *      iOS callers can `catch <Endpoint>.Error.<case>` directly.
+ * The base class for the throwable error classes (`PalError`, `Conflict`,
+ * `NotFound`, …). Construct one directly with `throw new HttpError(404,
+ * "todo_not_found", "No such todo")`, or throw a named subclass
+ * (`throw new NotFound("todo not found")`). The runtime catches any `HttpError`
+ * and emits the standard envelope; on the wire (and to iOS) it surfaces as
+ * `BackendError.server(code, status, message, requestId)`.
  *
  * The optional `data` field carries a structured payload alongside the
- * standard envelope — used by declared errors that need to ship extra context
- * (e.g. `todoLocked({ retryAfter: 30 })`). It rides through to the iOS typed
- * enum's associated value.
+ * standard envelope — for errors that need to ship extra context
+ * (e.g. `new Conflict("locked", "title_locked", { retryAfter: 30 })`). It rides
+ * through to the iOS typed enum's associated value.
  */
 declare class HttpError extends Error {
     readonly status: number;
@@ -84,6 +81,46 @@ declare class HttpError extends Error {
         data?: unknown;
     };
 }
+/**
+ * Throw with a custom HTTP status + wire code. The general-purpose escape hatch
+ * when none of the named classes (`Conflict`/`NotFound`/…) fits.
+ *
+ * @example
+ * throw new PalError(418, "teapot", "I'm a teapot");
+ */
+declare class PalError extends HttpError {
+    constructor(status: number, code: string, description: string, data?: unknown);
+}
+/** Base for the named status classes. Each subclass fixes its HTTP status; the
+ * `code` defaults to the class's canonical wire code (overridable), and the
+ * `message` defaults to a human-readable label (overridable). */
+declare abstract class NamedHttpError extends HttpError {
+    protected constructor(status: number, defaultCode: string, name: string, message?: string, code?: string, data?: unknown);
+}
+/** 400 — the request was malformed or failed validation. */
+declare class BadRequest extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 401 — the caller is not authenticated. */
+declare class Unauthorized extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 403 — the caller is authenticated but not allowed. */
+declare class Forbidden extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 404 — the requested resource does not exist. */
+declare class NotFound extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 409 — the request conflicts with the current state. */
+declare class Conflict extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 429 — the caller has exceeded the rate limit. */
+declare class TooManyRequests extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
 
 /**
  * Local typed interfaces for the 9 Palbase module clients injected into
@@ -1161,23 +1198,43 @@ interface RateLimitConfig {
     /** Window duration in seconds. */
     window: number;
 }
-/** The transaction-scoped client passed to `db.transaction(fn)` — same DB ops, no nested transaction. */
-type TxClient = Omit<DBClient, "transaction">;
-/** Database client interface injected into endpoint context. */
-interface DBClient {
+/** The six raw string-keyed DB operations shared by `DBClient` and the
+ * transaction-scoped client. */
+interface DBOps {
     /** Run a read-only SQL query (executes in a READ ONLY transaction). */
     query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
     insert(table: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Update the row with the given id and resolve to the updated row, or `null`
+     * if no row matched (the id is absent, or the row is hidden by RLS). This is
+     * an idempotent outcome, not an error — it mirrors `findById`. Map `null` to
+     * a 404 in your service if a missing row should be a client error.
+     */
+    update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Record<string, unknown> | null>;
     findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+/** The transaction-scoped client passed to `db.transaction(fn)` — the raw DB
+ * ops only. No nested transaction and no `asService` (the DB role is fixed once
+ * when the transaction begins; see `Database.asService().transaction(...)`). */
+type TxClient = DBOps;
+/** Database client interface injected into endpoint context. */
+interface DBClient extends DBOps {
     /**
      * Run an interactive transaction. The callback receives a `tx` with the same
      * DB ops as this client; returning normally commits, throwing rolls back.
      * Nested transactions are not supported.
      */
     transaction<T>(fn: (tx: TxClient) => Promise<T>): Promise<T>;
+    /**
+     * Return a sibling DB client that bypasses Row-Level Security by running as
+     * the `service_role` (BYPASSRLS). Use sparingly and explicitly — the default
+     * `Database.*` path is RLS-enforced. The returned client exposes the same op
+     * surface (`query`/`insert`/.../`transaction`) but never re-exposes
+     * `asService` (no double-bypass).
+     */
+    asService(): Omit<DBClient, "asService">;
 }
 /** Logger interface injected into endpoint context. */
 interface Logger {
@@ -1349,21 +1406,29 @@ type ErrorThrowers<TErrors extends ErrorMap | undefined> = TErrors extends Error
  * error throwers. Services (`Database`, `Documents`, `Cache`, …) are NOT on
  * the request: import them directly from `@palbase/backend` as singletons.
  *
- *   import { defineHandler, Database } from "@palbase/backend";
+ *   import { Controller, Get, Req, Database } from "@palbase/backend";
+ *
+ *   \@Controller("/todos")
+ *   export class TodosController {
+ *     \@Get("") list(\@Req() req: PBRequest): unknown {
+ *       return Database.findMany("todos");
+ *     }
+ *   }
  *
- *   export default defineHandler({
- *     handler: async (req) => Database.insert("todos", { title: req.input.title }),
- *   });
+ * Most controller methods reach individual request slices via their own
+ * parameter decorator (`@Body`/`@Query`/`@Param`/`@User`/…); `@Req()` is the
+ * escape hatch that injects this whole object.
  *
  * Generic parameters:
- * - `TInput` — the validated `input` type (inferred from the `input` Zod
- *   schema by `defineHandler`). The user-facing form is single-generic:
- *   `PBRequest<TodoInput>`.
+ * - `TInput` — the validated `input` type (the `@Body` schema's `z.infer`). The
+ *   user-facing form is single-generic: `PBRequest<TodoInput>`.
  * - `TAuthed` — whether `user` is non-null. DEFAULTS to `true` (the common
  *   case; the auth pipeline returns 401 before the handler when auth is
- *   required, so a non-null `user` is runtime-honest). `defineHandler` passes
- *   `IsAuthed<TAuth>` here, so `auth: false` → `User | null`.
- * - `TErrors` — the declared `errors` map, typing `req.errors.<name>(...)`.
+ *   required, so a non-null `user` is runtime-honest). A route whose effective
+ *   auth is `false` yields `User | null`.
+ * - `TErrors` — RETAINED for back-compat of the `errors` thrower shape; the
+ *   class-controller model throws global error classes
+ *   (`Conflict`/`NotFound`/…) instead, so `req.errors` is empty in practice.
  */
 interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors extends ErrorMap | undefined = undefined> {
     /** Validated request input (body for POST/PUT/PATCH; `{}` otherwise). */
@@ -1375,8 +1440,9 @@ interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors ex
     /** Request headers (lowercase keys). */
     headers: Record<string, string>;
     /** Authenticated user. Non-null (`User`) by default; `User | null` only when
-     * the endpoint's `auth` config disables enforcement (driven by `TAuthed`,
-     * which `defineHandler` computes from the `auth` literal via {@link IsAuthed}). */
+     * the route's effective auth disables enforcement (driven by `TAuthed`, which
+     * the runtime resolves from the route/controller `auth` cascade via
+     * {@link IsAuthed}). */
     user: TAuthed extends true ? User : User | null;
     /** Calling-client metadata derived from request headers (all nullable). */
     client: ClientInfo;
@@ -1390,8 +1456,9 @@ interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors ex
     traceId: string;
     /** W3C span id for this handler invocation. */
     spanId: string;
-    /** Typed throwers for the endpoint's declared errors. Empty when the
-     * `errors` block is absent on `defineHandler`. */
+    /** Typed throwers for the endpoint's declared errors. RETAINED for the
+     * `@Req()` escape-hatch shape; the class-controller model throws global error
+     * classes (`Conflict`/`NotFound`/…) instead, so this is empty in practice. */
     errors: ErrorThrowers<TErrors>;
 }
 /** Middleware function signature — uses MiddlewareContext (no input, not yet validated). */
@@ -1403,30 +1470,5 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  * omitted — which the runtime treats as `required: true` (see {@link IsAuthed}).
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
-/** Compute, at the type level, whether an endpoint authenticates its caller —
- * i.e. whether `req.user` should be `User` (non-null) instead of `User | null`.
- *
- * SECURE BY DEFAULT — mirrors the runtime (loader.go DefaultAuthConfig +
- * pipeline/auth.go): an endpoint requires auth UNLESS it explicitly opts out.
- * `req.user` is nullable ONLY for `auth: false` or `auth: { required: false }`.
- * Omitting `auth` means AUTH REQUIRED (non-null `req.user`), so a handler that
- * forgets `auth` fails safe (401) instead of silently exposing data.
- *
- * | `TAuth`                          | `IsAuthed<TAuth>` |
- * |----------------------------------|-------------------|
- * | omitted (`undefined`)            | `true`  (secure)  |
- * | `true`                           | `true`            |
- * | `false`                          | `false` (public)  |
- * | `{ required: true }`             | `true`            |
- * | `{ required: false }`            | `false` (public)  |
- * | `{ role: 'admin' }` (no `required`) | `true`         |
- *
- * Order matters: the `{ required: false }` branch is checked first so the object
- * case can't swallow it; `true`/`false` literals next; the catch-all (omitted)
- * resolves to `true` (secure-by-default).
- */
-type IsAuthed<TAuth> = TAuth extends {
-    required: false;
-} ? false : TAuth extends true ? true : TAuth extends false ? false : TAuth extends object ? true : true;
 
-export { type PalbaseEventsQueryInput as $, type AuthSpec as A, type PalbaseCohortQueryInput as B, type CacheClient as C, type DBClient as D, type ErrorMap as E, type FileContext as F, type PalbaseCohortResult as G, HttpError as H, type IsAuthed as I, type PalbaseCollectionRef as J, type PalbaseCountQueryInput as K, type Logger as L, type Middleware as M, type PalbaseCountResult as N, type PalbaseCreateLinkParams as O, type PBRequest as P, type QueueClient as Q, type RateLimitConfig as R, type PalbaseDeviceInfo as S, type PalbaseDeviceTokenView as T, type User as U, type PalbaseDocumentRef as V, type PalbaseDocumentSnapshot as W, type PalbaseEmailClient as X, type PalbaseEmailSendParams as Y, type PalbaseEmailSendResponse as Z, type PalbaseEventNamesResult as _, type PalbaseModuleClients as a, type PalbaseEventsResult as a0, type PalbaseFileObject as a1, type PalbaseFlag as a2, type PalbaseFlagContext as a3, type PalbaseFlagVariant as a4, type PalbaseFunctionsClient as a5, type PalbaseFunnelQueryInput as a6, type PalbaseFunnelResult as a7, type PalbaseIdentifyTraits as a8, type PalbaseInboxClient as a9, type PalbaseRealtimeClient as aA, type PalbaseRealtimeMessage as aB, type PalbaseRegisterDeviceParams as aC, type PalbaseResult as aD, type PalbaseRetentionQueryInput as aE, type PalbaseRetentionResult as aF, type PalbaseSession as aG, type PalbaseSignedUrlResponse as aH, type PalbaseSmsClient as aI, type PalbaseSmsSendParams as aJ, type PalbaseSmsSendResponse as aK, type PalbaseTransformOptions as aL, type PalbaseUpdateLinkParams as aM, type PalbaseUploadOptions as aN, type PalbaseUser as aO, type PalbaseUserDetailResult as aP, type PalbaseUsersQueryInput as aQ, type PalbaseUsersResult as aR, type PalbaseVerifyRequestSignatureParams as aS, type PalbaseWhereOperator as aT, type TxClient as aU, defineMiddleware as aV, type PalbaseInboxListOptions as aa, type PalbaseInboxListResult as ab, type PalbaseInboxMessage as ac, type PalbaseInboxSendParams as ad, type PalbaseInboxSendResponse as ae, type PalbaseInitialLink as af, type PalbaseInvokeOptions as ag, type PalbaseLink as ah, type PalbaseLinkAnalytics as ai, type PalbaseLinkDetails as aj, type PalbaseLinksClient as ak, type PalbaseListLinksOptions as al, type PalbaseListLinksResult as am, type PalbaseListOptions as an, type PalbaseMatchParams as ao, type PalbaseMultiChannelResponse as ap, type PalbaseOverviewResult as aq, type PalbasePreferences as ar, type PalbasePreferencesClient as as, type PalbasePublicUrlResponse as at, type PalbasePushClient as au, type PalbasePushSendParams as av, type PalbasePushSendResponse as aw, type PalbaseQrCodeOptions as ax, type PalbaseQuerySnapshot as ay, type PalbaseRealtimeChannel as az, type PalbaseDocsClient as b, type PalbaseFlagsClient as c, type PalbaseNotificationsClient as d, type PalbaseStorageClient as e, type AuthConfig as f, type ClientInfo as g, type ErrorDef as h, type ErrorThrowers as i, type HttpMethod as j, type MiddlewareContext as k, type MiddlewareHandler as l, type PalbaseAnalyticsClient as m, type PalbaseAnalyticsManagementNamespace as n, type PalbaseAnalyticsProperties as o, type PalbaseAnalyticsQueryNamespace as p, type PalbaseAttestAndroidParams as q, type PalbaseAttestAndroidResult as r, type PalbaseAttestiOSParams as s, type PalbaseAttestiOSResult as t, type PalbaseAuthClient as u, type PalbaseBindDeviceParams as v, type PalbaseBucketClient as w, type PalbaseCmsClient as x, type PalbaseCmsFindOneOptions as y, type PalbaseCmsFindOptions as z };
+export { type PalbaseDocumentSnapshot as $, type AuthSpec as A, BadRequest as B, type CacheClient as C, type DBClient as D, type ErrorDef as E, type FileContext as F, type PalbaseBucketClient as G, HttpError as H, type PalbaseCmsClient as I, type PalbaseCmsFindOneOptions as J, type PalbaseCmsFindOptions as K, type Logger as L, type Middleware as M, NotFound as N, type PalbaseCohortQueryInput as O, type PBRequest as P, type QueueClient as Q, type RateLimitConfig as R, type PalbaseCohortResult as S, type PalbaseCollectionRef as T, type User as U, type PalbaseCountQueryInput as V, type PalbaseCountResult as W, type PalbaseCreateLinkParams as X, type PalbaseDeviceInfo as Y, type PalbaseDeviceTokenView as Z, type PalbaseDocumentRef as _, type PalbaseModuleClients as a, Unauthorized as a$, type PalbaseEmailClient as a0, type PalbaseEmailSendParams as a1, type PalbaseEmailSendResponse as a2, type PalbaseEventNamesResult as a3, type PalbaseEventsQueryInput as a4, type PalbaseEventsResult as a5, type PalbaseFileObject as a6, type PalbaseFlag as a7, type PalbaseFlagContext as a8, type PalbaseFlagVariant as a9, type PalbasePushSendParams as aA, type PalbasePushSendResponse as aB, type PalbaseQrCodeOptions as aC, type PalbaseQuerySnapshot as aD, type PalbaseRealtimeChannel as aE, type PalbaseRealtimeClient as aF, type PalbaseRealtimeMessage as aG, type PalbaseRegisterDeviceParams as aH, type PalbaseResult as aI, type PalbaseRetentionQueryInput as aJ, type PalbaseRetentionResult as aK, type PalbaseSession as aL, type PalbaseSignedUrlResponse as aM, type PalbaseSmsClient as aN, type PalbaseSmsSendParams as aO, type PalbaseSmsSendResponse as aP, type PalbaseTransformOptions as aQ, type PalbaseUpdateLinkParams as aR, type PalbaseUploadOptions as aS, type PalbaseUser as aT, type PalbaseUserDetailResult as aU, type PalbaseUsersQueryInput as aV, type PalbaseUsersResult as aW, type PalbaseVerifyRequestSignatureParams as aX, type PalbaseWhereOperator as aY, TooManyRequests as aZ, type TxClient as a_, type PalbaseFunctionsClient as aa, type PalbaseFunnelQueryInput as ab, type PalbaseFunnelResult as ac, type PalbaseIdentifyTraits as ad, type PalbaseInboxClient as ae, type PalbaseInboxListOptions as af, type PalbaseInboxListResult as ag, type PalbaseInboxMessage as ah, type PalbaseInboxSendParams as ai, type PalbaseInboxSendResponse as aj, type PalbaseInitialLink as ak, type PalbaseInvokeOptions as al, type PalbaseLink as am, type PalbaseLinkAnalytics as an, type PalbaseLinkDetails as ao, type PalbaseLinksClient as ap, type PalbaseListLinksOptions as aq, type PalbaseListLinksResult as ar, type PalbaseListOptions as as, type PalbaseMatchParams as at, type PalbaseMultiChannelResponse as au, type PalbaseOverviewResult as av, type PalbasePreferences as aw, type PalbasePreferencesClient as ax, type PalbasePublicUrlResponse as ay, type PalbasePushClient as az, type PalbaseDocsClient as b, defineMiddleware as b0, type PalbaseFlagsClient as c, type PalbaseNotificationsClient as d, type PalbaseStorageClient as e, type AuthConfig as f, type ClientInfo as g, Conflict as h, type DBOps as i, type ErrorMap as j, type ErrorThrowers as k, Forbidden as l, type HttpMethod as m, type MiddlewareContext as n, type MiddlewareHandler as o, PalError as p, type PalbaseAnalyticsClient as q, type PalbaseAnalyticsManagementNamespace as r, type PalbaseAnalyticsProperties as s, type PalbaseAnalyticsQueryNamespace as t, type PalbaseAttestAndroidParams as u, type PalbaseAttestAndroidResult as v, type PalbaseAttestiOSParams as w, type PalbaseAttestiOSResult as x, type PalbaseAuthClient as y, type PalbaseBindDeviceParams as z };

package/dist/{endpoint-DJ98tQd6.d.ts → endpoint-BEHjfvFH.d.ts}

@@ -49,20 +49,17 @@ declare function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler;
 
 /** HTTP error with structured error response format.
  *
- * Two ways to construct one:
- *
- *   1. Directly: `throw new HttpError(404, "todo_not_found", "No such todo")`.
- *      Surfaces on the wire (and to iOS) as `BackendError.server(code, status,
- *      message, requestId)`.
- *   2. Via `req.errors.<name>(data?)` for declared errors — see a handler's
- *      `errors` map (`defineHandler`). The endpoint's OpenAPI spec describes
- *      each one, and the CLI codegen emits a typed `<Endpoint>.Error` enum so
- *      iOS callers can `catch <Endpoint>.Error.<case>` directly.
+ * The base class for the throwable error classes (`PalError`, `Conflict`,
+ * `NotFound`, …). Construct one directly with `throw new HttpError(404,
+ * "todo_not_found", "No such todo")`, or throw a named subclass
+ * (`throw new NotFound("todo not found")`). The runtime catches any `HttpError`
+ * and emits the standard envelope; on the wire (and to iOS) it surfaces as
+ * `BackendError.server(code, status, message, requestId)`.
  *
  * The optional `data` field carries a structured payload alongside the
- * standard envelope — used by declared errors that need to ship extra context
- * (e.g. `todoLocked({ retryAfter: 30 })`). It rides through to the iOS typed
- * enum's associated value.
+ * standard envelope — for errors that need to ship extra context
+ * (e.g. `new Conflict("locked", "title_locked", { retryAfter: 30 })`). It rides
+ * through to the iOS typed enum's associated value.
  */
 declare class HttpError extends Error {
     readonly status: number;
@@ -84,6 +81,46 @@ declare class HttpError extends Error {
         data?: unknown;
     };
 }
+/**
+ * Throw with a custom HTTP status + wire code. The general-purpose escape hatch
+ * when none of the named classes (`Conflict`/`NotFound`/…) fits.
+ *
+ * @example
+ * throw new PalError(418, "teapot", "I'm a teapot");
+ */
+declare class PalError extends HttpError {
+    constructor(status: number, code: string, description: string, data?: unknown);
+}
+/** Base for the named status classes. Each subclass fixes its HTTP status; the
+ * `code` defaults to the class's canonical wire code (overridable), and the
+ * `message` defaults to a human-readable label (overridable). */
+declare abstract class NamedHttpError extends HttpError {
+    protected constructor(status: number, defaultCode: string, name: string, message?: string, code?: string, data?: unknown);
+}
+/** 400 — the request was malformed or failed validation. */
+declare class BadRequest extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 401 — the caller is not authenticated. */
+declare class Unauthorized extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 403 — the caller is authenticated but not allowed. */
+declare class Forbidden extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 404 — the requested resource does not exist. */
+declare class NotFound extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 409 — the request conflicts with the current state. */
+declare class Conflict extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
+/** 429 — the caller has exceeded the rate limit. */
+declare class TooManyRequests extends NamedHttpError {
+    constructor(message?: string, code?: string, data?: unknown);
+}
 
 /**
  * Local typed interfaces for the 9 Palbase module clients injected into
@@ -1161,23 +1198,43 @@ interface RateLimitConfig {
     /** Window duration in seconds. */
     window: number;
 }
-/** The transaction-scoped client passed to `db.transaction(fn)` — same DB ops, no nested transaction. */
-type TxClient = Omit<DBClient, "transaction">;
-/** Database client interface injected into endpoint context. */
-interface DBClient {
+/** The six raw string-keyed DB operations shared by `DBClient` and the
+ * transaction-scoped client. */
+interface DBOps {
     /** Run a read-only SQL query (executes in a READ ONLY transaction). */
     query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
     insert(table: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-    update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Update the row with the given id and resolve to the updated row, or `null`
+     * if no row matched (the id is absent, or the row is hidden by RLS). This is
+     * an idempotent outcome, not an error — it mirrors `findById`. Map `null` to
+     * a 404 in your service if a missing row should be a client error.
+     */
+    update(table: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Record<string, unknown> | null>;
     findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+/** The transaction-scoped client passed to `db.transaction(fn)` — the raw DB
+ * ops only. No nested transaction and no `asService` (the DB role is fixed once
+ * when the transaction begins; see `Database.asService().transaction(...)`). */
+type TxClient = DBOps;
+/** Database client interface injected into endpoint context. */
+interface DBClient extends DBOps {
     /**
      * Run an interactive transaction. The callback receives a `tx` with the same
      * DB ops as this client; returning normally commits, throwing rolls back.
      * Nested transactions are not supported.
      */
     transaction<T>(fn: (tx: TxClient) => Promise<T>): Promise<T>;
+    /**
+     * Return a sibling DB client that bypasses Row-Level Security by running as
+     * the `service_role` (BYPASSRLS). Use sparingly and explicitly — the default
+     * `Database.*` path is RLS-enforced. The returned client exposes the same op
+     * surface (`query`/`insert`/.../`transaction`) but never re-exposes
+     * `asService` (no double-bypass).
+     */
+    asService(): Omit<DBClient, "asService">;
 }
 /** Logger interface injected into endpoint context. */
 interface Logger {
@@ -1349,21 +1406,29 @@ type ErrorThrowers<TErrors extends ErrorMap | undefined> = TErrors extends Error
  * error throwers. Services (`Database`, `Documents`, `Cache`, …) are NOT on
  * the request: import them directly from `@palbase/backend` as singletons.
  *
- *   import { defineHandler, Database } from "@palbase/backend";
+ *   import { Controller, Get, Req, Database } from "@palbase/backend";
+ *
+ *   \@Controller("/todos")
+ *   export class TodosController {
+ *     \@Get("") list(\@Req() req: PBRequest): unknown {
+ *       return Database.findMany("todos");
+ *     }
+ *   }
  *
- *   export default defineHandler({
- *     handler: async (req) => Database.insert("todos", { title: req.input.title }),
- *   });
+ * Most controller methods reach individual request slices via their own
+ * parameter decorator (`@Body`/`@Query`/`@Param`/`@User`/…); `@Req()` is the
+ * escape hatch that injects this whole object.
  *
  * Generic parameters:
- * - `TInput` — the validated `input` type (inferred from the `input` Zod
- *   schema by `defineHandler`). The user-facing form is single-generic:
- *   `PBRequest<TodoInput>`.
+ * - `TInput` — the validated `input` type (the `@Body` schema's `z.infer`). The
+ *   user-facing form is single-generic: `PBRequest<TodoInput>`.
  * - `TAuthed` — whether `user` is non-null. DEFAULTS to `true` (the common
  *   case; the auth pipeline returns 401 before the handler when auth is
- *   required, so a non-null `user` is runtime-honest). `defineHandler` passes
- *   `IsAuthed<TAuth>` here, so `auth: false` → `User | null`.
- * - `TErrors` — the declared `errors` map, typing `req.errors.<name>(...)`.
+ *   required, so a non-null `user` is runtime-honest). A route whose effective
+ *   auth is `false` yields `User | null`.
+ * - `TErrors` — RETAINED for back-compat of the `errors` thrower shape; the
+ *   class-controller model throws global error classes
+ *   (`Conflict`/`NotFound`/…) instead, so `req.errors` is empty in practice.
  */
 interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors extends ErrorMap | undefined = undefined> {
     /** Validated request input (body for POST/PUT/PATCH; `{}` otherwise). */
@@ -1375,8 +1440,9 @@ interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors ex
     /** Request headers (lowercase keys). */
     headers: Record<string, string>;
     /** Authenticated user. Non-null (`User`) by default; `User | null` only when
-     * the endpoint's `auth` config disables enforcement (driven by `TAuthed`,
-     * which `defineHandler` computes from the `auth` literal via {@link IsAuthed}). */
+     * the route's effective auth disables enforcement (driven by `TAuthed`, which
+     * the runtime resolves from the route/controller `auth` cascade via
+     * {@link IsAuthed}). */
     user: TAuthed extends true ? User : User | null;
     /** Calling-client metadata derived from request headers (all nullable). */
     client: ClientInfo;
@@ -1390,8 +1456,9 @@ interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors ex
     traceId: string;
     /** W3C span id for this handler invocation. */
     spanId: string;
-    /** Typed throwers for the endpoint's declared errors. Empty when the
-     * `errors` block is absent on `defineHandler`. */
+    /** Typed throwers for the endpoint's declared errors. RETAINED for the
+     * `@Req()` escape-hatch shape; the class-controller model throws global error
+     * classes (`Conflict`/`NotFound`/…) instead, so this is empty in practice. */
     errors: ErrorThrowers<TErrors>;
 }
 /** Middleware function signature — uses MiddlewareContext (no input, not yet validated). */
@@ -1403,30 +1470,5 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  * omitted — which the runtime treats as `required: true` (see {@link IsAuthed}).
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
-/** Compute, at the type level, whether an endpoint authenticates its caller —
- * i.e. whether `req.user` should be `User` (non-null) instead of `User | null`.
- *
- * SECURE BY DEFAULT — mirrors the runtime (loader.go DefaultAuthConfig +
- * pipeline/auth.go): an endpoint requires auth UNLESS it explicitly opts out.
- * `req.user` is nullable ONLY for `auth: false` or `auth: { required: false }`.
- * Omitting `auth` means AUTH REQUIRED (non-null `req.user`), so a handler that
- * forgets `auth` fails safe (401) instead of silently exposing data.
- *
- * | `TAuth`                          | `IsAuthed<TAuth>` |
- * |----------------------------------|-------------------|
- * | omitted (`undefined`)            | `true`  (secure)  |
- * | `true`                           | `true`            |
- * | `false`                          | `false` (public)  |
- * | `{ required: true }`             | `true`            |
- * | `{ required: false }`            | `false` (public)  |
- * | `{ role: 'admin' }` (no `required`) | `true`         |
- *
- * Order matters: the `{ required: false }` branch is checked first so the object
- * case can't swallow it; `true`/`false` literals next; the catch-all (omitted)
- * resolves to `true` (secure-by-default).
- */
-type IsAuthed<TAuth> = TAuth extends {
-    required: false;
-} ? false : TAuth extends true ? true : TAuth extends false ? false : TAuth extends object ? true : true;
 
-export { type PalbaseEventsQueryInput as $, type AuthSpec as A, type PalbaseCohortQueryInput as B, type CacheClient as C, type DBClient as D, type ErrorMap as E, type FileContext as F, type PalbaseCohortResult as G, HttpError as H, type IsAuthed as I, type PalbaseCollectionRef as J, type PalbaseCountQueryInput as K, type Logger as L, type Middleware as M, type PalbaseCountResult as N, type PalbaseCreateLinkParams as O, type PBRequest as P, type QueueClient as Q, type RateLimitConfig as R, type PalbaseDeviceInfo as S, type PalbaseDeviceTokenView as T, type User as U, type PalbaseDocumentRef as V, type PalbaseDocumentSnapshot as W, type PalbaseEmailClient as X, type PalbaseEmailSendParams as Y, type PalbaseEmailSendResponse as Z, type PalbaseEventNamesResult as _, type PalbaseModuleClients as a, type PalbaseEventsResult as a0, type PalbaseFileObject as a1, type PalbaseFlag as a2, type PalbaseFlagContext as a3, type PalbaseFlagVariant as a4, type PalbaseFunctionsClient as a5, type PalbaseFunnelQueryInput as a6, type PalbaseFunnelResult as a7, type PalbaseIdentifyTraits as a8, type PalbaseInboxClient as a9, type PalbaseRealtimeClient as aA, type PalbaseRealtimeMessage as aB, type PalbaseRegisterDeviceParams as aC, type PalbaseResult as aD, type PalbaseRetentionQueryInput as aE, type PalbaseRetentionResult as aF, type PalbaseSession as aG, type PalbaseSignedUrlResponse as aH, type PalbaseSmsClient as aI, type PalbaseSmsSendParams as aJ, type PalbaseSmsSendResponse as aK, type PalbaseTransformOptions as aL, type PalbaseUpdateLinkParams as aM, type PalbaseUploadOptions as aN, type PalbaseUser as aO, type PalbaseUserDetailResult as aP, type PalbaseUsersQueryInput as aQ, type PalbaseUsersResult as aR, type PalbaseVerifyRequestSignatureParams as aS, type PalbaseWhereOperator as aT, type TxClient as aU, defineMiddleware as aV, type PalbaseInboxListOptions as aa, type PalbaseInboxListResult as ab, type PalbaseInboxMessage as ac, type PalbaseInboxSendParams as ad, type PalbaseInboxSendResponse as ae, type PalbaseInitialLink as af, type PalbaseInvokeOptions as ag, type PalbaseLink as ah, type PalbaseLinkAnalytics as ai, type PalbaseLinkDetails as aj, type PalbaseLinksClient as ak, type PalbaseListLinksOptions as al, type PalbaseListLinksResult as am, type PalbaseListOptions as an, type PalbaseMatchParams as ao, type PalbaseMultiChannelResponse as ap, type PalbaseOverviewResult as aq, type PalbasePreferences as ar, type PalbasePreferencesClient as as, type PalbasePublicUrlResponse as at, type PalbasePushClient as au, type PalbasePushSendParams as av, type PalbasePushSendResponse as aw, type PalbaseQrCodeOptions as ax, type PalbaseQuerySnapshot as ay, type PalbaseRealtimeChannel as az, type PalbaseDocsClient as b, type PalbaseFlagsClient as c, type PalbaseNotificationsClient as d, type PalbaseStorageClient as e, type AuthConfig as f, type ClientInfo as g, type ErrorDef as h, type ErrorThrowers as i, type HttpMethod as j, type MiddlewareContext as k, type MiddlewareHandler as l, type PalbaseAnalyticsClient as m, type PalbaseAnalyticsManagementNamespace as n, type PalbaseAnalyticsProperties as o, type PalbaseAnalyticsQueryNamespace as p, type PalbaseAttestAndroidParams as q, type PalbaseAttestAndroidResult as r, type PalbaseAttestiOSParams as s, type PalbaseAttestiOSResult as t, type PalbaseAuthClient as u, type PalbaseBindDeviceParams as v, type PalbaseBucketClient as w, type PalbaseCmsClient as x, type PalbaseCmsFindOneOptions as y, type PalbaseCmsFindOptions as z };
+export { type PalbaseDocumentSnapshot as $, type AuthSpec as A, BadRequest as B, type CacheClient as C, type DBClient as D, type ErrorDef as E, type FileContext as F, type PalbaseBucketClient as G, HttpError as H, type PalbaseCmsClient as I, type PalbaseCmsFindOneOptions as J, type PalbaseCmsFindOptions as K, type Logger as L, type Middleware as M, NotFound as N, type PalbaseCohortQueryInput as O, type PBRequest as P, type QueueClient as Q, type RateLimitConfig as R, type PalbaseCohortResult as S, type PalbaseCollectionRef as T, type User as U, type PalbaseCountQueryInput as V, type PalbaseCountResult as W, type PalbaseCreateLinkParams as X, type PalbaseDeviceInfo as Y, type PalbaseDeviceTokenView as Z, type PalbaseDocumentRef as _, type PalbaseModuleClients as a, Unauthorized as a$, type PalbaseEmailClient as a0, type PalbaseEmailSendParams as a1, type PalbaseEmailSendResponse as a2, type PalbaseEventNamesResult as a3, type PalbaseEventsQueryInput as a4, type PalbaseEventsResult as a5, type PalbaseFileObject as a6, type PalbaseFlag as a7, type PalbaseFlagContext as a8, type PalbaseFlagVariant as a9, type PalbasePushSendParams as aA, type PalbasePushSendResponse as aB, type PalbaseQrCodeOptions as aC, type PalbaseQuerySnapshot as aD, type PalbaseRealtimeChannel as aE, type PalbaseRealtimeClient as aF, type PalbaseRealtimeMessage as aG, type PalbaseRegisterDeviceParams as aH, type PalbaseResult as aI, type PalbaseRetentionQueryInput as aJ, type PalbaseRetentionResult as aK, type PalbaseSession as aL, type PalbaseSignedUrlResponse as aM, type PalbaseSmsClient as aN, type PalbaseSmsSendParams as aO, type PalbaseSmsSendResponse as aP, type PalbaseTransformOptions as aQ, type PalbaseUpdateLinkParams as aR, type PalbaseUploadOptions as aS, type PalbaseUser as aT, type PalbaseUserDetailResult as aU, type PalbaseUsersQueryInput as aV, type PalbaseUsersResult as aW, type PalbaseVerifyRequestSignatureParams as aX, type PalbaseWhereOperator as aY, TooManyRequests as aZ, type TxClient as a_, type PalbaseFunctionsClient as aa, type PalbaseFunnelQueryInput as ab, type PalbaseFunnelResult as ac, type PalbaseIdentifyTraits as ad, type PalbaseInboxClient as ae, type PalbaseInboxListOptions as af, type PalbaseInboxListResult as ag, type PalbaseInboxMessage as ah, type PalbaseInboxSendParams as ai, type PalbaseInboxSendResponse as aj, type PalbaseInitialLink as ak, type PalbaseInvokeOptions as al, type PalbaseLink as am, type PalbaseLinkAnalytics as an, type PalbaseLinkDetails as ao, type PalbaseLinksClient as ap, type PalbaseListLinksOptions as aq, type PalbaseListLinksResult as ar, type PalbaseListOptions as as, type PalbaseMatchParams as at, type PalbaseMultiChannelResponse as au, type PalbaseOverviewResult as av, type PalbasePreferences as aw, type PalbasePreferencesClient as ax, type PalbasePublicUrlResponse as ay, type PalbasePushClient as az, type PalbaseDocsClient as b, defineMiddleware as b0, type PalbaseFlagsClient as c, type PalbaseNotificationsClient as d, type PalbaseStorageClient as e, type AuthConfig as f, type ClientInfo as g, Conflict as h, type DBOps as i, type ErrorMap as j, type ErrorThrowers as k, Forbidden as l, type HttpMethod as m, type MiddlewareContext as n, type MiddlewareHandler as o, PalError as p, type PalbaseAnalyticsClient as q, type PalbaseAnalyticsManagementNamespace as r, type PalbaseAnalyticsProperties as s, type PalbaseAnalyticsQueryNamespace as t, type PalbaseAttestAndroidParams as u, type PalbaseAttestAndroidResult as v, type PalbaseAttestiOSParams as w, type PalbaseAttestiOSResult as x, type PalbaseAuthClient as y, type PalbaseBindDeviceParams as z };