@palbase/backend 2.0.2 → 4.0.0

package/dist/{endpoint-BlcY2xNA.d.cts → endpoint-2d_DpASt.d.ts}

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