@neon/config 0.0.0 → 0.9.0

package/dist/lib/neon-api-real.js

@@ -0,0 +1,957 @@
+import { ErrorCode, PlatformError } from "./errors.js";
+import { formatSuspendTimeout, parseSuspendTimeout } from "./duration.js";
+import { wrapNeonError } from "./wrap-neon-error.js";
+import { z } from "zod";
+import { createNeonClient } from "@neon/sdk";
+import { createProject, createProjectBranch, createProjectBranchDataApi, getConnectionUri, getNeonAuth, getProject, getProjectBranchDataApi, listProjectBranchDatabases, listProjectBranchRoles, listProjectBranches, listProjectEndpoints, listProjects, updateProject, updateProjectBranch, updateProjectBranchDataApi, updateProjectEndpoint } from "@neon/sdk/raw";
+//#region src/lib/neon-api-real.ts
+const DEFAULT_NEON_API_BASE_URL = "https://console.neon.tech/api/v2";
+/**
+* Unwrap a `@neon/sdk` raw `{ data, error, response }` result into the bare body, throwing
+* on a non-2xx response. The thrown shape (`{ response: { status, data } }`) deliberately
+* matches what the package's REST fallbacks already throw, so {@link wrapNeonError} and the
+* 423 {@link retryOnLocked} retry keep working unchanged across both transports.
+*/
+function unwrap(result) {
+	const response = result.response;
+	if (!response || !response.ok) throw { response: {
+		status: response?.status,
+		data: result.error
+	} };
+	return result.data;
+}
+const neonAuthResponseSchema = z.object({
+	auth_provider_project_id: z.string(),
+	pub_client_key: z.string().optional(),
+	secret_server_key: z.string().optional(),
+	jwks_url: z.string(),
+	base_url: z.string().optional()
+});
+/** Map our camelCase {@link DataApiSettings} onto the Neon API's snake_case `DataAPISettings`. */
+function dataApiSettingsToApi(settings) {
+	const out = {};
+	if (settings.dbAggregatesEnabled !== void 0) out.db_aggregates_enabled = settings.dbAggregatesEnabled;
+	if (settings.dbAnonRole !== void 0) out.db_anon_role = settings.dbAnonRole;
+	if (settings.dbExtraSearchPath !== void 0) out.db_extra_search_path = settings.dbExtraSearchPath;
+	if (settings.dbMaxRows !== void 0) out.db_max_rows = settings.dbMaxRows;
+	if (settings.dbSchemas !== void 0) out.db_schemas = settings.dbSchemas;
+	if (settings.jwtRoleClaimKey !== void 0) out.jwt_role_claim_key = settings.jwtRoleClaimKey;
+	if (settings.jwtCacheMaxLifetime !== void 0) out.jwt_cache_max_lifetime = settings.jwtCacheMaxLifetime;
+	if (settings.openapiMode !== void 0) out.openapi_mode = settings.openapiMode;
+	if (settings.serverCorsAllowedOrigins !== void 0) out.server_cors_allowed_origins = settings.serverCorsAllowedOrigins;
+	if (settings.serverTimingEnabled !== void 0) out.server_timing_enabled = settings.serverTimingEnabled;
+	return out;
+}
+/** Narrow the API's free-form `openapi_mode` string to our literal union (else drop it). */
+function normalizeOpenapiMode(value) {
+	return value === "ignore-privileges" || value === "disabled" ? value : void 0;
+}
+/** Map the Neon API's snake_case `DataAPISettings` back to our camelCase {@link DataApiSettings}. */
+function dataApiSettingsFromApi(settings) {
+	if (!settings) return void 0;
+	const out = {};
+	if (settings.db_aggregates_enabled !== void 0) out.dbAggregatesEnabled = settings.db_aggregates_enabled;
+	if (settings.db_anon_role !== void 0) out.dbAnonRole = settings.db_anon_role;
+	if (settings.db_extra_search_path !== void 0) out.dbExtraSearchPath = settings.db_extra_search_path;
+	if (settings.db_max_rows !== void 0) out.dbMaxRows = settings.db_max_rows;
+	if (settings.db_schemas !== void 0) out.dbSchemas = settings.db_schemas;
+	if (settings.jwt_role_claim_key !== void 0) out.jwtRoleClaimKey = settings.jwt_role_claim_key;
+	if (settings.jwt_cache_max_lifetime !== void 0) out.jwtCacheMaxLifetime = settings.jwt_cache_max_lifetime;
+	if (settings.openapi_mode !== void 0) {
+		const mode = normalizeOpenapiMode(settings.openapi_mode);
+		if (mode !== void 0) out.openapiMode = mode;
+	}
+	if (settings.server_cors_allowed_origins !== void 0) out.serverCorsAllowedOrigins = settings.server_cors_allowed_origins;
+	if (settings.server_timing_enabled !== void 0) out.serverTimingEnabled = settings.server_timing_enabled;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/** Build the Neon API `DataAPICreateRequest` from our {@link EnableDataApiInput}. */
+function dataApiCreateRequest(input) {
+	const req = {};
+	if (!input) return req;
+	if (input.authProvider !== void 0) req.auth_provider = input.authProvider === "neon" ? "neon_auth" : "external";
+	if (input.jwksUrl !== void 0) req.jwks_url = input.jwksUrl;
+	if (input.providerName !== void 0) req.provider_name = input.providerName;
+	if (input.jwtAudience !== void 0) req.jwt_audience = input.jwtAudience;
+	if (input.settings) {
+		const settings = dataApiSettingsToApi(input.settings);
+		if (Object.keys(settings).length > 0) req.settings = settings;
+	}
+	return req;
+}
+/** Map a `DataAPIReponse` (GET) onto our {@link NeonDataApiSnapshot}. */
+function dataApiSnapshotFromResponse(data) {
+	const snapshot = { url: data.url };
+	if (data.status !== void 0) snapshot.status = data.status;
+	const settings = dataApiSettingsFromApi(data.settings);
+	if (settings) snapshot.settings = settings;
+	return snapshot;
+}
+const bucketSchema = z.object({
+	name: z.string(),
+	access_level: z.string().optional()
+});
+const bucketResponseSchema = z.object({ bucket: bucketSchema });
+const bucketsListResponseSchema = z.object({ buckets: z.array(bucketSchema) });
+const branchStorageSchema = z.object({
+	enabled: z.boolean().optional(),
+	s3_endpoint: z.string(),
+	region: z.string(),
+	force_path_style: z.boolean()
+});
+const functionDeploymentSchema = z.object({
+	id: z.number(),
+	status: z.string()
+});
+const neonFunctionSchema = z.object({
+	id: z.string(),
+	slug: z.string(),
+	name: z.string(),
+	invocation_url: z.string(),
+	active_deployment: functionDeploymentSchema.optional()
+});
+const functionsListResponseSchema = z.object({ functions: z.array(neonFunctionSchema) });
+const functionDeploymentResponseSchema = z.object({ deployment: functionDeploymentSchema });
+const credentialScopeSchema = z.enum([
+	"storage:read",
+	"storage:write",
+	"ai_gateway:invoke",
+	"functions:invoke"
+]);
+const createCredentialResponseSchema = z.object({
+	token_id: z.string(),
+	token_id_short: z.string(),
+	name: z.string().optional(),
+	api_token: z.string(),
+	s3_secret_access_key: z.string(),
+	scopes: z.array(credentialScopeSchema),
+	branch_id: z.string(),
+	created_at: z.string(),
+	expires_at: z.string().optional()
+});
+const credentialMetaSchema = z.object({
+	token_id: z.string(),
+	token_id_short: z.string(),
+	name: z.string().optional(),
+	scopes: z.array(credentialScopeSchema),
+	principal_type: z.enum(["user", "function"]),
+	function_id: z.string().optional(),
+	branch_id: z.string().optional(),
+	created_at: z.string(),
+	last_used_at: z.string().optional(),
+	revoked_at: z.string().optional(),
+	expires_at: z.string().optional()
+});
+const listCredentialsResponseSchema = z.object({ credentials: z.array(credentialMetaSchema) });
+/**
+* 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.
+*/
+function createRealNeonApi(options) {
+	if (!options.apiKey || options.apiKey.trim() === "") throw new PlatformError(ErrorCode.MissingApiKey, ["createRealNeonApi requires a non-empty `apiKey`.", "Generate one at https://console.neon.tech/app/settings/api-keys and pass it as { apiKey: process.env.NEON_API_KEY }."].join(" "));
+	const client = createNeonClient({
+		apiKey: options.apiKey,
+		retries: 0,
+		...options.baseUrl ? { baseUrl: options.baseUrl } : {}
+	}).client;
+	return new RealNeonApi(client, {
+		maxAttempts: options.retryOnLocked?.maxAttempts ?? 12,
+		initialDelayMs: options.retryOnLocked?.initialDelayMs ?? 250,
+		maxDelayMs: options.retryOnLocked?.maxDelayMs ?? 5e3
+	}, {
+		apiKey: options.apiKey,
+		baseUrl: options.baseUrl ?? DEFAULT_NEON_API_BASE_URL
+	});
+}
+/**
+* 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}.
+*/
+async function retryOnLocked(fn, config) {
+	let delay = config.initialDelayMs;
+	let lastError;
+	for (let attempt = 1; attempt <= config.maxAttempts; attempt++) try {
+		return await fn();
+	} catch (err) {
+		lastError = err;
+		if (readHttpStatusFromError(err) !== 423 || attempt === config.maxAttempts) throw err;
+		await sleep(delay);
+		delay = Math.min(delay * 2, config.maxDelayMs);
+	}
+	throw lastError;
+}
+function readHttpStatusFromError(err) {
+	if (err === null || typeof err !== "object") return void 0;
+	const response = err.response;
+	if (response === null || typeof response !== "object") return void 0;
+	const status = response.status;
+	return typeof status === "number" ? status : void 0;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var RealNeonApi = class {
+	client;
+	retryConfig;
+	restConfig;
+	constructor(client, retryConfig, restConfig) {
+		this.client = client;
+		this.retryConfig = retryConfig;
+		this.restConfig = restConfig;
+	}
+	retry(fn) {
+		return retryOnLocked(fn, this.retryConfig);
+	}
+	async call(op, fn, options = {}) {
+		try {
+			return options.mutating ? await this.retry(fn) : await fn();
+		} catch (err) {
+			throw wrapNeonError(err, options.projectId ? {
+				op,
+				projectId: options.projectId
+			} : { op });
+		}
+	}
+	async listProjects(filter) {
+		return this.call(filter.orgId ? `listProjects(org=${filter.orgId})` : "listProjects", async () => {
+			const projects = [];
+			let cursor;
+			while (true) {
+				const body = unwrap(await listProjects({
+					client: this.client,
+					query: {
+						...filter.orgId ? { org_id: filter.orgId } : {},
+						...cursor ? { cursor } : {},
+						limit: 100
+					}
+				}));
+				projects.push(...body.projects);
+				const next = body.pagination?.next;
+				if (!next || next === cursor) break;
+				cursor = next;
+			}
+			return projects.map(projectToSnapshot);
+		});
+	}
+	async getProject(projectId) {
+		return this.call(`getProject(${projectId})`, async () => {
+			return projectToSnapshot(unwrap(await getProject({
+				client: this.client,
+				path: { project_id: projectId }
+			})).project);
+		}, { projectId });
+	}
+	async createProject(input) {
+		const body = { project: {
+			name: input.name,
+			region_id: input.regionId,
+			...input.pgVersion !== void 0 ? { pg_version: input.pgVersion } : {},
+			...input.orgId ? { org_id: input.orgId } : {},
+			...input.defaultEndpointSettings ? { default_endpoint_settings: computeSettingsToDefaults(input.defaultEndpointSettings) } : {},
+			...input.defaultBranchName ? { branch: { name: input.defaultBranchName } } : {}
+		} };
+		return this.call(`createProject(${input.name})`, async () => {
+			return projectToSnapshot(unwrap(await createProject({
+				client: this.client,
+				body
+			})).project);
+		}, { mutating: true });
+	}
+	async updateProject(projectId, input) {
+		const body = { project: {
+			...input.name !== void 0 ? { name: input.name } : {},
+			...input.defaultEndpointSettings ? { default_endpoint_settings: computeSettingsToDefaults(input.defaultEndpointSettings) } : {}
+		} };
+		return this.call(`updateProject(${projectId})`, async () => {
+			return projectToSnapshot(unwrap(await updateProject({
+				client: this.client,
+				path: { project_id: projectId },
+				body
+			})).project);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listBranches(projectId) {
+		return this.call(`listBranches(${projectId})`, async () => {
+			const branches = [];
+			let cursor;
+			while (true) {
+				const body = unwrap(await listProjectBranches({
+					client: this.client,
+					path: { project_id: projectId },
+					query: {
+						limit: 100,
+						...cursor ? { cursor } : {}
+					}
+				}));
+				branches.push(...body.branches);
+				const next = body.pagination?.next;
+				if (!next || next === cursor) break;
+				cursor = next;
+			}
+			return branches.map(branchToSnapshot);
+		}, { projectId });
+	}
+	async createBranch(projectId, input) {
+		const endpointOptions = input.computeSettings ? {
+			type: "read_write",
+			...computeSettingsToEndpointOptions(input.computeSettings)
+		} : { type: "read_write" };
+		const body = {
+			branch: {
+				name: input.name,
+				...input.parentId ? { parent_id: input.parentId } : {},
+				...input.expiresAt ? { expires_at: input.expiresAt } : {},
+				...input.protected !== void 0 ? { protected: input.protected } : {}
+			},
+			endpoints: [endpointOptions]
+		};
+		return this.call(`createBranch(${projectId}/${input.name})`, async () => {
+			const data = unwrap(await createProjectBranch({
+				client: this.client,
+				path: { project_id: projectId },
+				body
+			}));
+			return {
+				branch: branchToSnapshot(data.branch),
+				endpoints: (data.endpoints ?? []).map(endpointToSnapshot)
+			};
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async updateBranch(projectId, branchId, input) {
+		const branch = {};
+		if (input.name !== void 0) branch.name = input.name;
+		if (input.expiresAt !== void 0) branch.expires_at = input.expiresAt;
+		if (input.protected !== void 0) branch.protected = input.protected;
+		return this.call(`updateBranch(${projectId}/${branchId})`, async () => {
+			return branchToSnapshot(unwrap(await updateProjectBranch({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					branch_id: branchId
+				},
+				body: { branch }
+			})).branch);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listEndpoints(projectId) {
+		return this.call(`listEndpoints(${projectId})`, async () => {
+			return unwrap(await listProjectEndpoints({
+				client: this.client,
+				path: { project_id: projectId }
+			})).endpoints.map(endpointToSnapshot);
+		}, { projectId });
+	}
+	async updateEndpoint(projectId, endpointId, settings) {
+		const endpoint = computeSettingsToEndpointOptions(settings);
+		return this.call(`updateEndpoint(${projectId}/${endpointId})`, async () => {
+			return endpointToSnapshot(unwrap(await updateProjectEndpoint({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					endpoint_id: endpointId
+				},
+				body: { endpoint }
+			})).endpoint);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listBranchRoles(projectId, branchId) {
+		return this.call(`listBranchRoles(${projectId}/${branchId})`, async () => {
+			return unwrap(await listProjectBranchRoles({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					branch_id: branchId
+				}
+			})).roles.map(roleToSnapshot);
+		}, { projectId });
+	}
+	async listBranchDatabases(projectId, branchId) {
+		return this.call(`listBranchDatabases(${projectId}/${branchId})`, async () => {
+			return unwrap(await listProjectBranchDatabases({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					branch_id: branchId
+				}
+			})).databases.map(databaseToSnapshot);
+		}, { projectId });
+	}
+	async getConnectionUri(projectId, input) {
+		const op = `getConnectionUri(${projectId}/${input.databaseName}@${input.roleName}${input.pooled ? " pooled" : ""})`;
+		const pooled = input.pooled === true;
+		return this.call(op, async () => {
+			return { uri: unwrap(await getConnectionUri({
+				client: this.client,
+				path: { project_id: projectId },
+				query: {
+					database_name: input.databaseName,
+					role_name: input.roleName,
+					...input.branchId ? { branch_id: input.branchId } : {},
+					...input.endpointId ? { endpoint_id: input.endpointId } : {},
+					pooled
+				}
+			})).uri };
+		}, { projectId });
+	}
+	async getNeonAuth(projectId, branchId) {
+		try {
+			return await this.call(`getNeonAuth(${projectId}/${branchId})`, async () => {
+				const data = unwrap(await getNeonAuth({
+					client: this.client,
+					path: {
+						project_id: projectId,
+						branch_id: branchId
+					}
+				}));
+				return neonAuthResponseToSnapshot(neonAuthResponseSchema.parse(data));
+			}, { projectId });
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.NotFound) return null;
+			throw err;
+		}
+	}
+	async enableNeonAuth(projectId, branchId, input = {}) {
+		try {
+			return await this.call(`enableNeonAuth(${projectId}/${branchId})`, async () => {
+				const data = await this.postJson(`/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/auth`, createNeonAuthRestInput(input));
+				return neonAuthResponseToSnapshot(neonAuthResponseSchema.parse(data));
+			}, {
+				projectId,
+				mutating: true
+			});
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.Conflict) {
+				const existing = await this.getNeonAuth(projectId, branchId);
+				if (existing) return existing;
+			}
+			throw err;
+		}
+	}
+	async postJson(path, body) {
+		return this.request("POST", path, {
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		});
+	}
+	async getJson(path) {
+		return this.request("GET", path);
+	}
+	async deleteJson(path) {
+		return this.request("DELETE", path);
+	}
+	/**
+	* Upload a built function bundle via `multipart/form-data` to the deploy endpoint
+	* (`POST .../functions/{slug}/deployments`). Body shape lives in the pure
+	* {@link buildFunctionDeployForm} helper so it can be unit-tested against the spec.
+	*/
+	async postMultipart(path, input) {
+		return this.request("POST", path, { body: buildFunctionDeployForm(input) });
+	}
+	async request(method, path, init = {}) {
+		const url = `${this.restConfig.baseUrl.replace(/\/+$/, "")}${path}`;
+		const res = await fetch(url, {
+			method,
+			headers: {
+				Authorization: `Bearer ${this.restConfig.apiKey}`,
+				...init.headers ?? {}
+			},
+			...init.body !== void 0 ? { body: init.body } : {}
+		});
+		const data = await readJsonBody(res);
+		if (!res.ok) throw { response: {
+			status: res.status,
+			data
+		} };
+		return data;
+	}
+	async getNeonDataApi(projectId, branchId, databaseName) {
+		try {
+			return await this.call(`getNeonDataApi(${projectId}/${branchId}/${databaseName})`, async () => dataApiSnapshotFromResponse(unwrap(await getProjectBranchDataApi({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					branch_id: branchId,
+					database_name: databaseName
+				}
+			}))), { projectId });
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.NotFound) return null;
+			throw err;
+		}
+	}
+	async enableProjectBranchDataApi(projectId, branchId, databaseName, input) {
+		try {
+			return await this.call(`enableProjectBranchDataApi(${projectId}/${branchId}/${databaseName})`, async () => {
+				return { url: unwrap(await createProjectBranchDataApi({
+					client: this.client,
+					path: {
+						project_id: projectId,
+						branch_id: branchId,
+						database_name: databaseName
+					},
+					body: dataApiCreateRequest(input)
+				})).url };
+			}, {
+				projectId,
+				mutating: true
+			});
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.Conflict) {
+				const existing = await this.getNeonDataApi(projectId, branchId, databaseName);
+				if (existing) return existing;
+			}
+			throw err;
+		}
+	}
+	async updateProjectBranchDataApi(projectId, branchId, databaseName, settings) {
+		return await this.call(`updateProjectBranchDataApi(${projectId}/${branchId}/${databaseName})`, async () => {
+			unwrap(await updateProjectBranchDataApi({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					branch_id: branchId,
+					database_name: databaseName
+				},
+				body: { settings: dataApiSettingsToApi(settings) }
+			}));
+			return dataApiSnapshotFromResponse(unwrap(await getProjectBranchDataApi({
+				client: this.client,
+				path: {
+					project_id: projectId,
+					branch_id: branchId,
+					database_name: databaseName
+				}
+			})));
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listBranchBuckets(projectId, branchId) {
+		try {
+			return await this.call(`listBranchBuckets(${projectId}/${branchId})`, async () => {
+				const data = await this.getJson(branchPreviewPath(projectId, branchId, "buckets"));
+				return bucketsListResponseSchema.parse(data).buckets.map(bucketToSnapshot);
+			}, { projectId });
+		} catch (err) {
+			throw previewUnavailableError(err, "Object storage (buckets)");
+		}
+	}
+	async createBranchBucket(projectId, branchId, input) {
+		return this.call(`createBranchBucket(${projectId}/${branchId}/${input.name})`, async () => {
+			const data = await this.postJson(branchPreviewPath(projectId, branchId, "buckets"), {
+				name: input.name,
+				...input.accessLevel ? { access_level: input.accessLevel } : {}
+			});
+			return bucketToSnapshot(bucketResponseSchema.parse(data).bucket);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async deleteBranchBucket(projectId, branchId, bucketName) {
+		await this.call(`deleteBranchBucket(${projectId}/${branchId}/${bucketName})`, async () => {
+			await this.deleteJson(`${branchPreviewPath(projectId, branchId, "buckets")}/${encodeURIComponent(bucketName)}`);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async getProjectBranchStorage(projectId, branchId) {
+		try {
+			return await this.call(`getProjectBranchStorage(${projectId}/${branchId})`, async () => {
+				const data = await this.getJson(`/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/storage`);
+				const parsed = branchStorageSchema.parse(data);
+				return {
+					s3Endpoint: parsed.s3_endpoint,
+					region: parsed.region,
+					forcePathStyle: parsed.force_path_style
+				};
+			}, { projectId });
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.NotFound) return null;
+			throw previewUnavailableError(err, "Object storage");
+		}
+	}
+	async listBranchFunctions(projectId, branchId) {
+		try {
+			return await this.call(`listBranchFunctions(${projectId}/${branchId})`, async () => {
+				const data = await this.getJson(branchPreviewPath(projectId, branchId, "functions"));
+				return functionsListResponseSchema.parse(data).functions.map(functionToSnapshot);
+			}, { projectId });
+		} catch (err) {
+			throw previewUnavailableError(err, "Functions");
+		}
+	}
+	async deleteBranchFunction(projectId, branchId, slug) {
+		await this.call(`deleteBranchFunction(${projectId}/${branchId}/${slug})`, async () => {
+			await this.deleteJson(`${branchPreviewPath(projectId, branchId, "functions")}/${encodeURIComponent(slug)}`);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async deployBranchFunction(projectId, branchId, slug, input) {
+		return this.call(`deployBranchFunction(${projectId}/${branchId}/${slug})`, async () => {
+			const data = await this.postMultipart(`${branchPreviewPath(projectId, branchId, "functions")}/${encodeURIComponent(slug)}/deployments`, input);
+			return deploymentToSnapshot(functionDeploymentResponseSchema.parse(data).deployment);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async createCredential(projectId, branchId, input) {
+		try {
+			return await this.call(`createCredential(${projectId}/${branchId})`, async () => {
+				const data = await this.postJson(credentialsPath(projectId, branchId), {
+					scopes: input.scopes,
+					principal_type: input.principalType,
+					...input.functionId ? { function_id: input.functionId } : {},
+					...input.name ? { name: input.name } : {}
+				});
+				return createCredentialToSnapshot(createCredentialResponseSchema.parse(data));
+			}, {
+				projectId,
+				mutating: true
+			});
+		} catch (err) {
+			throw previewUnavailableError(err, "Branch credentials");
+		}
+	}
+	async listCredentials(projectId, branchId) {
+		try {
+			return await this.call(`listCredentials(${projectId}/${branchId})`, async () => {
+				const data = await this.getJson(credentialsPath(projectId, branchId));
+				return listCredentialsResponseSchema.parse(data).credentials.map(credentialMetaToSnapshot);
+			}, { projectId });
+		} catch (err) {
+			throw previewUnavailableError(err, "Branch credentials");
+		}
+	}
+	async revokeCredential(projectId, branchId, tokenId) {
+		await this.call(`revokeCredential(${projectId}/${branchId}/${tokenId})`, async () => {
+			await this.deleteJson(`${credentialsPath(projectId, branchId)}/${encodeURIComponent(tokenId)}`);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+};
+function branchPreviewPath(projectId, branchId, resource) {
+	return `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/${resource}`;
+}
+function credentialsPath(projectId, branchId) {
+	return `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/credentials`;
+}
+function createCredentialToSnapshot(data) {
+	const snapshot = {
+		tokenId: data.token_id,
+		tokenIdShort: data.token_id_short,
+		apiToken: data.api_token,
+		s3SecretAccessKey: data.s3_secret_access_key,
+		scopes: data.scopes,
+		branchId: data.branch_id,
+		createdAt: data.created_at
+	};
+	if (data.name !== void 0) snapshot.name = data.name;
+	if (data.expires_at !== void 0) snapshot.expiresAt = data.expires_at;
+	return snapshot;
+}
+function credentialMetaToSnapshot(data) {
+	const snapshot = {
+		tokenId: data.token_id,
+		tokenIdShort: data.token_id_short,
+		scopes: data.scopes,
+		principalType: data.principal_type,
+		createdAt: data.created_at
+	};
+	if (data.name !== void 0) snapshot.name = data.name;
+	if (data.function_id !== void 0) snapshot.functionId = data.function_id;
+	if (data.branch_id !== void 0) snapshot.branchId = data.branch_id;
+	if (data.last_used_at !== void 0) snapshot.lastUsedAt = data.last_used_at;
+	if (data.revoked_at !== void 0) snapshot.revokedAt = data.revoked_at;
+	if (data.expires_at !== void 0) snapshot.expiresAt = data.expires_at;
+	return snapshot;
+}
+function bucketToSnapshot(bucket) {
+	return {
+		name: bucket.name,
+		accessLevel: normalizeBucketAccessLevel(bucket.access_level)
+	};
+}
+/**
+* The Neon API returns `access_level` as a free-form string (per the API guidelines:
+* responses use plain strings, not enums). Map the known values onto our union and treat
+* anything else as `private` — the safe default for an unrecognised access level.
+*/
+function normalizeBucketAccessLevel(value) {
+	return value === "public_read" ? "public_read" : "private";
+}
+function functionToSnapshot(fn) {
+	const snapshot = {
+		id: fn.id,
+		slug: fn.slug,
+		name: fn.name,
+		invocationUrl: fn.invocation_url
+	};
+	if (fn.active_deployment) snapshot.activeDeploymentId = fn.active_deployment.id;
+	return snapshot;
+}
+function deploymentToSnapshot(deployment) {
+	return {
+		id: deployment.id,
+		status: normalizeDeploymentStatus(deployment.status)
+	};
+}
+function normalizeDeploymentStatus(value) {
+	switch (value) {
+		case "pending":
+		case "building":
+		case "completed":
+		case "failed": return value;
+		default: return "pending";
+	}
+}
+/**
+* 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.
+*/
+function isPreviewFeatureUnavailable(err) {
+	if (!(err instanceof PlatformError)) return false;
+	const status = err.details.status;
+	const message = typeof err.details.neonMessage === "string" ? err.details.neonMessage.toLowerCase() : "";
+	return (message.includes("not available") || message.includes("does not exist") || message.includes("not enabled")) && (status === 503 || status === 404 || status === 501);
+}
+/**
+* Reason phrase for the handful of HTTP statuses a Preview-feature read can surface as
+* "unavailable". Used to print a short `HTTP <status> <reason>` line (not a stack trace),
+* so the message reads like the API response the user would see in a tool like curl.
+*/
+const HTTP_STATUS_TEXT = {
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	500: "Internal Server Error",
+	501: "Not Implemented",
+	503: "Service Unavailable"
+};
+/**
+* Per-status guidance for a Preview feature that came back "unavailable". A preview can be
+* gated several different ways and the HTTP status is the best signal for which, so we tailor
+* the next step instead of emitting one catch-all — valuable while these features are in
+* preview and rolling out region by region:
+*
+* - 404 / 501 — the route isn't deployed for this project's region (or the account isn't in
+*   the private preview): create a project in a region where the preview is enabled, and
+*   confirm your account has preview access.
+* - 503 — the route exists but is refusing right now: either the preview is still coming up,
+*   or Neon is having a transient incident. Retry; if it persists it's likely an incident.
+* - anything else — generic "not enabled for your account/region; request access".
+*
+* Only statuses {@link isPreviewFeatureUnavailable} accepts (404/501/503) actually reach
+* this, so there is intentionally no 401/403 branch — those never classify as "unavailable".
+*/
+function previewUnavailableHint(status) {
+	switch (status) {
+		case 404:
+		case 501: return "This usually means the preview isn't available in your project's region yet, or your Neon account isn't in the private preview: create a project in a region where the preview is enabled, and make sure your account has access to the preview.";
+		case 503: return "The endpoint is reachable but refused the request — the preview may still be coming up, or Neon may be having a transient incident. Retry shortly; if it keeps failing, check https://neonstatus.com and report it to Neon support.";
+		default: return "This usually means the preview isn't enabled for your Neon account or the project's region. Request access to the preview, or use a project in a region where it's available.";
+	}
+}
+/**
+* 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.
+*/
+function previewUnavailableError(err, featureLabel) {
+	if (!isPreviewFeatureUnavailable(err)) return err;
+	const details = err instanceof PlatformError ? err.details : {};
+	const status = typeof details.status === "number" ? details.status : void 0;
+	const neonMessage = typeof details.neonMessage === "string" ? details.neonMessage : void 0;
+	const requestId = typeof details.requestId === "string" ? details.requestId : void 0;
+	const statusText = status ? HTTP_STATUS_TEXT[status] : void 0;
+	const apiParts = [
+		status ? `HTTP ${status}${statusText ? ` ${statusText}` : ""}` : void 0,
+		neonMessage ? `Neon API said: "${neonMessage}"` : void 0,
+		requestId ? `request id ${requestId}` : void 0
+	].filter((part) => part !== void 0);
+	const apiContext = apiParts.length > 0 ? ` (${apiParts.join("; ")})` : "";
+	return new PlatformError(ErrorCode.FeatureUnavailable, [
+		`${featureLabel} is a Preview feature and isn't available for this Neon project${apiContext}.`,
+		previewUnavailableHint(status),
+		"If you don't need it, remove the corresponding feature from the `preview` block of your neon.ts and re-run."
+	].join(" "), {
+		cause: err,
+		details: {
+			feature: featureLabel,
+			...status !== void 0 ? { status } : {},
+			...requestId !== void 0 ? { requestId } : {}
+		}
+	});
+}
+function neonAuthResponseToSnapshot(data) {
+	const snapshot = {
+		projectId: data.auth_provider_project_id,
+		jwksUrl: data.jwks_url
+	};
+	if (data.pub_client_key !== void 0) snapshot.publishableClientKey = data.pub_client_key;
+	if (data.secret_server_key !== void 0) snapshot.secretServerKey = data.secret_server_key;
+	if (data.base_url) snapshot.baseUrl = data.base_url;
+	return snapshot;
+}
+function createNeonAuthRestInput(input) {
+	return {
+		auth_provider: "better_auth",
+		...input.databaseName ? { database_name: input.databaseName } : {}
+	};
+}
+/**
+* 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`.
+*/
+function buildFunctionDeployForm(input) {
+	const form = new FormData();
+	form.set("zip", new Blob([input.bundle], { type: "application/zip" }), "bundle.zip");
+	form.set("runtime", input.runtime);
+	if (Object.keys(input.environment).length > 0) form.set("environment", JSON.stringify(input.environment));
+	return form;
+}
+/**
+* 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.
+*/
+async function readJsonBody(res) {
+	const text = await res.text();
+	if (text.trim() === "") return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return { message: text.trim() };
+	}
+}
+function projectToSnapshot(project) {
+	const defaults = project.default_endpoint_settings;
+	const snapshot = {
+		id: project.id,
+		name: project.name,
+		regionId: project.region_id,
+		pgVersion: project.pg_version
+	};
+	if (project.org_id) snapshot.orgId = project.org_id;
+	if (defaults) {
+		const compute = defaultsToComputeSettings(defaults);
+		if (compute) snapshot.defaultEndpointSettings = compute;
+	}
+	return snapshot;
+}
+function branchToSnapshot(branch) {
+	const snapshot = {
+		id: branch.id,
+		name: branch.name,
+		isDefault: branch.default,
+		protected: branch.protected === true
+	};
+	if (branch.parent_id) snapshot.parentId = branch.parent_id;
+	if (branch.expires_at) snapshot.expiresAt = branch.expires_at;
+	return snapshot;
+}
+function endpointToSnapshot(endpoint) {
+	return {
+		id: endpoint.id,
+		branchId: endpoint.branch_id,
+		type: endpoint.type === "read_only" ? "read_only" : "read_write",
+		autoscalingLimitMinCu: endpoint.autoscaling_limit_min_cu,
+		autoscalingLimitMaxCu: endpoint.autoscaling_limit_max_cu,
+		suspendTimeout: formatSuspendTimeout(endpoint.suspend_timeout_seconds)
+	};
+}
+function roleToSnapshot(role) {
+	return {
+		name: role.name,
+		branchId: role.branch_id,
+		protected: role.protected ?? false
+	};
+}
+function databaseToSnapshot(database) {
+	return {
+		name: database.name,
+		branchId: database.branch_id,
+		ownerName: database.owner_name
+	};
+}
+function computeSettingsToDefaults(settings) {
+	const out = {};
+	if (settings.autoscalingLimitMinCu !== void 0) out.autoscaling_limit_min_cu = settings.autoscalingLimitMinCu;
+	if (settings.autoscalingLimitMaxCu !== void 0) out.autoscaling_limit_max_cu = settings.autoscalingLimitMaxCu;
+	if (settings.suspendTimeout !== void 0) {
+		const parsed = parseSuspendTimeout(settings.suspendTimeout);
+		if ("error" in parsed) throw new PlatformError(ErrorCode.InvalidConfig, `Invalid suspendTimeout: ${parsed.error}`);
+		out.suspend_timeout_seconds = parsed.seconds;
+	}
+	return out;
+}
+function computeSettingsToEndpointOptions(settings) {
+	const out = {};
+	if (settings.autoscalingLimitMinCu !== void 0) out.autoscaling_limit_min_cu = settings.autoscalingLimitMinCu;
+	if (settings.autoscalingLimitMaxCu !== void 0) out.autoscaling_limit_max_cu = settings.autoscalingLimitMaxCu;
+	if (settings.suspendTimeout !== void 0) {
+		const parsed = parseSuspendTimeout(settings.suspendTimeout);
+		if ("error" in parsed) throw new PlatformError(ErrorCode.InvalidConfig, `Invalid suspendTimeout: ${parsed.error}`);
+		out.suspend_timeout_seconds = parsed.seconds;
+	}
+	return out;
+}
+function defaultsToComputeSettings(defaults) {
+	const out = {};
+	if (defaults.autoscaling_limit_min_cu !== void 0) out.autoscalingLimitMinCu = defaults.autoscaling_limit_min_cu;
+	if (defaults.autoscaling_limit_max_cu !== void 0) out.autoscalingLimitMaxCu = defaults.autoscaling_limit_max_cu;
+	if (defaults.suspend_timeout_seconds !== void 0) out.suspendTimeout = formatSuspendTimeout(defaults.suspend_timeout_seconds);
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+//#endregion
+export { buildFunctionDeployForm, createNeonAuthRestInput, createRealNeonApi, isPreviewFeatureUnavailable, previewUnavailableError, readJsonBody, retryOnLocked };
+
+//# sourceMappingURL=neon-api-real.js.map