@neon/config 0.0.0 → 0.8.1

package/dist/lib/errors.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../../src/lib/errors.ts"],"mappings":";;;;;;AAuBA;AAsBA;;;;AAAiE;AAYjE;;;;;;AAAwC;AAyBxC;AAaA;AAUA;AAoBA;AAeA;;AAE8B,cAvHjB,SAuHiB,EAAA;WAEG,aAAA,EAAA,yBAAA;WAJM,cAAA,EAAA,2BAAA;EAAa,SAAA,cAAA,EAAA,0BAAA;EAqDvC,SAAA,YAAiB,EAAA,wBAAqB;EA8BtC,SAAA,WAAgB,EAAA,uBAAqB;;;;;;;;;;;;;;;;;KAlLtC,SAAA,WAAoB,wBAAwB;;;;;;;;;cAY3C,aAAA,SAAsB,KAAA;;;oBAGhB,SAAS;;;cAKa;;;;;;;;;;;;iBAiBzB,eAAA,2BAA0C;;;;;;iBAa1C,eAAA,CAAA;;;;;;;cAUH,qBAAA,SAA8B,aAAa;;;;;;;;;;;;cAoB3C,mBAAA,SAA4B,aAAa;;;;;;;;;;;cAezC,iBAAA,SAA0B,aAAA;;+BAET;kCAEG;;;;;;;;;cAiDpB,gBAAA,SAAyB,aAAa;;;;;;;;;cA8BtC,eAAA,SAAwB,aAAa"}

package/dist/lib/errors.js

@@ -0,0 +1,185 @@
+//#region src/lib/errors.ts
+/**
+* Every code a {@link PlatformError} can carry. Stable identifiers — consumers can rely on
+* these for `instanceof PlatformError && err.code === ErrorCode.…` style checks instead of
+* matching on free-text messages.
+*
+* Grouped by source:
+* - `PLATFORM_INVALID_CONFIG` — `defineConfig` / `configSchema` rejected the input.
+* - `PLATFORM_MISSING_CONTEXT` — no project / branch context could be resolved.
+* - `PLATFORM_PUSH_CONFLICT` — local config conflicts with remote and the caller did not
+*   opt in to apply.
+* - `PLATFORM_CONFIG_LOAD_FAILED` — `neon.ts` could not be found or evaluated.
+* - `PLATFORM_MISSING_API_KEY` — no `NEON_API_KEY` and no explicit `apiKey` was provided.
+* - `PLATFORM_MISSING_PARENT_BRANCH` — push tried to create a child of a non-existent
+*   branch.
+* - `PLATFORM_UNAUTHORIZED` / `PLATFORM_FORBIDDEN` / `PLATFORM_NOT_FOUND` /
+*   `PLATFORM_CONFLICT` / `PLATFORM_RATE_LIMITED` / `PLATFORM_LOCKED` /
+*   `PLATFORM_SERVER_ERROR` — wrappings of Neon HTTP failures.
+* - `PLATFORM_NETWORK_ERROR` — transport-level failure (no HTTP response at all).
+* - `PLATFORM_INTERNAL_ERROR` — invariant violations. Should never happen in production;
+*   if you see one, please open an issue.
+*/
+const ErrorCode = {
+	InvalidConfig: "PLATFORM_INVALID_CONFIG",
+	EnvNotInjected: "PLATFORM_ENV_NOT_INJECTED",
+	MissingContext: "PLATFORM_MISSING_CONTEXT",
+	PushConflict: "PLATFORM_PUSH_CONFLICT",
+	PushAborted: "PLATFORM_PUSH_ABORTED",
+	ConfigLoadFailed: "PLATFORM_CONFIG_LOAD_FAILED",
+	MissingApiKey: "PLATFORM_MISSING_API_KEY",
+	AmbiguousBranchAuth: "PLATFORM_AMBIGUOUS_BRANCH_AUTH",
+	BranchNotFound: "PLATFORM_BRANCH_NOT_FOUND",
+	FeatureUnavailable: "PLATFORM_FEATURE_UNAVAILABLE",
+	MissingParentBranch: "PLATFORM_MISSING_PARENT_BRANCH",
+	Unauthorized: "PLATFORM_UNAUTHORIZED",
+	Forbidden: "PLATFORM_FORBIDDEN",
+	NotFound: "PLATFORM_NOT_FOUND",
+	Conflict: "PLATFORM_CONFLICT",
+	RateLimited: "PLATFORM_RATE_LIMITED",
+	Locked: "PLATFORM_LOCKED",
+	ServerError: "PLATFORM_SERVER_ERROR",
+	NetworkError: "PLATFORM_NETWORK_ERROR",
+	InternalError: "PLATFORM_INTERNAL_ERROR"
+};
+const ISSUE_URL = "https://github.com/neondatabase/neon-pkgs/issues/new";
+/**
+* Base class for all errors thrown by `@neon/config`. Always extend this so callers
+* can catch every package-thrown error with a single `instanceof` check.
+*
+* Optional `details` carries structured context that the CLI prints under `--debug` and
+* that programmatic consumers can read (e.g. `details.status` for HTTP wrappings,
+* `details.requestId` for Neon API failures).
+*/
+var PlatformError = class extends Error {
+	name = "PlatformError";
+	code;
+	details;
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+		this.details = Object.freeze({ ...options?.details ?? {} });
+	}
+};
+/**
+* Structural check for a {@link PlatformError}.
+*
+* Prefer this over a bare `instanceof PlatformError` whenever the error may have crossed a
+* module-realm boundary. A `neon.ts` loaded through jiti imports its *own* copy of this
+* package, so a `PlatformError` thrown while evaluating it has a different class identity
+* than ours and fails `instanceof` — but its stable string `code` (always prefixed
+* `PLATFORM_`) survives the boundary intact, which is what we match on here.
+*/
+function isPlatformError(value) {
+	if (value instanceof PlatformError) return true;
+	if (typeof value !== "object" || value === null) return false;
+	if (!("code" in value)) return false;
+	const { code } = value;
+	return typeof code === "string" && code.startsWith("PLATFORM_");
+}
+/**
+* Append a "report-a-bug" footer to an error message. Used only on truly unreachable
+* internal errors — never on user-facing validation / configuration errors where the user
+* is supposed to fix something on their end.
+*/
+function bugReportFooter() {
+	return `\nThis indicates a bug in @neon/config. Please file an issue: ${ISSUE_URL}`;
+}
+/**
+* Thrown by {@link defineConfig} when the user-provided configuration object is invalid.
+*
+* The class collects every validation failure rather than throwing on the first one so that
+* users get a complete picture of what is wrong with their `neon.ts`.
+*/
+var ConfigValidationError = class extends PlatformError {
+	name = "ConfigValidationError";
+	issues;
+	constructor(issues) {
+		super("PLATFORM_INVALID_CONFIG", `Invalid Neon platform config:\n  - ${issues.join("\n  - ")}`);
+		this.issues = issues;
+	}
+};
+/**
+* Thrown when the package cannot resolve which Neon project to operate on.
+*
+* Per the package's read-only-filesystem contract, we never create a `.neon` context file;
+* callers must either pass `projectId`/`orgId` explicitly or rely on an existing context file
+* (`.neon/project.json` or neonctl's `.neon`).
+*/
+var MissingContextError = class extends PlatformError {
+	name = "MissingContextError";
+	constructor(message) {
+		super("PLATFORM_MISSING_CONTEXT", message);
+	}
+};
+/**
+* Thrown by {@link pushConfig} when it detects differences between the local config and
+* the remote project that the caller hasn't opted in to apply.
+*
+* The message lists every conflict with both the current and desired value plus a
+* per-conflict hint. Mutable branch drift is applied by passing `updateExisting: true`.
+*/
+var PushConflictError = class extends PlatformError {
+	name = "PushConflictError";
+	conflicts;
+	constructor(conflicts) {
+		const lines = ["pushConfig refused to apply: local config conflicts with remote state.", ""];
+		for (const c of conflicts) lines.push(`  - [${c.kind}:${c.identifier}] ${c.field}: ${c.reason}`, `      current : ${formatValue(c.current)}`, `      desired : ${formatValue(c.desired)}`, `      fix     : ${suggestFix(c)}`);
+		const hasMutable = conflicts.some((c) => !isImmutableConflict(c));
+		lines.push("");
+		if (hasMutable) lines.push("For mutable conflicts, pass `updateExisting: true` (SDK) / `--update-existing` (CLI) to apply.");
+		super("PLATFORM_PUSH_CONFLICT", lines.join("\n"), { details: { conflicts: conflicts.map((c) => ({ ...c })) } });
+		this.conflicts = conflicts;
+	}
+};
+function isImmutableConflict(_c) {
+	return false;
+}
+function suggestFix(c) {
+	if (isImmutableConflict(c)) return "immutable on Neon — recreate the project, or change your `neon.ts` to match the remote.";
+	if (c.kind === "branch" && c.field === "parent") return "create the parent branch on Neon first, or change the `parent` reference to an existing branch.";
+	return "pass `updateExisting: true` (SDK) / `--update-existing` (CLI) to apply.";
+}
+/**
+* Thrown by {@link pushConfig} when the caller-supplied `confirm` callback declines a
+* push that requires confirmation (protected branch and/or mutable drift overriding
+* existing remote settings).
+*
+* The CLI maps this to a non-zero exit so users see "aborted" rather than a stack trace.
+*/
+var PushAbortedError = class extends PlatformError {
+	name = "PushAbortedError";
+	branchName;
+	reasons;
+	constructor(branchName, reasons) {
+		super("PLATFORM_PUSH_ABORTED", [
+			`Aborted push to branch ${JSON.stringify(branchName)}.`,
+			reasons.length > 0 ? `Reason${reasons.length === 1 ? "" : "s"}: ${reasons.join(", ")}.` : void 0,
+			"Re-run with `--update-existing` (override existing settings) or `--allow-protected-branch` (push to a protected branch) to skip the prompt."
+		].filter(Boolean).join(" "), { details: {
+			branchName,
+			reasons: [...reasons]
+		} });
+		this.branchName = branchName;
+		this.reasons = reasons;
+	}
+};
+/**
+* Thrown when the SDK fails to find or load a `neon.ts` config file.
+*/
+var ConfigLoadError = class extends PlatformError {
+	name = "ConfigLoadError";
+	constructor(message, options) {
+		super("PLATFORM_CONFIG_LOAD_FAILED", message, options);
+	}
+};
+function formatValue(value) {
+	if (value === void 0) return "<unset>";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "object" && value !== null) return JSON.stringify(value);
+	return String(value);
+}
+//#endregion
+export { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PlatformError, PushAbortedError, PushConflictError, bugReportFooter, isPlatformError };
+
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/lib/errors.ts"],"sourcesContent":["import type { ConflictReport } from \"./types.js\";\n\n/**\n * Every code a {@link PlatformError} can carry. Stable identifiers — consumers can rely on\n * these for `instanceof PlatformError && err.code === ErrorCode.…` style checks instead of\n * matching on free-text messages.\n *\n * Grouped by source:\n * - `PLATFORM_INVALID_CONFIG` — `defineConfig` / `configSchema` rejected the input.\n * - `PLATFORM_MISSING_CONTEXT` — no project / branch context could be resolved.\n * - `PLATFORM_PUSH_CONFLICT` — local config conflicts with remote and the caller did not\n *   opt in to apply.\n * - `PLATFORM_CONFIG_LOAD_FAILED` — `neon.ts` could not be found or evaluated.\n * - `PLATFORM_MISSING_API_KEY` — no `NEON_API_KEY` and no explicit `apiKey` was provided.\n * - `PLATFORM_MISSING_PARENT_BRANCH` — push tried to create a child of a non-existent\n *   branch.\n * - `PLATFORM_UNAUTHORIZED` / `PLATFORM_FORBIDDEN` / `PLATFORM_NOT_FOUND` /\n *   `PLATFORM_CONFLICT` / `PLATFORM_RATE_LIMITED` / `PLATFORM_LOCKED` /\n *   `PLATFORM_SERVER_ERROR` — wrappings of Neon HTTP failures.\n * - `PLATFORM_NETWORK_ERROR` — transport-level failure (no HTTP response at all).\n * - `PLATFORM_INTERNAL_ERROR` — invariant violations. Should never happen in production;\n *   if you see one, please open an issue.\n */\nexport const ErrorCode = {\n\tInvalidConfig: \"PLATFORM_INVALID_CONFIG\",\n\tEnvNotInjected: \"PLATFORM_ENV_NOT_INJECTED\",\n\tMissingContext: \"PLATFORM_MISSING_CONTEXT\",\n\tPushConflict: \"PLATFORM_PUSH_CONFLICT\",\n\tPushAborted: \"PLATFORM_PUSH_ABORTED\",\n\tConfigLoadFailed: \"PLATFORM_CONFIG_LOAD_FAILED\",\n\tMissingApiKey: \"PLATFORM_MISSING_API_KEY\",\n\tAmbiguousBranchAuth: \"PLATFORM_AMBIGUOUS_BRANCH_AUTH\",\n\tBranchNotFound: \"PLATFORM_BRANCH_NOT_FOUND\",\n\tFeatureUnavailable: \"PLATFORM_FEATURE_UNAVAILABLE\",\n\tMissingParentBranch: \"PLATFORM_MISSING_PARENT_BRANCH\",\n\tUnauthorized: \"PLATFORM_UNAUTHORIZED\",\n\tForbidden: \"PLATFORM_FORBIDDEN\",\n\tNotFound: \"PLATFORM_NOT_FOUND\",\n\tConflict: \"PLATFORM_CONFLICT\",\n\tRateLimited: \"PLATFORM_RATE_LIMITED\",\n\tLocked: \"PLATFORM_LOCKED\",\n\tServerError: \"PLATFORM_SERVER_ERROR\",\n\tNetworkError: \"PLATFORM_NETWORK_ERROR\",\n\tInternalError: \"PLATFORM_INTERNAL_ERROR\",\n} as const;\nexport type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];\n\nconst ISSUE_URL = \"https://github.com/neondatabase/neon-pkgs/issues/new\";\n\n/**\n * Base class for all errors thrown by `@neon/config`. Always extend this so callers\n * can catch every package-thrown error with a single `instanceof` check.\n *\n * Optional `details` carries structured context that the CLI prints under `--debug` and\n * that programmatic consumers can read (e.g. `details.status` for HTTP wrappings,\n * `details.requestId` for Neon API failures).\n */\nexport class PlatformError extends Error {\n\toverride readonly name: string = \"PlatformError\";\n\treadonly code: string;\n\treadonly details: Readonly<Record<string, unknown>>;\n\n\tconstructor(\n\t\tcode: string,\n\t\tmessage: string,\n\t\toptions?: { cause?: unknown; details?: Record<string, unknown> },\n\t) {\n\t\tsuper(message, options);\n\t\tthis.code = code;\n\t\tthis.details = Object.freeze({ ...(options?.details ?? {}) });\n\t}\n}\n\n/**\n * Structural check for a {@link PlatformError}.\n *\n * Prefer this over a bare `instanceof PlatformError` whenever the error may have crossed a\n * module-realm boundary. A `neon.ts` loaded through jiti imports its *own* copy of this\n * package, so a `PlatformError` thrown while evaluating it has a different class identity\n * than ours and fails `instanceof` — but its stable string `code` (always prefixed\n * `PLATFORM_`) survives the boundary intact, which is what we match on here.\n */\nexport function isPlatformError(value: unknown): value is PlatformError {\n\tif (value instanceof PlatformError) return true;\n\tif (typeof value !== \"object\" || value === null) return false;\n\tif (!(\"code\" in value)) return false;\n\tconst { code } = value;\n\treturn typeof code === \"string\" && code.startsWith(\"PLATFORM_\");\n}\n\n/**\n * Append a \"report-a-bug\" footer to an error message. Used only on truly unreachable\n * internal errors — never on user-facing validation / configuration errors where the user\n * is supposed to fix something on their end.\n */\nexport function bugReportFooter(): string {\n\treturn `\\nThis indicates a bug in @neon/config. Please file an issue: ${ISSUE_URL}`;\n}\n\n/**\n * Thrown by {@link defineConfig} when the user-provided configuration object is invalid.\n *\n * The class collects every validation failure rather than throwing on the first one so that\n * users get a complete picture of what is wrong with their `neon.ts`.\n */\nexport class ConfigValidationError extends PlatformError {\n\toverride readonly name = \"ConfigValidationError\";\n\treadonly issues: readonly string[];\n\n\tconstructor(issues: readonly string[]) {\n\t\tsuper(\n\t\t\t\"PLATFORM_INVALID_CONFIG\",\n\t\t\t`Invalid Neon platform config:\\n  - ${issues.join(\"\\n  - \")}`,\n\t\t);\n\t\tthis.issues = issues;\n\t}\n}\n\n/**\n * Thrown when the package cannot resolve which Neon project to operate on.\n *\n * Per the package's read-only-filesystem contract, we never create a `.neon` context file;\n * callers must either pass `projectId`/`orgId` explicitly or rely on an existing context file\n * (`.neon/project.json` or neonctl's `.neon`).\n */\nexport class MissingContextError extends PlatformError {\n\toverride readonly name = \"MissingContextError\";\n\n\tconstructor(message: string) {\n\t\tsuper(\"PLATFORM_MISSING_CONTEXT\", message);\n\t}\n}\n\n/**\n * Thrown by {@link pushConfig} when it detects differences between the local config and\n * the remote project that the caller hasn't opted in to apply.\n *\n * The message lists every conflict with both the current and desired value plus a\n * per-conflict hint. Mutable branch drift is applied by passing `updateExisting: true`.\n */\nexport class PushConflictError extends PlatformError {\n\toverride readonly name = \"PushConflictError\";\n\treadonly conflicts: readonly ConflictReport[];\n\n\tconstructor(conflicts: readonly ConflictReport[]) {\n\t\tconst lines: string[] = [\n\t\t\t\"pushConfig refused to apply: local config conflicts with remote state.\",\n\t\t\t\"\",\n\t\t];\n\t\tfor (const c of conflicts) {\n\t\t\tlines.push(\n\t\t\t\t`  - [${c.kind}:${c.identifier}] ${c.field}: ${c.reason}`,\n\t\t\t\t`      current : ${formatValue(c.current)}`,\n\t\t\t\t`      desired : ${formatValue(c.desired)}`,\n\t\t\t\t`      fix     : ${suggestFix(c)}`,\n\t\t\t);\n\t\t}\n\t\tconst hasMutable = conflicts.some((c) => !isImmutableConflict(c));\n\t\tlines.push(\"\");\n\t\tif (hasMutable) {\n\t\t\tlines.push(\n\t\t\t\t\"For mutable conflicts, pass `updateExisting: true` (SDK) / `--update-existing` (CLI) to apply.\",\n\t\t\t);\n\t\t}\n\n\t\tsuper(\"PLATFORM_PUSH_CONFLICT\", lines.join(\"\\n\"), {\n\t\t\tdetails: { conflicts: conflicts.map((c) => ({ ...c })) },\n\t\t});\n\t\tthis.conflicts = conflicts;\n\t}\n}\n\nfunction isImmutableConflict(_c: ConflictReport): boolean {\n\treturn false;\n}\n\nfunction suggestFix(c: ConflictReport): string {\n\tif (isImmutableConflict(c)) {\n\t\treturn \"immutable on Neon — recreate the project, or change your `neon.ts` to match the remote.\";\n\t}\n\tif (c.kind === \"branch\" && c.field === \"parent\") {\n\t\treturn \"create the parent branch on Neon first, or change the `parent` reference to an existing branch.\";\n\t}\n\treturn \"pass `updateExisting: true` (SDK) / `--update-existing` (CLI) to apply.\";\n}\n\n/**\n * Thrown by {@link pushConfig} when the caller-supplied `confirm` callback declines a\n * push that requires confirmation (protected branch and/or mutable drift overriding\n * existing remote settings).\n *\n * The CLI maps this to a non-zero exit so users see \"aborted\" rather than a stack trace.\n */\nexport class PushAbortedError extends PlatformError {\n\toverride readonly name = \"PushAbortedError\";\n\treadonly branchName: string;\n\treadonly reasons: readonly (\"protected-branch\" | \"override-updates\")[];\n\n\tconstructor(\n\t\tbranchName: string,\n\t\treasons: readonly (\"protected-branch\" | \"override-updates\")[],\n\t) {\n\t\tsuper(\n\t\t\t\"PLATFORM_PUSH_ABORTED\",\n\t\t\t[\n\t\t\t\t`Aborted push to branch ${JSON.stringify(branchName)}.`,\n\t\t\t\treasons.length > 0\n\t\t\t\t\t? `Reason${reasons.length === 1 ? \"\" : \"s\"}: ${reasons.join(\", \")}.`\n\t\t\t\t\t: undefined,\n\t\t\t\t\"Re-run with `--update-existing` (override existing settings) or `--allow-protected-branch` (push to a protected branch) to skip the prompt.\",\n\t\t\t]\n\t\t\t\t.filter(Boolean)\n\t\t\t\t.join(\" \"),\n\t\t\t{ details: { branchName, reasons: [...reasons] } },\n\t\t);\n\t\tthis.branchName = branchName;\n\t\tthis.reasons = reasons;\n\t}\n}\n\n/**\n * Thrown when the SDK fails to find or load a `neon.ts` config file.\n */\nexport class ConfigLoadError extends PlatformError {\n\toverride readonly name = \"ConfigLoadError\";\n\n\tconstructor(message: string, options?: { cause?: unknown }) {\n\t\tsuper(\"PLATFORM_CONFIG_LOAD_FAILED\", message, options);\n\t}\n}\n\nfunction formatValue(value: unknown): string {\n\tif (value === undefined) return \"<unset>\";\n\tif (typeof value === \"string\") return JSON.stringify(value);\n\tif (typeof value === \"object\" && value !== null)\n\t\treturn JSON.stringify(value);\n\treturn String(value);\n}\n"],"mappings":"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"}

package/dist/lib/loader.d.ts

@@ -0,0 +1,44 @@
+import { Config } from "./types.js";
+
+//#region src/lib/loader.d.ts
+
+/**
+ * Default file names tried (in order) when {@link loadConfigFromFile} is called without an
+ * explicit path. We accept `.ts` first because that's the documented format; `.mjs` and `.js`
+ * fall out for free since jiti handles all of them.
+ */
+declare const DEFAULT_CONFIG_FILENAMES: readonly ["neon.ts", "neon.mts", "neon.js", "neon.mjs"];
+interface LoadConfigOptions {
+  /** Explicit absolute or cwd-relative path to a config file. Takes precedence over the search. */
+  path?: string;
+  /** Starting directory for the upward search. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /**
+   * Hard ceiling for the upward walk — once `current === stopAt` the search returns
+   * `null` even if no `.git` boundary was hit. Defaults to the OS home directory so
+   * stray runs from outside any repo never leak into the user's `~` files.
+   */
+  stopAt?: string;
+}
+/**
+ * Load a `neon.ts` (or any other supported extension) and return the validated {@link Config}.
+ *
+ * Behavior:
+ * - When `path` is set, that file is loaded directly. The file must exist and must default-export
+ *   a value produced by `defineConfig()`.
+ * - When `path` is omitted, we walk up from `cwd` picking the **closest** file matching
+ *   {@link DEFAULT_CONFIG_FILENAMES}. The walk is monorepo-friendly: intermediate
+ *   `package.json` files do **not** stop it, so a single `neon.ts` lifted to the workspace
+ *   root keeps working when invoked from inside any sub-package. The walk terminates at the
+ *   first directory containing `.git`, at `stopAt`, or at the filesystem root.
+ *
+ * jiti is loaded lazily so that callers who pass an already-resolved `Config` to `pushConfig`
+ * never pay the import cost.
+ */
+declare function loadConfigFromFile(options?: LoadConfigOptions): Promise<{
+  config: Config;
+  resolvedPath: string;
+}>;
+//#endregion
+export { DEFAULT_CONFIG_FILENAMES, LoadConfigOptions, loadConfigFromFile };
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","names":[],"sources":["../../src/lib/loader.ts"],"mappings":";;;;;;AAaA;AAOA;AA4BA;AAAwC,cAnC3B,wBAmC2B,EAAA,SAAA,CAAA,SAAA,EAAA,UAAA,EAAA,SAAA,EAAA,UAAA,CAAA;AAC9B,UA7BO,iBAAA,CA6BP;;MACP,CAAA,EAAA,MAAA;EAAO;;;;;;;;;;;;;;;;;;;;;;;;iBAFY,kBAAA,WACZ,oBACP;UACM"}

package/dist/lib/loader.js

@@ -0,0 +1,120 @@
+import { ConfigLoadError, isPlatformError } from "./errors.js";
+import { defineConfig } from "./define-config.js";
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { homedir } from "node:os";
+import { pathToFileURL } from "node:url";
+//#region src/lib/loader.ts
+/**
+* Default file names tried (in order) when {@link loadConfigFromFile} is called without an
+* explicit path. We accept `.ts` first because that's the documented format; `.mjs` and `.js`
+* fall out for free since jiti handles all of them.
+*/
+const DEFAULT_CONFIG_FILENAMES = [
+	"neon.ts",
+	"neon.mts",
+	"neon.js",
+	"neon.mjs"
+];
+/**
+* Load a `neon.ts` (or any other supported extension) and return the validated {@link Config}.
+*
+* Behavior:
+* - When `path` is set, that file is loaded directly. The file must exist and must default-export
+*   a value produced by `defineConfig()`.
+* - When `path` is omitted, we walk up from `cwd` picking the **closest** file matching
+*   {@link DEFAULT_CONFIG_FILENAMES}. The walk is monorepo-friendly: intermediate
+*   `package.json` files do **not** stop it, so a single `neon.ts` lifted to the workspace
+*   root keeps working when invoked from inside any sub-package. The walk terminates at the
+*   first directory containing `.git`, at `stopAt`, or at the filesystem root.
+*
+* jiti is loaded lazily so that callers who pass an already-resolved `Config` to `pushConfig`
+* never pay the import cost.
+*/
+async function loadConfigFromFile(options = {}) {
+	const resolvedPath = options.path ? resolveExplicitPath(options.path, options.cwd) : findDefaultConfig(options.cwd, options.stopAt);
+	if (!resolvedPath) throw new ConfigLoadError([
+		`Could not find a Neon config file while walking up from ${resolve(options.cwd ?? process.cwd())}.`,
+		`Looked for: ${DEFAULT_CONFIG_FILENAMES.join(", ")} (stopping at the first directory with a \`.git\`).`,
+		`Create one at your repository root (or anywhere on the path from cwd up to .git), or pass an explicit \`configPath\` (SDK) / \`--config <path>\` (CLI).`
+	].join("\n"));
+	let mod;
+	try {
+		mod = await importModule(resolvedPath);
+	} catch (cause) {
+		if (isPlatformError(cause)) throw cause;
+		throw new ConfigLoadError([
+			`Failed to evaluate ${resolvedPath}.`,
+			`Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,
+			"This is usually a TypeScript syntax error, a missing dependency, or a runtime exception inside the config file. Run the file directly (e.g. `npx tsx neon.ts`) to reproduce."
+		].join("\n"), { cause });
+	}
+	const exported = extractDefaultExport(mod);
+	if (exported === void 0) throw new ConfigLoadError([`${resolvedPath} loaded successfully but did not default-export a config.`, "Add `export default defineConfig({ ... })` at the bottom of the file. (Named exports are ignored.)"].join("\n"));
+	return {
+		config: defineConfig(exported),
+		resolvedPath
+	};
+}
+function resolveExplicitPath(input, cwd) {
+	const base = resolve(cwd ?? process.cwd());
+	const abs = isAbsolute(input) ? input : resolve(base, input);
+	if (!existsSync(abs)) throw new ConfigLoadError(`Config file not found at ${abs}. The path was resolved from \`${input}\` against ${base}.`);
+	if (!statSync(abs).isFile()) throw new ConfigLoadError(`Config path ${abs} is a directory, not a file. Pass a path to the file itself (e.g. ./neon.ts).`);
+	return abs;
+}
+function findDefaultConfig(cwd, stopAt) {
+	let current = resolve(cwd ?? process.cwd());
+	const stop = resolve(stopAt ?? homedir());
+	let lastSeen = null;
+	while (true) {
+		for (const name of DEFAULT_CONFIG_FILENAMES) {
+			const candidate = resolve(current, name);
+			if (existsSync(candidate) && safeIsFile(candidate)) return candidate;
+		}
+		if (existsSync(resolve(current, ".git"))) return null;
+		if (current === stop) return null;
+		const parent = dirname(current);
+		if (parent === current || parent === lastSeen) return null;
+		lastSeen = current;
+		current = parent;
+	}
+}
+async function importModule(absPath) {
+	const lower = absPath.toLowerCase();
+	if (!(lower.endsWith(".ts") || lower.endsWith(".mts") || lower.endsWith(".cts"))) return import(pathToFileURL(absPath).href);
+	const createJiti = extractCreateJiti(await import("jiti"));
+	if (!createJiti) throw new ConfigLoadError(["jiti is required to load TypeScript config files but could not be initialised.", "Reinstall the package dependencies (`pnpm install` / `npm install`) — jiti is a runtime dependency of @neon/config."].join(" "));
+	return createJiti(pathToFileURL(absPath).href, {
+		interopDefault: true,
+		moduleCache: false
+	}).import(absPath);
+}
+function extractCreateJiti(mod) {
+	if (mod === null || typeof mod !== "object") return null;
+	const obj = mod;
+	if (typeof obj.createJiti === "function") return obj.createJiti;
+	const def = obj.default;
+	if (def !== null && typeof def === "object") {
+		const defObj = def;
+		if (typeof defObj.createJiti === "function") return defObj.createJiti;
+	}
+	return null;
+}
+function extractDefaultExport(mod) {
+	if (mod === null || typeof mod !== "object") return mod;
+	const obj = mod;
+	if ("default" in obj && obj.default !== void 0) return obj.default;
+	if (typeof mod === "function") return mod;
+}
+function safeIsFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { DEFAULT_CONFIG_FILENAMES, loadConfigFromFile };
+
+//# sourceMappingURL=loader.js.map

package/dist/lib/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","names":[],"sources":["../../src/lib/loader.ts"],"sourcesContent":["import { existsSync, statSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { dirname, isAbsolute, resolve } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { defineConfig } from \"./define-config.js\";\nimport { ConfigLoadError, isPlatformError } from \"./errors.js\";\nimport type { Config } from \"./types.js\";\n\n/**\n * Default file names tried (in order) when {@link loadConfigFromFile} is called without an\n * explicit path. We accept `.ts` first because that's the documented format; `.mjs` and `.js`\n * fall out for free since jiti handles all of them.\n */\nexport const DEFAULT_CONFIG_FILENAMES = [\n\t\"neon.ts\",\n\t\"neon.mts\",\n\t\"neon.js\",\n\t\"neon.mjs\",\n] as const;\n\nexport interface LoadConfigOptions {\n\t/** Explicit absolute or cwd-relative path to a config file. Takes precedence over the search. */\n\tpath?: string;\n\t/** Starting directory for the upward search. Defaults to `process.cwd()`. */\n\tcwd?: string;\n\t/**\n\t * Hard ceiling for the upward walk — once `current === stopAt` the search returns\n\t * `null` even if no `.git` boundary was hit. Defaults to the OS home directory so\n\t * stray runs from outside any repo never leak into the user's `~` files.\n\t */\n\tstopAt?: string;\n}\n\n/**\n * Load a `neon.ts` (or any other supported extension) and return the validated {@link Config}.\n *\n * Behavior:\n * - When `path` is set, that file is loaded directly. The file must exist and must default-export\n *   a value produced by `defineConfig()`.\n * - When `path` is omitted, we walk up from `cwd` picking the **closest** file matching\n *   {@link DEFAULT_CONFIG_FILENAMES}. The walk is monorepo-friendly: intermediate\n *   `package.json` files do **not** stop it, so a single `neon.ts` lifted to the workspace\n *   root keeps working when invoked from inside any sub-package. The walk terminates at the\n *   first directory containing `.git`, at `stopAt`, or at the filesystem root.\n *\n * jiti is loaded lazily so that callers who pass an already-resolved `Config` to `pushConfig`\n * never pay the import cost.\n */\nexport async function loadConfigFromFile(\n\toptions: LoadConfigOptions = {},\n): Promise<{\n\tconfig: Config;\n\tresolvedPath: string;\n}> {\n\tconst resolvedPath = options.path\n\t\t? resolveExplicitPath(options.path, options.cwd)\n\t\t: findDefaultConfig(options.cwd, options.stopAt);\n\n\tif (!resolvedPath) {\n\t\tthrow new ConfigLoadError(\n\t\t\t[\n\t\t\t\t`Could not find a Neon config file while walking up from ${resolve(options.cwd ?? process.cwd())}.`,\n\t\t\t\t`Looked for: ${DEFAULT_CONFIG_FILENAMES.join(\", \")} (stopping at the first directory with a \\`.git\\`).`,\n\t\t\t\t`Create one at your repository root (or anywhere on the path from cwd up to .git), or pass an explicit \\`configPath\\` (SDK) / \\`--config <path>\\` (CLI).`,\n\t\t\t].join(\"\\n\"),\n\t\t);\n\t}\n\n\tlet mod: unknown;\n\ttry {\n\t\tmod = await importModule(resolvedPath);\n\t} catch (cause) {\n\t\t// `defineConfig()` runs at module-eval time, so a config the user got *wrong*\n\t\t// (a bad function slug, an unknown key, an invalid duration, …) throws a\n\t\t// PlatformError from inside this import. That error already pinpoints the exact\n\t\t// field and reason, so surface it verbatim — burying it under the generic\n\t\t// \"this is usually a TypeScript syntax error\" hint sent users hunting for a\n\t\t// syntax bug that isn't there. The hint is reserved for genuine evaluation\n\t\t// failures (syntax errors, missing deps, thrown runtime exceptions).\n\t\tif (isPlatformError(cause)) {\n\t\t\tthrow cause;\n\t\t}\n\t\tthrow new ConfigLoadError(\n\t\t\t[\n\t\t\t\t`Failed to evaluate ${resolvedPath}.`,\n\t\t\t\t`Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\t\t\"This is usually a TypeScript syntax error, a missing dependency, or a runtime exception inside the config file. Run the file directly (e.g. `npx tsx neon.ts`) to reproduce.\",\n\t\t\t].join(\"\\n\"),\n\t\t\t{ cause },\n\t\t);\n\t}\n\n\tconst exported = extractDefaultExport(mod);\n\tif (exported === undefined) {\n\t\tthrow new ConfigLoadError(\n\t\t\t[\n\t\t\t\t`${resolvedPath} loaded successfully but did not default-export a config.`,\n\t\t\t\t\"Add `export default defineConfig({ ... })` at the bottom of the file. (Named exports are ignored.)\",\n\t\t\t].join(\"\\n\"),\n\t\t);\n\t}\n\n\t// Run through defineConfig to validate any function the user might have constructed manually.\n\tconst config = defineConfig(exported as Config);\n\treturn { config, resolvedPath };\n}\n\nfunction resolveExplicitPath(input: string, cwd?: string): string {\n\tconst base = resolve(cwd ?? process.cwd());\n\tconst abs = isAbsolute(input) ? input : resolve(base, input);\n\tif (!existsSync(abs)) {\n\t\tthrow new ConfigLoadError(\n\t\t\t`Config file not found at ${abs}. The path was resolved from \\`${input}\\` against ${base}.`,\n\t\t);\n\t}\n\tconst s = statSync(abs);\n\tif (!s.isFile()) {\n\t\tthrow new ConfigLoadError(\n\t\t\t`Config path ${abs} is a directory, not a file. Pass a path to the file itself (e.g. ./neon.ts).`,\n\t\t);\n\t}\n\treturn abs;\n}\n\nfunction findDefaultConfig(\n\tcwd: string | undefined,\n\tstopAt: string | undefined,\n): string | null {\n\tlet current = resolve(cwd ?? process.cwd());\n\tconst stop = resolve(stopAt ?? homedir());\n\tlet lastSeen: string | null = null;\n\n\twhile (true) {\n\t\tfor (const name of DEFAULT_CONFIG_FILENAMES) {\n\t\t\tconst candidate = resolve(current, name);\n\t\t\tif (existsSync(candidate) && safeIsFile(candidate))\n\t\t\t\treturn candidate;\n\t\t}\n\n\t\t// `.git` is the canonical repo-root marker. `package.json` is deliberately *not*\n\t\t// a stop: monorepos lift `neon.ts` above sub-package package.jsons.\n\t\tif (existsSync(resolve(current, \".git\"))) return null;\n\t\tif (current === stop) return null;\n\n\t\tconst parent = dirname(current);\n\t\tif (parent === current || parent === lastSeen) return null;\n\t\tlastSeen = current;\n\t\tcurrent = parent;\n\t}\n}\n\nasync function importModule(absPath: string): Promise<unknown> {\n\tconst lower = absPath.toLowerCase();\n\tconst needsJiti =\n\t\tlower.endsWith(\".ts\") ||\n\t\tlower.endsWith(\".mts\") ||\n\t\tlower.endsWith(\".cts\");\n\n\tif (!needsJiti) {\n\t\treturn import(pathToFileURL(absPath).href);\n\t}\n\n\tconst jitiModule: unknown = await import(\"jiti\");\n\tconst createJiti = extractCreateJiti(jitiModule);\n\tif (!createJiti) {\n\t\tthrow new ConfigLoadError(\n\t\t\t[\n\t\t\t\t\"jiti is required to load TypeScript config files but could not be initialised.\",\n\t\t\t\t\"Reinstall the package dependencies (`pnpm install` / `npm install`) — jiti is a runtime dependency of @neon/config.\",\n\t\t\t].join(\" \"),\n\t\t);\n\t}\n\tconst jiti = createJiti(pathToFileURL(absPath).href, {\n\t\tinteropDefault: true,\n\t\tmoduleCache: false,\n\t});\n\treturn jiti.import(absPath);\n}\n\nfunction extractCreateJiti(\n\tmod: unknown,\n): ((id: string, options?: unknown) => JitiInstance) | null {\n\tif (mod === null || typeof mod !== \"object\") return null;\n\tconst obj = mod as Record<string, unknown>;\n\tif (typeof obj.createJiti === \"function\") {\n\t\treturn obj.createJiti as (\n\t\t\tid: string,\n\t\t\toptions?: unknown,\n\t\t) => JitiInstance;\n\t}\n\tconst def = obj.default;\n\tif (def !== null && typeof def === \"object\") {\n\t\tconst defObj = def as Record<string, unknown>;\n\t\tif (typeof defObj.createJiti === \"function\") {\n\t\t\treturn defObj.createJiti as (\n\t\t\t\tid: string,\n\t\t\t\toptions?: unknown,\n\t\t\t) => JitiInstance;\n\t\t}\n\t}\n\treturn null;\n}\n\ninterface JitiInstance {\n\timport(id: string): Promise<unknown>;\n}\n\nfunction extractDefaultExport(mod: unknown): unknown {\n\tif (mod === null || typeof mod !== \"object\") return mod;\n\tconst obj = mod as Record<string, unknown>;\n\tif (\"default\" in obj && obj.default !== undefined) return obj.default;\n\t// No `default` export. If the module itself is a function, treat it as the config —\n\t// that lets tests and advanced users skip the wrapper.\n\t// Otherwise, return `undefined` so the caller surfaces a clear ConfigLoadError.\n\tif (typeof mod === \"function\") return mod;\n\treturn undefined;\n}\n\nfunction safeIsFile(path: string): boolean {\n\ttry {\n\t\treturn statSync(path).isFile();\n\t} catch {\n\t\treturn false;\n\t}\n}\n"],"mappings":"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"}

package/dist/lib/neon-api-real.d.ts

@@ -0,0 +1,92 @@
+import { DeployFunctionInput, NeonApi } from "./neon-api.js";
+
+//#region src/lib/neon-api-real.d.ts
+interface CreateNeonAuthRestInput {
+  auth_provider: "better_auth";
+  database_name?: string;
+}
+/**
+ * Adapt `@neon/sdk` (raw layer) to the narrow {@link NeonApi} façade used by the rest of
+ * this package. Constructs are restricted to whole-object read/write of just the fields we
+ * model in {@link Config}; anything else stays untouched on the remote.
+ */
+declare function createRealNeonApi(options: {
+  apiKey: string;
+  baseUrl?: string;
+  /**
+   * Tuning knob for the built-in 423 retry. Defaults: ~30s of total wait spread across
+   * 12 attempts with exponential backoff capped at 5s. Lowering this is mostly useful in
+   * tests; raising it is rarely needed because Neon operations are usually sub-second.
+   */
+  retryOnLocked?: {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  };
+}): NeonApi;
+interface RetryConfig {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+}
+/**
+ * Retry a function whenever it throws an HTTP 423 (Locked) — Neon's signal that a prior
+ * mutation on the same resource is still in flight. Uses exponential backoff capped at
+ * `maxDelayMs`. Any other error (and the last attempt) propagates.
+ *
+ * Exported only for tests; production callers go through the wrapped {@link NeonApi}.
+ */
+declare function retryOnLocked<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
+/**
+ * Whether an error from a Preview-feature read means the feature simply isn't available
+ * for this project/branch/region (as opposed to a real, transient failure). Neon signals
+ * this a few ways: a 404 "this route does not exist" (the route isn't deployed at all), or
+ * a 503/4xx whose message says the platform feature is "not available" / "not enabled".
+ *
+ * Callers do **not** swallow this into an empty result — touching a Preview feature that
+ * isn't available is surfaced as a {@link previewUnavailableError} so `plan` / `status` /
+ * `pull` (and `neon dev`) fail clearly instead of, say, planning to create resources the
+ * API will refuse to create.
+ */
+declare function isPreviewFeatureUnavailable(err: unknown): boolean;
+/**
+ * Convert a Preview-feature error into a clear {@link PlatformError} when the feature is
+ * unavailable for the project; otherwise pass the original error through unchanged so a
+ * genuine failure (auth, transient 5xx, …) keeps its specific code and message.
+ *
+ * The message names the failing feature, summarizes the response in one short
+ * `HTTP <status> <reason>` line, includes the raw Neon API message + request id (valuable
+ * signal while the feature is in preview), gives status-specific guidance (see
+ * {@link previewUnavailableHint}), and offers removing the feature from the policy as an
+ * escape hatch. `status`/`requestId` are also kept on `details` for programmatic consumers.
+ */
+declare function previewUnavailableError(err: unknown, featureLabel: string): unknown;
+declare function createNeonAuthRestInput(input: {
+  databaseName?: string;
+}): CreateNeonAuthRestInput;
+/**
+ * Build the `multipart/form-data` body for a function deployment, matching the public
+ * `FunctionDeployRequest` schema (`POST .../functions/{slug}/deployments`):
+ *
+ * - `zip` — the bundle as a binary part (named `bundle.zip`).
+ * - `runtime` — the function runtime.
+ * - `environment` — a single JSON-encoded string→string map (multipart can't carry a typed
+ *   object part), omitted entirely when there are no env vars.
+ *
+ * Pure (no I/O) so it can be unit-tested against the spec without stubbing `fetch`.
+ */
+declare function buildFunctionDeployForm(input: DeployFunctionInput): FormData;
+/**
+ * Read a response body as JSON, tolerating non-JSON. Some Neon routes return a plain-text
+ * body (e.g. a 404 `"this route does not exist"` for a Preview feature not enabled in the
+ * project/region). Parsing that with `JSON.parse` used to throw a cryptic
+ * `SyntaxError: Unexpected token …`, which — because parsing happens before the `res.ok`
+ * check in {@link request} — masked the real HTTP status. We instead return the raw text
+ * wrapped as `{ message }` so the status-based error path in `request` / `wrapNeonError`
+ * runs and produces a proper {@link PlatformError} (e.g. `NotFound`), and a non-error body
+ * that simply isn't JSON degrades to text rather than crashing.
+ */
+declare function readJsonBody(res: Response): Promise<unknown>;
+//#endregion
+export { buildFunctionDeployForm, createNeonAuthRestInput, createRealNeonApi, isPreviewFeatureUnavailable, previewUnavailableError, readJsonBody, retryOnLocked };
+//# sourceMappingURL=neon-api-real.d.ts.map

package/dist/lib/neon-api-real.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neon-api-real.d.ts","names":[],"sources":["../../src/lib/neon-api-real.ts"],"mappings":";;;UAiRU,uBAAA;;EAAA,aAAA,CAAA,EAAA,MAAA;AAeV;AA4CC;AAeD;;;;AAES,iBA7DO,iBAAA,CA6DP,OAAA,EAAA;QACE,EAAA,MAAA;SAAR,CAAA,EAAA,MAAA;EAAO;AAk9BV;AAiFA;AA6DA;AAoBA;EAAuC,aAAA,CAAA,EAAA;IAAQ,WAAA,CAAA,EAAA,MAAA;IAAsB,cAAA,CAAA,EAAA,MAAA;IAAQ,UAAA,CAAA,EAAA,MAAA;EAwBvD,CAAA;CAAY,CAAA,EA7rC9B,OA6rC8B;UA5pCxB,WAAA,CA4pC8B;aAAW,EAAA,MAAA;EAAO,cAAA,EAAA,MAAA;;;;;;;;;;iBA/oCpC,2BACX,QAAQ,YACV,cACN,QAAQ;;;;;;;;;;;;iBAk9BK,2BAAA;;;;;;;;;;;;iBAiFA,uBAAA;iBA6DA,uBAAA;;IAEZ;;;;;;;;;;;;iBAkBY,uBAAA,QAA+B,sBAAsB;;;;;;;;;;;iBAwB/C,YAAA,MAAkB,WAAW"}