@palbase/backend 0.9.0 → 1.0.0

package/dist/index.d.cts

@@ -1,27 +1,200 @@
-import { E as EndpointContext, P as PalbaseModuleClients, D as DBClient, L as Logger, C as CacheClient, Q as QueueClient } from './endpoint-_1Qq8AFz.cjs';
-export { A as AuthConfig, a as EndpointConfig, F as FileContext, H as HttpMethod, I as InsertShape, M as Middleware, b as MiddlewareContext, c as MiddlewareHandler, d as PalbaseAnalyticsClient, e as PalbaseAnalyticsManagementNamespace, f as PalbaseAnalyticsProperties, g as PalbaseAnalyticsQueryNamespace, h as PalbaseAttestAndroidParams, i as PalbaseAttestAndroidResult, j as PalbaseAttestiOSParams, k as PalbaseAttestiOSResult, l as PalbaseAuthClient, m as PalbaseBindDeviceParams, n as PalbaseBucketClient, o as PalbaseCmsClient, p as PalbaseCmsFindOneOptions, q as PalbaseCmsFindOptions, r as PalbaseCohortQueryInput, s as PalbaseCohortResult, t as PalbaseCollectionRef, u as PalbaseCountQueryInput, v as PalbaseCountResult, w as PalbaseCreateLinkParams, x as PalbaseDeviceInfo, y as PalbaseDeviceTokenView, z as PalbaseDocsClient, B as PalbaseDocumentRef, G as PalbaseDocumentSnapshot, J as PalbaseEmailClient, K as PalbaseEmailSendParams, N as PalbaseEmailSendResponse, O as PalbaseEventNamesResult, R as PalbaseEventsQueryInput, S as PalbaseEventsResult, T as PalbaseFileObject, U as PalbaseFlag, V as PalbaseFlagContext, W as PalbaseFlagVariant, X as PalbaseFlagsClient, Y as PalbaseFunctionsClient, Z as PalbaseFunnelQueryInput, _ as PalbaseFunnelResult, $ as PalbaseIdentifyTraits, a0 as PalbaseInboxClient, a1 as PalbaseInboxListOptions, a2 as PalbaseInboxListResult, a3 as PalbaseInboxMessage, a4 as PalbaseInboxSendParams, a5 as PalbaseInboxSendResponse, a6 as PalbaseInitialLink, a7 as PalbaseInvokeOptions, a8 as PalbaseLink, a9 as PalbaseLinkAnalytics, aa as PalbaseLinkDetails, ab as PalbaseLinksClient, ac as PalbaseListLinksOptions, ad as PalbaseListLinksResult, ae as PalbaseListOptions, af as PalbaseMatchParams, ag as PalbaseMultiChannelResponse, ah as PalbaseNotificationsClient, ai as PalbaseOverviewResult, aj as PalbasePreferences, ak as PalbasePreferencesClient, al as PalbasePublicUrlResponse, am as PalbasePushClient, an as PalbasePushSendParams, ao as PalbasePushSendResponse, ap as PalbaseQrCodeOptions, aq as PalbaseQuerySnapshot, ar as PalbaseRealtimeChannel, as as PalbaseRealtimeClient, at as PalbaseRealtimeMessage, au as PalbaseRegisterDeviceParams, av as PalbaseResult, aw as PalbaseRetentionQueryInput, ax as PalbaseRetentionResult, ay as PalbaseSession, az as PalbaseSignedUrlResponse, aA as PalbaseSmsClient, aB as PalbaseSmsSendParams, aC as PalbaseSmsSendResponse, aD as PalbaseStorageClient, aE as PalbaseTransformOptions, aF as PalbaseUpdateLinkParams, aG as PalbaseUploadOptions, aH as PalbaseUser, aI as PalbaseUserDetailResult, aJ as PalbaseUsersQueryInput, aK as PalbaseUsersResult, aL as PalbaseVerifyRequestSignatureParams, aM as PalbaseWhereOperator, aN as RateLimitConfig, aO as RowShape, aP as TypedDB, aQ as TypedTable, aR as User, aS as defineEndpoint, aT as defineMiddleware, aU as makeTypedDB } from './endpoint-_1Qq8AFz.cjs';
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnType, O as OnDeleteAction, S as SchemaDef, T as TableDef, c as boolean, d as defineSchema, e as enumType, i as integer, j as jsonb, t as table, f as text, g as timestamp, u as uuid } from './schema-zk-a0Dv7.cjs';
+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-yn2xcrWu.cjs';
+export { A as AuthConfig, e as ClientInfo, f as EndpointConfig, g as ErrorDef, h as ErrorMap, F as FileContext, H as HttpError, i as HttpMethod, M as Middleware, j as MiddlewareContext, k as MiddlewareHandler, l as PBRequest, m as PalbaseAnalyticsClient, n as PalbaseAnalyticsManagementNamespace, o as PalbaseAnalyticsProperties, p as PalbaseAnalyticsQueryNamespace, q as PalbaseAttestAndroidParams, r as PalbaseAttestAndroidResult, s as PalbaseAttestiOSParams, t as PalbaseAttestiOSResult, u as PalbaseAuthClient, v as PalbaseBindDeviceParams, w as PalbaseBucketClient, x as PalbaseCmsClient, y as PalbaseCmsFindOneOptions, z as PalbaseCmsFindOptions, B as PalbaseCohortQueryInput, G as PalbaseCohortResult, I as PalbaseCollectionRef, J as PalbaseCountQueryInput, K as PalbaseCountResult, N as PalbaseCreateLinkParams, O as PalbaseDeviceInfo, R as PalbaseDeviceTokenView, S as PalbaseDocumentRef, T as PalbaseDocumentSnapshot, V as PalbaseEmailClient, W as PalbaseEmailSendParams, X as PalbaseEmailSendResponse, Y as PalbaseEventNamesResult, Z as PalbaseEventsQueryInput, _ as PalbaseEventsResult, $ as PalbaseFileObject, a0 as PalbaseFlag, a1 as PalbaseFlagContext, a2 as PalbaseFlagVariant, a3 as PalbaseFunctionsClient, a4 as PalbaseFunnelQueryInput, a5 as PalbaseFunnelResult, a6 as PalbaseIdentifyTraits, a7 as PalbaseInboxClient, a8 as PalbaseInboxListOptions, a9 as PalbaseInboxListResult, aa as PalbaseInboxMessage, ab as PalbaseInboxSendParams, ac as PalbaseInboxSendResponse, ad as PalbaseInitialLink, ae as PalbaseInvokeOptions, af as PalbaseLink, ag as PalbaseLinkAnalytics, ah as PalbaseLinkDetails, ai as PalbaseLinksClient, aj as PalbaseListLinksOptions, ak as PalbaseListLinksResult, al as PalbaseListOptions, am as PalbaseMatchParams, an as PalbaseMultiChannelResponse, ao as PalbaseOverviewResult, ap as PalbasePreferences, aq as PalbasePreferencesClient, ar as PalbasePublicUrlResponse, as as PalbasePushClient, at as PalbasePushSendParams, au as PalbasePushSendResponse, av as PalbaseQrCodeOptions, aw as PalbaseQuerySnapshot, ax as PalbaseRealtimeChannel, ay as PalbaseRealtimeClient, az as PalbaseRealtimeMessage, aA as PalbaseRegisterDeviceParams, aB as PalbaseResult, aC as PalbaseRetentionQueryInput, aD as PalbaseRetentionResult, aE as PalbaseSession, aF as PalbaseSignedUrlResponse, aG as PalbaseSmsClient, aH as PalbaseSmsSendParams, aI as PalbaseSmsSendResponse, aJ as PalbaseTransformOptions, aK as PalbaseUpdateLinkParams, aL as PalbaseUploadOptions, aM as PalbaseUser, aN as PalbaseUserDetailResult, aO as PalbaseUsersQueryInput, aP as PalbaseUsersResult, aQ as PalbaseVerifyRequestSignatureParams, aR as PalbaseWhereOperator, aS as RateLimitConfig, aT as TxClient, aU as defineEndpoint, aV as defineMiddleware } from './endpoint-yn2xcrWu.cjs';
+import { T as TableDef, C as ColIsOptionalOnInsert, a as ColValue, S as SchemaDef } from './schema-BqfEhIC0.cjs';
+export { b as ColumnBuilder, c as ColumnDef, d as ColumnType, O as OnDeleteAction, e as boolean, f as defineSchema, g as enumType, i as integer, j as jsonb, t as table, h as text, k as timestamp, u as uuid } from './schema-BqfEhIC0.cjs';
 export { z } from 'zod';
 
-/** HTTP error with structured error response format. */
-declare class HttpError extends Error {
-    readonly status: number;
-    readonly error: string;
-    readonly errorDescription: string;
-    constructor(status: number, error: string, errorDescription: string);
-    /**
-     * 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.
-     */
-    toJSON(requestId?: string): {
-        error: string;
-        error_description: string;
-        status: number;
-        request_id?: string;
+/**
+ * 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:
+ *
+ *   import { Database, Documents, Cache } from "@palbase/backend";
+ *
+ *   export default defineEndpoint({
+ *     method: "POST",
+ *     handler: async (req) => {
+ *       const row = await Database.insert("todos", { title: req.input.title });
+ *       return row;
+ *     },
+ *   });
+ *
+ * The singletons are thin Proxies. Every property access forwards to the live
+ * client held in a per-process mutable slot, which the runtime sets with
+ * {@link __setRuntime} BEFORE invoking the handler and (today) leaves in place
+ * for the lifetime of that fresh Node subprocess. Because each `br-<ref>` pod
+ * is single-tenant and every request runs in a fresh Node subprocess
+ * (node_executor.go), there is no cross-tenant leakage risk.
+ *
+ * The seam that makes `import { Database } from "@palbase/backend"` resolve to
+ * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL
+ * when the tenant bundle is built, and the package is installed globally in the
+ * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's
+ * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared
+ * module instance — calling `__setRuntime` on that instance is visible to the
+ * singletons the bundle imported.
+ */
+
+/** The set of live clients the runtime injects per request scope.
+ *
+ * EXCLUDED on purpose: Realtime, Functions, CMS, Links, Analytics, Auth. They
+ * are not exposed as backend handler singletons (auth lives on the client SDK;
+ * the rest are out of scope for backend endpoints). */
+interface RuntimeServices {
+    Database: DBClient;
+    Documents: PalbaseDocsClient;
+    Storage: PalbaseStorageClient;
+    Cache: CacheClient;
+    Queue: QueueClient;
+    Log: Logger;
+    Notifications: PalbaseNotificationsClient;
+    Flags: PalbaseFlagsClient;
+}
+/** Install the live clients for the current request scope.
+ *
+ * Called by the Palbase runtime (worker.js / dev-server.js) immediately before
+ * invoking a handler. NOT part of the public author-facing API — exported with
+ * a `__` prefix so the runtime can reach it across the shared module instance.
+ */
+declare function __setRuntime(services: RuntimeServices): void;
+/** Read the live clients, throwing if accessed outside a request scope.
+ *
+ * NOT part of the public author-facing API — exported with a `__` prefix for
+ * 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;
+/** Firestore-like document client (PalDocs). */
+declare const Documents: PalbaseDocsClient;
+/** Object storage client (buckets, signed URLs). */
+declare const Storage: PalbaseStorageClient;
+/** JSON-typed cache (get/set/incr/getOrSet). */
+declare const Cache: CacheClient;
+/** Background job queue. */
+declare const Queue: QueueClient;
+/** Structured logger. */
+declare const Log: Logger;
+/** Push / email / SMS / in-app notifications. */
+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.
+ *
+ *   const Db = typedDatabase(schema);
+ *   const todo = await Db.tables.todos.insert({ title: "x" });
+ *
+ * This is per-endpoint (not global module augmentation), so one endpoint's
+ * tables never leak into another's `Database` type.
+ */
+declare function typedDatabase<TSchema extends SchemaDef>(schema: TSchema): TypedDB<TSchema> & DBClient;
+
+/** Context injected into worker handlers — the non-request-scoped service
+ * surface (db/log/cache/queue + module clients), plus correlation ids. Workers
+ * are not part of the Phase 1 `ctx → PBRequest` redesign, so they keep their
+ * own `ctx`; the job payload arrives as the handler's second argument. */
+interface WorkerContext extends PalbaseModuleClients {
+    user: User | null;
+    db: DBClient;
+    env: Record<string, string>;
+    log: Logger;
+    cache: CacheClient;
+    queue: QueueClient;
+    errors: ErrorThrowers<undefined>;
+    requestId: string;
+    projectId: string;
+    environmentId: string;
+}
 /** Backoff strategy for worker retries. */
 type BackoffStrategy = "exponential" | "linear" | "fixed";
 /** Configuration for a background worker. */
@@ -35,7 +208,7 @@ interface WorkerConfig<TPayload = unknown> {
     /** Backoff strategy between retries. Defaults to "exponential". */
     backoff?: BackoffStrategy;
     /** Handler function that processes the job payload. */
-    handler: (ctx: Omit<EndpointContext<TPayload>, "input" | "params" | "query" | "headers" | "file" | "method" | "endpointPath">, payload: TPayload) => Promise<void>;
+    handler: (ctx: WorkerContext, payload: TPayload) => Promise<void>;
 }
 /** Resolved worker configuration with defaults applied. */
 interface ResolvedWorkerConfig<TPayload = unknown> {
@@ -43,7 +216,7 @@ interface ResolvedWorkerConfig<TPayload = unknown> {
     retry: number;
     timeout: number;
     backoff: BackoffStrategy;
-    handler: (ctx: Omit<EndpointContext<TPayload>, "input" | "params" | "query" | "headers" | "file" | "method" | "endpointPath">, payload: TPayload) => Promise<void>;
+    handler: (ctx: WorkerContext, payload: TPayload) => Promise<void>;
 }
 /**
  * Define a background worker that processes jobs from the queue.
@@ -370,4 +543,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-export { type BackoffStrategy, CacheClient, type CustomWebhookConfig, DBClient, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, EndpointContext, type EnvSecretRef, type FileDeletedEvent, type FileUploadedEvent, type HookContext, type HookHandler, HttpError, type JobConfig, type JobContext, Logger, PalbaseModuleClients, type PasswordResetEvent, type ProviderEventMap, type ProviderWebhookConfig, QueueClient, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, type SignInEvent, type SignOutEvent, type UserCreatedEvent, type WebhookContext, type WebhookEventHandler, type WebhookProvider, type WebhookRequest, type WorkerConfig, auth, defineJob, defineWebhook, defineWorker, documents, storage };
+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, __setRuntime, auth, defineJob, defineWebhook, defineWorker, documents, makeTypedDB, storage, typedDatabase };

package/dist/index.d.ts

@@ -1,27 +1,200 @@
-import { E as EndpointContext, P as PalbaseModuleClients, D as DBClient, L as Logger, C as CacheClient, Q as QueueClient } from './endpoint-DysSe3SI.js';
-export { A as AuthConfig, a as EndpointConfig, F as FileContext, H as HttpMethod, I as InsertShape, M as Middleware, b as MiddlewareContext, c as MiddlewareHandler, d as PalbaseAnalyticsClient, e as PalbaseAnalyticsManagementNamespace, f as PalbaseAnalyticsProperties, g as PalbaseAnalyticsQueryNamespace, h as PalbaseAttestAndroidParams, i as PalbaseAttestAndroidResult, j as PalbaseAttestiOSParams, k as PalbaseAttestiOSResult, l as PalbaseAuthClient, m as PalbaseBindDeviceParams, n as PalbaseBucketClient, o as PalbaseCmsClient, p as PalbaseCmsFindOneOptions, q as PalbaseCmsFindOptions, r as PalbaseCohortQueryInput, s as PalbaseCohortResult, t as PalbaseCollectionRef, u as PalbaseCountQueryInput, v as PalbaseCountResult, w as PalbaseCreateLinkParams, x as PalbaseDeviceInfo, y as PalbaseDeviceTokenView, z as PalbaseDocsClient, B as PalbaseDocumentRef, G as PalbaseDocumentSnapshot, J as PalbaseEmailClient, K as PalbaseEmailSendParams, N as PalbaseEmailSendResponse, O as PalbaseEventNamesResult, R as PalbaseEventsQueryInput, S as PalbaseEventsResult, T as PalbaseFileObject, U as PalbaseFlag, V as PalbaseFlagContext, W as PalbaseFlagVariant, X as PalbaseFlagsClient, Y as PalbaseFunctionsClient, Z as PalbaseFunnelQueryInput, _ as PalbaseFunnelResult, $ as PalbaseIdentifyTraits, a0 as PalbaseInboxClient, a1 as PalbaseInboxListOptions, a2 as PalbaseInboxListResult, a3 as PalbaseInboxMessage, a4 as PalbaseInboxSendParams, a5 as PalbaseInboxSendResponse, a6 as PalbaseInitialLink, a7 as PalbaseInvokeOptions, a8 as PalbaseLink, a9 as PalbaseLinkAnalytics, aa as PalbaseLinkDetails, ab as PalbaseLinksClient, ac as PalbaseListLinksOptions, ad as PalbaseListLinksResult, ae as PalbaseListOptions, af as PalbaseMatchParams, ag as PalbaseMultiChannelResponse, ah as PalbaseNotificationsClient, ai as PalbaseOverviewResult, aj as PalbasePreferences, ak as PalbasePreferencesClient, al as PalbasePublicUrlResponse, am as PalbasePushClient, an as PalbasePushSendParams, ao as PalbasePushSendResponse, ap as PalbaseQrCodeOptions, aq as PalbaseQuerySnapshot, ar as PalbaseRealtimeChannel, as as PalbaseRealtimeClient, at as PalbaseRealtimeMessage, au as PalbaseRegisterDeviceParams, av as PalbaseResult, aw as PalbaseRetentionQueryInput, ax as PalbaseRetentionResult, ay as PalbaseSession, az as PalbaseSignedUrlResponse, aA as PalbaseSmsClient, aB as PalbaseSmsSendParams, aC as PalbaseSmsSendResponse, aD as PalbaseStorageClient, aE as PalbaseTransformOptions, aF as PalbaseUpdateLinkParams, aG as PalbaseUploadOptions, aH as PalbaseUser, aI as PalbaseUserDetailResult, aJ as PalbaseUsersQueryInput, aK as PalbaseUsersResult, aL as PalbaseVerifyRequestSignatureParams, aM as PalbaseWhereOperator, aN as RateLimitConfig, aO as RowShape, aP as TypedDB, aQ as TypedTable, aR as User, aS as defineEndpoint, aT as defineMiddleware, aU as makeTypedDB } from './endpoint-DysSe3SI.js';
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnType, O as OnDeleteAction, S as SchemaDef, T as TableDef, c as boolean, d as defineSchema, e as enumType, i as integer, j as jsonb, t as table, f as text, g as timestamp, u as uuid } from './schema-zk-a0Dv7.js';
+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-knNIeovM.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-knNIeovM.js';
+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';
 export { z } from 'zod';
 
-/** HTTP error with structured error response format. */
-declare class HttpError extends Error {
-    readonly status: number;
-    readonly error: string;
-    readonly errorDescription: string;
-    constructor(status: number, error: string, errorDescription: string);
-    /**
-     * 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.
-     */
-    toJSON(requestId?: string): {
-        error: string;
-        error_description: string;
-        status: number;
-        request_id?: string;
+/**
+ * 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:
+ *
+ *   import { Database, Documents, Cache } from "@palbase/backend";
+ *
+ *   export default defineEndpoint({
+ *     method: "POST",
+ *     handler: async (req) => {
+ *       const row = await Database.insert("todos", { title: req.input.title });
+ *       return row;
+ *     },
+ *   });
+ *
+ * The singletons are thin Proxies. Every property access forwards to the live
+ * client held in a per-process mutable slot, which the runtime sets with
+ * {@link __setRuntime} BEFORE invoking the handler and (today) leaves in place
+ * for the lifetime of that fresh Node subprocess. Because each `br-<ref>` pod
+ * is single-tenant and every request runs in a fresh Node subprocess
+ * (node_executor.go), there is no cross-tenant leakage risk.
+ *
+ * The seam that makes `import { Database } from "@palbase/backend"` resolve to
+ * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL
+ * when the tenant bundle is built, and the package is installed globally in the
+ * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's
+ * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared
+ * module instance — calling `__setRuntime` on that instance is visible to the
+ * singletons the bundle imported.
+ */
+
+/** The set of live clients the runtime injects per request scope.
+ *
+ * EXCLUDED on purpose: Realtime, Functions, CMS, Links, Analytics, Auth. They
+ * are not exposed as backend handler singletons (auth lives on the client SDK;
+ * the rest are out of scope for backend endpoints). */
+interface RuntimeServices {
+    Database: DBClient;
+    Documents: PalbaseDocsClient;
+    Storage: PalbaseStorageClient;
+    Cache: CacheClient;
+    Queue: QueueClient;
+    Log: Logger;
+    Notifications: PalbaseNotificationsClient;
+    Flags: PalbaseFlagsClient;
+}
+/** Install the live clients for the current request scope.
+ *
+ * Called by the Palbase runtime (worker.js / dev-server.js) immediately before
+ * invoking a handler. NOT part of the public author-facing API — exported with
+ * a `__` prefix so the runtime can reach it across the shared module instance.
+ */
+declare function __setRuntime(services: RuntimeServices): void;
+/** Read the live clients, throwing if accessed outside a request scope.
+ *
+ * NOT part of the public author-facing API — exported with a `__` prefix for
+ * 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;
+/** Firestore-like document client (PalDocs). */
+declare const Documents: PalbaseDocsClient;
+/** Object storage client (buckets, signed URLs). */
+declare const Storage: PalbaseStorageClient;
+/** JSON-typed cache (get/set/incr/getOrSet). */
+declare const Cache: CacheClient;
+/** Background job queue. */
+declare const Queue: QueueClient;
+/** Structured logger. */
+declare const Log: Logger;
+/** Push / email / SMS / in-app notifications. */
+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.
+ *
+ *   const Db = typedDatabase(schema);
+ *   const todo = await Db.tables.todos.insert({ title: "x" });
+ *
+ * This is per-endpoint (not global module augmentation), so one endpoint's
+ * tables never leak into another's `Database` type.
+ */
+declare function typedDatabase<TSchema extends SchemaDef>(schema: TSchema): TypedDB<TSchema> & DBClient;
+
+/** Context injected into worker handlers — the non-request-scoped service
+ * surface (db/log/cache/queue + module clients), plus correlation ids. Workers
+ * are not part of the Phase 1 `ctx → PBRequest` redesign, so they keep their
+ * own `ctx`; the job payload arrives as the handler's second argument. */
+interface WorkerContext extends PalbaseModuleClients {
+    user: User | null;
+    db: DBClient;
+    env: Record<string, string>;
+    log: Logger;
+    cache: CacheClient;
+    queue: QueueClient;
+    errors: ErrorThrowers<undefined>;
+    requestId: string;
+    projectId: string;
+    environmentId: string;
+}
 /** Backoff strategy for worker retries. */
 type BackoffStrategy = "exponential" | "linear" | "fixed";
 /** Configuration for a background worker. */
@@ -35,7 +208,7 @@ interface WorkerConfig<TPayload = unknown> {
     /** Backoff strategy between retries. Defaults to "exponential". */
     backoff?: BackoffStrategy;
     /** Handler function that processes the job payload. */
-    handler: (ctx: Omit<EndpointContext<TPayload>, "input" | "params" | "query" | "headers" | "file" | "method" | "endpointPath">, payload: TPayload) => Promise<void>;
+    handler: (ctx: WorkerContext, payload: TPayload) => Promise<void>;
 }
 /** Resolved worker configuration with defaults applied. */
 interface ResolvedWorkerConfig<TPayload = unknown> {
@@ -43,7 +216,7 @@ interface ResolvedWorkerConfig<TPayload = unknown> {
     retry: number;
     timeout: number;
     backoff: BackoffStrategy;
-    handler: (ctx: Omit<EndpointContext<TPayload>, "input" | "params" | "query" | "headers" | "file" | "method" | "endpointPath">, payload: TPayload) => Promise<void>;
+    handler: (ctx: WorkerContext, payload: TPayload) => Promise<void>;
 }
 /**
  * Define a background worker that processes jobs from the queue.
@@ -370,4 +543,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-export { type BackoffStrategy, CacheClient, type CustomWebhookConfig, DBClient, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, EndpointContext, type EnvSecretRef, type FileDeletedEvent, type FileUploadedEvent, type HookContext, type HookHandler, HttpError, type JobConfig, type JobContext, Logger, PalbaseModuleClients, type PasswordResetEvent, type ProviderEventMap, type ProviderWebhookConfig, QueueClient, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, type SignInEvent, type SignOutEvent, type UserCreatedEvent, type WebhookContext, type WebhookEventHandler, type WebhookProvider, type WebhookRequest, type WorkerConfig, auth, defineJob, defineWebhook, defineWorker, documents, storage };
+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, __setRuntime, auth, defineJob, defineWebhook, defineWorker, documents, makeTypedDB, storage, typedDatabase };

package/dist/index.js

@@ -1,3 +1,17 @@
+import {
+  Cache,
+  Database,
+  Documents,
+  Flags,
+  Log,
+  Notifications,
+  Queue,
+  Storage,
+  __getRuntime,
+  __setRuntime,
+  makeTypedDB,
+  typedDatabase
+} from "./chunk-7N5ICXCB.js";
 import {
   boolean,
   defineSchema,
@@ -15,27 +29,6 @@ function defineEndpoint(config) {
   return config;
 }
 
-// src/db/typed-db.ts
-function makeTypedTable(name, raw) {
-  return {
-    insert: (data) => raw.insert(name, data),
-    update: (id, data) => raw.update(name, id, data),
-    delete: (id) => raw.delete(name, id),
-    findById: (id) => raw.findById(name, id),
-    findMany: (query) => raw.findMany(name, query)
-  };
-}
-function makeTypedDB(schema, raw) {
-  const tables = {};
-  for (const key of Object.keys(schema.tables)) {
-    const tableDef = schema.tables[key];
-    if (tableDef !== void 0) {
-      tables[key] = makeTypedTable(tableDef.name, raw);
-    }
-  }
-  return { tables };
-}
-
 // src/middleware.ts
 function defineMiddleware(fn) {
   return fn;
@@ -46,17 +39,22 @@ var HttpError = class extends Error {
   status;
   error;
   errorDescription;
-  constructor(status, error, errorDescription) {
+  data;
+  constructor(status, error, errorDescription, data) {
     super(errorDescription);
     this.name = "HttpError";
     this.status = status;
     this.error = error;
     this.errorDescription = errorDescription;
+    if (data !== void 0) {
+      this.data = data;
+    }
   }
   /**
    * 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) {
     const result = {
@@ -67,6 +65,9 @@ var HttpError = class extends Error {
     if (requestId) {
       result.request_id = requestId;
     }
+    if (this.data !== void 0) {
+      result.data = this.data;
+    }
     return result;
   }
 };
@@ -325,7 +326,17 @@ var documents = {
 // src/index.ts
 import { z } from "zod";
 export {
+  Cache,
+  Database,
+  Documents,
+  Flags,
   HttpError,
+  Log,
+  Notifications,
+  Queue,
+  Storage,
+  __getRuntime,
+  __setRuntime,
   auth,
   boolean,
   defineEndpoint,
@@ -343,6 +354,7 @@ export {
   table,
   text,
   timestamp,
+  typedDatabase,
   uuid,
   z
 };