@neon/env 0.0.0 → 0.9.0

package/dist/config/dist/lib/types.d.ts

@@ -0,0 +1,445 @@
+//#region ../config/dist/lib/types.d.ts
+//#region src/lib/types.d.ts
+/**
+ * Valid Neon Compute Unit values.
+ * Most plans support 0.25, 0.5, 1, 2, 4, 8. Higher values may be available on Business plans.
+ */
+type ComputeUnit = 0.25 | 0.5 | 1 | 2 | 4 | 8;
+/** Time units accepted in a {@link DurationString}: seconds, minutes, hours, days, weeks. */
+type DurationUnit = "s" | "m" | "h" | "d" | "w";
+/**
+ * A Neon duration string: a positive integer **followed by a unit** — `s` (seconds),
+ * `m` (minutes), `h` (hours), `d` (days), or `w` (weeks). Used by
+ * {@link ComputeSettings.suspendTimeout} and {@link BranchTuning.ttl}.
+ *
+ * A **unit is required**: a bare numeric string like `"7"` is rejected at the type level. To
+ * express a raw number of seconds, pass a `number` (`300`) — not a string (`"300"`). This
+ * removes the old ambiguity where `"7"` silently meant 7 *seconds* instead of, say, `"7d"`.
+ *
+ * @example "5m"  // 5 minutes
+ * @example "1h"  // 1 hour
+ * @example "7d"  // 7 days
+ */
+type DurationString = `${number}${DurationUnit}`;
+/**
+ * Autocomplete suggestions for {@link ComputeSettings.suspendTimeout}. Every value sits inside
+ * the Neon API's allowed scale-to-zero band: **60s–604800s** (1 minute – 1 week). This is *not*
+ * a closed set — the field also accepts any other {@link DurationString} or a `number` of
+ * seconds; out-of-range values type-check but are rejected at apply time.
+ */
+type SuspendTimeoutSuggestion = "1m" | "5m" | "15m" | "30m" | "1h" | "6h" | "12h" | "1d" | "7d";
+/**
+ * Autocomplete suggestions for {@link BranchTuning.ttl}. Every value sits within the Neon API's
+ * branch-expiration limit (**max 30 days** from creation; the Console's own presets are 1h / 1d
+ * / 7d). This is *not* a closed set — the field also accepts any other {@link DurationString} or
+ * a `number` of seconds; values over 30 days are rejected at apply time.
+ */
+type TtlSuggestion = "1h" | "6h" | "12h" | "1d" | "3d" | "7d" | "14d" | "30d";
+/**
+ * Compose a field's duration type: its curated autocomplete `Suggestions` plus the open
+ * `DurationString` template (so any `<integer><unit>` string still type-checks) and a `number`
+ * of seconds. Intersecting the template arm with `NonNullable<unknown>` stops TypeScript from
+ * collapsing the literal suggestions into the template, which is what preserves the autocomplete.
+ */
+type DurationField<Suggestions extends DurationString> = Suggestions | (DurationString & NonNullable<unknown>) | number;
+/**
+ * Compute settings applied to the read/write endpoint of a branch.
+ *
+ * Mirrors the subset of {@link https://api-docs.neon.tech/reference/getting-started-with-neon-api Neon endpoint}
+ * fields that we expose as IaC primitives. Anything left undefined falls back to the project's
+ * `default_endpoint_settings` (which themselves fall back to Neon platform defaults).
+ */
+interface ComputeSettings {
+  /**
+   * Minimum number of Compute Units. Set to 0.25 for true scale-to-zero.
+   * @example 0.25  // scale-to-zero
+   * @example 1     // always-on with 1 CU minimum
+   */
+  autoscalingLimitMinCu?: ComputeUnit;
+  /**
+   * Maximum number of Compute Units for autoscaling.
+   * @example 2
+   * @example 8
+   */
+  autoscalingLimitMaxCu?: ComputeUnit;
+  /**
+   * How long an idle compute waits before suspending (Neon's scale-to-zero). Accepts a
+   * {@link DurationString} (autocompletes common values), a number of seconds, or `false`.
+   *
+   * - `false` — never suspend (always-on compute)
+   * - {@link DurationString} — e.g. `"5m"`; autocompletes the in-range values `"1m"`, `"5m"`,
+   *   `"15m"`, `"30m"`, `"1h"`, `"6h"`, `"12h"`, `"1d"`, `"7d"`, and accepts any other
+   *   `<integer><unit>` (units: `s`, `m`, `h`, `d`, `w`). A **unit is required** — for raw
+   *   seconds pass a `number`, not a string.
+   * - `number` — custom timeout in **seconds**, must be in `60`–`604800` (1 minute to 1 week)
+   * - `undefined` — use the Neon platform default (currently 300s / 5 minutes)
+   *
+   * Whichever form you use, the resolved timeout must fall in `60`–`604800` seconds (the Neon
+   * API limit); the suggestions are all within that band, anything else is checked at apply.
+   *
+   * @example false  // never suspend (always-on)
+   * @example "5m"   // suspend after 5 minutes idle
+   * @example "1h"   // suspend after 1 hour idle
+   * @example 300    // 5 minutes, expressed in seconds
+   */
+  suspendTimeout?: false | DurationField<SuspendTimeoutSuggestion>;
+}
+/**
+ * Read-only descriptor of the branch a {@link Config} policy is being evaluated for — the
+ * `branch` argument passed to your `defineConfig({ branch: (branch) => … })` closure. It describes
+ * **which** branch this invocation decides for; it is not a live branch handle and must not
+ * be mutated. Switch on its fields and return the desired {@link BranchConfig}.
+ */
+interface BranchTarget {
+  /** Branch name being evaluated. For `branch dev`, this is the generated branch name. */
+  name: string;
+  /** Neon branch id when the branch already exists. Undefined during pre-create eval. */
+  id?: string;
+  /** Whether this branch already exists on Neon. */
+  exists: boolean;
+  /** Parent branch id from Neon when known. */
+  parentId?: string;
+  /** Whether Neon marks this branch as the project default. */
+  isDefault?: boolean;
+  /** Whether Neon currently marks this branch protected. */
+  isProtected?: boolean;
+  /** Current expiration timestamp from Neon, when set. */
+  expiresAt?: string;
+}
+/**
+ * Object form of a branch-scoped service toggle. `{}` or `{ enabled: true }` enables it;
+ * `{ enabled: false }` opts out. Used as the object half of {@link ServiceToggleInput}.
+ */
+interface ServiceToggle {
+  /** Defaults to `true` when the service namespace is present. Set `false` to opt out. */
+  enabled?: boolean;
+}
+/**
+ * How a branch-scoped service (Neon Auth, Data API, AI Gateway) is toggled in a policy.
+ *
+ * - `true` / `{}` / `{ enabled: true }` — enabled.
+ * - `false` / `{ enabled: false }` — disabled.
+ * - omitted (`undefined`) — not part of the policy at all.
+ *
+ * These toggles are **static** (they live in the top-level `defineConfig({ … })` object,
+ * not in the per-branch `branch` closure) so the secret set they imply can be derived at
+ * the type level — that's what makes `NeonEnv<typeof config>` exact.
+ */
+type ServiceToggleInput = boolean | ServiceToggle;
+/**
+ * Resolve a **static** service toggle (`true` / `false` / `{ enabled?: boolean }` / object /
+ * `undefined`) to a type-level boolean. The tuple wrapping (`[T] extends […]`) disables
+ * distribution so a union/`undefined` is judged as a single unit:
+ *
+ * - `false` / `{ enabled: false }` / `undefined` → `false`
+ * - `true` / `{ enabled: true }` / any other object (`{}`, `{ enabled?: boolean }`) → `true`
+ *   (a present toggle defaults to enabled)
+ * - the bare `boolean | … | undefined` (no literal info) → `false`
+ *
+ * Shared by the {@link Config} static cross-field checks and the `@neon/env`
+ * `NeonEnv` namespace derivation, so both read "is this service on?" identically.
+ */
+
+interface PostgresConfig {
+  computeSettings?: ComputeSettings;
+}
+/**
+ * Authentication providers a Data API integration can verify JWTs against, as written in
+ * `neon.ts`. Friendly authoring values (mapped to the Neon API's `neon_auth` / `external`
+ * at the API boundary):
+ *
+ * - `"neon"` — verify tokens minted by **Neon Auth** on the same branch. Neon supplies the
+ *   JWKS URL / provider wiring for you, so the `jwksUrl` / `providerName` / `jwtAudience`
+ *   fields are forbidden (a type error) on this variant — and the policy must also enable
+ *   top-level `auth` (Neon Auth) so the tokens exist.
+ * - `"external"` — verify tokens from a third-party IdP (Clerk, Stytch, Auth0, …). You
+ *   provide `jwksUrl` (and optionally `providerName` / `jwtAudience`).
+ */
+declare const DATA_API_AUTH_PROVIDERS: readonly ["neon", "external"];
+type DataApiAuthProvider = (typeof DATA_API_AUTH_PROVIDERS)[number];
+/**
+ * Reusable runtime settings for a Data API integration (the Neon API `DataAPISettings`,
+ * camelCased to match the rest of `neon.ts`). Every field is optional; omitted fields keep
+ * the Neon defaults shown below. These are the **only** Data API fields that can change on
+ * an already-enabled integration — drift here is reconciled as an *update* (requires
+ * `updateExisting` / `--update-existing`); the create-only auth wiring above cannot.
+ */
+interface DataApiSettings {
+  /** Enable the aggregates feature (`db_aggregates_enabled`). Default `true`. */
+  dbAggregatesEnabled?: boolean;
+  /** Database role used for anonymous requests (`db_anon_role`). Default `"anonymous"`. */
+  dbAnonRole?: string;
+  /** Extra schemas appended to the search path (`db_extra_search_path`). */
+  dbExtraSearchPath?: string;
+  /** Maximum rows returned in a single request (`db_max_rows`). */
+  dbMaxRows?: number;
+  /** Schemas exposed via the API (`db_schemas`). Default `["public"]`. */
+  dbSchemas?: string[];
+  /** JWT claim key used for role extraction (`jwt_role_claim_key`). Default `".role"`. */
+  jwtRoleClaimKey?: string;
+  /** Maximum lifetime of the JWT cache, in seconds (`jwt_cache_max_lifetime`). */
+  jwtCacheMaxLifetime?: number;
+  /** OpenAPI spec mode (`openapi_mode`). Default `"disabled"`. */
+  openapiMode?: "ignore-privileges" | "disabled";
+  /** CORS allowed origins (`server_cors_allowed_origins`). */
+  serverCorsAllowedOrigins?: string;
+  /** Emit server-timing headers (`server_timing_enabled`). */
+  serverTimingEnabled?: boolean;
+}
+/** Fields shared by every {@link DataApiConfig} variant. */
+interface DataApiConfigBase {
+  /** Defaults to `true` when the `dataApi` namespace is present. Set `false` to opt out. */
+  enabled?: boolean;
+  /** Reusable runtime settings. Drift here is reconciled as an update. */
+  settings?: DataApiSettings;
+}
+/**
+ * Data API verified by **Neon Auth** (`authProvider: "neon"`, the default). The external
+ * IdP fields are statically forbidden (`?: never`) because Neon supplies them; declaring any
+ * of them is a type error directing you to `authProvider: "external"`.
+ */
+interface DataApiNeonAuthConfig extends DataApiConfigBase {
+  authProvider?: "neon";
+  /** Forbidden with `authProvider: "neon"` — Neon provides the JWKS URL. */
+  jwksUrl?: never;
+  /** Forbidden with `authProvider: "neon"` — the provider is Neon Auth. */
+  providerName?: never;
+  /** Forbidden with `authProvider: "neon"` — Neon manages the audience. */
+  jwtAudience?: never;
+}
+/**
+ * Data API verified by an **external** IdP (`authProvider: "external"`). You provide the
+ * JWKS URL (and optionally a provider label / expected audience).
+ */
+interface DataApiExternalAuthConfig extends DataApiConfigBase {
+  authProvider: "external";
+  /** URL that publishes the IdP's JWKS (JSON Web Key Set). */
+  jwksUrl?: string;
+  /** Human label for the IdP (e.g. "Clerk", "Stytch", "Auth0"). */
+  providerName?: string;
+  /**
+   * Expected `aud` claim. ⚠️ This only **rejects** tokens carrying a *different* audience;
+   * tokens with no `aud` claim are still accepted.
+   */
+  jwtAudience?: string;
+}
+/**
+ * Object form of the `dataApi` toggle. A discriminated union on {@link DataApiAuthProvider}:
+ * the `"neon"` variant forbids the external-IdP fields, the `"external"` variant allows them.
+ */
+type DataApiConfig = DataApiNeonAuthConfig | DataApiExternalAuthConfig;
+/**
+ * How the Data API is toggled in a policy: a bare boolean (like the other service toggles)
+ * or the richer {@link DataApiConfig} object. `true` / `{}` / `{ enabled: true }` enable it
+ * with Neon defaults; `false` / `{ enabled: false }` opt out.
+ */
+type DataApiInput = boolean | DataApiConfig;
+/**
+ * Supported function runtimes. Mirrors the Neon Functions deploy API `runtime` enum.
+ * Only `nodejs24` exists today; kept as a union so adding runtimes later is a
+ * non-breaking, type-checked change.
+ */
+type FunctionRuntime = "nodejs24";
+/**
+ * Local-development settings for a function, used by `neon dev` when it serves every
+ * function declared in `neon.ts` (i.e. invoked with no `--source`). Never affects deploy.
+ */
+interface FunctionDevConfig {
+  /**
+   * Port the local server binds. Bound exactly (and `neon dev` fails loudly if it is taken)
+   * when set; a free port is found automatically when omitted.
+   */
+  port?: number;
+}
+/**
+ * Static definition of a Neon Function (Preview feature). Declares that the function
+ * **exists** on every branch; its branch-unique slug is the **record key** in
+ * {@link PreviewInput.functions} (not a field here), so slugs are statically enumerable,
+ * cannot duplicate, and the `branch` closure can only tune slugs that are declared here.
+ *
+ * A function is invoked like a Cloudflare/Vercel handler — its source module
+ * `export default { fetch }` or `export async function handler(req): Response`. The
+ * `source` path is bundled (esbuild) and uploaded as a deployment; the newest deployment
+ * becomes active.
+ *
+ * Runtime tuning is **not** here — it varies per branch and lives in the `branch` closure
+ * (see {@link FunctionTuning}). Memory is fixed by the platform policy for now and is not
+ * user-configurable.
+ */
+interface FunctionDef {
+  /** Free-form display name. @example "Hello World" */
+  name: string;
+  /**
+   * Path to the function's entry module, **relative to `neon.ts`** (or absolute). The
+   * module's default export (`{ fetch }`) or `handler` export is the function entry. This
+   * path is resolved against the loaded `neon.ts` location and bundled with esbuild at
+   * deploy time.
+   *
+   * We require a string path rather than an imported handler because a JS function value
+   * carries no reference back to its source file, so esbuild has nothing to bundle from.
+   * @example "./functions/hello-world.ts"
+   */
+  source: string;
+  /**
+   * Environment variables injected into the deployed function, keyed by the var name the
+   * function reads at runtime. The **keys** are static (preserved at the type level so
+   * `parseEnv(config, "<slug>").function.<key>` is typed); the **values** are arbitrary
+   * strings evaluated when `neon.ts` is loaded (typically `process.env.X`) and uploaded
+   * at `config apply`. Every value must be a defined string — a `process.env.X` that is
+   * `undefined` (unset) errors at validation time rather than silently shipping
+   * `undefined`.
+   * @example { resendApiKey: process.env.RESEND_API_KEY ?? "" }
+   */
+  env?: Record<string, string>;
+  /**
+   * Local-development settings used by `neon dev` when serving every function from
+   * `neon.ts`. Ignored at deploy time. See {@link FunctionDevConfig}.
+   */
+  dev?: FunctionDevConfig;
+}
+/**
+ * A single capability a branch-scoped service credential may exercise (Preview). A
+ * credential is granted a set of these and may only perform the listed actions. Mirrors
+ * the Neon API `CredentialScope` enum (`x-stability-level: beta`):
+ *
+ * - `storage:read` / `storage:write` — object-storage (bucket) access via the S3 key.
+ * - `ai_gateway:invoke` — call the AI Gateway with the bearer `api_token`.
+ * - `functions:invoke` — invoke Neon Functions with the bearer `api_token`.
+ *
+ * The set a policy needs is derived from its enabled Preview features (see
+ * {@link deriveCredentialScopes}); it is never authored by hand.
+ */
+type CredentialScope = "storage:read" | "storage:write" | "ai_gateway:invoke" | "functions:invoke";
+/**
+ * Who a credential acts as. `user` is the developer/app principal minted for local dev and
+ * app bootstrap (`fetchEnv` / `env pull`); `function` is a deployed-function principal
+ * (carries a `function_id`). The env tooling only mints `user` credentials today.
+ */
+type CredentialPrincipalType = "user" | "function";
+/** Anonymous-access level for a branchable object-storage bucket. */
+type BucketAccessLevel = "private" | "public_read";
+/**
+ * Static definition of a branchable object-storage bucket (Preview feature). The bucket's
+ * name is the **record key** in {@link PreviewInput.buckets}, so names are statically
+ * enumerable and cannot duplicate.
+ */
+interface BucketDef {
+  /**
+   * Anonymous access level. `private` (default) requires authenticated reads/writes;
+   * `public_read` allows anonymous GetObject/HeadObject.
+   */
+  access?: BucketAccessLevel;
+}
+/**
+ * Static, branch-scoped **Preview** features. Grouped under `preview` to signal they are
+ * backed by Neon `x-stability-level: beta` endpoints and may change before GA. Everything
+ * here is existential (it determines what exists on the branch); per-branch tuning lives in
+ * the `branch` closure.
+ */
+interface PreviewInput {
+  /** Enable/disable the AI Gateway on the branch (toggle, like auth / dataApi). */
+  aiGateway?: ServiceToggleInput;
+  /** Functions to deploy, keyed by branch-unique slug (`^[a-z0-9]{1,20}$`). */
+  functions?: Record<string, FunctionDef>;
+  /** Object-storage buckets to create, keyed by bucket name. */
+  buckets?: Record<string, BucketDef>;
+}
+/**
+ * Per-branch deploy tuning for a single function. Returned (per slug) by the `branch`
+ * closure. Deliberately **cannot** change the function's existence, source, name, env
+ * **keys**, or memory — only runtime selection is currently configurable — so the static
+ * secret/function set stays sound.
+ */
+interface FunctionTuning {
+  /** Runtime to execute the function with. Defaults to `"nodejs24"`. */
+  runtime?: FunctionRuntime;
+}
+/**
+ * Per-branch tuning of Preview features. Only existing function slugs (those declared in
+ * the static {@link PreviewInput.functions}) may be tuned — `Slug` is constrained to the
+ * declared keys by {@link BranchTuningFn}.
+ */
+interface PreviewTuning<Slug extends string = string> {
+  functions?: Partial<Record<Slug, FunctionTuning>>;
+}
+/**
+ * The per-branch tuning object returned by the `branch` closure. It can adjust branch
+ * lifecycle (`parent`, `ttl`, `protected`), Postgres compute settings, and per-function
+ * deploy tuning — but **cannot** add/remove services or functions. That guarantee is what
+ * keeps the static secret set (and therefore `NeonEnv`) exact.
+ */
+interface BranchTuning<Slug extends string = string> {
+  /** Parent branch name used when creating a new branch. Not a Postgres setting. */
+  parent?: string;
+  /**
+   * Branch time-to-live: how long after creation the branch should auto-expire. Applied
+   * when creating a new branch and reconciled on existing branches (when `updateExisting`
+   * is set). Accepts a {@link DurationString} (autocompletes common values) or a number of
+   * seconds. Omit to keep the branch indefinitely.
+   *
+   * - {@link DurationString} — e.g. `"7d"`; autocompletes `"1h"`, `"6h"`, `"12h"`, `"1d"`,
+   *   `"3d"`, `"7d"`, `"14d"`, `"30d"`, and accepts any other `<integer><unit>` (units: `s`,
+   *   `m`, `h`, `d`, `w` — e.g. `"12h"`, `"2w"`). A **unit is required** — `"7"` is rejected;
+   *   for raw seconds pass a `number`.
+   * - `number` — custom TTL in **seconds** (e.g. `3600`)
+   * - `undefined` — no expiry; the branch persists until explicitly deleted
+   *
+   * The Neon API caps branch expiration at **30 days** from creation, so the resolved TTL must
+   * be `> 0` and `<= 30d`; the suggestions stay within that limit and anything longer is
+   * rejected at apply.
+   *
+   * @example "1d"   // ephemeral preview branch: expires a day after creation
+   * @example "7d"   // one-week TTL
+   * @example "30d"  // the maximum the API allows
+   * @example 3600   // 1 hour, expressed in seconds
+   */
+  ttl?: DurationField<TtlSuggestion>;
+  /** Whether the selected branch should be protected. Undefined means "leave as-is". */
+  protected?: boolean;
+  postgres?: PostgresConfig;
+  preview?: PreviewTuning<Slug>;
+}
+/** Extract the declared function slugs from a {@link PreviewInput} for closure typing. */
+type FunctionSlugsOf<Preview extends PreviewInput | undefined> = Preview extends {
+  functions: infer F;
+} ? Extract<keyof F, string> : string;
+/**
+ * Signature of the `branch` closure. Generic over the static {@link PreviewInput} so the
+ * `preview.functions` keys it may tune are constrained to the slugs actually declared.
+ */
+type BranchTuningFn<Preview extends PreviewInput | undefined = PreviewInput | undefined> = (branch: BranchTarget) => BranchTuning<FunctionSlugsOf<Preview>>;
+/**
+ * A validated Neon branch policy — the value `defineConfig({ … })` returns and `neon.ts`
+ * default-exports.
+ *
+ * Split into a **static** existential set (top-level `auth` / `dataApi` GA toggles plus the
+ * beta `preview` block) and a **dynamic** per-branch `branch` closure for tuning. The
+ * static half is what makes the secret set — and therefore `NeonEnv<typeof config>` and
+ * `parseEnv` — exact; the closure can tune but never change what exists.
+ *
+ * Generic over the three static fields so the type system can read the exact toggle/slug
+ * literals; the defaults make the bare `Config` a usable "any policy" type for runtime
+ * function signatures.
+ */
+interface Config<Auth extends ServiceToggleInput | undefined = ServiceToggleInput | undefined, DataApi extends DataApiInput | undefined = DataApiInput | undefined, Preview extends PreviewInput | undefined = PreviewInput | undefined> {
+  /** Neon Auth integration toggle (GA). Static — drives `NeonEnv.auth`. */
+  auth?: Auth;
+  /**
+   * Neon Data API integration (GA). Static — drives `NeonEnv.dataApi`. A boolean/toggle, or
+   * a {@link DataApiConfig} object selecting the auth provider (`"neon"` / `"external"`) and
+   * runtime {@link DataApiSettings}. With `authProvider: "neon"` the policy must also enable
+   * top-level `auth`.
+   */
+  dataApi?: DataApi;
+  /** Beta (Preview) feature set: AI Gateway, functions, buckets. Static. */
+  preview?: Preview;
+  /** Per-branch tuning closure. Cannot change the static existential set. */
+  branch?: BranchTuningFn<Preview>;
+}
+/**
+ * A function with all deploy defaults applied. `resolveConfig` fills in `runtime` so
+ * downstream diff/apply never has to re-derive it.
+ */
+//#endregion
+export { BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, ServiceToggle, ServiceToggleInput };
+//# sourceMappingURL=types.d.ts.map

package/dist/config/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":["ComputeUnit","DurationUnit","DurationString","SuspendTimeoutSuggestion","TtlSuggestion","DurationField","Suggestions","NonNullable","ComputeSettings","BranchTarget","ServiceToggle","ServiceToggleInput","ServiceEnabled","T","PostgresConfig","DATA_API_AUTH_PROVIDERS","DataApiAuthProvider","DataApiSettings","DataApiConfigBase","DataApiNeonAuthConfig","DataApiExternalAuthConfig","DataApiConfig","DataApiInput","FunctionRuntime","FunctionDevConfig","FunctionDef","Record","CredentialScope","CredentialPrincipalType","BucketAccessLevel","BucketDef","PreviewInput","FunctionTuning","PreviewTuning","Slug","Partial","BranchTuning","FunctionSlugsOf","Preview","F","Extract","BranchTuningFn","Config","Auth","DataApi","ResolvedFunctionConfig","ResolvedBucketConfig","ResolvedPreviewConfig","ResolvedDataApiConfig","ResolvedBranchConfig","AppliedChange","ConflictReport","PushResult"],"sources":["../../../../../config/dist/lib/types.d.ts"],"sourcesContent":["//#region src/lib/types.d.ts\n/**\n * Valid Neon Compute Unit values.\n * Most plans support 0.25, 0.5, 1, 2, 4, 8. Higher values may be available on Business plans.\n */\ntype ComputeUnit = 0.25 | 0.5 | 1 | 2 | 4 | 8;\n/** Time units accepted in a {@link DurationString}: seconds, minutes, hours, days, weeks. */\ntype DurationUnit = \"s\" | \"m\" | \"h\" | \"d\" | \"w\";\n/**\n * A Neon duration string: a positive integer **followed by a unit** — `s` (seconds),\n * `m` (minutes), `h` (hours), `d` (days), or `w` (weeks). Used by\n * {@link ComputeSettings.suspendTimeout} and {@link BranchTuning.ttl}.\n *\n * A **unit is required**: a bare numeric string like `\"7\"` is rejected at the type level. To\n * express a raw number of seconds, pass a `number` (`300`) — not a string (`\"300\"`). This\n * removes the old ambiguity where `\"7\"` silently meant 7 *seconds* instead of, say, `\"7d\"`.\n *\n * @example \"5m\"  // 5 minutes\n * @example \"1h\"  // 1 hour\n * @example \"7d\"  // 7 days\n */\ntype DurationString = `${number}${DurationUnit}`;\n/**\n * Autocomplete suggestions for {@link ComputeSettings.suspendTimeout}. Every value sits inside\n * the Neon API's allowed scale-to-zero band: **60s–604800s** (1 minute – 1 week). This is *not*\n * a closed set — the field also accepts any other {@link DurationString} or a `number` of\n * seconds; out-of-range values type-check but are rejected at apply time.\n */\ntype SuspendTimeoutSuggestion = \"1m\" | \"5m\" | \"15m\" | \"30m\" | \"1h\" | \"6h\" | \"12h\" | \"1d\" | \"7d\";\n/**\n * Autocomplete suggestions for {@link BranchTuning.ttl}. Every value sits within the Neon API's\n * branch-expiration limit (**max 30 days** from creation; the Console's own presets are 1h / 1d\n * / 7d). This is *not* a closed set — the field also accepts any other {@link DurationString} or\n * a `number` of seconds; values over 30 days are rejected at apply time.\n */\ntype TtlSuggestion = \"1h\" | \"6h\" | \"12h\" | \"1d\" | \"3d\" | \"7d\" | \"14d\" | \"30d\";\n/**\n * Compose a field's duration type: its curated autocomplete `Suggestions` plus the open\n * `DurationString` template (so any `<integer><unit>` string still type-checks) and a `number`\n * of seconds. Intersecting the template arm with `NonNullable<unknown>` stops TypeScript from\n * collapsing the literal suggestions into the template, which is what preserves the autocomplete.\n */\ntype DurationField<Suggestions extends DurationString> = Suggestions | (DurationString & NonNullable<unknown>) | number;\n/**\n * Compute settings applied to the read/write endpoint of a branch.\n *\n * Mirrors the subset of {@link https://api-docs.neon.tech/reference/getting-started-with-neon-api Neon endpoint}\n * fields that we expose as IaC primitives. Anything left undefined falls back to the project's\n * `default_endpoint_settings` (which themselves fall back to Neon platform defaults).\n */\ninterface ComputeSettings {\n  /**\n   * Minimum number of Compute Units. Set to 0.25 for true scale-to-zero.\n   * @example 0.25  // scale-to-zero\n   * @example 1     // always-on with 1 CU minimum\n   */\n  autoscalingLimitMinCu?: ComputeUnit;\n  /**\n   * Maximum number of Compute Units for autoscaling.\n   * @example 2\n   * @example 8\n   */\n  autoscalingLimitMaxCu?: ComputeUnit;\n  /**\n   * How long an idle compute waits before suspending (Neon's scale-to-zero). Accepts a\n   * {@link DurationString} (autocompletes common values), a number of seconds, or `false`.\n   *\n   * - `false` — never suspend (always-on compute)\n   * - {@link DurationString} — e.g. `\"5m\"`; autocompletes the in-range values `\"1m\"`, `\"5m\"`,\n   *   `\"15m\"`, `\"30m\"`, `\"1h\"`, `\"6h\"`, `\"12h\"`, `\"1d\"`, `\"7d\"`, and accepts any other\n   *   `<integer><unit>` (units: `s`, `m`, `h`, `d`, `w`). A **unit is required** — for raw\n   *   seconds pass a `number`, not a string.\n   * - `number` — custom timeout in **seconds**, must be in `60`–`604800` (1 minute to 1 week)\n   * - `undefined` — use the Neon platform default (currently 300s / 5 minutes)\n   *\n   * Whichever form you use, the resolved timeout must fall in `60`–`604800` seconds (the Neon\n   * API limit); the suggestions are all within that band, anything else is checked at apply.\n   *\n   * @example false  // never suspend (always-on)\n   * @example \"5m\"   // suspend after 5 minutes idle\n   * @example \"1h\"   // suspend after 1 hour idle\n   * @example 300    // 5 minutes, expressed in seconds\n   */\n  suspendTimeout?: false | DurationField<SuspendTimeoutSuggestion>;\n}\n/**\n * Read-only descriptor of the branch a {@link Config} policy is being evaluated for — the\n * `branch` argument passed to your `defineConfig({ branch: (branch) => … })` closure. It describes\n * **which** branch this invocation decides for; it is not a live branch handle and must not\n * be mutated. Switch on its fields and return the desired {@link BranchConfig}.\n */\ninterface BranchTarget {\n  /** Branch name being evaluated. For `branch dev`, this is the generated branch name. */\n  name: string;\n  /** Neon branch id when the branch already exists. Undefined during pre-create eval. */\n  id?: string;\n  /** Whether this branch already exists on Neon. */\n  exists: boolean;\n  /** Parent branch id from Neon when known. */\n  parentId?: string;\n  /** Whether Neon marks this branch as the project default. */\n  isDefault?: boolean;\n  /** Whether Neon currently marks this branch protected. */\n  isProtected?: boolean;\n  /** Current expiration timestamp from Neon, when set. */\n  expiresAt?: string;\n}\n/**\n * Object form of a branch-scoped service toggle. `{}` or `{ enabled: true }` enables it;\n * `{ enabled: false }` opts out. Used as the object half of {@link ServiceToggleInput}.\n */\ninterface ServiceToggle {\n  /** Defaults to `true` when the service namespace is present. Set `false` to opt out. */\n  enabled?: boolean;\n}\n/**\n * How a branch-scoped service (Neon Auth, Data API, AI Gateway) is toggled in a policy.\n *\n * - `true` / `{}` / `{ enabled: true }` — enabled.\n * - `false` / `{ enabled: false }` — disabled.\n * - omitted (`undefined`) — not part of the policy at all.\n *\n * These toggles are **static** (they live in the top-level `defineConfig({ … })` object,\n * not in the per-branch `branch` closure) so the secret set they imply can be derived at\n * the type level — that's what makes `NeonEnv<typeof config>` exact.\n */\ntype ServiceToggleInput = boolean | ServiceToggle;\n/**\n * Resolve a **static** service toggle (`true` / `false` / `{ enabled?: boolean }` / object /\n * `undefined`) to a type-level boolean. The tuple wrapping (`[T] extends […]`) disables\n * distribution so a union/`undefined` is judged as a single unit:\n *\n * - `false` / `{ enabled: false }` / `undefined` → `false`\n * - `true` / `{ enabled: true }` / any other object (`{}`, `{ enabled?: boolean }`) → `true`\n *   (a present toggle defaults to enabled)\n * - the bare `boolean | … | undefined` (no literal info) → `false`\n *\n * Shared by the {@link Config} static cross-field checks and the `@neon/env`\n * `NeonEnv` namespace derivation, so both read \"is this service on?\" identically.\n */\ntype ServiceEnabled<T> = [T] extends [false] ? false : [T] extends [{\n  enabled: false;\n}] ? false : [T] extends [undefined] ? false : [T] extends [true] ? true : [T] extends [{\n  enabled: true;\n}] ? true : [T] extends [object] ? true : false;\ninterface PostgresConfig {\n  computeSettings?: ComputeSettings;\n}\n/**\n * Authentication providers a Data API integration can verify JWTs against, as written in\n * `neon.ts`. Friendly authoring values (mapped to the Neon API's `neon_auth` / `external`\n * at the API boundary):\n *\n * - `\"neon\"` — verify tokens minted by **Neon Auth** on the same branch. Neon supplies the\n *   JWKS URL / provider wiring for you, so the `jwksUrl` / `providerName` / `jwtAudience`\n *   fields are forbidden (a type error) on this variant — and the policy must also enable\n *   top-level `auth` (Neon Auth) so the tokens exist.\n * - `\"external\"` — verify tokens from a third-party IdP (Clerk, Stytch, Auth0, …). You\n *   provide `jwksUrl` (and optionally `providerName` / `jwtAudience`).\n */\ndeclare const DATA_API_AUTH_PROVIDERS: readonly [\"neon\", \"external\"];\ntype DataApiAuthProvider = (typeof DATA_API_AUTH_PROVIDERS)[number];\n/**\n * Reusable runtime settings for a Data API integration (the Neon API `DataAPISettings`,\n * camelCased to match the rest of `neon.ts`). Every field is optional; omitted fields keep\n * the Neon defaults shown below. These are the **only** Data API fields that can change on\n * an already-enabled integration — drift here is reconciled as an *update* (requires\n * `updateExisting` / `--update-existing`); the create-only auth wiring above cannot.\n */\ninterface DataApiSettings {\n  /** Enable the aggregates feature (`db_aggregates_enabled`). Default `true`. */\n  dbAggregatesEnabled?: boolean;\n  /** Database role used for anonymous requests (`db_anon_role`). Default `\"anonymous\"`. */\n  dbAnonRole?: string;\n  /** Extra schemas appended to the search path (`db_extra_search_path`). */\n  dbExtraSearchPath?: string;\n  /** Maximum rows returned in a single request (`db_max_rows`). */\n  dbMaxRows?: number;\n  /** Schemas exposed via the API (`db_schemas`). Default `[\"public\"]`. */\n  dbSchemas?: string[];\n  /** JWT claim key used for role extraction (`jwt_role_claim_key`). Default `\".role\"`. */\n  jwtRoleClaimKey?: string;\n  /** Maximum lifetime of the JWT cache, in seconds (`jwt_cache_max_lifetime`). */\n  jwtCacheMaxLifetime?: number;\n  /** OpenAPI spec mode (`openapi_mode`). Default `\"disabled\"`. */\n  openapiMode?: \"ignore-privileges\" | \"disabled\";\n  /** CORS allowed origins (`server_cors_allowed_origins`). */\n  serverCorsAllowedOrigins?: string;\n  /** Emit server-timing headers (`server_timing_enabled`). */\n  serverTimingEnabled?: boolean;\n}\n/** Fields shared by every {@link DataApiConfig} variant. */\ninterface DataApiConfigBase {\n  /** Defaults to `true` when the `dataApi` namespace is present. Set `false` to opt out. */\n  enabled?: boolean;\n  /** Reusable runtime settings. Drift here is reconciled as an update. */\n  settings?: DataApiSettings;\n}\n/**\n * Data API verified by **Neon Auth** (`authProvider: \"neon\"`, the default). The external\n * IdP fields are statically forbidden (`?: never`) because Neon supplies them; declaring any\n * of them is a type error directing you to `authProvider: \"external\"`.\n */\ninterface DataApiNeonAuthConfig extends DataApiConfigBase {\n  authProvider?: \"neon\";\n  /** Forbidden with `authProvider: \"neon\"` — Neon provides the JWKS URL. */\n  jwksUrl?: never;\n  /** Forbidden with `authProvider: \"neon\"` — the provider is Neon Auth. */\n  providerName?: never;\n  /** Forbidden with `authProvider: \"neon\"` — Neon manages the audience. */\n  jwtAudience?: never;\n}\n/**\n * Data API verified by an **external** IdP (`authProvider: \"external\"`). You provide the\n * JWKS URL (and optionally a provider label / expected audience).\n */\ninterface DataApiExternalAuthConfig extends DataApiConfigBase {\n  authProvider: \"external\";\n  /** URL that publishes the IdP's JWKS (JSON Web Key Set). */\n  jwksUrl?: string;\n  /** Human label for the IdP (e.g. \"Clerk\", \"Stytch\", \"Auth0\"). */\n  providerName?: string;\n  /**\n   * Expected `aud` claim. ⚠️ This only **rejects** tokens carrying a *different* audience;\n   * tokens with no `aud` claim are still accepted.\n   */\n  jwtAudience?: string;\n}\n/**\n * Object form of the `dataApi` toggle. A discriminated union on {@link DataApiAuthProvider}:\n * the `\"neon\"` variant forbids the external-IdP fields, the `\"external\"` variant allows them.\n */\ntype DataApiConfig = DataApiNeonAuthConfig | DataApiExternalAuthConfig;\n/**\n * How the Data API is toggled in a policy: a bare boolean (like the other service toggles)\n * or the richer {@link DataApiConfig} object. `true` / `{}` / `{ enabled: true }` enable it\n * with Neon defaults; `false` / `{ enabled: false }` opt out.\n */\ntype DataApiInput = boolean | DataApiConfig;\n/**\n * Supported function runtimes. Mirrors the Neon Functions deploy API `runtime` enum.\n * Only `nodejs24` exists today; kept as a union so adding runtimes later is a\n * non-breaking, type-checked change.\n */\ntype FunctionRuntime = \"nodejs24\";\n/**\n * Local-development settings for a function, used by `neon dev` when it serves every\n * function declared in `neon.ts` (i.e. invoked with no `--source`). Never affects deploy.\n */\ninterface FunctionDevConfig {\n  /**\n   * Port the local server binds. Bound exactly (and `neon dev` fails loudly if it is taken)\n   * when set; a free port is found automatically when omitted.\n   */\n  port?: number;\n}\n/**\n * Static definition of a Neon Function (Preview feature). Declares that the function\n * **exists** on every branch; its branch-unique slug is the **record key** in\n * {@link PreviewInput.functions} (not a field here), so slugs are statically enumerable,\n * cannot duplicate, and the `branch` closure can only tune slugs that are declared here.\n *\n * A function is invoked like a Cloudflare/Vercel handler — its source module\n * `export default { fetch }` or `export async function handler(req): Response`. The\n * `source` path is bundled (esbuild) and uploaded as a deployment; the newest deployment\n * becomes active.\n *\n * Runtime tuning is **not** here — it varies per branch and lives in the `branch` closure\n * (see {@link FunctionTuning}). Memory is fixed by the platform policy for now and is not\n * user-configurable.\n */\ninterface FunctionDef {\n  /** Free-form display name. @example \"Hello World\" */\n  name: string;\n  /**\n   * Path to the function's entry module, **relative to `neon.ts`** (or absolute). The\n   * module's default export (`{ fetch }`) or `handler` export is the function entry. This\n   * path is resolved against the loaded `neon.ts` location and bundled with esbuild at\n   * deploy time.\n   *\n   * We require a string path rather than an imported handler because a JS function value\n   * carries no reference back to its source file, so esbuild has nothing to bundle from.\n   * @example \"./functions/hello-world.ts\"\n   */\n  source: string;\n  /**\n   * Environment variables injected into the deployed function, keyed by the var name the\n   * function reads at runtime. The **keys** are static (preserved at the type level so\n   * `parseEnv(config, \"<slug>\").function.<key>` is typed); the **values** are arbitrary\n   * strings evaluated when `neon.ts` is loaded (typically `process.env.X`) and uploaded\n   * at `config apply`. Every value must be a defined string — a `process.env.X` that is\n   * `undefined` (unset) errors at validation time rather than silently shipping\n   * `undefined`.\n   * @example { resendApiKey: process.env.RESEND_API_KEY ?? \"\" }\n   */\n  env?: Record<string, string>;\n  /**\n   * Local-development settings used by `neon dev` when serving every function from\n   * `neon.ts`. Ignored at deploy time. See {@link FunctionDevConfig}.\n   */\n  dev?: FunctionDevConfig;\n}\n/**\n * A single capability a branch-scoped service credential may exercise (Preview). A\n * credential is granted a set of these and may only perform the listed actions. Mirrors\n * the Neon API `CredentialScope` enum (`x-stability-level: beta`):\n *\n * - `storage:read` / `storage:write` — object-storage (bucket) access via the S3 key.\n * - `ai_gateway:invoke` — call the AI Gateway with the bearer `api_token`.\n * - `functions:invoke` — invoke Neon Functions with the bearer `api_token`.\n *\n * The set a policy needs is derived from its enabled Preview features (see\n * {@link deriveCredentialScopes}); it is never authored by hand.\n */\ntype CredentialScope = \"storage:read\" | \"storage:write\" | \"ai_gateway:invoke\" | \"functions:invoke\";\n/**\n * Who a credential acts as. `user` is the developer/app principal minted for local dev and\n * app bootstrap (`fetchEnv` / `env pull`); `function` is a deployed-function principal\n * (carries a `function_id`). The env tooling only mints `user` credentials today.\n */\ntype CredentialPrincipalType = \"user\" | \"function\";\n/** Anonymous-access level for a branchable object-storage bucket. */\ntype BucketAccessLevel = \"private\" | \"public_read\";\n/**\n * Static definition of a branchable object-storage bucket (Preview feature). The bucket's\n * name is the **record key** in {@link PreviewInput.buckets}, so names are statically\n * enumerable and cannot duplicate.\n */\ninterface BucketDef {\n  /**\n   * Anonymous access level. `private` (default) requires authenticated reads/writes;\n   * `public_read` allows anonymous GetObject/HeadObject.\n   */\n  access?: BucketAccessLevel;\n}\n/**\n * Static, branch-scoped **Preview** features. Grouped under `preview` to signal they are\n * backed by Neon `x-stability-level: beta` endpoints and may change before GA. Everything\n * here is existential (it determines what exists on the branch); per-branch tuning lives in\n * the `branch` closure.\n */\ninterface PreviewInput {\n  /** Enable/disable the AI Gateway on the branch (toggle, like auth / dataApi). */\n  aiGateway?: ServiceToggleInput;\n  /** Functions to deploy, keyed by branch-unique slug (`^[a-z0-9]{1,20}$`). */\n  functions?: Record<string, FunctionDef>;\n  /** Object-storage buckets to create, keyed by bucket name. */\n  buckets?: Record<string, BucketDef>;\n}\n/**\n * Per-branch deploy tuning for a single function. Returned (per slug) by the `branch`\n * closure. Deliberately **cannot** change the function's existence, source, name, env\n * **keys**, or memory — only runtime selection is currently configurable — so the static\n * secret/function set stays sound.\n */\ninterface FunctionTuning {\n  /** Runtime to execute the function with. Defaults to `\"nodejs24\"`. */\n  runtime?: FunctionRuntime;\n}\n/**\n * Per-branch tuning of Preview features. Only existing function slugs (those declared in\n * the static {@link PreviewInput.functions}) may be tuned — `Slug` is constrained to the\n * declared keys by {@link BranchTuningFn}.\n */\ninterface PreviewTuning<Slug extends string = string> {\n  functions?: Partial<Record<Slug, FunctionTuning>>;\n}\n/**\n * The per-branch tuning object returned by the `branch` closure. It can adjust branch\n * lifecycle (`parent`, `ttl`, `protected`), Postgres compute settings, and per-function\n * deploy tuning — but **cannot** add/remove services or functions. That guarantee is what\n * keeps the static secret set (and therefore `NeonEnv`) exact.\n */\ninterface BranchTuning<Slug extends string = string> {\n  /** Parent branch name used when creating a new branch. Not a Postgres setting. */\n  parent?: string;\n  /**\n   * Branch time-to-live: how long after creation the branch should auto-expire. Applied\n   * when creating a new branch and reconciled on existing branches (when `updateExisting`\n   * is set). Accepts a {@link DurationString} (autocompletes common values) or a number of\n   * seconds. Omit to keep the branch indefinitely.\n   *\n   * - {@link DurationString} — e.g. `\"7d\"`; autocompletes `\"1h\"`, `\"6h\"`, `\"12h\"`, `\"1d\"`,\n   *   `\"3d\"`, `\"7d\"`, `\"14d\"`, `\"30d\"`, and accepts any other `<integer><unit>` (units: `s`,\n   *   `m`, `h`, `d`, `w` — e.g. `\"12h\"`, `\"2w\"`). A **unit is required** — `\"7\"` is rejected;\n   *   for raw seconds pass a `number`.\n   * - `number` — custom TTL in **seconds** (e.g. `3600`)\n   * - `undefined` — no expiry; the branch persists until explicitly deleted\n   *\n   * The Neon API caps branch expiration at **30 days** from creation, so the resolved TTL must\n   * be `> 0` and `<= 30d`; the suggestions stay within that limit and anything longer is\n   * rejected at apply.\n   *\n   * @example \"1d\"   // ephemeral preview branch: expires a day after creation\n   * @example \"7d\"   // one-week TTL\n   * @example \"30d\"  // the maximum the API allows\n   * @example 3600   // 1 hour, expressed in seconds\n   */\n  ttl?: DurationField<TtlSuggestion>;\n  /** Whether the selected branch should be protected. Undefined means \"leave as-is\". */\n  protected?: boolean;\n  postgres?: PostgresConfig;\n  preview?: PreviewTuning<Slug>;\n}\n/** Extract the declared function slugs from a {@link PreviewInput} for closure typing. */\ntype FunctionSlugsOf<Preview extends PreviewInput | undefined> = Preview extends {\n  functions: infer F;\n} ? Extract<keyof F, string> : string;\n/**\n * Signature of the `branch` closure. Generic over the static {@link PreviewInput} so the\n * `preview.functions` keys it may tune are constrained to the slugs actually declared.\n */\ntype BranchTuningFn<Preview extends PreviewInput | undefined = PreviewInput | undefined> = (branch: BranchTarget) => BranchTuning<FunctionSlugsOf<Preview>>;\n/**\n * A validated Neon branch policy — the value `defineConfig({ … })` returns and `neon.ts`\n * default-exports.\n *\n * Split into a **static** existential set (top-level `auth` / `dataApi` GA toggles plus the\n * beta `preview` block) and a **dynamic** per-branch `branch` closure for tuning. The\n * static half is what makes the secret set — and therefore `NeonEnv<typeof config>` and\n * `parseEnv` — exact; the closure can tune but never change what exists.\n *\n * Generic over the three static fields so the type system can read the exact toggle/slug\n * literals; the defaults make the bare `Config` a usable \"any policy\" type for runtime\n * function signatures.\n */\ninterface Config<Auth extends ServiceToggleInput | undefined = ServiceToggleInput | undefined, DataApi extends DataApiInput | undefined = DataApiInput | undefined, Preview extends PreviewInput | undefined = PreviewInput | undefined> {\n  /** Neon Auth integration toggle (GA). Static — drives `NeonEnv.auth`. */\n  auth?: Auth;\n  /**\n   * Neon Data API integration (GA). Static — drives `NeonEnv.dataApi`. A boolean/toggle, or\n   * a {@link DataApiConfig} object selecting the auth provider (`\"neon\"` / `\"external\"`) and\n   * runtime {@link DataApiSettings}. With `authProvider: \"neon\"` the policy must also enable\n   * top-level `auth`.\n   */\n  dataApi?: DataApi;\n  /** Beta (Preview) feature set: AI Gateway, functions, buckets. Static. */\n  preview?: Preview;\n  /** Per-branch tuning closure. Cannot change the static existential set. */\n  branch?: BranchTuningFn<Preview>;\n}\n/**\n * A function with all deploy defaults applied. `resolveConfig` fills in `runtime` so\n * downstream diff/apply never has to re-derive it.\n */\ninterface ResolvedFunctionConfig {\n  slug: string;\n  name: string;\n  source: string;\n  env: Record<string, string>;\n  runtime: FunctionRuntime;\n  /**\n   * Local-development settings, passed through untouched from {@link FunctionDef.dev}\n   * (no defaults applied). Only consumed by `neon dev`; deploy ignores it.\n   */\n  dev?: FunctionDevConfig;\n}\n/** A bucket with its access level defaulted to `private`. */\ninterface ResolvedBucketConfig {\n  name: string;\n  access: BucketAccessLevel;\n}\n/**\n * Normalized {@link PreviewInput}. Only present on {@link ResolvedBranchConfig} when the\n * policy returned a `preview` block. `aiGatewayEnabled` follows the same\n * \"present-and-not-`false`\" semantics as `authEnabled` / `dataApiEnabled`.\n */\ninterface ResolvedPreviewConfig {\n  functions: ResolvedFunctionConfig[];\n  buckets: ResolvedBucketConfig[];\n  aiGatewayEnabled: boolean;\n}\n/**\n * Normalized Data API integration. Present on {@link ResolvedBranchConfig} only when the\n * policy enables `dataApi`. `authProvider` always resolves (defaults to `\"neon\"`); the\n * external-IdP wiring is present only for `\"external\"`; `settings` carries the camelCase\n * runtime settings (reconciled as an update when they drift).\n */\ninterface ResolvedDataApiConfig {\n  authProvider: DataApiAuthProvider;\n  jwksUrl?: string;\n  providerName?: string;\n  jwtAudience?: string;\n  settings?: DataApiSettings;\n}\ninterface ResolvedBranchConfig {\n  parent?: string;\n  ttlSeconds?: number;\n  protected?: boolean;\n  postgres?: PostgresConfig;\n  authEnabled: boolean;\n  dataApiEnabled: boolean;\n  /**\n   * Resolved Data API integration. Present iff {@link dataApiEnabled} is `true`. Carries the\n   * create-time auth wiring and the updatable {@link DataApiSettings}.\n   */\n  dataApi?: ResolvedDataApiConfig;\n  preview?: ResolvedPreviewConfig;\n}\n/**\n * One concrete change `pushConfig` made (or, in dry-run, would make) on the remote.\n */\ninterface AppliedChange {\n  /**\n   * `service` covers branch-scoped integrations driven by the branch policy (e.g.\n   * Neon Auth, Data API).\n   */\n  kind: \"branch\" | \"service\";\n  action: \"create\" | \"update\" | \"noop\";\n  identifier: string;\n  details?: Record<string, unknown>;\n}\n/**\n * A diff entry that conflicts with the desired config. `pushConfig` throws\n * {@link PushConflictError} on the first call when conflicts exist; pass\n * `updateExisting: true` to apply mutable drift (settings, `protected`, TTL, project\n * rename). Immutable fields (region, Postgres major version) are always conflicts —\n * recreate the project to change them.\n */\ninterface ConflictReport {\n  kind: \"branch\";\n  identifier: string;\n  field: string;\n  current: unknown;\n  desired: unknown;\n  reason: string;\n}\n/**\n * Result of a `pushConfig` invocation.\n */\ninterface PushResult {\n  projectId: string;\n  orgId?: string;\n  branchId: string;\n  branchName: string;\n  /**\n   * `true` when `pushConfig` was called with `{ dryRun: true }`. `applied` then records\n   * what **would** be applied on a real push; no API mutations were performed.\n   */\n  dryRun: boolean;\n  applied: AppliedChange[];\n  conflicts: ConflictReport[];\n}\n//#endregion\nexport { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConflictReport, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput };\n//# sourceMappingURL=types.d.ts.map"],"mappings":";;;AAKgB;AAEC;AAc6B;AAOjB,KAvBxBA,WAAAA,GA8BAI,IAAa,GAAA,GAAA,GAAA,CAAA,GAAA,CAAA,GAAA,CAAA,GAAA,CAAA;AAAA;KA5BbH,YAAAA,GAmCa,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA;;;;;AAAkF;AAAA;;;;;;AAyC5D;AAAA;AAQlB,KAtEjBC,cAAAA,GA0FkB,GAAA,MAAA,GA1FWD,YA0FX,EAAA;AAAA;AAiCT;AAEqB;AAciC;AACV;AAQjC;AA2BG,KAxKvBE,wBAAAA,GA+K0B,IAAA,GAASe,IAAAA,GAAAA,KAAAA,GAAAA,KAAiB,GAAA,IAAA,GAAA,IAAA,GAAA,KAAA,GAAA,IAAA,GAAA,IAAA;AAAA;AAaI;;;;AAgBS;AAAA,KArMjEd,aAAAA,GA2MY,IAAA,GAAA,IAAaiB,GAAAA,KAAAA,GAAa,IAAA,GAAA,IAAA,GAAA,IAAA,GAAA,KAAA,GAAA,KAAA;AAAA;AAMvB;AAKO;;;;AAmDF,KAlQpBhB,aAkQoB,CAAA,oBAlQcH,cAkQd,CAAA,GAlQgCI,WAkQhC,GAAA,CAlQ+CJ,cAkQ/C,GAlQgEK,WAkQhE,CAAA,OAAA,CAAA,CAAA,GAAA,MAAA;AAAA;AAcL;AAMQ;AAEN;AAWM;;;UA3RlBC,eAAAA,CAuSmBiB;;;;AAEX;AAAA;EAUS,qBAOJ,CAAA,EApTGzB,WAoTH;EAAA;;;;;EACF,qBAAA,CAAA,EA/SKA,WA+SL;EAAA;;;;;;;AAqCI;AAAA;;;;;;AAKd;AAAA;;;;;gBAKuIsC,CAAAA,EAAAA,KAAAA,GAzUvHjC,aAyUuHiC,CAzUzGnC,wBAyUyGmC,CAAAA;;;AAAjB;AAAA;;;;UAjUvH7B,YAAAA,CA+UqGa;;QAAqES,MAAAA;;OAE3KY,MAAAA;;QASGL,EAAAA,OAAAA;;UAEDG,CAAAA,EAAAA,MAAAA;EAAc;;;;;;;;;;;UAxUf/B,aAAAA;;;;;;;;;;;;;;;KAeLC,kBAAAA,aAA+BD;;;;;;;;;;;;;;;UAmB1BI,cAAAA;oBACUN;;;;;;;;;;;;;;cAcNO;KACTC,mBAAAA,WAA8BD;;;;;;;;UAQzBE,eAAAA;;;;;;;;;;;;;;;;;;;;;;;UAuBAC,iBAAAA;;;;aAIGD;;;;;;;UAOHE,qBAAAA,SAA8BD;;;;;;;;;;;;;UAa9BE,yBAAAA,SAAkCF;;;;;;;;;;;;;;;;KAgBvCG,aAAAA,GAAgBF,wBAAwBC;;;;;;KAMxCE,YAAAA,aAAyBD;;;;;;KAMzBE,eAAAA;;;;;UAKKC,iBAAAA;;;;;;;;;;;;;;;;;;;;;;UAsBAC,WAAAA;;;;;;;;;;;;;;;;;;;;;;;;QAwBFC;;;;;QAKAF;;;;;;;;;;;;;;KAcHG,eAAAA;;;;;;KAMAC,uBAAAA;;KAEAC,iBAAAA;;;;;;UAMKC,SAAAA;;;;;WAKCD;;;;;;;;UAQDE,YAAAA;;cAEIpB;;cAEAe,eAAeD;;YAEjBC,eAAeI;;;;;;;;UAQjBE,cAAAA;;YAEET;;;;;;;UAOFU;cACIE,QAAQT,OAAOQ,MAAMF;;;;;;;;UAQzBI;;;;;;;;;;;;;;;;;;;;;;;;;QAyBF/B,cAAcD;;;aAGTU;YACDmB,cAAcC;;;KAGrBG,gCAAgCN,4BAA4BO;;IAE7DE,cAAcD;;;;;KAKbE,+BAA+BV,2BAA2BA,qCAAqCtB,iBAAiB2B,aAAaC,gBAAgBC;;;;;;;;;;;;;;UAcxII,oBAAoB/B,iCAAiCA,gDAAgDW,2BAA2BA,0CAA0CS,2BAA2BA;;SAEtMY;;;;;;;YAOGC;;YAEAN;;WAEDG,eAAeH"}

package/dist/config/dist/v1.d.ts

@@ -0,0 +1,4 @@
+import { BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, ServiceToggle, ServiceToggleInput } from "./lib/types.js";
+import { CreateBranchInput, CreateBucketInput, CreateCredentialInput, CreateProjectInput, DeployFunctionInput, EnableDataApiInput, GetConnectionUriInput, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBranchStorageSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonCredentialSecret, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, UpdateBranchInput } from "./lib/neon-api.js";
+import "zod";
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { FetchEnvOptions, FilteredNeonEnv, FunctionSlugOf, NEON_ENV_VAR_KEYS, NeonAiGatewayEnv, NeonAuthEnv, NeonBranchEnv, NeonDataApiEnv, NeonEnv, NeonFunctionEnv, NeonPostgresEnv, NeonStorageEnv, SelectableEnvKey, fetchEnv, parseEnv, toEntries } from "./lib/env.js";
+export { type FetchEnvOptions, type FilteredNeonEnv, type FunctionSlugOf, NEON_ENV_VAR_KEYS, type NeonAiGatewayEnv, type NeonAuthEnv, type NeonBranchEnv, type NeonDataApiEnv, type NeonEnv, type NeonFunctionEnv, type NeonPostgresEnv, type NeonStorageEnv, type SelectableEnvKey, fetchEnv, parseEnv, toEntries };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { NEON_ENV_VAR_KEYS, fetchEnv, parseEnv, toEntries } from "./lib/env.js";
+export { NEON_ENV_VAR_KEYS, fetchEnv, parseEnv, toEntries };

package/dist/lib/cli/commands.d.ts

@@ -0,0 +1,64 @@
+import { NeonApi } from "../../config/dist/lib/neon-api.js";
+import "../../config/dist/v1.js";
+
+//#region src/lib/cli/commands.d.ts
+
+/**
+ * Cross-cutting environment a CLI command is allowed to touch. Injected so tests can drive
+ * the handler with a custom NeonApi and a controlled `cwd` without spawning child
+ * processes.
+ */
+interface CommandEnv {
+  cwd: string;
+  /**
+   * When set, used directly as the NeonApi. When omitted, the real adapter is built from
+   * `options.apiKey ?? NEON_API_KEY` inside `fetchEnv`.
+   */
+  api?: NeonApi;
+}
+interface CommandResult {
+  /** Process exit code. `0` for success, non-zero for failure. */
+  exitCode: number;
+  /** Text intended for stdout. */
+  stdout: string;
+  /** Text intended for stderr (human-readable status / error messages). */
+  stderr: string;
+  /** Optional structured debug payload — printed only when `--debug` is passed. */
+  debugInfo?: string;
+}
+/**
+ * Inputs needed to resolve a branch and fetch its env, shared by `run` and `export`: an
+ * optional explicit `neon.ts` path, project/branch overrides, and an API key (otherwise
+ * resolved from `.neon` / `NEON_*` env by the CLI and `NEON_API_KEY` by `fetchEnv`).
+ */
+interface EnvResolveOptions {
+  configPath?: string;
+  projectId?: string;
+  branch?: string;
+  apiKey?: string;
+}
+interface EnvRunCommandOptions extends EnvResolveOptions {
+  /** The user command to spawn (after `--`). The first element is the executable. */
+  command: string[];
+}
+/**
+ * Implementation of `neon-env run -- <cmd...>`. Loads `neon.ts`, fetches the env from
+ * Neon, then spawns the user-supplied command with the env vars injected on top of the
+ * inherited `process.env`. Stdio is inherited so interactive dev servers keep working.
+ * The parent process exits with the child's exit code.
+ */
+declare function runEnvRun(options: EnvRunCommandOptions, ctx: CommandEnv): Promise<CommandResult>;
+interface EnvExportCommandOptions extends EnvResolveOptions {
+  /** Output format. `dotenv` (KEY=value lines) by default; `json` for tooling / bulk loaders. */
+  format?: "dotenv" | "json";
+}
+/**
+ * Implementation of `neon-env export`. Resolves the branch's Neon env the same way `run`
+ * does (neon.ts policy + linked branch), then writes it to stdout — as dotenv lines or JSON —
+ * instead of spawning a process, so other env tools can consume it. For example, varlock can
+ * bulk-load it with `@setValuesBulk(exec("neon-env export --format json"), format=json)`.
+ */
+declare function runEnvExport(options: EnvExportCommandOptions, ctx: CommandEnv): Promise<CommandResult>;
+//#endregion
+export { CommandEnv, CommandResult, EnvExportCommandOptions, EnvResolveOptions, EnvRunCommandOptions, runEnvExport, runEnvRun };
+//# sourceMappingURL=commands.d.ts.map

package/dist/lib/cli/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","names":[],"sources":["../../../src/lib/cli/commands.ts"],"mappings":";;;;;;;;AAsBA;AASA;AAgBiB,UAzBA,UAAA,CAyBiB;EAOjB,GAAA,EAAA,MAAA;EAWK;;;;KAGX,CAAA,EAxCJ,OAwCI;;AAAD,UArCO,aAAA,CAqCP;EA4CO;EAWK,QAAA,EAAA,MAAY;EAAA;QACxB,EAAA,MAAA;;QAEC,EAAA,MAAA;;EAAD,SAAA,CAAA,EAAA,MAAA;;;;;;;UA/EO,iBAAA;;;;;;UAOA,oBAAA,SAA6B;;;;;;;;;;iBAWxB,SAAA,UACZ,2BACJ,aACH,QAAQ;UA4CM,uBAAA,SAAgC;;;;;;;;;;iBAW3B,YAAA,UACZ,8BACJ,aACH,QAAQ"}