@neondatabase/env 1.1.5 → 1.2.0

package/README.md

@@ -41,6 +41,7 @@ const env2 = parseEnv(config);
 // Inside a deployed function, pass its slug for the typed `function` namespace:
 const fnEnv = parseEnv(config, "hello");
 fnEnv.function.resendApiKey; // typed from hello's declared env keys
+fnEnv.functions.hello.baseUrl;
 
 // Key filter — only enforce + return the vars you actually use (e.g. a Next.js app that
 // reads the pooled URL but not the unpooled one). The keys autocomplete from the policy, so
@@ -54,7 +55,7 @@ Both return the same namespaced `NeonEnv` shape: `postgres` is always present; `
 | Function | Description |
 | --- | --- |
 | `fetchEnv(config, { projectId, branch, ... })` | Async. Calls the Neon API for the given project + branch and returns live connection strings (and Auth/Data API values when enabled). `projectId` and `branch` are required; `branch` accepts a branch **name** (e.g. `main`) or a `br-…` id. (The legacy id-only `branchId` option still works.) Pass `keys` to fetch only some vars — see [Fetching a subset](#fetching-a-subset). Reads nothing from `process.env` or disk. |
-| `parseEnv(config)` / `parseEnv(config, slug)` / `parseEnv(config, keys)` | Sync. Reads/validates the Neon env vars already present in `process.env` against the static policy toggles. With a function `slug`, also returns a typed `function` namespace of that function's declared env keys. With a `keys` array (e.g. `["DATABASE_URL"]`), only those vars are required and returned, as a narrowed namespaced shape — the keys are typesafe against the policy. Throws `PlatformError(EnvNotInjected)` listing missing vars when the env isn't populated. |
+| `parseEnv(config)` / `parseEnv(config, slug)` / `parseEnv(config, keys)` | Sync. Reads/validates the Neon env vars already present in `process.env` against the static policy toggles. With a function `slug`, also returns a typed `function` namespace of that function's declared env keys; `functions.<slug>.baseUrl` is the invocation URL. With a `keys` array (e.g. `["DATABASE_URL"]`), only those vars are required and returned, as a narrowed namespaced shape — the keys are typesafe against the policy. Throws `PlatformError(EnvNotInjected)` listing missing vars when the env isn't populated. |
 | `toEntries(env)` | Project a resolved `NeonEnv` into `{ KEY: value }` pairs for cross-process transport (named after the web `.entries()` convention; returns a `Record`). |
 
 ## CLI
@@ -68,7 +69,7 @@ neon-env run -- npm run dev
 neon-env run -- pnpm dev
 ```
 
-`run` loads `neon.ts`, resolves the branch (via `--branch`, `NEON_BRANCH` / `NEON_BRANCH_ID`, or the `branch` field in `.neon[/project.json]` — by name or id), fetches the connection strings from Neon, and spawns the command with `NEON_BRANCH` / `DATABASE_URL` / `DATABASE_URL_UNPOOLED` (plus the Auth, Data API, object-storage `AWS_*`, and AI Gateway `NEON_AI_GATEWAY_*` vars when the policy enables them — see [Env vars produced](#env-vars-produced)) injected on top of the inherited environment. Stdio is inherited so interactive dev servers keep working, and the parent exits with the child's exit code.
+`run` loads `neon.ts`, resolves the branch (via `--branch`, `NEON_BRANCH` / `NEON_BRANCH_ID`, or the `branch` field in `.neon[/project.json]` — by name or id), fetches the connection strings from Neon, and spawns the command with `NEON_BRANCH` / `DATABASE_URL` / `DATABASE_URL_UNPOOLED` (plus the Auth, Data API, object-storage `AWS_*`, AI Gateway `NEON_AI_GATEWAY_*`, and function `NEON_FUNCTION_*_BASE_URL` vars when the policy enables them — see [Env vars produced](#env-vars-produced)) injected on top of the inherited environment. Stdio is inherited so interactive dev servers keep working, and the parent exits with the child's exit code.
 
 ### `export` — print env to stdout
 
@@ -136,6 +137,20 @@ These are the OS-level vars `fetchEnv` / `parseEnv` read and `toEntries` (so `ne
 | `NEON_AI_GATEWAY_TOKEN` | branch credential's API token (bearer) |
 | `NEON_AI_GATEWAY_BASE_URL` | bare branch gateway host (`https://<branch>-api.ai.<region>.…`, no path) |
 
+**Functions** (Preview — when `preview.functions` declares at least one slug). Each declared slug requires `NEON_FUNCTION_<SLUG>_BASE_URL`, typed as `env.functions.<slug>.baseUrl: string`. These are the public function URLs, not the function's declared `env` secrets (those are uploaded at deploy). `fetchEnv` / `neon env pull` derive the URL from the branch connection host; the function does not have to be deployed. `parseEnv` requires the var to be a URL. `neon dev` injects `http://localhost:<port>` instead.
+
+| Key | From |
+| --- | --- |
+| `NEON_FUNCTION_<SLUG>_BASE_URL` | the function's public URL (`https://<branchId>-<slug>.compute.…`), or `http://localhost:<port>` under `neon dev`. `<SLUG>` is the slug uppercased. |
+
+```ts
+const env = parseEnv(config);
+env.functions.hello.baseUrl; // string
+
+const { functions } = await fetchEnv(config, { projectId, branch: "main" });
+functions.hello.baseUrl; // string
+```
+
 ### The branch credential
 
 Object storage and the AI Gateway are backed by one branch credential, and the Neon API returns its secrets (`s3_secret_access_key`, `api_token`) **once**, at mint time — they aren't stored server-side, and the list endpoint returns metadata only. So there is nothing to *fetch*: `fetchEnv` mints. Call it on every `neon dev` start and you leave a live credential behind each time.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as previewCredentialScopes, i as credentialName, l as resolveBranchPolicy, n as createApiFromOptions, o as fetchEnvKeys, r as credentialEnvKeys, s as policyEnvKeys, t as NEON_ENV_VAR_KEYS, u as toEntries } from "./env.js";
+import { c as isFunctionBaseUrlKey, d as previewCredentialScopes, f as resolveBranchPolicy, i as credentialName, n as createApiFromOptions, o as fetchEnvKeysState, p as toEntries, r as credentialEnvKeys, t as NEON_ENV_VAR_KEYS, u as policyEnvKeys } from "./env.js";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -50,7 +50,7 @@ async function fetchEnvReusingSecrets(config, options) {
 	const { branch, desired } = await resolveBranchPolicy(config, options, api);
 	const allPolicyKeys = policyEnvKeys(desired);
 	const requested = requestedKeys ? new Set(requestedKeys) : null;
-	const selectedPolicyKeys = requested === null ? allPolicyKeys : allPolicyKeys.filter((key) => requested.has(key));
+	const selectedPolicyKeys = requested === null ? allPolicyKeys : [...allPolicyKeys.filter((key) => requested.has(key)), ...[...requested].filter(isFunctionBaseUrlKey).sort()];
 	const selected = new Set(selectedPolicyKeys);
 	const K = NEON_ENV_VAR_KEYS;
 	const storageCredentialSelected = (desired.preview?.buckets.length ?? 0) > 0 && (selected.has(K.storage.accessKeyId) || selected.has(K.storage.secretAccessKey));
@@ -60,15 +60,16 @@ async function fetchEnvReusingSecrets(config, options) {
 		aiGateway: gatewayCredentialSelected
 	}).filter((key) => selected.has(key));
 	if (secretKeys.length === 0) {
-		const fetched = await fetchEnvKeys(config, fetchOptions, requested === null ? null : selectedPolicyKeys);
+		const fetched = await fetchEnvKeysState(config, fetchOptions, requested === null ? null : selectedPolicyKeys);
 		return {
-			vars: preferPersisted(toEntries(fetched), source),
+			vars: preferPersisted(toEntries(fetched.env), source),
 			credential: {
 				issued: false,
 				keys: [],
 				revoked: [],
 				superseded: []
-			}
+			},
+			...fetched.functionUrlsUnavailable ? { functionUrlsUnavailable: true } : {}
 		};
 	}
 	const persisted = readPersistedSecrets(source);
@@ -88,13 +89,15 @@ async function fetchEnvReusingSecrets(config, options) {
 		aiGateway: gatewayCredentialSelected
 	});
 	const keep = reusable !== null && credentialScopesSatisfied(reusable.scopes, scopes);
-	const fetchKeys = keep ? selectedPolicyKeys.filter((key) => !secretKeys.includes(key)) : selectedPolicyKeys;
-	const fetched = await fetchEnvKeys(config, {
+	const fetchKeys = requested === null ? null : keep ? selectedPolicyKeys.filter((key) => !secretKeys.includes(key)) : selectedPolicyKeys;
+	const fetched = await fetchEnvKeysState(config, {
 		...fetchOptions,
 		branchId: branch.id,
-		api
+		api,
+		...keep && requested === null ? { omitKeys: secretKeys } : {}
 	}, fetchKeys);
-	const vars = preferPersisted(toEntries(fetched), source);
+	const vars = preferPersisted(toEntries(fetched.env), source);
+	const unavailable = fetched.functionUrlsUnavailable ? { functionUrlsUnavailable: true } : {};
 	if (keep) {
 		for (const key of secretKeys) {
 			const value = source[key];
@@ -107,7 +110,8 @@ async function fetchEnvReusingSecrets(config, options) {
 				keys: secretKeys,
 				revoked: [],
 				superseded: []
-			}
+			},
+			...unavailable
 		};
 	}
 	const ours = /* @__PURE__ */ new Set();
@@ -120,7 +124,8 @@ async function fetchEnvReusingSecrets(config, options) {
 			keys: secretKeys,
 			revoked: revokeSuperseded ? [...ours] : [],
 			superseded: revokeSuperseded ? [] : [...ours]
-		}
+		},
+		...unavailable
 	};
 }
 /** Read the branch credential's secrets out of an env source. */
@@ -727,7 +732,7 @@ const createCredentialStore = (dir, options = {}) => {
 	const assertKeyringWritable = (profile) => {
 		if (keyring === null) throw new KeyringUnavailableError(profile, "write");
 	};
-	const setKeyringOrRollback = (profile, credentials) => {
+	const setKeyringOrRollback = (profile, credentials, restorePrevious) => {
 		assertKeyringWritable(profile);
 		const kr = keyring;
 		if (kr === null) throw new KeyringUnavailableError(profile, "write");
@@ -747,7 +752,7 @@ const createCredentialStore = (dir, options = {}) => {
 		try {
 			if (kr.get("com.neon.neon-cli", account) === null) throw new Error(`Wrote credentials to the OS keyring for ${label} but could not read them back.`);
 		} catch (err) {
-			if (previous !== null) {
+			if (restorePrevious && previous !== null) {
 				try {
 					kr.set(KEYRING_SERVICE, account, previous);
 				} catch {
@@ -863,9 +868,9 @@ const createCredentialStore = (dir, options = {}) => {
 			profile: at.profile
 		};
 	};
-	const write = (at, credentials) => {
+	const write = (at, credentials, options) => {
 		if (at.storage === "keyring") {
-			setKeyringOrRollback(at.profile, credentials);
+			setKeyringOrRollback(at.profile, credentials, options?.restorePrevious !== false);
 			return {
 				credentials,
 				backend: CRED_STORAGE_KEYRING,