@neon/config-runtime 0.0.0 → 0.9.0

package/dist/lib/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","names":[],"sources":["../../src/lib/operations.ts"],"sourcesContent":["import {\n\ttype Config,\n\tcreateNeonApiFromOptions,\n\tErrorCode,\n\ttype NeonApi,\n\ttype NeonBranchSnapshot,\n\tPlatformError,\n\ttype PushResult,\n\tresolveConfig,\n} from \"@neon/config\";\nimport type { FunctionBundler } from \"./function-bundle.js\";\nimport { type PulledBranchConfig, pullConfig } from \"./pull-config.js\";\nimport { type PushConfigOptions, pushConfig } from \"./push-config.js\";\n\n/**\n * Where to run the operation and how to authenticate. Filesystem- and env-agnostic: the\n * `projectId` and `branchId` are always passed explicitly by the caller (e.g. neonctl\n * resolves them from `.neon` / `NEON_*` and forwards them here).\n */\nexport interface ConfigOperationOptions {\n\t/**\n\t * Neon project id. **Required** — the management API addresses branches through their\n\t * project, so operations cannot run without it.\n\t */\n\tprojectId: string;\n\t/**\n\t * Neon branch id (`br-…`). **Required.** Must already exist on the project; resolve\n\t * branch names to ids before calling.\n\t */\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?: PushConfigOptions[\"api\"];\n}\n\n/**\n * Options accepted by {@link apply} on top of {@link ConfigOperationOptions}.\n */\nexport interface ApplyOptions extends ConfigOperationOptions {\n\t/**\n\t * Auto-confirm overriding existing remote settings (TTL, `protected`, compute\n\t * settings) on the selected branch. Without it, drift is reported as a conflict.\n\t */\n\tupdateExisting?: boolean;\n\t/** Auto-confirm applying to a branch marked `protected` on Neon. */\n\tallowProtectedBranch?: boolean;\n\t/**\n\t * Custom function bundler. Defaults to esbuild (`buildFunctionBundle`); inject\n\t * your own to deploy functions without pulling esbuild's native binary into\n\t * your build. See {@link FunctionBundler}.\n\t */\n\tbundleFunction?: FunctionBundler;\n}\n\n/**\n * Read a branch's live Neon state as a plain object (project + branch metadata and the\n * reverse-engineered `BranchConfig`). Network read only — never mutates.\n *\n * `projectId` and `branchId` are **required** (both in `options`).\n */\nexport async function inspect(\n\toptions: ConfigOperationOptions,\n): Promise<PulledBranchConfig> {\n\treturn pullConfig({\n\t\tprojectId: options.projectId,\n\t\tbranchId: options.branchId,\n\t\t...(options.api ? { api: options.api } : {}),\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t\t...(options.apiHost ? { apiHost: options.apiHost } : {}),\n\t});\n}\n\n/**\n * Compute what {@link apply} would do for the given branch without mutating anything\n * (dry-run plan). Returns the full {@link PushResult} with the planned changes in\n * `applied` and any blocking drift in `conflicts` — the Neon equivalent of\n * `terraform plan`.\n *\n * `projectId` and `branchId` are **required** (both in `options`).\n */\nexport async function plan(\n\tconfig: Config,\n\toptions: ConfigOperationOptions,\n): Promise<PushResult> {\n\treturn pushConfig(config, {\n\t\tprojectId: options.projectId,\n\t\tbranchId: options.branchId,\n\t\tdryRun: true,\n\t\t// Surface the full would-apply list as plan steps without mutating anything.\n\t\tupdateExisting: true,\n\t\t...(options.api ? { api: options.api } : {}),\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t\t...(options.apiHost ? { apiHost: options.apiHost } : {}),\n\t});\n}\n\n/**\n * Apply a `neon.ts` policy to the given Neon branch and return the {@link PushResult}\n * describing what changed — the Neon equivalent of `terraform apply`.\n *\n * `projectId` and `branchId` are **required** (both in `options`). Pass `updateExisting`\n * to auto-confirm overriding existing remote settings and `allowProtectedBranch` to\n * auto-confirm applying to a protected branch; otherwise drift is reported as a\n * `PushConflictError`.\n *\n * Never creates projects or branches — both must already exist.\n */\nexport async function apply(\n\tconfig: Config,\n\toptions: ApplyOptions,\n): Promise<PushResult> {\n\treturn pushConfig(config, {\n\t\tprojectId: options.projectId,\n\t\tbranchId: options.branchId,\n\t\t...(options.api ? { api: options.api } : {}),\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t\t...(options.apiHost ? { apiHost: options.apiHost } : {}),\n\t\t...(options.updateExisting ? { updateExisting: true } : {}),\n\t\t...(options.allowProtectedBranch ? { allowProtectedBranch: true } : {}),\n\t\t...(options.bundleFunction\n\t\t\t? { bundleFunction: options.bundleFunction }\n\t\t\t: {}),\n\t});\n}\n\n/**\n * Options accepted by {@link createBranch}. Unlike {@link ConfigOperationOptions} this takes a\n * branch **name** (the branch does not exist yet) rather than an id.\n */\nexport interface CreateBranchOptions {\n\t/** Neon project id to create the branch in. **Required.** */\n\tprojectId: string;\n\t/** Name of the branch to create. **Required.** Must not already exist on the project. */\n\tbranchName: string;\n\t/** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. Ignored when `api` is set. */\n\tapiKey?: string;\n\t/** Inject a custom NeonApi adapter (primarily for tests). */\n\tapi?: NeonApi;\n\t/** Custom function bundler (defaults to esbuild). See {@link FunctionBundler}. */\n\tbundleFunction?: FunctionBundler;\n}\n\n/**\n * Result of {@link createBranch}: the created branch's id/name plus the {@link PushResult}\n * describing the policy that was applied to it.\n */\nexport interface CreateBranchResult {\n\tbranchId: string;\n\tbranchName: string;\n\t/** What applying the policy to the freshly created branch changed. */\n\tresult: PushResult;\n}\n\n/**\n * Create a Neon branch **from a `neon.ts` policy** and bring it up with its declared\n * settings/infra in one step — the operation `neonctl checkout <new-name>` needs.\n *\n * The flow is the one a creation actually wants:\n *  1. Evaluate the policy for the new branch with `exists: false` (so creation-time tuning —\n *     `parent`, `ttl`, compute settings, `protected` — resolves instead of the\n *     \"existing branch, leave as-is\" path most policies guard with `if (branch.exists)`).\n *  2. Create the branch, branched from the policy's `parent` (falling back to the project's\n *     default branch).\n *  3. {@link pushConfig} the policy onto it with `branchExists: false`, so TTL / compute /\n *     `protected` and the services (Neon Auth, Data API, functions) are applied.\n *\n * This is why `apply` alone couldn't do it: `apply` operates on an *existing* branch\n * (`exists: true`), so a policy keyed on `!branch.exists` never returns the creation tuning.\n *\n * Throws {@link PlatformError} (`Conflict`) if a branch with `branchName` already exists, or\n * (`BranchNotFound`) if the policy names a `parent` that isn't on the project.\n */\nexport async function createBranch(\n\tconfig: Config,\n\toptions: CreateBranchOptions,\n): Promise<CreateBranchResult> {\n\tconst api =\n\t\toptions.api ??\n\t\tcreateNeonApiFromOptions(\n\t\t\t\"createBranch\",\n\t\t\toptions.apiKey ? { apiKey: options.apiKey } : {},\n\t\t);\n\tconst { projectId, branchName } = options;\n\n\tconst branches = await api.listBranches(projectId);\n\tif (branches.some((b) => b.name === branchName)) {\n\t\tthrow new PlatformError(\n\t\t\tErrorCode.Conflict,\n\t\t\t`createBranch: a branch named \"${branchName}\" already exists on project ${projectId}. Pick a different name or check it out instead of creating it.`,\n\t\t\t{ details: { projectId, branchName } },\n\t\t);\n\t}\n\n\t// Evaluate the policy as a creation so `parent` (only settable at create time) resolves.\n\tconst resolved = resolveConfig(config, {\n\t\tname: branchName,\n\t\texists: false,\n\t});\n\tconst parentId = resolveParentBranchId(\n\t\tresolved.parent,\n\t\tbranches,\n\t\tbranchName,\n\t);\n\n\tconst { branch } = await api.createBranch(projectId, {\n\t\tname: branchName,\n\t\t...(parentId ? { parentId } : {}),\n\t});\n\n\t// Reconcile the rest as a new branch (`branchExists: false`): TTL, compute settings,\n\t// `protected`, and the services/functions the policy declares are applied onto the\n\t// freshly created branch. `updateExisting`/`allowProtectedBranch` are safe here — there is\n\t// no pre-existing state a user would be surprised to see overridden.\n\tconst result = await pushConfig(config, {\n\t\tprojectId,\n\t\tbranchId: branch.id,\n\t\tapi,\n\t\tbranchExists: false,\n\t\tupdateExisting: true,\n\t\tallowProtectedBranch: true,\n\t\t...(options.bundleFunction\n\t\t\t? { bundleFunction: options.bundleFunction }\n\t\t\t: {}),\n\t});\n\n\treturn { branchId: branch.id, branchName: branch.name, result };\n}\n\n/**\n * Resolve the parent branch id for a new branch. A policy-declared `parent` (a branch name) is\n * looked up by name; an unknown name is a hard error. With no `parent`, fall back to the\n * project's default branch, or `undefined` (let the API pick the project default) when none is\n * marked default.\n */\nfunction resolveParentBranchId(\n\tparentName: string | undefined,\n\tbranches: NeonBranchSnapshot[],\n\tbranchName: string,\n): string | undefined {\n\tif (parentName !== undefined) {\n\t\tconst match = branches.find((b) => b.name === parentName);\n\t\tif (!match) {\n\t\t\tthrow new PlatformError(\n\t\t\t\tErrorCode.BranchNotFound,\n\t\t\t\t`createBranch: the policy for \"${branchName}\" sets parent \"${parentName}\", but no branch with that name exists. Existing branches: ${\n\t\t\t\t\tbranches.map((b) => b.name).join(\", \") || \"(none)\"\n\t\t\t\t}.`,\n\t\t\t\t{\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\tbranchName,\n\t\t\t\t\t\tparent: parentName,\n\t\t\t\t\t\tavailable: branches.map((b) => b.name),\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t);\n\t\t}\n\t\treturn match.id;\n\t}\n\treturn branches.find((b) => b.isDefault)?.id;\n}\n"],"mappings":"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"}

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":";;AAgFA,eAAsB,WACrB,SAC8B;CAC9B,MAAM,MAAM,QAAQ,OAAO,qBAAqB,OAAO;CACvD,MAAM,YAAY,QAAQ;CAC1B,MAAM,UAAU,MAAM,IAAI,WAAW,SAAS;CAC9C,MAAM,CAAC,UAAU,aAAa,MAAM,QAAQ,IAAI,CAC/C,IAAI,aAAa,SAAS,GAC1B,IAAI,cAAc,SAAS,CAC5B,CAAC;CACD,MAAM,SAAS,cAAc,QAAQ,UAAU,QAAQ;CACvD,MAAM,WAAW,UAAU,MACzB,OAAO,GAAG,SAAS,gBAAgB,GAAG,aAAa,OAAO,EAC5D;CAIA,MAAM,gBAAgB,kBAAkB,MADhB,IAAI,oBAAoB,WAAW,OAAO,EAAE,CACnB;CAOjD,MAAM,CAAC,SAAS,WAAW,aAAa,MAAM,WAAW,MAAM,QAAQ,IAAI;EAC1E,yBACO,IAAI,kBAAkB,WAAW,OAAO,EAAE,GAChD,CAAC,CACF;EACA,yBACO,IAAI,oBAAoB,WAAW,OAAO,EAAE,GAClD,CAAC,CACF;EACA,yBAAyB,IAAI,gBAAgB,WAAW,OAAO,EAAE,GAAG,CAAC,CAAC;EACtE,IAAI,YAAY,WAAW,OAAO,EAAE;EACpC,gBACG,IAAI,eAAe,WAAW,OAAO,IAAI,aAAa,IACtD,QAAQ,QAAQ,IAAI;CACxB,CAAC;CAED,OAAO,wBAAwB,SAAS,QAAQ,UAAU,UAAU;EACnE;EACA;EACA;EACA,aAAa,SAAS;EACtB,gBAAgB,YAAY;CAC7B,CAAC;AACF;;;;;;;AAQA,SAAS,kBACR,WACqB;CACrB,IAAI,UAAU,WAAW,GAAG,OAAO,KAAA;CACnC,MAAM,SAAS,UAAU,MAAM,MAAM,EAAE,SAAS,QAAQ;CACxD,IAAI,QAAQ,OAAO,OAAO;CAC1B,OAAO,UAAU,EAAE,CAAC;AACrB;;;;;;;AAQA,eAAe,mBACd,MACA,UACa;CACb,IAAI;EACH,OAAO,MAAM,KAAK;CACnB,SAAS,KAAK;EACb,IACC,eAAe,iBACf,IAAI,SAAS,UAAU,oBAEvB,OAAO;EAER,MAAM;CACP;AACD;AAEA,SAAS,qBAAqB,SAAqC;CAClE,OAAO,yBAAyB,cAAc;EAC7C,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EACnD,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;CACvD,CAAC;AACF;AAEA,SAAgB,wBACf,SACA,QACA,UACA,UACA,cASqB;CACrB,MAAM,SAAS,OAAO,WACnB,SAAS,MAAM,MAAM,EAAE,OAAO,OAAO,QAAQ,IAC7C,KAAA;CAKH,MAAM,SAAuB,CAAC;CAC9B,IAAI,QAAQ,OAAO,SAAS,OAAO;CAMnC,IAAI,OAAO,WAAW,OAAO,YAAY;CACzC,IAAI,UAAU;EACb,MAAM,UAAU,0BAA0B,UAAU,OAAO;EAC3D,IAAI,SAAS,OAAO,WAAW,EAAE,iBAAiB,QAAQ;CAC3D;CACA,MAAM,SAAiB;EACtB,GAAI,cAAc,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;EAClD,GAAI,cAAc,iBAAiB,EAAE,SAAS,KAAK,IAAI,CAAC;EACxD,GAAI,OAAO,KAAK,MAAM,CAAC,CAAC,SAAS,IAAI,EAAE,cAAc,OAAO,IAAI,CAAC;CAClE;CACA,MAAM,SAA6B;EAClC,SAAS;GACR,IAAI,QAAQ;GACZ,MAAM,QAAQ;GACd,QAAQ,QAAQ;GAChB,WAAW,QAAQ;GACnB,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EACjD;EACA,QAAQ;GACP,IAAI,OAAO;GACX,MAAM,OAAO;GACb,GAAI,SAAS,EAAE,QAAQ,OAAO,KAAK,IAAI,CAAC;GACxC,WAAW,OAAO;GAClB,WAAW,OAAO;GAClB,GAAI,OAAO,YAAY,EAAE,WAAW,OAAO,UAAU,IAAI,CAAC;EAC3D;EACA;CACD;CACA,MAAM,UAAU,eAAe,mBAAmB,YAAY,IAAI,KAAA;CAClE,IAAI,SAAS,OAAO,UAAU;CAC9B,OAAO;AACR;;;;;AAMA,SAAS,mBAAmB,OAIE;CAC7B,MAAM,cAAc,MAAM,eAAe,CAAC;CAC1C,IACC,MAAM,QAAQ,WAAW,KACzB,MAAM,UAAU,WAAW,KAC3B,YAAY,WAAW,GAEvB;CAED,OAAO;EACN,SAAS,MAAM,QAAQ,KAAK,OAAO;GAClC,MAAM,EAAE;GACR,QAAQ,EAAE;EACX,EAAE;EACF,WAAW,MAAM,UAAU,KAAK,OAAO;GACtC,MAAM,EAAE;GACR,MAAM,EAAE;EACT,EAAE;EACF;CACD;AACD;AAEA,SAAS,cACR,UACA,UACqB;CACrB,MAAM,QAAQ,SAAS,MAAM,MAAM,EAAE,OAAO,QAAQ;CACpD,IAAI,OAAO,OAAO;CAClB,MAAM,IAAI,cACT,UAAU,gBACV,CACC,yBAAyB,KAAK,UAAU,QAAQ,EAAE,yBAClD,uBAAuB,SAAS,KAAK,MAAM,GAAG,EAAE,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,IAAI,KAAK,SAAS,EAC1F,CAAC,CAAC,KAAK,GAAG,GACV,EACC,SAAS;EACR;EACA,WAAW,SAAS,KAAK,MAAM,EAAE,EAAE;CACpC,EACD,CACD;AACD;AAEA,SAAS,0BACR,UACA,SAC8B;CAC9B,MAAM,WAAW,QAAQ;CACzB,MAAM,MAAuB,CAAC;CAC9B,IACC,SAAS,0BAA0B,KAAA,KACnC,SAAS,0BAA0B,UAAU,uBAE7C,IAAI,wBAAwB,SAAS;CAEtC,IACC,SAAS,0BAA0B,KAAA,KACnC,SAAS,0BAA0B,UAAU,uBAE7C,IAAI,wBAAwB,SAAS;CAEtC,IACC,SAAS,mBAAmB,KAAA,KAC5B,SAAS,mBAAmB,UAAU,gBAEtC,IAAI,iBAAiB,SAAS;CAE/B,OAAO,OAAO,KAAK,GAAG,CAAC,CAAC,SAAS,IAAI,MAAM,KAAA;AAC5C"}

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"}