@palbase/backend 0.9.0 → 1.0.0

package/dist/{endpoint-DysSe3SI.d.ts → endpoint-knNIeovM.d.ts}

@@ -1,5 +1,5 @@
 import { ZodSchema, z } from 'zod';
-import { S as SchemaDef, T as TableDef, h as ColIsOptionalOnInsert, k as ColValue } from './schema-zk-a0Dv7.js';
+import { S as SchemaDef } from './schema-BqfEhIC0.js';
 
 /** Supported HTTP methods for endpoints. */
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -47,77 +47,43 @@ type MiddlewareHandler = (ctx: MiddlewareContext, next: () => Promise<void>) =>
  */
 declare function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler;
 
-/**
- * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
+/** HTTP error with structured error response format.
  *
- * Derives INSERT and full-row TypeScript types from a `defineSchema()` result
- * and wraps the untyped runtime `DBClient` with a typed facade.
+ * Two ways to construct one:
  *
- * 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.
+ *   1. Directly: `throw new HttpError(404, "todo_not_found", "No such todo")`.
+ *      Surfaces on the wire (and to iOS) as `BackendError.server(code, status,
+ *      message, requestId)`.
+ *   2. Via `ctx.errors.<name>(data?)` for declared errors — see
+ *      `EndpointConfig.errors`. The endpoint's OpenAPI spec describes each
+ *      one, and the CLI codegen emits a typed `<Endpoint>.Error` enum so iOS
+ *      callers can `catch <Endpoint>.Error.<case>` directly.
  *
- * 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`.
+ * The optional `data` field carries a structured payload alongside the
+ * standard envelope — used by declared errors that need to ship extra context
+ * (e.g. `todoLocked({ retryAfter: 30 })`). It rides through to the iOS typed
+ * enum's associated value.
  */
-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]>;
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly error: string;
+    readonly errorDescription: string;
+    readonly data?: unknown;
+    constructor(status: number, error: string, errorDescription: string, data?: unknown);
+    /**
+     * Serialize to the standard Palbase error response format.
+     * The `requestId` is injected by the runtime layer from the request context.
+     * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+     * When `data` is set, it is appended as a strict-superset field.
+     */
+    toJSON(requestId?: string): {
+        error: string;
+        error_description: string;
+        status: number;
+        request_id?: string;
+        data?: unknown;
     };
 }
-/**
- * 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.
- *
- * The `satisfies` check verifies the built object is structurally compatible
- * before we present it as `TypedDB<S>`. The final `as TypedDB<S>` is a
- * single structural narrowing from the dynamically-built type to the precise
- * mapped type (TS cannot infer through `Object.keys` iteration).
- */
-declare function makeTypedDB<S extends SchemaDef>(schema: S, raw: DBClient): TypedDB<S>;
 
 /**
  * Local typed interfaces for the 9 Palbase module clients injected into
@@ -331,7 +297,18 @@ interface PalbasePushSendResponse {
 interface PalbaseEmailSendParams {
     to: string | string[];
     subject?: string;
+    /**
+     * @deprecated The server reads `template_slug`, not `template` — this
+     * field is forwarded as-is and ignored by palnotify. Use `templateSlug`
+     * instead. Retained for source-compat with older callers.
+     */
     template?: string;
+    /**
+     * Server email-template slug. The notifications client maps this to the
+     * wire field `template_slug` (mutually exclusive with `subject` + body
+     * fields when not overriding template output).
+     */
+    templateSlug?: string;
     variables?: Record<string, unknown>;
     html?: string;
     text?: string;
@@ -350,7 +327,18 @@ interface PalbaseEmailSendResponse {
 /** SMS send params. */
 interface PalbaseSmsSendParams {
     to: string | string[];
-    body: string;
+    /**
+     * SMS body text. Either `body` OR `templateSlug` must be supplied —
+     * the two are mutually exclusive at the server.
+     */
+    body?: string;
+    /**
+     * Server SMS-template slug. The notifications client maps this to the
+     * wire field `template_slug`. When provided, palnotify renders the
+     * template with `variables` and uses the result as the SMS body.
+     */
+    templateSlug?: string;
+    variables?: Record<string, unknown>;
     category?: string;
 }
 /** SMS send response. */
@@ -422,6 +410,56 @@ interface PalbaseRegisterDeviceParams {
     app_version?: string;
     locale?: string;
 }
+/** Email template view (camelCase). */
+interface PalbaseEmailTemplate {
+    id: string;
+    projectId: string;
+    slug: string;
+    subject: string;
+    htmlBody: string;
+    textBody?: string;
+    variables: string[];
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for templates.email.create. */
+interface PalbaseCreateEmailTemplateInput {
+    slug: string;
+    subject: string;
+    htmlBody: string;
+    textBody?: string;
+    variables?: string[];
+}
+/** Payload for templates.email.update — patch semantics. */
+interface PalbaseUpdateEmailTemplateInput {
+    subject?: string;
+    htmlBody?: string;
+    textBody?: string;
+    variables?: string[];
+}
+/** SMS template view (camelCase). No subject / html / text distinction. */
+interface PalbaseSMSTemplate {
+    id: string;
+    projectId: string;
+    slug: string;
+    body: string;
+    variables: string[];
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload for templates.sms.create. */
+interface PalbaseCreateSMSTemplateInput {
+    slug: string;
+    body: string;
+    variables?: string[];
+}
+/** Payload for templates.sms.update — patch semantics. */
+interface PalbaseUpdateSMSTemplateInput {
+    body?: string;
+    variables?: string[];
+}
 /** Analytics event properties. */
 type PalbaseAnalyticsProperties = Record<string, unknown>;
 /** Analytics identify traits. */
@@ -952,6 +990,47 @@ interface PalbasePreferencesClient {
     /** Update notification preferences. */
     update(params: PalbasePreferences): Promise<PalbaseResult<PalbasePreferences>>;
 }
+/**
+ * Email-template CRUD sub-client (service-role gated server-side).
+ */
+interface PalbaseEmailTemplatesClient {
+    /** List all email templates. */
+    list(): Promise<PalbaseResult<PalbaseEmailTemplate[]>>;
+    /** Get one email template by ID. */
+    get(id: string): Promise<PalbaseResult<PalbaseEmailTemplate>>;
+    /** Create an email template. */
+    create(input: PalbaseCreateEmailTemplateInput): Promise<PalbaseResult<PalbaseEmailTemplate>>;
+    /** Update an email template (patch semantics). */
+    update(id: string, input: PalbaseUpdateEmailTemplateInput): Promise<PalbaseResult<PalbaseEmailTemplate>>;
+    /** Delete an email template. */
+    delete(id: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * SMS-template CRUD sub-client (service-role gated server-side).
+ */
+interface PalbaseSMSTemplatesClient {
+    /** List all SMS templates. */
+    list(): Promise<PalbaseResult<PalbaseSMSTemplate[]>>;
+    /** Get one SMS template by ID. */
+    get(id: string): Promise<PalbaseResult<PalbaseSMSTemplate>>;
+    /** Create an SMS template. */
+    create(input: PalbaseCreateSMSTemplateInput): Promise<PalbaseResult<PalbaseSMSTemplate>>;
+    /** Update an SMS template (patch semantics). */
+    update(id: string, input: PalbaseUpdateSMSTemplateInput): Promise<PalbaseResult<PalbaseSMSTemplate>>;
+    /** Delete an SMS template. */
+    delete(id: string): Promise<PalbaseResult<void>>;
+}
+/**
+ * Templates sub-client — parallel CRUD for email and SMS templates.
+ * Service-role gated server-side; both surfaces map TS camelCase to
+ * wire snake_case in the runtime client.
+ */
+interface PalbaseTemplatesClient {
+    /** Email template CRUD. */
+    email: PalbaseEmailTemplatesClient;
+    /** SMS template CRUD. */
+    sms: PalbaseSMSTemplatesClient;
+}
 /**
  * Notifications client available on `ctx.notifications`.
  * Service-role: all send operations require privileged access.
@@ -968,6 +1047,8 @@ interface PalbaseNotificationsClient {
     inbox: PalbaseInboxClient;
     /** Notification preferences manager. */
     preferences: PalbasePreferencesClient;
+    /** Email + SMS template CRUD (service-role). */
+    templates: PalbaseTemplatesClient;
     /** Register a device for push notifications. */
     registerDevice(params: PalbaseRegisterDeviceParams): Promise<PalbaseResult<PalbaseDeviceTokenView>>;
     /** Remove a device registration. */
@@ -1080,6 +1161,8 @@ interface RateLimitConfig {
     /** Window duration in seconds. */
     window: number;
 }
+/** The transaction-scoped client passed to `db.transaction(fn)` — same DB ops, no nested transaction. */
+type TxClient = Omit<DBClient, "transaction">;
 /** Database client interface injected into endpoint context. */
 interface DBClient {
     /** Run a read-only SQL query (executes in a READ ONLY transaction). */
@@ -1089,6 +1172,12 @@ interface DBClient {
     delete(table: string, id: string): Promise<void>;
     findById(table: string, id: string): Promise<Record<string, unknown> | null>;
     findMany(table: string, query?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /**
+     * Run an interactive transaction. The callback receives a `tx` with the same
+     * DB ops as this client; returning normally commits, throwing rolls back.
+     * Nested transactions are not supported.
+     */
+    transaction<T>(fn: (tx: TxClient) => Promise<T>): Promise<T>;
 }
 /** Logger interface injected into endpoint context. */
 interface Logger {
@@ -1151,7 +1240,7 @@ interface PalbaseQuerySnapshot<T = Record<string, unknown>> {
 }
 /** Comparison operators supported by docs.where(). */
 type PalbaseWhereOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "array-contains";
-/** Document reference exposed by ctx.docs.collection(...).doc(...). */
+/** Document reference exposed by Documents.collection(...).doc(...). */
 interface PalbaseDocumentRef<T = Record<string, unknown>> {
     readonly path: string;
     set(data: T): Promise<PalbaseResult<void>>;
@@ -1159,7 +1248,7 @@ interface PalbaseDocumentRef<T = Record<string, unknown>> {
     update(data: Partial<T>): Promise<PalbaseResult<void>>;
     delete(): Promise<PalbaseResult<void>>;
 }
-/** Collection reference exposed by ctx.docs.collection(...). */
+/** Collection reference exposed by Documents.collection(...). */
 interface PalbaseCollectionRef<T = Record<string, unknown>> {
     readonly path: string;
     doc(id: string): PalbaseDocumentRef<T>;
@@ -1169,23 +1258,39 @@ interface PalbaseCollectionRef<T = Record<string, unknown>> {
     limit(n: number): PalbaseCollectionRef<T>;
     get(): Promise<PalbaseResult<PalbaseQuerySnapshot<T>>>;
 }
-/** Docs client surface available on ctx.docs. */
+/** Docs client surface available on the Documents singleton. */
 interface PalbaseDocsClient {
     collection<T = Record<string, unknown>>(path: string): PalbaseCollectionRef<T>;
     doc<T = Record<string, unknown>>(path: string): PalbaseDocumentRef<T>;
 }
-/** Palbase module clients surfaced directly on every context.
+/** Calling-client metadata, derived from request headers.
  *
- * `ctx.docs`, `ctx.storage`, … — no `ctx.palbase.*` namespace. Structurally
- * typed against the runtime's `ServerClient`; the runtime injects the real
- * client, so mismatched names would surface as `undefined is not a function`
- * at call time — keep these in sync with `ServerClient`.
+ * Populated from the `X-Palbase-*-Version` / platform headers the client SDKs
+ * send. All fields are nullable: a request may come from a non-SDK caller
+ * (curl, server-to-server) that sends none of them. The semver comparison
+ * helpers (`appVersionAtLeast`, …) arrive in Phase 2 — Phase 1 surfaces only
+ * the raw data fields. */
+interface ClientInfo {
+    /** Palbase SDK version (`X-Palbase-Sdk-Version`), or null. */
+    sdkVersion: string | null;
+    /** Calling app's own version (`X-Palbase-Client-Version`), or null. */
+    appVersion: string | null;
+    /** Platform identifier (e.g. "ios", "android", "web"), or null. */
+    platform: string | null;
+    /** OS version string, or null. */
+    osVersion: string | null;
+}
+/** Palbase module clients, as a structural bundle.
  *
- * Note: `db` here is NOT a module client — `ctx.db` is the project's own
- * Postgres (pgx, schema `env_<envId>`), declared separately on each context
- * as `DBClient`. The SDK's PostgREST query-builder is not exposed inside
- * endpoints.
- */
+ * NOT part of the endpoint surface anymore — endpoint handlers reach services
+ * via the PascalCase singletons (`Database`, `Documents`, …). This type is
+ * retained as an INTERNAL shape for the sibling contexts that still carry a
+ * `ctx` (middleware, jobs, workers, hooks, webhooks — out of Phase 1 scope).
+ * It is intentionally not re-exported from `index.ts`.
+ *
+ * Structurally typed against the runtime's `ServerClient`; the runtime injects
+ * the real client, so mismatched names would surface as `undefined is not a
+ * function` at call time — keep these in sync with `ServerClient`. */
 interface PalbaseModuleClients {
     auth: PalbaseAuthClient;
     storage: PalbaseStorageClient;
@@ -1198,40 +1303,97 @@ interface PalbaseModuleClients {
     links: PalbaseLinksClient;
     cms: PalbaseCmsClient;
 }
-/** Endpoint context — injected into every handler. Module clients hang
- * directly off ctx (`ctx.docs`, not `ctx.palbase.docs`); `ctx.db` is the
- * project's own Postgres.
+/** Declared-error definition.
+ *
+ * `code` is the stable snake_case identifier that lands on the wire envelope's
+ * `error` field. `status` is the HTTP status code returned. `data`, if set,
+ * is a Zod schema whose value rides on the envelope's `data` field — the CLI
+ * codegen lowers it to the typed enum's associated value on iOS.
+ *
+ * `description` is optional human-readable text; the OpenAPI generator uses it
+ * for the response description and the iOS codegen surfaces it in the
+ * generated method's doc-comment.
+ */
+interface ErrorDef<TData extends ZodSchema = ZodSchema> {
+    status: number;
+    code: string;
+    description?: string;
+    data?: TData;
+}
+/** Map of declared errors keyed by their TypeScript-side names.
+ *
+ * Keys are the friendly names the handler uses (`req.errors.todoLocked`);
+ * `code` on each value is the wire identifier. The TS name is what the iOS
+ * codegen lowers to (camelCase enum cases), and the wire `code` is what the
+ * envelope's `error` field carries.
+ */
+type ErrorMap = Record<string, ErrorDef>;
+/** Throwable proxy projected onto `req.errors` when `errors` is declared.
+ *
+ * Each entry is a constructor: declared errors with a `data` schema demand
+ * the payload as a required argument; declared errors without `data` take
+ * none. Throwing the result emits the standard envelope (with `data` when
+ * present).
+ *
+ *   throw req.errors.todoNotFound();
+ *   throw req.errors.todoLocked({ retryAfter: 30 });
+ */
+type ErrorThrowers<TErrors extends ErrorMap | undefined> = TErrors extends ErrorMap ? {
+    [K in keyof TErrors]: TErrors[K]["data"] extends ZodSchema ? (data: z.infer<NonNullable<TErrors[K]["data"]>>) => HttpError : () => HttpError;
+} : Record<string, never>;
+/** The request-scoped object passed to every endpoint handler.
+ *
+ * Replaces the old `ctx` god-object. `PBRequest` carries ONLY request-scoped
+ * data — the typed `input`, route/query params, headers, the authenticated
+ * `user`, calling-client metadata, trace ids, and the endpoint's declared
+ * error throwers. Services (`Database`, `Documents`, `Cache`, …) are NOT on
+ * the request: import them directly from `@palbase/backend` as singletons.
+ *
+ *   import { defineEndpoint, Database } from "@palbase/backend";
  *
- * When `TSchema` is a `SchemaDef`, `ctx.db` is `TypedDB<TSchema> & DBClient`:
- * both `ctx.db.tables.rooms.insert({...})` (typed) and
- * `ctx.db.insert("rooms", {...})` (legacy string API) compile.
- * When `TSchema` is `undefined` (no schema), `ctx.db` is plain `DBClient`.
+ *   export default defineEndpoint({
+ *     method: "POST",
+ *     handler: async (req) => Database.insert("todos", { title: req.input.title }),
+ *   });
+ *
+ * Generic parameters:
+ * - `TInput` — the validated `input` type (inferred from the `input` Zod
+ *   schema by `defineEndpoint`). The user-facing form is single-generic:
+ *   `PBRequest<TodoInput>`.
+ * - `TAuthed` — whether `user` is non-null. DEFAULTS to `true` (the common
+ *   case; the auth pipeline returns 401 before the handler when auth is
+ *   required, so a non-null `user` is runtime-honest). `defineEndpoint` passes
+ *   `IsAuthed<TAuth>` here, so `auth: false` → `User | null`.
+ * - `TErrors` — the declared `errors` map, typing `req.errors.<name>(...)`.
  */
-interface EndpointContext<TInput = unknown, TSchema extends SchemaDef | undefined = undefined, TAuthed extends boolean = false> extends PalbaseModuleClients {
+interface PBRequest<TInput = unknown, TAuthed extends boolean = true, TErrors extends ErrorMap | undefined = undefined> {
+    /** Validated request input (body for POST/PUT/PATCH; `{}` otherwise). */
     input: TInput;
+    /** Matched route params (e.g. `{ id }` for `/todos/[id]`). */
     params: Record<string, string>;
+    /** Parsed query-string params. */
     query: Record<string, string>;
+    /** Request headers (lowercase keys). */
     headers: Record<string, string>;
-    /** Authenticated user. Non-null (`User`) only when the endpoint's `auth`
-     * config forces authentication; otherwise `User | null`. The narrowing is
-     * driven by the `TAuthed` flag, which `defineEndpoint` computes from the
-     * `auth` literal via {@link IsAuthed}. */
+    /** Authenticated user. Non-null (`User`) by default; `User | null` only when
+     * the endpoint's `auth` config disables enforcement (driven by `TAuthed`,
+     * which `defineEndpoint` computes from the `auth` literal via {@link IsAuthed}). */
     user: TAuthed extends true ? User : User | null;
-    /** HTTP method of the incoming request (e.g. "GET", "POST"). */
-    method: string;
-    /** Matched endpoint path (e.g. "/todos/create"). */
-    endpointPath: string;
+    /** Calling-client metadata derived from request headers (all nullable). */
+    client: ClientInfo;
     /** Uploaded file, or null when the request has no file part. */
     file: FileContext | null;
-    db: TSchema extends SchemaDef ? TypedDB<TSchema> & DBClient : DBClient;
-    env: Record<string, string>;
-    log: Logger;
-    cache: CacheClient;
-    /** Queue client for dispatching background jobs. */
-    queue: QueueClient;
+    /** HTTP method of the incoming request (e.g. "GET", "POST"). */
+    method: string;
+    /** Per-request id (`req_<…>`), preserved for back-compat correlation. */
     requestId: string;
-    projectId: string;
-    environmentId: string;
+    /** W3C trace id (primary correlation key across modules). */
+    traceId: string;
+    /** W3C span id for this handler invocation. */
+    spanId: string;
+    /** Typed throwers for the endpoint's declared errors. Empty when the
+     * `errors` block is absent on `defineEndpoint`. */
+    errors: ErrorThrowers<TErrors>;
 }
 /** Middleware function signature — uses MiddlewareContext (no input, not yet validated). */
 type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
@@ -1243,11 +1405,11 @@ type Middleware = (ctx: MiddlewareContext, next: () => Promise<void>) => Promise
  */
 type AuthSpec = boolean | Partial<AuthConfig>;
 /** Compute, at the type level, whether an endpoint authenticates its caller —
- * i.e. whether `ctx.user` should be `User` (non-null) instead of `User | null`.
+ * i.e. whether `req.user` should be `User` (non-null) instead of `User | null`.
  *
  * This mirrors the Go pipeline's enforcement exactly (extract_meta.js + auth.go):
  * a request is authenticated ⟺ `auth === true` OR (`auth` is an object whose
- * `required` is not explicitly `false`). So `ctx.user` stays nullable ONLY when
+ * `required` is not explicitly `false`). So `req.user` stays nullable ONLY when
  * `auth` is absent (`undefined`), `auth === false`, or `auth: { required: false }`.
  *
  * | `TAuth`                         | `IsAuthed<TAuth>` |
@@ -1269,31 +1431,40 @@ type IsAuthed<TAuth> = TAuth extends {
 } ? false : TAuth extends true ? true : TAuth extends false ? false : TAuth extends object ? true : false;
 /** Configuration for defining an endpoint.
  *
- * `TSchema` — optional `SchemaDef` that, when provided, types `ctx.db` as
- * `TypedDB<TSchema> & DBClient` so both the typed `.tables` API and the
- * legacy string API compile inside the handler.
+ * `TSchema` — optional `SchemaDef` carried on the `schema` field. The runtime
+ * uses it to wire a typed `.tables.*` API; authors opt in per endpoint with
+ * `typedDatabase(schema)` (see runtime.ts).
  *
  * `TAuth` — captures the literal type of the `auth` field (via the `const`
- * type parameter on `defineEndpoint`) so the handler's `ctx.user` can be
+ * type parameter on `defineEndpoint`) so the handler's `req.user` can be
  * narrowed to non-null `User` when auth is required. See {@link IsAuthed}.
+ *
+ * `TErrors` — captures the literal `errors` map (via the `const` type
+ * parameter on `defineEndpoint`) so `req.errors.<name>(...)` is typed per
+ * declared entry. The OpenAPI generator emits each one as a discriminated
+ * response under `responses[<status>]`, and the CLI codegen lowers them to
+ * a typed `<Endpoint>.Error` enum on iOS.
  */
-interface EndpointConfig<TInputSchema extends ZodSchema = ZodSchema, TOutputSchema extends ZodSchema = ZodSchema, TSchema extends SchemaDef | undefined = undefined, TAuth extends AuthSpec | undefined = undefined> {
+interface EndpointConfig<TInputSchema extends ZodSchema = ZodSchema, TOutputSchema extends ZodSchema = ZodSchema, TSchema extends SchemaDef | undefined = undefined, TAuth extends AuthSpec | undefined = undefined, TErrors extends ErrorMap | undefined = undefined> {
     method: HttpMethod;
     auth?: TAuth;
     rateLimit?: RateLimitConfig;
     input?: TInputSchema;
     output?: TOutputSchema;
     schema?: TSchema;
+    errors?: TErrors;
     middleware?: Middleware[];
-    handler: (ctx: EndpointContext<z.infer<TInputSchema>, TSchema, IsAuthed<TAuth>>) => Promise<z.infer<TOutputSchema>>;
+    handler: (req: PBRequest<z.infer<TInputSchema>, IsAuthed<TAuth>, TErrors>) => Promise<z.infer<TOutputSchema>>;
 }
-/** Define a type-safe endpoint. Input schema infers the ctx.input type.
- * Pass a `schema` (from `defineSchema`) to get a typed `ctx.db.tables.*` API.
+/** Define a type-safe endpoint. The input schema infers the `req.input` type.
+ * Pass a `schema` (from `defineSchema`) and wrap `Database` with
+ * `typedDatabase(schema)` in the handler for a typed `.tables.*` API.
  *
- * The `const TAuth` type parameter captures the `auth` field as a literal
- * (`true` / `{ required: true }` / `{ role: 'admin' }` …) so the handler's
- * `ctx.user` is narrowed to `User` (non-null) whenever auth is enforced.
+ * The `const TAuth` and `const TErrors` type parameters capture the `auth`
+ * and `errors` fields as literals, so `req.user` narrows to non-null `User`
+ * when auth is enforced and `req.errors.<name>(...)` is typed per declared
+ * entry.
  */
-declare function defineEndpoint<TInputSchema extends ZodSchema, TOutputSchema extends ZodSchema, TSchema extends SchemaDef | undefined = undefined, const TAuth extends AuthSpec | undefined = undefined>(config: EndpointConfig<TInputSchema, TOutputSchema, TSchema, TAuth>): EndpointConfig<TInputSchema, TOutputSchema, TSchema, TAuth>;
+declare function defineEndpoint<TInputSchema extends ZodSchema, TOutputSchema extends ZodSchema, TSchema extends SchemaDef | undefined = undefined, const TAuth extends AuthSpec | undefined = undefined, const TErrors extends ErrorMap | undefined = undefined>(config: EndpointConfig<TInputSchema, TOutputSchema, TSchema, TAuth, TErrors>): EndpointConfig<TInputSchema, TOutputSchema, TSchema, TAuth, TErrors>;
 
-export { type PalbaseIdentifyTraits as $, type AuthConfig as A, type PalbaseDocumentRef as B, type CacheClient as C, type DBClient as D, type EndpointContext as E, type FileContext as F, type PalbaseDocumentSnapshot as G, type HttpMethod as H, type InsertShape as I, type PalbaseEmailClient as J, type PalbaseEmailSendParams as K, type Logger as L, type Middleware as M, type PalbaseEmailSendResponse as N, type PalbaseEventNamesResult as O, type PalbaseModuleClients as P, type QueueClient as Q, type PalbaseEventsQueryInput as R, type PalbaseEventsResult as S, type PalbaseFileObject as T, type PalbaseFlag as U, type PalbaseFlagContext as V, type PalbaseFlagVariant as W, type PalbaseFlagsClient as X, type PalbaseFunctionsClient as Y, type PalbaseFunnelQueryInput as Z, type PalbaseFunnelResult as _, type EndpointConfig as a, type PalbaseInboxClient as a0, type PalbaseInboxListOptions as a1, type PalbaseInboxListResult as a2, type PalbaseInboxMessage as a3, type PalbaseInboxSendParams as a4, type PalbaseInboxSendResponse as a5, type PalbaseInitialLink as a6, type PalbaseInvokeOptions as a7, type PalbaseLink as a8, type PalbaseLinkAnalytics as a9, type PalbaseSmsClient as aA, type PalbaseSmsSendParams as aB, type PalbaseSmsSendResponse as aC, type PalbaseStorageClient as aD, type PalbaseTransformOptions as aE, type PalbaseUpdateLinkParams as aF, type PalbaseUploadOptions as aG, type PalbaseUser as aH, type PalbaseUserDetailResult as aI, type PalbaseUsersQueryInput as aJ, type PalbaseUsersResult as aK, type PalbaseVerifyRequestSignatureParams as aL, type PalbaseWhereOperator as aM, type RateLimitConfig as aN, type RowShape as aO, type TypedDB as aP, type TypedTable as aQ, type User as aR, defineEndpoint as aS, defineMiddleware as aT, makeTypedDB as aU, type PalbaseLinkDetails as aa, type PalbaseLinksClient as ab, type PalbaseListLinksOptions as ac, type PalbaseListLinksResult as ad, type PalbaseListOptions as ae, type PalbaseMatchParams as af, type PalbaseMultiChannelResponse as ag, type PalbaseNotificationsClient as ah, type PalbaseOverviewResult as ai, type PalbasePreferences as aj, type PalbasePreferencesClient as ak, type PalbasePublicUrlResponse as al, type PalbasePushClient as am, type PalbasePushSendParams as an, type PalbasePushSendResponse as ao, type PalbaseQrCodeOptions as ap, type PalbaseQuerySnapshot as aq, type PalbaseRealtimeChannel as ar, type PalbaseRealtimeClient as as, type PalbaseRealtimeMessage as at, type PalbaseRegisterDeviceParams as au, type PalbaseResult as av, type PalbaseRetentionQueryInput as aw, type PalbaseRetentionResult as ax, type PalbaseSession as ay, type PalbaseSignedUrlResponse as az, type MiddlewareContext as b, type MiddlewareHandler as c, type PalbaseAnalyticsClient as d, type PalbaseAnalyticsManagementNamespace as e, type PalbaseAnalyticsProperties as f, type PalbaseAnalyticsQueryNamespace as g, type PalbaseAttestAndroidParams as h, type PalbaseAttestAndroidResult as i, type PalbaseAttestiOSParams as j, type PalbaseAttestiOSResult as k, type PalbaseAuthClient as l, type PalbaseBindDeviceParams as m, type PalbaseBucketClient as n, type PalbaseCmsClient as o, type PalbaseCmsFindOneOptions as p, type PalbaseCmsFindOptions as q, type PalbaseCohortQueryInput as r, type PalbaseCohortResult as s, type PalbaseCollectionRef as t, type PalbaseCountQueryInput as u, type PalbaseCountResult as v, type PalbaseCreateLinkParams as w, type PalbaseDeviceInfo as x, type PalbaseDeviceTokenView as y, type PalbaseDocsClient as z };
+export { type PalbaseFileObject as $, type AuthConfig as A, type PalbaseCohortQueryInput as B, type CacheClient as C, type DBClient as D, type ErrorThrowers as E, type FileContext as F, type PalbaseCohortResult as G, HttpError as H, type PalbaseCollectionRef as I, type PalbaseCountQueryInput as J, type PalbaseCountResult as K, type Logger as L, type Middleware as M, type PalbaseCreateLinkParams as N, type PalbaseDeviceInfo as O, type PalbaseDocsClient as P, type QueueClient as Q, type PalbaseDeviceTokenView as R, type PalbaseDocumentRef as S, type PalbaseDocumentSnapshot as T, type User as U, type PalbaseEmailClient as V, type PalbaseEmailSendParams as W, type PalbaseEmailSendResponse as X, type PalbaseEventNamesResult as Y, type PalbaseEventsQueryInput as Z, type PalbaseEventsResult as _, type PalbaseFlagsClient as a, type PalbaseFlag as a0, type PalbaseFlagContext as a1, type PalbaseFlagVariant as a2, type PalbaseFunctionsClient as a3, type PalbaseFunnelQueryInput as a4, type PalbaseFunnelResult as a5, type PalbaseIdentifyTraits as a6, type PalbaseInboxClient as a7, type PalbaseInboxListOptions as a8, type PalbaseInboxListResult as a9, type PalbaseRegisterDeviceParams as aA, type PalbaseResult as aB, type PalbaseRetentionQueryInput as aC, type PalbaseRetentionResult as aD, type PalbaseSession as aE, type PalbaseSignedUrlResponse as aF, type PalbaseSmsClient as aG, type PalbaseSmsSendParams as aH, type PalbaseSmsSendResponse as aI, type PalbaseTransformOptions as aJ, type PalbaseUpdateLinkParams as aK, type PalbaseUploadOptions as aL, type PalbaseUser as aM, type PalbaseUserDetailResult as aN, type PalbaseUsersQueryInput as aO, type PalbaseUsersResult as aP, type PalbaseVerifyRequestSignatureParams as aQ, type PalbaseWhereOperator as aR, type RateLimitConfig as aS, type TxClient as aT, defineEndpoint as aU, defineMiddleware as aV, type PalbaseInboxMessage as aa, type PalbaseInboxSendParams as ab, type PalbaseInboxSendResponse as ac, type PalbaseInitialLink as ad, type PalbaseInvokeOptions as ae, type PalbaseLink as af, type PalbaseLinkAnalytics as ag, type PalbaseLinkDetails as ah, type PalbaseLinksClient as ai, type PalbaseListLinksOptions as aj, type PalbaseListLinksResult as ak, type PalbaseListOptions as al, type PalbaseMatchParams as am, type PalbaseMultiChannelResponse as an, type PalbaseOverviewResult as ao, type PalbasePreferences as ap, type PalbasePreferencesClient as aq, type PalbasePublicUrlResponse as ar, type PalbasePushClient as as, type PalbasePushSendParams as at, type PalbasePushSendResponse as au, type PalbaseQrCodeOptions as av, type PalbaseQuerySnapshot as aw, type PalbaseRealtimeChannel as ax, type PalbaseRealtimeClient as ay, type PalbaseRealtimeMessage as az, type PalbaseNotificationsClient as b, type PalbaseStorageClient as c, type PalbaseModuleClients as d, type ClientInfo as e, type EndpointConfig as f, type ErrorDef as g, type ErrorMap as h, type HttpMethod as i, type MiddlewareContext as j, type MiddlewareHandler as k, type PBRequest as l, type PalbaseAnalyticsClient as m, type PalbaseAnalyticsManagementNamespace as n, type PalbaseAnalyticsProperties as o, type PalbaseAnalyticsQueryNamespace as p, type PalbaseAttestAndroidParams as q, type PalbaseAttestAndroidResult as r, type PalbaseAttestiOSParams as s, type PalbaseAttestiOSResult as t, type PalbaseAuthClient as u, type PalbaseBindDeviceParams as v, type PalbaseBucketClient as w, type PalbaseCmsClient as x, type PalbaseCmsFindOneOptions as y, type PalbaseCmsFindOptions as z };