@neon/env 0.0.0 → 0.8.1

package/dist/lib/env.js

@@ -0,0 +1,561 @@
+import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialScopes, resolveConfig } from "@neon/config/v1";
+import { z } from "zod";
+//#region src/lib/env.ts
+/**
+* Mapping between the {@link NeonEnv} property paths and the OS-level env-var keys used
+* for cross-process transport (via `.env` files, `env run -- <cmd>`, or anything else
+* that talks to `process.env`).
+*
+* Each top-level key here is a {@link NeonEnv} namespace; the inner record maps the
+* camelCase property names exposed to TypeScript to the UPPER_SNAKE env-var names used
+* by the OS. Keep this in sync with {@link postgresEnvSchema} / {@link authEnvSchema} /
+* {@link dataApiEnvSchema}.
+*/
+/**
+* Neon's default branch owner role, created with every project. This is the role a
+* `DATABASE_URL` should connect as.
+*/
+const NEON_DEFAULT_OWNER_ROLE = "neondb_owner";
+/**
+* Roles Neon provisions for the Auth / Data API (PostgREST) stack. They exist to back
+* RLS-scoped Data API requests authenticated by JWT — never to hold a `DATABASE_URL` —
+* so they're skipped when auto-picking the connection role. Enabling Neon Auth or the
+* Data API (`neon config apply`) adds these next to the owner role, which is why a plain
+* branch routinely reports more than one role.
+*/
+const NEON_MANAGED_AUTH_ROLES = /* @__PURE__ */ new Set([
+	"authenticator",
+	"anonymous",
+	"authenticated"
+]);
+const NEON_ENV_VAR_KEYS = {
+	/**
+	* Branch identity. `NEON_BRANCH` carries the branch **name** and is injected into the
+	* Neon Functions runtime on every branch (including the default) by default. `env pull` /
+	* `neon dev` / `neon-env run` emit it too so local dev mirrors the deployed runtime.
+	*/
+	branch: { name: "NEON_BRANCH" },
+	postgres: {
+		databaseUrl: "DATABASE_URL",
+		databaseUrlUnpooled: "DATABASE_URL_UNPOOLED"
+	},
+	auth: {
+		baseUrl: "NEON_AUTH_BASE_URL",
+		jwksUrl: "NEON_AUTH_JWKS_URL"
+	},
+	dataApi: { url: "NEON_DATA_API_URL" },
+	/**
+	* Object storage (Preview). The S3 SDKs read `AWS_*` from their standard config chain, so
+	* a branch credential + `neon dev` / `env pull` makes object storage work from env alone.
+	* `region` is injected under the SDK-standard `AWS_REGION`.
+	*/
+	storage: {
+		accessKeyId: "AWS_ACCESS_KEY_ID",
+		secretAccessKey: "AWS_SECRET_ACCESS_KEY",
+		endpoint: "AWS_ENDPOINT_URL_S3",
+		region: "AWS_REGION"
+	},
+	/**
+	* AI Gateway (Preview). Mapped onto the OpenAI SDK's standard env vars so the OpenAI
+	* clients work from env alone; `baseUrl` carries the gateway's OpenAI-dialect route prefix
+	* (`/ai-gateway/openai/v1`). The `NEON_AI_GATEWAY_*` aliases are also emitted: `neonToken`
+	* mirrors the OpenAI key, and `neonBaseUrl` is the bare branch gateway host
+	* (`scheme://host`, no path) — the `@ai-sdk/neon` provider appends the
+	* `/ai-gateway/<dialect>/…` routes itself (https://github.com/vercel/ai/pull/15997).
+	*/
+	aiGateway: {
+		apiKey: "OPENAI_API_KEY",
+		baseUrl: "OPENAI_BASE_URL",
+		neonToken: "NEON_AI_GATEWAY_TOKEN",
+		neonBaseUrl: "NEON_AI_GATEWAY_BASE_URL"
+	}
+};
+/** OpenAI-dialect route prefix on the branch AI Gateway host. */
+const AI_GATEWAY_OPENAI_PATH = "/ai-gateway/openai/v1";
+/**
+* Resolve the project + branch this process should target, then fetch live Neon
+* connection strings for that branch over the network. Async — calls the Neon API.
+*
+* Use this from build scripts and the `neon-env run` command, where top-level await is
+* fine. For application code that needs a synchronous bootstrap (most frameworks: Drizzle
+* config, Next.js, Vite, etc.), inject env vars via `neon-env run -- <cmd>` and use
+* {@link parseEnv} instead — same {@link NeonEnv} shape, but a sync call against
+* `process.env`.
+*
+* Filesystem- and env-agnostic: pass `projectId` and the target `branchId` explicitly
+* (resolve them in your CLI, e.g. neonctl).
+*
+* ```ts
+* import config from "../neon";
+* import { fetchEnv } from "@neon/env";
+*
+* const env = await fetchEnv(config, { projectId: "patient-art-12345", branchId: "br-…" });
+* const db = drizzle(neon(env.postgres.databaseUrl), { schema });
+* ```
+*
+* The package does **not** mutate `process.env` or the filesystem itself.
+*/
+async function fetchEnv(config, options) {
+	const api = options.api ?? createApiFromOptions(options);
+	const projectId = options.projectId;
+	const branches = await api.listBranches(projectId);
+	if (branches.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: project ${projectId} has no branches.`, "Deploy your neon.ts policy (or create a branch) first, or pick a different project id."].join(" "), { details: { projectId } });
+	const branch = resolveBranch(options.branchId, branches);
+	const desired = resolveConfig(config, {
+		name: branch.name,
+		id: branch.id,
+		exists: true,
+		...branch.parentId ? { parentId: branch.parentId } : {},
+		isDefault: branch.isDefault,
+		isProtected: branch.protected,
+		...branch.expiresAt ? { expiresAt: branch.expiresAt } : {}
+	});
+	const [roles, databases] = await Promise.all([api.listBranchRoles(projectId, branch.id), api.listBranchDatabases(projectId, branch.id)]);
+	const roleName = pickRoleName(roles, branch, options.roleName);
+	const databaseName = pickDatabaseName(databases, branch, roleName, options.databaseName);
+	const wantsAuth = desired.authEnabled;
+	const wantsDataApi = desired.dataApiEnabled;
+	const [pooled, unpooled, authSnapshot, dataApiSnapshot] = await Promise.all([
+		api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			databaseName,
+			roleName,
+			pooled: true
+		}),
+		api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			databaseName,
+			roleName,
+			pooled: false
+		}),
+		wantsAuth ? api.getNeonAuth(projectId, branch.id) : Promise.resolve(null),
+		wantsDataApi ? api.getNeonDataApi(projectId, branch.id, databaseName) : Promise.resolve(null)
+	]);
+	const result = {
+		postgres: {
+			databaseUrl: pooled.uri,
+			databaseUrlUnpooled: unpooled.uri
+		},
+		branch: { name: branch.name }
+	};
+	if (wantsAuth) {
+		if (!authSnapshot) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables auth but no Neon Auth integration is enabled on branch ${branch.name} (${branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or `npx neonctl …`), in the Neon Console — then re-run fetchEnv. Or return auth.enabled=false."].join(" "), { details: {
+			projectId,
+			branchId: branch.id
+		} });
+		const envSource = options.env ?? process.env;
+		result.auth = {
+			baseUrl: resolveAuthBaseUrl(authSnapshot.baseUrl, envSource),
+			jwksUrl: resolveAuthJwksUrl(authSnapshot.jwksUrl, envSource)
+		};
+	}
+	if (wantsDataApi) {
+		if (!dataApiSnapshot) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables dataApi but no Data API integration is enabled on branch ${branch.name} (${branch.id}) database ${databaseName}.`, "Enable it via `apply(config, { projectId, branchId })` or in the Neon Console — then re-run fetchEnv. Or return dataApi.enabled=false."].join(" "), { details: {
+			projectId,
+			branchId: branch.id,
+			databaseName
+		} });
+		result.dataApi = { url: dataApiSnapshot.url };
+	}
+	const wantsStorage = (desired.preview?.buckets.length ?? 0) > 0;
+	const wantsAiGateway = desired.preview?.aiGatewayEnabled ?? false;
+	if (wantsStorage || wantsAiGateway) {
+		const secrets = await resolveCredentialSecrets({
+			api,
+			projectId,
+			branchId: branch.id,
+			branchName: branch.name,
+			scopes: previewCredentialScopes(desired.preview),
+			env: options.env ?? process.env,
+			needStorage: wantsStorage,
+			needApiToken: wantsAiGateway
+		});
+		if (wantsStorage) {
+			const storage = await api.getProjectBranchStorage(projectId, branch.id);
+			if (!storage) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy declares object storage (preview.buckets) but storage is not enabled on branch ${branch.name} (${branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or in the Neon Console) — then re-run fetchEnv. Or remove preview.buckets."].join(" "), { details: {
+				projectId,
+				branchId: branch.id
+			} });
+			result.storage = {
+				accessKeyId: secrets.accessKeyId,
+				secretAccessKey: secrets.secretAccessKey,
+				endpoint: storage.s3Endpoint,
+				region: storage.region
+			};
+		}
+		if (wantsAiGateway) result.aiGateway = {
+			apiKey: secrets.apiToken,
+			baseUrl: aiGatewayBaseUrl(branch.id, unpooled.uri)
+		};
+	}
+	return result;
+}
+/**
+* Scopes the branch credential should carry for a resolved branch policy. Only object storage
+* and the AI Gateway *require* a credential; functions never force one (they have no credential
+* of their own), but `functions:invoke` is added to the scope set when a credential is already
+* being minted for storage / the AI Gateway, so the one credential can invoke the branch's
+* functions too. Returns `[]` only when nothing credential-bearing is enabled.
+*/
+function previewCredentialScopes(preview) {
+	if (!preview) return [];
+	const storage = preview.buckets.length > 0;
+	const aiGateway = preview.aiGatewayEnabled;
+	if (!storage && !aiGateway) return [];
+	return deriveCredentialScopes({
+		storage,
+		aiGateway,
+		functions: preview.functions.length > 0
+	});
+}
+/**
+* Resolve the branch credential's secrets, reusing the ones already in the env source when
+* present and minting a fresh `user` credential otherwise. The Neon API returns `api_token` /
+* `s3_secret_access_key` exactly once at mint time, so the persisted copies (e.g. in
+* `.env.local`, surfaced as `OPENAI_API_KEY` / `AWS_SECRET_ACCESS_KEY`) are the only way to
+* recover them — exactly how one-time Auth keys are round-tripped. Reuse is presence-based
+* (no extra bookkeeping vars): if every secret the enabled features need is already present,
+* reuse it; otherwise mint one credential covering all currently-needed scopes.
+*/
+async function resolveCredentialSecrets(args) {
+	const sKeys = NEON_ENV_VAR_KEYS.storage;
+	const aKeys = NEON_ENV_VAR_KEYS.aiGateway;
+	const haveStorage = !args.needStorage || Boolean(args.env[sKeys.accessKeyId] && args.env[sKeys.secretAccessKey]);
+	const haveApiToken = !args.needApiToken || Boolean(args.env[aKeys.apiKey]);
+	if (haveStorage && haveApiToken) return {
+		accessKeyId: args.env[sKeys.accessKeyId] ?? "",
+		secretAccessKey: args.env[sKeys.secretAccessKey] ?? "",
+		apiToken: args.env[aKeys.apiKey] ?? ""
+	};
+	const minted = await args.api.createCredential(args.projectId, args.branchId, {
+		scopes: args.scopes,
+		principalType: "user",
+		name: `neon-env ${args.branchName}`
+	});
+	return {
+		accessKeyId: minted.tokenId,
+		secretAccessKey: minted.s3SecretAccessKey,
+		apiToken: minted.apiToken
+	};
+}
+/**
+* The AI Gateway is a **branch-scoped host** — `<branchId>-api.ai.<host-suffix>` — NOT the
+* control-plane API origin. Derive the suffix from the branch's own Postgres connection host
+* by dropping only the endpoint label (the first segment) and keeping everything after it,
+* including any infra cell prefix (`c-N.`): a connection host of
+* `ep-x.c-3.us-east-2.aws.neon.tech` yields the gateway host
+* `<branchId>-api.ai.c-3.us-east-2.aws.neon.tech`. The cell prefix is **load-bearing** —
+* the gateway is cell-routed, so dropping `c-N.` resolves to the wrong (or no) host.
+*/
+function aiGatewayHost(branchId, connectionUri) {
+	let connectionHost = "";
+	try {
+		connectionHost = new URL(connectionUri).hostname;
+	} catch {
+		connectionHost = "";
+	}
+	return `${branchId}-api.ai.${connectionHost.split(".").slice(1).join(".")}`;
+}
+/** The AI Gateway's OpenAI-dialect base URL (`OPENAI_BASE_URL`) on the branch gateway host. */
+function aiGatewayBaseUrl(branchId, connectionUri) {
+	return `https://${aiGatewayHost(branchId, connectionUri)}${AI_GATEWAY_OPENAI_PATH}`;
+}
+/**
+* Resolve the Neon Auth base URL to surface in `env.auth`. Prefer the value returned by
+* the integration (`getNeonAuth` includes it); fall back to whatever is already in the
+* caller's env source so older integrations created before `base_url` was returned still
+* round-trip through `env run`.
+*/
+function resolveAuthBaseUrl(snapshotBaseUrl, source) {
+	if (snapshotBaseUrl && snapshotBaseUrl !== "") return snapshotBaseUrl;
+	return source[NEON_ENV_VAR_KEYS.auth.baseUrl] ?? "";
+}
+/**
+* Resolve the Neon Auth JWKS URL to surface in `env.auth`. Prefer the value returned by the
+* integration (`getNeonAuth` always includes `jwks_url`); fall back to the caller's env
+* source so the value still round-trips through `env run` if a snapshot ever omits it.
+*/
+function resolveAuthJwksUrl(snapshotJwksUrl, source) {
+	if (snapshotJwksUrl && snapshotJwksUrl !== "") return snapshotJwksUrl;
+	return source[NEON_ENV_VAR_KEYS.auth.jwksUrl] ?? "";
+}
+function createApiFromOptions(options) {
+	return createNeonApiFromOptions("fetchEnv", {
+		...options.apiKey ? { apiKey: options.apiKey } : {},
+		...options.apiHost ? { apiHost: options.apiHost } : {}
+	});
+}
+function resolveBranch(branchId, branches) {
+	const match = branches.find((b) => b.id === branchId);
+	if (match) return match;
+	throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch id ${JSON.stringify(branchId)} not found on project.`, `Existing branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ")}.`].join(" "), { details: {
+		branchId,
+		available: branches.map((b) => b.id)
+	} });
+}
+function pickRoleName(roles, branch, requested) {
+	if (requested) {
+		if (!roles.some((r) => r.name === requested)) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: role "${requested}" not found on branch ${branch.name} (${branch.id}).`, `Existing roles: ${roles.map((r) => r.name).join(", ") || "(none)"}.`].join(" "), { details: {
+			branchId: branch.id,
+			roleName: requested,
+			availableRoles: roles.map((r) => r.name)
+		} });
+		return requested;
+	}
+	if (roles.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${branch.name} (${branch.id}) has no roles.`, "Create one via the Neon console or pass `roleName` explicitly."].join(" "), { details: { branchId: branch.id } });
+	if (roles.length === 1) return roles[0].name;
+	const owner = roles.find((r) => r.name === NEON_DEFAULT_OWNER_ROLE);
+	if (owner) return owner.name;
+	const appRoles = roles.filter((r) => !NEON_MANAGED_AUTH_ROLES.has(r.name));
+	if (appRoles.length === 1) return appRoles[0].name;
+	throw new PlatformError(ErrorCode.AmbiguousBranchAuth, [`fetchEnv: branch ${branch.name} (${branch.id}) has ${roles.length} roles and none is "${NEON_DEFAULT_OWNER_ROLE}"; cannot auto-pick.`, `Pass \`roleName\` explicitly. Available: ${roles.map((r) => r.name).join(", ")}.`].join(" "), { details: {
+		branchId: branch.id,
+		availableRoles: roles.map((r) => r.name)
+	} });
+}
+function pickDatabaseName(databases, branch, roleName, requested) {
+	if (requested) {
+		if (!databases.some((d) => d.name === requested)) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: database "${requested}" not found on branch ${branch.name} (${branch.id}).`, `Existing databases: ${databases.map((d) => d.name).join(", ") || "(none)"}.`].join(" "), { details: {
+			branchId: branch.id,
+			databaseName: requested,
+			availableDatabases: databases.map((d) => d.name)
+		} });
+		return requested;
+	}
+	if (databases.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${branch.name} (${branch.id}) has no databases.`, "Create one via the Neon console or pass `databaseName` explicitly."].join(" "), { details: { branchId: branch.id } });
+	if (databases.length === 1) return databases[0].name;
+	const owned = databases.filter((d) => d.ownerName === roleName);
+	if (owned.length === 1) return owned[0].name;
+	throw new PlatformError(ErrorCode.AmbiguousBranchAuth, [`fetchEnv: branch ${branch.name} (${branch.id}) has ${databases.length} databases; cannot auto-pick.`, `Pass \`databaseName\` explicitly. Available: ${databases.map((d) => d.name).join(", ")}.`].join(" "), { details: {
+		branchId: branch.id,
+		availableDatabases: databases.map((d) => d.name)
+	} });
+}
+/**
+* Per-namespace zod schemas. Each defines exactly the OS-level keys parsed from
+* `process.env` for its namespace. Keep in sync with {@link NEON_ENV_VAR_KEYS}.
+*
+* `z.string().url()` would be tighter than `min(1)` but Postgres URIs that include
+* URL-illegal characters in the password (rare but legal in Neon's connection-string
+* format) fail the WHATWG `URL` parse, so we settle for "non-empty string".
+*/
+const postgresEnvSchema = z.object({
+	DATABASE_URL: z.string({ message: "DATABASE_URL is missing" }).min(1, "DATABASE_URL must not be empty"),
+	DATABASE_URL_UNPOOLED: z.string({ message: "DATABASE_URL_UNPOOLED is missing" }).min(1, "DATABASE_URL_UNPOOLED must not be empty")
+});
+const authEnvSchema = z.object({
+	NEON_AUTH_BASE_URL: z.string({ message: "NEON_AUTH_BASE_URL is missing" }).min(1, "NEON_AUTH_BASE_URL must not be empty"),
+	NEON_AUTH_JWKS_URL: z.string({ message: "NEON_AUTH_JWKS_URL is missing" }).min(1, "NEON_AUTH_JWKS_URL must not be empty")
+});
+const dataApiEnvSchema = z.object({ NEON_DATA_API_URL: z.string({ message: "NEON_DATA_API_URL is missing" }).min(1, "NEON_DATA_API_URL must not be empty") });
+const storageEnvSchema = z.object({
+	AWS_ACCESS_KEY_ID: z.string({ message: "AWS_ACCESS_KEY_ID is missing" }).min(1, "AWS_ACCESS_KEY_ID must not be empty"),
+	AWS_SECRET_ACCESS_KEY: z.string({ message: "AWS_SECRET_ACCESS_KEY is missing" }).min(1, "AWS_SECRET_ACCESS_KEY must not be empty"),
+	AWS_ENDPOINT_URL_S3: z.string({ message: "AWS_ENDPOINT_URL_S3 is missing" }).min(1, "AWS_ENDPOINT_URL_S3 must not be empty"),
+	AWS_REGION: z.string({ message: "AWS_REGION is missing" }).min(1, "AWS_REGION must not be empty")
+});
+const aiGatewayEnvSchema = z.object({
+	OPENAI_API_KEY: z.string({ message: "OPENAI_API_KEY is missing" }).min(1, "OPENAI_API_KEY must not be empty"),
+	OPENAI_BASE_URL: z.string({ message: "OPENAI_BASE_URL is missing" }).min(1, "OPENAI_BASE_URL must not be empty")
+});
+/** Whether a **static** policy declares object storage (`preview.buckets`). No network. */
+function configWantsStorage(config) {
+	return Object.keys(config.preview?.buckets ?? {}).length > 0;
+}
+/** Whether a **static** policy enables the AI Gateway (`preview.aiGateway`). No network. */
+function configWantsAiGateway(config) {
+	return isServiceEnabledInput(config.preview?.aiGateway);
+}
+/** Static-toggle helper mirroring `config`'s `isServiceEnabled` for the env reader. */
+function isServiceEnabledInput(toggle) {
+	if (toggle === void 0) return false;
+	if (typeof toggle === "boolean") return toggle;
+	return toggle.enabled !== false;
+}
+function parseEnv(config, scopeOrKeys) {
+	const source = process.env;
+	if (Array.isArray(scopeOrKeys)) return parseFilteredEnv(source, scopeOrKeys);
+	const scope = typeof scopeOrKeys === "string" ? scopeOrKeys : void 0;
+	const issues = [];
+	const result = {};
+	const pg = postgresEnvSchema.safeParse({
+		DATABASE_URL: source.DATABASE_URL,
+		DATABASE_URL_UNPOOLED: source.DATABASE_URL_UNPOOLED
+	});
+	if (pg.success) result.postgres = {
+		databaseUrl: pg.data.DATABASE_URL,
+		databaseUrlUnpooled: pg.data.DATABASE_URL_UNPOOLED
+	};
+	else for (const issue of pg.error.issues) issues.push(issue.message);
+	const branchName = source[NEON_ENV_VAR_KEYS.branch.name];
+	if (branchName !== void 0 && branchName !== "") result.branch = { name: branchName };
+	if (isServiceEnabledInput(config.auth)) {
+		const auth = authEnvSchema.safeParse({
+			NEON_AUTH_BASE_URL: source.NEON_AUTH_BASE_URL,
+			NEON_AUTH_JWKS_URL: source.NEON_AUTH_JWKS_URL
+		});
+		if (auth.success) result.auth = {
+			baseUrl: auth.data.NEON_AUTH_BASE_URL,
+			jwksUrl: auth.data.NEON_AUTH_JWKS_URL
+		};
+		else for (const issue of auth.error.issues) issues.push(issue.message);
+	}
+	if (isServiceEnabledInput(config.dataApi)) {
+		const dataApi = dataApiEnvSchema.safeParse({ NEON_DATA_API_URL: source.NEON_DATA_API_URL });
+		if (dataApi.success) result.dataApi = { url: dataApi.data.NEON_DATA_API_URL };
+		else for (const issue of dataApi.error.issues) issues.push(issue.message);
+	}
+	if (configWantsStorage(config)) {
+		const storage = storageEnvSchema.safeParse({
+			AWS_ACCESS_KEY_ID: source.AWS_ACCESS_KEY_ID,
+			AWS_SECRET_ACCESS_KEY: source.AWS_SECRET_ACCESS_KEY,
+			AWS_ENDPOINT_URL_S3: source.AWS_ENDPOINT_URL_S3,
+			AWS_REGION: source.AWS_REGION
+		});
+		if (storage.success) result.storage = {
+			accessKeyId: storage.data.AWS_ACCESS_KEY_ID,
+			secretAccessKey: storage.data.AWS_SECRET_ACCESS_KEY,
+			endpoint: storage.data.AWS_ENDPOINT_URL_S3,
+			region: storage.data.AWS_REGION
+		};
+		else for (const issue of storage.error.issues) issues.push(issue.message);
+	}
+	if (configWantsAiGateway(config)) {
+		const aiGateway = aiGatewayEnvSchema.safeParse({
+			OPENAI_API_KEY: source.OPENAI_API_KEY,
+			OPENAI_BASE_URL: source.OPENAI_BASE_URL
+		});
+		if (aiGateway.success) result.aiGateway = {
+			apiKey: aiGateway.data.OPENAI_API_KEY,
+			baseUrl: aiGateway.data.OPENAI_BASE_URL
+		};
+		else for (const issue of aiGateway.error.issues) issues.push(issue.message);
+	}
+	if (scope !== void 0) {
+		const fn = config.preview?.functions?.[scope];
+		if (!fn) throw new PlatformError(ErrorCode.EnvNotInjected, [`parseEnv: no function "${scope}" is declared in this policy's preview.functions.`, "Pass a declared function slug (or omit the scope to read external env)."].join("\n"), { details: { scope } });
+		const envOut = {};
+		for (const key of Object.keys(fn.env ?? {})) {
+			const value = source[key];
+			if (value === void 0) issues.push(`${key} is missing (function "${scope}")`);
+			else envOut[key] = value;
+		}
+		result.function = envOut;
+	}
+	if (issues.length > 0) throw new PlatformError(ErrorCode.EnvNotInjected, [
+		"parseEnv: the required Neon env variables are not present in process.env.",
+		...issues.map((i) => `  - ${i}`),
+		"Inject them via one of:",
+		"  - `neon dev` / `neon-env run -- <your dev command>` (wraps the command with the vars injected)",
+		"  - your hosting platform's Neon integration (Vercel, Fly, Railway, …)",
+		"  - for the `function` namespace: deploy the function (`neon deploy` / `config apply`) so its env is uploaded.",
+		"Or switch the call to `await fetchEnv(config, …)` if you're in a context that can do async I/O."
+	].join("\n"), { details: { missing: issues } });
+	return result;
+}
+/**
+* Runtime reverse map for filtered `parseEnv`: OS-level env-var key → `[namespace, property]`
+* in the {@link NeonEnv} shape. The compile-time mirror is {@link EnvKeysByNamespace} /
+* {@link EnvKeyToProp}; keep all three in sync. Only input vars appear (no output-only
+* aliases).
+*/
+const FILTERABLE_ENV_KEYS = {
+	DATABASE_URL: ["postgres", "databaseUrl"],
+	DATABASE_URL_UNPOOLED: ["postgres", "databaseUrlUnpooled"],
+	NEON_AUTH_BASE_URL: ["auth", "baseUrl"],
+	NEON_AUTH_JWKS_URL: ["auth", "jwksUrl"],
+	NEON_DATA_API_URL: ["dataApi", "url"],
+	AWS_ACCESS_KEY_ID: ["storage", "accessKeyId"],
+	AWS_SECRET_ACCESS_KEY: ["storage", "secretAccessKey"],
+	AWS_ENDPOINT_URL_S3: ["storage", "endpoint"],
+	AWS_REGION: ["storage", "region"],
+	OPENAI_API_KEY: ["aiGateway", "apiKey"],
+	OPENAI_BASE_URL: ["aiGateway", "baseUrl"]
+};
+/**
+* Filtered counterpart to the {@link parseEnv} body: validate and return only the explicitly
+* selected OS-level env-var keys, projected back into the narrowed namespaced shape. Unlike
+* the full reader it never consults the policy — the selection alone decides what's required —
+* so vars the caller didn't ask for (e.g. `DATABASE_URL_UNPOOLED`) can be absent without
+* throwing. Mirrors the same non-empty constraint and {@link PlatformError} aggregation.
+*/
+function parseFilteredEnv(source, keys) {
+	const issues = [];
+	const result = {};
+	for (const key of keys) {
+		if (!Object.hasOwn(FILTERABLE_ENV_KEYS, key)) {
+			issues.push(`${key} is not a selectable Neon env variable`);
+			continue;
+		}
+		const value = source[key];
+		if (value === void 0) {
+			issues.push(`${key} is missing`);
+			continue;
+		}
+		if (value === "") {
+			issues.push(`${key} must not be empty`);
+			continue;
+		}
+		const [namespace, property] = FILTERABLE_ENV_KEYS[key];
+		const bucket = result[namespace] ?? {};
+		bucket[property] = value;
+		result[namespace] = bucket;
+	}
+	if (issues.length > 0) throw new PlatformError(ErrorCode.EnvNotInjected, [
+		"parseEnv: the required Neon env variables are not present in process.env.",
+		...issues.map((i) => `  - ${i}`),
+		"Inject them via one of:",
+		"  - `neon dev` / `neon-env run -- <your dev command>` (wraps the command with the vars injected)",
+		"  - your hosting platform's Neon integration (Vercel, Fly, Railway, …)",
+		"Or switch the call to `await fetchEnv(config, …)` if you're in a context that can do async I/O."
+	].join("\n"), { details: { missing: issues } });
+	return result;
+}
+/**
+* Project a fully-resolved {@link NeonEnv} into the OS-level `{ KEY: value }` pairs used
+* for cross-process transport. Named after the web-platform `.entries()` convention
+* (`URLSearchParams` / `Headers` / `FormData`); returns a `Record` rather than an
+* iterator of tuples since that's the shape env injection needs (wrap with
+* `Object.entries(...)` if you want literal `[key, value]` pairs). Used by `neon-env run`
+* to inject the vars into a subprocess's `process.env`.
+*
+* Walks the value at runtime so it works for any `NeonEnv<C>` regardless of which
+* conditional namespaces are present.
+*/
+function toEntries(env) {
+	const out = {
+		[NEON_ENV_VAR_KEYS.postgres.databaseUrl]: env.postgres.databaseUrl,
+		[NEON_ENV_VAR_KEYS.postgres.databaseUrlUnpooled]: env.postgres.databaseUrlUnpooled
+	};
+	if (env.branch) out[NEON_ENV_VAR_KEYS.branch.name] = env.branch.name;
+	const withAuth = env;
+	if (withAuth.auth) {
+		out[NEON_ENV_VAR_KEYS.auth.baseUrl] = withAuth.auth.baseUrl;
+		out[NEON_ENV_VAR_KEYS.auth.jwksUrl] = withAuth.auth.jwksUrl;
+	}
+	const withDataApi = env;
+	if (withDataApi.dataApi) out[NEON_ENV_VAR_KEYS.dataApi.url] = withDataApi.dataApi.url;
+	const withStorage = env;
+	if (withStorage.storage) {
+		const s = withStorage.storage;
+		const keys = NEON_ENV_VAR_KEYS.storage;
+		out[keys.accessKeyId] = s.accessKeyId;
+		out[keys.secretAccessKey] = s.secretAccessKey;
+		out[keys.endpoint] = s.endpoint;
+		out[keys.region] = s.region;
+	}
+	const withAiGateway = env;
+	if (withAiGateway.aiGateway) {
+		const keys = NEON_ENV_VAR_KEYS.aiGateway;
+		const ai = withAiGateway.aiGateway;
+		out[keys.apiKey] = ai.apiKey;
+		out[keys.baseUrl] = ai.baseUrl;
+		out[keys.neonToken] = ai.apiKey;
+		out[keys.neonBaseUrl] = new URL(ai.baseUrl).origin;
+	}
+	return out;
+}
+//#endregion
+export { NEON_ENV_VAR_KEYS, fetchEnv, parseEnv, toEntries };
+
+//# sourceMappingURL=env.js.map