@palbase/backend 9.0.0 → 10.0.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { C as CacheClient, b as PalbaseDocsClient, c as PalbaseFlagsClient, L as Logger, d as PalbaseNotificationsClient, Q as QueueClient, e as PalbaseRealtimeClient, D as DBClient, f as PalbaseStorageClient, A as AuthSpec, R as RateLimitConfig, H as HttpError, U as User$1 } from './endpoint-CGI5cZMg.js';
-export { g as AuthConfig, B as BadRequest, h as ClientInfo, i as Conflict, j as DBOps, E as ErrorDef, k as ErrorMap, l as ErrorThrowers, F as FileContext, m as Forbidden, n as HttpMethod, M as Middleware, o as MiddlewareContext, p as MiddlewareHandler, N as NotFound, P as PBRequest, q as PalError, r as PalbaseAnalyticsClient, s as PalbaseAnalyticsManagementNamespace, t as PalbaseAnalyticsProperties, u as PalbaseAnalyticsQueryNamespace, v as PalbaseAttestAndroidParams, w as PalbaseAttestAndroidResult, x as PalbaseAttestiOSParams, y as PalbaseAttestiOSResult, z as PalbaseAuthClient, G as PalbaseBatchOverrideOperation, I as PalbaseBatchSetOverridesResult, J as PalbaseBindDeviceParams, K as PalbaseBucketClient, O as PalbaseClearAllOverridesResult, S as PalbaseClearOverrideResult, T as PalbaseCohortQueryInput, V as PalbaseCohortResult, W as PalbaseCollectionRef, X as PalbaseCountQueryInput, Y as PalbaseCountResult, Z as PalbaseCreateLinkParams, _ as PalbaseDeviceInfo, $ as PalbaseDeviceTokenView, a0 as PalbaseDocumentRef, a1 as PalbaseDocumentSnapshot, a2 as PalbaseEmailClient, a3 as PalbaseEmailSendParams, a4 as PalbaseEmailSendResponse, a5 as PalbaseEventNamesResult, a6 as PalbaseEventsQueryInput, a7 as PalbaseEventsResult, a8 as PalbaseFileObject, a9 as PalbaseFlag, aa as PalbaseFlagContext, ab as PalbaseFlagSource, ac as PalbaseFlagValue, ad as PalbaseFlagVariant, ae as PalbaseFlagsServiceClient, af as PalbaseFunctionsClient, ag as PalbaseFunnelQueryInput, ah as PalbaseFunnelResult, ai as PalbaseIdentifyTraits, aj as PalbaseInboxClient, ak as PalbaseInboxListOptions, al as PalbaseInboxListResult, am as PalbaseInboxMessage, an as PalbaseInboxSendParams, ao as PalbaseInboxSendResponse, ap as PalbaseInitialLink, aq as PalbaseInvokeOptions, ar as PalbaseLink, as as PalbaseLinkAnalytics, at as PalbaseLinkDetails, au as PalbaseLinksClient, av as PalbaseListLinksOptions, aw as PalbaseListLinksResult, ax as PalbaseListOptions, ay as PalbaseMatchParams, az as PalbaseMultiChannelResponse, aA as PalbaseOverviewResult, aB as PalbasePreferences, aC as PalbasePreferencesClient, aD as PalbasePublicUrlResponse, aE as PalbasePushClient, aF as PalbasePushSendParams, aG as PalbasePushSendResponse, aH as PalbaseQrCodeOptions, aI as PalbaseQuerySnapshot, aJ as PalbaseRegisterDeviceParams, aK as PalbaseResult, aL as PalbaseRetentionQueryInput, aM as PalbaseRetentionResult, aN as PalbaseSession, aO as PalbaseSetOverrideResult, aP as PalbaseSetOverridesResult, aQ as PalbaseSignedUrlResponse, aR as PalbaseSmsClient, aS as PalbaseSmsSendParams, aT as PalbaseSmsSendResponse, aU as PalbaseTransformOptions, aV as PalbaseUpdateLinkParams, aW as PalbaseUploadOptions, aX as PalbaseUser, aY as PalbaseUserDetailResult, aZ as PalbaseUsersQueryInput, a_ as PalbaseUsersResult, a$ as PalbaseVerifyRequestSignatureParams, b0 as PalbaseWhereOperator, b1 as TooManyRequests, b2 as TxClient, b3 as Unauthorized, b4 as defineMiddleware } from './endpoint-CGI5cZMg.js';
+import { C as CacheClient, b as PalbaseDocsClient, c as PalbaseFlagsClient, L as Logger, d as PalbaseNotificationsClient, Q as QueueClient, e as PalbaseRealtimeClient, D as DBClient, f as PalbaseStorageClient, A as AuthSpec, R as RateLimitConfig, H as HttpError, U as User$1 } from './endpoint-Cn3ICGTf.js';
+export { g as AuthConfig, B as BadRequest, h as ClientInfo, i as Conflict, j as DBOps, E as ErrorDef, k as ErrorMap, l as ErrorThrowers, F as FileContext, m as Forbidden, n as HttpMethod, M as Middleware, o as MiddlewareContext, p as MiddlewareHandler, N as NotFound, P as PBRequest, q as PalError, r as PalbaseAnalyticsClient, s as PalbaseAnalyticsManagementNamespace, t as PalbaseAnalyticsProperties, u as PalbaseAnalyticsQueryNamespace, v as PalbaseAttestAndroidParams, w as PalbaseAttestAndroidResult, x as PalbaseAttestiOSParams, y as PalbaseAttestiOSResult, z as PalbaseAuthClient, G as PalbaseBatchOverrideOperation, I as PalbaseBatchSetOverridesResult, J as PalbaseBindDeviceParams, K as PalbaseBucketClient, O as PalbaseClearAllOverridesResult, S as PalbaseClearOverrideResult, T as PalbaseCohortQueryInput, V as PalbaseCohortResult, W as PalbaseCollectionRef, X as PalbaseCountQueryInput, Y as PalbaseCountResult, Z as PalbaseCreateLinkParams, _ as PalbaseDeviceInfo, $ as PalbaseDeviceTokenView, a0 as PalbaseDocumentRef, a1 as PalbaseDocumentSnapshot, a2 as PalbaseEmailClient, a3 as PalbaseEmailSendParams, a4 as PalbaseEmailSendResponse, a5 as PalbaseEventNamesResult, a6 as PalbaseEventsQueryInput, a7 as PalbaseEventsResult, a8 as PalbaseFileObject, a9 as PalbaseFlag, aa as PalbaseFlagContext, ab as PalbaseFlagSource, ac as PalbaseFlagValue, ad as PalbaseFlagVariant, ae as PalbaseFlagsServiceClient, af as PalbaseFunctionsClient, ag as PalbaseFunnelQueryInput, ah as PalbaseFunnelResult, ai as PalbaseIdentifyTraits, aj as PalbaseInboxClient, ak as PalbaseInboxListOptions, al as PalbaseInboxListResult, am as PalbaseInboxMessage, an as PalbaseInboxSendParams, ao as PalbaseInboxSendResponse, ap as PalbaseInitialLink, aq as PalbaseInvokeOptions, ar as PalbaseLink, as as PalbaseLinkAnalytics, at as PalbaseLinkDetails, au as PalbaseLinksClient, av as PalbaseListLinksOptions, aw as PalbaseListLinksResult, ax as PalbaseListOptions, ay as PalbaseMatchParams, az as PalbaseMultiChannelResponse, aA as PalbaseOverviewResult, aB as PalbasePreferences, aC as PalbasePreferencesClient, aD as PalbasePublicUrlResponse, aE as PalbasePushClient, aF as PalbasePushSendParams, aG as PalbasePushSendResponse, aH as PalbaseQrCodeOptions, aI as PalbaseQuerySnapshot, aJ as PalbaseRegisterDeviceParams, aK as PalbaseResult, aL as PalbaseRetentionQueryInput, aM as PalbaseRetentionResult, aN as PalbaseSession, aO as PalbaseSetOverrideResult, aP as PalbaseSetOverridesResult, aQ as PalbaseSignedUrlResponse, aR as PalbaseSmsClient, aS as PalbaseSmsSendParams, aT as PalbaseSmsSendResponse, aU as PalbaseTransformOptions, aV as PalbaseUpdateLinkParams, aW as PalbaseUploadOptions, aX as PalbaseUser, aY as PalbaseUserDetailResult, aZ as PalbaseUsersQueryInput, a_ as PalbaseUsersResult, a$ as PalbaseVerifyRequestSignatureParams, b0 as PalbaseWhereOperator, b1 as TooManyRequests, b2 as TxClient, b3 as Unauthorized, b4 as VerifiedDevice, b5 as defineMiddleware } from './endpoint-Cn3ICGTf.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { E as EnvTypedDatabase, S as SchemaDef } from './index--dH5i4Nu.js';
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, f as EnvTables, g as EnvTypedTable, h as EnvTypedTx, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RawConstraintDef, n as RowShape, o as SchemaInput, T as TableDef, p as TableInput, q as TypedDB, r as TypedTable, s as TypedTx, t as bigint, u as boolean, v as defineSchema, w as enumType, x as integer, y as isPalbaseExtension, z as jsonb, A as makeTypedDB, B as numeric, D as policy, F as raw, G as text, H as timestamp, J as uuid } from './index--dH5i4Nu.js';
-export { TableTypes, Tables } from './db/env.js';
+import { E as EnvTypedDatabase, S as SchemaDef } from './index-V0ealeY-.js';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, f as EnvTables, g as EnvTypedTable, h as EnvTypedTx, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as RawConstraintDef, n as RowShape, o as SchemaInput, T as TableDef, p as TableInput, q as TypedDB, r as TypedTable, s as TypedTx, t as bigint, u as boolean, v as defineSchema, w as enumType, x as integer, y as isPalbaseExtension, z as jsonb, A as makeTypedDB, B as numeric, D as policy, F as raw, G as text, H as timestamp, J as uuid } from './index-V0ealeY-.js';
+import { TableTypes, Tables } from './db/env.js';
 import { ZodTypeAny, z } from 'zod';
 export { z } from 'zod';
 
@@ -307,6 +307,47 @@ declare function bucket(opts?: BucketOptions): BucketDef;
  */
 declare function defineStorage(input: StorageInput): StorageConfig;
 
+/**
+ * egress.ts — the tenant outbound-HTTP allowlist config-as-code DSL.
+ *
+ * `defineEgress({ hosts })` declares the external hosts a backend may fetch().
+ * config/egress.ts default-exports it; the deploy evals it to JSON
+ * (SchemaExtractor.EvaluateConfigFile → config_extract.js) and bakes the
+ * allowlist into the artifact manifest → the isolate loader → Tenant.egressAllow.
+ * The tenantFetch capability rejects any host NOT on it. NO config/egress.ts (or
+ * an empty list) ⇒ the backend has NO outbound network — fail-closed.
+ *
+ * @example
+ *   // config/egress.ts
+ *   import { defineEgress } from "@palbase/backend";
+ *   export default defineEgress({
+ *     hosts: ["api.open-meteo.com", "restcountries.com", "zenquotes.io"],
+ *   });
+ *
+ * Each host is a bare hostname (no scheme/port/path/wildcard). A leading dot,
+ * `.example.com`, also covers subdomains (Squid dstdomain semantics). Egress is
+ * https-only on :443; the deploy REJECTS a malformed / IP-literal / internal host
+ * (fail-closed — a security allowlist is never best-effort).
+ *
+ * Emits: { __config: "egress", hosts: [...] }
+ */
+/** The discriminant written under `__config` so the deploy eval knows the kind. */
+declare const EGRESS_CONFIG_KIND: "egress";
+/** The author-facing input to defineEgress. */
+interface EgressInput {
+    hosts: string[];
+}
+/** The evaluated config/egress.ts default export (what the deploy reads). */
+interface EgressConfig {
+    __config: typeof EGRESS_CONFIG_KIND;
+    hosts: string[];
+}
+/**
+ * Declare the backend's outbound-HTTP allowlist. Client-side this only shapes +
+ * validates the list; the authoritative fail-closed validation runs at deploy.
+ */
+declare function defineEgress(input: EgressInput): EgressConfig;
+
 /**
  * notifications.ts — the notification-providers config-as-code DSL.
  *
@@ -554,6 +595,173 @@ declare function defineNotifications(input: NotificationsInput): NotificationsCo
  */
 declare function reservedSecretKey(provider: ProviderName, secretField: string): string;
 
+/**
+ * test-users.ts — the test-user fixtures config-as-code DSL.
+ *
+ * `defineTestUsers({ users })` is a MODULE config-as-code surface (a sibling of
+ * `config/storage.ts`'s `defineStorage` and `config/flags.ts`'s `defineFlags`).
+ * A `config/test-users.ts` file default-exports a `defineTestUsers(...)` result;
+ * on deploy the runtime evaluates it to JSON and hands it to Studio, which owns
+ * the single apply engine (mint + seed). Studio, the CLI and the deploy all go
+ * through that one engine — there is no second interpreter of this JSON.
+ *
+ * TWO SHAPES, ONE DSL:
+ *
+ *  - `email` GIVEN  → a FIXTURE. Deploy materializes it create-if-missing, so
+ *    the app can always be signed into with the same credentials. Deliberately
+ *    NOT applied to a production Environment (the password lives in git).
+ *  - `email` OMITTED → a TEMPLATE. Deploy creates nothing; Studio and the CLI
+ *    mint as many fresh instances from it as you want (random credentials).
+ *
+ * Every minted user is an `is_test` user: excluded from MAU/billing, carrying
+ * `test: true` in its token, and refused by the Test Data write path if it ever
+ * turns out not to be one.
+ *
+ * @example
+ * import { defineTestUsers, testUser } from "@palbase/backend";
+ *
+ * export default defineTestUsers({
+ *   users: {
+ *     demo: testUser({
+ *       email: "demo@test.local",
+ *       password: "demo-password-1234",
+ *       seed: {
+ *         profiles: [{ display_name: "Demo", tier: "pro" }],
+ *         lists: [
+ *           { title: "Groceries", todos: [{ title: "Milk" }, { title: "Eggs", done: true }] },
+ *         ],
+ *       },
+ *     }),
+ *     heavy_user: testUser({ seed: { lists: [{ title: "L", todos: [{ title: "t" }] }] } }),
+ *   },
+ * });
+ *
+ * The returned value is the EXACT JSON shape the runtime's generic config
+ * extractor emits and the apply engine consumes:
+ *   { __config: "test-users", users: { <name>: { email, password, seed } } }
+ * `email` / `password` are the string or `null`; `seed` is `{}` when omitted.
+ */
+
+/** The `__config` discriminant the eval/apply reads to confirm a config/*.ts is
+ * a test-users config. */
+declare const TEST_USERS_CONFIG_KIND: "test-users";
+/**
+ * A table graph in the shape the env `Tables` interface carries. The
+ * derivations below are parameterized over it (rather than reading the global
+ * `Tables` directly) so they can be type-tested against a fixture graph without
+ * augmenting the global interface — augmentation is program-wide and would leak
+ * into every other type test.
+ *
+ * The `Record<keyof G, …>` constraint is deliberate: a plain
+ * `Record<string, TableTypes>` would reject the `Tables` INTERFACE, which has
+ * no index signature.
+ */
+type TableGraph = Record<string, TableTypes>;
+/** The user-rooted tables of `G` — the ones a test user owns rows in directly. */
+type OwnedTablesOf<G extends Record<keyof G, TableTypes>> = {
+    [T in keyof G]: G[T]["owner"] extends string ? T : never;
+}[keyof G];
+/**
+ * One authored seed row for table `T` of graph `G`.
+ *
+ * Starts from the table's INSERT shape and removes the two columns the engine
+ * owns: the owner column (set to the minted user) and `Via` — the FK column
+ * this row hangs off its parent by, when the row is nested under one. What
+ * remains is extended with the table's children, each an optional array of
+ * their own seed rows.
+ *
+ * Recursion terminates because `makeEnvDts` drops self-FKs and cycle
+ * back-edges when it emits `children`.
+ *
+ * Name collision note: if a table has a COLUMN whose name equals a CHILD
+ * table's name, the intersection makes that key unusable (its type collapses).
+ * That is a schema-naming problem the author sees at compile time; the apply
+ * engine resolves the same ambiguity live in favour of the column, because it
+ * introspects the real table.
+ */
+type SeedRowFor<G extends Record<keyof G, TableTypes>, T extends keyof G, Via extends string = never> = Omit<G[T]["insert"], (G[T]["owner"] & string) | Via> & {
+    [C in keyof G[T]["children"]]?: Array<SeedRowFor<G, C & keyof G, G[T]["children"][C] & string>>;
+};
+/** The typed seed over graph `G`: top-level keys are user-rooted tables only;
+ * everything else is reached by nesting under its parent. */
+type SeedFor<G extends Record<keyof G, TableTypes>> = {
+    [T in OwnedTablesOf<G>]?: Array<SeedRowFor<G, T>>;
+};
+/** The serialized seed — what travels as JSON and what the engine receives. */
+type SeedJson = Record<string, Array<Record<string, unknown>>>;
+/**
+ * The author-facing seed type. Falls back to the loose shape when `Tables` is
+ * still empty (no `db/schema.ts`, or `palbase-env.d.ts` not generated yet) so
+ * an unseeded project gets a usable DSL instead of an inscrutable `{}` error.
+ */
+type Seed = [keyof Tables] extends [never] ? SeedJson : SeedFor<Tables>;
+/**
+ * The options for one declared test user.
+ *
+ * - `email` / `password`: supply BOTH to make this a fixture with stable
+ *   credentials (deploy materializes it, the app signs in with them), or
+ *   NEITHER to make it a template the server generates credentials for.
+ * - `seed`: the user's data tree, derived from `db/schema.ts`. Top-level keys
+ *   are user-rooted tables; FK children nest inside their parent's rows.
+ */
+interface TestUserOptions {
+    email?: string;
+    password?: string;
+    seed?: Seed;
+}
+/** The compiled, serializable test-user definition — the EXACT shape emitted to
+ * JSON and consumed by the apply engine. */
+interface TestUserDef {
+    /** Fixed login e-mail (fixture), or `null` when the server should generate one. */
+    email: string | null;
+    /** Fixed password (fixture), or `null` when the server should generate one. */
+    password: string | null;
+    /** The user's data tree; `{}` when nothing is seeded. */
+    seed: SeedJson;
+}
+/** A test-users config: the discriminant + the declared users by name. */
+interface TestUsersConfig {
+    __config: typeof TEST_USERS_CONFIG_KIND;
+    users: Record<string, TestUserDef>;
+}
+/** The author-facing input to `defineTestUsers`. */
+interface TestUsersInput {
+    users: Record<string, TestUserDef>;
+}
+/**
+ * Define a single test user. The NAME is supplied by the object key in
+ * `defineTestUsers({ users: { <name>: testUser({...}) } })`, so `testUser()`
+ * takes only the options.
+ *
+ * Validates eagerly (at config-author time):
+ *  - `email` and `password` are supplied together or not at all — half a
+ *    credential pair would silently degrade a fixture into a template.
+ *  - `email` looks like an address; `password` is at least
+ *    {@link MIN_PASSWORD_LENGTH} characters.
+ *  - `seed` is structurally `{ <table>: [ {...}, ... ] }` with non-empty arrays.
+ *
+ * The user NAME is validated by `defineTestUsers`, which is where it is known.
+ */
+declare function testUser(opts?: TestUserOptions): TestUserDef;
+/**
+ * Define a project's test users. The user NAME comes from each object key
+ * (authors never repeat it). Returns the discriminated {@link TestUsersConfig}
+ * the runtime config extractor serializes and the apply engine consumes.
+ *
+ * Validates eagerly:
+ *  - each name matches `^[a-zA-Z][a-zA-Z0-9_]*$` (the CLI's `--template <name>`
+ *    and control-pg's scenario name share this vocabulary).
+ *  - no two fixtures declare the SAME e-mail — they would race to
+ *    create-if-missing the one account and the second would silently adopt the
+ *    first one's data tree.
+ *
+ * @example
+ * export default defineTestUsers({
+ *   users: { demo: testUser({ email: "demo@test.local", password: "demo-password-1234" }) },
+ * });
+ */
+declare function defineTestUsers(input: TestUsersInput): TestUsersConfig;
+
 /**
  * flags.ts — the feature-flag-definitions config-as-code DSL.
  *
@@ -804,6 +1012,21 @@ interface RouteOptions {
      * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
     uploadConfig?: UploadConfig;
 }
+/** The kind of value a parameter decorator injects. Drives both dispatch
+ * (which request slice to inject) and codegen (which OpenAPI parameter source a
+ * schema-bearing kind maps to). */
+type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject";
+/** One parameter decorator's recorded metadata. `index` is the parameter
+ * position esbuild/tsc preserve; `schema` is present for the schema-bearing
+ * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */
+interface ParamMeta {
+    index: number;
+    kind: ParamKind;
+    /** Zod schema for `body`/`query`/`headers` (validation + codegen source). */
+    schema?: ZodTypeAny;
+    /** Path-param name for `@Param("id")`. */
+    name?: string;
+}
 /** One inferred throw site: the error CLASS name (e.g. "TodoLocked") and its
  * wire code (e.g. "todo_locked"). `status`, `hasData`, and the data JSON schema
  * are NOT carried here — they resolve from the error registry by `code` at
@@ -812,12 +1035,37 @@ interface ThrowDescriptor {
     name: string;
     code: string;
 }
+/** One route's recorded metadata: the verb + subpath + method name + options,
+ * the ordered parameter metas, and the resolved return schema (injected by the
+ * codegen step — see `returnSchema`). */
+interface RouteMeta {
+    method: HttpMethodUpper;
+    subpath: string;
+    fnName: string;
+    options: RouteOptions;
+    params: ParamMeta[];
+    /** Response schema for the route, if any. Derived from the method's RETURN
+     * TYPE by codegen and written here via `recordReturn` (a generated top-level
+     * IIFE injected per controller), not by an author-written decorator. */
+    returnSchema?: ZodTypeAny;
+    /** Error classes this route can throw, if inferred. Derived from the method
+     * body + service call graph by the deploy stager's throw analysis and written
+     * here via `recordThrows` (a generated top-level IIFE injected per controller,
+     * the `recordReturn` twin), not by an author-written decorator. */
+    throws?: ThrowDescriptor[];
+}
 /** Attach the inferred throw descriptors to the route for `fnName` (called by
  * the stager-injected IIFE that carries the throw analysis result — the
  * `recordReturn` twin). If the route does not exist yet, the descriptors are
  * buffered (THROWS_BUFFER) and drained into the route by `recordRoute` when the
  * method decorator runs. */
 declare function recordThrows(target: object, fnName: string, throws: ThrowDescriptor[]): void;
+/** Read the route metadata for a controller class (the deploy/dispatch entry
+ * point). Applies any buffered return schemas + throw descriptors (for the
+ * recordReturn/recordThrows-runs-before orderings) and returns a defensive copy
+ * so callers cannot mutate the registry.
+ */
+declare function getRoutes(ctor: object): RouteMeta[];
 
 /** A legacy method decorator. */
 type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
@@ -906,13 +1154,13 @@ declare function defineError(code: string, status: number): DefinedError;
 /** Non-service, per-invocation data for background worker handlers.
  * Services (Database, Log, …) are imported as singletons, not passed here. */
 interface WorkerMeta {
-    /** Branch-scoped env vars. */
+    /** Environment-scoped env vars. */
     env: Record<string, string>;
     /** The user that enqueued the job, if any (background jobs are usually system-initiated). */
     user: User$1 | null;
     /** Per-invocation id for correlation. */
     requestId: string;
-    projectId: string;
+    /** The globally unique Environment runtime identifier. */
     environmentId: string;
 }
 /** Backoff strategy for worker retries. */
@@ -961,9 +1209,9 @@ declare function defineWorker<TPayload = unknown>(config: WorkerConfig<TPayload>
 /** Non-service, per-invocation data for job handlers.
  * Services (Database, Log, …) are imported as singletons, not passed here. */
 interface JobMeta {
-    /** Branch-scoped env vars. */
+    /** Environment-scoped env vars. */
     env: Record<string, string>;
-    projectId: string;
+    /** The globally unique Environment runtime identifier. */
     environmentId: string;
 }
 /** Configuration for defining a scheduled job. */
@@ -1009,11 +1257,11 @@ type WebhookProvider = "stripe" | "github" | "twilio" | "sendgrid" | "slack" | "
 /** Non-service, per-invocation data for webhook handlers.
  * Services (Database, Log, …) are imported as singletons, not passed here. */
 interface WebhookMeta {
-    /** Branch-scoped env vars. */
+    /** Environment-scoped env vars. */
     env: Record<string, string>;
     /** Per-invocation id for correlation. */
     requestId: string;
-    projectId: string;
+    /** The globally unique Environment runtime identifier. */
     environmentId: string;
 }
 /** Secret reference — resolves from environment variables at runtime. */
@@ -1241,9 +1489,9 @@ declare function __shutdownResources(): Promise<void>;
 /** Non-service, per-invocation data for hook handlers.
  * Services (Database, Log, …) are imported as singletons, not passed here. */
 interface HookMeta {
-    /** Branch-scoped env vars. */
+    /** Environment-scoped env vars. */
     env: Record<string, string>;
-    projectId: string;
+    /** The globally unique Environment runtime identifier. */
     environmentId: string;
 }
 /** Payload for auth.onUserCreated hook. */
@@ -1355,4 +1603,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-export { type AcsOptions, type ApnsOptions, type BackoffStrategy, Body, type BucketDef, type BucketOptions, Cache, CacheClient, Client, Controller, type ControllerOptions, type CustomWebhookConfig, DBClient, Database, type DefinedError, type DefinedErrorWithData, Delete, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, type EnvSecretRef, EnvTypedDatabase, FLAGS_CONFIG_KIND, type FcmOptions, type FileDeletedEvent, type FileUploadedEvent, type FlagDef, type FlagOptions, type FlagType, type FlagValue, Flags, type FlagsConfig, type FlagsInput, Get, Headers, type HookHandler, type HookMeta, HttpError, type HttpMethodUpper, type JobConfig, type JobMeta, Log, Logger, NOTIFICATIONS_CONFIG_KIND, Notifications, type NotificationsConfig, type NotificationsInput, OptionalUser, PROVIDER_CATALOG, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseRealtimeClient, PalbaseStorageClient, Param, type PasswordResetEvent, Patch, Post, type ProviderCatalogEntry, type ProviderDef, type ProviderEventMap, type ProviderName, type ProviderOptions, type ProviderWebhookConfig, Put, Query, QueryParams, Queue, QueueClient, RESERVED_SECRET_PREFIX, RateLimitConfig, Realtime, type RegisteredError, Req, RequestId, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, Resource, type ResourceEnv, type RouteOptions, type RuntimeServices, STORAGE_CONFIG_KIND, SchemaDef, type SendgridOptions, type SesOptions, type SignInEvent, type SignOutEvent, type SmtpOptions, Storage, type StorageConfig, type StorageInput, type ThrowDescriptor, TraceId, type TwilioOptions, Upload, type UploadConfig, UploadedObject, User, type UserCreatedEvent, User$1 as UserT, type WebhookEventHandler, type WebhookMeta, type WebhookProvider, type WebhookRequest, type WorkerConfig, type WorkerMeta, __getRuntime, __registerResource, __requestALS, __runResourceBoot, __runWithRuntime, __setRuntime, __shutdownResources, auth, bucket, buildProvider, defineError, defineFlags, defineJob, defineNotifications, defineStorage, defineWebhook, defineWorker, documents, flag, getErrorRegistry, makeEnvDts, parseFileSizeLimit, recordThrows, reservedSecretKey, storage, validateUploadAgainstStorage };
+export { type AcsOptions, type ApnsOptions, type BackoffStrategy, Body, type BucketDef, type BucketOptions, Cache, CacheClient, Client, Controller, type ControllerOptions, type CustomWebhookConfig, DBClient, Database, type DefinedError, type DefinedErrorWithData, Delete, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, EGRESS_CONFIG_KIND, type EgressConfig, type EgressInput, type EnvSecretRef, EnvTypedDatabase, FLAGS_CONFIG_KIND, type FcmOptions, type FileDeletedEvent, type FileUploadedEvent, type FlagDef, type FlagOptions, type FlagType, type FlagValue, Flags, type FlagsConfig, type FlagsInput, Get, Headers, type HookHandler, type HookMeta, HttpError, type HttpMethodUpper, type JobConfig, type JobMeta, Log, Logger, NOTIFICATIONS_CONFIG_KIND, Notifications, type NotificationsConfig, type NotificationsInput, OptionalUser, type OwnedTablesOf, PROVIDER_CATALOG, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseRealtimeClient, PalbaseStorageClient, Param, type ParamKind, type ParamMeta, type PasswordResetEvent, Patch, Post, type ProviderCatalogEntry, type ProviderDef, type ProviderEventMap, type ProviderName, type ProviderOptions, type ProviderWebhookConfig, Put, Query, QueryParams, Queue, QueueClient, RESERVED_SECRET_PREFIX, RateLimitConfig, Realtime, type RegisteredError, Req, RequestId, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, Resource, type ResourceEnv, type RouteMeta, type RouteOptions, type RuntimeServices, STORAGE_CONFIG_KIND, SchemaDef, type Seed, type SeedFor, type SeedJson, type SeedRowFor, type SendgridOptions, type SesOptions, type SignInEvent, type SignOutEvent, type SmtpOptions, Storage, type StorageConfig, type StorageInput, TEST_USERS_CONFIG_KIND, type TableGraph, TableTypes, Tables, type TestUserDef, type TestUserOptions, type TestUsersConfig, type TestUsersInput, type ThrowDescriptor, TraceId, type TwilioOptions, Upload, type UploadConfig, UploadedObject, User, type UserCreatedEvent, User$1 as UserT, type WebhookEventHandler, type WebhookMeta, type WebhookProvider, type WebhookRequest, type WorkerConfig, type WorkerMeta, __getRuntime, __registerResource, __requestALS, __runResourceBoot, __runWithRuntime, __setRuntime, __shutdownResources, auth, bucket, buildProvider, defineEgress, defineError, defineFlags, defineJob, defineNotifications, defineStorage, defineTestUsers, defineWebhook, defineWorker, documents, flag, getErrorRegistry, getRoutes, makeEnvDts, parseFileSizeLimit, recordThrows, reservedSecretKey, storage, testUser, validateUploadAgainstStorage };

package/dist/index.js

@@ -31,7 +31,7 @@ import {
   text,
   timestamp,
   uuid
-} from "./chunk-SO6YV35D.js";
+} from "./chunk-4WOQWFUP.js";
 
 // src/db/env-gen.ts
 function baseTsType(def) {
@@ -64,7 +64,50 @@ function rowType(def) {
 function optionalOnInsert(def) {
   return def.nullable === true || def.defaultRandom === true || def.defaultNow === true || def.defaultValue !== void 0;
 }
-function tableBlock(table, indent) {
+var AUTH_USERS_TABLE = "auth.users";
+function ownerColumnOf(table) {
+  for (const [col, builder] of Object.entries(table.columns)) {
+    if (builder._def.references?.table === AUTH_USERS_TABLE) return col;
+  }
+  return null;
+}
+function buildChildEdges(schema) {
+  const edges = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(schema.tables)) edges.set(name, []);
+  for (const childName of Object.keys(schema.tables)) {
+    const table = schema.tables[childName];
+    if (table === void 0) continue;
+    for (const [col, builder] of Object.entries(table.columns)) {
+      const ref = builder._def.references;
+      if (ref === void 0) continue;
+      if (ref.table === childName) continue;
+      const bucket2 = edges.get(ref.table);
+      if (bucket2 === void 0) continue;
+      if (bucket2.some((e) => e.child === childName)) continue;
+      bucket2.push({ child: childName, column: col });
+    }
+  }
+  return edges;
+}
+function pruneCycles(raw2) {
+  const pruned = /* @__PURE__ */ new Map();
+  for (const table of raw2.keys()) pruned.set(table, []);
+  const state = /* @__PURE__ */ new Map();
+  function visit(table) {
+    state.set(table, "visiting");
+    for (const edge of raw2.get(table) ?? []) {
+      if (state.get(edge.child) === "visiting") continue;
+      pruned.get(table)?.push(edge);
+      if (state.get(edge.child) === void 0) visit(edge.child);
+    }
+    state.set(table, "done");
+  }
+  for (const table of raw2.keys()) {
+    if (state.get(table) === void 0) visit(table);
+  }
+  return pruned;
+}
+function tableBlock(table, children, indent) {
   const cols = Object.entries(table.columns);
   const rowLines = cols.map(([col, builder]) => {
     return `${indent}    ${col}: ${rowType(builder._def)};`;
@@ -74,6 +117,8 @@ function tableBlock(table, indent) {
     const opt = optionalOnInsert(def) ? "?" : "";
     return `${indent}    ${col}${opt}: ${rowType(def)};`;
   });
+  const owner = ownerColumnOf(table);
+  const childEntries = children.map((e) => `${JSON.stringify(e.child)}: ${JSON.stringify(e.column)}`).join("; ");
   return [
     `${indent}${table.name}: {`,
     `${indent}  row: {`,
@@ -82,12 +127,17 @@ function tableBlock(table, indent) {
     `${indent}  insert: {`,
     ...insertLines,
     `${indent}  };`,
+    `${indent}  owner: ${owner === null ? "null" : JSON.stringify(owner)};`,
+    `${indent}  children: {${childEntries === "" ? "" : ` ${childEntries} `}};`,
     `${indent}};`
   ].join("\n");
 }
 function makeEnvDts(schema) {
   const tableNames = Object.keys(schema.tables);
-  const blocks = tableNames.map((name) => tableBlock(schema.tables[name], "    "));
+  const children = pruneCycles(buildChildEdges(schema));
+  const blocks = tableNames.map(
+    (name) => tableBlock(schema.tables[name], children.get(name) ?? [], "    ")
+  );
   const body = blocks.length > 0 ? `
 ${blocks.join("\n")}
   ` : "";
@@ -182,6 +232,22 @@ function defineStorage(input) {
   return { __config: STORAGE_CONFIG_KIND, buckets };
 }
 
+// src/config/egress.ts
+var EGRESS_CONFIG_KIND = "egress";
+function defineEgress(input) {
+  if (input === null || typeof input !== "object" || !Array.isArray(input.hosts)) {
+    throw new Error("defineEgress expects { hosts: string[] }");
+  }
+  const hosts = [];
+  for (const h of input.hosts) {
+    if (typeof h !== "string" || h.trim().length === 0) {
+      throw new Error("defineEgress: every host must be a non-empty string");
+    }
+    hosts.push(h.trim().toLowerCase());
+  }
+  return { __config: EGRESS_CONFIG_KIND, hosts };
+}
+
 // src/config/notifications.ts
 var NOTIFICATIONS_CONFIG_KIND = "notifications";
 var RESERVED_SECRET_PREFIX = "PB_NOTIFICATIONS";
@@ -293,6 +359,98 @@ function camelToUpperSnake(s) {
   return s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 }
 
+// src/config/test-users.ts
+var TEST_USERS_CONFIG_KIND = "test-users";
+var TEST_USER_NAME_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var MIN_PASSWORD_LENGTH = 8;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeSeed(seed, userName) {
+  if (seed === void 0) return {};
+  if (!isPlainObject(seed)) {
+    throw new Error(`testUser ${JSON.stringify(userName)}: seed must be { <table>: [ {...} ] }`);
+  }
+  const out = {};
+  for (const [table, rows] of Object.entries(seed)) {
+    if (!Array.isArray(rows)) {
+      throw new Error(
+        `testUser ${JSON.stringify(userName)}: seed.${table} must be an array of rows`
+      );
+    }
+    if (rows.length === 0) {
+      throw new Error(
+        `testUser ${JSON.stringify(userName)}: seed.${table} is empty \u2014 remove it or add a row`
+      );
+    }
+    for (const row of rows) {
+      if (!isPlainObject(row)) {
+        throw new Error(
+          `testUser ${JSON.stringify(userName)}: every row in seed.${table} must be an object`
+        );
+      }
+    }
+    out[table] = rows;
+  }
+  return out;
+}
+function testUser(opts = {}) {
+  if (!isPlainObject(opts)) {
+    throw new Error("testUser() expects { email?, password?, seed? }");
+  }
+  const hasEmail = opts.email !== void 0;
+  const hasPassword = opts.password !== void 0;
+  if (hasEmail !== hasPassword) {
+    throw new Error(
+      "testUser() needs email AND password together (a fixture with stable credentials) or neither (a template the server generates credentials for)"
+    );
+  }
+  let email = null;
+  let password = null;
+  if (hasEmail) {
+    if (typeof opts.email !== "string" || !EMAIL_RE.test(opts.email)) {
+      throw new Error(`testUser email ${JSON.stringify(opts.email)} is not a valid address`);
+    }
+    if (typeof opts.password !== "string" || opts.password.length < MIN_PASSWORD_LENGTH) {
+      throw new Error(
+        `testUser password must be at least ${MIN_PASSWORD_LENGTH} characters (got ${typeof opts.password === "string" ? opts.password.length : 0})`
+      );
+    }
+    email = opts.email;
+    password = opts.password;
+  }
+  return { email, password, seed: normalizeSeed(opts.seed, email ?? "<template>") };
+}
+function defineTestUsers(input) {
+  if (!isPlainObject(input) || !isPlainObject(input.users)) {
+    throw new Error("defineTestUsers expects { users: { <name>: testUser({...}) } }");
+  }
+  const users = {};
+  const emails = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(input.users)) {
+    if (!TEST_USER_NAME_RE.test(name)) {
+      throw new Error(
+        `test user name ${JSON.stringify(name)} is invalid \u2014 must start with a letter and contain only letters, digits, and underscores`
+      );
+    }
+    const def = input.users[name];
+    if (def === void 0) continue;
+    if (def.email !== null) {
+      const lower = def.email.toLowerCase();
+      const already = emails.get(lower);
+      if (already !== void 0) {
+        throw new Error(
+          `test users ${JSON.stringify(already)} and ${JSON.stringify(name)} declare the same e-mail ${JSON.stringify(def.email)}`
+        );
+      }
+      emails.set(lower, name);
+    }
+    users[name] = def;
+  }
+  return { __config: TEST_USERS_CONFIG_KIND, users };
+}
+
 // src/config/flags.ts
 var FLAGS_CONFIG_KIND = "flags";
 var FLAG_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
@@ -465,10 +623,42 @@ function recordThrows(target, fnName, throws) {
   const throwsBuffer = carrier[THROWS_BUFFER];
   if (throwsBuffer) throwsBuffer[fnName] = throws;
 }
+function getRoutes(ctor) {
+  const carrier = carrierOf(ctor);
+  const routes = carrier[ROUTES] ?? [];
+  const returnBuffer = carrier[RETURN_BUFFER];
+  if (returnBuffer) {
+    for (const route of routes) {
+      const buffered = returnBuffer[route.fnName];
+      if (buffered && route.returnSchema === void 0) {
+        route.returnSchema = buffered;
+      }
+    }
+  }
+  const throwsBuffer = carrier[THROWS_BUFFER];
+  if (throwsBuffer) {
+    for (const route of routes) {
+      const buffered = throwsBuffer[route.fnName];
+      if (buffered && route.throws === void 0) {
+        route.throws = buffered;
+      }
+    }
+  }
+  return routes.map((r) => ({
+    ...r,
+    params: r.params.slice(),
+    ...r.throws !== void 0 ? { throws: r.throws.slice() } : {}
+  }));
+}
 
 // src/decorators/methods.ts
 function makeMethodDecorator(method) {
   return function(subpath, options = {}) {
+    if (typeof subpath !== "string") {
+      throw new Error(
+        `@${method[0]}${method.slice(1).toLowerCase()}(subpath) expects a string subpath, got ${typeof subpath}.` + (method === "QUERY" ? " If this is a zod schema on a method parameter: the query-string param decorator was renamed @QueryParams(schema) in @palbase/backend 9.0.0." : "")
+      );
+    }
     return function(target, propertyKey) {
       recordRoute(target, String(propertyKey), method, subpath, options);
     };
@@ -1071,6 +1261,7 @@ export {
   Database,
   Delete,
   Documents,
+  EGRESS_CONFIG_KIND,
   EXTENSION_DEPENDENCIES,
   FLAGS_CONFIG_KIND,
   Flags,
@@ -1101,6 +1292,7 @@ export {
   Resource,
   STORAGE_CONFIG_KIND,
   Storage,
+  TEST_USERS_CONFIG_KIND,
   TooManyRequests,
   TraceId,
   Unauthorized,
@@ -1119,6 +1311,7 @@ export {
   boolean,
   bucket,
   buildProvider,
+  defineEgress,
   defineError,
   defineFlags,
   defineJob,
@@ -1126,12 +1319,14 @@ export {
   defineNotifications,
   defineSchema,
   defineStorage,
+  defineTestUsers,
   defineWebhook,
   defineWorker,
   documents,
   enumType,
   flag,
   getErrorRegistry,
+  getRoutes,
   integer,
   isPalbaseExtension,
   jsonb,
@@ -1144,6 +1339,7 @@ export {
   recordThrows,
   reservedSecretKey,
   storage,
+  testUser,
   text,
   timestamp,
   uuid,