@neon/config-runtime 0.0.0 → 0.8.1

package/dist/lib/pull-config.d.ts

@@ -0,0 +1,81 @@
+import { BucketAccessLevel, Config, NeonApi, NeonBranchSnapshot, NeonBucketSnapshot, NeonCredentialMeta, NeonEndpointSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot } from "@neon/config";
+
+//#region src/lib/pull-config.d.ts
+interface PullConfigOptions {
+  /** Neon project id (`<project>`). Required — the API addresses branches by project. */
+  projectId: string;
+  /** Neon branch id (`br-…`). Required. Resolve names to ids before calling. */
+  branchId: string;
+  /** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */
+  apiKey?: string;
+  /** Neon API base URL. Falls back to `NEON_API_HOST`, then production. */
+  apiHost?: string;
+  /** Inject a custom NeonApi adapter (primarily for tests). */
+  api?: NeonApi;
+}
+/**
+ * Live Preview-feature state read back from a branch. Surfaced alongside `config` rather
+ * than inside it because functions cannot round-trip: the remote only knows the deployed
+ * bundle, not the local `source` path a {@link FunctionConfig} requires, so a pulled
+ * function is reported as `{ slug, name }` (no `source`).
+ */
+interface PulledPreview {
+  buckets: Array<{
+    name: string;
+    access: BucketAccessLevel;
+  }>;
+  functions: Array<{
+    slug: string;
+    name: string;
+  }>;
+  /**
+   * Secret-free metadata for the credentials issued on the branch (Preview). Surfaced so
+   * `config status` can show issued credentials (id, scopes, last used) without ever
+   * exposing the one-time `api_token` / `s3_secret_access_key`. Empty when none / the
+   * credentials endpoint is unavailable for the project.
+   */
+  credentials: NeonCredentialMeta[];
+}
+interface PulledBranchConfig {
+  project: {
+    id: string;
+    name: string;
+    region: string;
+    pgVersion: number;
+    orgId?: string;
+  };
+  branch: {
+    id: string;
+    name: string;
+    parent?: string;
+    isDefault: boolean;
+    protected: boolean;
+    expiresAt?: string;
+  };
+  /**
+   * The branch's live state expressed as a {@link Config}: static `auth` / `dataApi`
+   * toggles plus a `branch` closure carrying the branch's lifecycle/compute tuning.
+   * Preview functions/buckets are reported separately in {@link PulledBranchConfig.preview}
+   * because functions cannot round-trip (the remote has no `source` path).
+   */
+  config: Config;
+  /**
+   * Live Preview-feature state, when the branch has any buckets/functions or issued
+   * credentials. Omitted entirely when there is nothing to report. The AI Gateway is not
+   * included: it is always available (credential-gated), not per-branch state.
+   */
+  preview?: PulledPreview;
+}
+declare function pullConfig(options: PullConfigOptions): Promise<PulledBranchConfig>;
+declare function buildPulledBranchConfig(project: NeonProjectSnapshot, branch: NeonBranchSnapshot, branches: NeonBranchSnapshot[], endpoint: NeonEndpointSnapshot | undefined, previewState?: {
+  buckets: NeonBucketSnapshot[];
+  functions: NeonFunctionSnapshot[];
+  credentials?: NeonCredentialMeta[];
+  /** Whether a Neon Auth integration is enabled on the branch. */
+  authEnabled?: boolean;
+  /** Whether a Neon Data API integration is enabled on the branch. */
+  dataApiEnabled?: boolean;
+}): PulledBranchConfig;
+//#endregion
+export { PullConfigOptions, PulledBranchConfig, PulledPreview, buildPulledBranchConfig, pullConfig };
+//# sourceMappingURL=pull-config.d.ts.map

package/dist/lib/pull-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-config.d.ts","names":[],"sources":["../../src/lib/pull-config.ts"],"mappings":";;;UAkBiB,iBAAA;;EAAA,SAAA,EAAA,MAAA;EAmBA;EAAa,QAAA,EAAA,MAAA;;QACpB,CAAA,EAAA,MAAA;;SAQI,CAAA,EAAA,MAAA;EAAkB;EAGf,GAAA,CAAA,EArBV,OAqBU;;;;AA4BO;AAGxB;;;AAEW,UA7CM,aAAA,CA6CN;SAAR,EA5CO,KA4CP,CAAA;IAAO,IAAA,EAAA,MAAA;IA4FM,MAAA,EAxIwB,iBAwID;EAAA,CAAA,CAAA;WAC7B,EAxIE,KAwIF,CAAA;IACD,IAAA,EAAA,MAAA;IACE,IAAA,EAAA,MAAA;;;;;;AAWU;;eA9IP;;UAGG,kBAAA;;;;;;;;;;;;;;;;;;;;;;UAsBR;;;;;;YAME;;iBAGW,UAAA,UACZ,oBACP,QAAQ;iBA4FK,uBAAA,UACN,6BACD,8BACE,gCACA;WAEA;aACE;gBACG;;;;;IAMb"}

package/dist/lib/pull-config.js

@@ -0,0 +1,132 @@
+import { ErrorCode, PlatformError, createNeonApiFromOptions } from "@neon/config";
+//#region src/lib/pull-config.ts
+async function pullConfig(options) {
+	const api = options.api ?? createApiFromOptions(options);
+	const projectId = options.projectId;
+	const project = await api.getProject(projectId);
+	const [branches, endpoints] = await Promise.all([api.listBranches(projectId), api.listEndpoints(projectId)]);
+	const branch = resolveBranch(options.branchId, branches);
+	const endpoint = endpoints.find((ep) => ep.type === "read_write" && ep.branchId === branch.id);
+	const probeDatabase = pickProbeDatabase(await api.listBranchDatabases(projectId, branch.id));
+	const [buckets, functions, credentials, auth, dataApi] = await Promise.all([
+		degradeUnavailable(() => api.listBranchBuckets(projectId, branch.id), []),
+		degradeUnavailable(() => api.listBranchFunctions(projectId, branch.id), []),
+		degradeUnavailable(() => api.listCredentials(projectId, branch.id), []),
+		api.getNeonAuth(projectId, branch.id),
+		probeDatabase ? api.getNeonDataApi(projectId, branch.id, probeDatabase) : Promise.resolve(null)
+	]);
+	return buildPulledBranchConfig(project, branch, branches, endpoint, {
+		buckets,
+		functions,
+		credentials,
+		authEnabled: auth !== null,
+		dataApiEnabled: dataApi !== null
+	});
+}
+/**
+* Pick the database to probe for a Data API integration. Data API is enabled per
+* branch + database; for read-back we only need to know whether *any* database has it
+* on, so prefer the conventional default (`neondb`) and otherwise fall back to the first
+* database. Returns `undefined` when the branch has no databases.
+*/
+function pickProbeDatabase(databases) {
+	if (databases.length === 0) return void 0;
+	const byName = databases.find((d) => d.name === "neondb");
+	if (byName) return byName.name;
+	return databases[0].name;
+}
+/**
+* Run a Preview-feature read, returning `fallback` if the feature is unavailable for the
+* project/region (a {@link ErrorCode.FeatureUnavailable} from the adapter). Other errors
+* propagate. Used by `pullConfig` so a branch without a Preview feature still mirrors
+* cleanly for env resolution / `inspect`, rather than aborting on an unrelated capability.
+*/
+async function degradeUnavailable(read, fallback) {
+	try {
+		return await read();
+	} catch (err) {
+		if (err instanceof PlatformError && err.code === ErrorCode.FeatureUnavailable) return fallback;
+		throw err;
+	}
+}
+function createApiFromOptions(options) {
+	return createNeonApiFromOptions("pullConfig", {
+		...options.apiKey ? { apiKey: options.apiKey } : {},
+		...options.apiHost ? { apiHost: options.apiHost } : {}
+	});
+}
+function buildPulledBranchConfig(project, branch, branches, endpoint, previewState) {
+	const parent = branch.parentId ? branches.find((b) => b.id === branch.parentId) : void 0;
+	const tuning = {};
+	if (parent) tuning.parent = parent.name;
+	if (branch.protected) tuning.protected = true;
+	if (endpoint) {
+		const compute = endpointToComputeSettings(endpoint, project);
+		if (compute) tuning.postgres = { computeSettings: compute };
+	}
+	const config = {
+		...previewState?.authEnabled ? { auth: true } : {},
+		...previewState?.dataApiEnabled ? { dataApi: true } : {},
+		...Object.keys(tuning).length > 0 ? { branch: () => tuning } : {}
+	};
+	const result = {
+		project: {
+			id: project.id,
+			name: project.name,
+			region: project.regionId,
+			pgVersion: project.pgVersion,
+			...project.orgId ? { orgId: project.orgId } : {}
+		},
+		branch: {
+			id: branch.id,
+			name: branch.name,
+			...parent ? { parent: parent.name } : {},
+			isDefault: branch.isDefault,
+			protected: branch.protected,
+			...branch.expiresAt ? { expiresAt: branch.expiresAt } : {}
+		},
+		config
+	};
+	const preview = previewState ? buildPulledPreview(previewState) : void 0;
+	if (preview) result.preview = preview;
+	return result;
+}
+/**
+* Reverse-engineer the {@link PulledPreview} from remote snapshots. Returns `undefined` when
+* the branch has no Preview features so the field can be omitted entirely.
+*/
+function buildPulledPreview(state) {
+	const credentials = state.credentials ?? [];
+	if (state.buckets.length === 0 && state.functions.length === 0 && credentials.length === 0) return;
+	return {
+		buckets: state.buckets.map((b) => ({
+			name: b.name,
+			access: b.accessLevel
+		})),
+		functions: state.functions.map((f) => ({
+			slug: f.slug,
+			name: f.name
+		})),
+		credentials
+	};
+}
+function resolveBranch(branchId, branches) {
+	const match = branches.find((b) => b.id === branchId);
+	if (match) return match;
+	throw new PlatformError(ErrorCode.BranchNotFound, [`pullConfig: branch id ${JSON.stringify(branchId)} not found on project.`, `Available branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ") || "(none)"}.`].join(" "), { details: {
+		branchId,
+		available: branches.map((b) => b.id)
+	} });
+}
+function endpointToComputeSettings(endpoint, project) {
+	const defaults = project.defaultEndpointSettings;
+	const out = {};
+	if (endpoint.autoscalingLimitMinCu !== void 0 && endpoint.autoscalingLimitMinCu !== defaults?.autoscalingLimitMinCu) out.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;
+	if (endpoint.autoscalingLimitMaxCu !== void 0 && endpoint.autoscalingLimitMaxCu !== defaults?.autoscalingLimitMaxCu) out.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;
+	if (endpoint.suspendTimeout !== void 0 && endpoint.suspendTimeout !== defaults?.suspendTimeout) out.suspendTimeout = endpoint.suspendTimeout;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+//#endregion
+export { buildPulledBranchConfig, pullConfig };
+
+//# sourceMappingURL=pull-config.js.map

package/dist/lib/pull-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-config.js","names":[],"sources":["../../src/lib/pull-config.ts"],"sourcesContent":["import {\n\ttype BranchTuning,\n\ttype BucketAccessLevel,\n\ttype ComputeSettings,\n\ttype Config,\n\tcreateNeonApiFromOptions,\n\tErrorCode,\n\ttype NeonApi,\n\ttype NeonBranchSnapshot,\n\ttype NeonBucketSnapshot,\n\ttype NeonCredentialMeta,\n\ttype NeonDatabaseSnapshot,\n\ttype NeonEndpointSnapshot,\n\ttype NeonFunctionSnapshot,\n\ttype NeonProjectSnapshot,\n\tPlatformError,\n} from \"@neon/config\";\n\nexport interface PullConfigOptions {\n\t/** Neon project id (`<project>`). Required — the API addresses branches by project. */\n\tprojectId: string;\n\t/** Neon branch id (`br-…`). Required. Resolve names to ids before calling. */\n\tbranchId: string;\n\t/** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */\n\tapiKey?: string;\n\t/** Neon API base URL. Falls back to `NEON_API_HOST`, then production. */\n\tapiHost?: string;\n\t/** Inject a custom NeonApi adapter (primarily for tests). */\n\tapi?: NeonApi;\n}\n\n/**\n * Live Preview-feature state read back from a branch. Surfaced alongside `config` rather\n * than inside it because functions cannot round-trip: the remote only knows the deployed\n * bundle, not the local `source` path a {@link FunctionConfig} requires, so a pulled\n * function is reported as `{ slug, name }` (no `source`).\n */\nexport interface PulledPreview {\n\tbuckets: Array<{ name: string; access: BucketAccessLevel }>;\n\tfunctions: Array<{ slug: string; name: string }>;\n\t/**\n\t * Secret-free metadata for the credentials issued on the branch (Preview). Surfaced so\n\t * `config status` can show issued credentials (id, scopes, last used) without ever\n\t * exposing the one-time `api_token` / `s3_secret_access_key`. Empty when none / the\n\t * credentials endpoint is unavailable for the project.\n\t */\n\tcredentials: NeonCredentialMeta[];\n}\n\nexport interface PulledBranchConfig {\n\tproject: {\n\t\tid: string;\n\t\tname: string;\n\t\tregion: string;\n\t\tpgVersion: number;\n\t\torgId?: string;\n\t};\n\tbranch: {\n\t\tid: string;\n\t\tname: string;\n\t\tparent?: string;\n\t\tisDefault: boolean;\n\t\tprotected: boolean;\n\t\texpiresAt?: string;\n\t};\n\t/**\n\t * The branch's live state expressed as a {@link Config}: static `auth` / `dataApi`\n\t * toggles plus a `branch` closure carrying the branch's lifecycle/compute tuning.\n\t * Preview functions/buckets are reported separately in {@link PulledBranchConfig.preview}\n\t * because functions cannot round-trip (the remote has no `source` path).\n\t */\n\tconfig: Config;\n\t/**\n\t * Live Preview-feature state, when the branch has any buckets/functions or issued\n\t * credentials. Omitted entirely when there is nothing to report. The AI Gateway is not\n\t * included: it is always available (credential-gated), not per-branch state.\n\t */\n\tpreview?: PulledPreview;\n}\n\nexport async function pullConfig(\n\toptions: PullConfigOptions,\n): Promise<PulledBranchConfig> {\n\tconst api = options.api ?? createApiFromOptions(options);\n\tconst projectId = options.projectId;\n\tconst project = await api.getProject(projectId);\n\tconst [branches, endpoints] = await Promise.all([\n\t\tapi.listBranches(projectId),\n\t\tapi.listEndpoints(projectId),\n\t]);\n\tconst branch = resolveBranch(options.branchId, branches);\n\tconst endpoint = endpoints.find(\n\t\t(ep) => ep.type === \"read_write\" && ep.branchId === branch.id,\n\t);\n\n\t// Data API is enabled per branch + database, so resolve a database to probe.\n\tconst databases = await api.listBranchDatabases(projectId, branch.id);\n\tconst probeDatabase = pickProbeDatabase(databases);\n\n\t// Preview reads degrade to \"none / disabled\" when the feature isn't available for the\n\t// project/region. `pullConfig` mirrors the branch for env resolution (`neon dev`,\n\t// `neon env pull`) and `inspect` — an unavailable Preview feature should not break those\n\t// (env comes from auth/dataApi/postgres). `pushConfig` is the place that fails on an\n\t// unavailable feature, and only when the policy declares it.\n\tconst [buckets, functions, credentials, auth, dataApi] = await Promise.all([\n\t\tdegradeUnavailable(\n\t\t\t() => api.listBranchBuckets(projectId, branch.id),\n\t\t\t[],\n\t\t),\n\t\tdegradeUnavailable(\n\t\t\t() => api.listBranchFunctions(projectId, branch.id),\n\t\t\t[],\n\t\t),\n\t\tdegradeUnavailable(() => api.listCredentials(projectId, branch.id), []),\n\t\tapi.getNeonAuth(projectId, branch.id),\n\t\tprobeDatabase\n\t\t\t? api.getNeonDataApi(projectId, branch.id, probeDatabase)\n\t\t\t: Promise.resolve(null),\n\t]);\n\n\treturn buildPulledBranchConfig(project, branch, branches, endpoint, {\n\t\tbuckets,\n\t\tfunctions,\n\t\tcredentials,\n\t\tauthEnabled: auth !== null,\n\t\tdataApiEnabled: dataApi !== null,\n\t});\n}\n\n/**\n * Pick the database to probe for a Data API integration. Data API is enabled per\n * branch + database; for read-back we only need to know whether *any* database has it\n * on, so prefer the conventional default (`neondb`) and otherwise fall back to the first\n * database. Returns `undefined` when the branch has no databases.\n */\nfunction pickProbeDatabase(\n\tdatabases: NeonDatabaseSnapshot[],\n): string | undefined {\n\tif (databases.length === 0) return undefined;\n\tconst byName = databases.find((d) => d.name === \"neondb\");\n\tif (byName) return byName.name;\n\treturn databases[0].name;\n}\n\n/**\n * Run a Preview-feature read, returning `fallback` if the feature is unavailable for the\n * project/region (a {@link ErrorCode.FeatureUnavailable} from the adapter). Other errors\n * propagate. Used by `pullConfig` so a branch without a Preview feature still mirrors\n * cleanly for env resolution / `inspect`, rather than aborting on an unrelated capability.\n */\nasync function degradeUnavailable<T>(\n\tread: () => Promise<T>,\n\tfallback: T,\n): Promise<T> {\n\ttry {\n\t\treturn await read();\n\t} catch (err) {\n\t\tif (\n\t\t\terr instanceof PlatformError &&\n\t\t\terr.code === ErrorCode.FeatureUnavailable\n\t\t) {\n\t\t\treturn fallback;\n\t\t}\n\t\tthrow err;\n\t}\n}\n\nfunction createApiFromOptions(options: PullConfigOptions): NeonApi {\n\treturn createNeonApiFromOptions(\"pullConfig\", {\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t\t...(options.apiHost ? { apiHost: options.apiHost } : {}),\n\t});\n}\n\nexport function buildPulledBranchConfig(\n\tproject: NeonProjectSnapshot,\n\tbranch: NeonBranchSnapshot,\n\tbranches: NeonBranchSnapshot[],\n\tendpoint: NeonEndpointSnapshot | undefined,\n\tpreviewState?: {\n\t\tbuckets: NeonBucketSnapshot[];\n\t\tfunctions: NeonFunctionSnapshot[];\n\t\tcredentials?: NeonCredentialMeta[];\n\t\t/** Whether a Neon Auth integration is enabled on the branch. */\n\t\tauthEnabled?: boolean;\n\t\t/** Whether a Neon Data API integration is enabled on the branch. */\n\t\tdataApiEnabled?: boolean;\n\t},\n): PulledBranchConfig {\n\tconst parent = branch.parentId\n\t\t? branches.find((b) => b.id === branch.parentId)\n\t\t: undefined;\n\t// Auth/Data API are static top-level toggles, so a config pulled from a branch with\n\t// them enabled round-trips through `resolveConfig` / `fetchEnv` and the matching\n\t// secrets get injected. Branch lifecycle/compute is per-branch tuning, so it goes in\n\t// the `branch` closure.\n\tconst tuning: BranchTuning = {};\n\tif (parent) tuning.parent = parent.name;\n\t// Deliberately NOT emitting `ttl` from `branch.expiresAt`: policy `ttl` is a\n\t// creation-time *duration*, while `expiresAt` is an absolute timestamp. Feeding the\n\t// timestamp through `parseDuration` (in `resolveConfig`) would throw, breaking\n\t// `fetchEnv` / `neon dev` / `neon env pull` for any branch that has a TTL. The expiry\n\t// is reported faithfully on `branch.expiresAt` above.\n\tif (branch.protected) tuning.protected = true;\n\tif (endpoint) {\n\t\tconst compute = endpointToComputeSettings(endpoint, project);\n\t\tif (compute) tuning.postgres = { computeSettings: compute };\n\t}\n\tconst config: Config = {\n\t\t...(previewState?.authEnabled ? { auth: true } : {}),\n\t\t...(previewState?.dataApiEnabled ? { dataApi: true } : {}),\n\t\t...(Object.keys(tuning).length > 0 ? { branch: () => tuning } : {}),\n\t};\n\tconst result: PulledBranchConfig = {\n\t\tproject: {\n\t\t\tid: project.id,\n\t\t\tname: project.name,\n\t\t\tregion: project.regionId,\n\t\t\tpgVersion: project.pgVersion,\n\t\t\t...(project.orgId ? { orgId: project.orgId } : {}),\n\t\t},\n\t\tbranch: {\n\t\t\tid: branch.id,\n\t\t\tname: branch.name,\n\t\t\t...(parent ? { parent: parent.name } : {}),\n\t\t\tisDefault: branch.isDefault,\n\t\t\tprotected: branch.protected,\n\t\t\t...(branch.expiresAt ? { expiresAt: branch.expiresAt } : {}),\n\t\t},\n\t\tconfig,\n\t};\n\tconst preview = previewState ? buildPulledPreview(previewState) : undefined;\n\tif (preview) result.preview = preview;\n\treturn result;\n}\n\n/**\n * Reverse-engineer the {@link PulledPreview} from remote snapshots. Returns `undefined` when\n * the branch has no Preview features so the field can be omitted entirely.\n */\nfunction buildPulledPreview(state: {\n\tbuckets: NeonBucketSnapshot[];\n\tfunctions: NeonFunctionSnapshot[];\n\tcredentials?: NeonCredentialMeta[];\n}): PulledPreview | undefined {\n\tconst credentials = state.credentials ?? [];\n\tif (\n\t\tstate.buckets.length === 0 &&\n\t\tstate.functions.length === 0 &&\n\t\tcredentials.length === 0\n\t) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tbuckets: state.buckets.map((b) => ({\n\t\t\tname: b.name,\n\t\t\taccess: b.accessLevel,\n\t\t})),\n\t\tfunctions: state.functions.map((f) => ({\n\t\t\tslug: f.slug,\n\t\t\tname: f.name,\n\t\t})),\n\t\tcredentials,\n\t};\n}\n\nfunction resolveBranch(\n\tbranchId: string,\n\tbranches: NeonBranchSnapshot[],\n): NeonBranchSnapshot {\n\tconst match = branches.find((b) => b.id === branchId);\n\tif (match) return match;\n\tthrow new PlatformError(\n\t\tErrorCode.BranchNotFound,\n\t\t[\n\t\t\t`pullConfig: branch id ${JSON.stringify(branchId)} not found on project.`,\n\t\t\t`Available branches: ${branches.map((b) => `${b.name} (${b.id})`).join(\", \") || \"(none)\"}.`,\n\t\t].join(\" \"),\n\t\t{\n\t\t\tdetails: {\n\t\t\t\tbranchId,\n\t\t\t\tavailable: branches.map((b) => b.id),\n\t\t\t},\n\t\t},\n\t);\n}\n\nfunction endpointToComputeSettings(\n\tendpoint: NeonEndpointSnapshot,\n\tproject: NeonProjectSnapshot,\n): ComputeSettings | undefined {\n\tconst defaults = project.defaultEndpointSettings;\n\tconst out: ComputeSettings = {};\n\tif (\n\t\tendpoint.autoscalingLimitMinCu !== undefined &&\n\t\tendpoint.autoscalingLimitMinCu !== defaults?.autoscalingLimitMinCu\n\t) {\n\t\tout.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;\n\t}\n\tif (\n\t\tendpoint.autoscalingLimitMaxCu !== undefined &&\n\t\tendpoint.autoscalingLimitMaxCu !== defaults?.autoscalingLimitMaxCu\n\t) {\n\t\tout.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;\n\t}\n\tif (\n\t\tendpoint.suspendTimeout !== undefined &&\n\t\tendpoint.suspendTimeout !== defaults?.suspendTimeout\n\t) {\n\t\tout.suspendTimeout = endpoint.suspendTimeout;\n\t}\n\treturn Object.keys(out).length > 0 ? out : undefined;\n}\n"],"mappings":"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"}

package/dist/lib/push-config.d.ts

@@ -0,0 +1,124 @@
+import { FunctionBundler } from "./function-bundle.js";
+import { Config, NeonApi, PushResult } from "@neon/config";
+
+//#region src/lib/push-config.d.ts
+interface PushConfigOptions {
+  /**
+   * Neon project id. **Required** — the management API addresses every branch through
+   * its project, so there is no way to push without it. `pushConfig` never creates a
+   * project; resolve the id yourself (e.g. via neonctl) and pass it in.
+   */
+  projectId: string;
+  /**
+   * Neon branch id (`br-…`). **Required.** `pushConfig` never creates a branch — it must
+   * already exist on the project. Resolve names to ids before calling.
+   */
+  branchId: string;
+  /** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. Ignored when `api` is supplied. */
+  apiKey?: string;
+  /** Neon API base URL. Falls back to `NEON_API_HOST`, then production. */
+  apiHost?: string;
+  /**
+   * Inject a custom NeonApi adapter. Primarily used by tests; production callers can rely
+   * on the default real adapter built from `apiKey`.
+   */
+  api?: NeonApi;
+  /**
+   * Whether to evaluate the policy as if the target branch **already exists** (the value of
+   * `branch.exists` passed to the `defineConfig({ branch: (branch) => … })` closure). Defaults to `true`.
+   *
+   * Set to `false` to evaluate the policy as a **branch creation** — used by
+   * {@link createBranch} right after it provisions a new branch, so creation-time tuning
+   * gated on `!branch.exists` (TTL, compute settings, `parent`) actually resolves instead of
+   * hitting the "existing branch, leave as-is" path. Only affects policy evaluation; the
+   * branch must still physically exist on Neon (`pushConfig` never creates one).
+   */
+  branchExists?: boolean;
+  /**
+   * Auto-confirm overriding existing remote settings.
+   *
+   * When `true`, mutable drift on the selected branch (TTL, `protected` flag, compute
+   * settings) is applied as actual mutations and the override-confirm prompt is
+   * skipped. When `false` (default) the behaviour depends on whether `confirm` is
+   * supplied:
+   *   - With `confirm`: the callback is asked whether to apply the override.
+   *   - Without `confirm`: drift is reported as a `PushConflictError` (legacy
+   *     non-interactive default — preserved so programmatic SDK callers don't
+   *     silently start mutating remote state).
+   */
+  updateExisting?: boolean;
+  /**
+   * Auto-confirm pushing to a protected branch.
+   *
+   * When `true`, no protected-branch confirmation is asked. When `false` (default):
+   *   - With `confirm`: the callback is asked.
+   *   - Without `confirm`: the push proceeds (legacy SDK default).
+   */
+  allowProtectedBranch?: boolean;
+  /**
+   * Optional confirmation callback. Invoked once with a single context object before
+   * any mutations run when the push needs confirmation: pushing to a protected
+   * branch (unless `allowProtectedBranch` is `true`) and/or applying mutable drift
+   * (unless `updateExisting` is `true`).
+   *
+   * Both prompts collapse into a single callback invocation when both apply, so the
+   * CLI can render one combined "are you sure?" prompt.
+   *
+   * Resolves to `true` to proceed, `false` to abort with {@link PushAbortedError}.
+   *
+   * Never invoked on `dryRun`.
+   */
+  confirm?: (context: PushConfirmContext) => boolean | Promise<boolean>;
+  /**
+   * Custom bundler for function source. Defaults to {@link buildFunctionBundle}
+   * (esbuild). Inject your own to deploy functions without this package pulling
+   * esbuild's native binary into your build — see {@link FunctionBundler}.
+   */
+  bundleFunction?: FunctionBundler;
+  /**
+   * When `true`, compute the full plan against the live remote state but **do not
+   * execute any mutations**. The resulting `PushResult.applied` array records every
+   * change that *would* run on a real push (with the same action / identifier / details
+   * shape, so the existing CLI summary formatter just works), and conflicts are
+   * reported instead of thrown.
+   *
+   * Used by `plan(config, branchId)` and any caller that wants a "would this push do
+   * something dangerous?" check before invoking `pushConfig` for real.
+   */
+  dryRun?: boolean;
+}
+/**
+ * Context handed to a {@link PushConfigOptions.confirm} callback. Both flags can be
+ * `true` simultaneously when the push targets a protected branch *and* would override
+ * existing settings — render a single combined prompt covering both reasons.
+ */
+interface PushConfirmContext {
+  /** Name of the target branch on Neon. */
+  branchName: string;
+  /**
+   * `true` when the target branch has the `protected` flag on Neon and the caller
+   * did not pass `allowProtectedBranch: true`.
+   */
+  protectedBranch: boolean;
+  /**
+   * `true` when the plan would override existing remote settings (TTL, `protected`
+   * flag, compute settings on an existing endpoint) and the caller did not pass
+   * `updateExisting: true`. Additive operations (enabling Neon Auth / Data API for
+   * the first time) are **not** counted here — those are unambiguous and never
+   * prompt.
+   */
+  overrideUpdates: boolean;
+}
+/**
+ * Push a Neon branch policy to a specific project + branch.
+ *
+ * Filesystem- and env-agnostic: the caller supplies an already-validated `Config` object
+ * (from `defineConfig` / `loadConfigFromFile`) and explicit `projectId` + `branch` in
+ * `options`. `pushConfig` performs no `.neon` lookups and reads no `NEON_*` env vars except the API credential/host resolution documented on `apiKey`/`apiHost`.
+ *
+ * It will **not** create a project or branch — both must already exist on Neon.
+ */
+declare function pushConfig(config: Config, options: PushConfigOptions): Promise<PushResult>;
+//#endregion
+export { PushConfigOptions, PushConfirmContext, pushConfig };
+//# sourceMappingURL=push-config.d.ts.map

package/dist/lib/push-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-config.d.ts","names":[],"sources":["../../src/lib/push-config.ts"],"mappings":";;;;UAoCiB,iBAAA;;AAAjB;;;;WAkEsD,EAAA,MAAA;;AAMrB;AAmBjC;AA2BA;EAAgC,QAAA,EAAA,MAAA;;QAEtB,CAAA,EAAA,MAAA;;SACP,CAAA,EAAA,MAAA;EAAO;;;;QArGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA8Cc,iCAAiC;;;;;;mBAMpC;;;;;;;;;;;;;;;;;;UAmBD,kBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BK,UAAA,SACb,iBACC,oBACP,QAAQ"}