@neondatabase/config 0.0.0 → 0.2.0

package/dist/lib/diff.d.ts

@@ -0,0 +1,109 @@
+import { BucketAccessLevel, ComputeSettings, ConflictReport, ResolvedBranchConfig, ResolvedFunctionConfig } from "./types.js";
+import { NeonBranchSnapshot, NeonBucketSnapshot, NeonEndpointSnapshot, NeonFunctionSnapshot } from "./neon-api.js";
+
+//#region src/lib/diff.d.ts
+
+/**
+ * A planned action to perform a single mutation against the Neon API. The diff engine
+ * produces a list of these for `pushConfig` to execute (or report).
+ */
+type PlanStep = {
+  kind: "update-branch-ttl";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  expiresAt: string | null;
+} | {
+  kind: "update-branch-protected";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  protected: boolean;
+} | {
+  kind: "update-endpoint";
+  projectId: string;
+  branchName: string;
+  endpointId: string;
+  settings: ComputeSettings;
+} | {
+  kind: "enable-auth";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  databaseName?: string;
+} | {
+  kind: "enable-data-api";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  databaseName: string;
+} | {
+  kind: "create-bucket";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  bucketName: string;
+  accessLevel: BucketAccessLevel;
+} | {
+  kind: "create-function";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  fn: ResolvedFunctionConfig;
+} | {
+  /**
+   * Deploy (or re-deploy) code to a function. Always planned for every desired
+   * function — deployments are versioned and the newest becomes active, so a push
+   * ships the current source each time. `functionExists` tells `pushConfig` whether
+   * it must create the function first (covered by a preceding `create-function` step).
+   */
+  kind: "deploy-function";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  fn: ResolvedFunctionConfig;
+} | {
+  kind: "enable-ai-gateway";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+};
+interface RemoteServiceState {
+  databaseName: string;
+  authEnabled: boolean;
+  dataApiEnabled: boolean;
+}
+/**
+ * Snapshot of the branch's current Preview-feature state. Absent (`undefined`) when the
+ * policy has no `preview` block — `pushConfig` only fetches this when needed.
+ */
+interface RemotePreviewState {
+  buckets: NeonBucketSnapshot[];
+  functions: NeonFunctionSnapshot[];
+  aiGatewayEnabled: boolean;
+}
+interface RemoteState {
+  projectId: string;
+  branch: NeonBranchSnapshot;
+  endpoint?: NeonEndpointSnapshot;
+  services: RemoteServiceState;
+  preview?: RemotePreviewState;
+}
+interface DiffOptions {
+  /**
+   * Apply mutable drift on the selected branch as plan steps instead of conflicts.
+   * Default: `false`.
+   */
+  updateExisting: boolean;
+}
+interface DiffResult {
+  plan: PlanStep[];
+  conflicts: ConflictReport[];
+}
+/**
+ * Diff desired branch policy against the selected remote branch. Pure function.
+ */
+declare function diffConfig(config: ResolvedBranchConfig, remote: RemoteState, options: DiffOptions): DiffResult;
+//#endregion
+export { DiffOptions, DiffResult, PlanStep, RemotePreviewState, RemoteServiceState, RemoteState, diffConfig };
+//# sourceMappingURL=diff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","names":[],"sources":["../../src/lib/diff.ts"],"mappings":";;;;;;;AAkBA;;AAoBa,KApBD,QAAA,GAoBC;MAsBG,EAAA,mBAAA;WAOT,EAAA,MAAA;UAaA,EAAA,MAAA;EAAsB,UAAA,EAAA,MAAA;EASZ,SAAA,EAAA,MAAA,GAAA,IAAkB;AAUnC,CAAA,GAAiB;EAAkB,IAAA,EAAA,yBAAA;WACzB,EAAA,MAAA;UACE,EAAA,MAAA;EAAoB,UAAA,EAAA,MAAA;EAIf,SAAA,EAAA,OAAW;CAAA,GAAA;MAEnB,EAAA,iBAAA;WACG,EAAA,MAAA;YACD,EAAA,MAAA;YACA,EAAA,MAAA;EAAkB,QAAA,EAxEhB,eAwEgB;AAG7B,CAAA,GAAiB;EAQA,IAAA,EAAA,aAAU;EAAA,SAAA,EAAA,MAAA;UACpB,EAAA,MAAA;YACK,EAAA,MAAA;EAAc,YAAA,CAAA,EAAA,MAAA;AAM1B,CAAA,GAAgB;EAAU,IAAA,EAAA,iBAAA;WACjB,EAAA,MAAA;UACA,EAAA,MAAA;YACC,EAAA,MAAA;cACP,EAAA,MAAA;AAAU,CAAA,GAAA;;;;;;eAzEG;;;;;;MAOT;;;;;;;;;;;;MAaA;;;;;;;UASU,kBAAA;;;;;;;;;UAUA,kBAAA;WACP;aACE;;;UAIK,WAAA;;UAER;aACG;YACD;YACA;;UAGM,WAAA;;;;;;;UAQA,UAAA;QACV;aACK;;;;;iBAMI,UAAA,SACP,8BACA,sBACC,cACP"}

package/dist/lib/diff.js

@@ -0,0 +1,205 @@
+//#region src/lib/diff.ts
+/**
+* Diff desired branch policy against the selected remote branch. Pure function.
+*/
+function diffConfig(config, remote, options) {
+	const conflicts = [];
+	const plan = [];
+	diffBranchConfig({
+		config,
+		remote,
+		options,
+		plan,
+		conflicts
+	});
+	diffServices({
+		config,
+		remote,
+		plan
+	});
+	diffPreview({
+		config,
+		remote,
+		plan
+	});
+	return {
+		plan,
+		conflicts
+	};
+}
+/**
+* Plan Preview features (functions, buckets, AI Gateway). Like {@link diffServices}, this
+* is **additive**: it creates desired buckets/functions and enables the AI Gateway, but
+* never deletes buckets/functions or disables the gateway. Teardown is destructive, so it
+* stays explicit/manual — matching the existing auth / dataApi behaviour.
+*
+* Functions are always (re-)deployed: deployments are versioned and the newest becomes
+* active, so each push ships the current source. A `create-function` step precedes the
+* `deploy-function` step when the function does not yet exist remotely.
+*/
+function diffPreview(args) {
+	const { config, remote, plan } = args;
+	const preview = config.preview;
+	if (!preview) return;
+	const state = remote.preview ?? {
+		buckets: [],
+		functions: [],
+		aiGatewayEnabled: false
+	};
+	for (const bucket of preview.buckets) {
+		if (state.buckets.some((b) => b.name === bucket.name)) continue;
+		plan.push({
+			kind: "create-bucket",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+			bucketName: bucket.name,
+			accessLevel: bucket.access
+		});
+	}
+	for (const fn of preview.functions) {
+		if (!state.functions.some((f) => f.slug === fn.slug)) plan.push({
+			kind: "create-function",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+			fn
+		});
+		plan.push({
+			kind: "deploy-function",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+			fn
+		});
+	}
+	if (preview.aiGatewayEnabled && !state.aiGatewayEnabled) plan.push({
+		kind: "enable-ai-gateway",
+		projectId: remote.projectId,
+		branchId: remote.branch.id,
+		branchName: remote.branch.name
+	});
+}
+/**
+* Plan additive branch-scoped integrations. Disabling remains explicit/manual because
+* teardown is destructive.
+*/
+function diffServices(args) {
+	const { config, remote, plan } = args;
+	const state = remote.services;
+	if (config.authEnabled && !state.authEnabled) {
+		const step = {
+			kind: "enable-auth",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name
+		};
+		if (state.databaseName) step.databaseName = state.databaseName;
+		plan.push(step);
+	}
+	if (config.dataApiEnabled && !state.dataApiEnabled) plan.push({
+		kind: "enable-data-api",
+		projectId: remote.projectId,
+		branchId: remote.branch.id,
+		branchName: remote.branch.name,
+		databaseName: state.databaseName
+	});
+}
+function diffBranchConfig(args) {
+	const { config, remote, options, plan, conflicts } = args;
+	const branchName = remote.branch.name;
+	const computeSettings = config.postgres?.computeSettings;
+	if (computeSettings) {
+		const endpoint = remote.endpoint;
+		if (!endpoint) conflicts.push({
+			kind: "branch",
+			identifier: branchName,
+			field: "endpoint",
+			current: void 0,
+			desired: computeSettings,
+			reason: "Branch has no read-write endpoint; cannot apply compute settings."
+		});
+		else {
+			const drift = computeDriftBetween(computeSettings, endpoint);
+			if (drift) if (options.updateExisting) plan.push({
+				kind: "update-endpoint",
+				projectId: remote.projectId,
+				branchName,
+				endpointId: endpoint.id,
+				settings: computeSettings
+			});
+			else conflicts.push({
+				kind: "branch",
+				identifier: branchName,
+				field: "computeSettings",
+				current: drift.current,
+				desired: drift.desired,
+				reason: "Existing branch has different compute settings. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply."
+			});
+		}
+	}
+	if (config.protected !== void 0 && config.protected !== remote.branch.protected) if (options.updateExisting) plan.push({
+		kind: "update-branch-protected",
+		projectId: remote.projectId,
+		branchId: remote.branch.id,
+		branchName,
+		protected: config.protected
+	});
+	else conflicts.push({
+		kind: "branch",
+		identifier: branchName,
+		field: "protected",
+		current: remote.branch.protected,
+		desired: config.protected,
+		reason: "Existing branch has a different `protected` flag. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply."
+	});
+	if (config.ttlSeconds !== void 0) {
+		const current = remote.branch.expiresAt ? Math.max(0, Math.round((Date.parse(remote.branch.expiresAt) - Date.now()) / 1e3)) : void 0;
+		if (current === void 0 || Math.abs(current - config.ttlSeconds) > 30) {
+			const expiresAt = new Date(Date.now() + config.ttlSeconds * 1e3).toISOString();
+			if (options.updateExisting) plan.push({
+				kind: "update-branch-ttl",
+				projectId: remote.projectId,
+				branchId: remote.branch.id,
+				branchName,
+				expiresAt
+			});
+			else conflicts.push({
+				kind: "branch",
+				identifier: branchName,
+				field: "ttl",
+				current: remote.branch.expiresAt,
+				desired: expiresAt,
+				reason: "Existing branch has a different TTL. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply."
+			});
+		}
+	}
+}
+function computeDriftBetween(desired, endpoint) {
+	const currentDrift = {};
+	const desiredDrift = {};
+	let drift = false;
+	if (desired.autoscalingLimitMinCu !== void 0 && desired.autoscalingLimitMinCu !== endpoint.autoscalingLimitMinCu) {
+		currentDrift.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;
+		desiredDrift.autoscalingLimitMinCu = desired.autoscalingLimitMinCu;
+		drift = true;
+	}
+	if (desired.autoscalingLimitMaxCu !== void 0 && desired.autoscalingLimitMaxCu !== endpoint.autoscalingLimitMaxCu) {
+		currentDrift.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;
+		desiredDrift.autoscalingLimitMaxCu = desired.autoscalingLimitMaxCu;
+		drift = true;
+	}
+	if (desired.suspendTimeout !== void 0 && desired.suspendTimeout !== endpoint.suspendTimeout) {
+		currentDrift.suspendTimeout = endpoint.suspendTimeout;
+		desiredDrift.suspendTimeout = desired.suspendTimeout;
+		drift = true;
+	}
+	return drift ? {
+		current: currentDrift,
+		desired: desiredDrift
+	} : null;
+}
+//#endregion
+export { diffConfig };
+
+//# sourceMappingURL=diff.js.map

package/dist/lib/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","names":[],"sources":["../../src/lib/diff.ts"],"sourcesContent":["import type {\n\tNeonBranchSnapshot,\n\tNeonBucketSnapshot,\n\tNeonEndpointSnapshot,\n\tNeonFunctionSnapshot,\n} from \"./neon-api.js\";\nimport type {\n\tBucketAccessLevel,\n\tComputeSettings,\n\tConflictReport,\n\tResolvedBranchConfig,\n\tResolvedFunctionConfig,\n} from \"./types.js\";\n\n/**\n * A planned action to perform a single mutation against the Neon API. The diff engine\n * produces a list of these for `pushConfig` to execute (or report).\n */\nexport type PlanStep =\n\t| {\n\t\t\tkind: \"update-branch-ttl\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\texpiresAt: string | null;\n\t  }\n\t| {\n\t\t\tkind: \"update-branch-protected\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\tprotected: boolean;\n\t  }\n\t| {\n\t\t\tkind: \"update-endpoint\";\n\t\t\tprojectId: string;\n\t\t\tbranchName: string;\n\t\t\tendpointId: string;\n\t\t\tsettings: ComputeSettings;\n\t  }\n\t| {\n\t\t\tkind: \"enable-auth\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\tdatabaseName?: string;\n\t  }\n\t| {\n\t\t\tkind: \"enable-data-api\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\tdatabaseName: string;\n\t  }\n\t| {\n\t\t\tkind: \"create-bucket\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\tbucketName: string;\n\t\t\taccessLevel: BucketAccessLevel;\n\t  }\n\t| {\n\t\t\tkind: \"create-function\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\tfn: ResolvedFunctionConfig;\n\t  }\n\t| {\n\t\t\t/**\n\t\t\t * Deploy (or re-deploy) code to a function. Always planned for every desired\n\t\t\t * function — deployments are versioned and the newest becomes active, so a push\n\t\t\t * ships the current source each time. `functionExists` tells `pushConfig` whether\n\t\t\t * it must create the function first (covered by a preceding `create-function` step).\n\t\t\t */\n\t\t\tkind: \"deploy-function\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t\t\tfn: ResolvedFunctionConfig;\n\t  }\n\t| {\n\t\t\tkind: \"enable-ai-gateway\";\n\t\t\tprojectId: string;\n\t\t\tbranchId: string;\n\t\t\tbranchName: string;\n\t  };\n\nexport interface RemoteServiceState {\n\tdatabaseName: string;\n\tauthEnabled: boolean;\n\tdataApiEnabled: boolean;\n}\n\n/**\n * Snapshot of the branch's current Preview-feature state. Absent (`undefined`) when the\n * policy has no `preview` block — `pushConfig` only fetches this when needed.\n */\nexport interface RemotePreviewState {\n\tbuckets: NeonBucketSnapshot[];\n\tfunctions: NeonFunctionSnapshot[];\n\taiGatewayEnabled: boolean;\n}\n\nexport interface RemoteState {\n\tprojectId: string;\n\tbranch: NeonBranchSnapshot;\n\tendpoint?: NeonEndpointSnapshot;\n\tservices: RemoteServiceState;\n\tpreview?: RemotePreviewState;\n}\n\nexport interface DiffOptions {\n\t/**\n\t * Apply mutable drift on the selected branch as plan steps instead of conflicts.\n\t * Default: `false`.\n\t */\n\tupdateExisting: boolean;\n}\n\nexport interface DiffResult {\n\tplan: PlanStep[];\n\tconflicts: ConflictReport[];\n}\n\n/**\n * Diff desired branch policy against the selected remote branch. Pure function.\n */\nexport function diffConfig(\n\tconfig: ResolvedBranchConfig,\n\tremote: RemoteState,\n\toptions: DiffOptions,\n): DiffResult {\n\tconst conflicts: ConflictReport[] = [];\n\tconst plan: PlanStep[] = [];\n\tdiffBranchConfig({ config, remote, options, plan, conflicts });\n\tdiffServices({ config, remote, plan });\n\tdiffPreview({ config, remote, plan });\n\treturn { plan, conflicts };\n}\n\n/**\n * Plan Preview features (functions, buckets, AI Gateway). Like {@link diffServices}, this\n * is **additive**: it creates desired buckets/functions and enables the AI Gateway, but\n * never deletes buckets/functions or disables the gateway. Teardown is destructive, so it\n * stays explicit/manual — matching the existing auth / dataApi behaviour.\n *\n * Functions are always (re-)deployed: deployments are versioned and the newest becomes\n * active, so each push ships the current source. A `create-function` step precedes the\n * `deploy-function` step when the function does not yet exist remotely.\n */\nfunction diffPreview(args: {\n\tconfig: ResolvedBranchConfig;\n\tremote: RemoteState;\n\tplan: PlanStep[];\n}): void {\n\tconst { config, remote, plan } = args;\n\tconst preview = config.preview;\n\tif (!preview) return;\n\t// `remote.preview` is only fetched when the policy has a preview block; treat a missing\n\t// snapshot as \"nothing exists yet\" so the diff is still well-defined.\n\tconst state: RemotePreviewState = remote.preview ?? {\n\t\tbuckets: [],\n\t\tfunctions: [],\n\t\taiGatewayEnabled: false,\n\t};\n\n\tfor (const bucket of preview.buckets) {\n\t\tif (state.buckets.some((b) => b.name === bucket.name)) continue;\n\t\tplan.push({\n\t\t\tkind: \"create-bucket\",\n\t\t\tprojectId: remote.projectId,\n\t\t\tbranchId: remote.branch.id,\n\t\t\tbranchName: remote.branch.name,\n\t\t\tbucketName: bucket.name,\n\t\t\taccessLevel: bucket.access,\n\t\t});\n\t}\n\n\tfor (const fn of preview.functions) {\n\t\tconst exists = state.functions.some((f) => f.slug === fn.slug);\n\t\tif (!exists) {\n\t\t\tplan.push({\n\t\t\t\tkind: \"create-function\",\n\t\t\t\tprojectId: remote.projectId,\n\t\t\t\tbranchId: remote.branch.id,\n\t\t\t\tbranchName: remote.branch.name,\n\t\t\t\tfn,\n\t\t\t});\n\t\t}\n\t\tplan.push({\n\t\t\tkind: \"deploy-function\",\n\t\t\tprojectId: remote.projectId,\n\t\t\tbranchId: remote.branch.id,\n\t\t\tbranchName: remote.branch.name,\n\t\t\tfn,\n\t\t});\n\t}\n\n\tif (preview.aiGatewayEnabled && !state.aiGatewayEnabled) {\n\t\tplan.push({\n\t\t\tkind: \"enable-ai-gateway\",\n\t\t\tprojectId: remote.projectId,\n\t\t\tbranchId: remote.branch.id,\n\t\t\tbranchName: remote.branch.name,\n\t\t});\n\t}\n}\n\n/**\n * Plan additive branch-scoped integrations. Disabling remains explicit/manual because\n * teardown is destructive.\n */\nfunction diffServices(args: {\n\tconfig: ResolvedBranchConfig;\n\tremote: RemoteState;\n\tplan: PlanStep[];\n}): void {\n\tconst { config, remote, plan } = args;\n\tconst state = remote.services;\n\tif (config.authEnabled && !state.authEnabled) {\n\t\tconst step: PlanStep = {\n\t\t\tkind: \"enable-auth\",\n\t\t\tprojectId: remote.projectId,\n\t\t\tbranchId: remote.branch.id,\n\t\t\tbranchName: remote.branch.name,\n\t\t};\n\t\tif (state.databaseName) step.databaseName = state.databaseName;\n\t\tplan.push(step);\n\t}\n\tif (config.dataApiEnabled && !state.dataApiEnabled) {\n\t\tplan.push({\n\t\t\tkind: \"enable-data-api\",\n\t\t\tprojectId: remote.projectId,\n\t\t\tbranchId: remote.branch.id,\n\t\t\tbranchName: remote.branch.name,\n\t\t\tdatabaseName: state.databaseName,\n\t\t});\n\t}\n}\n\ninterface BranchConfigArgs {\n\tconfig: ResolvedBranchConfig;\n\tremote: RemoteState;\n\toptions: DiffOptions;\n\tplan: PlanStep[];\n\tconflicts: ConflictReport[];\n}\n\nfunction diffBranchConfig(args: BranchConfigArgs): void {\n\tconst { config, remote, options, plan, conflicts } = args;\n\tconst branchName = remote.branch.name;\n\tconst computeSettings = config.postgres?.computeSettings;\n\n\tif (computeSettings) {\n\t\tconst endpoint = remote.endpoint;\n\t\tif (!endpoint) {\n\t\t\tconflicts.push({\n\t\t\t\tkind: \"branch\",\n\t\t\t\tidentifier: branchName,\n\t\t\t\tfield: \"endpoint\",\n\t\t\t\tcurrent: undefined,\n\t\t\t\tdesired: computeSettings,\n\t\t\t\treason: \"Branch has no read-write endpoint; cannot apply compute settings.\",\n\t\t\t});\n\t\t} else {\n\t\t\tconst drift = computeDriftBetween(computeSettings, endpoint);\n\t\t\tif (drift) {\n\t\t\t\tif (options.updateExisting) {\n\t\t\t\t\tplan.push({\n\t\t\t\t\t\tkind: \"update-endpoint\",\n\t\t\t\t\t\tprojectId: remote.projectId,\n\t\t\t\t\t\tbranchName,\n\t\t\t\t\t\tendpointId: endpoint.id,\n\t\t\t\t\t\tsettings: computeSettings,\n\t\t\t\t\t});\n\t\t\t\t} else {\n\t\t\t\t\tconflicts.push({\n\t\t\t\t\t\tkind: \"branch\",\n\t\t\t\t\t\tidentifier: branchName,\n\t\t\t\t\t\tfield: \"computeSettings\",\n\t\t\t\t\t\tcurrent: drift.current,\n\t\t\t\t\t\tdesired: drift.desired,\n\t\t\t\t\t\treason: \"Existing branch has different compute settings. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply.\",\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif (\n\t\tconfig.protected !== undefined &&\n\t\tconfig.protected !== remote.branch.protected\n\t) {\n\t\tif (options.updateExisting) {\n\t\t\tplan.push({\n\t\t\t\tkind: \"update-branch-protected\",\n\t\t\t\tprojectId: remote.projectId,\n\t\t\t\tbranchId: remote.branch.id,\n\t\t\t\tbranchName,\n\t\t\t\tprotected: config.protected,\n\t\t\t});\n\t\t} else {\n\t\t\tconflicts.push({\n\t\t\t\tkind: \"branch\",\n\t\t\t\tidentifier: branchName,\n\t\t\t\tfield: \"protected\",\n\t\t\t\tcurrent: remote.branch.protected,\n\t\t\t\tdesired: config.protected,\n\t\t\t\treason: \"Existing branch has a different `protected` flag. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply.\",\n\t\t\t});\n\t\t}\n\t}\n\n\tif (config.ttlSeconds !== undefined) {\n\t\tconst current = remote.branch.expiresAt\n\t\t\t? Math.max(\n\t\t\t\t\t0,\n\t\t\t\t\tMath.round(\n\t\t\t\t\t\t(Date.parse(remote.branch.expiresAt) - Date.now()) /\n\t\t\t\t\t\t\t1000,\n\t\t\t\t\t),\n\t\t\t\t)\n\t\t\t: undefined;\n\t\tif (\n\t\t\tcurrent === undefined ||\n\t\t\tMath.abs(current - config.ttlSeconds) > 30\n\t\t) {\n\t\t\tconst expiresAt = new Date(\n\t\t\t\tDate.now() + config.ttlSeconds * 1000,\n\t\t\t).toISOString();\n\t\t\tif (options.updateExisting) {\n\t\t\t\tplan.push({\n\t\t\t\t\tkind: \"update-branch-ttl\",\n\t\t\t\t\tprojectId: remote.projectId,\n\t\t\t\t\tbranchId: remote.branch.id,\n\t\t\t\t\tbranchName,\n\t\t\t\t\texpiresAt,\n\t\t\t\t});\n\t\t\t} else {\n\t\t\t\tconflicts.push({\n\t\t\t\t\tkind: \"branch\",\n\t\t\t\t\tidentifier: branchName,\n\t\t\t\t\tfield: \"ttl\",\n\t\t\t\t\tcurrent: remote.branch.expiresAt,\n\t\t\t\t\tdesired: expiresAt,\n\t\t\t\t\treason: \"Existing branch has a different TTL. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply.\",\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n}\n\nfunction computeDriftBetween(\n\tdesired: ComputeSettings,\n\tendpoint: NeonEndpointSnapshot,\n): {\n\tcurrent: Partial<ComputeSettings>;\n\tdesired: Partial<ComputeSettings>;\n} | null {\n\tconst currentDrift: Partial<ComputeSettings> = {};\n\tconst desiredDrift: Partial<ComputeSettings> = {};\n\tlet drift = false;\n\n\tif (\n\t\tdesired.autoscalingLimitMinCu !== undefined &&\n\t\tdesired.autoscalingLimitMinCu !== endpoint.autoscalingLimitMinCu\n\t) {\n\t\tcurrentDrift.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;\n\t\tdesiredDrift.autoscalingLimitMinCu = desired.autoscalingLimitMinCu;\n\t\tdrift = true;\n\t}\n\tif (\n\t\tdesired.autoscalingLimitMaxCu !== undefined &&\n\t\tdesired.autoscalingLimitMaxCu !== endpoint.autoscalingLimitMaxCu\n\t) {\n\t\tcurrentDrift.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;\n\t\tdesiredDrift.autoscalingLimitMaxCu = desired.autoscalingLimitMaxCu;\n\t\tdrift = true;\n\t}\n\tif (\n\t\tdesired.suspendTimeout !== undefined &&\n\t\tdesired.suspendTimeout !== endpoint.suspendTimeout\n\t) {\n\t\tcurrentDrift.suspendTimeout = endpoint.suspendTimeout;\n\t\tdesiredDrift.suspendTimeout = desired.suspendTimeout;\n\t\tdrift = true;\n\t}\n\treturn drift ? { current: currentDrift, desired: desiredDrift } : null;\n}\n"],"mappings":";;;;AAiIA,SAAgB,WACf,QACA,QACA,SACa;CACb,MAAM,YAA8B,CAAC;CACrC,MAAM,OAAmB,CAAC;CAC1B,iBAAiB;EAAE;EAAQ;EAAQ;EAAS;EAAM;CAAU,CAAC;CAC7D,aAAa;EAAE;EAAQ;EAAQ;CAAK,CAAC;CACrC,YAAY;EAAE;EAAQ;EAAQ;CAAK,CAAC;CACpC,OAAO;EAAE;EAAM;CAAU;AAC1B;;;;;;;;;;;AAYA,SAAS,YAAY,MAIZ;CACR,MAAM,EAAE,QAAQ,QAAQ,SAAS;CACjC,MAAM,UAAU,OAAO;CACvB,IAAI,CAAC,SAAS;CAGd,MAAM,QAA4B,OAAO,WAAW;EACnD,SAAS,CAAC;EACV,WAAW,CAAC;EACZ,kBAAkB;CACnB;CAEA,KAAK,MAAM,UAAU,QAAQ,SAAS;EACrC,IAAI,MAAM,QAAQ,MAAM,MAAM,EAAE,SAAS,OAAO,IAAI,GAAG;EACvD,KAAK,KAAK;GACT,MAAM;GACN,WAAW,OAAO;GAClB,UAAU,OAAO,OAAO;GACxB,YAAY,OAAO,OAAO;GAC1B,YAAY,OAAO;GACnB,aAAa,OAAO;EACrB,CAAC;CACF;CAEA,KAAK,MAAM,MAAM,QAAQ,WAAW;EAEnC,IAAI,CADW,MAAM,UAAU,MAAM,MAAM,EAAE,SAAS,GAAG,IAC/C,GACT,KAAK,KAAK;GACT,MAAM;GACN,WAAW,OAAO;GAClB,UAAU,OAAO,OAAO;GACxB,YAAY,OAAO,OAAO;GAC1B;EACD,CAAC;EAEF,KAAK,KAAK;GACT,MAAM;GACN,WAAW,OAAO;GAClB,UAAU,OAAO,OAAO;GACxB,YAAY,OAAO,OAAO;GAC1B;EACD,CAAC;CACF;CAEA,IAAI,QAAQ,oBAAoB,CAAC,MAAM,kBACtC,KAAK,KAAK;EACT,MAAM;EACN,WAAW,OAAO;EAClB,UAAU,OAAO,OAAO;EACxB,YAAY,OAAO,OAAO;CAC3B,CAAC;AAEH;;;;;AAMA,SAAS,aAAa,MAIb;CACR,MAAM,EAAE,QAAQ,QAAQ,SAAS;CACjC,MAAM,QAAQ,OAAO;CACrB,IAAI,OAAO,eAAe,CAAC,MAAM,aAAa;EAC7C,MAAM,OAAiB;GACtB,MAAM;GACN,WAAW,OAAO;GAClB,UAAU,OAAO,OAAO;GACxB,YAAY,OAAO,OAAO;EAC3B;EACA,IAAI,MAAM,cAAc,KAAK,eAAe,MAAM;EAClD,KAAK,KAAK,IAAI;CACf;CACA,IAAI,OAAO,kBAAkB,CAAC,MAAM,gBACnC,KAAK,KAAK;EACT,MAAM;EACN,WAAW,OAAO;EAClB,UAAU,OAAO,OAAO;EACxB,YAAY,OAAO,OAAO;EAC1B,cAAc,MAAM;CACrB,CAAC;AAEH;AAUA,SAAS,iBAAiB,MAA8B;CACvD,MAAM,EAAE,QAAQ,QAAQ,SAAS,MAAM,cAAc;CACrD,MAAM,aAAa,OAAO,OAAO;CACjC,MAAM,kBAAkB,OAAO,UAAU;CAEzC,IAAI,iBAAiB;EACpB,MAAM,WAAW,OAAO;EACxB,IAAI,CAAC,UACJ,UAAU,KAAK;GACd,MAAM;GACN,YAAY;GACZ,OAAO;GACP,SAAS,KAAA;GACT,SAAS;GACT,QAAQ;EACT,CAAC;OACK;GACN,MAAM,QAAQ,oBAAoB,iBAAiB,QAAQ;GAC3D,IAAI,OACH,IAAI,QAAQ,gBACX,KAAK,KAAK;IACT,MAAM;IACN,WAAW,OAAO;IAClB;IACA,YAAY,SAAS;IACrB,UAAU;GACX,CAAC;QAED,UAAU,KAAK;IACd,MAAM;IACN,YAAY;IACZ,OAAO;IACP,SAAS,MAAM;IACf,SAAS,MAAM;IACf,QAAQ;GACT,CAAC;EAGJ;CACD;CAEA,IACC,OAAO,cAAc,KAAA,KACrB,OAAO,cAAc,OAAO,OAAO,WAEnC,IAAI,QAAQ,gBACX,KAAK,KAAK;EACT,MAAM;EACN,WAAW,OAAO;EAClB,UAAU,OAAO,OAAO;EACxB;EACA,WAAW,OAAO;CACnB,CAAC;MAED,UAAU,KAAK;EACd,MAAM;EACN,YAAY;EACZ,OAAO;EACP,SAAS,OAAO,OAAO;EACvB,SAAS,OAAO;EAChB,QAAQ;CACT,CAAC;CAIH,IAAI,OAAO,eAAe,KAAA,GAAW;EACpC,MAAM,UAAU,OAAO,OAAO,YAC3B,KAAK,IACL,GACA,KAAK,OACH,KAAK,MAAM,OAAO,OAAO,SAAS,IAAI,KAAK,IAAI,KAC/C,GACF,CACD,IACC,KAAA;EACH,IACC,YAAY,KAAA,KACZ,KAAK,IAAI,UAAU,OAAO,UAAU,IAAI,IACvC;GACD,MAAM,YAAY,IAAI,KACrB,KAAK,IAAI,IAAI,OAAO,aAAa,GAClC,EAAE,YAAY;GACd,IAAI,QAAQ,gBACX,KAAK,KAAK;IACT,MAAM;IACN,WAAW,OAAO;IAClB,UAAU,OAAO,OAAO;IACxB;IACA;GACD,CAAC;QAED,UAAU,KAAK;IACd,MAAM;IACN,YAAY;IACZ,OAAO;IACP,SAAS,OAAO,OAAO;IACvB,SAAS;IACT,QAAQ;GACT,CAAC;EAEH;CACD;AACD;AAEA,SAAS,oBACR,SACA,UAIQ;CACR,MAAM,eAAyC,CAAC;CAChD,MAAM,eAAyC,CAAC;CAChD,IAAI,QAAQ;CAEZ,IACC,QAAQ,0BAA0B,KAAA,KAClC,QAAQ,0BAA0B,SAAS,uBAC1C;EACD,aAAa,wBAAwB,SAAS;EAC9C,aAAa,wBAAwB,QAAQ;EAC7C,QAAQ;CACT;CACA,IACC,QAAQ,0BAA0B,KAAA,KAClC,QAAQ,0BAA0B,SAAS,uBAC1C;EACD,aAAa,wBAAwB,SAAS;EAC9C,aAAa,wBAAwB,QAAQ;EAC7C,QAAQ;CACT;CACA,IACC,QAAQ,mBAAmB,KAAA,KAC3B,QAAQ,mBAAmB,SAAS,gBACnC;EACD,aAAa,iBAAiB,SAAS;EACvC,aAAa,iBAAiB,QAAQ;EACtC,QAAQ;CACT;CACA,OAAO,QAAQ;EAAE,SAAS;EAAc,SAAS;CAAa,IAAI;AACnE"}

package/dist/lib/duration.d.ts

@@ -0,0 +1,46 @@
+//#region src/lib/duration.d.ts
+/**
+ * Parse a TTL value into whole seconds.
+ *
+ * Accepted formats:
+ * - a positive finite number → interpreted as seconds (must be an integer)
+ * - a positive integer string ("3600") → seconds
+ * - `<number><unit>` where unit is one of `s`, `m`, `h`, `d`, `w` (e.g. `30s`, `5m`, `1h`, `7d`, `2w`)
+ *
+ * Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.
+ */
+declare function parseDuration(input: string | number): {
+  seconds: number;
+} | {
+  error: string;
+};
+/**
+ * Render a TTL in seconds back to the canonical "<n><unit>" form. Used for round-trip
+ * serialization when {@link pullConfig} emits a TTL value (it always falls back to seconds
+ * when no clean unit boundary matches).
+ */
+declare function formatDurationSeconds(totalSeconds: number): string;
+/**
+ * Parse a suspend timeout value into seconds for the Neon API.
+ *
+ * Accepted formats:
+ * - `false` → -1 (never suspend)
+ * - `undefined` → 0 (use platform default)
+ * - duration string → parsed seconds ("5m", "1h", "7d")
+ * - number → validated seconds (must be 60-604800 or -1/0)
+ *
+ * Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.
+ */
+declare function parseSuspendTimeout(input: false | string | number | undefined): {
+  seconds: number;
+} | {
+  error: string;
+};
+/**
+ * Format a suspend timeout value from API seconds back to the user-facing type.
+ * Returns `false` for -1 (never suspend), `undefined` for 0 (default), or a duration string.
+ */
+declare function formatSuspendTimeout(seconds: number): false | string | undefined;
+//#endregion
+export { formatDurationSeconds, formatSuspendTimeout, parseDuration, parseSuspendTimeout };
+//# sourceMappingURL=duration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","names":[],"sources":["../../src/lib/duration.ts"],"mappings":";;AAUA;AAoDA;AA+BA;AA+CA;;;;;;iBAlIgB,aAAA;;;;;;;;;;iBAoDA,qBAAA;;;;;;;;;;;;iBA+BA,mBAAA;;;;;;;;;iBA+CA,oBAAA"}

package/dist/lib/duration.js

@@ -0,0 +1,96 @@
+//#region src/lib/duration.ts
+/**
+* Parse a TTL value into whole seconds.
+*
+* Accepted formats:
+* - a positive finite number → interpreted as seconds (must be an integer)
+* - a positive integer string ("3600") → seconds
+* - `<number><unit>` where unit is one of `s`, `m`, `h`, `d`, `w` (e.g. `30s`, `5m`, `1h`, `7d`, `2w`)
+*
+* Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.
+*/
+function parseDuration(input) {
+	if (typeof input === "number") {
+		if (!Number.isFinite(input)) return { error: `not a finite number: ${input}` };
+		if (!Number.isInteger(input)) return { error: `must be an integer when passed as number: ${input}` };
+		if (input <= 0) return { error: `must be > 0, got ${input}` };
+		return { seconds: input };
+	}
+	const trimmed = input.trim();
+	if (trimmed === "") return { error: "duration string is empty" };
+	const numericMatch = /^(\d+)$/.exec(trimmed);
+	if (numericMatch) {
+		const n = Number(numericMatch[1]);
+		if (n <= 0) return { error: `must be > 0, got "${trimmed}"` };
+		return { seconds: n };
+	}
+	const unitMatch = /^(\d+)([smhdw])$/i.exec(trimmed);
+	if (!unitMatch) return { error: `invalid duration "${input}"; expected a number followed by one of: s, m, h, d, w (e.g. "30s", "1h", "7d")` };
+	const value = Number(unitMatch[1]);
+	const unit = unitMatch[2].toLowerCase();
+	if (value <= 0) return { error: `must be > 0, got "${trimmed}"` };
+	return { seconds: value * UNIT_SECONDS[unit] };
+}
+const UNIT_SECONDS = {
+	s: 1,
+	m: 60,
+	h: 3600,
+	d: 1440 * 60,
+	w: 10080 * 60
+};
+/**
+* Render a TTL in seconds back to the canonical "<n><unit>" form. Used for round-trip
+* serialization when {@link pullConfig} emits a TTL value (it always falls back to seconds
+* when no clean unit boundary matches).
+*/
+function formatDurationSeconds(totalSeconds) {
+	if (!Number.isFinite(totalSeconds) || totalSeconds <= 0) throw new RangeError(`formatDurationSeconds expected a positive finite number, got ${totalSeconds}`);
+	const candidates = [
+		["w", UNIT_SECONDS.w],
+		["d", UNIT_SECONDS.d],
+		["h", UNIT_SECONDS.h],
+		["m", UNIT_SECONDS.m]
+	];
+	for (const [unit, perUnit] of candidates) if (totalSeconds % perUnit === 0) return `${totalSeconds / perUnit}${unit}`;
+	return `${totalSeconds}s`;
+}
+/**
+* Parse a suspend timeout value into seconds for the Neon API.
+*
+* Accepted formats:
+* - `false` → -1 (never suspend)
+* - `undefined` → 0 (use platform default)
+* - duration string → parsed seconds ("5m", "1h", "7d")
+* - number → validated seconds (must be 60-604800 or -1/0)
+*
+* Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.
+*/
+function parseSuspendTimeout(input) {
+	if (input === false) return { seconds: -1 };
+	if (input === void 0) return { seconds: 0 };
+	if (typeof input === "number") {
+		if (!Number.isFinite(input)) return { error: `not a finite number: ${input}` };
+		if (!Number.isInteger(input)) return { error: `must be an integer: ${input}` };
+		if (input === -1 || input === 0) return { seconds: input };
+		if (input < 60 || input > 604800) return { error: `suspend timeout must be between 60 and 604800 seconds (1 minute to 1 week), got ${input}` };
+		return { seconds: input };
+	}
+	const result = parseDuration(input);
+	if ("error" in result) return result;
+	const { seconds } = result;
+	if (seconds < 60 || seconds > 604800) return { error: `suspend timeout must be between 60 and 604800 seconds (1 minute to 1 week), "${input}" = ${seconds}s` };
+	return { seconds };
+}
+/**
+* Format a suspend timeout value from API seconds back to the user-facing type.
+* Returns `false` for -1 (never suspend), `undefined` for 0 (default), or a duration string.
+*/
+function formatSuspendTimeout(seconds) {
+	if (seconds === -1) return false;
+	if (seconds === 0) return void 0;
+	return formatDurationSeconds(seconds);
+}
+//#endregion
+export { formatDurationSeconds, formatSuspendTimeout, parseDuration, parseSuspendTimeout };
+
+//# sourceMappingURL=duration.js.map

package/dist/lib/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","names":[],"sources":["../../src/lib/duration.ts"],"sourcesContent":["/**\n * Parse a TTL value into whole seconds.\n *\n * Accepted formats:\n * - a positive finite number → interpreted as seconds (must be an integer)\n * - a positive integer string (\"3600\") → seconds\n * - `<number><unit>` where unit is one of `s`, `m`, `h`, `d`, `w` (e.g. `30s`, `5m`, `1h`, `7d`, `2w`)\n *\n * Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.\n */\nexport function parseDuration(\n\tinput: string | number,\n): { seconds: number } | { error: string } {\n\tif (typeof input === \"number\") {\n\t\tif (!Number.isFinite(input))\n\t\t\treturn { error: `not a finite number: ${input}` };\n\t\tif (!Number.isInteger(input))\n\t\t\treturn {\n\t\t\t\terror: `must be an integer when passed as number: ${input}`,\n\t\t\t};\n\t\tif (input <= 0) return { error: `must be > 0, got ${input}` };\n\t\treturn { seconds: input };\n\t}\n\n\tconst trimmed = input.trim();\n\tif (trimmed === \"\") return { error: \"duration string is empty\" };\n\n\tconst numericMatch = /^(\\d+)$/.exec(trimmed);\n\tif (numericMatch) {\n\t\tconst n = Number(numericMatch[1]);\n\t\tif (n <= 0) return { error: `must be > 0, got \"${trimmed}\"` };\n\t\treturn { seconds: n };\n\t}\n\n\tconst unitMatch = /^(\\d+)([smhdw])$/i.exec(trimmed);\n\tif (!unitMatch) {\n\t\treturn {\n\t\t\terror: `invalid duration \"${input}\"; expected a number followed by one of: s, m, h, d, w (e.g. \"30s\", \"1h\", \"7d\")`,\n\t\t};\n\t}\n\n\tconst value = Number(unitMatch[1]);\n\tconst unit = unitMatch[2].toLowerCase() as \"s\" | \"m\" | \"h\" | \"d\" | \"w\";\n\tif (value <= 0) return { error: `must be > 0, got \"${trimmed}\"` };\n\n\tconst seconds = value * UNIT_SECONDS[unit];\n\treturn { seconds };\n}\n\nconst UNIT_SECONDS = {\n\ts: 1,\n\tm: 60,\n\th: 60 * 60,\n\td: 24 * 60 * 60,\n\tw: 7 * 24 * 60 * 60,\n} as const;\n\n/**\n * Render a TTL in seconds back to the canonical \"<n><unit>\" form. Used for round-trip\n * serialization when {@link pullConfig} emits a TTL value (it always falls back to seconds\n * when no clean unit boundary matches).\n */\nexport function formatDurationSeconds(totalSeconds: number): string {\n\tif (!Number.isFinite(totalSeconds) || totalSeconds <= 0) {\n\t\tthrow new RangeError(\n\t\t\t`formatDurationSeconds expected a positive finite number, got ${totalSeconds}`,\n\t\t);\n\t}\n\tconst candidates = [\n\t\t[\"w\", UNIT_SECONDS.w],\n\t\t[\"d\", UNIT_SECONDS.d],\n\t\t[\"h\", UNIT_SECONDS.h],\n\t\t[\"m\", UNIT_SECONDS.m],\n\t] as const;\n\tfor (const [unit, perUnit] of candidates) {\n\t\tif (totalSeconds % perUnit === 0) {\n\t\t\treturn `${totalSeconds / perUnit}${unit}`;\n\t\t}\n\t}\n\treturn `${totalSeconds}s`;\n}\n\n/**\n * Parse a suspend timeout value into seconds for the Neon API.\n *\n * Accepted formats:\n * - `false` → -1 (never suspend)\n * - `undefined` → 0 (use platform default)\n * - duration string → parsed seconds (\"5m\", \"1h\", \"7d\")\n * - number → validated seconds (must be 60-604800 or -1/0)\n *\n * Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.\n */\nexport function parseSuspendTimeout(\n\tinput: false | string | number | undefined,\n): { seconds: number } | { error: string } {\n\t// false means \"never suspend\"\n\tif (input === false) return { seconds: -1 };\n\n\t// undefined means \"use platform default\"\n\tif (input === undefined) return { seconds: 0 };\n\n\t// If it's a number, validate the range\n\tif (typeof input === \"number\") {\n\t\tif (!Number.isFinite(input))\n\t\t\treturn { error: `not a finite number: ${input}` };\n\t\tif (!Number.isInteger(input))\n\t\t\treturn { error: `must be an integer: ${input}` };\n\n\t\t// Allow special values: -1 (never), 0 (default)\n\t\tif (input === -1 || input === 0) return { seconds: input };\n\n\t\t// Validate range for custom timeout: 60s (1 min) to 604800s (1 week)\n\t\tif (input < 60 || input > 604_800) {\n\t\t\treturn {\n\t\t\t\terror: `suspend timeout must be between 60 and 604800 seconds (1 minute to 1 week), got ${input}`,\n\t\t\t};\n\t\t}\n\t\treturn { seconds: input };\n\t}\n\n\t// Parse duration string\n\tconst result = parseDuration(input);\n\tif (\"error\" in result) return result;\n\n\t// Validate the parsed duration is in the valid range\n\tconst { seconds } = result;\n\tif (seconds < 60 || seconds > 604_800) {\n\t\treturn {\n\t\t\terror: `suspend timeout must be between 60 and 604800 seconds (1 minute to 1 week), \"${input}\" = ${seconds}s`,\n\t\t};\n\t}\n\n\treturn { seconds };\n}\n\n/**\n * Format a suspend timeout value from API seconds back to the user-facing type.\n * Returns `false` for -1 (never suspend), `undefined` for 0 (default), or a duration string.\n */\nexport function formatSuspendTimeout(\n\tseconds: number,\n): false | string | undefined {\n\tif (seconds === -1) return false; // never suspend\n\tif (seconds === 0) return undefined; // platform default\n\treturn formatDurationSeconds(seconds);\n}\n"],"mappings":";;;;;;;;;;;AAUA,SAAgB,cACf,OAC0C;CAC1C,IAAI,OAAO,UAAU,UAAU;EAC9B,IAAI,CAAC,OAAO,SAAS,KAAK,GACzB,OAAO,EAAE,OAAO,wBAAwB,QAAQ;EACjD,IAAI,CAAC,OAAO,UAAU,KAAK,GAC1B,OAAO,EACN,OAAO,6CAA6C,QACrD;EACD,IAAI,SAAS,GAAG,OAAO,EAAE,OAAO,oBAAoB,QAAQ;EAC5D,OAAO,EAAE,SAAS,MAAM;CACzB;CAEA,MAAM,UAAU,MAAM,KAAK;CAC3B,IAAI,YAAY,IAAI,OAAO,EAAE,OAAO,2BAA2B;CAE/D,MAAM,eAAe,UAAU,KAAK,OAAO;CAC3C,IAAI,cAAc;EACjB,MAAM,IAAI,OAAO,aAAa,EAAE;EAChC,IAAI,KAAK,GAAG,OAAO,EAAE,OAAO,qBAAqB,QAAQ,GAAG;EAC5D,OAAO,EAAE,SAAS,EAAE;CACrB;CAEA,MAAM,YAAY,oBAAoB,KAAK,OAAO;CAClD,IAAI,CAAC,WACJ,OAAO,EACN,OAAO,qBAAqB,MAAM,iFACnC;CAGD,MAAM,QAAQ,OAAO,UAAU,EAAE;CACjC,MAAM,OAAO,UAAU,GAAG,YAAY;CACtC,IAAI,SAAS,GAAG,OAAO,EAAE,OAAO,qBAAqB,QAAQ,GAAG;CAGhE,OAAO,EAAE,SADO,QAAQ,aAAa,MACpB;AAClB;AAEA,MAAM,eAAe;CACpB,GAAG;CACH,GAAG;CACH,GAAG;CACH,GAAG,OAAU;CACb,GAAG,QAAc;AAClB;;;;;;AAOA,SAAgB,sBAAsB,cAA8B;CACnE,IAAI,CAAC,OAAO,SAAS,YAAY,KAAK,gBAAgB,GACrD,MAAM,IAAI,WACT,gEAAgE,cACjE;CAED,MAAM,aAAa;EAClB,CAAC,KAAK,aAAa,CAAC;EACpB,CAAC,KAAK,aAAa,CAAC;EACpB,CAAC,KAAK,aAAa,CAAC;EACpB,CAAC,KAAK,aAAa,CAAC;CACrB;CACA,KAAK,MAAM,CAAC,MAAM,YAAY,YAC7B,IAAI,eAAe,YAAY,GAC9B,OAAO,GAAG,eAAe,UAAU;CAGrC,OAAO,GAAG,aAAa;AACxB;;;;;;;;;;;;AAaA,SAAgB,oBACf,OAC0C;CAE1C,IAAI,UAAU,OAAO,OAAO,EAAE,SAAS,GAAG;CAG1C,IAAI,UAAU,KAAA,GAAW,OAAO,EAAE,SAAS,EAAE;CAG7C,IAAI,OAAO,UAAU,UAAU;EAC9B,IAAI,CAAC,OAAO,SAAS,KAAK,GACzB,OAAO,EAAE,OAAO,wBAAwB,QAAQ;EACjD,IAAI,CAAC,OAAO,UAAU,KAAK,GAC1B,OAAO,EAAE,OAAO,uBAAuB,QAAQ;EAGhD,IAAI,UAAU,MAAM,UAAU,GAAG,OAAO,EAAE,SAAS,MAAM;EAGzD,IAAI,QAAQ,MAAM,QAAQ,QACzB,OAAO,EACN,OAAO,mFAAmF,QAC3F;EAED,OAAO,EAAE,SAAS,MAAM;CACzB;CAGA,MAAM,SAAS,cAAc,KAAK;CAClC,IAAI,WAAW,QAAQ,OAAO;CAG9B,MAAM,EAAE,YAAY;CACpB,IAAI,UAAU,MAAM,UAAU,QAC7B,OAAO,EACN,OAAO,gFAAgF,MAAM,MAAM,QAAQ,GAC5G;CAGD,OAAO,EAAE,QAAQ;AAClB;;;;;AAMA,SAAgB,qBACf,SAC6B;CAC7B,IAAI,YAAY,IAAI,OAAO;CAC3B,IAAI,YAAY,GAAG,OAAO,KAAA;CAC1B,OAAO,sBAAsB,OAAO;AACrC"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,129 @@
+import { ConflictReport } from "./types.js";
+
+//#region src/lib/errors.d.ts
+
+/**
+ * Every code a {@link PlatformError} can carry. Stable identifiers — consumers can rely on
+ * these for `instanceof PlatformError && err.code === ErrorCode.…` style checks instead of
+ * matching on free-text messages.
+ *
+ * Grouped by source:
+ * - `PLATFORM_INVALID_CONFIG` — `defineConfig` / `configSchema` rejected the input.
+ * - `PLATFORM_MISSING_CONTEXT` — no project / branch context could be resolved.
+ * - `PLATFORM_PUSH_CONFLICT` — local config conflicts with remote and the caller did not
+ *   opt in to apply.
+ * - `PLATFORM_CONFIG_LOAD_FAILED` — `neon.ts` could not be found or evaluated.
+ * - `PLATFORM_MISSING_API_KEY` — no `NEON_API_KEY` and no explicit `apiKey` was provided.
+ * - `PLATFORM_MISSING_PARENT_BRANCH` — push tried to create a child of a non-existent
+ *   branch.
+ * - `PLATFORM_UNAUTHORIZED` / `PLATFORM_FORBIDDEN` / `PLATFORM_NOT_FOUND` /
+ *   `PLATFORM_CONFLICT` / `PLATFORM_RATE_LIMITED` / `PLATFORM_LOCKED` /
+ *   `PLATFORM_SERVER_ERROR` — wrappings of Neon HTTP failures.
+ * - `PLATFORM_NETWORK_ERROR` — transport-level failure (no HTTP response at all).
+ * - `PLATFORM_INTERNAL_ERROR` — invariant violations. Should never happen in production;
+ *   if you see one, please open an issue.
+ */
+declare const ErrorCode: {
+  readonly InvalidConfig: "PLATFORM_INVALID_CONFIG";
+  readonly EnvNotInjected: "PLATFORM_ENV_NOT_INJECTED";
+  readonly MissingContext: "PLATFORM_MISSING_CONTEXT";
+  readonly PushConflict: "PLATFORM_PUSH_CONFLICT";
+  readonly PushAborted: "PLATFORM_PUSH_ABORTED";
+  readonly ConfigLoadFailed: "PLATFORM_CONFIG_LOAD_FAILED";
+  readonly MissingApiKey: "PLATFORM_MISSING_API_KEY";
+  readonly AmbiguousBranchAuth: "PLATFORM_AMBIGUOUS_BRANCH_AUTH";
+  readonly BranchNotFound: "PLATFORM_BRANCH_NOT_FOUND";
+  readonly MissingParentBranch: "PLATFORM_MISSING_PARENT_BRANCH";
+  readonly Unauthorized: "PLATFORM_UNAUTHORIZED";
+  readonly Forbidden: "PLATFORM_FORBIDDEN";
+  readonly NotFound: "PLATFORM_NOT_FOUND";
+  readonly Conflict: "PLATFORM_CONFLICT";
+  readonly RateLimited: "PLATFORM_RATE_LIMITED";
+  readonly Locked: "PLATFORM_LOCKED";
+  readonly ServerError: "PLATFORM_SERVER_ERROR";
+  readonly NetworkError: "PLATFORM_NETWORK_ERROR";
+  readonly InternalError: "PLATFORM_INTERNAL_ERROR";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * Base class for all errors thrown by `@neondatabase/config`. Always extend this so callers
+ * can catch every package-thrown error with a single `instanceof` check.
+ *
+ * Optional `details` carries structured context that the CLI prints under `--debug` and
+ * that programmatic consumers can read (e.g. `details.status` for HTTP wrappings,
+ * `details.requestId` for Neon API failures).
+ */
+declare class PlatformError extends Error {
+  readonly name: string;
+  readonly code: string;
+  readonly details: Readonly<Record<string, unknown>>;
+  constructor(code: string, message: string, options?: {
+    cause?: unknown;
+    details?: Record<string, unknown>;
+  });
+}
+/**
+ * Append a "report-a-bug" footer to an error message. Used only on truly unreachable
+ * internal errors — never on user-facing validation / configuration errors where the user
+ * is supposed to fix something on their end.
+ */
+declare function bugReportFooter(): string;
+/**
+ * Thrown by {@link defineConfig} when the user-provided configuration object is invalid.
+ *
+ * The class collects every validation failure rather than throwing on the first one so that
+ * users get a complete picture of what is wrong with their `neon.ts`.
+ */
+declare class ConfigValidationError extends PlatformError {
+  readonly name = "ConfigValidationError";
+  readonly issues: readonly string[];
+  constructor(issues: readonly string[]);
+}
+/**
+ * Thrown when the package cannot resolve which Neon project to operate on.
+ *
+ * Per the package's read-only-filesystem contract, we never create a `.neon` context file;
+ * callers must either pass `projectId`/`orgId` explicitly or rely on an existing context file
+ * (`.neon/project.json` or neonctl's `.neon`).
+ */
+declare class MissingContextError extends PlatformError {
+  readonly name = "MissingContextError";
+  constructor(message: string);
+}
+/**
+ * Thrown by {@link pushConfig} when it detects differences between the local config and
+ * the remote project that the caller hasn't opted in to apply.
+ *
+ * The message lists every conflict with both the current and desired value plus a
+ * per-conflict hint. Mutable branch drift is applied by passing `updateExisting: true`.
+ */
+declare class PushConflictError extends PlatformError {
+  readonly name = "PushConflictError";
+  readonly conflicts: readonly ConflictReport[];
+  constructor(conflicts: readonly ConflictReport[]);
+}
+/**
+ * Thrown by {@link pushConfig} when the caller-supplied `confirm` callback declines a
+ * push that requires confirmation (protected branch and/or mutable drift overriding
+ * existing remote settings).
+ *
+ * The CLI maps this to a non-zero exit so users see "aborted" rather than a stack trace.
+ */
+declare class PushAbortedError extends PlatformError {
+  readonly name = "PushAbortedError";
+  readonly branchName: string;
+  readonly reasons: readonly ("protected-branch" | "override-updates")[];
+  constructor(branchName: string, reasons: readonly ("protected-branch" | "override-updates")[]);
+}
+/**
+ * Thrown when the SDK fails to find or load a `neon.ts` config file.
+ */
+declare class ConfigLoadError extends PlatformError {
+  readonly name = "ConfigLoadError";
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PlatformError, PushAbortedError, PushConflictError, bugReportFooter };
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../../src/lib/errors.ts"],"mappings":";;;;;;AAuBA;AAqBA;;;;AAAiE;AAYjE;;;;;;AAAwC;AAqBxC;AAUA;AAoBA;AAeA;;;AAIiC,cAvGpB,SAuGoB,EAAA;WAJM,aAAA,EAAA,yBAAA;EAAa,SAAA,cAAA,EAAA,2BAAA;EAqDvC,SAAA,cAAiB,EAAA,0BAAqB;EA8BtC,SAAA,YAAgB,EAAA,wBAAqB;;;;;;;;;;;;;;;;;KAjKtC,SAAA,WAAoB,wBAAwB;;;;;;;;;cAY3C,aAAA,SAAsB,KAAA;;;oBAGhB,SAAS;;;cAKa;;;;;;;;iBAazB,eAAA,CAAA;;;;;;;cAUH,qBAAA,SAA8B,aAAa;;;;;;;;;;;;cAoB3C,mBAAA,SAA4B,aAAa;;;;;;;;;;;cAezC,iBAAA,SAA0B,aAAA;;+BAET;kCAEG;;;;;;;;;cAiDpB,gBAAA,SAAyB,aAAa;;;;;;;;;cA8BtC,eAAA,SAAwB,aAAa"}