@palbase/backend 2.0.2 → 4.0.0

package/dist/index.d.ts

@@ -1,110 +1,26 @@
-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-Djk5L6G2.js';
-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-Djk5L6G2.js';
+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, U as User$1 } from './endpoint-2d_DpASt.js';
+export { f as AuthConfig, B as BadRequest, g as ClientInfo, h as Conflict, i as DBOps, E as ErrorDef, j as ErrorMap, k as ErrorThrowers, F as FileContext, l as Forbidden, H as HttpError, m as HttpMethod, M as Middleware, n as MiddlewareContext, o as MiddlewareHandler, N as NotFound, P as PBRequest, p as PalError, q as PalbaseAnalyticsClient, r as PalbaseAnalyticsManagementNamespace, s as PalbaseAnalyticsProperties, t as PalbaseAnalyticsQueryNamespace, u as PalbaseAttestAndroidParams, v as PalbaseAttestAndroidResult, w as PalbaseAttestiOSParams, x as PalbaseAttestiOSResult, y as PalbaseAuthClient, z as PalbaseBindDeviceParams, G as PalbaseBucketClient, I as PalbaseCmsClient, J as PalbaseCmsFindOneOptions, K as PalbaseCmsFindOptions, O as PalbaseCohortQueryInput, S as PalbaseCohortResult, T as PalbaseCollectionRef, V as PalbaseCountQueryInput, W as PalbaseCountResult, X as PalbaseCreateLinkParams, Y as PalbaseDeviceInfo, Z as PalbaseDeviceTokenView, _ as PalbaseDocumentRef, $ as PalbaseDocumentSnapshot, a0 as PalbaseEmailClient, a1 as PalbaseEmailSendParams, a2 as PalbaseEmailSendResponse, a3 as PalbaseEventNamesResult, a4 as PalbaseEventsQueryInput, a5 as PalbaseEventsResult, a6 as PalbaseFileObject, a7 as PalbaseFlag, a8 as PalbaseFlagContext, a9 as PalbaseFlagVariant, aa as PalbaseFunctionsClient, ab as PalbaseFunnelQueryInput, ac as PalbaseFunnelResult, ad as PalbaseIdentifyTraits, ae as PalbaseInboxClient, af as PalbaseInboxListOptions, ag as PalbaseInboxListResult, ah as PalbaseInboxMessage, ai as PalbaseInboxSendParams, aj as PalbaseInboxSendResponse, ak as PalbaseInitialLink, al as PalbaseInvokeOptions, am as PalbaseLink, an as PalbaseLinkAnalytics, ao as PalbaseLinkDetails, ap as PalbaseLinksClient, aq as PalbaseListLinksOptions, ar as PalbaseListLinksResult, as as PalbaseListOptions, at as PalbaseMatchParams, au as PalbaseMultiChannelResponse, av as PalbaseOverviewResult, aw as PalbasePreferences, ax as PalbasePreferencesClient, ay as PalbasePublicUrlResponse, az as PalbasePushClient, aA as PalbasePushSendParams, aB as PalbasePushSendResponse, aC as PalbaseQrCodeOptions, aD as PalbaseQuerySnapshot, aE as PalbaseRealtimeChannel, aF as PalbaseRealtimeClient, aG as PalbaseRealtimeMessage, aH as PalbaseRegisterDeviceParams, aI as PalbaseResult, aJ as PalbaseRetentionQueryInput, aK as PalbaseRetentionResult, aL as PalbaseSession, aM as PalbaseSignedUrlResponse, aN as PalbaseSmsClient, aO as PalbaseSmsSendParams, aP as PalbaseSmsSendResponse, aQ as PalbaseTransformOptions, aR as PalbaseUpdateLinkParams, aS as PalbaseUploadOptions, aT as PalbaseUser, aU as PalbaseUserDetailResult, aV as PalbaseUsersQueryInput, aW as PalbaseUsersResult, aX as PalbaseVerifyRequestSignatureParams, aY as PalbaseWhereOperator, aZ as TooManyRequests, a_ as TxClient, a$ as Unauthorized, b0 as defineMiddleware } from './endpoint-2d_DpASt.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { T as TableDef, C as ColIsOptionalOnInsert, a as ColValue, S as SchemaDef } from './schema-BqfEhIC0.js';
-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.js';
+import { E as EnvTypedDatabase, S as SchemaDef } from './index-DZW9CjiY.js';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, f as EnvTables, g as EnvTypedTable, h as EnvTypedTx, 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, 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-DZW9CjiY.js';
+export { TableTypes, Tables } from './db/env.js';
+import { ZodTypeAny } 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.
  *
  * The backend SDK no longer threads a `ctx` god-object through every handler.
- * Instead, endpoint authors import PascalCase service singletons directly:
+ * Instead, controller methods import PascalCase service singletons directly:
  *
- *   import { Database, Documents, Cache } from "@palbase/backend";
+ *   import { Controller, Post, Body, Database } from "@palbase/backend";
  *
- *   export default defineEndpoint({
- *     method: "POST",
- *     handler: async (req) => {
- *       const row = await Database.insert("todos", { title: req.input.title });
- *       return row;
- *     },
- *   });
+ *   \@Controller("/todos")
+ *   export default class TodosController {
+ *     \@Post("") create(\@Body(CreateTodoBody) body: CreateTodoBody): unknown {
+ *       return Database.insert("todos", { title: body.title });
+ *     }
+ *   }
  *
  * The singletons are thin Proxies. Every property access forwards to the live
  * client for the CURRENT request scope, resolved through {@link __getRuntime}.
@@ -176,10 +92,27 @@ 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.
+ *
+ * RLS is enforced by default (the runtime runs each op as `authenticated` with
+ * the verified user's claims). To bypass RLS, call `Database.asService()` —
+ * explicit and greppable — which runs as the `service_role` (BYPASSRLS).
+ *
+ * @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]);
+ * const all  = await Database.asService().tables.todos.findMany({}); // RLS bypass
+ */
+declare const Database: EnvTypedDatabase;
 /** Firestore-like document client (PalDocs). */
 declare const Documents: PalbaseDocsClient;
 /** Object storage client (buckets, signed URLs). */
@@ -194,31 +127,123 @@ 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.
+ *
+ * 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.
  *
- *   const Db = typedDatabase(schema);
- *   const todo = await Db.tables.todos.insert({ title: "x" });
+ * 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`.
+ */
+
+/**
+ * Generate the full `palbase-env.d.ts` text for a schema.
  *
- * This is per-endpoint (not global module augmentation), so one endpoint's
- * tables never leak into another's `Database` type.
+ * @example
+ * import { makeEnvDts } from "@palbase/backend";
+ * import schema from "./db/schema.js";
+ * writeFileSync("palbase-env.d.ts", makeEnvDts(schema));
  */
-declare function typedDatabase<TSchema extends SchemaDef>(schema: TSchema): TypedDB<TSchema> & DBClient;
+declare function makeEnvDts(schema: SchemaDef): string;
 
-/** 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;
+/** Options accepted by `@Controller`. */
+interface ControllerOptions {
+    /** Default auth for ALL routes in this controller (route-level overrides). */
+    auth?: AuthSpec;
+}
+/**
+ * Mark a class as a Palbase backend controller. `basePath` is the mount path
+ * for every route the class declares; `options.auth` sets the controller-level
+ * default auth (a route's own `auth` overrides it; absent ⇒ secure-by-default).
+ *
+ * @example
+ * \@Controller("/todos", { auth: false })
+ * export class TodosController {
+ *   \@Get("") list(\@Query(ListTodosQuery) q: ListTodosQuery): TodoSchema[] { … }
+ * }
+ */
+declare function Controller(basePath: string, options?: ControllerOptions): <T extends abstract new (...args: never[]) => object>(ctor: T) => T;
+
+/** The HTTP verbs a route may declare, upper-cased (the runtime router +
+ * OpenAPI lower-case on their own). */
+type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */
+interface RouteOptions {
+    /** OVERRIDES the controller-level default auth for this one route. */
+    auth?: AuthSpec;
+    /** Per-route rate limit. */
+    rateLimit?: RateLimitConfig;
+}
+
+/** A legacy method decorator. */
+type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/** `@Get(subpath, options?)` — declare a GET route. */
+declare const Get: (subpath: string, options?: RouteOptions) => MethodDecorator;
+/** `@Post(subpath, options?)` — declare a POST route. */
+declare const Post: (subpath: string, options?: RouteOptions) => MethodDecorator;
+/** `@Put(subpath, options?)` — declare a PUT route. */
+declare const Put: (subpath: string, options?: RouteOptions) => MethodDecorator;
+/** `@Patch(subpath, options?)` — declare a PATCH route. */
+declare const Patch: (subpath: string, options?: RouteOptions) => MethodDecorator;
+/** `@Delete(subpath, options?)` — declare a DELETE route. */
+declare const Delete: (subpath: string, options?: RouteOptions) => MethodDecorator;
+/**
+ * `@Returns(schema)` — declare the route's success-response zod schema. The
+ * method's return TYPE drives compile-time checking; `@Returns` supplies the
+ * matching zod VALUE the OpenAPI generator reads for the 200 response. Optional:
+ * a `void` method (no response body) omits it.
+ *
+ * @example
+ * \@Get("/{id}")
+ * \@Returns(TodoSchema)
+ * getOne(\@Param("id") id: string): TodoSchema { … }
+ */
+declare function Returns(schema: ZodTypeAny): MethodDecorator;
+
+/** A legacy parameter decorator. */
+type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/** `@Body(schema)` — inject the request body, validated against `schema`. The
+ * developer writes `: T` (= `z.infer<schema>`, same name) for autocomplete. */
+declare function Body(schema: ZodTypeAny): ParameterDecorator;
+/** `@Query(schema)` — inject the parsed query params, validated against
+ * `schema`. */
+declare function Query(schema: ZodTypeAny): ParameterDecorator;
+/** `@Headers(schema?)` — inject the request headers (lowercase keys). With a
+ * schema, headers are validated + the codegen emits header parameters. */
+declare function Headers(schema?: ZodTypeAny): ParameterDecorator;
+/** `@Param("id")` — inject one matched path param by name. */
+declare function Param(name: string): ParameterDecorator;
+/** `@User()` — inject the authenticated user (`: User`, non-null for an
+ * effective-required route). The runtime resolves the effective auth. */
+declare function User(): ParameterDecorator;
+/** `@OptionalUser()` — inject the user as `User | null` (for routes whose
+ * effective auth is `false` / `{ required: false }`). */
+declare function OptionalUser(): ParameterDecorator;
+/** `@Client()` — inject the parsed calling-client metadata (`: ClientInfo`). */
+declare function Client(): ParameterDecorator;
+/** `@RequestId()` — inject the per-request id (`: string`). */
+declare function RequestId(): ParameterDecorator;
+/** `@TraceId()` — inject the W3C trace id (`: string`). */
+declare function TraceId(): ParameterDecorator;
+/** `@Req()` — inject the raw request object (escape hatch, `: PBRequest`). */
+declare function Req(): ParameterDecorator;
+
+/** 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$1 | null;
+    /** Per-invocation id for correlation. */
     requestId: string;
     projectId: string;
     environmentId: string;
@@ -236,7 +261,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 +269,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 +283,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 +291,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 +308,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 +328,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 +339,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 +408,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 +428,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 +442,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 +455,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 +471,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 +583,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 +594,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 +605,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 +665,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 +688,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, Body, Cache, CacheClient, Client, Controller, type ControllerOptions, type CustomWebhookConfig, DBClient, Database, Delete, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, type EnvSecretRef, EnvTypedDatabase, type FileDeletedEvent, type FileUploadedEvent, Flags, Get, Headers, type HookHandler, type HookMeta, type HttpMethodUpper, type JobConfig, type JobMeta, Log, Logger, Notifications, OptionalUser, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseStorageClient, Param, type PasswordResetEvent, Patch, Post, type ProviderEventMap, type ProviderWebhookConfig, Put, Query, Queue, QueueClient, RateLimitConfig, Req, RequestId, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, Resource, type ResourceEnv, Returns, type RouteOptions, type RuntimeServices, SchemaDef, type SignInEvent, type SignOutEvent, Storage, TraceId, User, type UserCreatedEvent, User$1 as UserT, type WebhookEventHandler, type WebhookMeta, type WebhookProvider, type WebhookRequest, type WorkerConfig, type WorkerMeta, __getRuntime, __registerResource, __requestALS, __runResourceBoot, __runWithRuntime, __setRuntime, __shutdownResources, auth, defineJob, defineWebhook, defineWorker, documents, makeEnvDts, storage };