@palbase/backend 3.0.0 → 5.0.0

package/dist/index.d.cts

@@ -1,26 +1,26 @@
-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 { 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-BEHjfvFH.cjs';
+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-BEHjfvFH.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-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';
+import { E as EnvTypedDatabase, S as SchemaDef } from './index-mr3Co63T.cjs';
+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-mr3Co63T.cjs';
 export { TableTypes, Tables } from './db/env.cjs';
-import { ZodSchema, z } from 'zod';
+import { ZodTypeAny } from 'zod';
 export { z } from 'zod';
 
 /**
  * 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 defineHandler({
- *     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}.
@@ -100,12 +100,17 @@ declare function __getRuntime(): RuntimeServices;
  * 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). */
@@ -149,219 +154,75 @@ declare const Flags: PalbaseFlagsClient;
  */
 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";
+/** Options accepted by `@Controller`. */
+interface ControllerOptions {
+    /** Default auth for ALL routes in this controller (route-level overrides). */
     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.
+ * 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
- * 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 }),
- * });
+ * \@Controller("/todos", { auth: false })
+ * export class TodosController {
+ *   \@Get("") list(\@Query(ListTodosQuery) q: ListTodosQuery): TodoSchema[] { … }
+ * }
  */
-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>;
+declare function Controller(basePath: string, options?: ControllerOptions): <T extends abstract new (...args: never[]) => object>(ctor: T) => T;
 
-/**
- * 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). */
+/** 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";
-/**
- * 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-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;
 }
-/**
- * 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>;
+
+/** 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;
+
+/** 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. */
@@ -369,7 +230,7 @@ interface WorkerMeta {
     /** Branch-scoped env vars. */
     env: Record<string, string>;
     /** The user that enqueued the job, if any (background jobs are usually system-initiated). */
-    user: User | null;
+    user: User$1 | null;
     /** Per-invocation id for correlation. */
     requestId: string;
     projectId: string;
@@ -815,4 +676,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-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 };
+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, 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 };