@palbase/backend 4.0.0 → 5.1.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { C as CacheClient, b as PalbaseDocsClient, c as PalbaseFlagsClient, L as Logger, d as PalbaseNotificationsClient, Q as QueueClient, D as DBClient, e as PalbaseStorageClient, A as AuthSpec, R as RateLimitConfig, U as User$1 } from './endpoint-2d_DpASt.cjs';
-export { f as AuthConfig, B as BadRequest, g as ClientInfo, h as Conflict, i as DBOps, E as ErrorDef, j as ErrorMap, k as ErrorThrowers, F as FileContext, l as Forbidden, H as HttpError, m as HttpMethod, M as Middleware, n as MiddlewareContext, o as MiddlewareHandler, N as NotFound, P as PBRequest, p as PalError, q as PalbaseAnalyticsClient, r as PalbaseAnalyticsManagementNamespace, s as PalbaseAnalyticsProperties, t as PalbaseAnalyticsQueryNamespace, u as PalbaseAttestAndroidParams, v as PalbaseAttestAndroidResult, w as PalbaseAttestiOSParams, x as PalbaseAttestiOSResult, y as PalbaseAuthClient, z as PalbaseBindDeviceParams, G as PalbaseBucketClient, I as PalbaseCmsClient, J as PalbaseCmsFindOneOptions, K as PalbaseCmsFindOptions, O as PalbaseCohortQueryInput, S as PalbaseCohortResult, T as PalbaseCollectionRef, V as PalbaseCountQueryInput, W as PalbaseCountResult, X as PalbaseCreateLinkParams, Y as PalbaseDeviceInfo, Z as PalbaseDeviceTokenView, _ as PalbaseDocumentRef, $ as PalbaseDocumentSnapshot, a0 as PalbaseEmailClient, a1 as PalbaseEmailSendParams, a2 as PalbaseEmailSendResponse, a3 as PalbaseEventNamesResult, a4 as PalbaseEventsQueryInput, a5 as PalbaseEventsResult, a6 as PalbaseFileObject, a7 as PalbaseFlag, a8 as PalbaseFlagContext, a9 as PalbaseFlagVariant, aa as PalbaseFunctionsClient, ab as PalbaseFunnelQueryInput, ac as PalbaseFunnelResult, ad as PalbaseIdentifyTraits, ae as PalbaseInboxClient, af as PalbaseInboxListOptions, ag as PalbaseInboxListResult, ah as PalbaseInboxMessage, ai as PalbaseInboxSendParams, aj as PalbaseInboxSendResponse, ak as PalbaseInitialLink, al as PalbaseInvokeOptions, am as PalbaseLink, an as PalbaseLinkAnalytics, ao as PalbaseLinkDetails, ap as PalbaseLinksClient, aq as PalbaseListLinksOptions, ar as PalbaseListLinksResult, as as PalbaseListOptions, at as PalbaseMatchParams, au as PalbaseMultiChannelResponse, av as PalbaseOverviewResult, aw as PalbasePreferences, ax as PalbasePreferencesClient, ay as PalbasePublicUrlResponse, az as PalbasePushClient, aA as PalbasePushSendParams, aB as PalbasePushSendResponse, aC as PalbaseQrCodeOptions, aD as PalbaseQuerySnapshot, aE as PalbaseRealtimeChannel, aF as PalbaseRealtimeClient, aG as PalbaseRealtimeMessage, aH as PalbaseRegisterDeviceParams, aI as PalbaseResult, aJ as PalbaseRetentionQueryInput, aK as PalbaseRetentionResult, aL as PalbaseSession, aM as PalbaseSignedUrlResponse, aN as PalbaseSmsClient, aO as PalbaseSmsSendParams, aP as PalbaseSmsSendResponse, aQ as PalbaseTransformOptions, aR as PalbaseUpdateLinkParams, aS as PalbaseUploadOptions, aT as PalbaseUser, aU as PalbaseUserDetailResult, aV as PalbaseUsersQueryInput, aW as PalbaseUsersResult, aX as PalbaseVerifyRequestSignatureParams, aY as PalbaseWhereOperator, aZ as TooManyRequests, a_ as TxClient, a$ as Unauthorized, b0 as defineMiddleware } from './endpoint-2d_DpASt.cjs';
+import { C as CacheClient, b as PalbaseDocsClient, c as PalbaseFlagsClient, L as Logger, d as PalbaseNotificationsClient, Q as QueueClient, D as DBClient, e as PalbaseStorageClient, A as AuthSpec, R as RateLimitConfig, U as User$1 } from './endpoint-BEHjfvFH.cjs';
+export { f as AuthConfig, B as BadRequest, g as ClientInfo, h as Conflict, i as DBOps, E as ErrorDef, j as ErrorMap, k as ErrorThrowers, F as FileContext, l as Forbidden, H as HttpError, m as HttpMethod, M as Middleware, n as MiddlewareContext, o as MiddlewareHandler, N as NotFound, P as PBRequest, p as PalError, q as PalbaseAnalyticsClient, r as PalbaseAnalyticsManagementNamespace, s as PalbaseAnalyticsProperties, t as PalbaseAnalyticsQueryNamespace, u as PalbaseAttestAndroidParams, v as PalbaseAttestAndroidResult, w as PalbaseAttestiOSParams, x as PalbaseAttestiOSResult, y as PalbaseAuthClient, z as PalbaseBindDeviceParams, G as PalbaseBucketClient, I as PalbaseCmsClient, J as PalbaseCmsFindOneOptions, K as PalbaseCmsFindOptions, O as PalbaseCohortQueryInput, S as PalbaseCohortResult, T as PalbaseCollectionRef, V as PalbaseCountQueryInput, W as PalbaseCountResult, X as PalbaseCreateLinkParams, Y as PalbaseDeviceInfo, Z as PalbaseDeviceTokenView, _ as PalbaseDocumentRef, $ as PalbaseDocumentSnapshot, a0 as PalbaseEmailClient, a1 as PalbaseEmailSendParams, a2 as PalbaseEmailSendResponse, a3 as PalbaseEventNamesResult, a4 as PalbaseEventsQueryInput, a5 as PalbaseEventsResult, a6 as PalbaseFileObject, a7 as PalbaseFlag, a8 as PalbaseFlagContext, a9 as PalbaseFlagVariant, aa as PalbaseFunctionsClient, ab as PalbaseFunnelQueryInput, ac as PalbaseFunnelResult, ad as PalbaseIdentifyTraits, ae as PalbaseInboxClient, af as PalbaseInboxListOptions, ag as PalbaseInboxListResult, ah as PalbaseInboxMessage, ai as PalbaseInboxSendParams, aj as PalbaseInboxSendResponse, ak as PalbaseInitialLink, al as PalbaseInvokeOptions, am as PalbaseLink, an as PalbaseLinkAnalytics, ao as PalbaseLinkDetails, ap as PalbaseLinksClient, aq as PalbaseListLinksOptions, ar as PalbaseListLinksResult, as as PalbaseListOptions, at as PalbaseMatchParams, au as PalbaseMultiChannelResponse, av as PalbaseOverviewResult, aw as PalbasePreferences, ax as PalbasePreferencesClient, ay as PalbasePublicUrlResponse, az as PalbasePushClient, aA as PalbasePushSendParams, aB as PalbasePushSendResponse, aC as PalbaseQrCodeOptions, aD as PalbaseQuerySnapshot, aE as PalbaseRealtimeChannel, aF as PalbaseRealtimeClient, aG as PalbaseRealtimeMessage, aH as PalbaseRegisterDeviceParams, aI as PalbaseResult, aJ as PalbaseRetentionQueryInput, aK as PalbaseRetentionResult, aL as PalbaseSession, aM as PalbaseSignedUrlResponse, aN as PalbaseSmsClient, aO as PalbaseSmsSendParams, aP as PalbaseSmsSendResponse, aQ as PalbaseTransformOptions, aR as PalbaseUpdateLinkParams, aS as PalbaseUploadOptions, aT as PalbaseUser, aU as PalbaseUserDetailResult, aV as PalbaseUsersQueryInput, aW as PalbaseUsersResult, aX as PalbaseVerifyRequestSignatureParams, aY as PalbaseWhereOperator, aZ as TooManyRequests, a_ as TxClient, a$ as Unauthorized, b0 as defineMiddleware } from './endpoint-BEHjfvFH.cjs';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { E as EnvTypedDatabase, S as SchemaDef } from './index-DzRFS3Tl.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 RowShape, n as SchemaInput, T as TableDef, o as TableInput, p as TypedDB, q as TypedTable, r as TypedTx, s as boolean, t as defineSchema, u as enumType, v as integer, w as isPalbaseExtension, x as jsonb, y as makeTypedDB, z as policy, A as text, B as timestamp, D as uuid } from './index-DzRFS3Tl.cjs';
+import { E as EnvTypedDatabase, S as SchemaDef } from './index-mr3Co63T.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 RowShape, n as SchemaInput, T as TableDef, o as TableInput, p as TypedDB, q as TypedTable, r as TypedTx, s as boolean, t as defineSchema, u as enumType, v as integer, w as isPalbaseExtension, x as jsonb, y as makeTypedDB, z as policy, A as text, B as timestamp, D as uuid } from './index-mr3Co63T.cjs';
 export { TableTypes, Tables } from './db/env.cjs';
 import { ZodTypeAny } from 'zod';
 export { z } from 'zod';
@@ -154,6 +154,503 @@ declare const Flags: PalbaseFlagsClient;
  */
 declare function makeEnvDts(schema: SchemaDef): string;
 
+/**
+ * storage.ts — the storage-buckets config-as-code DSL.
+ *
+ * `defineStorage({ buckets })` is the first MODULE config-as-code surface (the
+ * sibling of `db/schema.ts`'s `defineSchema`). A `config/storage.ts` file
+ * default-exports a `defineStorage(...)` result; on deploy the br-pod evaluates
+ * it to JSON and reconciles the declared buckets against the tenant's live
+ * buckets via the Storage admin API (create missing, update changed; never
+ * auto-delete — dropping a bucket is destructive and warned only).
+ *
+ * Buckets are DECLARATIVE: name + access + size/mime limits. The FILES inside a
+ * bucket are runtime state (uploaded via the SDK), never in git.
+ *
+ * @example
+ * import { defineStorage, bucket } from "@palbase/backend";
+ *
+ * export default defineStorage({
+ *   buckets: {
+ *     avatars: bucket({
+ *       public: true,
+ *       fileSizeLimit: "5MB",
+ *       allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
+ *     }),
+ *     invoices: bucket({
+ *       public: false,
+ *       fileSizeLimit: "20MB",
+ *       allowedMimeTypes: ["application/pdf"],
+ *     }),
+ *   },
+ * });
+ *
+ * The returned value is the EXACT JSON shape the runtime's generic config
+ * extractor (`config_extract.js`) emits and the Go apply step parses:
+ *   { __config: "storage", buckets: { avatars: { public, fileSizeLimit, allowedMimeTypes }, ... } }
+ * `fileSizeLimit` is always normalized to a number of bytes (or null when
+ * omitted, meaning "no limit"); the apply step maps it to the Storage API's
+ * `file_size_limit` field. `allowedMimeTypes` is the allowlist or null (any).
+ */
+/** The discriminant written under `__config` so the eval/apply can tell which
+ * module config a `config/*.ts` file describes. Storage is `"storage"`. */
+declare const STORAGE_CONFIG_KIND: "storage";
+/**
+ * The author-facing options for a single bucket.
+ *
+ * - `public`: when true the bucket is served without a signed URL. Defaults to
+ *   `false` (private — signed URLs only).
+ * - `fileSizeLimit`: the per-object upload cap. Accepts a human string
+ *   (`"5MB"`, `"20MB"`, `"1GB"`) or a bare number of BYTES. Omit for no limit.
+ * - `allowedMimeTypes`: an allowlist of MIME types accepted on upload. Omit to
+ *   allow any type. Each entry must look like `type/subtype` (e.g. `image/png`,
+ *   `application/pdf`, or a wildcard `image/*`).
+ */
+interface BucketOptions {
+    public?: boolean;
+    fileSizeLimit?: string | number;
+    allowedMimeTypes?: string[];
+}
+/**
+ * The compiled, serializable bucket definition — the EXACT shape emitted to
+ * JSON and consumed by the Go apply step.
+ *
+ * - `public`: always present (defaulted to `false`).
+ * - `fileSizeLimit`: bytes as a number, or `null` for "no limit".
+ * - `allowedMimeTypes`: the MIME allowlist, or `null` for "any type".
+ */
+interface BucketDef {
+    public: boolean;
+    fileSizeLimit: number | null;
+    allowedMimeTypes: string[] | null;
+}
+/** A storage config definition: the discriminant + a map of bucket name →
+ * {@link BucketDef}. This is the value `defineStorage` returns and the runtime
+ * config extractor serializes. */
+interface StorageConfig {
+    __config: typeof STORAGE_CONFIG_KIND;
+    buckets: Record<string, BucketDef>;
+}
+/** The author-facing input to `defineStorage`: a `buckets` map whose keys are
+ * the bucket names and whose values are `bucket({...})` builders. */
+interface StorageInput {
+    buckets: Record<string, BucketDef>;
+}
+/**
+ * Parse a `fileSizeLimit` into a number of bytes.
+ *
+ * - A bare number is taken as bytes verbatim (must be a non-negative integer).
+ * - A string is `<number><unit>` (e.g. `"5MB"`, `"1.5GB"`, `"500kb"`); the unit
+ *   is case-insensitive and optional (a bare numeric string = bytes). Binary
+ *   units (1 MB = 1024 squared bytes) to match the Storage module's parser.
+ *
+ * Throws on a negative value, a non-finite number, or an unrecognized unit so a
+ * bad limit fails at config-author time, not silently at deploy.
+ */
+declare function parseFileSizeLimit(input: string | number): number;
+/**
+ * Define a single bucket. The bucket NAME is supplied by the key in
+ * `defineStorage({ buckets: { <name>: bucket({...}) } })`, so `bucket()` takes
+ * only the options.
+ *
+ * Validates eagerly (at config-author time):
+ *  - `fileSizeLimit` parses to a valid non-negative byte count.
+ *  - each `allowedMimeTypes` entry is a `type/subtype` MIME string.
+ *
+ * Returns a normalized {@link BucketDef}: `public` defaulted to `false`,
+ * `fileSizeLimit` as bytes-or-null, `allowedMimeTypes` deduped-or-null.
+ */
+declare function bucket(opts?: BucketOptions): BucketDef;
+/**
+ * Define the storage config for a project. The bucket NAME comes from each
+ * object key (authors never repeat the name). Returns the discriminated
+ * {@link StorageConfig} the runtime config extractor serializes and the Go
+ * apply step reconciles.
+ *
+ * @example
+ * export default defineStorage({
+ *   buckets: { avatars: bucket({ public: true, fileSizeLimit: "5MB" }) },
+ * });
+ */
+declare function defineStorage(input: StorageInput): StorageConfig;
+
+/**
+ * notifications.ts — the notification-providers config-as-code DSL.
+ *
+ * `defineNotifications({ push, email, sms })` is the second MODULE config-as-code
+ * surface (the sibling of `config/storage.ts`'s `defineStorage`). A
+ * `config/notifications.ts` file default-exports a `defineNotifications(...)`
+ * result; on deploy the br-pod evaluates it to JSON and reconciles the declared
+ * providers against the tenant's live providers via the PalNotify admin API
+ * (create missing; never auto-delete — dropping a provider is destructive and
+ * warned only).
+ *
+ * SECRETS ARE NEVER IN THE FILE. Each provider's NON-SECRET fields (team id, key
+ * id, bundle id, region, host, port, from address, account sid, …) are literals
+ * in the config. Each provider's SECRET material (the APNs .p8 key, the FCM
+ * service-account JSON, an api_key, an auth token, the SMTP/ACS password, …) is
+ * NOT a field here — it is bound BY CONVENTION to a RESERVED encrypted env var
+ * and resolved at deploy from control-pg. The env-key convention is:
+ *
+ *     PB_NOTIFICATIONS_<PROVIDER>_<FIELD>      (UPPER_SNAKE_CASE)
+ *
+ * e.g. `PB_NOTIFICATIONS_APNS_P8`, `PB_NOTIFICATIONS_FCM_SERVICE_ACCOUNT`,
+ * `PB_NOTIFICATIONS_TWILIO_AUTH_TOKEN`. The `PB_` namespace is reserved (the CLI
+ * refuses a hand-set `palbase secret set PB_*`); the CLI's `palbase notifications
+ * add <provider>` derives the key and uploads the secret for you, so an author
+ * never types either the secret or the env-key name into git.
+ *
+ * @example
+ * import { defineNotifications } from "@palbase/backend";
+ *
+ * export default defineNotifications({
+ *   push: {
+ *     apns: { enabled: true, teamId: "ABCDE12345", keyId: "KEY1234567", bundleId: "com.acme.app" },
+ *     fcm:  { enabled: true },
+ *   },
+ *   email: {
+ *     sendgrid: { enabled: true, fromDomain: "mail.acme.com" },
+ *   },
+ *   sms: {
+ *     twilio: { enabled: true, accountSid: "ACxxxxxxxx", messagingServiceSid: "MGxxxxxxxx" },
+ *   },
+ * });
+ *
+ * The returned value is the EXACT JSON shape the runtime's generic config
+ * extractor (`config_extract.js`) emits and the Go apply step parses:
+ *   { __config: "notifications", push: {...}, email: {...}, sms: {...} }
+ * Only ENABLED providers carry their non-secret fields; a disabled (or absent)
+ * provider serializes as `{ enabled: false }` so the apply step skips it.
+ */
+/** The `__config` discriminant the eval/apply reads to confirm a config/*.ts is
+ * a notifications config. Notifications is `"notifications"`. */
+declare const NOTIFICATIONS_CONFIG_KIND: "notifications";
+/** The reserved env-var prefix that backs provider secrets. A `palbase secret
+ * set` of a key under this prefix is REFUSED by the CLI (it is managed by
+ * `palbase notifications add`). Both the CLI and the br-pod apply step derive a
+ * provider's secret env key as `${RESERVED_SECRET_PREFIX}_<PROVIDER>_<FIELD>`. */
+declare const RESERVED_SECRET_PREFIX: "PB_NOTIFICATIONS";
+/** One provider's catalog entry: which non-secret fields are required, which are
+ * optional, and which secret field-name(s) bind to reserved env vars. */
+interface ProviderCatalogEntry {
+    /** The channel this provider serves (`push` | `email` | `sms`). */
+    readonly channel: "push" | "email" | "sms";
+    /** Non-secret config fields the author MUST supply (validated eagerly). */
+    readonly required: readonly string[];
+    /** Non-secret config fields the author MAY supply. */
+    readonly optional: readonly string[];
+    /** Secret field name(s) — each backed by `PB_NOTIFICATIONS_<PROVIDER>_<FIELD>`
+     * (FIELD is the UPPER_SNAKE of the name here). NOT a config field. */
+    readonly secrets: readonly string[];
+}
+/**
+ * The provider catalog: provider key → fields. The non-secret field names are
+ * the camelCase keys an author writes in `config/notifications.ts`; the secret
+ * names are the snake-ish tokens that become the reserved env-var suffix.
+ *
+ * apns:     team_id / key_id / bundle_id (+ optional is_production); secret = p8.
+ * fcm:      no non-secret fields; secret = service_account (the full JSON).
+ * sendgrid: from_domain; secret = api_key.
+ * ses:      region / from_domain / access_key_id; secret = secret_access_key.
+ * smtp:     host / port / from_email (+ optional username, use_starttls); secret = password.
+ * acs:      from_email (+ optional from_name); secret = connection_string.
+ * twilio:   account_sid + (from_number OR messaging_service_sid); secret = auth_token.
+ */
+declare const PROVIDER_CATALOG: {
+    readonly apns: {
+        readonly channel: "push";
+        readonly required: readonly ["teamId", "keyId", "bundleId"];
+        readonly optional: readonly ["isProduction"];
+        readonly secrets: readonly ["p8"];
+    };
+    readonly fcm: {
+        readonly channel: "push";
+        readonly required: readonly [];
+        readonly optional: readonly [];
+        readonly secrets: readonly ["serviceAccount"];
+    };
+    readonly sendgrid: {
+        readonly channel: "email";
+        readonly required: readonly ["fromDomain"];
+        readonly optional: readonly [];
+        readonly secrets: readonly ["apiKey"];
+    };
+    readonly ses: {
+        readonly channel: "email";
+        readonly required: readonly ["region", "accessKeyId", "fromDomain"];
+        readonly optional: readonly [];
+        readonly secrets: readonly ["secretAccessKey"];
+    };
+    readonly smtp: {
+        readonly channel: "email";
+        readonly required: readonly ["host", "port", "fromEmail"];
+        readonly optional: readonly ["username", "useStarttls"];
+        readonly secrets: readonly ["password"];
+    };
+    readonly acs: {
+        readonly channel: "email";
+        readonly required: readonly ["fromEmail"];
+        readonly optional: readonly ["fromName"];
+        readonly secrets: readonly ["connectionString"];
+    };
+    readonly twilio: {
+        readonly channel: "sms";
+        readonly required: readonly ["accountSid"];
+        readonly optional: readonly ["fromNumber", "messagingServiceSid"];
+        readonly secrets: readonly ["authToken"];
+    };
+};
+/** A provider key (`"apns" | "fcm" | "sendgrid" | …`). */
+type ProviderName = keyof typeof PROVIDER_CATALOG;
+/** APNs (Apple Push) — non-secret fields. The `.p8` key is the reserved secret
+ * `PB_NOTIFICATIONS_APNS_P8` (uploaded via `palbase notifications add apns`). */
+interface ApnsOptions {
+    enabled?: boolean;
+    teamId: string;
+    keyId: string;
+    bundleId: string;
+    /** APNs production gateway vs sandbox. Defaults to true (production). */
+    isProduction?: boolean;
+}
+/** FCM (Firebase Cloud Messaging) — no non-secret fields; the service-account
+ * JSON is the reserved secret `PB_NOTIFICATIONS_FCM_SERVICE_ACCOUNT`. */
+interface FcmOptions {
+    enabled?: boolean;
+}
+/** SendGrid email — non-secret `fromDomain`; api_key is the reserved secret. */
+interface SendgridOptions {
+    enabled?: boolean;
+    fromDomain: string;
+}
+/** Amazon SES email — secret_access_key is the reserved secret. */
+interface SesOptions {
+    enabled?: boolean;
+    region: string;
+    accessKeyId: string;
+    fromDomain: string;
+}
+/** SMTP email — password is the reserved secret. */
+interface SmtpOptions {
+    enabled?: boolean;
+    host: string;
+    port: number;
+    fromEmail: string;
+    username?: string;
+    useStarttls?: boolean;
+}
+/** Azure Communication Services email — connection_string is the reserved secret. */
+interface AcsOptions {
+    enabled?: boolean;
+    fromEmail: string;
+    fromName?: string;
+}
+/** Twilio SMS — auth_token is the reserved secret. Exactly one of `fromNumber`
+ * or `messagingServiceSid` must be supplied. */
+interface TwilioOptions {
+    enabled?: boolean;
+    accountSid: string;
+    fromNumber?: string;
+    messagingServiceSid?: string;
+}
+/** The union of every provider's author-facing options. `buildProvider` accepts
+ * this so each provider's typed options pass without a cast. */
+type ProviderOptions = ApnsOptions | FcmOptions | SendgridOptions | SesOptions | SmtpOptions | AcsOptions | TwilioOptions;
+/** The author-facing input to `defineNotifications`. Every provider + every
+ * channel is optional — declare only what you use. */
+interface NotificationsInput {
+    push?: {
+        apns?: ApnsOptions;
+        fcm?: FcmOptions;
+    };
+    email?: {
+        sendgrid?: SendgridOptions;
+        ses?: SesOptions;
+        smtp?: SmtpOptions;
+        acs?: AcsOptions;
+    };
+    sms?: {
+        twilio?: TwilioOptions;
+    };
+}
+/** A compiled provider def. `enabled` is always present; the remaining keys are
+ * the provider's non-secret fields (verbatim from the catalog). A disabled
+ * provider is `{ enabled: false }` with no other fields. */
+type ProviderDef = {
+    enabled: boolean;
+} & Record<string, unknown>;
+/** The compiled notifications config — the discriminant + per-channel maps of
+ * provider name → {@link ProviderDef}. This is what `defineNotifications`
+ * returns and the runtime extractor serializes. */
+interface NotificationsConfig {
+    __config: typeof NOTIFICATIONS_CONFIG_KIND;
+    push: Record<string, ProviderDef>;
+    email: Record<string, ProviderDef>;
+    sms: Record<string, ProviderDef>;
+}
+/**
+ * Compile + validate one provider's author options into a {@link ProviderDef}.
+ *
+ * - A provider with `enabled === false` (or omitted) compiles to `{ enabled:
+ *   false }` and its required fields are NOT enforced (you can declare a disabled
+ *   provider as a placeholder without filling it in).
+ * - An ENABLED provider must supply every `required` non-secret field from the
+ *   catalog; a missing one throws at config-author time (not silently at deploy).
+ * - Only the catalog's non-secret fields (required + optional) are copied into
+ *   the def — an unknown extra key is ignored (it would have no effect on the
+ *   live provider). Secrets are never read here.
+ */
+declare function buildProvider(name: ProviderName, opts: ProviderOptions): ProviderDef;
+/**
+ * Define the notification-provider config for a project. Returns the
+ * discriminated {@link NotificationsConfig} the runtime config extractor
+ * serializes and the Go apply step reconciles. Validates eagerly: an enabled
+ * provider missing a required non-secret field throws here (config-author time),
+ * not at deploy.
+ *
+ * @example
+ * export default defineNotifications({
+ *   push: { apns: { enabled: true, teamId: "T", keyId: "K", bundleId: "com.x" } },
+ * });
+ */
+declare function defineNotifications(input: NotificationsInput): NotificationsConfig;
+/**
+ * Derive the RESERVED env-var key that backs a provider's secret field, e.g.
+ * `reservedSecretKey("apns", "p8")` → `"PB_NOTIFICATIONS_APNS_P8"`. The CLI uses
+ * this to upload the secret and the br-pod apply step uses the same derivation
+ * to resolve it — they never hand-type the key, so they cannot drift.
+ */
+declare function reservedSecretKey(provider: ProviderName, secretField: string): string;
+
+/**
+ * flags.ts — the feature-flag-definitions config-as-code DSL.
+ *
+ * `defineFlags({ flags })` is the third MODULE config-as-code surface (a sibling
+ * of `config/storage.ts`'s `defineStorage` and `config/notifications.ts`'s
+ * `defineNotifications`). A `config/flags.ts` file default-exports a
+ * `defineFlags(...)` result; on deploy the br-pod evaluates it to JSON and
+ * UPSERTS the declared flag DEFINITIONS into PalFlags (the user-flags module's
+ * system-flags admin API) — create-or-update, idempotent. A live flag NOT in
+ * config is NEVER auto-deleted (an orphan flag is harmless; upsert-only).
+ *
+ * Flags are DECLARATIVE: a flag is a typed project-wide DEFAULT (its key, type,
+ * default value, an optional description, and — for string flags — an optional
+ * list of allowed `variants`). The VALUE of a flag for a specific USER (a
+ * per-user override / A-B assignment) is runtime state set via the SDK, NEVER in
+ * git. `variants` here is part of the DEFINITION (the allowed values a string
+ * flag may take), not a per-user assignment.
+ *
+ * NO SECRETS. Unlike notifications, a flag carries no credentials — this is the
+ * simplest module config (pure declarative data).
+ *
+ * @example
+ * import { defineFlags, flag } from "@palbase/backend";
+ *
+ * export default defineFlags({
+ *   flags: {
+ *     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"] }),
+ *   },
+ * });
+ *
+ * The returned value is the EXACT JSON shape the runtime's generic config
+ * extractor (`config_extract.js`) emits and the Go apply step parses:
+ *   { __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").
+ */
+/** 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.)
+ *
+ * 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).
+ */
+type FlagType = "boolean" | "number" | "string";
+/** The runtime JSON value a flag's `default` may hold (matches {@link FlagType}). */
+type FlagValue = boolean | number | string;
+/**
+ * The author-facing options for a single flag.
+ *
+ * - `type`: the flag's type — `"boolean" | "number" | "string"`.
+ * - `default`: the project-wide default value. MUST match `type` (a `number`
+ *   default with `type: "boolean"` throws).
+ * - `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.
+ * - `description`: an optional human description of what the flag controls.
+ */
+interface FlagOptions {
+    type: FlagType;
+    default: FlagValue;
+    variants?: string[];
+    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"`).
+ * - `default`: the default value (matches `type`).
+ * - `variants`: the allowed-values list for a string flag, or `null` (any).
+ * - `description`: the doc string, or `null`.
+ */
+interface FlagDef {
+    type: FlagType;
+    default: FlagValue;
+    variants: string[] | null;
+    description: string | null;
+}
+/** A flags config definition: the discriminant + a map of flag key →
+ * {@link FlagDef}. This is the value `defineFlags` returns and the runtime
+ * config extractor serializes. */
+interface FlagsConfig {
+    __config: typeof FLAGS_CONFIG_KIND;
+    flags: Record<string, FlagDef>;
+}
+/** The author-facing input to `defineFlags`: a `flags` map whose keys are the
+ * flag keys and whose values are `flag({...})` builders. */
+interface FlagsInput {
+    flags: Record<string, FlagDef>;
+}
+/**
+ * Define a single flag. The flag KEY is supplied by the object key in
+ * `defineFlags({ flags: { <key>: flag({...}) } })`, so `flag()` takes only the
+ * options.
+ *
+ * Validates eagerly (at config-author time):
+ *  - `type` is one of `"boolean" | "number" | "string"`.
+ *  - `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.
+ *
+ * Returns a normalized {@link FlagDef}: `variants` deduped-or-null,
+ * `description` trimmed-or-null.
+ */
+declare function flag(opts: FlagOptions): FlagDef;
+/**
+ * Define the feature-flag definitions for a project. The flag KEY comes from
+ * each object key (authors never repeat the key). Returns the discriminated
+ * {@link FlagsConfig} the runtime config extractor serializes and the Go apply
+ * step UPSERTS into PalFlags.
+ *
+ * @example
+ * export default defineFlags({
+ *   flags: { dark_mode: flag({ type: "boolean", default: false }) },
+ * });
+ */
+declare function defineFlags(input: FlagsInput): FlagsConfig;
+
 /** Options accepted by `@Controller`. */
 interface ControllerOptions {
     /** Default auth for ALL routes in this controller (route-level overrides). */
@@ -195,18 +692,6 @@ declare const Put: (subpath: string, options?: RouteOptions) => MethodDecorator;
 declare const Patch: (subpath: string, options?: RouteOptions) => MethodDecorator;
 /** `@Delete(subpath, options?)` — declare a DELETE route. */
 declare const Delete: (subpath: string, options?: RouteOptions) => MethodDecorator;
-/**
- * `@Returns(schema)` — declare the route's success-response zod schema. The
- * method's return TYPE drives compile-time checking; `@Returns` supplies the
- * matching zod VALUE the OpenAPI generator reads for the 200 response. Optional:
- * a `void` method (no response body) omits it.
- *
- * @example
- * \@Get("/{id}")
- * \@Returns(TodoSchema)
- * getOne(\@Param("id") id: string): TodoSchema { … }
- */
-declare function Returns(schema: ZodTypeAny): MethodDecorator;
 
 /** A legacy parameter decorator. */
 type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
@@ -688,4 +1173,4 @@ declare const documents: {
     onDocumentDeleted(handler: HookHandler<DocumentDeletedEvent>): ResolvedHook<DocumentDeletedEvent>;
 };
 
-export { type BackoffStrategy, Body, Cache, CacheClient, Client, Controller, type ControllerOptions, type CustomWebhookConfig, DBClient, Database, Delete, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentUpdatedEvent, Documents, type EnvSecretRef, EnvTypedDatabase, type FileDeletedEvent, type FileUploadedEvent, Flags, Get, Headers, type HookHandler, type HookMeta, type HttpMethodUpper, type JobConfig, type JobMeta, Log, Logger, Notifications, OptionalUser, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseStorageClient, Param, type PasswordResetEvent, Patch, Post, type ProviderEventMap, type ProviderWebhookConfig, Put, Query, Queue, QueueClient, RateLimitConfig, Req, RequestId, type ResolvedCustomWebhook, type ResolvedHook, type ResolvedJobConfig, type ResolvedProviderWebhook, type ResolvedWebhookConfig, type ResolvedWorkerConfig, Resource, type ResourceEnv, Returns, type RouteOptions, type RuntimeServices, SchemaDef, type SignInEvent, type SignOutEvent, Storage, TraceId, 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, defineJob, defineWebhook, defineWorker, documents, makeEnvDts, storage };
+export { type AcsOptions, type ApnsOptions, type BackoffStrategy, Body, type BucketDef, type BucketOptions, Cache, CacheClient, Client, Controller, type ControllerOptions, type CustomWebhookConfig, DBClient, Database, 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, type HttpMethodUpper, type JobConfig, type JobMeta, Log, Logger, NOTIFICATIONS_CONFIG_KIND, Notifications, type NotificationsConfig, type NotificationsInput, OptionalUser, PROVIDER_CATALOG, PalbaseDocsClient, PalbaseFlagsClient, PalbaseNotificationsClient, PalbaseStorageClient, Param, type PasswordResetEvent, Patch, Post, type ProviderCatalogEntry, type ProviderDef, type ProviderEventMap, type ProviderName, type ProviderOptions, type ProviderWebhookConfig, Put, Query, Queue, QueueClient, RESERVED_SECRET_PREFIX, RateLimitConfig, 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, TraceId, type TwilioOptions, 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, defineFlags, defineJob, defineNotifications, defineStorage, defineWebhook, defineWorker, documents, flag, makeEnvDts, parseFileSizeLimit, reservedSecretKey, storage };