@palbase/backend 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -1,95 +1,12 @@
-import { D as DBClient, C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, Q as QueueClient, c as PalbaseStorageClient, d as PalbaseModuleClients, U as User, E as ErrorThrowers } from './endpoint-BlcY2xNA.cjs';
-export { A as AuthConfig, e as ClientInfo, f as EndpointConfig, g as ErrorDef, h as ErrorMap, F as FileContext, H as HttpError, i as HttpMethod, M as Middleware, j as MiddlewareContext, k as MiddlewareHandler, l as PBRequest, m as PalbaseAnalyticsClient, n as PalbaseAnalyticsManagementNamespace, o as PalbaseAnalyticsProperties, p as PalbaseAnalyticsQueryNamespace, q as PalbaseAttestAndroidParams, r as PalbaseAttestAndroidResult, s as PalbaseAttestiOSParams, t as PalbaseAttestiOSResult, u as PalbaseAuthClient, v as PalbaseBindDeviceParams, w as PalbaseBucketClient, x as PalbaseCmsClient, y as PalbaseCmsFindOneOptions, z as PalbaseCmsFindOptions, B as PalbaseCohortQueryInput, G as PalbaseCohortResult, I as PalbaseCollectionRef, J as PalbaseCountQueryInput, K as PalbaseCountResult, N as PalbaseCreateLinkParams, O as PalbaseDeviceInfo, R as PalbaseDeviceTokenView, S as PalbaseDocumentRef, T as PalbaseDocumentSnapshot, V as PalbaseEmailClient, W as PalbaseEmailSendParams, X as PalbaseEmailSendResponse, Y as PalbaseEventNamesResult, Z as PalbaseEventsQueryInput, _ as PalbaseEventsResult, $ as PalbaseFileObject, a0 as PalbaseFlag, a1 as PalbaseFlagContext, a2 as PalbaseFlagVariant, a3 as PalbaseFunctionsClient, a4 as PalbaseFunnelQueryInput, a5 as PalbaseFunnelResult, a6 as PalbaseIdentifyTraits, a7 as PalbaseInboxClient, a8 as PalbaseInboxListOptions, a9 as PalbaseInboxListResult, aa as PalbaseInboxMessage, ab as PalbaseInboxSendParams, ac as PalbaseInboxSendResponse, ad as PalbaseInitialLink, ae as PalbaseInvokeOptions, af as PalbaseLink, ag as PalbaseLinkAnalytics, ah as PalbaseLinkDetails, ai as PalbaseLinksClient, aj as PalbaseListLinksOptions, ak as PalbaseListLinksResult, al as PalbaseListOptions, am as PalbaseMatchParams, an as PalbaseMultiChannelResponse, ao as PalbaseOverviewResult, ap as PalbasePreferences, aq as PalbasePreferencesClient, ar as PalbasePublicUrlResponse, as as PalbasePushClient, at as PalbasePushSendParams, au as PalbasePushSendResponse, av as PalbaseQrCodeOptions, aw as PalbaseQuerySnapshot, ax as PalbaseRealtimeChannel, ay as PalbaseRealtimeClient, az as PalbaseRealtimeMessage, aA as PalbaseRegisterDeviceParams, aB as PalbaseResult, aC as PalbaseRetentionQueryInput, aD as PalbaseRetentionResult, aE as PalbaseSession, aF as PalbaseSignedUrlResponse, aG as PalbaseSmsClient, aH as PalbaseSmsSendParams, aI as PalbaseSmsSendResponse, aJ as PalbaseTransformOptions, aK as PalbaseUpdateLinkParams, aL as PalbaseUploadOptions, aM as PalbaseUser, aN as PalbaseUserDetailResult, aO as PalbaseUsersQueryInput, aP as PalbaseUsersResult, aQ as PalbaseVerifyRequestSignatureParams, aR as PalbaseWhereOperator, aS as RateLimitConfig, aT as TxClient, aU as defineEndpoint, aV as defineMiddleware } from './endpoint-BlcY2xNA.cjs';
+import { C as CacheClient, b as PalbaseDocsClient, c as PalbaseFlagsClient, L as Logger, d as PalbaseNotificationsClient, Q as QueueClient, D as DBClient, e as PalbaseStorageClient, A as AuthSpec, R as RateLimitConfig, E as ErrorMap, M as Middleware, P as PBRequest, I as IsAuthed, U as User } from './endpoint-DJ98tQd6.cjs';
+export { f as AuthConfig, g as ClientInfo, h as ErrorDef, i as ErrorThrowers, F as FileContext, H as HttpError, j as HttpMethod, k as MiddlewareContext, l as MiddlewareHandler, m as PalbaseAnalyticsClient, n as PalbaseAnalyticsManagementNamespace, o as PalbaseAnalyticsProperties, p as PalbaseAnalyticsQueryNamespace, q as PalbaseAttestAndroidParams, r as PalbaseAttestAndroidResult, s as PalbaseAttestiOSParams, t as PalbaseAttestiOSResult, u as PalbaseAuthClient, v as PalbaseBindDeviceParams, w as PalbaseBucketClient, x as PalbaseCmsClient, y as PalbaseCmsFindOneOptions, z as PalbaseCmsFindOptions, B as PalbaseCohortQueryInput, G as PalbaseCohortResult, J as PalbaseCollectionRef, K as PalbaseCountQueryInput, N as PalbaseCountResult, O as PalbaseCreateLinkParams, S as PalbaseDeviceInfo, T as PalbaseDeviceTokenView, V as PalbaseDocumentRef, W as PalbaseDocumentSnapshot, X as PalbaseEmailClient, Y as PalbaseEmailSendParams, Z as PalbaseEmailSendResponse, _ as PalbaseEventNamesResult, $ as PalbaseEventsQueryInput, a0 as PalbaseEventsResult, a1 as PalbaseFileObject, a2 as PalbaseFlag, a3 as PalbaseFlagContext, a4 as PalbaseFlagVariant, a5 as PalbaseFunctionsClient, a6 as PalbaseFunnelQueryInput, a7 as PalbaseFunnelResult, a8 as PalbaseIdentifyTraits, a9 as PalbaseInboxClient, aa as PalbaseInboxListOptions, ab as PalbaseInboxListResult, ac as PalbaseInboxMessage, ad as PalbaseInboxSendParams, ae as PalbaseInboxSendResponse, af as PalbaseInitialLink, ag as PalbaseInvokeOptions, ah as PalbaseLink, ai as PalbaseLinkAnalytics, aj as PalbaseLinkDetails, ak as PalbaseLinksClient, al as PalbaseListLinksOptions, am as PalbaseListLinksResult, an as PalbaseListOptions, ao as PalbaseMatchParams, ap as PalbaseMultiChannelResponse, aq as PalbaseOverviewResult, ar as PalbasePreferences, as as PalbasePreferencesClient, at as PalbasePublicUrlResponse, au as PalbasePushClient, av as PalbasePushSendParams, aw as PalbasePushSendResponse, ax as PalbaseQrCodeOptions, ay as PalbaseQuerySnapshot, az as PalbaseRealtimeChannel, aA as PalbaseRealtimeClient, aB as PalbaseRealtimeMessage, aC as PalbaseRegisterDeviceParams, aD as PalbaseResult, aE as PalbaseRetentionQueryInput, aF as PalbaseRetentionResult, aG as PalbaseSession, aH as PalbaseSignedUrlResponse, aI as PalbaseSmsClient, aJ as PalbaseSmsSendParams, aK as PalbaseSmsSendResponse, aL as PalbaseTransformOptions, aM as PalbaseUpdateLinkParams, aN as PalbaseUploadOptions, aO as PalbaseUser, aP as PalbaseUserDetailResult, aQ as PalbaseUsersQueryInput, aR as PalbaseUsersResult, aS as PalbaseVerifyRequestSignatureParams, aT as PalbaseWhereOperator, aU as TxClient, aV as defineMiddleware } from './endpoint-DJ98tQd6.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { T as TableDef, C as ColIsOptionalOnInsert, a as ColValue, S as SchemaDef } from './schema-BqfEhIC0.cjs';
-export { b as ColumnBuilder, c as ColumnDef, d as ColumnType, O as OnDeleteAction, e as boolean, f as defineSchema, g as enumType, i as integer, j as jsonb, t as table, h as text, k as timestamp, u as uuid } from './schema-BqfEhIC0.cjs';
+import { E as EnvTypedDatabase, S as SchemaDef } from './index-CZAwpQE1.cjs';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EnvTables, e as EnvTypedTable, f as EnvTypedTx, I as InsertShape, O as OnDeleteAction, R as RowShape, 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 { TableTypes, Tables } from './db/env.cjs';
+import { ZodSchema, z } from 'zod';
 export { z } from 'zod';
 
-/**
- * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
- *
- * Derives INSERT and full-row TypeScript types from a `defineSchema()` result
- * and wraps the untyped runtime `DBClient` with a typed facade.
- *
- * No value-any. No `as unknown as X`. The two narrow `as` casts in
- * `makeTypedTable` are safe because:
- *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to
- *    typed values; all value types are subsets of `unknown`, so the cast is
- *    structurally sound.
- *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,
- *    unknown>` which is the erased form of the typed row; we're narrowing back
- *    to the precise shape that the schema declared.
- * Both casts are narrowing only (not widening) and correctness is guaranteed
- * by the schema the caller provides.
- */
-
-/** Keys of C whose columns are required on INSERT (not nullable, no default). */
-type RequiredKeys<C> = {
-    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;
-}[keyof C];
-/** Keys of C whose columns are optional on INSERT (nullable or has a default). */
-type OptionalKeys<C> = {
-    [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;
-}[keyof C];
-/**
- * The TypeScript type for an INSERT payload for table `T`.
- * - Required: columns that are NOT NULL and have no DB-level default.
- * - Optional: columns that are nullable or carry a default.
- *
- * When all columns are optional, `RequiredKeys<C>` resolves to `never` and
- * the first part becomes `{}`, which is a neutral element for `&`.
- */
-type InsertShape<T extends TableDef> = {
-    [K in RequiredKeys<T["columns"]>]: ColValue<T["columns"][K]>;
-} & {
-    [K in OptionalKeys<T["columns"]>]?: ColValue<T["columns"][K]>;
-};
-/**
- * The TypeScript type for a full row returned by the DB for table `T`.
- * Every column is present; nullable columns resolve to `T | null`.
- */
-type RowShape<T extends TableDef> = {
-    [K in keyof T["columns"]]: ColValue<T["columns"][K]>;
-};
-/** A typed table accessor that mirrors the runtime DBClient surface. */
-interface TypedTable<T extends TableDef> {
-    insert(data: InsertShape<T>): Promise<RowShape<T>>;
-    update(id: string, data: Partial<InsertShape<T>>): Promise<RowShape<T>>;
-    delete(id: string): Promise<void>;
-    findById(id: string): Promise<RowShape<T> | null>;
-    findMany(query?: Partial<RowShape<T>>): Promise<RowShape<T>[]>;
-}
-/** A typed DB facade covering all tables declared in schema `S`. */
-interface TypedDB<S extends SchemaDef> {
-    tables: {
-        [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
-    };
-    transaction<T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T>;
-}
-/** Transaction-scoped typed facade: same typed tables, no nested transaction. */
-interface TypedTx<S extends SchemaDef> {
-    tables: {
-        [K in keyof S["tables"]]: TypedTable<S["tables"][K]>;
-    };
-}
-/**
- * Wraps a raw `DBClient` with the type-safe `TypedDB<S>` facade derived from
- * the provided schema. No behavior change — all calls delegate to `raw` with
- * the table name as a plain string.
- *
- * `buildTables` is the reusable factory that wraps any op-bearing client
- * (`TxClient` — the surface shared by `DBClient` and the transaction-scoped
- * client) into the typed tables map. It is used both for the top-level db
- * (wrapping `raw`) and inside `transaction`, where it wraps the raw `TxClient`
- * the runtime yields so the callback sees the same typed `.tables` API.
- *
- * `transaction` delegates straight to `raw.transaction`; the two narrow
- * `as TypedTx<S>` / `as TypedDB<S>` casts are single structural narrowings
- * from the dynamically-built tables object to the precise mapped type (TS
- * cannot infer through `Object.keys` iteration) — see module-level doc comment.
- */
-declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: DBClient): TypedDB<S>;
-
 /**
  * runtime.ts — request-scoped service singletons.
  *
@@ -98,8 +15,7 @@ declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: DBClient): Typ
  *
  *   import { Database, Documents, Cache } from "@palbase/backend";
  *
- *   export default defineEndpoint({
- *     method: "POST",
+ *   export default defineHandler({
  *     handler: async (req) => {
  *       const row = await Database.insert("todos", { title: req.input.title });
  *       return row;
@@ -176,10 +92,22 @@ declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
  * process-global fallback (dev-server / tests). NOT part of the public
  * author-facing API — used by the runtime and the singleton Proxies. */
 declare function __getRuntime(): RuntimeServices;
-/** The project's own Postgres (pgx, schema `env_<envId>`). Typed CRUD +
- * `query`/`transaction`. For a typed `.tables.<name>` API, wrap with
- * {@link typedDatabase}. */
-declare const Database: DBClient;
+/**
+ * The project's own Postgres (pgx, schema `env_<envId>`).
+ *
+ * Typed by default: `Database.tables.<name>.insert({...})` is typed against
+ * the project's generated `palbase-env.d.ts` with NO import and NO generic.
+ * The raw string ops (`query`/`insert`/`update`/`delete`/`findById`/`findMany`)
+ * are also available for dynamic table names and read-only SQL.
+ *
+ * @example
+ * import { Database } from "@palbase/backend";
+ *
+ * const todo = await Database.tables.todos.insert({ title: req.input.title });
+ * todo.id; // string ✓
+ * const rows = await Database.query("SELECT id FROM todos WHERE done = $1", [false]);
+ */
+declare const Database: EnvTypedDatabase;
 /** Firestore-like document client (PalDocs). */
 declare const Documents: PalbaseDocsClient;
 /** Object storage client (buckets, signed URLs). */
@@ -194,31 +122,255 @@ declare const Log: Logger;
 declare const Notifications: PalbaseNotificationsClient;
 /** Feature flags. */
 declare const Flags: PalbaseFlagsClient;
+
 /**
- * Type the `Database` singleton against a `defineSchema()` result, returning a
- * facade with a typed `.tables.<name>.insert(...)` API alongside the raw
- * `query`/`transaction` ops.
+ * env-gen.ts — generate the `palbase-env.d.ts` text from a `defineSchema()`
+ * result.
  *
- *   const Db = typedDatabase(schema);
- *   const todo = await Db.tables.todos.insert({ title: "x" });
+ * The CLI (`palbase serve` / codegen) and the deploy pipeline call
+ * {@link makeEnvDts} with the project's schema and write the returned string to
+ * `palbase-env.d.ts` at the project root. That file AUGMENTS the
+ * `@palbase/backend/env` `Tables` interface (controlled global augmentation,
+ * C5) so `Database.tables.<name>` is typed with no import and no generic.
  *
- * This is per-endpoint (not global module augmentation), so one endpoint's
- * tables never leak into another's `Database` type.
+ * The output is FLAT: each table gets a `{ row: {...}; insert: {...} }` entry
+ * with plain TypeScript object types. The phantom `ColumnBuilder<...>` type
+ * NEVER appears in the generated `.d.ts` — that type only lives at authoring
+ * time inside `db/schema.ts`.
  */
-declare function typedDatabase<TSchema extends SchemaDef>(schema: TSchema): TypedDB<TSchema> & DBClient;
 
-/** Context injected into worker handlers — the non-request-scoped service
- * surface (db/log/cache/queue + module clients), plus correlation ids. Workers
- * are not part of the Phase 1 `ctx → PBRequest` redesign, so they keep their
- * own `ctx`; the job payload arrives as the handler's second argument. */
-interface WorkerContext extends PalbaseModuleClients {
-    user: User | null;
-    db: DBClient;
+/**
+ * Generate the full `palbase-env.d.ts` text for a schema.
+ *
+ * @example
+ * import { makeEnvDts } from "@palbase/backend";
+ * import schema from "./db/schema.js";
+ * writeFileSync("palbase-env.d.ts", makeEnvDts(schema));
+ */
+declare function makeEnvDts(schema: SchemaDef): string;
+
+/**
+ * handler.ts — `defineHandler`: an endpoint UNIT (schema + thin logic), one per
+ * file, with NO routing.
+ *
+ * Everything that types `req` lives here (colocated): `auth` → `req.user`
+ * nullability, `input` → `req.input`, `errors` → `req.errors`, `output` → the
+ * return type. There is NO `method`/`path` on a handler — the HTTP verb + path
+ * are declared in a controller's route map, NOT on the handler. A handler file
+ * does:
+ *
+ *   // handlers/places/import-nearby.ts
+ *   export default defineHandler({ auth, input, output, errors, handler });
+ *
+ * # Runtime-readable shape (read by the Go runtime's extract_meta.js)
+ *
+ * `defineHandler` returns a {@link HandlerDef}: a plain object marked with
+ * `__palbase: "handler"` carrying the optional `auth`/`input`/`output`/`errors`
+ * and the `handler` function. There is deliberately NO `method`/`path` on it —
+ * a handler is route-agnostic.
+ */
+/** Configuration accepted by {@link defineHandler}. Carries the schema +
+ * auth/errors/middleware that type `req`, but NO `method` (routing lives in
+ * controllers). */
+interface HandlerConfig<TInputSchema extends ZodSchema = ZodSchema, TOutputSchema extends ZodSchema = ZodSchema, TAuth extends AuthSpec | undefined = undefined, TErrors extends ErrorMap | undefined = undefined> {
+    auth?: TAuth;
+    rateLimit?: RateLimitConfig;
+    input?: TInputSchema;
+    output?: TOutputSchema;
+    errors?: TErrors;
+    middleware?: Middleware[];
+    handler: (req: PBRequest<z.infer<TInputSchema>, IsAuthed<TAuth>, TErrors>) => Promise<z.infer<TOutputSchema>> | z.infer<TOutputSchema>;
+}
+/**
+ * The runtime-readable handler descriptor returned by {@link defineHandler}.
+ *
+ * Shape (the Go runtime's `extract_meta.js` reads this off the default export):
+ *
+ *   {
+ *     __palbase: "handler",
+ *     auth?:     AuthSpec,
+ *     rateLimit?: RateLimitConfig,
+ *     input?:    ZodSchema,
+ *     output?:   ZodSchema,
+ *     errors?:   ErrorMap,
+ *     middleware?: Middleware[],
+ *     handler:   (req) => result,   // the invoked function
+ *   }
+ *
+ * NOTE: there is NO `method`/`path` — those come from the controller route map.
+ */
+interface HandlerDef<TInputSchema extends ZodSchema = ZodSchema, TOutputSchema extends ZodSchema = ZodSchema, TAuth extends AuthSpec | undefined = undefined, TErrors extends ErrorMap | undefined = undefined> {
+    /** Discriminant the runtime + a controller route check read. */
+    readonly __palbase: "handler";
+    auth?: TAuth;
+    rateLimit?: RateLimitConfig;
+    input?: TInputSchema;
+    output?: TOutputSchema;
+    errors?: TErrors;
+    middleware?: Middleware[];
+    handler: (req: PBRequest<z.infer<TInputSchema>, IsAuthed<TAuth>, TErrors>) => Promise<z.infer<TOutputSchema>> | z.infer<TOutputSchema>;
+}
+/**
+ * A {@link HandlerDef} with its schema/auth/errors type params ERASED — the
+ * shape a controller's `route.*` stores. EVERY `defineHandler()` result (any
+ * `auth`/`input`/`output`/`errors`) is assignable to this, because `handler` is
+ * typed `(req: never) => unknown` (params are contravariant, so a handler taking
+ * any concrete `PBRequest` satisfies a `never` param). A controller only needs
+ * to route + carry the handler; the handler's own `req` typing is validated
+ * where it is defined, so erasing the params here is sound and lets a route
+ * accept a handler regardless of its `auth`/`errors` — without `any`.
+ */
+interface AnyHandlerDef {
+    readonly __palbase: "handler";
+    auth?: AuthSpec;
+    rateLimit?: RateLimitConfig;
+    input?: ZodSchema;
+    output?: ZodSchema;
+    errors?: ErrorMap;
+    middleware?: Middleware[];
+    handler: (req: never) => unknown;
+}
+/**
+ * Define an endpoint handler (schema + thin logic), with full `req` inference
+ * and NO routing. Mounted by a controller's `route.*` map.
+ *
+ * @example
+ * import { defineHandler, z, Database } from "@palbase/backend";
+ *
+ * export default defineHandler({
+ *   auth:   { required: true },
+ *   input:  z.object({ title: z.string() }),
+ *   output: z.object({ id: z.string() }),
+ *   errors: { titleTaken: { status: 409, code: "title_taken" } },
+ *   handler: (req) => Database.tables.todos.insert({ title: req.input.title }),
+ * });
+ */
+declare function defineHandler<TInputSchema extends ZodSchema, TOutputSchema extends ZodSchema, const TAuth extends AuthSpec | undefined = undefined, const TErrors extends ErrorMap | undefined = undefined>(config: HandlerConfig<TInputSchema, TOutputSchema, TAuth, TErrors>): HandlerDef<TInputSchema, TOutputSchema, TAuth, TErrors>;
+
+/**
+ * controller.ts — `defineController` + `route.*`: the ROUTE MAP (method+path →
+ * handler). Logic cannot be written here — a controller only wires existing
+ * handlers, so the small-blast-radius / no-cross-file-type-sync property holds.
+ *
+ * ```ts
+ * // controllers/places.controller.ts
+ * import { defineController, route } from "@palbase/backend";
+ * import importNearby  from "../handlers/places/import-nearby.js";
+ * import listFavorites from "../handlers/places/list-favorites.js";
+ *
+ * export default defineController("/places", {
+ *   importNearby:  route.post("/import",    importNearby),   // map key = sugar
+ *   listFavorites: route.get ("/favorites", listFavorites),
+ * });
+ * ```
+ *
+ * # Runtime-readable object shapes (read by the Go runtime's extract_meta.js)
+ *
+ * The default export of a controller file is a `ControllerDef`:
+ *
+ *   ControllerDef = {
+ *     __palbase: "controller",
+ *     basePath:  string,                      // e.g. "/places"
+ *     routes:    { [mapKey: string]: RouteDef } // mapKey is AUTHORING SUGAR only
+ *   }
+ *
+ *   RouteDef = {
+ *     __palbase: "route",
+ *     method:    "GET" | "POST" | "PUT" | "PATCH" | "DELETE",  // upper-case
+ *     path:      string,        // the SUBPATH passed to route.*(…), e.g. "/import"
+ *     handler:   HandlerDef,    // the imported defineHandler() result
+ *   }
+ *
+ *   HandlerDef = {
+ *     __palbase: "handler",
+ *     auth?, rateLimit?, input?, output?, errors?, middleware?,
+ *     handler:   (req) => result,
+ *   }
+ *
+ * The FULL path for a route is `basePath + path` (e.g. "/places" + "/import" =
+ * "/places/import"). The operationId is NOT computed here — the runtime
+ * `generator.go` derives it FLAT from `(method, full-path)` (e.g.
+ * `postPlacesImport`). The map key (`importNearby`) is authoring sugar and is
+ * NOT the operationId.
+ */
+/** The five HTTP verbs a route may declare, upper-cased (matches the runtime
+ * router + OpenAPI which lower-cases on its own). */
+type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * A single route entry: the HTTP verb, the SUBPATH (relative to the
+ * controller's `basePath`), and the handler to invoke. Produced by `route.*`.
+ */
+interface RouteDef<H extends AnyHandlerDef = AnyHandlerDef, M extends HttpMethodUpper = HttpMethodUpper> {
+    /** Discriminant the runtime + `defineController` read. */
+    readonly __palbase: "route";
+    /** Upper-case HTTP verb. */
+    method: M;
+    /** The subpath passed to `route.*(subpath, handler)` (relative to basePath). */
+    path: string;
+    /** The handler (a `defineHandler()` result) this route invokes. */
+    handler: H;
+}
+/** The route map a controller declares: keys are authoring sugar, values must
+ * each be a `route.*()` result. The mapped-over `Record<string, RouteDef>`
+ * constraint is what makes a bare handler (or plain object) a TS error. */
+type RouteMap = Record<string, RouteDef>;
+/**
+ * The controller descriptor returned by {@link defineController}. The default
+ * export of a `controllers/*.ts` file.
+ */
+interface ControllerDef<R extends RouteMap = RouteMap> {
+    /** Discriminant the runtime reads. */
+    readonly __palbase: "controller";
+    /** The path every route in this controller is mounted under (e.g. "/places"). */
+    basePath: string;
+    /** The route map — keys are authoring sugar, values are RouteDefs. */
+    routes: R;
+}
+/**
+ * Route builders — one per HTTP verb. Each takes the SUBPATH (relative to the
+ * controller `basePath`) and the handler to mount there.
+ *
+ * @example
+ * import { defineController, route } from "@palbase/backend";
+ * import create from "../handlers/todos/create.js";
+ *
+ * export default defineController("/todos", {
+ *   create: route.post("/", create),
+ * });
+ */
+declare const route: {
+    readonly get: <H extends AnyHandlerDef>(path: string, handler: H) => RouteDef<H, "GET">;
+    readonly post: <H extends AnyHandlerDef>(path: string, handler: H) => RouteDef<H, "POST">;
+    readonly put: <H extends AnyHandlerDef>(path: string, handler: H) => RouteDef<H, "PUT">;
+    readonly patch: <H extends AnyHandlerDef>(path: string, handler: H) => RouteDef<H, "PATCH">;
+    readonly delete: <H extends AnyHandlerDef>(path: string, handler: H) => RouteDef<H, "DELETE">;
+};
+/**
+ * Define a controller: a base path + a route map (method+path → handler). The
+ * route-map KEY is authoring sugar only (NOT the operationId). Each route value
+ * MUST be a `route.*()` result — a bare handler or plain object is a TS error,
+ * which is what keeps logic out of controllers structurally.
+ *
+ * @example
+ * import { defineController, route } from "@palbase/backend";
+ * import create from "../handlers/todos/create.js";
+ * import list   from "../handlers/todos/list.js";
+ *
+ * export default defineController("/todos", {
+ *   create: route.post("/", create),
+ *   list:   route.get("/", list),
+ * });
+ */
+declare function defineController<const R extends RouteMap>(basePath: string, routes: R): ControllerDef<R>;
+
+/** Non-service, per-invocation data for background worker handlers.
+ * Services (Database, Log, …) are imported as singletons, not passed here. */
+interface WorkerMeta {
+    /** Branch-scoped env vars. */
     env: Record<string, string>;
-    log: Logger;
-    cache: CacheClient;
-    queue: QueueClient;
-    errors: ErrorThrowers<undefined>;
+    /** The user that enqueued the job, if any (background jobs are usually system-initiated). */
+    user: User | null;
+    /** Per-invocation id for correlation. */
     requestId: string;
     projectId: string;
     environmentId: string;
@@ -236,7 +388,7 @@ interface WorkerConfig<TPayload = unknown> {
     /** Backoff strategy between retries. Defaults to "exponential". */
     backoff?: BackoffStrategy;
     /** Handler function that processes the job payload. */
-    handler: (ctx: WorkerContext, payload: TPayload) => Promise<void>;
+    handler: (payload: TPayload, meta: WorkerMeta) => Promise<void>;
 }
 /** Resolved worker configuration with defaults applied. */
 interface ResolvedWorkerConfig<TPayload = unknown> {
@@ -244,7 +396,7 @@ interface ResolvedWorkerConfig<TPayload = unknown> {
     retry: number;
     timeout: number;
     backoff: BackoffStrategy;
-    handler: (ctx: WorkerContext, payload: TPayload) => Promise<void>;
+    handler: (payload: TPayload, meta: WorkerMeta) => Promise<void>;
 }
 /**
  * Define a background worker that processes jobs from the queue.
@@ -258,7 +410,7 @@ interface ResolvedWorkerConfig<TPayload = unknown> {
  *   retry: 5,
  *   timeout: 60,
  *   backoff: "exponential",
- *   handler: async (ctx, payload: { to: string; subject: string }) => {
+ *   handler: async (payload: { to: string; subject: string }, meta) => {
  *     await sendEmail(payload.to, payload.subject);
  *   },
  * });
@@ -266,13 +418,11 @@ interface ResolvedWorkerConfig<TPayload = unknown> {
  */
 declare function defineWorker<TPayload = unknown>(config: WorkerConfig<TPayload>): ResolvedWorkerConfig<TPayload>;
 
-/** Context injected into job handlers — subset of EndpointContext without request-specific fields. */
-interface JobContext extends PalbaseModuleClients {
-    db: DBClient;
+/** Non-service, per-invocation data for job handlers.
+ * Services (Database, Log, …) are imported as singletons, not passed here. */
+interface JobMeta {
+    /** Branch-scoped env vars. */
     env: Record<string, string>;
-    log: Logger;
-    cache: CacheClient;
-    queue: QueueClient;
     projectId: string;
     environmentId: string;
 }
@@ -285,14 +435,14 @@ interface JobConfig {
     /** Execution timeout in seconds. Defaults to 30. */
     timeout?: number;
     /** Job handler function. */
-    handler: (ctx: JobContext) => Promise<void>;
+    handler: (meta: JobMeta) => Promise<void>;
 }
 /** Resolved job configuration with defaults applied. */
 interface ResolvedJobConfig {
     name: string;
     schedule: string;
     timeout: number;
-    handler: (ctx: JobContext) => Promise<void>;
+    handler: (meta: JobMeta) => Promise<void>;
 }
 /**
  * Define a scheduled cron job.
@@ -305,9 +455,9 @@ interface ResolvedJobConfig {
  *   name: "cleanup-expired",
  *   schedule: "0 3 * * *", // every day at 3 AM
  *   timeout: 60,
- *   handler: async (ctx) => {
- *     await ctx.db.delete("sessions", "expired < NOW()");
- *     ctx.log.info("Cleaned up expired sessions");
+ *   handler: async (meta) => {
+ *     await Database.delete("sessions", "expired < NOW()");
+ *     Log.info("Cleaned up expired sessions");
  *   },
  * });
  * ```
@@ -316,16 +466,15 @@ declare function defineJob(config: JobConfig): ResolvedJobConfig;
 
 /** Supported webhook provider types. */
 type WebhookProvider = "stripe" | "github" | "twilio" | "sendgrid" | "slack" | "discord" | "livekit";
-/** Context injected into webhook handlers — no user (webhooks are machine-to-machine). */
-interface WebhookContext extends PalbaseModuleClients {
-    db: DBClient;
+/** Non-service, per-invocation data for webhook handlers.
+ * Services (Database, Log, …) are imported as singletons, not passed here. */
+interface WebhookMeta {
+    /** Branch-scoped env vars. */
     env: Record<string, string>;
-    log: Logger;
-    cache: CacheClient;
-    queue: QueueClient;
+    /** Per-invocation id for correlation. */
+    requestId: string;
     projectId: string;
     environmentId: string;
-    requestId: string;
 }
 /** Secret reference — resolves from environment variables at runtime. */
 interface EnvSecretRef {
@@ -386,7 +535,7 @@ interface ProviderEventMap {
     };
 }
 /** Event handler function type. */
-type WebhookEventHandler<TEvent = Record<string, unknown>> = (ctx: WebhookContext, event: TEvent) => Promise<void>;
+type WebhookEventHandler<TEvent = Record<string, unknown>> = (event: TEvent, meta: WebhookMeta) => Promise<void>;
 /** Provider-based webhook configuration. */
 interface ProviderWebhookConfig<P extends WebhookProvider = WebhookProvider> {
     provider: P;
@@ -406,7 +555,7 @@ interface WebhookRequest {
 interface CustomWebhookConfig {
     path: string;
     verify?: (req: WebhookRequest) => Promise<boolean> | boolean;
-    handler: (ctx: WebhookContext, payload: Record<string, unknown>) => Promise<void>;
+    handler: (payload: Record<string, unknown>, meta: WebhookMeta) => Promise<void>;
 }
 /** Resolved provider webhook (internal). */
 interface ResolvedProviderWebhook<P extends WebhookProvider = WebhookProvider> {
@@ -420,7 +569,7 @@ interface ResolvedCustomWebhook {
     type: "custom";
     path: string;
     verify?: (req: WebhookRequest) => Promise<boolean> | boolean;
-    handler: (ctx: WebhookContext, payload: Record<string, unknown>) => Promise<void>;
+    handler: (payload: Record<string, unknown>, meta: WebhookMeta) => Promise<void>;
 }
 /** Union of resolved webhook types. */
 type ResolvedWebhookConfig = ResolvedProviderWebhook | ResolvedCustomWebhook;
@@ -433,8 +582,8 @@ type ResolvedWebhookConfig = ResolvedProviderWebhook | ResolvedCustomWebhook;
  *   provider: "stripe",
  *   secret: { env: "STRIPE_WEBHOOK_SECRET" },
  *   events: {
- *     "checkout.session.completed": async (ctx, event) => {
- *       await ctx.db.insert("orders", { status: "paid" });
+ *     "checkout.session.completed": async (event, meta) => {
+ *       await Database.insert("orders", { status: "paid" });
  *     },
  *   },
  * });
@@ -449,21 +598,111 @@ declare function defineWebhook<P extends WebhookProvider>(config: ProviderWebhoo
  * export default defineWebhook({
  *   path: "/webhooks/livekit",
  *   verify: async (req) => req.headers["x-api-key"] === "secret",
- *   handler: async (ctx, payload) => {
- *     ctx.log.info("Received webhook", payload);
+ *   handler: async (payload, meta) => {
+ *     Log.info("Received webhook", payload);
  *   },
  * });
  * ```
  */
 declare function defineWebhook(config: CustomWebhookConfig): ResolvedCustomWebhook;
 
-/** Context injected into hook handlers. */
-interface HookContext extends PalbaseModuleClients {
-    db: DBClient;
+/**
+ * resource.ts — external connections as lifecycle-managed classes.
+ *
+ * A `Resource` subclass models one external connection (a pooled datastore, a
+ * stateless API client, or a per-user factory). The framework discovers each
+ * instance, calls `init(env)` ONCE at boot with the declared secret subset, and
+ * `shutdown()` (reverse order) on SIGTERM. On top of that lifecycle the author
+ * exposes their own clean facade methods.
+ *
+ *   // resources/neo4j.ts
+ *   import { Resource } from "@palbase/backend";
+ *   import neo4j, { type Driver, type Session } from "neo4j-driver";
+ *
+ *   export class Neo4jResource extends Resource {
+ *     static secrets = ["NEO4J_URL", "NEO4J_USER", "NEO4J_PASSWORD"] as const;
+ *     private driver!: Driver;
+ *     async init(env: { NEO4J_URL: string; NEO4J_USER: string; NEO4J_PASSWORD: string }) {
+ *       this.driver = neo4j.driver(env.NEO4J_URL, neo4j.auth.basic(env.NEO4J_USER, env.NEO4J_PASSWORD));
+ *     }
+ *     async shutdown() { await this.driver.close(); }
+ *     session(): Session { return this.driver.session(); }
+ *   }
+ *   export const neo4j = new Neo4jResource();  // framework finds + manages it
+ *
+ * # Boot scope (NOT request-ALS)
+ *
+ * Resources are instantiated once at process boot. This is deliberately NOT the
+ * per-request {@link AsyncLocalStorage} scope used for `Database`/`Cache`/… — a
+ * connection pool must outlive a single request. The runtime discovers
+ * resources from the project's `resources/` directory, registers each via
+ * {@link __registerResource}, then calls {@link __runResourceBoot} before
+ * serving and {@link __shutdownResources} on SIGTERM. Discovery is a runtime
+ * concern; the SDK provides the base class + registry + boot/shutdown hooks.
+ */
+/** Map a declared `secrets` tuple to the `init(env)` argument type — a record
+ * over the secret names, each `string`. An empty tuple maps to an empty
+ * record. */
+type ResourceEnv<Secrets extends readonly string[]> = {
+    [K in Secrets[number]]: string;
+};
+/**
+ * Base class for external connections.
+ *
+ * - `static secrets` — OPTIONAL readonly tuple of env-var names this resource
+ *   needs. Drives (a) the `env` type passed to `init` and (b) the
+ *   missing-secret check at boot (deploy fails naming the absent secret).
+ * - `init(env)` — called ONCE at boot with the declared secret subset. May be
+ *   sync (`void`) or async (`Promise<void>`).
+ * - `shutdown()` — OPTIONAL drain hook, called on SIGTERM in reverse boot
+ *   order.
+ *
+ * @example
+ * import { Resource } from "@palbase/backend";
+ * import { Client } from "@googlemaps/google-maps-services-js";
+ *
+ * export class GoogleResource extends Resource {
+ *   static secrets = ["GOOGLE_MAPS_KEY"] as const;
+ *   private client = new Client();
+ *   private key = "";
+ *   init(env: { GOOGLE_MAPS_KEY: string }) { this.key = env.GOOGLE_MAPS_KEY; }
+ * }
+ * export const google = new GoogleResource();
+ */
+declare abstract class Resource {
+    /** The env-var names this resource needs. Optional; omit for none. */
+    static secrets?: readonly string[];
+    /** Set up the connection from the declared secrets. Called once at boot. */
+    abstract init(env: Record<string, string>): void | Promise<void>;
+    /** Drain/close the connection on SIGTERM. Optional. */
+    shutdown?(): void | Promise<void>;
+}
+/**
+ * Register a resource instance with the boot registry. The runtime calls this
+ * for each instance discovered under the project's `resources/` directory.
+ * NOT part of the public author-facing API (prefixed `__`).
+ */
+declare function __registerResource(resource: Resource): void;
+/**
+ * Boot every registered resource that has not yet been booted: resolve its
+ * declared secret subset from `envMap`, then await its `init(env)`. Idempotent
+ * — an already-booted resource is skipped. Throws (failing deploy/boot) when a
+ * declared secret is absent, naming the missing secret. NOT part of the public
+ * author-facing API.
+ */
+declare function __runResourceBoot(envMap: Record<string, string>): Promise<void>;
+/**
+ * Shut down every booted resource in REVERSE registration order, awaiting each
+ * `shutdown()` (a no-op when undefined). Clears the registry afterwards so a
+ * second call is a no-op. NOT part of the public author-facing API.
+ */
+declare function __shutdownResources(): Promise<void>;
+
+/** Non-service, per-invocation data for hook handlers.
+ * Services (Database, Log, …) are imported as singletons, not passed here. */
+interface HookMeta {
+    /** Branch-scoped env vars. */
     env: Record<string, string>;
-    log: Logger;
-    cache: CacheClient;
-    queue: QueueClient;
     projectId: string;
     environmentId: string;
 }
@@ -471,7 +710,8 @@ interface HookContext extends PalbaseModuleClients {
 interface UserCreatedEvent {
     user: {
         id: string;
-        email: string;
+        /** User's email, if they signed up with one (absent for phone-only users). */
+        email?: string;
         role: string;
         metadata: Record<string, unknown>;
         createdAt: string;
@@ -481,7 +721,8 @@ interface UserCreatedEvent {
 interface SignInEvent {
     user: {
         id: string;
-        email: string;
+        /** User's email, if they have one (absent for phone-only users). */
+        email?: string;
         role: string;
     };
     provider: string;
@@ -491,11 +732,14 @@ interface SignInEvent {
 interface SignOutEvent {
     user: {
         id: string;
-        email: string;
+        /** User's email, if they have one (absent for phone-only users). */
+        email?: string;
     };
     timestamp: string;
 }
-/** Payload for auth.onPasswordReset hook. */
+/** Payload for auth.onPasswordReset hook.
+ * Password reset is inherently email-based, so `email` is always present here
+ * (a phone-only passwordless user cannot trigger this event). */
 interface PasswordResetEvent {
     user: {
         id: string;
@@ -548,7 +792,7 @@ interface DocumentDeletedEvent {
         data: Record<string, unknown>;
     };
 }
-type HookHandler<TEvent> = (ctx: HookContext, event: TEvent) => Promise<void>;
+type HookHandler<TEvent> = (event: TEvent, meta: HookMeta) => Promise<void>;
 /** Resolved hook configuration (internal). */
 interface ResolvedHook<TEvent = unknown> {
     module: string;
@@ -571,4 +815,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-export { type BackoffStrategy, Cache, CacheClient, type CustomWebhookConfig, DBClient, Database, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, type EnvSecretRef, ErrorThrowers, type FileDeletedEvent, type FileUploadedEvent, Flags, type HookContext, type HookHandler, type InsertShape, type JobConfig, type JobContext, Log, Logger, Notifications, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseStorageClient, type PasswordResetEvent, type ProviderEventMap, type ProviderWebhookConfig, Queue, QueueClient, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, type RowShape, type RuntimeServices, SchemaDef, type SignInEvent, type SignOutEvent, Storage, TableDef, type TypedDB, type TypedTable, type TypedTx, User, type UserCreatedEvent, type WebhookContext, type WebhookEventHandler, type WebhookProvider, type WebhookRequest, type WorkerConfig, type WorkerContext, __getRuntime, __requestALS, __runWithRuntime, __setRuntime, auth, defineJob, defineWebhook, defineWorker, documents, makeTypedDB, storage, typedDatabase };
+export { type BackoffStrategy, Cache, CacheClient, type ControllerDef, type CustomWebhookConfig, DBClient, Database, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, type EnvSecretRef, EnvTypedDatabase, ErrorMap, type FileDeletedEvent, type FileUploadedEvent, Flags, type HandlerConfig, type HandlerDef, type HookHandler, type HookMeta, type HttpMethodUpper, type JobConfig, type JobMeta, Log, Logger, Middleware, Notifications, PBRequest, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseStorageClient, type PasswordResetEvent, type ProviderEventMap, type ProviderWebhookConfig, Queue, QueueClient, RateLimitConfig, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, Resource, type ResourceEnv, type RouteDef, type RouteMap, type RuntimeServices, SchemaDef, type SignInEvent, type SignOutEvent, Storage, User, type UserCreatedEvent, type WebhookEventHandler, type WebhookMeta, type WebhookProvider, type WebhookRequest, type WorkerConfig, type WorkerMeta, __getRuntime, __registerResource, __requestALS, __runResourceBoot, __runWithRuntime, __setRuntime, __shutdownResources, auth, defineController, defineHandler, defineJob, defineWebhook, defineWorker, documents, makeEnvDts, route, storage };