@neondatabase/config 0.0.0

package/src/lib/wrap-neon-error.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "vitest";
+import { ErrorCode, PlatformError } from "./errors.js";
+import { wrapNeonError } from "./wrap-neon-error.js";
+
+function axiosLike(
+	status: number,
+	body?: { message?: string; code?: string; request_id?: string },
+): { response: { status: number; data?: object } } {
+	const err: { response: { status: number; data?: object } } = {
+		response: { status },
+	};
+	if (body) err.response.data = body;
+	return err;
+}
+
+const CTX = { op: "getProject(proj-x)", projectId: "proj-x" } as const;
+
+describe("wrapNeonError — HTTP status mapping", () => {
+	test("401 → Unauthorized + key + neonctl-auth advice + request id", () => {
+		const err = wrapNeonError(
+			axiosLike(401, { message: "Invalid API key", request_id: "req-1" }),
+			CTX,
+		);
+		expect(err).toBeInstanceOf(PlatformError);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.Unauthorized);
+		// Message now suggests both fix paths since we accept both API keys and the
+		// OAuth token written by `neonctl auth`.
+		expect(p.message).toContain(
+			"Bearer token sent to the Neon API was rejected",
+		);
+		expect(p.message).toContain(
+			"https://console.neon.tech/app/settings/api-keys",
+		);
+		expect(p.message).toContain("neonctl auth");
+		expect(p.message).toContain("req-1");
+		expect(p.details.status).toBe(401);
+		expect(p.details.requestId).toBe("req-1");
+	});
+
+	test("403 → Forbidden + project-scoped key explanation", () => {
+		const err = wrapNeonError(
+			axiosLike(403, {
+				message: "not allowed for organization API keys",
+			}),
+			CTX,
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.Forbidden);
+		expect(p.message).toContain(
+			"Project-scoped keys can only operate on their own project",
+		);
+	});
+
+	test("404 → NotFound + verifies project id when present", () => {
+		const err = wrapNeonError(
+			axiosLike(404, { message: "project not found" }),
+			CTX,
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.NotFound);
+		expect(p.message).toContain("project 'proj-x'");
+	});
+
+	test("409 → Conflict + name-collision hint", () => {
+		const err = wrapNeonError(
+			axiosLike(409, { message: "branch already exists" }),
+			{
+				op: "createBranch(proj-x/preview)",
+			},
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.Conflict);
+		expect(p.message).toContain("conflicting resource");
+		expect(p.message).toContain("Pull first");
+	});
+
+	test("423 → Locked + retry-knob hint", () => {
+		const err = wrapNeonError(
+			axiosLike(423, { message: "operation in progress" }),
+			CTX,
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.Locked);
+		expect(p.message).toContain("retryOnLocked");
+	});
+
+	test("429 → RateLimited + support link", () => {
+		const err = wrapNeonError(axiosLike(429), CTX);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.RateLimited);
+		expect(p.message).toContain("rate-limited");
+	});
+
+	test("5xx → ServerError + status mention", () => {
+		const err = wrapNeonError(
+			axiosLike(503, { message: "service unavailable" }),
+			CTX,
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.ServerError);
+		expect(p.message).toContain("HTTP 503");
+		expect(p.message).toContain("https://neonstatus.com");
+	});
+
+	test("unknown 4xx falls back to ServerError with raw status", () => {
+		const err = wrapNeonError(
+			axiosLike(418, { message: "I'm a teapot" }),
+			CTX,
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.ServerError);
+		expect(p.message).toContain("HTTP 418");
+	});
+});
+
+describe("wrapNeonError — network errors", () => {
+	test.each([
+		["ECONNREFUSED", "Connection refused"],
+		["ETIMEDOUT", "Operation timed out"],
+		["ENOTFOUND", "DNS lookup failed"],
+		["ECONNABORTED", "Request aborted"],
+	])("%s → NetworkError with explanation", (code, message) => {
+		const err = wrapNeonError(
+			Object.assign(new Error(message), { code }),
+			CTX,
+		);
+		const p = err as PlatformError;
+		expect(p.code).toBe(ErrorCode.NetworkError);
+		expect(p.message).toContain("Could not reach the Neon API");
+		expect(p.message).toContain(message);
+	});
+});
+
+describe("wrapNeonError — passthrough", () => {
+	test("returns existing PlatformError unchanged (no double-wrapping)", () => {
+		const original = new PlatformError(ErrorCode.InternalError, "test");
+		expect(wrapNeonError(original, CTX)).toBe(original);
+	});
+
+	test("returns non-axios, non-network errors unchanged", () => {
+		const original = new Error("plain error");
+		expect(wrapNeonError(original, CTX)).toBe(original);
+	});
+});

package/src/lib/wrap-neon-error.ts

@@ -0,0 +1,204 @@
+import { ErrorCode, PlatformError } from "./errors.js";
+
+/**
+ * Context the wrapper attaches to every PlatformError so consumers can debug without
+ * digging into the raw axios stack.
+ */
+export 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).
+ */
+export function wrapNeonError(
+	err: unknown,
+	context: NeonErrorContext,
+): PlatformError | unknown {
+	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) },
+		);
+	}
+
+	// 4xx we don't have a dedicated code for. Surface what we know.
+	return new PlatformError(
+		ErrorCode.ServerError,
+		`${context.op} failed: HTTP ${httpInfo.status}. ${apiSummary}${requestIdSuffix}.`,
+		{ cause: err, details: httpDetails(context, httpInfo) },
+	);
+}
+
+interface HttpInfo {
+	status: number;
+	neonMessage?: string;
+	neonCode?: string;
+	requestId?: string;
+}
+
+function extractHttpInfo(err: unknown): HttpInfo | null {
+	if (err === null || typeof err !== "object") return null;
+	const response = (err as { response?: unknown }).response;
+	if (response === null || typeof response !== "object") return null;
+	const status = (response as { status?: unknown }).status;
+	if (typeof status !== "number") return null;
+	const data = (response as { data?: unknown }).data;
+	const out: HttpInfo = { status };
+	if (data !== null && typeof data === "object") {
+		const dataObj = data as Record<string, unknown>;
+		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;
+}
+
+interface NetworkInfo {
+	message: string;
+	code?: string;
+}
+
+function extractNetworkInfo(err: unknown): NetworkInfo | null {
+	if (err === null || typeof err !== "object") return null;
+	const code = (err as { code?: unknown }).code;
+	const message = (err as { message?: unknown }).message;
+	if (
+		typeof code === "string" &&
+		/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EPIPE|EHOSTUNREACH|ENETUNREACH)$/.test(
+			code,
+		)
+	) {
+		return { message: typeof message === "string" ? message : code, code };
+	}
+	// axios timeout reports `code: "ECONNABORTED"`.
+	if (code === "ECONNABORTED") {
+		return {
+			message: typeof message === "string" ? message : "timeout",
+			code,
+		};
+	}
+	return null;
+}
+
+function httpDetails(
+	context: NeonErrorContext,
+	info: HttpInfo,
+): Record<string, unknown> {
+	const out: Record<string, unknown> = {
+		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;
+}

package/src/v1.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import {
+	createRealNeonApi,
+	defineConfig,
+	diffConfig,
+	loadConfigFromFile,
+	resolveConfig,
+} from "./v1.js";
+
+describe("v1 surface", () => {
+	test("exports the authoring helpers, pure diff engine, adapter, and loader", () => {
+		const config = defineConfig((branch) => ({
+			parent: branch.name === "main" ? undefined : "main",
+		}));
+		expect(config({ name: "dev", exists: false })).toEqual({
+			parent: "main",
+		});
+		// Authoring + pure core stays in @neondatabase/config.
+		expect(resolveConfig).toBeTypeOf("function");
+		expect(diffConfig).toBeTypeOf("function");
+		expect(createRealNeonApi).toBeTypeOf("function");
+		expect(loadConfigFromFile).toBeTypeOf("function");
+	});
+
+	test("does not export the imperative operations (they live in @neondatabase/config-runtime)", async () => {
+		const surface = await import("./v1.js");
+		expect("apply" in surface).toBe(false);
+		expect("plan" in surface).toBe(false);
+		expect("inspect" in surface).toBe(false);
+		expect("pushConfig" in surface).toBe(false);
+		expect("pullConfig" in surface).toBe(false);
+	});
+});

package/src/v1.ts

@@ -0,0 +1,148 @@
+/**
+ * `@neondatabase/config/v1` — the v1 public API for Config-as-Code on the Neon Platform.
+ *
+ * Usage in `neon.ts`:
+ * ```ts
+ * import { defineConfig } from "@neondatabase/config/v1";
+ *
+ * export default defineConfig((branch) => {
+ *   if (branch.name === "main") return { protected: true, auth: {} };
+ *   return { parent: "main", ttl: "7d" };
+ * });
+ * ```
+ *
+ * This is the **authoring** surface — `defineConfig`, types, schemas, the pure diff engine,
+ * and the Neon API adapter. It is intentionally free of heavy/native dependencies so that
+ * importing it from `neon.ts` stays cheap and bundler-safe.
+ *
+ * The imperative operations (`inspect` / `plan` / `apply`, `pushConfig` / `pullConfig`) and
+ * function bundling/deploy live in **`@neondatabase/config-runtime`**, which depends on this
+ * package and pulls in `esbuild`. Import that from your CLI / CI, not from `neon.ts`:
+ * ```ts
+ * import config from "../neon";
+ * import { inspect, plan, apply } from "@neondatabase/config-runtime/v1";
+ * ```
+ *
+ * Surface guidelines:
+ * - Top-level: `defineConfig` / `resolveConfig`, the pure `diffConfig` engine, the
+ *   `createRealNeonApi` adapter + `NeonApi` types, the config loader, the `PlatformError`
+ *   base class + `ErrorCode` enum, and the config types used in `neon.ts`.
+ * - `errors` namespace: specific `PlatformError` subclasses (`ConfigLoadError`,
+ *   `PushConflictError`, …).
+ * - `schemas` namespace: the zod schemas underlying `defineConfig`.
+ */
+
+import {
+	ConfigLoadError,
+	ConfigValidationError,
+	ErrorCode,
+	MissingContextError,
+	PlatformError,
+	PushAbortedError,
+	PushConflictError,
+} from "./lib/errors.js";
+import {
+	branchConfigSchema,
+	bucketConfigSchema,
+	computeSettingsSchema,
+	configSchema,
+	functionConfigSchema,
+	postgresConfigSchema,
+	previewConfigSchema,
+	serviceToggleSchema,
+} from "./lib/schema.js";
+
+/**
+ * Specific `PlatformError` subclasses, grouped for `instanceof` / structured access.
+ * Also available as top-level exports.
+ */
+export const errors = {
+	ConfigLoadError,
+	ConfigValidationError,
+	ErrorCode,
+	MissingContextError,
+	PlatformError,
+	PushAbortedError,
+	PushConflictError,
+} as const;
+
+/** The zod schemas underlying `defineConfig`, grouped under product-friendly names. */
+export const schemas = {
+	branch: branchConfigSchema,
+	bucket: bucketConfigSchema,
+	computeSettings: computeSettingsSchema,
+	config: configSchema,
+	function: functionConfigSchema,
+	postgres: postgresConfigSchema,
+	preview: previewConfigSchema,
+	service: serviceToggleSchema,
+} as const;
+
+// ─── Lower-level adapters ──────────────────────────────────────────────────────
+export { createNeonApiFromOptions, resolveApiKey } from "./lib/auth.js";
+export { defineConfig, resolveConfig } from "./lib/define-config.js";
+// ─── Diff engine (pure; consumed by @neondatabase/config-runtime) ─────────────
+export type {
+	DiffOptions,
+	DiffResult,
+	PlanStep,
+	RemotePreviewState,
+	RemoteServiceState,
+	RemoteState,
+} from "./lib/diff.js";
+export { diffConfig } from "./lib/diff.js";
+// ─── Errors ────────────────────────────────────────────────────────────────────
+export {
+	ConfigLoadError,
+	ConfigValidationError,
+	ErrorCode,
+	MissingContextError,
+	PlatformError,
+	PushAbortedError,
+	PushConflictError,
+} from "./lib/errors.js";
+export type { LoadConfigOptions } from "./lib/loader.js";
+export { loadConfigFromFile } from "./lib/loader.js";
+// ─── NeonApi types (needed by callers implementing their own adapters) ────────
+export type {
+	CreateBranchInput,
+	CreateBucketInput,
+	CreateProjectInput,
+	DeployFunctionInput,
+	GetConnectionUriInput,
+	NeonApi,
+	NeonAuthSnapshot,
+	NeonBranchSnapshot,
+	NeonBucketSnapshot,
+	NeonDataApiSnapshot,
+	NeonDatabaseSnapshot,
+	NeonEndpointSnapshot,
+	NeonFunctionDeploymentSnapshot,
+	NeonFunctionSnapshot,
+	NeonProjectSnapshot,
+	NeonRoleSnapshot,
+	UpdateBranchInput,
+} from "./lib/neon-api.js";
+export { createRealNeonApi } from "./lib/neon-api-real.js";
+// ─── Config types (used in neon.ts and in operation return values) ────────────
+export type {
+	AppliedChange,
+	BranchConfig,
+	BranchTarget,
+	BucketAccessLevel,
+	BucketConfig,
+	ComputeSettings,
+	Config,
+	ConflictReport,
+	FunctionConfig,
+	FunctionMemoryMib,
+	FunctionRuntime,
+	PostgresConfig,
+	PreviewConfig,
+	PushResult,
+	ResolvedBranchConfig,
+	ResolvedBucketConfig,
+	ResolvedFunctionConfig,
+	ResolvedPreviewConfig,
+	ServiceToggle,
+} from "./lib/types.js";

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"include": ["src", "e2e", "vitest.config.ts", "vitest.e2e.config.ts", "tsdown.config.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	name: "@neondatabase/config",
+	bundle: false,
+	clean: true,
+	dts: true,
+	entry: [
+		"src/index.ts",
+		"src/v1.ts",
+		"src/lib/**/*.ts",
+		"!src/**/*.test.*",
+		"!src/lib/fake-neon-api.ts",
+		"!src/lib/test-utils.ts",
+	],
+	format: "esm",
+	outDir: "dist",
+	treeshake: true,
+});

package/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		clearMocks: true,
+		mockReset: true,
+		unstubEnvs: true,
+		coverage: {
+			all: true,
+			include: ["src"],
+			exclude: ["src/**/*.test.ts", "src/lib/fake-neon-api.ts"],
+			reporter: ["html", "lcov"],
+		},
+		// Skip e2e tests (which talk to the real Neon API) in the standard suite — they
+		// run via `pnpm test:e2e` against `vitest.e2e.config.ts`.
+		exclude: ["lib", "node_modules", "dist", "**/*.e2e.test.ts", "e2e/**"],
+		setupFiles: ["console-fail-test/setup"],
+	},
+});

package/vitest.e2e.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Vitest config for end-to-end tests that hit the **real** Neon API.
+ *
+ * - Matches `**\/*.e2e.test.ts` only — the standard `test:ci` config explicitly excludes
+ *   this pattern so the two suites never collide.
+ * - Uses long per-test timeouts because real project creation / deletion can take 10+s.
+ * - Forces single-threaded execution to avoid quota / rate-limit interference between
+ *   tests (`pool: "forks"` with `singleFork: true`).
+ * - Loads `.env` via Vitest's built-in dotenv support so `NEON_API_KEY` (and optionally
+ *   `NEON_ORG_ID`) become `process.env` entries inside the tests.
+ */
+export default defineConfig({
+	test: {
+		include: ["src/**/*.e2e.test.ts", "e2e/**/*.test.ts"],
+		exclude: ["node_modules", "dist"],
+		setupFiles: ["./e2e/load-env.ts", "./e2e/setup.ts"],
+		testTimeout: 120_000,
+		hookTimeout: 120_000,
+		pool: "forks",
+		poolOptions: {
+			forks: {
+				singleFork: true,
+			},
+		},
+		reporters: ["verbose"],
+	},
+});