@neondatabase/config 0.0.0 → 0.1.0

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

@@ -0,0 +1,582 @@
+import { ErrorCode, PlatformError } from "./errors.js";
+import { formatSuspendTimeout, parseSuspendTimeout } from "./duration.js";
+import { wrapNeonError } from "./wrap-neon-error.js";
+import { z } from "zod";
+import { EndpointType, createApiClient } from "@neondatabase/api-client";
+//#region src/lib/neon-api-real.ts
+const DEFAULT_NEON_API_BASE_URL = "https://console.neon.tech/api/v2";
+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()
+});
+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 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 functionResponseSchema = z.object({ function: neonFunctionSchema });
+const functionsListResponseSchema = z.object({ functions: z.array(neonFunctionSchema) });
+const functionDeploymentResponseSchema = z.object({ deployment: functionDeploymentSchema });
+/**
+* Adapt `@neondatabase/api-client` 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(" "));
+	return new RealNeonApi(createApiClient({
+		apiKey: options.apiKey,
+		...options.baseUrl ? { baseURL: options.baseUrl } : {}
+	}), {
+		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 res = await this.client.listProjects({
+					...filter.orgId ? { org_id: filter.orgId } : {},
+					...cursor ? { cursor } : {},
+					limit: 100
+				});
+				projects.push(...res.data.projects);
+				const next = res.data.pagination?.next;
+				if (!next || next === cursor) break;
+				cursor = next;
+			}
+			return projects.map(projectToSnapshot);
+		});
+	}
+	async getProject(projectId) {
+		return this.call(`getProject(${projectId})`, async () => {
+			return projectToSnapshot((await this.client.getProject(projectId)).data.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((await this.client.createProject(body)).data.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((await this.client.updateProject(projectId, body)).data.project);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listBranches(projectId) {
+		return this.call(`listBranches(${projectId})`, async () => {
+			const branches = [];
+			let cursor;
+			while (true) {
+				const res = await this.client.listProjectBranches({
+					projectId,
+					limit: 100,
+					...cursor ? { cursor } : {}
+				});
+				branches.push(...res.data.branches);
+				const next = res.data.pagination?.next;
+				if (!next || next === cursor) break;
+				cursor = next;
+			}
+			return branches.map(branchToSnapshot);
+		}, { projectId });
+	}
+	async createBranch(projectId, input) {
+		const endpointOptions = input.computeSettings ? {
+			type: EndpointType.ReadWrite,
+			...computeSettingsToEndpointOptions(input.computeSettings)
+		} : { type: EndpointType.ReadWrite };
+		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 res = await this.client.createProjectBranch(projectId, body);
+			return {
+				branch: branchToSnapshot(res.data.branch),
+				endpoints: (res.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((await this.client.updateProjectBranch(projectId, branchId, { branch })).data.branch);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listEndpoints(projectId) {
+		return this.call(`listEndpoints(${projectId})`, async () => {
+			return (await this.client.listProjectEndpoints(projectId)).data.endpoints.map(endpointToSnapshot);
+		}, { projectId });
+	}
+	async updateEndpoint(projectId, endpointId, settings) {
+		const endpoint = computeSettingsToEndpointOptions(settings);
+		return this.call(`updateEndpoint(${projectId}/${endpointId})`, async () => {
+			return endpointToSnapshot((await this.client.updateProjectEndpoint(projectId, endpointId, { endpoint })).data.endpoint);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async listBranchRoles(projectId, branchId) {
+		return this.call(`listBranchRoles(${projectId}/${branchId})`, async () => {
+			return (await this.client.listProjectBranchRoles(projectId, branchId)).data.roles.map(roleToSnapshot);
+		}, { projectId });
+	}
+	async listBranchDatabases(projectId, branchId) {
+		return this.call(`listBranchDatabases(${projectId}/${branchId})`, async () => {
+			return (await this.client.listProjectBranchDatabases(projectId, branchId)).data.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: (await this.client.getConnectionUri({
+				projectId,
+				database_name: input.databaseName,
+				role_name: input.roleName,
+				...input.branchId ? { branch_id: input.branchId } : {},
+				...input.endpointId ? { endpoint_id: input.endpointId } : {},
+				pooled
+			})).data.uri };
+		}, { projectId });
+	}
+	async getNeonAuth(projectId, branchId) {
+		try {
+			return await this.call(`getNeonAuth(${projectId}/${branchId})`, async () => {
+				return neonAuthResponseToSnapshot((await this.client.getNeonAuth(projectId, branchId)).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.
+	* Sends the bundle as the `file` field plus the deploy params Neon requires.
+	*/
+	async postMultipart(path, input) {
+		const form = new FormData();
+		form.set("file", new Blob([input.bundle], { type: "application/zip" }), "bundle.zip");
+		form.set("memory_mib", String(input.memoryMib));
+		form.set("concurrency", "1");
+		form.set("runtime", input.runtime);
+		for (const [key, value] of Object.entries(input.environment)) form.set(`environment[${key}]`, value);
+		return this.request("POST", path, { body: form });
+	}
+	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 () => {
+				return { url: (await this.client.getProjectBranchDataApi(projectId, branchId, databaseName)).data.url };
+			}, { projectId });
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.NotFound) return null;
+			throw err;
+		}
+	}
+	async enableProjectBranchDataApi(projectId, branchId, databaseName) {
+		try {
+			return await this.call(`enableProjectBranchDataApi(${projectId}/${branchId}/${databaseName})`, async () => {
+				return { url: (await this.client.createProjectBranchDataApi(projectId, branchId, databaseName, {})).data.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 listBranchBuckets(projectId, branchId) {
+		return this.call(`listBranchBuckets(${projectId}/${branchId})`, async () => {
+			const data = await this.getJson(branchPreviewPath(projectId, branchId, "buckets"));
+			return bucketsListResponseSchema.parse(data).buckets.map(bucketToSnapshot);
+		}, { projectId });
+	}
+	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 listBranchFunctions(projectId, branchId) {
+		return this.call(`listBranchFunctions(${projectId}/${branchId})`, async () => {
+			const data = await this.getJson(branchPreviewPath(projectId, branchId, "functions"));
+			return functionsListResponseSchema.parse(data).functions.map(functionToSnapshot);
+		}, { projectId });
+	}
+	async createBranchFunction(projectId, branchId, input) {
+		return this.call(`createBranchFunction(${projectId}/${branchId}/${input.slug})`, async () => {
+			const data = await this.postJson(branchPreviewPath(projectId, branchId, "functions"), {
+				slug: input.slug,
+				name: input.name
+			});
+			return functionToSnapshot(functionResponseSchema.parse(data).function);
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	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 getAiGatewayEnabled(projectId, branchId) {
+		try {
+			return await this.call(`getAiGatewayEnabled(${projectId}/${branchId})`, async () => {
+				return aiGatewayEnabledFromResponse(await this.getJson(aiGatewayPath(projectId, branchId)));
+			}, { projectId });
+		} catch (err) {
+			if (err instanceof PlatformError && err.code === ErrorCode.NotFound) return false;
+			throw err;
+		}
+	}
+	async enableAiGateway(projectId, branchId) {
+		await this.call(`enableAiGateway(${projectId}/${branchId})`, async () => {
+			await this.postJson(aiGatewayPath(projectId, branchId), { enabled: true });
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+	async disableAiGateway(projectId, branchId) {
+		await this.call(`disableAiGateway(${projectId}/${branchId})`, async () => {
+			await this.deleteJson(aiGatewayPath(projectId, branchId));
+		}, {
+			projectId,
+			mutating: true
+		});
+	}
+};
+function branchPreviewPath(projectId, branchId, resource) {
+	return `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/${resource}`;
+}
+function aiGatewayPath(projectId, branchId) {
+	return `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/ai-gateway`;
+}
+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";
+	}
+}
+function aiGatewayEnabledFromResponse(data) {
+	if (data !== null && typeof data === "object" && "enabled" in data) return data.enabled === true;
+	return false;
+}
+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 } : {}
+	};
+}
+async function readJsonBody(res) {
+	const text = await res.text();
+	if (text.trim() === "") return {};
+	return JSON.parse(text);
+}
+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 === EndpointType.ReadOnly ? "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 { createNeonAuthRestInput, createRealNeonApi, retryOnLocked };
+
+//# sourceMappingURL=neon-api-real.js.map