@neondatabase/config 1.7.3 → 1.8.0

package/dist/lib/types.d.ts

@@ -652,6 +652,264 @@ interface Config<Auth extends ServiceToggleInput | undefined = ServiceToggleInpu
   preview?: Preview;
   /** Per-branch tuning closure. Cannot change the static existential set. */
   branch?: BranchTuningFn<Preview, Functions>;
+  /**
+   * Experimental (unstable) features, isolated in their own namespace so they can change
+   * shape or disappear without touching the rest of the policy. See {@link ExperimentalInput}.
+   */
+  experimental?: ExperimentalInput;
+}
+/**
+ * Experimental (unstable) features. Currently just `hooks`. Kept out of the top-level
+ * namespace — rather than a sibling of `auth` / `functions` / `branch` — as a signal that
+ * this shape is still moving and isn't covered by the same stability guarantees as the rest
+ * of the policy.
+ */
+interface ExperimentalInput {
+  /**
+   * Imperative lifecycle hooks (Preview) — run side effects (migrations, seeding, …) on the
+   * real `checkout` / `deploy` commands. The declarative companion to {@link Config.branch}:
+   * hooks never run during `plan` / `status` / `inspect`, so the diff engine stays sound.
+   * See {@link Hooks}.
+   */
+  hooks?: Hooks;
+}
+/**
+ * Read-only git facts injected into every hook by the CLI. A hook can *read* the git state
+ * (to name a branch, gate a migration, …) but the hooks never *drive* git — that keeps the
+ * git → Neon relationship a loop-free, one-way edge (`git checkout` syncs Neon, never the
+ * reverse). Populated from the surrounding repository; all fields except `available`,
+ * `isDetached`, and `isDirty` are absent when {@link available} is `false` (not a git repo,
+ * or `git` is not installed).
+ *
+ * What *triggered* this hook invocation — the installed git hook vs. an explicit CLI
+ * command — is a separate concern; see {@link CheckoutEvent} / {@link DeployEvent} on each
+ * hook context's `event` field, not this type.
+ */
+interface GitContext {
+  /** `false` when the command did not run inside a git work tree (or `git` is missing). */
+  available: boolean;
+  /** Current branch (`git symbolic-ref --short HEAD`). Undefined in detached-HEAD state. */
+  branch?: string;
+  /**
+   * `branch`, sanitized into a valid Neon branch name: lowercased, each `/`-separated
+   * segment reduced to `[a-z0-9-]`, empty results fall back to `"branch"`, clamped to 256
+   * characters. Undefined whenever `branch` is (detached HEAD, not a git repo, or `git` is
+   * unavailable). Prepend your own prefix with plain string concatenation, e.g.
+   * `` `preview/${git.neonSafeBranchName}` ``.
+   */
+  neonSafeBranchName?: string;
+  /** Full commit SHA of `HEAD`. */
+  sha?: string;
+  /** Abbreviated commit SHA of `HEAD`. */
+  shortSha?: string;
+  /** `true` when `HEAD` is detached (no current branch). */
+  isDetached: boolean;
+  /** `true` when the work tree has uncommitted changes (`git status --porcelain`). */
+  isDirty: boolean;
+  /** Default branch the remote points at (`origin/HEAD`), e.g. `"main"`, when resolvable. */
+  defaultBranch?: string;
+  /** `origin` remote URL, when configured. */
+  remoteUrl?: string;
+  /** Absolute path to the repository root (`git rev-parse --show-toplevel`). */
+  repoRoot?: string;
+}
+/**
+ * What triggered a `checkout` (and the `create` it may perform). `inputName` — what the user
+ * typed at a Neon prompt, if anything — lives *inside* the event so narrowing on `event.type`
+ * narrows `inputName` too (TypeScript only propagates discriminated-union narrowing within
+ * the object actually holding the discriminant, not to sibling fields of an outer object):
+ *
+ * - `"git-checkout"` — the installed `post-checkout` git hook, via `neon git sync`. Carries
+ *   the git branch that triggered it (`gitBranch`); `inputName` is always `undefined` here —
+ *   nothing was typed at a Neon prompt. The sanitized Neon-safe form of that branch is on the
+ *   sibling `git` context, at `git.neonSafeBranchName`.
+ * - `"neon-checkout"` — an explicit `neon checkout` invocation. `inputName` is the name/id
+ *   the user passed, or `undefined` when they omitted it (interactive picker).
+ */
+type CheckoutEvent = {
+  type: "git-checkout";
+  gitBranch: string;
+  inputName?: undefined;
+} | {
+  type: "neon-checkout";
+  inputName?: string;
+};
+/** What triggered a `deploy`. Currently always `"neon-deploy"` — an explicit `neon deploy` / `config apply` invocation; `deploy` is never triggered by the git hook. */
+type DeployEvent = {
+  type: "neon-deploy";
+};
+/**
+ * The branch a hook is acting on — a resolved, live branch (unlike the pre-create
+ * {@link BranchTarget} the `branch` closure may receive). Always carries a concrete `id`.
+ */
+interface HookBranch {
+  /** Neon project id the branch belongs to. */
+  projectId: string;
+  /** Neon branch id (`br-…`). */
+  id: string;
+  /** Branch name. */
+  name: string;
+  /** `true` when **this** operation created the branch (vs selecting an existing one). */
+  created: boolean;
+  /** Whether Neon marks the branch as the project default. */
+  isDefault: boolean;
+  /** Whether Neon marks the branch protected. */
+  isProtected: boolean;
+  /** Parent branch id, when known. */
+  parentId?: string;
+  /** Branch expiration timestamp, when set. */
+  expiresAt?: string;
+}
+/**
+ * A resolved branch's env vars, namespaced like `@neon/env`'s `NeonEnv<C>` — but **not**
+ * generic over the policy. `@neon/config` cannot import the real, policy-exact `NeonEnv<C>`
+ * (it lives in a package that itself depends on `@neon/config`, and importing it back would
+ * be a dependency cycle), so every namespace here is optional regardless of what the policy
+ * declares, rather than conditionally present/absent. `postgres` is the only field every
+ * resolved branch actually has, so it stays the one non-optional namespace.
+ */
+interface HookEnv {
+  postgres: {
+    databaseUrl: string;
+    databaseUrlUnpooled: string;
+  };
+  branch?: {
+    name: string;
+  };
+  auth?: {
+    baseUrl: string;
+    jwksUrl: string;
+  };
+  dataApi?: {
+    url: string;
+  };
+  storage?: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint: string;
+    region: string;
+  };
+  aiGateway?: {
+    apiKey: string;
+    baseUrl: string;
+  };
+  functions?: Record<string, {
+    baseUrl: string;
+  }>;
+}
+/** Context passed to `hooks.checkout.before` (runs before the branch name is resolved). */
+interface CheckoutBeforeContext {
+  event: CheckoutEvent;
+  git: GitContext;
+}
+/**
+ * Return value of a `hooks.checkout.before` **function** hook. Return `{ name }` to rewrite
+ * the branch that will be checked out / created; return nothing to keep the resolved name.
+ * Throw to abort the checkout. (Shell-command `before` hooks cannot rewrite the name — only
+ * abort via a non-zero exit — since they have no return channel.)
+ */
+interface CheckoutBeforeResult {
+  /** Overrides the Neon branch name to check out / create. */
+  name?: string;
+}
+/**
+ * Context passed to `hooks.checkout.after` (branch resolved + env pulled). `env` is
+ * {@link HookEnv} — every namespace optional; see that type for why it can't be the exact,
+ * policy-typed `NeonEnv<C>`.
+ */
+interface CheckoutAfterContext {
+  branch: HookBranch;
+  env: HookEnv;
+  git: GitContext;
+  event: CheckoutEvent;
+}
+/**
+ * Context passed to `hooks.create.before` (runs before a new branch is created). Fires only
+ * for a genuine creation — never for `checkout` selecting an existing branch. Unlike
+ * `checkout.before`, this cannot rename the branch: by the time a `create` is reached, the
+ * name is already resolved (rename via `checkout.before` if you need that).
+ */
+interface CreateBeforeContext {
+  /** Name of the branch about to be created. */
+  branchName: string;
+  git: GitContext;
+  /** The event that triggered the enclosing `checkout` — `create` never runs standalone. */
+  event: CheckoutEvent;
+}
+/** Context passed to `hooks.create.after` (branch created, policy applied, env pulled). `branch.created` is always `true` here. */
+interface CreateAfterContext {
+  branch: HookBranch;
+  env: HookEnv;
+  git: GitContext;
+  event: CheckoutEvent;
+}
+/** Context passed to `hooks.deploy.before` (branch resolved, policy not yet applied). */
+interface DeployBeforeContext {
+  branch: HookBranch;
+  git: GitContext;
+  event: DeployEvent;
+}
+/** Context passed to `hooks.deploy.after` (policy applied, env pulled). */
+interface DeployAfterContext {
+  branch: HookBranch;
+  env: HookEnv;
+  /** What the apply changed. */
+  result: PushResult;
+  git: GitContext;
+  event: DeployEvent;
+}
+/**
+ * A shell-command hook: a single command string, or a list of commands run sequentially
+ * (each must exit 0 or the operation aborts). Commands run **non-interactively** (stdin is
+ * not a TTY and `CI=1` is set) so an accidental interactive command fails fast instead of
+ * hanging. Resolved Neon env vars are injected into the command's environment.
+ */
+type ShellHook = string | string[];
+/**
+ * A lifecycle hook: either a (possibly async) function receiving a typed `Ctx`, or a
+ * {@link ShellHook}. `before` hooks may influence/abort (functions can return `Result`,
+ * any hook can throw to abort); `after` hooks observe (their return value is ignored).
+ */
+type Hook<Ctx, Result = void> = ((ctx: Ctx) => Result | Promise<Result>) | ShellHook;
+/** Hooks for the `checkout` command (`neon checkout`). */
+interface CheckoutHooks {
+  /** Runs before the branch is resolved; may rewrite the name (function form) or abort. */
+  before?: Hook<CheckoutBeforeContext, CheckoutBeforeResult | void>;
+  /** Runs after checkout + env pull. Use `branch.created` to distinguish new vs existing. */
+  after?: Hook<CheckoutAfterContext>;
+}
+/**
+ * Hooks for branch **creation**. Fires only when `checkout` (or another consumer of the
+ * runtime's create operation) actually creates a new branch — not when `checkout` selects
+ * an existing one. Distinct from `checkout`, which brackets the whole `checkout` command
+ * regardless of whether it created or selected a branch: use `create` when you specifically
+ * care about the creation moment.
+ */
+interface CreateHooks {
+  /** Runs before the branch is created; throw/non-zero exit to abort. */
+  before?: Hook<CreateBeforeContext, void>;
+  /** Runs after the branch is created and the policy applied. */
+  after?: Hook<CreateAfterContext>;
+}
+/** Hooks for the `deploy` command (`neon deploy` / `config apply`). */
+interface DeployHooks {
+  /** Runs before the policy is applied; throw/non-zero exit to abort. */
+  before?: Hook<DeployBeforeContext, void>;
+  /** Runs after a successful apply + env pull. */
+  after?: Hook<DeployAfterContext>;
+}
+/**
+ * Imperative lifecycle hooks, keyed by the phase they bracket. Each phase exposes a
+ * `before` (influence/abort) and `after` (observe) hook. Hooks never run during `plan` /
+ * `status` / `inspect`.
+ *
+ * `env` in every `after` hook is the fixed {@link HookEnv}, not a policy-exact type — see
+ * that type's doc comment for why.
+ */
+interface Hooks {
+  checkout?: CheckoutHooks;
+  create?: CreateHooks;
+  deploy?: DeployHooks;
 }
 /**
  * A function with all deploy defaults applied. `resolveConfig` fills in `runtime` so
@@ -819,5 +1077,5 @@ interface PushResult {
   warnings: string[];
 }
 //#endregion
-export { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, COMPUTE_UNITS, ComputeSettings, ComputeUnit, Config, ConflictReport, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, ExternalPackageDef, ExternalPackageEntry, FunctionBundle, FunctionBundler, FunctionBundlerInput, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionScheduleTriggerDef, FunctionStorageObjectCreatedTriggerDef, FunctionTriggerDef, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedExternalPackage, ResolvedFunctionConfig, ResolvedFunctionScheduleTrigger, ResolvedFunctionStorageObjectCreatedTrigger, ResolvedFunctionTrigger, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput };
+export { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, COMPUTE_UNITS, CheckoutAfterContext, CheckoutBeforeContext, CheckoutBeforeResult, CheckoutEvent, CheckoutHooks, ComputeSettings, ComputeUnit, Config, ConflictReport, CreateAfterContext, CreateBeforeContext, CreateHooks, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DeployAfterContext, DeployBeforeContext, DeployEvent, DeployHooks, DurationString, DurationUnit, ExperimentalInput, ExternalPackageDef, ExternalPackageEntry, FunctionBundle, FunctionBundler, FunctionBundlerInput, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionScheduleTriggerDef, FunctionStorageObjectCreatedTriggerDef, FunctionTriggerDef, FunctionTuning, GitContext, Hook, HookBranch, HookEnv, Hooks, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedExternalPackage, ResolvedFunctionConfig, ResolvedFunctionScheduleTrigger, ResolvedFunctionStorageObjectCreatedTrigger, ResolvedFunctionTrigger, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput, ShellHook };
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/lib/types.ts"],"mappings":"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"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/lib/types.ts"],"mappings":";;AAKA;AAKA;AAGA;AAeA;AAQK,cA/BQ,aA+BgB,EAAA,SAAA,CAAA,IAAA,EAAA,GAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,EAAA,CAAA;AAiBxB,KA3CO,WAAA,GA2CM,CAAA,OA3CgB,aA2ChB,CAAA,CAAA,MAAA,CAAA;AAAA;AAQA,KAhDN,YAAA,GAgDM,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA,GAAA;AAAqB;AACpC;AACC;AAAiB;AAAW;AAUhC;AAAgC;AAcP;AASA;AAqBe;AAAd;AAAa;AASvC;AAqBiB,KAvHL,cAAA,GAuHkB,GAAA,MAAA,GAvHW,YAuHX,EAAA;AAgB9B;AAeA;AAA0B;AAAO;AAE7B;AAEC;AAEC,KApJD,wBAAA,GAoJC,IAAA,GAAA,IAAA,GAAA,KAAA,GAAA,KAAA,GAAA,IAAA,GAAA,IAAA,GAAA,KAAA,GAAA,IAAA,GAAA,IAAA;AAEC;AAEC;AAAC;AAIT;AAgBA;AACA;AASA,KArKK,aAAA,GAqKY,IAAe,GAAA,IAAA,GAAA,KAAA,GAAA,IAAA,GAAA,IAAA,GAAA,IAAA,GAAA,KAAA,GAAA,KAAA;AAqB/B;AAeD;AAcA;AAiBA;AAAyB;AAAG;AAAwB,KAhO/C,aAgO+C,CAAA,oBAhOb,cAgOa,CAAA,GA/NjD,WA+NiD,GAAA,CA9NhD,cA8NgD,GA9N/B,WA8N+B,CAAA,OAAA,CAAA,CAAA,GAAA,MAAA;AAAyB;AAQ7E;AAOA;AAMA;AAYA;AAiBA;AAMA;AAQY,UApRK,eAAA,CAoRS;EAAA;AAAkB;AAAf;AAAM;AAGnC;AAA2B;AACtB;AACQ;AAAR;AAAO;AAQZ;AAWA;AAA4B;EAmBrB,qBAAA,CAAA,EAjTkB,WAiTlB;EA8Da;AAUT;AAKJ;AAAiB;AAqBxB;AAA8B;AAC3B;AACA;EAAsC,qBAAA,CAAA,EA5YhB,WA4YgB;EAQxB;AAejB;AAqBA;AAWA;AAGA;AAOA;AAgBA;AAA6B;AAKhB;AAKe;AAAf;AAKa;AAAf;AAAM;AASjB;AAkBA;AAA8B;AAIF;AAAM;AAAb;EAAR,cAAA,CAAA,EAAA,KAAA,GAtfa,aAsfb,CAtf2B,wBAsf3B,CAAA;AAAO;AASpB;AAA6B;AAyBR;AAAd;AAGK;AAEgB;AAAM,UAphBjB,YAAA,CAohBiB;EAAb;EAAR,IAAA,EAAA,MAAA;EAIY;EAAd,EAAA,CAAA,EAAA,MAAA;EAAa;EAInB,MAAA,EAAA,OAAA;EAAoB;EAAY,QAAA,CAAA,EAAA,MAAA;EACpB;EAAd,SAAA,CAAA,EAAA,OAAA;EAAO;EAML,WAAA,CAAA,EAAA,OAAe;EAAA;EAAe,SAAA,CAAA,EAAA,MAAA;AAEC;AAAZ;AAEM;AAAZ;AAAd;AAAO,UAlhBM,aAAA,CAkhBN;EAEN;EAAe,OAAA,CAAA,EAAA,OAAA;AACH;AACiB;AAAf;AACO;AAArB;AAAgD;AAAhB;AAEb;AAArB;AAAgD;AAAhB;AAAe;AAMtC,KA/gBA,kBAAA,GA+gBc,OAAA,GA/gBiB,aA+gBjB;AAAA;AACT;AAA2B;AACV;AAAf;AACN;AAA8C;AAAS;AAAzB;AAAb;AAAY;AAgB1C;AAAuB;AACT,KAphBF,cAohBE,CAAA,CAAA,CAAA,GAAA,CAphBmB,CAohBnB,CAAA,SAAA,CAAA,KAAA,CAAA,GAAA,KAAA,GAAA,CAlhBV,CAkhBU,CAAA,SAAA,CAAA;EACV,OAAA,EAAA,KAAA;AAEa,CAAA,CAAA,GAAA,KAAA,GAAA,CAnhBZ,CAmhBY,CAAA,SAAA,CAAA,SAAA,CAAA,GAAA,KAAA,GAAA,CAjhBX,CAihBW,CAAA,SAAA,CAAA,IAAA,CAAA,GAAA,IAAA,GAAA,CA/gBV,CA+gBU,CAAA,SAAA,CAAA;EAA2B,OAAA,EAAA,IAAA;AAC3B,CAAA,CAAA,GAAA,IAAA,GAAA,CA9gBT,CA8gBS,CAAA,SAAA,CAAA,MAAA,CAAA,GAAA,IAAA,GAAA,KAAA;AAA2B,UA1gB3B,cAAA,CA0gB2B;EACV,eAAA,CAAA,EA1gBf,eA0gBe;AAAf;AACA;AAAf;AAE4B;AAAf;AACE;AAAf;AAEe;AACf;AAII;AAOG;AAIE;AAIA;AAIF,cAzhBE,uBAyhBF,EAAA,SAAA,CAAA,MAAA,EAAA,UAAA,CAAA;AAMgB,KA9hBf,mBAAA,GA8hBe,CAAA,OA9hBe,uBA8hBf,CAAA,CAAA,MAAA,CAAA;AAAf;AAID;AAEc;AAAS;AAAxB;AAKM;AAAiB;AAShB,UAziBA,eAAA,CAyiBiB;EA+BjB;EA0CL,mBAAa,CAAA,EAAA,OAAA;EAKb;EAMK,UAAA,CAAA,EAAU,MAAA;EA2BV;EAmBA,iBAAA,CAAA,EAAA,MAAqB;EAAA;EAC9B,SAAA,CAAA,EAAA,MAAA;EACF;EAAU,SAAA,CAAA,EAAA,MAAA,EAAA;EASC;EAUA,eAAA,CAAA,EAAA,MAAoB;EAAA;EAC5B,mBAAA,CAAA,EAAA,MAAA;EACH;EACA,WAAA,CAAA,EAAA,mBAAA,GAAA,UAAA;EACE;EAAa,wBAAA,CAAA,EAAA,MAAA;EASJ;EAAmB,mBAAA,CAAA,EAAA,OAAA;AAG9B;AAEE;AAAa,UA1rBX,iBAAA,CA0rBW;EAIJ;EAAkB,OAAA,CAAA,EAAA,OAAA;EAC1B;EACH,QAAA,CAAA,EA5rBM,eA4rBN;AACA;AACE;AAAa;AAIrB;AAAoC;AAC3B;AACH,UA5rBW,qBAAA,SAA8B,iBA4rBzC,CAAA;EACE,YAAA,CAAA,EAAA,MAAA;EAAW;EAIF,OAAA,CAAA,EAAA,KAAA;EAAkB;EAC1B,YAAA,CAAA,EAAA,KAAA;EACH;EAEG,WAAA,CAAA,EAAA,KAAA;AACH;AACE;AAAW;AASnB;AAOA;AAAgB,UAzsBC,yBAAA,SAAkC,iBAysBnC,CAAA;EACN,YAAA,EAAA,UAAA;EAAQ;EAAiB,OAAA,CAAA,EAAA,MAAA;EAAR;EACxB,YAAA,CAAA,EAAA,MAAA;EAAS;AAGZ;AAA8B;AAGf;EAAuB,WAAA,CAAA,EAAA,MAAA;AAA5B;AAEI;AAAL;AAAI;AAUb;AAA4B,KA5sBhB,aAAA,GAAgB,qBA4sBA,GA5sBwB,yBA4sBxB;AAEb;AAAL;AAEI;AAAL;AAAI;AAIb;AAA4B,KA5sBhB,YAAA,GA4sBgB,OAAA,GA5sBS,aA4sBT;AAEb;AAAL;AAEI;AAAL;AAAI;AAWI,KAptBL,eAAA,GAotBU,UAAA;AAAA;AACV;AACF;AACA;AAAW,UAjtBJ,iBAAA,CAitBI;EAOJ;AAAsB;AAIjC;AAQc;EACV,IAAA,CAAA,EAAA,MAAA;AACA;AAKH;AAAiB;AAQxB;AAAmC;AAChC,UAxuBc,kBAAA,CAwuBd;EACA;EAA2C,IAAA,EAAA,MAAA;EAE7B;AASjB;AAWA;AAUA;AAAsC;AAC1B;AACF;EAAoB,YAAA,CAAA,EAAA,OAAA;AAU9B;AAAsC;AACvB;AAIH;AAAe;AAGV,KA5wBL,oBAAA,GA4wByB,MAAA,GA5wBO,kBA4wBP;AAAA;AAIzB;AASD;AACA;AAKC,UAzxBK,uBAAA,CAyxBL;EAAuB;EAMlB,IAAA,EAAA,MAAA;EAkBA;EAYA,YAAA,EAAU,OAAA;AAAA;AAUjB;AACE,KAh0BA,cAAA,GAAiB,MAg0BjB,CAAA,MAAA,EAh0BgC,UAg0BhC,CAAA;AAOK;AAAK,KAp0BV,eAAA,GAo0BU,CAAA,EAAA,EAn0BjB,sBAm0BiB,EAAA,GAl0BjB,OAk0BiB,CAl0BT,cAk0BS,CAAA;;;;;;;KA1zBV,oBAAA,wBAA4C;;;;;;;;;;UAWvC,WAAA;;;;;;;;;;;;;;;;;;;QAmBV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8Da;;;;;;;;;;YAUT;;;;;QAKJ;;;;;;;;;;;;;;;;;;;;KAqBK,kBAAA,GACT,6BACA;;;;;;;UAQc,0BAAA;;;;;;;;;;;;;;UAeA,sCAAA;;;;;;;;;;;;;;;;;;;;KAqBL,eAAA;;;;;;KAWA,uBAAA;;KAGA,iBAAA;;;;;;UAOK,SAAA;;;;;WAKP;;;;;;;;;;UAWO,YAAA;;;;;cAKJ;;;;;cAKA,eAAe;;;;;YAKjB,eAAe;;;;;;;;UAST,cAAA;;YAEN;;;;;;;;;;;;;;;UAgBM;;;;cAIJ,QAAQ,OAAO,MAAM;;;;;;;;UASjB;;;;;;;;;;;;;;;;;;;;;;;;;QAyBV,cAAc;;;aAGT;;cAEC,QAAQ,OAAO,MAAM;;;;YAIvB,cAAc;;;KAIpB,gCAAgC;;IAClC,cAAc;KAMZ,8BAA8B,8DAEX,YAAY,qBAEhC,cAAc,YAAY;KAEzB,gCACY,4CACE,eAAe,yCAC7B,qBAAqB,WAAW,gBAAgB,uCAElD,qBAAqB,WAAW,gBAAgB;;;;;KAMvC,+BACK,2BAA2B,4CACzB,eAAe,iDACrB,iBAAiB,aAAa,gBAAgB,SAAS;;;;;;;;;;;;;;;UAgBnD,oBACH,iCACV,gDAEa,2BAA2B,0CAC3B,2BAA2B,4CACzB,eAAe,2BAC9B,eAAe,0CAEF,eAAe,yBAC5B,eAAe,0CAEA,iCACf;;SAII;;;;;;;YAOG;;;;cAIE;;;;cAIA;;;;YAIF;;;;;;aAMC,eAAe;;;;YAIhB;;WAED,eAAe,SAAS;;;;;iBAKlB;;;;;;;;UASC,iBAAA;;;;;;;UAOR;;;;;;;;;;;;;;UAwBQ,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0CL,aAAA;;;;;;;;;KAKA,WAAA;;;;;;;UAMK,UAAA;;;;;;;;;;;;;;;;;;;;;;;;;;UA2BA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;cAeJ;;;;;UAII,qBAAA;SACT;OACF;;;;;;;;UASW,oBAAA;;;;;;;;;UAUA,oBAAA;UACR;OACH;OACA;SACE;;;;;;;;UASS,mBAAA;;;OAGX;;SAEE;;;UAIS,kBAAA;UACR;OACH;OACA;SACE;;;UAIS,mBAAA;UACR;OACH;SACE;;;UAIS,kBAAA;UACR;OACH;;UAEG;OACH;SACE;;;;;;;;KASI,SAAA;;;;;;KAOA,kCACF,QAAQ,SAAS,QAAQ,WAChC;;UAGc,aAAA;;WAGP,KAAK,uBAAuB;;UAE7B,KAAK;;;;;;;;;UAUG,WAAA;;WAEP,KAAK;;UAEN,KAAK;;;UAIG,WAAA;;WAEP,KAAK;;UAEN,KAAK;;;;;;;;;;UAWG,KAAA;aACL;WACF;WACA;;;;;;UAOO,sBAAA;;;;OAIX;;;;;;;;qBAQc;WACV;WACA;;;;;QAKH;;;;;;;KAQK,uBAAA,GACT,kCACA;UAEc,+BAAA;;;;;;;;UASA,2CAAA;;;;;;;;;;UAWA,oBAAA;;UAER;;;;;;;UAQQ,qBAAA;aACL;WACF;;;;;;;;;UAUO,qBAAA;gBACF;;;;aAIH;;UAGK,oBAAA;;;;aAIL;;;;;;;;;YASD;YACA;;;;;aAKC;;;;;UAMK,aAAA;;;;;;;;YAQN;;;;;;;;;UAUM,cAAA;;;;;;;;;;;UAYA,UAAA;;;;;;;;;;WAUP;aACE;;;;;;;kBAOK"}

package/dist/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/lib/types.ts"],"sourcesContent":["/**\n * Every compute size in the Console size table\n * (https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration).\n * Plan availability is enforced by the API, not this list.\n */\nexport const COMPUTE_UNITS = [\n\t0.25, 0.5, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 20,\n\t22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46, 48, 50, 52, 54, 56,\n] as const;\n\nexport type ComputeUnit = (typeof COMPUTE_UNITS)[number];\n\n/** Time units accepted in a {@link DurationString}: seconds, minutes, hours, days, weeks. */\nexport type DurationUnit = \"s\" | \"m\" | \"h\" | \"d\" | \"w\";\n\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 */\nexport type DurationString = `${number}${DurationUnit}`;\n\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 =\n\t| \"1m\"\n\t| \"5m\"\n\t| \"15m\"\n\t| \"30m\"\n\t| \"1h\"\n\t| \"6h\"\n\t| \"12h\"\n\t| \"1d\"\n\t| \"7d\";\n\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/**\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> =\n\t| Suggestions\n\t| (DurationString & NonNullable<unknown>)\n\t| number;\n\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 defaults).\n */\nexport interface ComputeSettings {\n\t/**\n\t * Minimum number of Compute Units. Set to 0.25 for true scale-to-zero.\n\t *\n\t * Sizes above 16 CU are fixed-size only: if this is set with a different\n\t * {@link ComputeSettings.autoscalingLimitMaxCu}, both bounds must be ≤ 16 and\n\t * `max - min` cannot exceed 8 CU. A single bound is checked against the catalog\n\t * only — the other bound comes from the project's default endpoint settings, so\n\t * the API is the arbiter of the resolved pair.\n\t *\n\t * @example 0.25  // scale-to-zero\n\t * @example 1     // always-on with 1 CU minimum\n\t * @example 4\n\t */\n\tautoscalingLimitMinCu?: ComputeUnit;\n\t/**\n\t * Maximum number of Compute Units for autoscaling, or the fixed size when equal\n\t * to {@link ComputeSettings.autoscalingLimitMinCu}.\n\t *\n\t * @example 2\n\t * @example 12\n\t * @example 56  // fixed-size; pair with the same min\n\t */\n\tautoscalingLimitMaxCu?: ComputeUnit;\n\t/**\n\t * How long an idle compute waits before suspending (Neon's scale-to-zero). Accepts a\n\t * {@link DurationString} (autocompletes common values), a number of seconds, or `false`.\n\t *\n\t * - `false` — never suspend (always-on compute)\n\t * - {@link DurationString} — e.g. `\"5m\"`; autocompletes the in-range values `\"1m\"`, `\"5m\"`,\n\t *   `\"15m\"`, `\"30m\"`, `\"1h\"`, `\"6h\"`, `\"12h\"`, `\"1d\"`, `\"7d\"`, and accepts any other\n\t *   `<integer><unit>` (units: `s`, `m`, `h`, `d`, `w`). A **unit is required** — for raw\n\t *   seconds pass a `number`, not a string.\n\t * - `number` — custom timeout in **seconds**, must be in `60`–`604800` (1 minute to 1 week)\n\t * - `undefined` — use the Neon default (currently 300s / 5 minutes)\n\t *\n\t * Whichever form you use, the resolved timeout must fall in `60`–`604800` seconds (the Neon\n\t * API limit); the suggestions are all within that band, anything else is checked at apply.\n\t *\n\t * @example false  // never suspend (always-on)\n\t * @example \"5m\"   // suspend after 5 minutes idle\n\t * @example \"1h\"   // suspend after 1 hour idle\n\t * @example 300    // 5 minutes, expressed in seconds\n\t */\n\tsuspendTimeout?: false | DurationField<SuspendTimeoutSuggestion>;\n}\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 */\nexport interface BranchTarget {\n\t/** Branch name being evaluated. For `branch dev`, this is the generated branch name. */\n\tname: string;\n\t/** Neon branch id when the branch already exists. Undefined during pre-create eval. */\n\tid?: string;\n\t/** Whether this branch already exists on Neon. */\n\texists: boolean;\n\t/** Parent branch id from Neon when known. */\n\tparentId?: string;\n\t/** Whether Neon marks this branch as the project default. */\n\tisDefault?: boolean;\n\t/** Whether Neon currently marks this branch protected. */\n\tisProtected?: boolean;\n\t/** Current expiration timestamp from Neon, when set. */\n\texpiresAt?: string;\n}\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 */\nexport interface ServiceToggle {\n\t/** Defaults to `true` when the service namespace is present. Set `false` to opt out. */\n\tenabled?: boolean;\n}\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 */\nexport type ServiceToggleInput = boolean | ServiceToggle;\n\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 */\nexport type ServiceEnabled<T> = [T] extends [false]\n\t? false\n\t: [T] extends [{ enabled: false }]\n\t\t? false\n\t\t: [T] extends [undefined]\n\t\t\t? false\n\t\t\t: [T] extends [true]\n\t\t\t\t? true\n\t\t\t\t: [T] extends [{ enabled: true }]\n\t\t\t\t\t? true\n\t\t\t\t\t: [T] extends [object]\n\t\t\t\t\t\t? true\n\t\t\t\t\t\t: false;\n\nexport interface PostgresConfig {\n\tcomputeSettings?: ComputeSettings;\n}\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 */\nexport const DATA_API_AUTH_PROVIDERS = [\"neon\", \"external\"] as const;\nexport type DataApiAuthProvider = (typeof DATA_API_AUTH_PROVIDERS)[number];\n\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 */\nexport interface DataApiSettings {\n\t/** Enable the aggregates feature (`db_aggregates_enabled`). Default `true`. */\n\tdbAggregatesEnabled?: boolean;\n\t/** Database role used for anonymous requests (`db_anon_role`). Default `\"anonymous\"`. */\n\tdbAnonRole?: string;\n\t/** Extra schemas appended to the search path (`db_extra_search_path`). */\n\tdbExtraSearchPath?: string;\n\t/** Maximum rows returned in a single request (`db_max_rows`). */\n\tdbMaxRows?: number;\n\t/** Schemas exposed via the API (`db_schemas`). Default `[\"public\"]`. */\n\tdbSchemas?: string[];\n\t/** JWT claim key used for role extraction (`jwt_role_claim_key`). Default `\".role\"`. */\n\tjwtRoleClaimKey?: string;\n\t/** Maximum lifetime of the JWT cache, in seconds (`jwt_cache_max_lifetime`). */\n\tjwtCacheMaxLifetime?: number;\n\t/** OpenAPI spec mode (`openapi_mode`). Default `\"disabled\"`. */\n\topenapiMode?: \"ignore-privileges\" | \"disabled\";\n\t/** CORS allowed origins (`server_cors_allowed_origins`). */\n\tserverCorsAllowedOrigins?: string;\n\t/** Emit server-timing headers (`server_timing_enabled`). */\n\tserverTimingEnabled?: boolean;\n}\n\n/** Fields shared by every {@link DataApiConfig} variant. */\ninterface DataApiConfigBase {\n\t/** Defaults to `true` when the `dataApi` namespace is present. `false` disables and apply deletes. */\n\tenabled?: boolean;\n\t/** Reusable runtime settings. Drift here is reconciled as an update. */\n\tsettings?: DataApiSettings;\n}\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 */\nexport interface DataApiNeonAuthConfig extends DataApiConfigBase {\n\tauthProvider?: \"neon\";\n\t/** Forbidden with `authProvider: \"neon\"` — Neon provides the JWKS URL. */\n\tjwksUrl?: never;\n\t/** Forbidden with `authProvider: \"neon\"` — the provider is Neon Auth. */\n\tproviderName?: never;\n\t/** Forbidden with `authProvider: \"neon\"` — Neon manages the audience. */\n\tjwtAudience?: never;\n}\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 */\nexport interface DataApiExternalAuthConfig extends DataApiConfigBase {\n\tauthProvider: \"external\";\n\t/** URL that publishes the IdP's JWKS (JSON Web Key Set). */\n\tjwksUrl?: string;\n\t/** Human label for the IdP (e.g. \"Clerk\", \"Stytch\", \"Auth0\"). */\n\tproviderName?: string;\n\t/**\n\t * Expected `aud` claim. ⚠️ This only **rejects** tokens carrying a *different* audience;\n\t * tokens with no `aud` claim are still accepted.\n\t */\n\tjwtAudience?: string;\n}\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 */\nexport type DataApiConfig = DataApiNeonAuthConfig | DataApiExternalAuthConfig;\n\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 }` disable it; apply deletes an existing\n * Data API. Omit the field to leave an existing integration alone.\n */\nexport type DataApiInput = boolean | DataApiConfig;\n\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 */\nexport type FunctionRuntime = \"nodejs24\";\n\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 */\nexport interface FunctionDevConfig {\n\t/**\n\t * Port the local server binds. Bound exactly (and `neon dev` fails loudly if it is taken)\n\t * when set; a free port is found automatically when omitted.\n\t */\n\tport?: number;\n}\n\n/**\n * The object form of an {@link FunctionDef.externalPackages} entry, for the one case the\n * bare string cannot express: externalizing a package without shipping its files.\n */\nexport interface ExternalPackageDef {\n\t/** Package name, optionally with a subpath: `sharp`, `@scope/pkg`, `pkg/sub`. */\n\tname: string;\n\t/**\n\t * Whether the package's real files ship into the deployed archive next to the bundle.\n\t *\n\t * Defaults to `true`, which is the state where the import resolves and the function\n\t * works. Set it to `false` only for a package the function never reaches: nothing is\n\t * shipped for it, so reaching it throws `Cannot find module` at invoke.\n\t */\n\tincludeFiles?: boolean;\n}\n\n/**\n * One entry of {@link FunctionDef.externalPackages}. A bare string is the common form and\n * ships the package's files; {@link ExternalPackageDef} exists to turn that off.\n */\nexport type ExternalPackageEntry = string | ExternalPackageDef;\n\n/**\n * An {@link ExternalPackageEntry} with its default applied, as every consumer downstream of\n * `resolveConfig` reads it.\n */\nexport interface ResolvedExternalPackage {\n\t/** Package name as declared, subpath included. */\n\tname: string;\n\t/** Whether this package's files are staged into the archive. */\n\tincludeFiles: boolean;\n}\n\n/** Archive-relative paths. The runtime imports `index.mjs` or `index.js` at the root. */\nexport type FunctionBundle = Record<string, Uint8Array>;\n\n/** Defined here so policy imports stay free of build-time dependencies. */\nexport type FunctionBundler = (\n\tfn: ResolvedFunctionConfig,\n) => Promise<FunctionBundle>;\n\n/**\n * `\"esbuild\"` (default) bundles a file, or a directory from the first of\n * `index.ts`, `index.js`, `index.mjs`. `\"none\"` ships a prebuilt directory or a\n * single `index.mjs` / `index.js`. An inline {@link FunctionBundler} returns the\n * file map.\n */\nexport type FunctionBundlerInput = \"esbuild\" | \"none\" | FunctionBundler;\n\n/**\n * Static definition of a Neon Function. Declares that the function\n * **exists** on every branch; its branch-unique slug is the **record key** in\n * `functions` (or deprecated {@link PreviewInput.functions}), so slugs are statically enumerable,\n * cannot duplicate, and the `branch` closure can only tune slugs that are declared here.\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 */\nexport interface FunctionDef {\n\t/** Free-form display name. @example \"Hello World\" */\n\tname: string;\n\t/**\n\t * Path to the entry module or source directory, relative to `neon.ts` (or\n\t * absolute). A file is the entry; a directory is searched for `index.ts`,\n\t * then `index.js`, then `index.mjs`. A JS function value has no source path\n\t * for a bundler to resolve.\n\t * @example \"./functions/hello-world.ts\"\n\t * @example \".mastra/output\"\n\t */\n\tsource: string;\n\t/**\n\t * Environment variables injected into the deployed function, keyed by the var name the\n\t * function reads at runtime. The **keys** are static (preserved at the type level so\n\t * `parseEnv(config, \"<slug>\").function.<key>` is typed). An unset `process.env.X`\n\t * fails validation. Omit a key to preserve its deployed value; an empty string deletes it.\n\t * @example { resendApiKey: process.env.RESEND_API_KEY! }\n\t */\n\tenv?: Record<string, string>;\n\t/**\n\t * Ship a dependency's real files into the deployed archive instead of bundling it —\n\t * `sharp` and other packages backed by a native binary.\n\t *\n\t * The deploy-time equivalent of Next.js's `serverExternalPackages`. Every entry is passed\n\t * to esbuild's `external`, so the import survives into the bundle instead of being\n\t * followed, and the package's own files are shipped beside the bundle so that import\n\t * resolves.\n\t *\n\t * Reach for this when bundling a package is impossible rather than merely undesirable.\n\t * The case that comes up is a package backed by a native `.node` binary: the binary is a\n\t * compiled object the platform loads from a real path, so no bundler can inline it.\n\t * `sharp` is the common one, and it does not even fail at build time — it loads its\n\t * binary through `createRequire`, which esbuild does not follow, so it bundles cleanly\n\t * and then fails at invoke with \"Could not load the sharp module\".\n\t *\n\t * ```ts\n\t * externalPackages: [\"sharp\"]\n\t * ```\n\t *\n\t * Each declared package is installed for the Functions runtime target — **linux-arm64,\n\t * glibc** — into a throwaway directory, traced for the files it actually reaches, and\n\t * copied into the archive under `node_modules/` with its directory layout preserved. That\n\t * layout is load-bearing rather than cosmetic: a `.node` addon locates its sibling shared\n\t * libraries relative to its own directory, so a flattened tree fails to load.\n\t *\n\t * Your own `node_modules` is never read for these files or modified. Its binaries are\n\t * built for your machine rather than the deploy target, and a cross-platform install does\n\t * not survive your next plain `npm install`, so the target's packages are resolved fresh\n\t * on each deploy.\n\t *\n\t * Requirements, all reported at deploy time rather than at invoke: the package must\n\t * publish a linux-arm64 glibc build (`sharp` and most `@napi-rs/*` packages do; anything\n\t * compiled from source at install time does not), `npm` must be on `PATH`, and the\n\t * archive must stay inside the deploy size limits — native binaries are large.\n\t *\n\t * ### Excluding a package's files\n\t *\n\t * `includeFiles: false` externalizes the import without shipping anything, which is the\n\t * escape hatch for a package that cannot be staged — no build for the target, or too\n\t * large — and that the function never actually reaches:\n\t *\n\t * ```ts\n\t * externalPackages: [\"sharp\", { name: \"canvas\", includeFiles: false }]\n\t * ```\n\t *\n\t * **An excluded package is not resolvable at runtime.** Nothing is shipped for it, so it\n\t * throws `Cannot find module` if the function reaches it. It unblocks an import that is\n\t * never evaluated; it does not make a dependency usable.\n\t *\n\t * Entries are package names, optionally with a subpath (`pkg`, `@scope/pkg`, `pkg/sub`),\n\t * matching esbuild. A relative or absolute path is rejected at validation time: those are\n\t * local modules, and a local module that cannot be bundled is a different problem. Files\n\t * are staged per package, so a subpath narrows what esbuild leaves unresolved without\n\t * narrowing what ships.\n\t *\n\t * Under `neon dev` the list only keeps the package out of the bundle — nothing is\n\t * installed or copied, and it resolves from your own `node_modules` against your host\n\t * architecture, which is what you want locally.\n\t * @example [\"sharp\", { name: \"canvas\", includeFiles: false }]\n\t */\n\texternalPackages?: ExternalPackageEntry[];\n\t/**\n\t * How {@link source} becomes deployable files. Defaults to `\"esbuild\"`.\n\t * `\"none\"` ships a prebuilt directory or `index.mjs` / `index.js` file.\n\t * An inline {@link FunctionBundler} returns the file map used by deploy and\n\t * `neon dev`. Inline functions do not round-trip through inspect or pull and\n\t * must be re-declared.\n\t * @example \"none\"\n\t * @example (fn) => myFrameworkBuild(fn.source)\n\t */\n\tbundler?: FunctionBundlerInput;\n\t/**\n\t * Local-development settings used by `neon dev` when serving every function from\n\t * `neon.ts`. Ignored at deploy time. See {@link FunctionDevConfig}.\n\t */\n\tdev?: FunctionDevConfig;\n\t/**\n\t * Customer-owned hostnames that should point at this function (beta).\n\t * v1 only supports functions. Hostnames are unique across functions in the resolved\n\t * policy. Applied after the function is deployed, on the project's default branch.\n\t * Other branches apply a list only when {@link FunctionTuning.customDomains} sets one.\n\t * Domains that exist remotely but are omitted here are left alone — delete with\n\t * `neon function domains delete`.\n\t *\n\t * @example [\"docs.example.com\"]\n\t */\n\tcustomDomains?: string[];\n}\n\n/**\n * A trigger that invokes a function. The trigger name is the record key in\n * {@link Config.triggers}. `functionPath` defaults to `/`. `enabled` defaults to `true`.\n *\n * @example { type: \"schedule\", function: \"cron\", cron: \"0 * * * *\" }\n * @example { type: \"storage_object_created\", function: \"ingest\", bucket: \"assets\", prefix: \"logos/\" }\n */\nexport type FunctionTriggerDef =\n\t| FunctionScheduleTriggerDef\n\t| FunctionStorageObjectCreatedTriggerDef;\n\n/**\n * A cron schedule that invokes a function. `function` is a slug from {@link Config.functions}\n * (or deprecated `preview.functions`). `cron` is a numeric five-field expression in UTC.\n *\n * @example { type: \"schedule\", function: \"cron\", cron: \"0 * * * *\" }\n */\nexport interface FunctionScheduleTriggerDef {\n\ttype: \"schedule\";\n\tfunction: string;\n\tcron: string;\n\tfunctionPath?: string;\n\tenabled?: boolean;\n}\n\n/**\n * Invokes a function when an object is created in a bucket from {@link Config.buckets}\n * (or deprecated `preview.buckets`). `prefix` is an exact object-key prefix; omit it to\n * match every key in the bucket.\n *\n * @example { type: \"storage_object_created\", function: \"ingest\", bucket: \"assets\", prefix: \"logos/\" }\n */\nexport interface FunctionStorageObjectCreatedTriggerDef {\n\ttype: \"storage_object_created\";\n\tfunction: string;\n\tbucket: string;\n\tprefix?: string;\n\tfunctionPath?: string;\n\tenabled?: boolean;\n}\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 */\nexport type CredentialScope =\n\t| \"storage:read\"\n\t| \"storage:write\"\n\t| \"ai_gateway:invoke\"\n\t| \"functions:invoke\";\n\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 */\nexport type CredentialPrincipalType = \"user\" | \"function\";\n\n/** Anonymous-access level for a branchable object-storage bucket. */\nexport type BucketAccessLevel = \"private\" | \"public_read\";\n\n/**\n * Static definition of a branchable object-storage bucket. The bucket's\n * name is the **record key** in `buckets` (or deprecated {@link PreviewInput.buckets}), so names are statically\n * enumerable and cannot duplicate.\n */\nexport interface BucketDef {\n\t/**\n\t * Anonymous access level. `private` (default) requires authenticated reads/writes;\n\t * `public_read` allows anonymous GetObject/HeadObject.\n\t */\n\taccess?: BucketAccessLevel;\n}\n\n/**\n * Deprecated home for AI Gateway, Functions, and Object Storage.\n *\n * Those services are GA as top-level `aiGateway`, `functions`, and `buckets`.\n * A `preview` block still works; deploy/apply warns that the keys can be lifted.\n *\n * @deprecated Use top-level `aiGateway`, `functions`, and `buckets`.\n */\nexport interface PreviewInput {\n\t/**\n\t * Enable/disable the AI Gateway on the branch (toggle, like auth / dataApi).\n\t * @deprecated Use top-level `aiGateway`.\n\t */\n\taiGateway?: ServiceToggleInput;\n\t/**\n\t * Functions to deploy, keyed by branch-unique slug (`^[a-z0-9]{1,20}$`).\n\t * @deprecated Use top-level `functions`.\n\t */\n\tfunctions?: Record<string, FunctionDef>;\n\t/**\n\t * Object-storage buckets to create, keyed by bucket name.\n\t * @deprecated Use top-level `buckets`.\n\t */\n\tbuckets?: Record<string, BucketDef>;\n}\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 — so the static secret/function set stays sound. Runtime selection\n * and the custom-domain list may vary per branch.\n */\nexport interface FunctionTuning {\n\t/** Runtime to execute the function with. Defaults to `\"nodejs24\"`. */\n\truntime?: FunctionRuntime;\n\t/**\n\t * When present, replaces {@link FunctionDef.customDomains} for this branch.\n\t * `[]` registers nothing on this branch. Omit the key: the default branch\n\t * inherits the static list; other branches do not.\n\t */\n\tcustomDomains?: string[];\n}\n\n/**\n * Per-branch tuning of functions under the deprecated `preview` key.\n * Only existing function slugs may be tuned — `Slug` is constrained to the\n * declared keys by {@link BranchTuningFn}.\n *\n * @deprecated Use top-level `branch: (branch) => ({ functions: { … } })`.\n */\nexport interface PreviewTuning<Slug extends string = string> {\n\t/**\n\t * @deprecated Use top-level `functions` on the object returned by `branch`.\n\t */\n\tfunctions?: Partial<Record<Slug, FunctionTuning>>;\n}\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 */\nexport interface BranchTuning<Slug extends string = string> {\n\t/** Parent branch name used when creating a new branch. Not a Postgres setting. */\n\tparent?: string;\n\t/**\n\t * Branch time-to-live: how long after creation the branch should auto-expire. Applied\n\t * when creating a new branch and reconciled on existing branches (when `updateExisting`\n\t * is set). Accepts a {@link DurationString} (autocompletes common values) or a number of\n\t * seconds. Omit to keep the branch indefinitely.\n\t *\n\t * - {@link DurationString} — e.g. `\"7d\"`; autocompletes `\"1h\"`, `\"6h\"`, `\"12h\"`, `\"1d\"`,\n\t *   `\"3d\"`, `\"7d\"`, `\"14d\"`, `\"30d\"`, and accepts any other `<integer><unit>` (units: `s`,\n\t *   `m`, `h`, `d`, `w` — e.g. `\"12h\"`, `\"2w\"`). A **unit is required** — `\"7\"` is rejected;\n\t *   for raw seconds pass a `number`.\n\t * - `number` — custom TTL in **seconds** (e.g. `3600`)\n\t * - `undefined` — no expiry; the branch persists until explicitly deleted\n\t *\n\t * The Neon API caps branch expiration at **30 days** from creation, so the resolved TTL must\n\t * be `> 0` and `<= 30d`; the suggestions stay within that limit and anything longer is\n\t * rejected at apply.\n\t *\n\t * @example \"1d\"   // ephemeral preview branch: expires a day after creation\n\t * @example \"7d\"   // one-week TTL\n\t * @example \"30d\"  // the maximum the API allows\n\t * @example 3600   // 1 hour, expressed in seconds\n\t */\n\tttl?: DurationField<TtlSuggestion>;\n\t/** Whether the selected branch should be protected. Undefined means \"leave as-is\". */\n\tprotected?: boolean;\n\tpostgres?: PostgresConfig;\n\t/** Per-function deploy tuning, keyed by declared slug. */\n\tfunctions?: Partial<Record<Slug, FunctionTuning>>;\n\t/**\n\t * @deprecated Use top-level `functions` on this object.\n\t */\n\tpreview?: PreviewTuning<Slug>;\n}\n\n/** Extract declared function slugs from top-level `functions` and/or `preview.functions`. */\ntype PreviewFunctionSlugs<Preview> = Preview extends { functions: infer F }\n\t? Extract<keyof F, string>\n\t: never;\n\n// Config's Functions default is `Record<string, FunctionDef> | undefined`. A string\n// index would otherwise union into FunctionSlugsOf as `string` and drop slug checking\n// on positional `Config<Auth, DataApi, Preview>`.\ntype GaFunctionSlugs<Functions> = [Functions] extends [undefined]\n\t? never\n\t: string extends keyof NonNullable<Functions>\n\t\t? never\n\t\t: Extract<keyof NonNullable<Functions>, string>;\n\ntype FunctionSlugsOf<\n\tPreview extends PreviewInput | undefined,\n\tFunctions extends Record<string, FunctionDef> | undefined = undefined,\n> = [PreviewFunctionSlugs<Preview> | GaFunctionSlugs<Functions>] extends [never]\n\t? string\n\t: PreviewFunctionSlugs<Preview> | GaFunctionSlugs<Functions>;\n\n/**\n * Signature of the `branch` closure. Generic over the static function homes so the\n * `functions` keys it may tune are constrained to the slugs actually declared.\n */\nexport type BranchTuningFn<\n\tPreview extends PreviewInput | undefined = PreviewInput | undefined,\n\tFunctions extends Record<string, FunctionDef> | undefined = undefined,\n> = (branch: BranchTarget) => BranchTuning<FunctionSlugsOf<Preview, Functions>>;\n\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 service toggles and records) and a\n * **dynamic** per-branch `branch` closure for tuning. The static half is what makes the\n * secret set — and therefore `NeonEnv<typeof config>` and `parseEnv` — exact; the closure\n * can tune but never change what exists.\n *\n * Generic over the 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. The first three type parameters stay `Auth`, `DataApi`, `Preview`\n * so existing positional `Config<Auth, DataApi, Preview>` consumers keep compiling.\n */\nexport interface Config<\n\tAuth extends ServiceToggleInput | undefined =\n\t\t| ServiceToggleInput\n\t\t| undefined,\n\tDataApi extends DataApiInput | undefined = DataApiInput | undefined,\n\tPreview extends PreviewInput | undefined = PreviewInput | undefined,\n\tFunctions extends Record<string, FunctionDef> | undefined =\n\t\t| Record<string, FunctionDef>\n\t\t| undefined,\n\tBuckets extends Record<string, BucketDef> | undefined =\n\t\t| Record<string, BucketDef>\n\t\t| undefined,\n\tAiGateway extends ServiceToggleInput | undefined =\n\t\t| ServiceToggleInput\n\t\t| undefined,\n> {\n\t/** Neon Auth integration toggle (GA). Static — drives `NeonEnv.auth`. */\n\tauth?: Auth;\n\t/**\n\t * Neon Data API integration (GA). Static — drives `NeonEnv.dataApi`. A boolean/toggle, or\n\t * a {@link DataApiConfig} object selecting the auth provider (`\"neon\"` / `\"external\"`) and\n\t * runtime {@link DataApiSettings}. With `authProvider: \"neon\"` the policy must also enable\n\t * top-level `auth`.\n\t */\n\tdataApi?: DataApi;\n\t/**\n\t * AI Gateway toggle (GA). Static — drives `NeonEnv.aiGateway`. Same shapes as `auth`.\n\t */\n\taiGateway?: AiGateway;\n\t/**\n\t * Functions to deploy, keyed by branch-unique slug (`^[a-z0-9]{1,20}$`).\n\t */\n\tfunctions?: Functions;\n\t/**\n\t * Object-storage buckets to create, keyed by bucket name.\n\t */\n\tbuckets?: Buckets;\n\t/**\n\t * Function triggers, keyed by branch-unique name. Each value names the function\n\t * (and, for `storage_object_created`, the bucket) it binds. Applied after functions\n\t * are deployed. Triggers that exist remotely but are omitted here are left alone.\n\t */\n\ttriggers?: Record<string, FunctionTriggerDef>;\n\t/**\n\t * @deprecated Use top-level `aiGateway`, `functions`, and `buckets`.\n\t */\n\tpreview?: Preview;\n\t/** Per-branch tuning closure. Cannot change the static existential set. */\n\tbranch?: BranchTuningFn<Preview, Functions>;\n}\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 */\nexport interface ResolvedFunctionConfig {\n\tslug: string;\n\tname: string;\n\tsource: string;\n\tenv: Record<string, string>;\n\t/**\n\t * Packages the bundler leaves unresolved, normalized from\n\t * {@link FunctionDef.externalPackages} with `includeFiles` defaulted.\n\t *\n\t * Absent rather than empty when undeclared, so a policy that never mentions it takes the\n\t * pre-existing bundling path and produces the archive it always did.\n\t */\n\texternalPackages?: ResolvedExternalPackage[];\n\truntime: FunctionRuntime;\n\tbundler: FunctionBundlerInput;\n\t/**\n\t * Local-development settings, passed through untouched from {@link FunctionDef.dev}\n\t * (no defaults applied). Only consumed by `neon dev`; deploy ignores it.\n\t */\n\tdev?: FunctionDevConfig;\n\t/**\n\t * Normalized hostnames this function should own on the branch. Absent when this\n\t * branch has no list to apply. Empty when tuning replaced the list with `[]`.\n\t */\n\tcustomDomains?: string[];\n}\n\nexport type ResolvedFunctionTrigger =\n\t| ResolvedFunctionScheduleTrigger\n\t| ResolvedFunctionStorageObjectCreatedTrigger;\n\nexport interface ResolvedFunctionScheduleTrigger {\n\ttype: \"schedule\";\n\tname: string;\n\tfunctionSlug: string;\n\tcron: string;\n\tfunctionPath: string;\n\tenabled: boolean;\n}\n\nexport interface ResolvedFunctionStorageObjectCreatedTrigger {\n\ttype: \"storage_object_created\";\n\tname: string;\n\tfunctionSlug: string;\n\tbucketName: string;\n\tprefix?: string;\n\tfunctionPath: string;\n\tenabled: boolean;\n}\n\n/** A bucket with its access level defaulted to `private`. */\nexport interface ResolvedBucketConfig {\n\tname: string;\n\taccess: BucketAccessLevel;\n}\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 */\nexport interface ResolvedPreviewConfig {\n\tfunctions: ResolvedFunctionConfig[];\n\tbuckets: ResolvedBucketConfig[];\n\taiGatewayEnabled: boolean;\n}\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 */\nexport interface ResolvedDataApiConfig {\n\tauthProvider: DataApiAuthProvider;\n\tjwksUrl?: string;\n\tproviderName?: string;\n\tjwtAudience?: string;\n\tsettings?: DataApiSettings;\n}\n\nexport interface ResolvedBranchConfig {\n\tparent?: string;\n\tttlSeconds?: number;\n\tprotected?: boolean;\n\tpostgres?: PostgresConfig;\n\tauthEnabled: boolean;\n\tdataApiEnabled: boolean;\n\t/** Optional for compatibility with hand-built configs. */\n\tdataApiPolicy?: \"omitted\" | \"enabled\" | \"disabled\";\n\t/**\n\t * Resolved Data API integration. Present iff {@link dataApiEnabled} is `true`. Carries the\n\t * create-time auth wiring and the updatable {@link DataApiSettings}.\n\t */\n\tdataApi?: ResolvedDataApiConfig;\n\tpreview?: ResolvedPreviewConfig;\n\t/**\n\t * Resolved triggers from {@link Config.triggers}. Absent when none are declared\n\t * (hand-built configs may omit it).\n\t */\n\ttriggers?: ResolvedFunctionTrigger[];\n}\n\n/**\n * One concrete change `pushConfig` made (or, in dry-run, would make) on the remote.\n */\nexport interface AppliedChange {\n\t/**\n\t * `service` covers branch-scoped integrations driven by the branch policy (e.g.\n\t * Neon Auth, Data API).\n\t */\n\tkind: \"branch\" | \"service\";\n\taction: \"create\" | \"update\" | \"delete\" | \"noop\";\n\tidentifier: string;\n\tdetails?: Record<string, unknown>;\n}\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 */\nexport interface ConflictReport {\n\tkind: \"branch\";\n\tidentifier: string;\n\tfield: string;\n\tcurrent: unknown;\n\tdesired: unknown;\n\treason: string;\n}\n\n/**\n * Result of a `pushConfig` invocation.\n */\nexport interface PushResult {\n\tprojectId: string;\n\torgId?: string;\n\tbranchId: string;\n\tbranchName: string;\n\t/**\n\t * `true` when `pushConfig` was called with `{ dryRun: true }`. `applied` then records\n\t * what **would** be applied on a real push; no API mutations were performed.\n\t */\n\tdryRun: boolean;\n\tapplied: AppliedChange[];\n\tconflicts: ConflictReport[];\n\t/**\n\t * Declared custom domains for this branch after the push (or what apply would\n\t * leave in place). `cnameTarget` is omitted when the domain is not registered yet\n\t * (dry-run of a new registration). An empty string means the region has no\n\t * custom-domains front door.\n\t */\n\tcustomDomains?: Array<{\n\t\tdomain: string;\n\t\tslug: string;\n\t\tcnameTarget?: string;\n\t}>;\n\t/**\n\t * Advisory findings from the push — a function that bundles a native dependency it never\n\t * declared, or a staged package whose version could not be pinned.\n\t *\n\t * Returned rather than logged, because a library has no business choosing an output\n\t * channel, and returned rather than left to an opt-in callback, because these are the\n\t * only warning that a deployed function will fail at invoke and an unregistered callback\n\t * is easy to never notice. Empty when there is nothing to report.\n\t *\n\t * Only populated by the built-in bundler: a caller that injects its own `bundleFunction`\n\t * owns its own reporting.\n\t */\n\twarnings: string[];\n}\n"],"mappings":";;;;;;AAKA,MAAa,gBAAgB;CAC5B;CAAM;CAAK;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CACtE;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;AACrE;;;;;;;;;;;;;AAwMA,MAAa,0BAA0B,CAAC,QAAQ,UAAU"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/lib/types.ts"],"sourcesContent":["/**\n * Every compute size in the Console size table\n * (https://neon.com/docs/manage/endpoints#compute-size-and-autoscaling-configuration).\n * Plan availability is enforced by the API, not this list.\n */\nexport const COMPUTE_UNITS = [\n\t0.25, 0.5, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 18, 20,\n\t22, 24, 26, 28, 30, 32, 34, 36, 38, 40, 42, 44, 46, 48, 50, 52, 54, 56,\n] as const;\n\nexport type ComputeUnit = (typeof COMPUTE_UNITS)[number];\n\n/** Time units accepted in a {@link DurationString}: seconds, minutes, hours, days, weeks. */\nexport type DurationUnit = \"s\" | \"m\" | \"h\" | \"d\" | \"w\";\n\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 */\nexport type DurationString = `${number}${DurationUnit}`;\n\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 =\n\t| \"1m\"\n\t| \"5m\"\n\t| \"15m\"\n\t| \"30m\"\n\t| \"1h\"\n\t| \"6h\"\n\t| \"12h\"\n\t| \"1d\"\n\t| \"7d\";\n\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/**\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> =\n\t| Suggestions\n\t| (DurationString & NonNullable<unknown>)\n\t| number;\n\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 defaults).\n */\nexport interface ComputeSettings {\n\t/**\n\t * Minimum number of Compute Units. Set to 0.25 for true scale-to-zero.\n\t *\n\t * Sizes above 16 CU are fixed-size only: if this is set with a different\n\t * {@link ComputeSettings.autoscalingLimitMaxCu}, both bounds must be ≤ 16 and\n\t * `max - min` cannot exceed 8 CU. A single bound is checked against the catalog\n\t * only — the other bound comes from the project's default endpoint settings, so\n\t * the API is the arbiter of the resolved pair.\n\t *\n\t * @example 0.25  // scale-to-zero\n\t * @example 1     // always-on with 1 CU minimum\n\t * @example 4\n\t */\n\tautoscalingLimitMinCu?: ComputeUnit;\n\t/**\n\t * Maximum number of Compute Units for autoscaling, or the fixed size when equal\n\t * to {@link ComputeSettings.autoscalingLimitMinCu}.\n\t *\n\t * @example 2\n\t * @example 12\n\t * @example 56  // fixed-size; pair with the same min\n\t */\n\tautoscalingLimitMaxCu?: ComputeUnit;\n\t/**\n\t * How long an idle compute waits before suspending (Neon's scale-to-zero). Accepts a\n\t * {@link DurationString} (autocompletes common values), a number of seconds, or `false`.\n\t *\n\t * - `false` — never suspend (always-on compute)\n\t * - {@link DurationString} — e.g. `\"5m\"`; autocompletes the in-range values `\"1m\"`, `\"5m\"`,\n\t *   `\"15m\"`, `\"30m\"`, `\"1h\"`, `\"6h\"`, `\"12h\"`, `\"1d\"`, `\"7d\"`, and accepts any other\n\t *   `<integer><unit>` (units: `s`, `m`, `h`, `d`, `w`). A **unit is required** — for raw\n\t *   seconds pass a `number`, not a string.\n\t * - `number` — custom timeout in **seconds**, must be in `60`–`604800` (1 minute to 1 week)\n\t * - `undefined` — use the Neon default (currently 300s / 5 minutes)\n\t *\n\t * Whichever form you use, the resolved timeout must fall in `60`–`604800` seconds (the Neon\n\t * API limit); the suggestions are all within that band, anything else is checked at apply.\n\t *\n\t * @example false  // never suspend (always-on)\n\t * @example \"5m\"   // suspend after 5 minutes idle\n\t * @example \"1h\"   // suspend after 1 hour idle\n\t * @example 300    // 5 minutes, expressed in seconds\n\t */\n\tsuspendTimeout?: false | DurationField<SuspendTimeoutSuggestion>;\n}\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 */\nexport interface BranchTarget {\n\t/** Branch name being evaluated. For `branch dev`, this is the generated branch name. */\n\tname: string;\n\t/** Neon branch id when the branch already exists. Undefined during pre-create eval. */\n\tid?: string;\n\t/** Whether this branch already exists on Neon. */\n\texists: boolean;\n\t/** Parent branch id from Neon when known. */\n\tparentId?: string;\n\t/** Whether Neon marks this branch as the project default. */\n\tisDefault?: boolean;\n\t/** Whether Neon currently marks this branch protected. */\n\tisProtected?: boolean;\n\t/** Current expiration timestamp from Neon, when set. */\n\texpiresAt?: string;\n}\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 */\nexport interface ServiceToggle {\n\t/** Defaults to `true` when the service namespace is present. Set `false` to opt out. */\n\tenabled?: boolean;\n}\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 */\nexport type ServiceToggleInput = boolean | ServiceToggle;\n\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 */\nexport type ServiceEnabled<T> = [T] extends [false]\n\t? false\n\t: [T] extends [{ enabled: false }]\n\t\t? false\n\t\t: [T] extends [undefined]\n\t\t\t? false\n\t\t\t: [T] extends [true]\n\t\t\t\t? true\n\t\t\t\t: [T] extends [{ enabled: true }]\n\t\t\t\t\t? true\n\t\t\t\t\t: [T] extends [object]\n\t\t\t\t\t\t? true\n\t\t\t\t\t\t: false;\n\nexport interface PostgresConfig {\n\tcomputeSettings?: ComputeSettings;\n}\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 */\nexport const DATA_API_AUTH_PROVIDERS = [\"neon\", \"external\"] as const;\nexport type DataApiAuthProvider = (typeof DATA_API_AUTH_PROVIDERS)[number];\n\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 */\nexport interface DataApiSettings {\n\t/** Enable the aggregates feature (`db_aggregates_enabled`). Default `true`. */\n\tdbAggregatesEnabled?: boolean;\n\t/** Database role used for anonymous requests (`db_anon_role`). Default `\"anonymous\"`. */\n\tdbAnonRole?: string;\n\t/** Extra schemas appended to the search path (`db_extra_search_path`). */\n\tdbExtraSearchPath?: string;\n\t/** Maximum rows returned in a single request (`db_max_rows`). */\n\tdbMaxRows?: number;\n\t/** Schemas exposed via the API (`db_schemas`). Default `[\"public\"]`. */\n\tdbSchemas?: string[];\n\t/** JWT claim key used for role extraction (`jwt_role_claim_key`). Default `\".role\"`. */\n\tjwtRoleClaimKey?: string;\n\t/** Maximum lifetime of the JWT cache, in seconds (`jwt_cache_max_lifetime`). */\n\tjwtCacheMaxLifetime?: number;\n\t/** OpenAPI spec mode (`openapi_mode`). Default `\"disabled\"`. */\n\topenapiMode?: \"ignore-privileges\" | \"disabled\";\n\t/** CORS allowed origins (`server_cors_allowed_origins`). */\n\tserverCorsAllowedOrigins?: string;\n\t/** Emit server-timing headers (`server_timing_enabled`). */\n\tserverTimingEnabled?: boolean;\n}\n\n/** Fields shared by every {@link DataApiConfig} variant. */\ninterface DataApiConfigBase {\n\t/** Defaults to `true` when the `dataApi` namespace is present. `false` disables and apply deletes. */\n\tenabled?: boolean;\n\t/** Reusable runtime settings. Drift here is reconciled as an update. */\n\tsettings?: DataApiSettings;\n}\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 */\nexport interface DataApiNeonAuthConfig extends DataApiConfigBase {\n\tauthProvider?: \"neon\";\n\t/** Forbidden with `authProvider: \"neon\"` — Neon provides the JWKS URL. */\n\tjwksUrl?: never;\n\t/** Forbidden with `authProvider: \"neon\"` — the provider is Neon Auth. */\n\tproviderName?: never;\n\t/** Forbidden with `authProvider: \"neon\"` — Neon manages the audience. */\n\tjwtAudience?: never;\n}\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 */\nexport interface DataApiExternalAuthConfig extends DataApiConfigBase {\n\tauthProvider: \"external\";\n\t/** URL that publishes the IdP's JWKS (JSON Web Key Set). */\n\tjwksUrl?: string;\n\t/** Human label for the IdP (e.g. \"Clerk\", \"Stytch\", \"Auth0\"). */\n\tproviderName?: string;\n\t/**\n\t * Expected `aud` claim. ⚠️ This only **rejects** tokens carrying a *different* audience;\n\t * tokens with no `aud` claim are still accepted.\n\t */\n\tjwtAudience?: string;\n}\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 */\nexport type DataApiConfig = DataApiNeonAuthConfig | DataApiExternalAuthConfig;\n\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 }` disable it; apply deletes an existing\n * Data API. Omit the field to leave an existing integration alone.\n */\nexport type DataApiInput = boolean | DataApiConfig;\n\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 */\nexport type FunctionRuntime = \"nodejs24\";\n\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 */\nexport interface FunctionDevConfig {\n\t/**\n\t * Port the local server binds. Bound exactly (and `neon dev` fails loudly if it is taken)\n\t * when set; a free port is found automatically when omitted.\n\t */\n\tport?: number;\n}\n\n/**\n * The object form of an {@link FunctionDef.externalPackages} entry, for the one case the\n * bare string cannot express: externalizing a package without shipping its files.\n */\nexport interface ExternalPackageDef {\n\t/** Package name, optionally with a subpath: `sharp`, `@scope/pkg`, `pkg/sub`. */\n\tname: string;\n\t/**\n\t * Whether the package's real files ship into the deployed archive next to the bundle.\n\t *\n\t * Defaults to `true`, which is the state where the import resolves and the function\n\t * works. Set it to `false` only for a package the function never reaches: nothing is\n\t * shipped for it, so reaching it throws `Cannot find module` at invoke.\n\t */\n\tincludeFiles?: boolean;\n}\n\n/**\n * One entry of {@link FunctionDef.externalPackages}. A bare string is the common form and\n * ships the package's files; {@link ExternalPackageDef} exists to turn that off.\n */\nexport type ExternalPackageEntry = string | ExternalPackageDef;\n\n/**\n * An {@link ExternalPackageEntry} with its default applied, as every consumer downstream of\n * `resolveConfig` reads it.\n */\nexport interface ResolvedExternalPackage {\n\t/** Package name as declared, subpath included. */\n\tname: string;\n\t/** Whether this package's files are staged into the archive. */\n\tincludeFiles: boolean;\n}\n\n/** Archive-relative paths. The runtime imports `index.mjs` or `index.js` at the root. */\nexport type FunctionBundle = Record<string, Uint8Array>;\n\n/** Defined here so policy imports stay free of build-time dependencies. */\nexport type FunctionBundler = (\n\tfn: ResolvedFunctionConfig,\n) => Promise<FunctionBundle>;\n\n/**\n * `\"esbuild\"` (default) bundles a file, or a directory from the first of\n * `index.ts`, `index.js`, `index.mjs`. `\"none\"` ships a prebuilt directory or a\n * single `index.mjs` / `index.js`. An inline {@link FunctionBundler} returns the\n * file map.\n */\nexport type FunctionBundlerInput = \"esbuild\" | \"none\" | FunctionBundler;\n\n/**\n * Static definition of a Neon Function. Declares that the function\n * **exists** on every branch; its branch-unique slug is the **record key** in\n * `functions` (or deprecated {@link PreviewInput.functions}), so slugs are statically enumerable,\n * cannot duplicate, and the `branch` closure can only tune slugs that are declared here.\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 */\nexport interface FunctionDef {\n\t/** Free-form display name. @example \"Hello World\" */\n\tname: string;\n\t/**\n\t * Path to the entry module or source directory, relative to `neon.ts` (or\n\t * absolute). A file is the entry; a directory is searched for `index.ts`,\n\t * then `index.js`, then `index.mjs`. A JS function value has no source path\n\t * for a bundler to resolve.\n\t * @example \"./functions/hello-world.ts\"\n\t * @example \".mastra/output\"\n\t */\n\tsource: string;\n\t/**\n\t * Environment variables injected into the deployed function, keyed by the var name the\n\t * function reads at runtime. The **keys** are static (preserved at the type level so\n\t * `parseEnv(config, \"<slug>\").function.<key>` is typed). An unset `process.env.X`\n\t * fails validation. Omit a key to preserve its deployed value; an empty string deletes it.\n\t * @example { resendApiKey: process.env.RESEND_API_KEY! }\n\t */\n\tenv?: Record<string, string>;\n\t/**\n\t * Ship a dependency's real files into the deployed archive instead of bundling it —\n\t * `sharp` and other packages backed by a native binary.\n\t *\n\t * The deploy-time equivalent of Next.js's `serverExternalPackages`. Every entry is passed\n\t * to esbuild's `external`, so the import survives into the bundle instead of being\n\t * followed, and the package's own files are shipped beside the bundle so that import\n\t * resolves.\n\t *\n\t * Reach for this when bundling a package is impossible rather than merely undesirable.\n\t * The case that comes up is a package backed by a native `.node` binary: the binary is a\n\t * compiled object the platform loads from a real path, so no bundler can inline it.\n\t * `sharp` is the common one, and it does not even fail at build time — it loads its\n\t * binary through `createRequire`, which esbuild does not follow, so it bundles cleanly\n\t * and then fails at invoke with \"Could not load the sharp module\".\n\t *\n\t * ```ts\n\t * externalPackages: [\"sharp\"]\n\t * ```\n\t *\n\t * Each declared package is installed for the Functions runtime target — **linux-arm64,\n\t * glibc** — into a throwaway directory, traced for the files it actually reaches, and\n\t * copied into the archive under `node_modules/` with its directory layout preserved. That\n\t * layout is load-bearing rather than cosmetic: a `.node` addon locates its sibling shared\n\t * libraries relative to its own directory, so a flattened tree fails to load.\n\t *\n\t * Your own `node_modules` is never read for these files or modified. Its binaries are\n\t * built for your machine rather than the deploy target, and a cross-platform install does\n\t * not survive your next plain `npm install`, so the target's packages are resolved fresh\n\t * on each deploy.\n\t *\n\t * Requirements, all reported at deploy time rather than at invoke: the package must\n\t * publish a linux-arm64 glibc build (`sharp` and most `@napi-rs/*` packages do; anything\n\t * compiled from source at install time does not), `npm` must be on `PATH`, and the\n\t * archive must stay inside the deploy size limits — native binaries are large.\n\t *\n\t * ### Excluding a package's files\n\t *\n\t * `includeFiles: false` externalizes the import without shipping anything, which is the\n\t * escape hatch for a package that cannot be staged — no build for the target, or too\n\t * large — and that the function never actually reaches:\n\t *\n\t * ```ts\n\t * externalPackages: [\"sharp\", { name: \"canvas\", includeFiles: false }]\n\t * ```\n\t *\n\t * **An excluded package is not resolvable at runtime.** Nothing is shipped for it, so it\n\t * throws `Cannot find module` if the function reaches it. It unblocks an import that is\n\t * never evaluated; it does not make a dependency usable.\n\t *\n\t * Entries are package names, optionally with a subpath (`pkg`, `@scope/pkg`, `pkg/sub`),\n\t * matching esbuild. A relative or absolute path is rejected at validation time: those are\n\t * local modules, and a local module that cannot be bundled is a different problem. Files\n\t * are staged per package, so a subpath narrows what esbuild leaves unresolved without\n\t * narrowing what ships.\n\t *\n\t * Under `neon dev` the list only keeps the package out of the bundle — nothing is\n\t * installed or copied, and it resolves from your own `node_modules` against your host\n\t * architecture, which is what you want locally.\n\t * @example [\"sharp\", { name: \"canvas\", includeFiles: false }]\n\t */\n\texternalPackages?: ExternalPackageEntry[];\n\t/**\n\t * How {@link source} becomes deployable files. Defaults to `\"esbuild\"`.\n\t * `\"none\"` ships a prebuilt directory or `index.mjs` / `index.js` file.\n\t * An inline {@link FunctionBundler} returns the file map used by deploy and\n\t * `neon dev`. Inline functions do not round-trip through inspect or pull and\n\t * must be re-declared.\n\t * @example \"none\"\n\t * @example (fn) => myFrameworkBuild(fn.source)\n\t */\n\tbundler?: FunctionBundlerInput;\n\t/**\n\t * Local-development settings used by `neon dev` when serving every function from\n\t * `neon.ts`. Ignored at deploy time. See {@link FunctionDevConfig}.\n\t */\n\tdev?: FunctionDevConfig;\n\t/**\n\t * Customer-owned hostnames that should point at this function (beta).\n\t * v1 only supports functions. Hostnames are unique across functions in the resolved\n\t * policy. Applied after the function is deployed, on the project's default branch.\n\t * Other branches apply a list only when {@link FunctionTuning.customDomains} sets one.\n\t * Domains that exist remotely but are omitted here are left alone — delete with\n\t * `neon function domains delete`.\n\t *\n\t * @example [\"docs.example.com\"]\n\t */\n\tcustomDomains?: string[];\n}\n\n/**\n * A trigger that invokes a function. The trigger name is the record key in\n * {@link Config.triggers}. `functionPath` defaults to `/`. `enabled` defaults to `true`.\n *\n * @example { type: \"schedule\", function: \"cron\", cron: \"0 * * * *\" }\n * @example { type: \"storage_object_created\", function: \"ingest\", bucket: \"assets\", prefix: \"logos/\" }\n */\nexport type FunctionTriggerDef =\n\t| FunctionScheduleTriggerDef\n\t| FunctionStorageObjectCreatedTriggerDef;\n\n/**\n * A cron schedule that invokes a function. `function` is a slug from {@link Config.functions}\n * (or deprecated `preview.functions`). `cron` is a numeric five-field expression in UTC.\n *\n * @example { type: \"schedule\", function: \"cron\", cron: \"0 * * * *\" }\n */\nexport interface FunctionScheduleTriggerDef {\n\ttype: \"schedule\";\n\tfunction: string;\n\tcron: string;\n\tfunctionPath?: string;\n\tenabled?: boolean;\n}\n\n/**\n * Invokes a function when an object is created in a bucket from {@link Config.buckets}\n * (or deprecated `preview.buckets`). `prefix` is an exact object-key prefix; omit it to\n * match every key in the bucket.\n *\n * @example { type: \"storage_object_created\", function: \"ingest\", bucket: \"assets\", prefix: \"logos/\" }\n */\nexport interface FunctionStorageObjectCreatedTriggerDef {\n\ttype: \"storage_object_created\";\n\tfunction: string;\n\tbucket: string;\n\tprefix?: string;\n\tfunctionPath?: string;\n\tenabled?: boolean;\n}\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 */\nexport type CredentialScope =\n\t| \"storage:read\"\n\t| \"storage:write\"\n\t| \"ai_gateway:invoke\"\n\t| \"functions:invoke\";\n\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 */\nexport type CredentialPrincipalType = \"user\" | \"function\";\n\n/** Anonymous-access level for a branchable object-storage bucket. */\nexport type BucketAccessLevel = \"private\" | \"public_read\";\n\n/**\n * Static definition of a branchable object-storage bucket. The bucket's\n * name is the **record key** in `buckets` (or deprecated {@link PreviewInput.buckets}), so names are statically\n * enumerable and cannot duplicate.\n */\nexport interface BucketDef {\n\t/**\n\t * Anonymous access level. `private` (default) requires authenticated reads/writes;\n\t * `public_read` allows anonymous GetObject/HeadObject.\n\t */\n\taccess?: BucketAccessLevel;\n}\n\n/**\n * Deprecated home for AI Gateway, Functions, and Object Storage.\n *\n * Those services are GA as top-level `aiGateway`, `functions`, and `buckets`.\n * A `preview` block still works; deploy/apply warns that the keys can be lifted.\n *\n * @deprecated Use top-level `aiGateway`, `functions`, and `buckets`.\n */\nexport interface PreviewInput {\n\t/**\n\t * Enable/disable the AI Gateway on the branch (toggle, like auth / dataApi).\n\t * @deprecated Use top-level `aiGateway`.\n\t */\n\taiGateway?: ServiceToggleInput;\n\t/**\n\t * Functions to deploy, keyed by branch-unique slug (`^[a-z0-9]{1,20}$`).\n\t * @deprecated Use top-level `functions`.\n\t */\n\tfunctions?: Record<string, FunctionDef>;\n\t/**\n\t * Object-storage buckets to create, keyed by bucket name.\n\t * @deprecated Use top-level `buckets`.\n\t */\n\tbuckets?: Record<string, BucketDef>;\n}\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 — so the static secret/function set stays sound. Runtime selection\n * and the custom-domain list may vary per branch.\n */\nexport interface FunctionTuning {\n\t/** Runtime to execute the function with. Defaults to `\"nodejs24\"`. */\n\truntime?: FunctionRuntime;\n\t/**\n\t * When present, replaces {@link FunctionDef.customDomains} for this branch.\n\t * `[]` registers nothing on this branch. Omit the key: the default branch\n\t * inherits the static list; other branches do not.\n\t */\n\tcustomDomains?: string[];\n}\n\n/**\n * Per-branch tuning of functions under the deprecated `preview` key.\n * Only existing function slugs may be tuned — `Slug` is constrained to the\n * declared keys by {@link BranchTuningFn}.\n *\n * @deprecated Use top-level `branch: (branch) => ({ functions: { … } })`.\n */\nexport interface PreviewTuning<Slug extends string = string> {\n\t/**\n\t * @deprecated Use top-level `functions` on the object returned by `branch`.\n\t */\n\tfunctions?: Partial<Record<Slug, FunctionTuning>>;\n}\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 */\nexport interface BranchTuning<Slug extends string = string> {\n\t/** Parent branch name used when creating a new branch. Not a Postgres setting. */\n\tparent?: string;\n\t/**\n\t * Branch time-to-live: how long after creation the branch should auto-expire. Applied\n\t * when creating a new branch and reconciled on existing branches (when `updateExisting`\n\t * is set). Accepts a {@link DurationString} (autocompletes common values) or a number of\n\t * seconds. Omit to keep the branch indefinitely.\n\t *\n\t * - {@link DurationString} — e.g. `\"7d\"`; autocompletes `\"1h\"`, `\"6h\"`, `\"12h\"`, `\"1d\"`,\n\t *   `\"3d\"`, `\"7d\"`, `\"14d\"`, `\"30d\"`, and accepts any other `<integer><unit>` (units: `s`,\n\t *   `m`, `h`, `d`, `w` — e.g. `\"12h\"`, `\"2w\"`). A **unit is required** — `\"7\"` is rejected;\n\t *   for raw seconds pass a `number`.\n\t * - `number` — custom TTL in **seconds** (e.g. `3600`)\n\t * - `undefined` — no expiry; the branch persists until explicitly deleted\n\t *\n\t * The Neon API caps branch expiration at **30 days** from creation, so the resolved TTL must\n\t * be `> 0` and `<= 30d`; the suggestions stay within that limit and anything longer is\n\t * rejected at apply.\n\t *\n\t * @example \"1d\"   // ephemeral preview branch: expires a day after creation\n\t * @example \"7d\"   // one-week TTL\n\t * @example \"30d\"  // the maximum the API allows\n\t * @example 3600   // 1 hour, expressed in seconds\n\t */\n\tttl?: DurationField<TtlSuggestion>;\n\t/** Whether the selected branch should be protected. Undefined means \"leave as-is\". */\n\tprotected?: boolean;\n\tpostgres?: PostgresConfig;\n\t/** Per-function deploy tuning, keyed by declared slug. */\n\tfunctions?: Partial<Record<Slug, FunctionTuning>>;\n\t/**\n\t * @deprecated Use top-level `functions` on this object.\n\t */\n\tpreview?: PreviewTuning<Slug>;\n}\n\n/** Extract declared function slugs from top-level `functions` and/or `preview.functions`. */\ntype PreviewFunctionSlugs<Preview> = Preview extends { functions: infer F }\n\t? Extract<keyof F, string>\n\t: never;\n\n// Config's Functions default is `Record<string, FunctionDef> | undefined`. A string\n// index would otherwise union into FunctionSlugsOf as `string` and drop slug checking\n// on positional `Config<Auth, DataApi, Preview>`.\ntype GaFunctionSlugs<Functions> = [Functions] extends [undefined]\n\t? never\n\t: string extends keyof NonNullable<Functions>\n\t\t? never\n\t\t: Extract<keyof NonNullable<Functions>, string>;\n\ntype FunctionSlugsOf<\n\tPreview extends PreviewInput | undefined,\n\tFunctions extends Record<string, FunctionDef> | undefined = undefined,\n> = [PreviewFunctionSlugs<Preview> | GaFunctionSlugs<Functions>] extends [never]\n\t? string\n\t: PreviewFunctionSlugs<Preview> | GaFunctionSlugs<Functions>;\n\n/**\n * Signature of the `branch` closure. Generic over the static function homes so the\n * `functions` keys it may tune are constrained to the slugs actually declared.\n */\nexport type BranchTuningFn<\n\tPreview extends PreviewInput | undefined = PreviewInput | undefined,\n\tFunctions extends Record<string, FunctionDef> | undefined = undefined,\n> = (branch: BranchTarget) => BranchTuning<FunctionSlugsOf<Preview, Functions>>;\n\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 service toggles and records) and a\n * **dynamic** per-branch `branch` closure for tuning. The static half is what makes the\n * secret set — and therefore `NeonEnv<typeof config>` and `parseEnv` — exact; the closure\n * can tune but never change what exists.\n *\n * Generic over the 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. The first three type parameters stay `Auth`, `DataApi`, `Preview`\n * so existing positional `Config<Auth, DataApi, Preview>` consumers keep compiling.\n */\nexport interface Config<\n\tAuth extends ServiceToggleInput | undefined =\n\t\t| ServiceToggleInput\n\t\t| undefined,\n\tDataApi extends DataApiInput | undefined = DataApiInput | undefined,\n\tPreview extends PreviewInput | undefined = PreviewInput | undefined,\n\tFunctions extends Record<string, FunctionDef> | undefined =\n\t\t| Record<string, FunctionDef>\n\t\t| undefined,\n\tBuckets extends Record<string, BucketDef> | undefined =\n\t\t| Record<string, BucketDef>\n\t\t| undefined,\n\tAiGateway extends ServiceToggleInput | undefined =\n\t\t| ServiceToggleInput\n\t\t| undefined,\n> {\n\t/** Neon Auth integration toggle (GA). Static — drives `NeonEnv.auth`. */\n\tauth?: Auth;\n\t/**\n\t * Neon Data API integration (GA). Static — drives `NeonEnv.dataApi`. A boolean/toggle, or\n\t * a {@link DataApiConfig} object selecting the auth provider (`\"neon\"` / `\"external\"`) and\n\t * runtime {@link DataApiSettings}. With `authProvider: \"neon\"` the policy must also enable\n\t * top-level `auth`.\n\t */\n\tdataApi?: DataApi;\n\t/**\n\t * AI Gateway toggle (GA). Static — drives `NeonEnv.aiGateway`. Same shapes as `auth`.\n\t */\n\taiGateway?: AiGateway;\n\t/**\n\t * Functions to deploy, keyed by branch-unique slug (`^[a-z0-9]{1,20}$`).\n\t */\n\tfunctions?: Functions;\n\t/**\n\t * Object-storage buckets to create, keyed by bucket name.\n\t */\n\tbuckets?: Buckets;\n\t/**\n\t * Function triggers, keyed by branch-unique name. Each value names the function\n\t * (and, for `storage_object_created`, the bucket) it binds. Applied after functions\n\t * are deployed. Triggers that exist remotely but are omitted here are left alone.\n\t */\n\ttriggers?: Record<string, FunctionTriggerDef>;\n\t/**\n\t * @deprecated Use top-level `aiGateway`, `functions`, and `buckets`.\n\t */\n\tpreview?: Preview;\n\t/** Per-branch tuning closure. Cannot change the static existential set. */\n\tbranch?: BranchTuningFn<Preview, Functions>;\n\t/**\n\t * Experimental (unstable) features, isolated in their own namespace so they can change\n\t * shape or disappear without touching the rest of the policy. See {@link ExperimentalInput}.\n\t */\n\texperimental?: ExperimentalInput;\n}\n\n/**\n * Experimental (unstable) features. Currently just `hooks`. Kept out of the top-level\n * namespace — rather than a sibling of `auth` / `functions` / `branch` — as a signal that\n * this shape is still moving and isn't covered by the same stability guarantees as the rest\n * of the policy.\n */\nexport interface ExperimentalInput {\n\t/**\n\t * Imperative lifecycle hooks (Preview) — run side effects (migrations, seeding, …) on the\n\t * real `checkout` / `deploy` commands. The declarative companion to {@link Config.branch}:\n\t * hooks never run during `plan` / `status` / `inspect`, so the diff engine stays sound.\n\t * See {@link Hooks}.\n\t */\n\thooks?: Hooks;\n}\n\n// ─── Lifecycle hooks (Preview) ──────────────────────────────────────────────────\n//\n// Hooks are the **imperative** companion to the pure, declarative `branch` closure.\n// `branch()` answers *\"what should this branch look like?\"* (and runs during `plan` /\n// `status` / `apply`, so it must stay side-effect free). Hooks answer *\"do this when a\n// branch is created / checked out / deployed\"* (migrations, seeding, notifications) and\n// run **only** during the real `checkout` / `deploy` commands (and, for `create`,\n// whenever those actually create a branch) — never during `plan` / `status` / `inspect`.\n\n/**\n * Read-only git facts injected into every hook by the CLI. A hook can *read* the git state\n * (to name a branch, gate a migration, …) but the hooks never *drive* git — that keeps the\n * git → Neon relationship a loop-free, one-way edge (`git checkout` syncs Neon, never the\n * reverse). Populated from the surrounding repository; all fields except `available`,\n * `isDetached`, and `isDirty` are absent when {@link available} is `false` (not a git repo,\n * or `git` is not installed).\n *\n * What *triggered* this hook invocation — the installed git hook vs. an explicit CLI\n * command — is a separate concern; see {@link CheckoutEvent} / {@link DeployEvent} on each\n * hook context's `event` field, not this type.\n */\nexport interface GitContext {\n\t/** `false` when the command did not run inside a git work tree (or `git` is missing). */\n\tavailable: boolean;\n\t/** Current branch (`git symbolic-ref --short HEAD`). Undefined in detached-HEAD state. */\n\tbranch?: string;\n\t/**\n\t * `branch`, sanitized into a valid Neon branch name: lowercased, each `/`-separated\n\t * segment reduced to `[a-z0-9-]`, empty results fall back to `\"branch\"`, clamped to 256\n\t * characters. Undefined whenever `branch` is (detached HEAD, not a git repo, or `git` is\n\t * unavailable). Prepend your own prefix with plain string concatenation, e.g.\n\t * `` `preview/${git.neonSafeBranchName}` ``.\n\t */\n\tneonSafeBranchName?: string;\n\t/** Full commit SHA of `HEAD`. */\n\tsha?: string;\n\t/** Abbreviated commit SHA of `HEAD`. */\n\tshortSha?: string;\n\t/** `true` when `HEAD` is detached (no current branch). */\n\tisDetached: boolean;\n\t/** `true` when the work tree has uncommitted changes (`git status --porcelain`). */\n\tisDirty: boolean;\n\t/** Default branch the remote points at (`origin/HEAD`), e.g. `\"main\"`, when resolvable. */\n\tdefaultBranch?: string;\n\t/** `origin` remote URL, when configured. */\n\tremoteUrl?: string;\n\t/** Absolute path to the repository root (`git rev-parse --show-toplevel`). */\n\trepoRoot?: string;\n}\n\n/**\n * What triggered a `checkout` (and the `create` it may perform). `inputName` — what the user\n * typed at a Neon prompt, if anything — lives *inside* the event so narrowing on `event.type`\n * narrows `inputName` too (TypeScript only propagates discriminated-union narrowing within\n * the object actually holding the discriminant, not to sibling fields of an outer object):\n *\n * - `\"git-checkout\"` — the installed `post-checkout` git hook, via `neon git sync`. Carries\n *   the git branch that triggered it (`gitBranch`); `inputName` is always `undefined` here —\n *   nothing was typed at a Neon prompt. The sanitized Neon-safe form of that branch is on the\n *   sibling `git` context, at `git.neonSafeBranchName`.\n * - `\"neon-checkout\"` — an explicit `neon checkout` invocation. `inputName` is the name/id\n *   the user passed, or `undefined` when they omitted it (interactive picker).\n */\nexport type CheckoutEvent =\n\t| { type: \"git-checkout\"; gitBranch: string; inputName?: undefined }\n\t| { type: \"neon-checkout\"; inputName?: string };\n\n/** What triggered a `deploy`. Currently always `\"neon-deploy\"` — an explicit `neon deploy` / `config apply` invocation; `deploy` is never triggered by the git hook. */\nexport type DeployEvent = { type: \"neon-deploy\" };\n\n/**\n * The branch a hook is acting on — a resolved, live branch (unlike the pre-create\n * {@link BranchTarget} the `branch` closure may receive). Always carries a concrete `id`.\n */\nexport interface HookBranch {\n\t/** Neon project id the branch belongs to. */\n\tprojectId: string;\n\t/** Neon branch id (`br-…`). */\n\tid: string;\n\t/** Branch name. */\n\tname: string;\n\t/** `true` when **this** operation created the branch (vs selecting an existing one). */\n\tcreated: boolean;\n\t/** Whether Neon marks the branch as the project default. */\n\tisDefault: boolean;\n\t/** Whether Neon marks the branch protected. */\n\tisProtected: boolean;\n\t/** Parent branch id, when known. */\n\tparentId?: string;\n\t/** Branch expiration timestamp, when set. */\n\texpiresAt?: string;\n}\n\n/**\n * A resolved branch's env vars, namespaced like `@neon/env`'s `NeonEnv<C>` — but **not**\n * generic over the policy. `@neon/config` cannot import the real, policy-exact `NeonEnv<C>`\n * (it lives in a package that itself depends on `@neon/config`, and importing it back would\n * be a dependency cycle), so every namespace here is optional regardless of what the policy\n * declares, rather than conditionally present/absent. `postgres` is the only field every\n * resolved branch actually has, so it stays the one non-optional namespace.\n */\nexport interface HookEnv {\n\tpostgres: {\n\t\tdatabaseUrl: string;\n\t\tdatabaseUrlUnpooled: string;\n\t};\n\tbranch?: { name: string };\n\tauth?: { baseUrl: string; jwksUrl: string };\n\tdataApi?: { url: string };\n\tstorage?: {\n\t\taccessKeyId: string;\n\t\tsecretAccessKey: string;\n\t\tendpoint: string;\n\t\tregion: string;\n\t};\n\taiGateway?: { apiKey: string; baseUrl: string };\n\tfunctions?: Record<string, { baseUrl: string }>;\n}\n\n/** Context passed to `hooks.checkout.before` (runs before the branch name is resolved). */\nexport interface CheckoutBeforeContext {\n\tevent: CheckoutEvent;\n\tgit: GitContext;\n}\n\n/**\n * Return value of a `hooks.checkout.before` **function** hook. Return `{ name }` to rewrite\n * the branch that will be checked out / created; return nothing to keep the resolved name.\n * Throw to abort the checkout. (Shell-command `before` hooks cannot rewrite the name — only\n * abort via a non-zero exit — since they have no return channel.)\n */\nexport interface CheckoutBeforeResult {\n\t/** Overrides the Neon branch name to check out / create. */\n\tname?: string;\n}\n\n/**\n * Context passed to `hooks.checkout.after` (branch resolved + env pulled). `env` is\n * {@link HookEnv} — every namespace optional; see that type for why it can't be the exact,\n * policy-typed `NeonEnv<C>`.\n */\nexport interface CheckoutAfterContext {\n\tbranch: HookBranch;\n\tenv: HookEnv;\n\tgit: GitContext;\n\tevent: CheckoutEvent;\n}\n\n/**\n * Context passed to `hooks.create.before` (runs before a new branch is created). Fires only\n * for a genuine creation — never for `checkout` selecting an existing branch. Unlike\n * `checkout.before`, this cannot rename the branch: by the time a `create` is reached, the\n * name is already resolved (rename via `checkout.before` if you need that).\n */\nexport interface CreateBeforeContext {\n\t/** Name of the branch about to be created. */\n\tbranchName: string;\n\tgit: GitContext;\n\t/** The event that triggered the enclosing `checkout` — `create` never runs standalone. */\n\tevent: CheckoutEvent;\n}\n\n/** Context passed to `hooks.create.after` (branch created, policy applied, env pulled). `branch.created` is always `true` here. */\nexport interface CreateAfterContext {\n\tbranch: HookBranch;\n\tenv: HookEnv;\n\tgit: GitContext;\n\tevent: CheckoutEvent;\n}\n\n/** Context passed to `hooks.deploy.before` (branch resolved, policy not yet applied). */\nexport interface DeployBeforeContext {\n\tbranch: HookBranch;\n\tgit: GitContext;\n\tevent: DeployEvent;\n}\n\n/** Context passed to `hooks.deploy.after` (policy applied, env pulled). */\nexport interface DeployAfterContext {\n\tbranch: HookBranch;\n\tenv: HookEnv;\n\t/** What the apply changed. */\n\tresult: PushResult;\n\tgit: GitContext;\n\tevent: DeployEvent;\n}\n\n/**\n * A shell-command hook: a single command string, or a list of commands run sequentially\n * (each must exit 0 or the operation aborts). Commands run **non-interactively** (stdin is\n * not a TTY and `CI=1` is set) so an accidental interactive command fails fast instead of\n * hanging. Resolved Neon env vars are injected into the command's environment.\n */\nexport type ShellHook = string | string[];\n\n/**\n * A lifecycle hook: either a (possibly async) function receiving a typed `Ctx`, or a\n * {@link ShellHook}. `before` hooks may influence/abort (functions can return `Result`,\n * any hook can throw to abort); `after` hooks observe (their return value is ignored).\n */\nexport type Hook<Ctx, Result = void> =\n\t| ((ctx: Ctx) => Result | Promise<Result>)\n\t| ShellHook;\n\n/** Hooks for the `checkout` command (`neon checkout`). */\nexport interface CheckoutHooks {\n\t/** Runs before the branch is resolved; may rewrite the name (function form) or abort. */\n\t// biome-ignore lint/suspicious/noConfusingVoidType: a `before` hook may return an override or nothing — `void` (not `undefined`) is what lets a no-op `() => {}` validation hook type-check.\n\tbefore?: Hook<CheckoutBeforeContext, CheckoutBeforeResult | void>;\n\t/** Runs after checkout + env pull. Use `branch.created` to distinguish new vs existing. */\n\tafter?: Hook<CheckoutAfterContext>;\n}\n\n/**\n * Hooks for branch **creation**. Fires only when `checkout` (or another consumer of the\n * runtime's create operation) actually creates a new branch — not when `checkout` selects\n * an existing one. Distinct from `checkout`, which brackets the whole `checkout` command\n * regardless of whether it created or selected a branch: use `create` when you specifically\n * care about the creation moment.\n */\nexport interface CreateHooks {\n\t/** Runs before the branch is created; throw/non-zero exit to abort. */\n\tbefore?: Hook<CreateBeforeContext, void>;\n\t/** Runs after the branch is created and the policy applied. */\n\tafter?: Hook<CreateAfterContext>;\n}\n\n/** Hooks for the `deploy` command (`neon deploy` / `config apply`). */\nexport interface DeployHooks {\n\t/** Runs before the policy is applied; throw/non-zero exit to abort. */\n\tbefore?: Hook<DeployBeforeContext, void>;\n\t/** Runs after a successful apply + env pull. */\n\tafter?: Hook<DeployAfterContext>;\n}\n\n/**\n * Imperative lifecycle hooks, keyed by the phase they bracket. Each phase exposes a\n * `before` (influence/abort) and `after` (observe) hook. Hooks never run during `plan` /\n * `status` / `inspect`.\n *\n * `env` in every `after` hook is the fixed {@link HookEnv}, not a policy-exact type — see\n * that type's doc comment for why.\n */\nexport interface Hooks {\n\tcheckout?: CheckoutHooks;\n\tcreate?: CreateHooks;\n\tdeploy?: DeployHooks;\n}\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 */\nexport interface ResolvedFunctionConfig {\n\tslug: string;\n\tname: string;\n\tsource: string;\n\tenv: Record<string, string>;\n\t/**\n\t * Packages the bundler leaves unresolved, normalized from\n\t * {@link FunctionDef.externalPackages} with `includeFiles` defaulted.\n\t *\n\t * Absent rather than empty when undeclared, so a policy that never mentions it takes the\n\t * pre-existing bundling path and produces the archive it always did.\n\t */\n\texternalPackages?: ResolvedExternalPackage[];\n\truntime: FunctionRuntime;\n\tbundler: FunctionBundlerInput;\n\t/**\n\t * Local-development settings, passed through untouched from {@link FunctionDef.dev}\n\t * (no defaults applied). Only consumed by `neon dev`; deploy ignores it.\n\t */\n\tdev?: FunctionDevConfig;\n\t/**\n\t * Normalized hostnames this function should own on the branch. Absent when this\n\t * branch has no list to apply. Empty when tuning replaced the list with `[]`.\n\t */\n\tcustomDomains?: string[];\n}\n\nexport type ResolvedFunctionTrigger =\n\t| ResolvedFunctionScheduleTrigger\n\t| ResolvedFunctionStorageObjectCreatedTrigger;\n\nexport interface ResolvedFunctionScheduleTrigger {\n\ttype: \"schedule\";\n\tname: string;\n\tfunctionSlug: string;\n\tcron: string;\n\tfunctionPath: string;\n\tenabled: boolean;\n}\n\nexport interface ResolvedFunctionStorageObjectCreatedTrigger {\n\ttype: \"storage_object_created\";\n\tname: string;\n\tfunctionSlug: string;\n\tbucketName: string;\n\tprefix?: string;\n\tfunctionPath: string;\n\tenabled: boolean;\n}\n\n/** A bucket with its access level defaulted to `private`. */\nexport interface ResolvedBucketConfig {\n\tname: string;\n\taccess: BucketAccessLevel;\n}\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 */\nexport interface ResolvedPreviewConfig {\n\tfunctions: ResolvedFunctionConfig[];\n\tbuckets: ResolvedBucketConfig[];\n\taiGatewayEnabled: boolean;\n}\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 */\nexport interface ResolvedDataApiConfig {\n\tauthProvider: DataApiAuthProvider;\n\tjwksUrl?: string;\n\tproviderName?: string;\n\tjwtAudience?: string;\n\tsettings?: DataApiSettings;\n}\n\nexport interface ResolvedBranchConfig {\n\tparent?: string;\n\tttlSeconds?: number;\n\tprotected?: boolean;\n\tpostgres?: PostgresConfig;\n\tauthEnabled: boolean;\n\tdataApiEnabled: boolean;\n\t/** Optional for compatibility with hand-built configs. */\n\tdataApiPolicy?: \"omitted\" | \"enabled\" | \"disabled\";\n\t/**\n\t * Resolved Data API integration. Present iff {@link dataApiEnabled} is `true`. Carries the\n\t * create-time auth wiring and the updatable {@link DataApiSettings}.\n\t */\n\tdataApi?: ResolvedDataApiConfig;\n\tpreview?: ResolvedPreviewConfig;\n\t/**\n\t * Resolved triggers from {@link Config.triggers}. Absent when none are declared\n\t * (hand-built configs may omit it).\n\t */\n\ttriggers?: ResolvedFunctionTrigger[];\n}\n\n/**\n * One concrete change `pushConfig` made (or, in dry-run, would make) on the remote.\n */\nexport interface AppliedChange {\n\t/**\n\t * `service` covers branch-scoped integrations driven by the branch policy (e.g.\n\t * Neon Auth, Data API).\n\t */\n\tkind: \"branch\" | \"service\";\n\taction: \"create\" | \"update\" | \"delete\" | \"noop\";\n\tidentifier: string;\n\tdetails?: Record<string, unknown>;\n}\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 */\nexport interface ConflictReport {\n\tkind: \"branch\";\n\tidentifier: string;\n\tfield: string;\n\tcurrent: unknown;\n\tdesired: unknown;\n\treason: string;\n}\n\n/**\n * Result of a `pushConfig` invocation.\n */\nexport interface PushResult {\n\tprojectId: string;\n\torgId?: string;\n\tbranchId: string;\n\tbranchName: string;\n\t/**\n\t * `true` when `pushConfig` was called with `{ dryRun: true }`. `applied` then records\n\t * what **would** be applied on a real push; no API mutations were performed.\n\t */\n\tdryRun: boolean;\n\tapplied: AppliedChange[];\n\tconflicts: ConflictReport[];\n\t/**\n\t * Declared custom domains for this branch after the push (or what apply would\n\t * leave in place). `cnameTarget` is omitted when the domain is not registered yet\n\t * (dry-run of a new registration). An empty string means the region has no\n\t * custom-domains front door.\n\t */\n\tcustomDomains?: Array<{\n\t\tdomain: string;\n\t\tslug: string;\n\t\tcnameTarget?: string;\n\t}>;\n\t/**\n\t * Advisory findings from the push — a function that bundles a native dependency it never\n\t * declared, or a staged package whose version could not be pinned.\n\t *\n\t * Returned rather than logged, because a library has no business choosing an output\n\t * channel, and returned rather than left to an opt-in callback, because these are the\n\t * only warning that a deployed function will fail at invoke and an unregistered callback\n\t * is easy to never notice. Empty when there is nothing to report.\n\t *\n\t * Only populated by the built-in bundler: a caller that injects its own `bundleFunction`\n\t * owns its own reporting.\n\t */\n\twarnings: string[];\n}\n"],"mappings":";;;;;;AAKA,MAAa,gBAAgB;CAC5B;CAAM;CAAK;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAG;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CACtE;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;CAAI;AACrE;;;;;;;;;;;;;AAwMA,MAAa,0BAA0B,CAAC,QAAQ,UAAU"}