@palbase/backend 10.1.0 → 10.3.0

package/dist/index.d.cts

@@ -1,12 +1,68 @@
-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.cjs';
-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.cjs';
+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-92kVepng.cjs';
+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-92kVepng.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { E as EnvTypedDatabase, S as SchemaDef } from './index-Bt7UHkAM.cjs';
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, f as EnvTables, g as EnvTypedTable, h as EnvTypedTx, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as 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-Bt7UHkAM.cjs';
+import { E as EnvTypedDatabase, S as SchemaDef } from './index-BaHs33jr.cjs';
+export { C as ColumnBuilder, a as ColumnDef, b as ColumnMap, c as ColumnType, d as EXTENSION_DEPENDENCIES, e as EnvServiceDatabase, f as EnvTables, g as EnvTypedTable, h as EnvTypedTx, I as InsertShape, O as OnDeleteAction, P as PALBASE_EXTENSIONS, i as PalbaseExtension, j as PolicyBuilder, k as PolicyCommand, l as PolicyDef, m as PolicyMode, R as 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-BaHs33jr.cjs';
+import { EntitlementKey, LimitKey } from './purchases/keys.cjs';
 import { TableTypes, Tables } from './db/env.cjs';
 import { ZodTypeAny, z } from 'zod';
 export { z } from 'zod';
 
+/**
+ * The purchases surface the decorators need, declared as a NARROW STRUCTURAL
+ * interface rather than an import of `@palstore/purchases`.
+ *
+ * `PurchasesClient` (palstore's `sk_` backend SDK) satisfies this shape as-is,
+ * so the runtime injects the real client with no adapter — but `@palbase/backend`
+ * itself gains no dependency on it. That matters: this package is published
+ * public and baked into the br-pod image from a tarball, so a dependency on an
+ * unpublished sibling would break `npm install palbase-backend.tgz`. It is also
+ * the pattern `withSpend` already uses for the same reason (`SpendCapableClient`
+ * in palstore's own spend.ts: "a narrow structural interface … so this file has
+ * no dependency on client.ts").
+ *
+ * The methods here are a SUBSET of `PurchasesClient` — only what the two
+ * decorators call. Grants, refunds, credits and customer-info reads stay off
+ * this interface: a tenant that wants them imports the palstore SDK directly.
+ */
+/** Store environment a subject is fixed to. Mirrors `StoreEnv` in `@palstore/purchases`. */
+type StoreEnv = "production" | "sandbox";
+/** Quota/credit state carried by a 429. Mirrors `LimitState` in `@palstore/purchases`
+ * (SPEC-purchases-v1 §11) — re-declared, not imported, for the reason above. */
+interface LimitState {
+    key: string;
+    scope: string;
+    window: string;
+    used: number;
+    reserved: number;
+    max: number;
+    remaining: number;
+    resetAt: string;
+}
+/** Options for one spend. `idempotencyKey` is required by the server (§9). */
+interface SpendOptions {
+    /** Defaults to 1. */
+    count?: number;
+    idempotencyKey: string;
+}
+interface PurchasesService {
+    /** Map a tenant-side user reference to its palstore subject, creating one on
+     * first sight. Server-authoritative — the caller never names a subject. */
+    resolveSubject(input: {
+        userRef: string;
+        storeEnv: StoreEnv;
+    }): Promise<{
+        subjectId: string;
+    }>;
+    /** Resolve silently when `entitlementKey` is active for `subjectId`; throw
+     * `EntitlementRequiredError` otherwise. Consumes nothing. */
+    require(subjectId: string, entitlementKey: string): Promise<void>;
+    /** Reserve → run `handler` → commit on success, cancel on throw, always
+     * rethrowing the handler's own error. The whole reason the decorators are a
+     * thin layer: this lifecycle is already written and tested in palstore's SDK. */
+    withSpend<T>(subjectId: string, key: string, opts: SpendOptions, handler: () => Promise<T>): Promise<T>;
+}
+
 /**
  * runtime.ts — request-scoped service singletons.
  *
@@ -66,6 +122,28 @@ interface RuntimeServices {
     Notifications: PalbaseNotificationsClient;
     Flags: PalbaseFlagsClient;
     Realtime: PalbaseRealtimeClient;
+    Purchases: PurchasesService;
+}
+/**
+ * The per-request ALS box.
+ *
+ * `runtime` is the service bundle. `userId` is the request's authenticated user
+ * id, written by the runtime immediately after it assembles the request object
+ * (worker.js: `requestALS.getStore().userId = pbReq.user?.id || null`) and
+ * `null` on an anonymous request. It was already being written there for the
+ * Flags client's auto-bind; declaring it here makes the existing contract typed
+ * instead of implicit, which is what lets `currentSubjectId()` read a
+ * server-owned identity rather than trusting anything the caller sent.
+ */
+interface RequestStore {
+    runtime: RuntimeServices;
+    userId?: string | null;
+    /** This request's id (`req_…`), written by the runtime. Used as the spend
+     * idempotency scope when the caller supplied no `Idempotency-Key`. */
+    requestId?: string;
+    /** The caller's `Idempotency-Key` header, or `null` when absent. What makes a
+     * client's retry replay its first result instead of charging twice. */
+    idempotencyKey?: string | null;
 }
 /**
  * Per-request store. The persistent runtime runs each request inside
@@ -76,9 +154,7 @@ interface RuntimeServices {
  * instance across the one module instance — two ALS instances would silently
  * not see each other's stores. NOT part of the public author-facing API.
  */
-declare const __requestALS: AsyncLocalStorage<{
-    runtime: RuntimeServices;
-}>;
+declare const __requestALS: AsyncLocalStorage<RequestStore>;
 /** Install the live clients in the process-global fallback slot.
  *
  * Persistent-server requests should use {@link __runWithRuntime} instead; this
@@ -129,6 +205,15 @@ declare const Queue: QueueClient;
 declare const Log: Logger;
 /** Push / email / SMS / in-app notifications. */
 declare const Notifications: PalbaseNotificationsClient;
+/**
+ * Palstore purchases (entitlements + quota/credit spend).
+ *
+ * Reached by handlers through the `@RequireEntitlement` / `@Spend` decorators
+ * rather than called directly in the common case; exposed as a singleton for
+ * the cases the decorators deliberately do not cover (a dynamic spend count,
+ * which must run BEFORE the billable side-effect).
+ */
+declare const Purchases: PurchasesService;
 /**
  * Feature flags.
  *
@@ -161,11 +246,120 @@ declare const Flags: PalbaseFlagsClient;
  */
 declare const Realtime: PalbaseRealtimeClient;
 
+/**
+ * `@RequireEntitlement` and `@Spend` — access and metering at the decorator
+ * level, so a controller method says what it costs instead of wiring it.
+ *
+ * TWO decorators, deliberately, because not every subscription is limit-based.
+ * Most products just say "pro users may call this" and consume nothing; a
+ * zero-count spend would express that badly and run the whole reserve/commit
+ * machine for no reason.
+ *
+ *   @RequireEntitlement('pro')   pure gate    → 403, consumes nothing
+ *   @Spend('bookCreate')         consumption  → 429 when exhausted
+ *
+ * ORDER IS FIXED, and not by where you wrote them. Both decorators record
+ * metadata and share ONE installed wrapper that always runs the entitlement
+ * gate before it reserves quota. Reserving for someone who is about to get a
+ * 403 is wasted work and a race window, so the source order of the two
+ * decorators cannot introduce it.
+ */
+
+type MethodDecorator$2 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/**
+ * Require an active entitlement. Answers 403 `entitlement_required` when it is
+ * absent and consumes nothing.
+ *
+ * The key is a member of the generated `EntitlementKey` union, so a typo is a
+ * compile error rather than a gate that silently never matches.
+ */
+declare function RequireEntitlement(key: EntitlementKey): MethodDecorator$2;
+/**
+ * Consume one unit of a limit or credit for the request's subject.
+ *
+ * Reserves before the handler runs and commits only if it returns; a throw
+ * cancels the hold, so a user is never charged for work that did not complete.
+ * Answers 429 `quota_exceeded` (carrying the `LimitState`) when exhausted.
+ *
+ * The count is fixed at 1. A DYNAMIC amount is deliberately not expressible
+ * here: it has to be decided inside the handler and spent BEFORE the billable
+ * side-effect, which is an explicit `Purchases.withSpend(...)` call, not a
+ * decorator.
+ */
+declare function Spend(key: LimitKey): MethodDecorator$2;
+
+/**
+ * keys-gen.ts — generate the `palbase-purchases.d.ts` text from a catalog
+ * manifest.
+ *
+ * The twin of `db/env-gen.ts`: the CLI / deploy pipeline calls
+ * {@link makePurchasesDts} with the project's catalog revision and writes the
+ * result to `palbase-purchases.d.ts` at the project root. That file augments
+ * the `@palbase/backend/purchases` `Entitlements` / `Limits` interfaces, so
+ * `@RequireEntitlement(...)` and `@Spend(...)` accept the project's real keys
+ * and nothing else.
+ *
+ * Same catalog, two languages: this is the TypeScript half of what swiftgen
+ * already emits for iOS. Neither side is hand-maintained, so the two cannot
+ * drift from each other or from the manifest the server validated.
+ *
+ * The emitted file ends in `export {};` — same as `makeEnvDts`. Without it the
+ * `.d.ts` is a global script, and `declare module "…"` there DECLARES an
+ * ambient module (shadowing the real one, so every key silently becomes
+ * invalid) instead of AUGMENTING it.
+ */
+/** A catalog entry that may be tombstoned. */
+interface Removable {
+    removed?: boolean;
+}
+/**
+ * The slice of `pur_catalogs.manifest` this generator reads. Deliberately
+ * partial and permissive: the server already validated the manifest (its models
+ * are `extra="forbid"`), so re-checking here would be a second, weaker copy of
+ * that authority.
+ */
+interface PurchasesManifest {
+    limits?: Record<string, Removable>;
+    credits?: Record<string, Removable>;
+    entitlements?: Record<string, Removable>;
+}
+/**
+ * Render the project's `palbase-purchases.d.ts`.
+ *
+ * `Limits` carries BOTH limits and credits: `@Spend` consumes either, and the
+ * server answers both with a 429 (`quota_exceeded` / `credit_insufficient`), so
+ * splitting them into two unions would make the author pick the right decorator
+ * for a distinction the spend path does not make.
+ */
+declare function makePurchasesDts(manifest: PurchasesManifest): string;
+
+/**
+ * Per-method purchases metadata, stored on the controller class the same way
+ * `decorators/registry.ts` stores routes: a symbol-keyed static, plain data, no
+ * `reflect-metadata`.
+ *
+ * Its only consumer is the OpenAPI step, which needs to know that a route is
+ * gated (declare 403) or metered (declare 429) so the iOS client codegen emits
+ * TYPED errors instead of a bare status number. Enforcement does NOT read this
+ * — the decorators wrap the method directly — so a stale registry can never
+ * cause a missed gate.
+ */
+
+/** What `@Spend` recorded for one method. */
+interface SpendMeta {
+    key: LimitKey;
+    count: number;
+}
+/** The entitlement `fnName` is gated on, or undefined when it is not gated. */
+declare function entitlementFor(ctor: object, fnName: string): EntitlementKey | undefined;
+/** What `fnName` spends, or undefined when it spends nothing. */
+declare function spendFor(ctor: object, fnName: string): SpendMeta | undefined;
+
 /**
  * env-gen.ts — generate the `palbase-env.d.ts` text from a `defineSchema()`
  * result.
  *
- * The CLI (`palbase serve` / codegen) and the deploy pipeline call
+ * The CLI (`palbase db types` / codegen) and the deploy pipeline call
  * {@link makeEnvDts} with the project's schema and write the returned string to
  * `palbase-env.d.ts` at the project root. That file AUGMENTS the
  * `@palbase/backend/env` `Tables` interface (controlled global augmentation,
@@ -808,6 +1002,7 @@ declare function defineTestUsers(input: TestUsersInput): TestUsersConfig;
  *     new_dashboard: flag({ type: "boolean", default: false, description: "Roll out the new dashboard" }),
  *     max_uploads:   flag({ type: "number",  default: 10 }),
  *     theme:         flag({ type: "string",  default: "light", variants: ["light", "dark", "system"] }),
+ *     limits:        flag({ type: "json",    default: { daily: 10, burst: 50 } }),
  *   },
  * });
  *
@@ -816,47 +1011,80 @@ declare function defineTestUsers(input: TestUsersInput): TestUsersConfig;
  *   { __config: "flags", flags: { <key>: { type, default, variants, description }, ... } }
  * `variants` is the allowed-values list for a string flag, or `null` (any
  * string). `description` is the doc string, or `null`. The apply step maps the
- * author-facing `type` ("boolean") to PalFlags' `value_type` ("bool").
+ * author-facing `type` to PalFlags' `value_type`: "boolean" → "bool" and
+ * "json" → "object"; "number"/"string" pass through.
  */
 /** The `__config` discriminant the eval/apply reads to confirm a config/*.ts is
  * a flags config. Flags is `"flags"`. */
 declare const FLAGS_CONFIG_KIND: "flags";
 /**
  * A flag's type. The author-facing vocabulary is `"boolean" | "number" |
- * "string"`. (The br-pod maps `"boolean"` to PalFlags' `value_type: "bool"` on
- * apply — the SDK keeps the JS-natural `"boolean"` so the DSL reads cleanly.)
+ * "string" | "json"`; the apply step maps it to PalFlags' `value_type` enum —
+ * `"boolean"` → `"bool"`, `"json"` → `"object"`, the other two pass through. The
+ * SDK keeps the JS-natural names so the DSL reads cleanly.
  *
- * PalFlags also supports an `object` value type, but config-as-code flags are
- * deliberately scoped to the three SCALAR types — an object default is awkward
- * to author on the CLI and rare for a feature flag, so it is intentionally
- * omitted here (set an object flag via the Studio / API directly if needed).
+ * `"json"` is a structured (object) flag. It is named for what an author types —
+ * a JSON object literal — and matches the `--type json` the CLI's per-user
+ * override commands already use for this same server type.
+ */
+type FlagType = "boolean" | "number" | "string" | "json";
+/** Any value expressible in JSON — what may appear INSIDE a `"json"` flag's default. */
+type FlagJsonValue = boolean | number | string | null | FlagJsonValue[] | {
+    [key: string]: FlagJsonValue;
+};
+/**
+ * The default of a `"json"` flag: a JSON OBJECT. Not an array and not a scalar —
+ * PalFlags' `object` value type accepts a JSON object at the top level only
+ * (`validate.ValidateValueTypeMatch`), and it caps nesting depth at 3.
  */
-type FlagType = "boolean" | "number" | "string";
+type FlagJsonObject = {
+    [key: string]: FlagJsonValue;
+};
 /** The runtime JSON value a flag's `default` may hold (matches {@link FlagType}). */
-type FlagValue = boolean | number | string;
+type FlagValue = boolean | number | string | FlagJsonObject;
 /**
- * The author-facing options for a single flag.
+ * The author-facing options for a single flag — a UNION keyed on `type`, so
+ * `default` is checked against the declared type at compile time and `variants`
+ * is only accepted where it means something.
  *
- * - `type`: the flag's type — `"boolean" | "number" | "string"`.
+ * - `type`: the flag's type — `"boolean" | "number" | "string" | "json"`.
  * - `default`: the project-wide default value. MUST match `type` (a `number`
- *   default with `type: "boolean"` throws).
+ *   default with `type: "boolean"` is a type error, and throws at runtime).
  * - `variants`: ONLY valid for `type: "string"` — the allowed values the string
  *   flag may take (a DEFINITION, not a per-user assignment). When given, the
- *   `default` MUST be one of the variants. Supplying `variants` on a non-string
- *   type throws.
+ *   `default` MUST be one of the variants. Supplying `variants` on any other
+ *   type is a type error, and throws at runtime. (PalFlags rejects variants for
+ *   every non-string `value_type`, so accepting them here would only produce a
+ *   config the server refuses.)
  * - `description`: an optional human description of what the flag controls.
  */
-interface FlagOptions {
-    type: FlagType;
-    default: FlagValue;
+type FlagOptions = {
+    type: "boolean";
+    default: boolean;
+    variants?: never;
+    description?: string;
+} | {
+    type: "number";
+    default: number;
+    variants?: never;
+    description?: string;
+} | {
+    type: "string";
+    default: string;
     variants?: string[];
     description?: string;
-}
+} | {
+    type: "json";
+    default: FlagJsonObject;
+    variants?: never;
+    description?: string;
+};
 /**
  * The compiled, serializable flag definition — the EXACT shape emitted to JSON
  * and consumed by the Go apply step.
  *
- * - `type`: the author-facing type verbatim (`"boolean" | "number" | "string"`).
+ * - `type`: the author-facing type verbatim (`"boolean" | "number" | "string" |
+ *   "json"`) — the apply step maps it to PalFlags' `value_type`.
  * - `default`: the default value (matches `type`).
  * - `variants`: the allowed-values list for a string flag, or `null` (any).
  * - `description`: the doc string, or `null`.
@@ -885,12 +1113,12 @@ interface FlagsInput {
  * options.
  *
  * Validates eagerly (at config-author time):
- *  - `type` is one of `"boolean" | "number" | "string"`.
+ *  - `type` is one of `"boolean" | "number" | "string" | "json"`.
  *  - `default` matches `type` (e.g. a `number` default with `type: "boolean"`
- *    throws).
- *  - `variants` is ONLY allowed for a string flag (variants on a non-string
- *    type throws); each entry is a non-empty string; the `default` must be one
- *    of the variants.
+ *    throws; a `"json"` default must be a plain object, not an array or scalar).
+ *  - `variants` is ONLY allowed for a string flag (variants on any other type
+ *    throws); each entry is a non-empty string; the `default` must be one of the
+ *    variants.
  *
  * Returns a normalized {@link FlagDef}: `variants` deduped-or-null,
  * `description` trimmed-or-null.
@@ -1620,4 +1848,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, 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 };
+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, EntitlementKey, type EnvSecretRef, EnvTypedDatabase, FLAGS_CONFIG_KIND, type FcmOptions, type FileDeletedEvent, type FileUploadedEvent, type FlagDef, type FlagJsonObject, type FlagJsonValue, type FlagOptions, type FlagType, type FlagValue, Flags, type FlagsConfig, type FlagsInput, Get, Headers, type HookHandler, type HookMeta, HttpError, type HttpMethodUpper, type JobConfig, type JobMeta, LimitKey, type LimitState, 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, Purchases, type PurchasesManifest, type PurchasesService, Put, Query, QueryParams, Queue, QueueClient, RESERVED_SECRET_PREFIX, RateLimitConfig, Realtime, type RegisteredError, Req, RequestId, type RequestStore, RequireEntitlement, 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, Spend, type SpendMeta, type SpendOptions, Storage, type StorageConfig, type StorageInput, type StoreEnv, 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, entitlementFor, flag, getErrorRegistry, getRoutes, makeEnvDts, makePurchasesDts, parseFileSizeLimit, recordThrows, reservedSecretKey, spendFor, storage, testUser, validateUploadAgainstStorage };