@neondatabase/config 0.0.0 → 0.1.0

package/dist/lib/schema.js

@@ -0,0 +1,199 @@
+import { parseDuration, parseSuspendTimeout } from "./duration.js";
+import { isWildcardPattern, validatePattern } from "./patterns.js";
+import { z } from "zod";
+//#region src/lib/schema.ts
+/**
+* Zod schema for {@link import("./types.js").ComputeSettings}.
+*
+* - CU values must be one of: 0.25, 0.5, 1, 2, 4, 8
+* - `suspendTimeout` can be:
+*   - `false` (never suspend)
+*   - duration string like "5m", "1h" (must be 60s-604800s when parsed)
+*   - number in seconds (60-604800, or -1/0 for special values)
+*   - `undefined` (use platform default)
+*
+* Cross-field invariants (min <= max) are enforced via `superRefine`.
+*/
+const computeSettingsSchema = z.strictObject({
+	autoscalingLimitMinCu: z.union([
+		z.literal(.25),
+		z.literal(.5),
+		z.literal(1),
+		z.literal(2),
+		z.literal(4),
+		z.literal(8)
+	]).optional(),
+	autoscalingLimitMaxCu: z.union([
+		z.literal(.25),
+		z.literal(.5),
+		z.literal(1),
+		z.literal(2),
+		z.literal(4),
+		z.literal(8)
+	]).optional(),
+	suspendTimeout: z.union([
+		z.literal(false),
+		z.string(),
+		z.number()
+	]).optional().superRefine((value, ctx) => {
+		if (value === void 0) return;
+		const result = parseSuspendTimeout(value);
+		if ("error" in result) ctx.addIssue({
+			code: "custom",
+			message: result.error
+		});
+	})
+}).superRefine((settings, ctx) => {
+	const { autoscalingLimitMinCu: min, autoscalingLimitMaxCu: max } = settings;
+	if (min !== void 0 && max !== void 0 && min > max) ctx.addIssue({
+		code: "custom",
+		path: ["autoscalingLimitMinCu"],
+		message: `autoscalingLimitMinCu (${min}) must be <= autoscalingLimitMaxCu (${max})`
+	});
+});
+const serviceToggleSchema = z.strictObject({ enabled: z.boolean().optional() });
+const postgresConfigSchema = z.strictObject({ computeSettings: computeSettingsSchema.optional() });
+/**
+* Branch-unique function slug. Mirrors the Neon Functions API path-segment rule
+* (`platform/internal/platform/functions/name.go`): lowercase DNS label, 1–40 chars.
+*/
+const functionSlugSchema = z.string().regex(/^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$/, "function slug must be a lowercase DNS label (1-40 chars, letters/digits/hyphens, no leading/trailing hyphen)");
+/**
+* Per-function environment map. Every value must be a defined string: a `process.env.X`
+* that is unset surfaces as `undefined` and is rejected here (rather than silently
+* shipping `undefined` into the deployment).
+*/
+const functionEnvSchema = z.record(z.string(), z.string());
+const functionConfigSchema = z.strictObject({
+	slug: functionSlugSchema,
+	name: z.string().min(1).max(255),
+	source: z.string().min(1),
+	env: functionEnvSchema.optional(),
+	runtime: z.literal("nodejs24").optional(),
+	memoryMib: z.union([
+		z.literal(256),
+		z.literal(512),
+		z.literal(1024),
+		z.literal(2048),
+		z.literal(4096),
+		z.literal(8192)
+	]).optional()
+});
+const bucketConfigSchema = z.strictObject({
+	name: z.string().min(1).max(255),
+	access: z.union([z.literal("private"), z.literal("public_read")]).optional()
+});
+const previewConfigSchema = z.strictObject({
+	functions: z.array(functionConfigSchema).optional(),
+	buckets: z.array(bucketConfigSchema).optional(),
+	aiGateway: serviceToggleSchema.optional()
+}).superRefine((preview, ctx) => {
+	assertUnique({
+		ctx,
+		path: ["functions"],
+		items: preview.functions ?? [],
+		key: (fn) => fn.slug,
+		label: "function slug"
+	});
+	assertUnique({
+		ctx,
+		path: ["buckets"],
+		items: preview.buckets ?? [],
+		key: (bucket) => bucket.name,
+		label: "bucket name"
+	});
+});
+/**
+* Flag duplicate keys within a Preview collection so a typo in two function slugs (or two
+* buckets) surfaces as a config error rather than the second silently clobbering the first
+* at apply time.
+*/
+function assertUnique(args) {
+	const { ctx, path, items, key, label } = args;
+	const seen = /* @__PURE__ */ new Set();
+	items.forEach((item, index) => {
+		const value = key(item);
+		if (seen.has(value)) ctx.addIssue({
+			code: "custom",
+			path: [...path, index],
+			message: `duplicate ${label}: ${JSON.stringify(value)}`
+		});
+		seen.add(value);
+	});
+}
+const branchConfigSchema = z.strictObject({
+	parent: z.string().optional(),
+	protected: z.boolean().optional(),
+	ttl: z.union([z.string(), z.number()]).optional().superRefine((value, ctx) => {
+		if (value === void 0) return;
+		const result = parseDuration(value);
+		if ("error" in result) ctx.addIssue({
+			code: "custom",
+			message: result.error
+		});
+	}),
+	postgres: postgresConfigSchema.optional(),
+	auth: serviceToggleSchema.optional(),
+	dataApi: serviceToggleSchema.optional(),
+	preview: previewConfigSchema.optional()
+}).superRefine((cfg, ctx) => {
+	validateParentReference({
+		ctx,
+		path: ["parent"],
+		parent: cfg.parent
+	});
+});
+function validateParentReference(args) {
+	const { ctx, path, parent } = args;
+	if (parent === void 0) return;
+	const patternCheck = validatePattern(parent);
+	if ("error" in patternCheck) ctx.addIssue({
+		code: "custom",
+		path,
+		message: patternCheck.error
+	});
+	else if (isWildcardPattern(parent)) ctx.addIssue({
+		code: "custom",
+		path,
+		message: `parent must be a concrete branch name (no wildcards), got "${parent}"`
+	});
+}
+const configSchema = z.function({
+	input: [z.unknown()],
+	output: z.unknown()
+});
+/**
+* Convert the structured {@link z.ZodError} produced by `configSchema.safeParse` into the
+* `string[]` shape used by {@link import("./errors.js").ConfigValidationError}.
+*
+* Issue paths are rendered as dot-separated property accesses (`postgres.computeSettings`)
+* and unknown-key issues from `strictObject` are normalised so the message contains the
+* substring "unknown key" — keeping pre-zod assertions in test suites and downstream tools
+* stable.
+*/
+function formatZodIssues(error) {
+	return error.issues.map((issue) => {
+		const path = renderPath(issue.path);
+		const message = normaliseIssueMessage(issue);
+		return path ? `${path}: ${message}` : message;
+	});
+}
+function renderPath(path) {
+	let out = "";
+	for (const segment of path) if (typeof segment === "number") out += `[${segment}]`;
+	else if (out === "") out += String(segment);
+	else out += `.${String(segment)}`;
+	return out;
+}
+function normaliseIssueMessage(issue) {
+	if (issue.code === "unrecognized_keys") {
+		const keys = issue.keys ?? [];
+		const formatted = keys.map((k) => JSON.stringify(k)).join(", ");
+		return `unknown key${keys.length === 1 ? "" : "s"}: ${formatted}`;
+	}
+	return issue.message;
+}
+//#endregion
+export { branchConfigSchema, bucketConfigSchema, computeSettingsSchema, configSchema, formatZodIssues, functionConfigSchema, postgresConfigSchema, previewConfigSchema, serviceToggleSchema };
+
+//# sourceMappingURL=schema.js.map

package/dist/lib/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","names":[],"sources":["../../src/lib/schema.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { parseDuration, parseSuspendTimeout } from \"./duration.js\";\nimport { isWildcardPattern, validatePattern } from \"./patterns.js\";\n\n/**\n * Zod schema for {@link import(\"./types.js\").ComputeSettings}.\n *\n * - CU values must be one of: 0.25, 0.5, 1, 2, 4, 8\n * - `suspendTimeout` can be:\n *   - `false` (never suspend)\n *   - duration string like \"5m\", \"1h\" (must be 60s-604800s when parsed)\n *   - number in seconds (60-604800, or -1/0 for special values)\n *   - `undefined` (use platform default)\n *\n * Cross-field invariants (min <= max) are enforced via `superRefine`.\n */\nexport const computeSettingsSchema = z\n\t.strictObject({\n\t\tautoscalingLimitMinCu: z\n\t\t\t.union([\n\t\t\t\tz.literal(0.25),\n\t\t\t\tz.literal(0.5),\n\t\t\t\tz.literal(1),\n\t\t\t\tz.literal(2),\n\t\t\t\tz.literal(4),\n\t\t\t\tz.literal(8),\n\t\t\t])\n\t\t\t.optional(),\n\t\tautoscalingLimitMaxCu: z\n\t\t\t.union([\n\t\t\t\tz.literal(0.25),\n\t\t\t\tz.literal(0.5),\n\t\t\t\tz.literal(1),\n\t\t\t\tz.literal(2),\n\t\t\t\tz.literal(4),\n\t\t\t\tz.literal(8),\n\t\t\t])\n\t\t\t.optional(),\n\t\tsuspendTimeout: z\n\t\t\t.union([z.literal(false), z.string(), z.number()])\n\t\t\t.optional()\n\t\t\t.superRefine((value, ctx) => {\n\t\t\t\tif (value === undefined) return; // undefined is valid (use platform default)\n\t\t\t\tconst result = parseSuspendTimeout(value);\n\t\t\t\tif (\"error\" in result) {\n\t\t\t\t\tctx.addIssue({\n\t\t\t\t\t\tcode: \"custom\",\n\t\t\t\t\t\tmessage: result.error,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}),\n\t})\n\t.superRefine((settings, ctx) => {\n\t\tconst { autoscalingLimitMinCu: min, autoscalingLimitMaxCu: max } =\n\t\t\tsettings;\n\t\tif (min !== undefined && max !== undefined && min > max) {\n\t\t\tctx.addIssue({\n\t\t\t\tcode: \"custom\",\n\t\t\t\tpath: [\"autoscalingLimitMinCu\"],\n\t\t\t\tmessage: `autoscalingLimitMinCu (${min}) must be <= autoscalingLimitMaxCu (${max})`,\n\t\t\t});\n\t\t}\n\t});\n\nexport const serviceToggleSchema = z.strictObject({\n\tenabled: z.boolean().optional(),\n});\n\nexport const postgresConfigSchema = z.strictObject({\n\tcomputeSettings: computeSettingsSchema.optional(),\n});\n\n/**\n * Branch-unique function slug. Mirrors the Neon Functions API path-segment rule\n * (`platform/internal/platform/functions/name.go`): lowercase DNS label, 1–40 chars.\n */\nconst functionSlugSchema = z\n\t.string()\n\t.regex(\n\t\t/^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$/,\n\t\t\"function slug must be a lowercase DNS label (1-40 chars, letters/digits/hyphens, no leading/trailing hyphen)\",\n\t);\n\n/**\n * Per-function environment map. Every value must be a defined string: a `process.env.X`\n * that is unset surfaces as `undefined` and is rejected here (rather than silently\n * shipping `undefined` into the deployment).\n */\nconst functionEnvSchema = z.record(z.string(), z.string());\n\nexport const functionConfigSchema = z.strictObject({\n\tslug: functionSlugSchema,\n\tname: z.string().min(1).max(255),\n\tsource: z.string().min(1),\n\tenv: functionEnvSchema.optional(),\n\truntime: z.literal(\"nodejs24\").optional(),\n\tmemoryMib: z\n\t\t.union([\n\t\t\tz.literal(256),\n\t\t\tz.literal(512),\n\t\t\tz.literal(1024),\n\t\t\tz.literal(2048),\n\t\t\tz.literal(4096),\n\t\t\tz.literal(8192),\n\t\t])\n\t\t.optional(),\n});\n\nexport const bucketConfigSchema = z.strictObject({\n\tname: z.string().min(1).max(255),\n\taccess: z\n\t\t.union([z.literal(\"private\"), z.literal(\"public_read\")])\n\t\t.optional(),\n});\n\nexport const previewConfigSchema = z\n\t.strictObject({\n\t\tfunctions: z.array(functionConfigSchema).optional(),\n\t\tbuckets: z.array(bucketConfigSchema).optional(),\n\t\taiGateway: serviceToggleSchema.optional(),\n\t})\n\t.superRefine((preview, ctx) => {\n\t\tassertUnique({\n\t\t\tctx,\n\t\t\tpath: [\"functions\"],\n\t\t\titems: preview.functions ?? [],\n\t\t\tkey: (fn) => fn.slug,\n\t\t\tlabel: \"function slug\",\n\t\t});\n\t\tassertUnique({\n\t\t\tctx,\n\t\t\tpath: [\"buckets\"],\n\t\t\titems: preview.buckets ?? [],\n\t\t\tkey: (bucket) => bucket.name,\n\t\t\tlabel: \"bucket name\",\n\t\t});\n\t});\n\n/**\n * Flag duplicate keys within a Preview collection so a typo in two function slugs (or two\n * buckets) surfaces as a config error rather than the second silently clobbering the first\n * at apply time.\n */\nfunction assertUnique<T>(args: {\n\tctx: z.RefinementCtx;\n\tpath: (string | number)[];\n\titems: T[];\n\tkey: (item: T) => string;\n\tlabel: string;\n}): void {\n\tconst { ctx, path, items, key, label } = args;\n\tconst seen = new Set<string>();\n\titems.forEach((item, index) => {\n\t\tconst value = key(item);\n\t\tif (seen.has(value)) {\n\t\t\tctx.addIssue({\n\t\t\t\tcode: \"custom\",\n\t\t\t\tpath: [...path, index],\n\t\t\t\tmessage: `duplicate ${label}: ${JSON.stringify(value)}`,\n\t\t\t});\n\t\t}\n\t\tseen.add(value);\n\t});\n}\n\nexport const branchConfigSchema = z\n\t.strictObject({\n\t\tparent: z.string().optional(),\n\t\tprotected: z.boolean().optional(),\n\t\tttl: z\n\t\t\t.union([z.string(), z.number()])\n\t\t\t.optional()\n\t\t\t.superRefine((value, ctx) => {\n\t\t\t\tif (value === undefined) return;\n\t\t\t\tconst result = parseDuration(value);\n\t\t\t\tif (\"error\" in result) {\n\t\t\t\t\tctx.addIssue({ code: \"custom\", message: result.error });\n\t\t\t\t}\n\t\t\t}),\n\t\tpostgres: postgresConfigSchema.optional(),\n\t\tauth: serviceToggleSchema.optional(),\n\t\tdataApi: serviceToggleSchema.optional(),\n\t\tpreview: previewConfigSchema.optional(),\n\t})\n\t.superRefine((cfg, ctx) => {\n\t\tvalidateParentReference({\n\t\t\tctx,\n\t\t\tpath: [\"parent\"],\n\t\t\tparent: cfg.parent,\n\t\t});\n\t});\n\nfunction validateParentReference(args: {\n\tctx: z.RefinementCtx;\n\tpath: (string | number)[];\n\tparent: string | undefined;\n}): void {\n\tconst { ctx, path, parent } = args;\n\tif (parent === undefined) return;\n\n\tconst patternCheck = validatePattern(parent);\n\tif (\"error\" in patternCheck) {\n\t\tctx.addIssue({ code: \"custom\", path, message: patternCheck.error });\n\t} else if (isWildcardPattern(parent)) {\n\t\tctx.addIssue({\n\t\t\tcode: \"custom\",\n\t\t\tpath,\n\t\t\tmessage: `parent must be a concrete branch name (no wildcards), got \"${parent}\"`,\n\t\t});\n\t}\n}\n\nexport const configSchema = z.function({\n\tinput: [z.unknown()],\n\toutput: z.unknown(),\n});\n\n/**\n * Convert the structured {@link z.ZodError} produced by `configSchema.safeParse` into the\n * `string[]` shape used by {@link import(\"./errors.js\").ConfigValidationError}.\n *\n * Issue paths are rendered as dot-separated property accesses (`postgres.computeSettings`)\n * and unknown-key issues from `strictObject` are normalised so the message contains the\n * substring \"unknown key\" — keeping pre-zod assertions in test suites and downstream tools\n * stable.\n */\nexport function formatZodIssues(error: z.ZodError): string[] {\n\treturn error.issues.map((issue) => {\n\t\tconst path = renderPath(issue.path);\n\t\tconst message = normaliseIssueMessage(issue);\n\t\treturn path ? `${path}: ${message}` : message;\n\t});\n}\n\nfunction renderPath(path: ReadonlyArray<PropertyKey>): string {\n\tlet out = \"\";\n\tfor (const segment of path) {\n\t\tif (typeof segment === \"number\") out += `[${segment}]`;\n\t\telse if (out === \"\") out += String(segment);\n\t\telse out += `.${String(segment)}`;\n\t}\n\treturn out;\n}\n\nfunction normaliseIssueMessage(issue: z.core.$ZodIssue): string {\n\tif (issue.code === \"unrecognized_keys\") {\n\t\tconst keys = (issue as z.core.$ZodIssueUnrecognizedKeys).keys ?? [];\n\t\tconst formatted = keys.map((k) => JSON.stringify(k)).join(\", \");\n\t\treturn `unknown key${keys.length === 1 ? \"\" : \"s\"}: ${formatted}`;\n\t}\n\treturn issue.message;\n}\n"],"mappings":"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"}

package/dist/lib/types.d.ts

@@ -0,0 +1,259 @@
+//#region src/lib/types.d.ts
+/**
+ * Valid Neon Compute Unit values.
+ * Most plans support 0.25, 0.5, 1, 2, 4, 8. Higher values may be available on Business plans.
+ */
+type ComputeUnit = 0.25 | 0.5 | 1 | 2 | 4 | 8;
+/**
+ * Compute settings applied to the read/write endpoint of a branch.
+ *
+ * Mirrors the subset of {@link https://api-docs.neon.tech/reference/getting-started-with-neon-api Neon endpoint}
+ * fields that we expose as IaC primitives. Anything left undefined falls back to the project's
+ * `default_endpoint_settings` (which themselves fall back to Neon platform defaults).
+ */
+interface ComputeSettings {
+  /**
+   * Minimum number of Compute Units. Set to 0.25 for true scale-to-zero.
+   * @example 0.25  // scale-to-zero
+   * @example 1     // always-on with 1 CU minimum
+   */
+  autoscalingLimitMinCu?: ComputeUnit;
+  /**
+   * Maximum number of Compute Units for autoscaling.
+   * @example 2
+   * @example 8
+   */
+  autoscalingLimitMaxCu?: ComputeUnit;
+  /**
+   * How long to wait before suspending an idle compute.
+   *
+   * - `false` — never suspend (always-on compute)
+   * - `"5m"` — duration string (supports "30s", "5m", "1h", "7d", etc)
+   * - `300` — custom timeout in seconds (60-604800)
+   * - `undefined` — use Neon platform default (currently 300s / 5 minutes)
+   *
+   * @example false       // never suspend
+   * @example "5m"        // 5 minutes
+   * @example "1h"        // 1 hour
+   * @example 300         // 5 minutes in seconds
+   */
+  suspendTimeout?: false | "5m" | "1h" | string | number;
+}
+/**
+ * Read-only descriptor of the branch a {@link Config} policy is being evaluated for — the
+ * `branch` argument passed to your `defineConfig((branch) => …)` callback. It describes
+ * **which** branch this invocation decides for; it is not a live branch handle and must not
+ * be mutated. Switch on its fields and return the desired {@link BranchConfig}.
+ */
+interface BranchTarget {
+  /** Branch name being evaluated. For `branch dev`, this is the generated branch name. */
+  name: string;
+  /** Neon branch id when the branch already exists. Undefined during pre-create eval. */
+  id?: string;
+  /** Whether this branch already exists on Neon. */
+  exists: boolean;
+  /** Parent branch id from Neon when known. */
+  parentId?: string;
+  /** Whether Neon marks this branch as the project default. */
+  isDefault?: boolean;
+  /** Whether Neon currently marks this branch protected. */
+  isProtected?: boolean;
+  /** Current expiration timestamp from Neon, when set. */
+  expiresAt?: string;
+}
+interface ServiceToggle {
+  /** Defaults to `true` when the service namespace is present. Set `false` to opt out. */
+  enabled?: boolean;
+}
+interface PostgresConfig {
+  computeSettings?: ComputeSettings;
+}
+/**
+ * Supported function runtimes. Mirrors the Neon Functions deploy API `runtime` enum.
+ * Only `nodejs24` exists today; kept as a union so adding runtimes later is a
+ * non-breaking, type-checked change.
+ */
+type FunctionRuntime = "nodejs24";
+/**
+ * Memory sizes (MiB) accepted by the Neon Functions deploy API. Mirrors the
+ * `memory_mib` enum in the spec.
+ */
+type FunctionMemoryMib = 256 | 512 | 1024 | 2048 | 4096 | 8192;
+/**
+ * A single Neon Function deployed to a branch (Preview feature).
+ *
+ * A function is invoked like a Cloudflare/Vercel handler — its source module
+ * `export default { fetch }` or `export async function handler(req): Response`. The
+ * `source` path is bundled (esbuild) and uploaded as a deployment; the newest
+ * deployment becomes active.
+ */
+interface FunctionConfig {
+  /**
+   * Branch-unique, lowercase DNS-label used as the path segment in the function's
+   * invocation URL. Immutable once created. 1–40 chars, `^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$`.
+   * @example "hello-world"
+   */
+  slug: string;
+  /** Free-form display name. @example "Hello World" */
+  name: string;
+  /**
+   * Path to the function's entry module, **relative to `neon.ts`** (or absolute). The
+   * module's default export (`{ fetch }`) or `handler` export is the function entry. This
+   * path is resolved against the loaded `neon.ts` location and bundled with esbuild at
+   * deploy time.
+   *
+   * We require a string path rather than an imported handler because a JS function value
+   * carries no reference back to its source file, so esbuild has nothing to bundle from.
+   * @example "./functions/hello-world.ts"
+   */
+  source: string;
+  /**
+   * Environment variables injected into the deployed function. Every value must be a
+   * defined string — a `process.env.X` that is `undefined` (unset) errors at validation
+   * time rather than silently shipping `undefined`.
+   * @example { RESEND_API_KEY: process.env.RESEND_API_KEY }
+   */
+  env?: Record<string, string>;
+  /** Runtime to execute the function with. Defaults to `"nodejs24"`. */
+  runtime?: FunctionRuntime;
+  /** Memory allotted to each invocation, in MiB. Defaults to `512`. */
+  memoryMib?: FunctionMemoryMib;
+}
+/** Anonymous-access level for a branchable object-storage bucket. */
+type BucketAccessLevel = "private" | "public_read";
+/**
+ * A branchable object-storage bucket on a branch (Preview feature).
+ */
+interface BucketConfig {
+  /** Bucket name, unique within a branch. 1–255 chars. */
+  name: string;
+  /**
+   * Anonymous access level. `private` (default) requires authenticated reads/writes;
+   * `public_read` allows anonymous GetObject/HeadObject.
+   */
+  access?: BucketAccessLevel;
+}
+/**
+ * Branch-scoped Preview features. Grouped under `preview` to signal they are backed by
+ * Neon `x-stability-level: beta` endpoints and may change before GA.
+ */
+interface PreviewConfig {
+  /** Functions to deploy on the branch. */
+  functions?: FunctionConfig[];
+  /** Object-storage buckets to create on the branch. */
+  buckets?: BucketConfig[];
+  /** Enable/disable the AI Gateway on the branch (toggle, like auth / dataApi). */
+  aiGateway?: ServiceToggle;
+}
+interface BranchConfigBase {
+  /** Parent branch name used when creating a new branch. Not a Postgres setting. */
+  parent?: string;
+  /** Time-to-live applied when creating a new branch, or reconciled on existing branches. */
+  ttl?: string | number;
+  /** Whether the selected branch should be protected. Undefined means "leave as-is". */
+  protected?: boolean;
+  postgres?: PostgresConfig;
+  /**
+   * Branch-scoped Preview features (functions, object-storage buckets, AI Gateway).
+   * Backed by Neon `x-stability-level: beta` endpoints — see {@link PreviewConfig}.
+   */
+  preview?: PreviewConfig;
+}
+type BranchServiceConfig = {
+  auth?: never;
+  dataApi?: never;
+} | {
+  auth: ServiceToggle;
+  dataApi?: never;
+} | {
+  auth?: never;
+  dataApi: ServiceToggle;
+} | {
+  auth: ServiceToggle;
+  dataApi: ServiceToggle;
+};
+type BranchConfig = BranchConfigBase & BranchServiceConfig;
+type Config = (branch: BranchTarget) => BranchConfig;
+/**
+ * A function with all deploy defaults applied. `resolveConfig` fills in `runtime` and
+ * `memoryMib` so downstream diff/apply never has to re-derive them.
+ */
+interface ResolvedFunctionConfig {
+  slug: string;
+  name: string;
+  source: string;
+  env: Record<string, string>;
+  runtime: FunctionRuntime;
+  memoryMib: FunctionMemoryMib;
+}
+/** A bucket with its access level defaulted to `private`. */
+interface ResolvedBucketConfig {
+  name: string;
+  access: BucketAccessLevel;
+}
+/**
+ * Normalized {@link PreviewConfig}. Only present on {@link ResolvedBranchConfig} when the
+ * policy returned a `preview` block. `aiGatewayEnabled` follows the same
+ * "present-and-not-`false`" semantics as `authEnabled` / `dataApiEnabled`.
+ */
+interface ResolvedPreviewConfig {
+  functions: ResolvedFunctionConfig[];
+  buckets: ResolvedBucketConfig[];
+  aiGatewayEnabled: boolean;
+}
+interface ResolvedBranchConfig {
+  parent?: string;
+  ttlSeconds?: number;
+  protected?: boolean;
+  postgres?: PostgresConfig;
+  authEnabled: boolean;
+  dataApiEnabled: boolean;
+  preview?: ResolvedPreviewConfig;
+}
+/**
+ * One concrete change `pushConfig` made (or, in dry-run, would make) on the remote.
+ */
+interface AppliedChange {
+  /**
+   * `service` covers branch-scoped integrations driven by the branch policy (e.g.
+   * Neon Auth, Data API).
+   */
+  kind: "branch" | "service";
+  action: "create" | "update" | "noop";
+  identifier: string;
+  details?: Record<string, unknown>;
+}
+/**
+ * A diff entry that conflicts with the desired config. `pushConfig` throws
+ * {@link PushConflictError} on the first call when conflicts exist; pass
+ * `updateExisting: true` to apply mutable drift (settings, `protected`, TTL, project
+ * rename). Immutable fields (region, Postgres major version) are always conflicts —
+ * recreate the project to change them.
+ */
+interface ConflictReport {
+  kind: "branch";
+  identifier: string;
+  field: string;
+  current: unknown;
+  desired: unknown;
+  reason: string;
+}
+/**
+ * Result of a `pushConfig` invocation.
+ */
+interface PushResult {
+  projectId: string;
+  orgId?: string;
+  branchId: string;
+  branchName: string;
+  /**
+   * `true` when `pushConfig` was called with `{ dryRun: true }`. `applied` then records
+   * what **would** be applied on a real push; no API mutations were performed.
+   */
+  dryRun: boolean;
+  applied: AppliedChange[];
+  conflicts: ConflictReport[];
+}
+//#endregion
+export { AppliedChange, BranchConfig, BranchTarget, BucketAccessLevel, BucketConfig, ComputeSettings, ComputeUnit, Config, ConflictReport, FunctionConfig, FunctionMemoryMib, FunctionRuntime, PostgresConfig, PreviewConfig, PushResult, ResolvedBranchConfig, ResolvedBucketConfig, ResolvedFunctionConfig, ResolvedPreviewConfig, ServiceToggle };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/lib/types.ts"],"mappings":";;AAIA;AASA;;AAMyB,KAfb,WAAA,GAea,IAAA,GAAA,GAAA,GAAA,CAAA,GAAA,CAAA,GAAA,CAAA,GAAA,CAAA;;AAMW;AAuBpC;AAiBA;AAKA;AASA;AAMA;AAUiB,UAlFA,eAAA,CAkFc;EAAA;;;;AA8BD;EAIlB,qBAAiB,CAAA,EA9GJ,WA8GI;EAKZ;AAcjB;;;;uBAMa,CAAA,EAjIY,WAiIZ;EAAa;AACzB;;;;AAcuB;AAAA;;;;;;AAOwB;EAEpC,cAAA,CAAY,EAAA,KAAA,GAAA,IAAA,GAAA,IAAA,GAAA,MAAA,GAAA,MAAA;;;;AAAyC;AAEjE;;;AAA+C,UApI9B,YAAA,CAoI8B;EAAY;EAM1C,IAAA,EAAA,MAAA;EAAsB;KAIjC,EAAA,MAAA;;QAEM,EAAA,OAAA;EAAiB;EAIZ,QAAA,CAAA,EAAA,MAAA;EAUA;EAAqB,SAAA,CAAA,EAAA,OAAA;;aAE5B,CAAA,EAAA,OAAA;EAAoB;EAIb,SAAA,CAAA,EAAA,MAAA;;AAIL,UAvJK,aAAA,CAuJL;;EAGoB,OAAA,CAAA,EAAA,OAAA;AAMhC;AAkBiB,UA7KA,cAAA,CA6Kc;EAYd,eAAU,CAAA,EAxLR,eAwLQ;;;;AAWD;;;KA3Ld,eAAA;;;;;KAMA,iBAAA;;;;;;;;;UAUK,cAAA;;;;;;;;;;;;;;;;;;;;;;;;;;QA0BV;;YAEI;;cAEE;;;KAID,iBAAA;;;;UAKK,YAAA;;;;;;;WAOP;;;;;;UAOO,aAAA;;cAEJ;;YAEF;;cAEE;;UAGH,gBAAA;;;;;;;aAOE;;;;;YAKD;;KAGN,mBAAA;;;;QAEM;;;;WACiB;;QACjB;WAAwB;;KAEvB,YAAA,GAAe,mBAAmB;KAElC,MAAA,YAAkB,iBAAiB;;;;;UAM9B,sBAAA;;;;OAIX;WACI;aACE;;;UAIK,oBAAA;;UAER;;;;;;;UAQQ,qBAAA;aACL;WACF;;;UAIO,oBAAA;;;;aAIL;;;YAGD;;;;;UAMM,aAAA;;;;;;;;YAQN;;;;;;;;;UAUM,cAAA;;;;;;;;;;;UAYA,UAAA;;;;;;;;;;WAUP;aACE"}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/wrap-neon-error.d.ts

@@ -0,0 +1,30 @@
+import { PlatformError } from "./errors.js";
+
+//#region src/lib/wrap-neon-error.d.ts
+
+/**
+ * Context the wrapper attaches to every PlatformError so consumers can debug without
+ * digging into the raw axios stack.
+ */
+interface NeonErrorContext {
+  /** Short label of the operation that failed, e.g. `getProject(proj-foo)` or `createBranch`. */
+  op: string;
+  /** Optional project id when the operation is project-scoped. */
+  projectId?: string;
+}
+/**
+ * Turn a raw error from `@neondatabase/api-client` (axios under the hood) into a typed
+ * {@link PlatformError} whose message includes:
+ *
+ * 1. What operation was attempted (`op`, e.g. `getProject(proj-foo)`).
+ * 2. Why it failed in human terms (e.g. "API key is unauthorized").
+ * 3. The exact Neon API error message + request id (when present) for support tickets.
+ * 4. A concrete next action ("Generate a new key at …", "Pass `projectId`", …).
+ *
+ * Non-axios errors are passed through unchanged (a regular `Error` already has a useful
+ * stack trace; wrapping it would lose information without adding value).
+ */
+declare function wrapNeonError(err: unknown, context: NeonErrorContext): PlatformError | unknown;
+//#endregion
+export { NeonErrorContext, wrapNeonError };
+//# sourceMappingURL=wrap-neon-error.d.ts.map

package/dist/lib/wrap-neon-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-neon-error.d.ts","names":[],"sources":["../../src/lib/wrap-neon-error.ts"],"mappings":";;;;;;AAMA;AAmBA;AAA6B,UAnBZ,gBAAA,CAmBY;;MAG1B,MAAA;EAAa;;;;;;;;;;;;;;;iBAHA,aAAA,wBAEN,mBACP"}

package/dist/lib/wrap-neon-error.js

@@ -0,0 +1,139 @@
+import { ErrorCode, PlatformError } from "./errors.js";
+//#region src/lib/wrap-neon-error.ts
+/**
+* Turn a raw error from `@neondatabase/api-client` (axios under the hood) into a typed
+* {@link PlatformError} whose message includes:
+*
+* 1. What operation was attempted (`op`, e.g. `getProject(proj-foo)`).
+* 2. Why it failed in human terms (e.g. "API key is unauthorized").
+* 3. The exact Neon API error message + request id (when present) for support tickets.
+* 4. A concrete next action ("Generate a new key at …", "Pass `projectId`", …).
+*
+* Non-axios errors are passed through unchanged (a regular `Error` already has a useful
+* stack trace; wrapping it would lose information without adding value).
+*/
+function wrapNeonError(err, context) {
+	if (err instanceof PlatformError) return err;
+	const httpInfo = extractHttpInfo(err);
+	if (!httpInfo) {
+		const networkInfo = extractNetworkInfo(err);
+		if (networkInfo) return new PlatformError(ErrorCode.NetworkError, `Could not reach the Neon API while running ${context.op}: ${networkInfo.message}. Check your network connection and that https://console.neon.tech is reachable.`, {
+			cause: err,
+			details: {
+				op: context.op,
+				...networkInfo
+			}
+		});
+		return err;
+	}
+	const apiSummary = httpInfo.neonMessage ? `Neon API said: "${httpInfo.neonMessage}"` : `HTTP ${httpInfo.status}`;
+	const requestIdSuffix = httpInfo.requestId ? ` (request id ${httpInfo.requestId})` : "";
+	const apiSummaryWithRequestId = `${apiSummary}${requestIdSuffix}.`;
+	switch (httpInfo.status) {
+		case 401: return new PlatformError(ErrorCode.Unauthorized, [
+			`${context.op} failed: the Bearer token sent to the Neon API was rejected.`,
+			apiSummaryWithRequestId,
+			"Either (a) generate or rotate an API key at https://console.neon.tech/app/settings/api-keys and set NEON_API_KEY / pass --api-key, or (b) re-run `npx neonctl auth` to refresh the OAuth token in `~/.config/neonctl/credentials.json` (OAuth tokens expire)."
+		].join(" "), {
+			cause: err,
+			details: httpDetails(context, httpInfo)
+		});
+		case 403: return new PlatformError(ErrorCode.Forbidden, [
+			`${context.op} failed: this API key is not allowed to perform that operation.`,
+			apiSummaryWithRequestId,
+			"Project-scoped keys can only operate on their own project; switch to an organisation/user-scoped key or pass `projectId` for an operation that doesn't need listing."
+		].join(" "), {
+			cause: err,
+			details: httpDetails(context, httpInfo)
+		});
+		case 404: return new PlatformError(ErrorCode.NotFound, [
+			`${context.op} failed: resource not found on Neon.`,
+			apiSummaryWithRequestId,
+			context.projectId ? `Verify that project '${context.projectId}' exists in this account and that the API key has access to it.` : "Verify that the resource id is correct and that the API key has access to it."
+		].join(" "), {
+			cause: err,
+			details: httpDetails(context, httpInfo)
+		});
+		case 409: return new PlatformError(ErrorCode.Conflict, [
+			`${context.op} failed: a conflicting resource already exists on Neon.`,
+			apiSummaryWithRequestId,
+			"This is often a name collision (e.g. a branch with the same name already exists). Pull first to compare against the remote, or rename in your `neon.ts`."
+		].join(" "), {
+			cause: err,
+			details: httpDetails(context, httpInfo)
+		});
+		case 423: return new PlatformError(ErrorCode.Locked, [
+			`${context.op} failed: the resource is still being modified by a previous operation, and our built-in retries did not drain it in time.`,
+			apiSummaryWithRequestId,
+			"Wait a few seconds and re-run, or raise `retryOnLocked.maxAttempts` when constructing the real Neon adapter."
+		].join(" "), {
+			cause: err,
+			details: httpDetails(context, httpInfo)
+		});
+		case 429: return new PlatformError(ErrorCode.RateLimited, [
+			`${context.op} failed: rate-limited by the Neon API.`,
+			apiSummaryWithRequestId,
+			"Back off and retry; if this happens repeatedly, contact Neon support with the request id above."
+		].join(" "), {
+			cause: err,
+			details: httpDetails(context, httpInfo)
+		});
+	}
+	if (httpInfo.status >= 500) return new PlatformError(ErrorCode.ServerError, [
+		`${context.op} failed: the Neon API returned a server error (HTTP ${httpInfo.status}).`,
+		apiSummaryWithRequestId,
+		"This is most likely transient. Retry shortly; if it persists, file an issue with the request id above and check https://neonstatus.com."
+	].join(" "), {
+		cause: err,
+		details: httpDetails(context, httpInfo)
+	});
+	return new PlatformError(ErrorCode.ServerError, `${context.op} failed: HTTP ${httpInfo.status}. ${apiSummary}${requestIdSuffix}.`, {
+		cause: err,
+		details: httpDetails(context, httpInfo)
+	});
+}
+function extractHttpInfo(err) {
+	if (err === null || typeof err !== "object") return null;
+	const response = err.response;
+	if (response === null || typeof response !== "object") return null;
+	const status = response.status;
+	if (typeof status !== "number") return null;
+	const data = response.data;
+	const out = { status };
+	if (data !== null && typeof data === "object") {
+		const dataObj = data;
+		if (typeof dataObj.message === "string" && dataObj.message !== "") out.neonMessage = dataObj.message;
+		if (typeof dataObj.code === "string" && dataObj.code !== "") out.neonCode = dataObj.code;
+		if (typeof dataObj.request_id === "string" && dataObj.request_id !== "") out.requestId = dataObj.request_id;
+	}
+	return out;
+}
+function extractNetworkInfo(err) {
+	if (err === null || typeof err !== "object") return null;
+	const code = err.code;
+	const message = err.message;
+	if (typeof code === "string" && /^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/.test(code)) return {
+		message: typeof message === "string" ? message : code,
+		code
+	};
+	if (code === "ECONNABORTED") return {
+		message: typeof message === "string" ? message : "timeout",
+		code
+	};
+	return null;
+}
+function httpDetails(context, info) {
+	const out = {
+		op: context.op,
+		status: info.status
+	};
+	if (context.projectId) out.projectId = context.projectId;
+	if (info.neonMessage) out.neonMessage = info.neonMessage;
+	if (info.neonCode) out.neonCode = info.neonCode;
+	if (info.requestId) out.requestId = info.requestId;
+	return out;
+}
+//#endregion
+export { wrapNeonError };
+
+//# sourceMappingURL=wrap-neon-error.js.map