@neondatabase/config 0.11.0 → 0.12.0

package/README.md

@@ -143,7 +143,9 @@ const live = await inspect(target);
 | `plan(config, options)` | Returns the dry-run diff — what `apply` would do for the branch, with no mutations. Returns a `PushResult` whose `applied` holds the plan and `conflicts` holds blocking drift. |
 | `apply(config, options)` | Reconciles your local `neon.ts` policy onto the branch. Pass `updateExisting` to auto-confirm overriding existing remote settings and `allowProtectedBranch` to auto-confirm applying to a protected branch. |
 
-`options` requires both `projectId` and `branchId` (a Neon branch id, `br-…`). Resolve branch names to ids before calling. The Neon API key resolves via the `apiKey` option → `NEON_API_KEY` → `~/.config/neonctl/credentials.json`.
+`options` requires both `projectId` and `branchId` (a Neon branch id, `br-…`). Resolve branch names to ids before calling.
+
+**Pass `apiKey` explicitly** (or inject your own `api` adapter). This package reads no environment variables and no files on your behalf — it will not pick up `NEON_API_KEY` or `~/.config/neonctl/credentials.json`, and omitting the key raises `PLATFORM_MISSING_API_KEY`. Resolving where a credential comes from belongs to the application or CLI embedding this package, because only it knows which ambient sources its users expect. `packages/cli` and `packages/env`'s `neon-env` both implement that chain; the latter's `src/lib/cli/resolve-api-key.ts` is a ~60-line reference implementation of flag → `NEON_API_KEY` → stored credentials.
 
 ## Lower-level engine
 
@@ -159,7 +161,6 @@ import {
   pullConfig,
   loadConfigFromFile,
   createRealNeonApi,
-  resolveApiKey,
   PlatformError,
   ErrorCode,
   errors,

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConflictReport, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput } from "./lib/types.js";
 import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, isPartialBranchCreateError, isPlatformError } from "./lib/errors.js";
 import { CreateBranchInput, CreateBucketInput, CreateCredentialInput, CreateProjectInput, DeployFunctionInput, EnableDataApiInput, GetConnectionUriInput, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBranchStorageSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonCredentialSecret, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, UpdateBranchInput } from "./lib/neon-api.js";
-import { createNeonApiFromOptions, resolveApiKey } from "./lib/auth.js";
+import { createNeonApiFromOptions } from "./lib/auth.js";
 import { CredentialFeatureFlags, credentialScopesSatisfied, deriveCredentialScopes } from "./lib/credentials.js";
 import { defineConfig, resolveConfig } from "./lib/define-config.js";
 import { DiffOptions, DiffResult, PlanStep, RemotePreviewState, RemoteServiceState, RemoteState, diffConfig } from "./lib/diff.js";
 import { LoadConfigOptions, loadConfigFromFile } from "./lib/loader.js";
 import { createRealNeonApi } from "./lib/neon-api-real.js";
 import { errors, schemas } from "./v1.js";
-export { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConfigLoadError, ConfigValidationError, ConflictReport, CreateBranchInput, CreateBucketInput, CreateCredentialInput, CreateProjectInput, CredentialFeatureFlags, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DeployFunctionInput, DiffOptions, DiffResult, DurationString, DurationUnit, EnableDataApiInput, ErrorCode, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, GetConnectionUriInput, LoadConfigOptions, MissingContextError, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBranchStorageSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonCredentialSecret, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, PartialBranchCreateError, PlanStep, PlatformError, PostgresConfig, PreviewInput, PreviewTuning, PushAbortedError, PushConflictError, PushResult, RemotePreviewState, RemoteServiceState, RemoteState, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput, UpdateBranchInput, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveApiKey, resolveConfig, schemas };
+export { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConfigLoadError, ConfigValidationError, ConflictReport, CreateBranchInput, CreateBucketInput, CreateCredentialInput, CreateProjectInput, CredentialFeatureFlags, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DeployFunctionInput, DiffOptions, DiffResult, DurationString, DurationUnit, EnableDataApiInput, ErrorCode, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, GetConnectionUriInput, LoadConfigOptions, MissingContextError, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBranchStorageSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonCredentialSecret, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, PartialBranchCreateError, PlanStep, PlatformError, PostgresConfig, PreviewInput, PreviewTuning, PushAbortedError, PushConflictError, PushResult, RemotePreviewState, RemoteServiceState, RemoteState, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput, UpdateBranchInput, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveConfig, schemas };

package/dist/index.js

@@ -1,10 +1,10 @@
 import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, isPartialBranchCreateError, isPlatformError } from "./lib/errors.js";
 import { createRealNeonApi } from "./lib/neon-api-real.js";
-import { createNeonApiFromOptions, resolveApiKey } from "./lib/auth.js";
+import { createNeonApiFromOptions } from "./lib/auth.js";
 import { credentialScopesSatisfied, deriveCredentialScopes } from "./lib/credentials.js";
 import { defineConfig, resolveConfig } from "./lib/define-config.js";
 import { diffConfig } from "./lib/diff.js";
 import { loadConfigFromFile } from "./lib/loader.js";
 import { DATA_API_AUTH_PROVIDERS } from "./lib/types.js";
 import { errors, schemas } from "./v1.js";
-export { ConfigLoadError, ConfigValidationError, DATA_API_AUTH_PROVIDERS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveApiKey, resolveConfig, schemas };
+export { ConfigLoadError, ConfigValidationError, DATA_API_AUTH_PROVIDERS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveConfig, schemas };

package/dist/lib/auth.d.ts

@@ -3,65 +3,30 @@ import { NeonApi } from "./neon-api.js";
 //#region src/lib/auth.d.ts
 
 /**
- * Minimal shape of `~/.config/neonctl/credentials.json` we read. `neonctl` writes more
- * fields (refresh_token, expires_at, …) but only `access_token` is what we need — it's a
- * Bearer token the Neon API accepts on the same endpoints `napi_*` API keys do.
- */
-interface NeonctlCredentials {
-  access_token: string;
-  [key: string]: unknown;
-}
-/**
- * Locate and read the OAuth credentials neonctl writes after `neon auth`.
- *
- * Resolution:
- * 1. `options.configDir` (explicit override — mirrors neonctl's `--config-dir` flag).
- * 2. `NEONCTL_CONFIG_DIR` environment variable.
- * 3. `<home>/.config/neonctl/credentials.json` (the neonctl default; `home` reads
- *    `HOME`, falling back to `USERPROFILE` for Windows parity).
- *
- * Returns `null` (never throws) when the file is missing, unreadable, malformed, or has
- * no `access_token` — so callers can use this as a quiet fallback in a resolution chain
- * without try/catch noise.
- */
-declare function readNeonctlCredentials(options?: {
-  configDir?: string;
-}): NeonctlCredentials | null;
-/**
- * Resolution chain for the Bearer token sent to the Neon API. Each entry wins over the
- * next:
- *
- * 1. `options.apiKey` (explicit).
- * 2. `NEON_API_KEY` environment variable.
- * 3. `access_token` from `~/.config/neonctl/credentials.json` (or `NEONCTL_CONFIG_DIR`).
+ * Build a real {@link NeonApi} adapter from an explicit API key, or throw a uniform
+ * `PLATFORM_MISSING_API_KEY` error when the caller didn't supply one.
  *
- * Returns `null` when no source provides one. Callers wrap the null case in a
- * `PLATFORM_MISSING_API_KEY` error with a message tailored to the operation.
- */
-declare function resolveApiKey(options?: {
-  apiKey?: string;
-  configDir?: string;
-}): {
-  token: string;
-  source: "option" | "env" | "neonctl";
-} | null;
-/**
- * Resolve the Neon API key via the standard chain (option → `NEON_API_KEY` env →
- * `~/.config/neonctl/credentials.json`) and construct a real {@link NeonApi} adapter from
- * it, or throw a uniform `PLATFORM_MISSING_API_KEY` error if no key can be found.
+ * **This function is pure with respect to its environment**: it reads no environment
+ * variables and no files. Everything it needs arrives in `options`. Resolving *where* a
+ * credential comes from — a flag, `NEON_API_KEY`, a credentials file on disk — is the
+ * caller's job, because only the caller knows which of those its users expect. See
+ * `packages/cli` (`ensureAuth` + `resolveApiKeyFromEnv`) and `packages/init`
+ * (`src/lib/auth.ts`) for the two implementations in this repo.
  *
- * The API host is resolved via: `options.apiHost` → `NEON_API_HOST` env → production
- * default (`https://console.neon.tech/api/v2`).
+ * `apiHost` stays **optional** and defaults to production
+ * (`https://console.neon.tech/api/v2`, applied by {@link createRealNeonApi}) — only pass it
+ * to target a non-production API. It is the *ambient* `NEON_API_HOST` lookup that's gone,
+ * not the default.
  *
  * Used by `pullConfig`, `pushConfig`, `fetchEnv`, and `branch` to build their default
- * `NeonApi` when the caller doesn't inject one. `operation` is the calling function's
- * name (e.g. `"pushConfig"`, `"branch"`) — it's prepended to the error message so users
- * can tell which call surfaced the missing key.
+ * adapter when the caller doesn't inject one. `operation` is the calling function's name
+ * (e.g. `"pushConfig"`, `"branch"`) — it's prepended to the error message so users can tell
+ * which call surfaced the missing key.
  */
 declare function createNeonApiFromOptions(operation: string, options?: {
   apiKey?: string;
   apiHost?: string;
 }): NeonApi;
 //#endregion
-export { NeonctlCredentials, createNeonApiFromOptions, readNeonctlCredentials, resolveApiKey };
+export { createNeonApiFromOptions };
 //# sourceMappingURL=auth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","names":[],"sources":["../../src/lib/auth.ts"],"mappings":";;;;;;AAWA;AAkBA;AA8CA;AAsCgB,UAtGC,kBAAA,CAsGuB;;;;;;;;;;;;;;;;;iBApFxB,sBAAA;;IAEb;;;;;;;;;;;;iBA4Ca,aAAA;;;;;;;;;;;;;;;;;;;;iBAsCA,wBAAA;;;IAMb"}
+{"version":3,"file":"auth.d.ts","names":[],"sources":["../../src/lib/auth.ts"],"mappings":";;;;;;AA+BA;;;;;;;;;;;;;;;;;;;iBAAgB,wBAAA;;;IAMb"}

package/dist/lib/auth.js

@@ -1,107 +1,47 @@
 import { ErrorCode, PlatformError } from "./errors.js";
 import { createRealNeonApi } from "./neon-api-real.js";
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
 //#region src/lib/auth.ts
-/**
-* Locate and read the OAuth credentials neonctl writes after `neon auth`.
-*
-* Resolution:
-* 1. `options.configDir` (explicit override — mirrors neonctl's `--config-dir` flag).
-* 2. `NEONCTL_CONFIG_DIR` environment variable.
-* 3. `<home>/.config/neonctl/credentials.json` (the neonctl default; `home` reads
-*    `HOME`, falling back to `USERPROFILE` for Windows parity).
-*
-* Returns `null` (never throws) when the file is missing, unreadable, malformed, or has
-* no `access_token` — so callers can use this as a quiet fallback in a resolution chain
-* without try/catch noise.
-*/
-function readNeonctlCredentials(options = {}) {
-	const home = process.env.HOME ?? process.env.USERPROFILE;
-	const configDir = options.configDir ?? process.env.NEONCTL_CONFIG_DIR ?? (home ? resolve(home, ".config", "neonctl") : void 0);
-	if (!configDir) return null;
-	const credentialsPath = resolve(configDir, "credentials.json");
-	if (!existsSync(credentialsPath)) return null;
-	let raw;
-	try {
-		raw = readFileSync(credentialsPath, "utf-8");
-	} catch {
-		return null;
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return null;
-	}
-	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-	const obj = parsed;
-	if (typeof obj.access_token !== "string" || obj.access_token === "") return null;
-	return obj;
-}
-/**
-* Resolution chain for the Bearer token sent to the Neon API. Each entry wins over the
-* next:
-*
-* 1. `options.apiKey` (explicit).
-* 2. `NEON_API_KEY` environment variable.
-* 3. `access_token` from `~/.config/neonctl/credentials.json` (or `NEONCTL_CONFIG_DIR`).
-*
-* Returns `null` when no source provides one. Callers wrap the null case in a
-* `PLATFORM_MISSING_API_KEY` error with a message tailored to the operation.
-*/
-function resolveApiKey(options = {}) {
-	if (options.apiKey && options.apiKey.trim() !== "") return {
-		token: options.apiKey.trim(),
-		source: "option"
-	};
-	const envKey = process.env.NEON_API_KEY;
-	if (typeof envKey === "string" && envKey.trim() !== "") return {
-		token: envKey.trim(),
-		source: "env"
-	};
-	const creds = readNeonctlCredentials(options.configDir ? { configDir: options.configDir } : {});
-	if (creds) return {
-		token: creds.access_token,
-		source: "neonctl"
-	};
-	return null;
-}
 /** Trim trailing slashes and surrounding whitespace; treat empty as unset. */
 function normalizeApiHost(url) {
 	const trimmed = url?.trim().replace(/\/+$/, "");
 	return trimmed ? trimmed : void 0;
 }
 /**
-* Resolve the Neon API key via the standard chain (option → `NEON_API_KEY` env →
-* `~/.config/neonctl/credentials.json`) and construct a real {@link NeonApi} adapter from
-* it, or throw a uniform `PLATFORM_MISSING_API_KEY` error if no key can be found.
+* Build a real {@link NeonApi} adapter from an explicit API key, or throw a uniform
+* `PLATFORM_MISSING_API_KEY` error when the caller didn't supply one.
+*
+* **This function is pure with respect to its environment**: it reads no environment
+* variables and no files. Everything it needs arrives in `options`. Resolving *where* a
+* credential comes from — a flag, `NEON_API_KEY`, a credentials file on disk — is the
+* caller's job, because only the caller knows which of those its users expect. See
+* `packages/cli` (`ensureAuth` + `resolveApiKeyFromEnv`) and `packages/init`
+* (`src/lib/auth.ts`) for the two implementations in this repo.
 *
-* The API host is resolved via: `options.apiHost` → `NEON_API_HOST` env → production
-* default (`https://console.neon.tech/api/v2`).
+* `apiHost` stays **optional** and defaults to production
+* (`https://console.neon.tech/api/v2`, applied by {@link createRealNeonApi}) — only pass it
+* to target a non-production API. It is the *ambient* `NEON_API_HOST` lookup that's gone,
+* not the default.
 *
 * Used by `pullConfig`, `pushConfig`, `fetchEnv`, and `branch` to build their default
-* `NeonApi` when the caller doesn't inject one. `operation` is the calling function's
-* name (e.g. `"pushConfig"`, `"branch"`) — it's prepended to the error message so users
-* can tell which call surfaced the missing key.
+* adapter when the caller doesn't inject one. `operation` is the calling function's name
+* (e.g. `"pushConfig"`, `"branch"`) — it's prepended to the error message so users can tell
+* which call surfaced the missing key.
 */
 function createNeonApiFromOptions(operation, options = {}) {
-	const resolved = resolveApiKey(options.apiKey ? { apiKey: options.apiKey } : {});
-	if (resolved) {
-		const baseUrl = normalizeApiHost(options.apiHost) ?? normalizeApiHost(process.env.NEON_API_HOST);
-		return createRealNeonApi({
-			apiKey: resolved.token,
-			...baseUrl ? { baseUrl } : {}
-		});
-	}
-	throw new PlatformError(ErrorCode.MissingApiKey, [
-		`${operation} has no Neon API key to work with.`,
-		"Tried (in order): `apiKey` option, NEON_API_KEY env, and `~/.config/neonctl/credentials.json`.",
-		"Either pass `apiKey` directly, set NEON_API_KEY, run `npx neonctl auth` to populate the credentials file, or pass a custom `api` adapter (e.g. an in-memory fake for tests).",
+	const apiKey = options.apiKey?.trim();
+	if (!apiKey) throw new PlatformError(ErrorCode.MissingApiKey, [
+		`${operation} was not given a Neon API key.`,
+		"Pass `apiKey` explicitly, or inject your own `api` adapter (e.g. an in-memory fake for tests).",
+		"This package never reads NEON_API_KEY or a credentials file on your behalf — resolve the key in your own application or CLI and pass it in.",
 		"Generate a key at https://console.neon.tech/app/settings/api-keys."
 	].join(" "));
+	const baseUrl = normalizeApiHost(options.apiHost);
+	return createRealNeonApi({
+		apiKey,
+		...baseUrl ? { baseUrl } : {}
+	});
 }
 //#endregion
-export { createNeonApiFromOptions, readNeonctlCredentials, resolveApiKey };
+export { createNeonApiFromOptions };
 
 //# sourceMappingURL=auth.js.map

package/dist/lib/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","names":[],"sources":["../../src/lib/auth.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { ErrorCode, PlatformError } from \"./errors.js\";\nimport type { NeonApi } from \"./neon-api.js\";\nimport { createRealNeonApi } from \"./neon-api-real.js\";\n\n/**\n * Minimal shape of `~/.config/neonctl/credentials.json` we read. `neonctl` writes more\n * fields (refresh_token, expires_at, …) but only `access_token` is what we need — it's a\n * Bearer token the Neon API accepts on the same endpoints `napi_*` API keys do.\n */\nexport interface NeonctlCredentials {\n\taccess_token: string;\n\t[key: string]: unknown;\n}\n\n/**\n * Locate and read the OAuth credentials neonctl writes after `neon auth`.\n *\n * Resolution:\n * 1. `options.configDir` (explicit override — mirrors neonctl's `--config-dir` flag).\n * 2. `NEONCTL_CONFIG_DIR` environment variable.\n * 3. `<home>/.config/neonctl/credentials.json` (the neonctl default; `home` reads\n *    `HOME`, falling back to `USERPROFILE` for Windows parity).\n *\n * Returns `null` (never throws) when the file is missing, unreadable, malformed, or has\n * no `access_token` — so callers can use this as a quiet fallback in a resolution chain\n * without try/catch noise.\n */\nexport function readNeonctlCredentials(\n\toptions: { configDir?: string } = {},\n): NeonctlCredentials | null {\n\tconst home = process.env.HOME ?? process.env.USERPROFILE;\n\tconst configDir =\n\t\toptions.configDir ??\n\t\tprocess.env.NEONCTL_CONFIG_DIR ??\n\t\t(home ? resolve(home, \".config\", \"neonctl\") : undefined);\n\tif (!configDir) return null;\n\n\tconst credentialsPath = resolve(configDir, \"credentials.json\");\n\tif (!existsSync(credentialsPath)) return null;\n\n\tlet raw: string;\n\ttry {\n\t\traw = readFileSync(credentialsPath, \"utf-8\");\n\t} catch {\n\t\treturn null;\n\t}\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(raw);\n\t} catch {\n\t\treturn null;\n\t}\n\n\tif (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed))\n\t\treturn null;\n\tconst obj = parsed as Record<string, unknown>;\n\tif (typeof obj.access_token !== \"string\" || obj.access_token === \"\")\n\t\treturn null;\n\treturn obj as NeonctlCredentials;\n}\n\n/**\n * Resolution chain for the Bearer token sent to the Neon API. Each entry wins over the\n * next:\n *\n * 1. `options.apiKey` (explicit).\n * 2. `NEON_API_KEY` environment variable.\n * 3. `access_token` from `~/.config/neonctl/credentials.json` (or `NEONCTL_CONFIG_DIR`).\n *\n * Returns `null` when no source provides one. Callers wrap the null case in a\n * `PLATFORM_MISSING_API_KEY` error with a message tailored to the operation.\n */\nexport function resolveApiKey(\n\toptions: { apiKey?: string; configDir?: string } = {},\n): { token: string; source: \"option\" | \"env\" | \"neonctl\" } | null {\n\tif (options.apiKey && options.apiKey.trim() !== \"\") {\n\t\treturn { token: options.apiKey.trim(), source: \"option\" };\n\t}\n\tconst envKey = process.env.NEON_API_KEY;\n\tif (typeof envKey === \"string\" && envKey.trim() !== \"\") {\n\t\treturn { token: envKey.trim(), source: \"env\" };\n\t}\n\tconst creds = readNeonctlCredentials(\n\t\toptions.configDir ? { configDir: options.configDir } : {},\n\t);\n\tif (creds) {\n\t\treturn { token: creds.access_token, source: \"neonctl\" };\n\t}\n\treturn null;\n}\n\n/** Trim trailing slashes and surrounding whitespace; treat empty as unset. */\nfunction normalizeApiHost(url: string | undefined): string | undefined {\n\tconst trimmed = url?.trim().replace(/\\/+$/, \"\");\n\treturn trimmed ? trimmed : undefined;\n}\n\n/**\n * Resolve the Neon API key via the standard chain (option → `NEON_API_KEY` env →\n * `~/.config/neonctl/credentials.json`) and construct a real {@link NeonApi} adapter from\n * it, or throw a uniform `PLATFORM_MISSING_API_KEY` error if no key can be found.\n *\n * The API host is resolved via: `options.apiHost` → `NEON_API_HOST` env → production\n * default (`https://console.neon.tech/api/v2`).\n *\n * Used by `pullConfig`, `pushConfig`, `fetchEnv`, and `branch` to build their default\n * `NeonApi` when the caller doesn't inject one. `operation` is the calling function's\n * name (e.g. `\"pushConfig\"`, `\"branch\"`) — it's prepended to the error message so users\n * can tell which call surfaced the missing key.\n */\nexport function createNeonApiFromOptions(\n\toperation: string,\n\toptions: {\n\t\tapiKey?: string;\n\t\tapiHost?: string;\n\t} = {},\n): NeonApi {\n\tconst resolved = resolveApiKey(\n\t\toptions.apiKey ? { apiKey: options.apiKey } : {},\n\t);\n\tif (resolved) {\n\t\tconst baseUrl =\n\t\t\tnormalizeApiHost(options.apiHost) ??\n\t\t\tnormalizeApiHost(process.env.NEON_API_HOST);\n\t\treturn createRealNeonApi({\n\t\t\tapiKey: resolved.token,\n\t\t\t...(baseUrl ? { baseUrl } : {}),\n\t\t});\n\t}\n\tthrow new PlatformError(\n\t\tErrorCode.MissingApiKey,\n\t\t[\n\t\t\t`${operation} has no Neon API key to work with.`,\n\t\t\t\"Tried (in order): `apiKey` option, NEON_API_KEY env, and `~/.config/neonctl/credentials.json`.\",\n\t\t\t\"Either pass `apiKey` directly, set NEON_API_KEY, run `npx neonctl auth` to populate the credentials file, or pass a custom `api` adapter (e.g. an in-memory fake for tests).\",\n\t\t\t\"Generate a key at https://console.neon.tech/app/settings/api-keys.\",\n\t\t].join(\" \"),\n\t);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA6BA,SAAgB,uBACf,UAAkC,CAAC,GACP;CAC5B,MAAM,OAAO,QAAQ,IAAI,QAAQ,QAAQ,IAAI;CAC7C,MAAM,YACL,QAAQ,aACR,QAAQ,IAAI,uBACX,OAAO,QAAQ,MAAM,WAAW,SAAS,IAAI,KAAA;CAC/C,IAAI,CAAC,WAAW,OAAO;CAEvB,MAAM,kBAAkB,QAAQ,WAAW,kBAAkB;CAC7D,IAAI,CAAC,WAAW,eAAe,GAAG,OAAO;CAEzC,IAAI;CACJ,IAAI;EACH,MAAM,aAAa,iBAAiB,OAAO;CAC5C,QAAQ;EACP,OAAO;CACR;CAEA,IAAI;CACJ,IAAI;EACH,SAAS,KAAK,MAAM,GAAG;CACxB,QAAQ;EACP,OAAO;CACR;CAEA,IAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GACxE,OAAO;CACR,MAAM,MAAM;CACZ,IAAI,OAAO,IAAI,iBAAiB,YAAY,IAAI,iBAAiB,IAChE,OAAO;CACR,OAAO;AACR;;;;;;;;;;;;AAaA,SAAgB,cACf,UAAmD,CAAC,GACa;CACjE,IAAI,QAAQ,UAAU,QAAQ,OAAO,KAAK,MAAM,IAC/C,OAAO;EAAE,OAAO,QAAQ,OAAO,KAAK;EAAG,QAAQ;CAAS;CAEzD,MAAM,SAAS,QAAQ,IAAI;CAC3B,IAAI,OAAO,WAAW,YAAY,OAAO,KAAK,MAAM,IACnD,OAAO;EAAE,OAAO,OAAO,KAAK;EAAG,QAAQ;CAAM;CAE9C,MAAM,QAAQ,uBACb,QAAQ,YAAY,EAAE,WAAW,QAAQ,UAAU,IAAI,CAAC,CACzD;CACA,IAAI,OACH,OAAO;EAAE,OAAO,MAAM;EAAc,QAAQ;CAAU;CAEvD,OAAO;AACR;;AAGA,SAAS,iBAAiB,KAA6C;CACtE,MAAM,UAAU,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,EAAE;CAC9C,OAAO,UAAU,UAAU,KAAA;AAC5B;;;;;;;;;;;;;;AAeA,SAAgB,yBACf,WACA,UAGI,CAAC,GACK;CACV,MAAM,WAAW,cAChB,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC,CAChD;CACA,IAAI,UAAU;EACb,MAAM,UACL,iBAAiB,QAAQ,OAAO,KAChC,iBAAiB,QAAQ,IAAI,aAAa;EAC3C,OAAO,kBAAkB;GACxB,QAAQ,SAAS;GACjB,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;EAC9B,CAAC;CACF;CACA,MAAM,IAAI,cACT,UAAU,eACV;EACC,GAAG,UAAU;EACb;EACA;EACA;CACD,CAAC,CAAC,KAAK,GAAG,CACX;AACD"}
+{"version":3,"file":"auth.js","names":[],"sources":["../../src/lib/auth.ts"],"sourcesContent":["import { ErrorCode, PlatformError } from \"./errors.js\";\nimport type { NeonApi } from \"./neon-api.js\";\nimport { createRealNeonApi } from \"./neon-api-real.js\";\n\n/** Trim trailing slashes and surrounding whitespace; treat empty as unset. */\nfunction normalizeApiHost(url: string | undefined): string | undefined {\n\tconst trimmed = url?.trim().replace(/\\/+$/, \"\");\n\treturn trimmed ? trimmed : undefined;\n}\n\n/**\n * Build a real {@link NeonApi} adapter from an explicit API key, or throw a uniform\n * `PLATFORM_MISSING_API_KEY` error when the caller didn't supply one.\n *\n * **This function is pure with respect to its environment**: it reads no environment\n * variables and no files. Everything it needs arrives in `options`. Resolving *where* a\n * credential comes from — a flag, `NEON_API_KEY`, a credentials file on disk — is the\n * caller's job, because only the caller knows which of those its users expect. See\n * `packages/cli` (`ensureAuth` + `resolveApiKeyFromEnv`) and `packages/init`\n * (`src/lib/auth.ts`) for the two implementations in this repo.\n *\n * `apiHost` stays **optional** and defaults to production\n * (`https://console.neon.tech/api/v2`, applied by {@link createRealNeonApi}) — only pass it\n * to target a non-production API. It is the *ambient* `NEON_API_HOST` lookup that's gone,\n * not the default.\n *\n * Used by `pullConfig`, `pushConfig`, `fetchEnv`, and `branch` to build their default\n * adapter when the caller doesn't inject one. `operation` is the calling function's name\n * (e.g. `\"pushConfig\"`, `\"branch\"`) — it's prepended to the error message so users can tell\n * which call surfaced the missing key.\n */\nexport function createNeonApiFromOptions(\n\toperation: string,\n\toptions: {\n\t\tapiKey?: string;\n\t\tapiHost?: string;\n\t} = {},\n): NeonApi {\n\tconst apiKey = options.apiKey?.trim();\n\tif (!apiKey) {\n\t\tthrow new PlatformError(\n\t\t\tErrorCode.MissingApiKey,\n\t\t\t[\n\t\t\t\t`${operation} was not given a Neon API key.`,\n\t\t\t\t\"Pass `apiKey` explicitly, or inject your own `api` adapter (e.g. an in-memory fake for tests).\",\n\t\t\t\t\"This package never reads NEON_API_KEY or a credentials file on your behalf — resolve the key in your own application or CLI and pass it in.\",\n\t\t\t\t\"Generate a key at https://console.neon.tech/app/settings/api-keys.\",\n\t\t\t].join(\" \"),\n\t\t);\n\t}\n\n\tconst baseUrl = normalizeApiHost(options.apiHost);\n\treturn createRealNeonApi({\n\t\tapiKey,\n\t\t...(baseUrl ? { baseUrl } : {}),\n\t});\n}\n"],"mappings":";;;;AAKA,SAAS,iBAAiB,KAA6C;CACtE,MAAM,UAAU,KAAK,KAAK,CAAC,CAAC,QAAQ,QAAQ,EAAE;CAC9C,OAAO,UAAU,UAAU,KAAA;AAC5B;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,yBACf,WACA,UAGI,CAAC,GACK;CACV,MAAM,SAAS,QAAQ,QAAQ,KAAK;CACpC,IAAI,CAAC,QACJ,MAAM,IAAI,cACT,UAAU,eACV;EACC,GAAG,UAAU;EACb;EACA;EACA;CACD,CAAC,CAAC,KAAK,GAAG,CACX;CAGD,MAAM,UAAU,iBAAiB,QAAQ,OAAO;CAChD,OAAO,kBAAkB;EACxB;EACA,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAC9B,CAAC;AACF"}

package/dist/lib/loader.js

@@ -1,8 +1,8 @@
 import { ConfigLoadError, isPlatformError } from "./errors.js";
 import { defineConfig } from "./define-config.js";
 import { existsSync, statSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
 import { homedir } from "node:os";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/lib/loader.ts
 /**

package/dist/v1.d.ts

@@ -1,7 +1,7 @@
 import { AppliedChange, BranchTarget, BranchTuning, BranchTuningFn, BucketAccessLevel, BucketDef, ComputeSettings, ComputeUnit, Config, ConflictReport, CredentialPrincipalType, CredentialScope, DATA_API_AUTH_PROVIDERS, DataApiAuthProvider, DataApiConfig, DataApiExternalAuthConfig, DataApiInput, DataApiNeonAuthConfig, DataApiSettings, DurationString, DurationUnit, FunctionDef, FunctionDevConfig, FunctionRuntime, FunctionTuning, PostgresConfig, PreviewInput, PreviewTuning, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedDataApiConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceEnabled, ServiceToggle, ServiceToggleInput } from "./lib/types.js";
 import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, isPartialBranchCreateError, isPlatformError } from "./lib/errors.js";
 import { CreateBranchInput, CreateBucketInput, CreateCredentialInput, CreateProjectInput, DeployFunctionInput, EnableDataApiInput, GetConnectionUriInput, NeonApi, NeonAuthSnapshot, NeonBranchSnapshot, NeonBranchStorageSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonCredentialSecret, NeonDataApiSnapshot, NeonDatabaseSnapshot, NeonEndpointSnapshot, NeonFunctionDeploymentSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot, NeonRoleSnapshot, UpdateBranchInput } from "./lib/neon-api.js";
-import { createNeonApiFromOptions, resolveApiKey } from "./lib/auth.js";
+import { createNeonApiFromOptions } from "./lib/auth.js";
 import { CredentialFeatureFlags, credentialScopesSatisfied, deriveCredentialScopes } from "./lib/credentials.js";
 import { defineConfig, resolveConfig } from "./lib/define-config.js";
 import { DiffOptions, DiffResult, PlanStep, RemotePreviewState, RemoteServiceState, RemoteState, diffConfig } from "./lib/diff.js";
@@ -213,5 +213,5 @@ declare const schemas: {
   }, zod_v4_core0.$strict>]>;
 };
 //#endregion
-export { type AppliedChange, type BranchTarget, type BranchTuning, type BranchTuningFn, type BucketAccessLevel, type BucketDef, type ComputeSettings, type ComputeUnit, type Config, ConfigLoadError, ConfigValidationError, type ConflictReport, type CreateBranchInput, type CreateBucketInput, type CreateCredentialInput, type CreateProjectInput, type CredentialFeatureFlags, type CredentialPrincipalType, type CredentialScope, DATA_API_AUTH_PROVIDERS, type DataApiAuthProvider, type DataApiConfig, type DataApiExternalAuthConfig, type DataApiInput, type DataApiNeonAuthConfig, type DataApiSettings, type DeployFunctionInput, type DiffOptions, type DiffResult, type DurationString, type DurationUnit, type EnableDataApiInput, ErrorCode, type FunctionDef, type FunctionDevConfig, type FunctionRuntime, type FunctionTuning, type GetConnectionUriInput, type LoadConfigOptions, MissingContextError, type NeonApi, type NeonAuthSnapshot, type NeonBranchSnapshot, type NeonBranchStorageSnapshot, type NeonBucketSnapshot, type NeonCredentialMeta, type NeonCredentialSecret, type NeonDataApiSnapshot, type NeonDatabaseSnapshot, type NeonEndpointSnapshot, type NeonFunctionDeploymentSnapshot, type NeonFunctionSnapshot, type NeonProjectSnapshot, type NeonRoleSnapshot, PartialBranchCreateError, type PlanStep, PlatformError, type PostgresConfig, type PreviewInput, type PreviewTuning, PushAbortedError, PushConflictError, type PushResult, type RemotePreviewState, type RemoteServiceState, type RemoteState, type ResolvedBranchConfig, type ResolvedBucketConfig, type ResolvedDataApiConfig, type ResolvedFunctionConfig, type ResolvedPreviewConfig, type ServiceEnabled, type ServiceToggle, type ServiceToggleInput, type UpdateBranchInput, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveApiKey, resolveConfig, schemas };
+export { type AppliedChange, type BranchTarget, type BranchTuning, type BranchTuningFn, type BucketAccessLevel, type BucketDef, type ComputeSettings, type ComputeUnit, type Config, ConfigLoadError, ConfigValidationError, type ConflictReport, type CreateBranchInput, type CreateBucketInput, type CreateCredentialInput, type CreateProjectInput, type CredentialFeatureFlags, type CredentialPrincipalType, type CredentialScope, DATA_API_AUTH_PROVIDERS, type DataApiAuthProvider, type DataApiConfig, type DataApiExternalAuthConfig, type DataApiInput, type DataApiNeonAuthConfig, type DataApiSettings, type DeployFunctionInput, type DiffOptions, type DiffResult, type DurationString, type DurationUnit, type EnableDataApiInput, ErrorCode, type FunctionDef, type FunctionDevConfig, type FunctionRuntime, type FunctionTuning, type GetConnectionUriInput, type LoadConfigOptions, MissingContextError, type NeonApi, type NeonAuthSnapshot, type NeonBranchSnapshot, type NeonBranchStorageSnapshot, type NeonBucketSnapshot, type NeonCredentialMeta, type NeonCredentialSecret, type NeonDataApiSnapshot, type NeonDatabaseSnapshot, type NeonEndpointSnapshot, type NeonFunctionDeploymentSnapshot, type NeonFunctionSnapshot, type NeonProjectSnapshot, type NeonRoleSnapshot, PartialBranchCreateError, type PlanStep, PlatformError, type PostgresConfig, type PreviewInput, type PreviewTuning, PushAbortedError, PushConflictError, type PushResult, type RemotePreviewState, type RemoteServiceState, type RemoteState, type ResolvedBranchConfig, type ResolvedBucketConfig, type ResolvedDataApiConfig, type ResolvedFunctionConfig, type ResolvedPreviewConfig, type ServiceEnabled, type ServiceToggle, type ServiceToggleInput, type UpdateBranchInput, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveConfig, schemas };
 //# sourceMappingURL=v1.d.ts.map

package/dist/v1.js

@@ -1,7 +1,7 @@
 import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, isPartialBranchCreateError, isPlatformError } from "./lib/errors.js";
 import { branchTuningSchema, bucketDefSchema, computeSettingsSchema, configInputSchema, dataApiConfigSchema, dataApiInputSchema, dataApiSettingsSchema, functionDefSchema, functionTuningSchema, postgresConfigSchema, previewInputSchema, serviceToggleInputSchema, serviceToggleSchema } from "./lib/schema.js";
 import { createRealNeonApi } from "./lib/neon-api-real.js";
-import { createNeonApiFromOptions, resolveApiKey } from "./lib/auth.js";
+import { createNeonApiFromOptions } from "./lib/auth.js";
 import { credentialScopesSatisfied, deriveCredentialScopes } from "./lib/credentials.js";
 import { defineConfig, resolveConfig } from "./lib/define-config.js";
 import { diffConfig } from "./lib/diff.js";
@@ -79,6 +79,6 @@ const schemas = {
 	serviceInput: serviceToggleInputSchema
 };
 //#endregion
-export { ConfigLoadError, ConfigValidationError, DATA_API_AUTH_PROVIDERS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveApiKey, resolveConfig, schemas };
+export { ConfigLoadError, ConfigValidationError, DATA_API_AUTH_PROVIDERS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, credentialScopesSatisfied, defineConfig, deriveCredentialScopes, diffConfig, errors, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, resolveConfig, schemas };
 
 //# sourceMappingURL=v1.js.map

package/dist/v1.js.map

@@ -1 +1 @@
-{"version":3,"file":"v1.js","names":[],"sources":["../src/v1.ts"],"sourcesContent":["/**\n * `@neon/config/v1` — the v1 public API for Config-as-Code on Neon.\n *\n * Usage in `neon.ts`:\n * ```ts\n * import { defineConfig } from \"@neon/config/v1\";\n *\n * export default defineConfig({\n *   // Static: what *exists* on every branch (drives the typed env).\n *   auth: true,\n *   // Dynamic: per-branch tuning only — cannot add/remove services.\n *   branch: (branch) => ({\n *     protected: branch.name === \"main\",\n *     ...(branch.name === \"main\" ? {} : { parent: \"main\", ttl: \"7d\" }),\n *   }),\n * });\n * ```\n *\n * This is the **authoring** surface — `defineConfig`, types, schemas, the pure diff engine,\n * and the Neon API adapter. It is intentionally free of heavy/native dependencies so that\n * importing it from `neon.ts` stays cheap and bundler-safe.\n *\n * The imperative operations (`inspect` / `plan` / `apply`, `pushConfig` / `pullConfig`) and\n * function bundling/deploy live in **`@neon/config-runtime`**, which depends on this\n * package and pulls in `esbuild`. Import that from your CLI / CI, not from `neon.ts`:\n * ```ts\n * import config from \"../neon\";\n * import { inspect, plan, apply } from \"@neon/config-runtime/v1\";\n * ```\n *\n * Surface guidelines:\n * - Top-level: `defineConfig` / `resolveConfig`, the pure `diffConfig` engine, the\n *   `createRealNeonApi` adapter + `NeonApi` types, the config loader, the `PlatformError`\n *   base class + `ErrorCode` enum, and the config types used in `neon.ts`.\n * - `errors` namespace: specific `PlatformError` subclasses (`ConfigLoadError`,\n *   `PushConflictError`, …).\n * - `schemas` namespace: the zod schemas underlying `defineConfig`.\n */\n\nimport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nimport {\n\tbranchTuningSchema,\n\tbucketDefSchema,\n\tcomputeSettingsSchema,\n\tconfigInputSchema,\n\tdataApiConfigSchema,\n\tdataApiInputSchema,\n\tdataApiSettingsSchema,\n\tfunctionDefSchema,\n\tfunctionTuningSchema,\n\tpostgresConfigSchema,\n\tpreviewInputSchema,\n\tserviceToggleInputSchema,\n\tserviceToggleSchema,\n} from \"./lib/schema.js\";\n\n/**\n * Specific `PlatformError` subclasses, grouped for `instanceof` / structured access.\n * Also available as top-level exports.\n */\nexport const errors = {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} as const;\n\n/** The zod schemas underlying `defineConfig`, grouped under product-friendly names. */\nexport const schemas = {\n\tconfig: configInputSchema,\n\tbranchTuning: branchTuningSchema,\n\tbucket: bucketDefSchema,\n\tcomputeSettings: computeSettingsSchema,\n\tdataApi: dataApiConfigSchema,\n\tdataApiInput: dataApiInputSchema,\n\tdataApiSettings: dataApiSettingsSchema,\n\tfunction: functionDefSchema,\n\tfunctionTuning: functionTuningSchema,\n\tpostgres: postgresConfigSchema,\n\tpreview: previewInputSchema,\n\tservice: serviceToggleSchema,\n\tserviceInput: serviceToggleInputSchema,\n} as const;\n\n// ─── Lower-level adapters ──────────────────────────────────────────────────────\nexport { createNeonApiFromOptions, resolveApiKey } from \"./lib/auth.js\";\n// ─── Credentials (pure scope derivation; Preview) ─────────────────────────────\nexport type { CredentialFeatureFlags } from \"./lib/credentials.js\";\nexport {\n\tcredentialScopesSatisfied,\n\tderiveCredentialScopes,\n} from \"./lib/credentials.js\";\nexport { defineConfig, resolveConfig } from \"./lib/define-config.js\";\n// ─── Diff engine (pure; consumed by @neon/config-runtime) ─────────────\nexport type {\n\tDiffOptions,\n\tDiffResult,\n\tPlanStep,\n\tRemotePreviewState,\n\tRemoteServiceState,\n\tRemoteState,\n} from \"./lib/diff.js\";\nexport { diffConfig } from \"./lib/diff.js\";\n// ─── Errors ────────────────────────────────────────────────────────────────────\nexport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nexport type { LoadConfigOptions } from \"./lib/loader.js\";\nexport { loadConfigFromFile } from \"./lib/loader.js\";\n// ─── NeonApi types (needed by callers implementing their own adapters) ────────\nexport type {\n\tCreateBranchInput,\n\tCreateBucketInput,\n\tCreateCredentialInput,\n\tCreateProjectInput,\n\tDeployFunctionInput,\n\tEnableDataApiInput,\n\tGetConnectionUriInput,\n\tNeonApi,\n\tNeonAuthSnapshot,\n\tNeonBranchSnapshot,\n\tNeonBranchStorageSnapshot,\n\tNeonBucketSnapshot,\n\tNeonCredentialMeta,\n\tNeonCredentialSecret,\n\tNeonDataApiSnapshot,\n\tNeonDatabaseSnapshot,\n\tNeonEndpointSnapshot,\n\tNeonFunctionDeploymentSnapshot,\n\tNeonFunctionSnapshot,\n\tNeonProjectSnapshot,\n\tNeonRoleSnapshot,\n\tUpdateBranchInput,\n} from \"./lib/neon-api.js\";\nexport { createRealNeonApi } from \"./lib/neon-api-real.js\";\nexport type {\n\tAppliedChange,\n\tBranchTarget,\n\tBranchTuning,\n\tBranchTuningFn,\n\tBucketAccessLevel,\n\tBucketDef,\n\tComputeSettings,\n\tComputeUnit,\n\tConfig,\n\tConflictReport,\n\tCredentialPrincipalType,\n\tCredentialScope,\n\tDataApiAuthProvider,\n\tDataApiConfig,\n\tDataApiExternalAuthConfig,\n\tDataApiInput,\n\tDataApiNeonAuthConfig,\n\tDataApiSettings,\n\tDurationString,\n\tDurationUnit,\n\tFunctionDef,\n\tFunctionDevConfig,\n\tFunctionRuntime,\n\tFunctionTuning,\n\tPostgresConfig,\n\tPreviewInput,\n\tPreviewTuning,\n\tPushResult,\n\tResolvedBranchConfig,\n\tResolvedBucketConfig,\n\tResolvedDataApiConfig,\n\tResolvedFunctionConfig,\n\tResolvedPreviewConfig,\n\tServiceEnabled,\n\tServiceToggle,\n\tServiceToggleInput,\n} from \"./lib/types.js\";\n// ─── Config types (used in neon.ts and in operation return values) ────────────\nexport { DATA_API_AUTH_PROVIDERS } from \"./lib/types.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,MAAa,SAAS;CACrB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;;AAGA,MAAa,UAAU;CACtB,QAAQ;CACR,cAAc;CACd,QAAQ;CACR,iBAAiB;CACjB,SAAS;CACT,cAAc;CACd,iBAAiB;CACjB,UAAU;CACV,gBAAgB;CAChB,UAAU;CACV,SAAS;CACT,SAAS;CACT,cAAc;AACf"}
+{"version":3,"file":"v1.js","names":[],"sources":["../src/v1.ts"],"sourcesContent":["/**\n * `@neon/config/v1` — the v1 public API for Config-as-Code on Neon.\n *\n * Usage in `neon.ts`:\n * ```ts\n * import { defineConfig } from \"@neon/config/v1\";\n *\n * export default defineConfig({\n *   // Static: what *exists* on every branch (drives the typed env).\n *   auth: true,\n *   // Dynamic: per-branch tuning only — cannot add/remove services.\n *   branch: (branch) => ({\n *     protected: branch.name === \"main\",\n *     ...(branch.name === \"main\" ? {} : { parent: \"main\", ttl: \"7d\" }),\n *   }),\n * });\n * ```\n *\n * This is the **authoring** surface — `defineConfig`, types, schemas, the pure diff engine,\n * and the Neon API adapter. It is intentionally free of heavy/native dependencies so that\n * importing it from `neon.ts` stays cheap and bundler-safe.\n *\n * The imperative operations (`inspect` / `plan` / `apply`, `pushConfig` / `pullConfig`) and\n * function bundling/deploy live in **`@neon/config-runtime`**, which depends on this\n * package and pulls in `esbuild`. Import that from your CLI / CI, not from `neon.ts`:\n * ```ts\n * import config from \"../neon\";\n * import { inspect, plan, apply } from \"@neon/config-runtime/v1\";\n * ```\n *\n * Surface guidelines:\n * - Top-level: `defineConfig` / `resolveConfig`, the pure `diffConfig` engine, the\n *   `createRealNeonApi` adapter + `NeonApi` types, the config loader, the `PlatformError`\n *   base class + `ErrorCode` enum, and the config types used in `neon.ts`.\n * - `errors` namespace: specific `PlatformError` subclasses (`ConfigLoadError`,\n *   `PushConflictError`, …).\n * - `schemas` namespace: the zod schemas underlying `defineConfig`.\n */\n\nimport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nimport {\n\tbranchTuningSchema,\n\tbucketDefSchema,\n\tcomputeSettingsSchema,\n\tconfigInputSchema,\n\tdataApiConfigSchema,\n\tdataApiInputSchema,\n\tdataApiSettingsSchema,\n\tfunctionDefSchema,\n\tfunctionTuningSchema,\n\tpostgresConfigSchema,\n\tpreviewInputSchema,\n\tserviceToggleInputSchema,\n\tserviceToggleSchema,\n} from \"./lib/schema.js\";\n\n/**\n * Specific `PlatformError` subclasses, grouped for `instanceof` / structured access.\n * Also available as top-level exports.\n */\nexport const errors = {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} as const;\n\n/** The zod schemas underlying `defineConfig`, grouped under product-friendly names. */\nexport const schemas = {\n\tconfig: configInputSchema,\n\tbranchTuning: branchTuningSchema,\n\tbucket: bucketDefSchema,\n\tcomputeSettings: computeSettingsSchema,\n\tdataApi: dataApiConfigSchema,\n\tdataApiInput: dataApiInputSchema,\n\tdataApiSettings: dataApiSettingsSchema,\n\tfunction: functionDefSchema,\n\tfunctionTuning: functionTuningSchema,\n\tpostgres: postgresConfigSchema,\n\tpreview: previewInputSchema,\n\tservice: serviceToggleSchema,\n\tserviceInput: serviceToggleInputSchema,\n} as const;\n\n// ─── Lower-level adapters ──────────────────────────────────────────────────────\nexport { createNeonApiFromOptions } from \"./lib/auth.js\";\n// ─── Credentials (pure scope derivation; Preview) ─────────────────────────────\nexport type { CredentialFeatureFlags } from \"./lib/credentials.js\";\nexport {\n\tcredentialScopesSatisfied,\n\tderiveCredentialScopes,\n} from \"./lib/credentials.js\";\nexport { defineConfig, resolveConfig } from \"./lib/define-config.js\";\n// ─── Diff engine (pure; consumed by @neon/config-runtime) ─────────────\nexport type {\n\tDiffOptions,\n\tDiffResult,\n\tPlanStep,\n\tRemotePreviewState,\n\tRemoteServiceState,\n\tRemoteState,\n} from \"./lib/diff.js\";\nexport { diffConfig } from \"./lib/diff.js\";\n// ─── Errors ────────────────────────────────────────────────────────────────────\nexport {\n\tConfigLoadError,\n\tConfigValidationError,\n\tErrorCode,\n\tisPartialBranchCreateError,\n\tisPlatformError,\n\tMissingContextError,\n\tPartialBranchCreateError,\n\tPlatformError,\n\tPushAbortedError,\n\tPushConflictError,\n} from \"./lib/errors.js\";\nexport type { LoadConfigOptions } from \"./lib/loader.js\";\nexport { loadConfigFromFile } from \"./lib/loader.js\";\n// ─── NeonApi types (needed by callers implementing their own adapters) ────────\nexport type {\n\tCreateBranchInput,\n\tCreateBucketInput,\n\tCreateCredentialInput,\n\tCreateProjectInput,\n\tDeployFunctionInput,\n\tEnableDataApiInput,\n\tGetConnectionUriInput,\n\tNeonApi,\n\tNeonAuthSnapshot,\n\tNeonBranchSnapshot,\n\tNeonBranchStorageSnapshot,\n\tNeonBucketSnapshot,\n\tNeonCredentialMeta,\n\tNeonCredentialSecret,\n\tNeonDataApiSnapshot,\n\tNeonDatabaseSnapshot,\n\tNeonEndpointSnapshot,\n\tNeonFunctionDeploymentSnapshot,\n\tNeonFunctionSnapshot,\n\tNeonProjectSnapshot,\n\tNeonRoleSnapshot,\n\tUpdateBranchInput,\n} from \"./lib/neon-api.js\";\nexport { createRealNeonApi } from \"./lib/neon-api-real.js\";\nexport type {\n\tAppliedChange,\n\tBranchTarget,\n\tBranchTuning,\n\tBranchTuningFn,\n\tBucketAccessLevel,\n\tBucketDef,\n\tComputeSettings,\n\tComputeUnit,\n\tConfig,\n\tConflictReport,\n\tCredentialPrincipalType,\n\tCredentialScope,\n\tDataApiAuthProvider,\n\tDataApiConfig,\n\tDataApiExternalAuthConfig,\n\tDataApiInput,\n\tDataApiNeonAuthConfig,\n\tDataApiSettings,\n\tDurationString,\n\tDurationUnit,\n\tFunctionDef,\n\tFunctionDevConfig,\n\tFunctionRuntime,\n\tFunctionTuning,\n\tPostgresConfig,\n\tPreviewInput,\n\tPreviewTuning,\n\tPushResult,\n\tResolvedBranchConfig,\n\tResolvedBucketConfig,\n\tResolvedDataApiConfig,\n\tResolvedFunctionConfig,\n\tResolvedPreviewConfig,\n\tServiceEnabled,\n\tServiceToggle,\n\tServiceToggleInput,\n} from \"./lib/types.js\";\n// ─── Config types (used in neon.ts and in operation return values) ────────────\nexport { DATA_API_AUTH_PROVIDERS } from \"./lib/types.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,MAAa,SAAS;CACrB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;;AAGA,MAAa,UAAU;CACtB,QAAQ;CACR,cAAc;CACd,QAAQ;CACR,iBAAiB;CACjB,SAAS;CACT,cAAc;CACd,iBAAiB;CACjB,UAAU;CACV,gBAAgB;CAChB,UAAU;CACV,SAAS;CACT,SAAS;CACT,cAAc;AACf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neondatabase/config",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Config-as-Code for Neon. Define a `neon.ts` policy and inspect/diff/deploy it against the Neon API as plain TypeScript functions.",
   "keywords": [
     "neon",