neon 3.0.0 → 3.1.0

package/README.md

@@ -743,6 +743,59 @@ neon snapshots schedule set --branch main --schedule '[{"frequency":"weekly","da
 
 All sub-commands honor the [global options](#global-options), including `--output json|yaml|table`.
 
+## Logs (`logs`)
+
+`neon logs` reads the log records the services on a branch emit — Neon Functions, object storage, and Postgres computes. **Logs require Neon Platform Beta and are currently available only for projects in `aws-us-east-2`.**
+
+Every sub-command resolves the project through the standard chain (`--project-id`, then the `.neon` context file, then a single-project auto-detect), and takes `--branch <id|name>`, defaulting to the project's default branch. `logs query` searches the previous hour by default; `logs field-values` searches the previous six hours. The maximum time window is seven days.
+
+```bash
+# The last 30 minutes on the default branch
+neon logs query --since 30m
+
+# Postgres compute errors on main, oldest first
+neon logs query --branch main --source pg_endpoint --minimum-severity error --sort-order asc
+
+# An explicit window (--start-time replaces --since; --end-time works with either)
+neon logs query --start-time 2025-01-01T00:00:00Z --end-time 2025-01-01T01:00:00Z
+
+# One request trace, across every service that took part in it
+neon logs query --trace-id 4bf92f3577b34da6a3ce929d0e0e4736
+
+# What the structured filters cannot express: a raw LogQL selection. It replaces
+# them, but the window, --limit, --sort-order and --cursor still apply.
+neon logs query --since 1h --logql '{entity_type="function"} |= "timeout"'
+
+# Which fields this branch supports, and the values it has actually seen
+neon logs fields
+neon logs field-values service_name --since 6h --source function
+```
+
+A response holds at most `--limit` records (1–1000; default 100). When more matched, table output prints the `--cursor` to repeat the same query with; `--output json|yaml` returns `is_truncated` and `next_cursor` on the envelope instead, so nothing but the payload lands on stdout. Table output shows the common fields; use structured output for the complete records:
+
+```console
+$ neon logs query --since 24h --output json
+{
+  "logs": [
+    {
+      "timestamp": "2025-01-01T00:00:02.000Z",
+      "message": "GET /api/todos 200",
+      "source": "function",
+      "service_name": "api",
+      "severity_text": "INFO",
+      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "attributes": { "http_status": 200 }
+    }
+  ],
+  "next_cursor": "eyJvZmZzZXQiOjEwMH0",
+  "is_truncated": true
+}
+```
+
+Two combinations are rejected before the request: `--since` with `--start-time`, and `--logql` with any of `--source`, `--service-name`, `--scope-name`, `--minimum-severity`, `--severity-text`, `--body-contains` or `--trace-id`. `--minimum-severity` and `--severity-text` are independent filters and combine with AND. If Neon reports that `--minimum-severity` is unsupported, use `--severity-text` instead; `neon logs field-values severity_text` lists the exact values present on a branch.
+
+`--body-contains` compares a case-sensitive substring against the rendered message. Structured bodies, including object storage records, are rendered as compact JSON, so match the JSON form (for example, `"http_status":200`).
+
 ## Profiles
 
 The CLI holds one Neon account by default. A profile adds another, and is nothing more than a pointer to a credentials file:
@@ -971,6 +1024,7 @@ API keys in org-7
 | function                                                                   | `deploy`, `list`, `get`, `delete`                                                                            | Manage Neon Functions              |
 | [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                                   | Manage roles                       |
 | [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                                       | Manage operations                  |
+| logs                                                                       | `query`, `fields`, `field-values`                                                                            | Query branch logs (Beta)           |
 | snapshots                                                                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `finalize`, `schedule get`, `schedule set`           | Manage snapshots                   |
 | [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                                              | Get connection string              |
 | [psql](https://neon.com/docs/reference/cli-psql)                           |                                                                                                              | Connect to a database via psql     |

package/dist/_shared/auth_selection.js

@@ -1,86 +1,83 @@
+import "./profiles.js";
+//#region src/_shared/auth_selection.ts
 /**
- * # Which credential an invocation authenticates with
- *
- * Four inputs can each answer "who am I": the `--api-key` flag, `NEON_API_KEY`, the
- * `--profile` flag, and `NEON_PROFILE`. This module decides between them, and it is pure so
- * the decision can be tested without a filesystem, a network, or a config directory.
- *
- * ## The rule
- *
- * **An explicit flag beats an ambient environment variable.** That single rule fixes the bug
- * this module exists for: before it, any API key — including one merely exported into the
- * shell — silently voided `--profile`, so `neon --profile work …` would quietly run as
- * whoever `NEON_API_KEY` belonged to and say nothing about it.
- *
- * | Given | What runs |
- * | --- | --- |
- * | `--api-key` and `--profile` | neither: contradictory explicit flags, so this throws |
- * | `--api-key` and `NEON_PROFILE` | the flag's key |
- * | `--profile` and `NEON_API_KEY` | the profile |
- * | `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
- * | `--profile` or `NEON_PROFILE` alone | that profile |
- * | nothing | `DEFAULT` |
- *
- * Two explicit flags throw rather than picking a winner. They express different intents —
- * `--api-key` supplies a credential, `--profile` selects a stored one — so there is no
- * reading of the command that makes both true, and guessing is how the original bug behaved.
- *
- * When both are merely ambient, the key wins. That keeps CI exactly as it was: a pipeline
- * that injects `NEON_API_KEY` must not change behaviour because a `NEON_PROFILE` leaked into
- * the environment. It warns instead of staying silent, because a disregarded account
- * selection is precisely what nobody noticed last time.
- *
- * `auth` and the `profile` subcommands do not use any of this. They read the same flags with
- * different meanings — `neon auth --profile work` names where to *write* a credential, and
- * `neon profile create work --api-key …` names one to *store* — so their callers skip
- * selection entirely rather than passing exemptions down here.
- */
-import { DEFAULT_PROFILE } from "./profiles.js";
-const NO_INPUTS = {
-    apiKeyFlag: "",
-    apiKeyEnv: "",
-    profileEnv: "",
+* # Which credential an invocation authenticates with
+*
+* Four inputs can each answer "who am I": the `--api-key` flag, `NEON_API_KEY`, the
+* `--profile` flag, and `NEON_PROFILE`. This module decides between them, and it is pure so
+* the decision can be tested without a filesystem, a network, or a config directory.
+*
+* ## The rule
+*
+* **An explicit flag beats an ambient environment variable.** That single rule fixes the bug
+* this module exists for: before it, any API key — including one merely exported into the
+* shell — silently voided `--profile`, so `neon --profile work …` would quietly run as
+* whoever `NEON_API_KEY` belonged to and say nothing about it.
+*
+* | Given | What runs |
+* | --- | --- |
+* | `--api-key` and `--profile` | neither: contradictory explicit flags, so this throws |
+* | `--api-key` and `NEON_PROFILE` | the flag's key |
+* | `--profile` and `NEON_API_KEY` | the profile |
+* | `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
+* | `--profile` or `NEON_PROFILE` alone | that profile |
+* | nothing | `DEFAULT` |
+*
+* Two explicit flags throw rather than picking a winner. They express different intents —
+* `--api-key` supplies a credential, `--profile` selects a stored one — so there is no
+* reading of the command that makes both true, and guessing is how the original bug behaved.
+*
+* When both are merely ambient, the key wins. That keeps CI exactly as it was: a pipeline
+* that injects `NEON_API_KEY` must not change behaviour because a `NEON_PROFILE` leaked into
+* the environment. It warns instead of staying silent, because a disregarded account
+* selection is precisely what nobody noticed last time.
+*
+* `auth` and the `profile` subcommands do not use any of this. They read the same flags with
+* different meanings — `neon auth --profile work` names where to *write* a credential, and
+* `neon profile create work --api-key …` names one to *store* — so their callers skip
+* selection entirely rather than passing exemptions down here.
+*/
+let inputs = {
+	apiKeyFlag: "",
+	apiKeyEnv: "",
+	profileEnv: ""
 };
-let inputs = NO_INPUTS;
-export const recordCredentialInputs = (recorded) => {
-    inputs = recorded;
+const recordCredentialInputs = (recorded) => {
+	inputs = recorded;
 };
-export const credentialInputs = () => inputs;
-export const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv, }) => {
-    const flagKey = nonEmpty(apiKeyFlag);
-    const flagProfile = nonEmpty(profileFlag);
-    if (flagKey !== undefined && flagProfile !== undefined) {
-        throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
-    }
-    if (flagKey !== undefined) {
-        return { source: "explicit-api-key", apiKey: flagKey };
-    }
-    if (flagProfile !== undefined) {
-        return { source: "profile", profile: flagProfile, explicit: true };
-    }
-    const envKey = nonEmpty(apiKeyEnv);
-    const envProfile = nonEmpty(profileEnv);
-    if (envKey !== undefined) {
-        return {
-            source: "ambient-api-key",
-            apiKey: envKey,
-            ...(envProfile !== undefined ? { ignoredProfile: envProfile } : {}),
-        };
-    }
-    return {
-        source: "profile",
-        profile: envProfile ?? DEFAULT_PROFILE,
-        explicit: envProfile !== undefined,
-    };
+const credentialInputs = () => inputs;
+const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv }) => {
+	const flagKey = nonEmpty(apiKeyFlag);
+	const flagProfile = nonEmpty(profileFlag);
+	if (flagKey !== void 0 && flagProfile !== void 0) throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
+	if (flagKey !== void 0) return {
+		source: "explicit-api-key",
+		apiKey: flagKey
+	};
+	if (flagProfile !== void 0) return {
+		source: "profile",
+		profile: flagProfile,
+		explicit: true
+	};
+	const envKey = nonEmpty(apiKeyEnv);
+	const envProfile = nonEmpty(profileEnv);
+	if (envKey !== void 0) return {
+		source: "ambient-api-key",
+		apiKey: envKey,
+		...envProfile !== void 0 ? { ignoredProfile: envProfile } : {}
+	};
+	return {
+		source: "profile",
+		profile: envProfile ?? "DEFAULT",
+		explicit: envProfile !== void 0
+	};
 };
 /** The warning for an ambient key that displaced an ambient profile, or `null`. */
-export const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" &&
-    selection.ignoredProfile !== undefined
-    ? `NEON_API_KEY is set, so profile "${selection.ignoredProfile}" from NEON_PROFILE was ignored. Pass --profile ${selection.ignoredProfile} to use it instead.`
-    : null;
+const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" && selection.ignoredProfile !== void 0 ? `NEON_API_KEY is set, so profile "${selection.ignoredProfile}" from NEON_PROFILE was ignored. Pass --profile ${selection.ignoredProfile} to use it instead.` : null;
 function nonEmpty(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed === "" ? undefined : trimmed;
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
 }
+//#endregion
+export { credentialInputs, displacedProfileWarning, recordCredentialInputs, selectCredential };

package/dist/_shared/credentials.js

@@ -1,209 +1,188 @@
-/**
- * # Stored credentials — one file per account, two kinds
- *
- * A profile points at exactly one credentials file (see `./profiles.ts`), and that file says
- * what kind of credential it holds. Adding API-key support this way rather than adding a
- * second pointer to `profiles.json` keeps a profile what it already was — one name, one path
- * — and means `profiles.json` needs no schema change at all.
- *
- * ```json
- * // oauth: every file written before this existed. An absent `type` means this.
- * { "access_token": "…", "refresh_token": "…", "expires_at": 1786…, "user_id": "…" }
- *
- * // api_key, stored by `neon profile create --api-key`
- * { "type": "api_key", "api_key": "napi_…", "user_id": "…" }
- *
- * // api_key minted by `--mint --org-id`, which records the scope it was issued at
- * { "type": "api_key", "api_key": "napi_…", "key_id": 123, "org_id": "org-…" }
- * ```
- *
- * ## One profile, one kind
- *
- * A credentials file holds an API key or an OAuth session, never both, and `type` states
- * which. An earlier draft let the two coexist — the idea being that a key could keep the
- * session it was minted from and so rotate without a browser. It did not survive review, for
- * two reasons that are worth recording so nobody rebuilds it:
- *
- * 1. **It never worked.** The resolver returned the key without testing it, so a revoked key
- *    failed to mint and never fell back to the session sitting beside it.
- * 2. **It could mix accounts.** Nothing compared the identity of the credential being written
- *    with the one already there, so a profile could hold one account's session and another's
- *    key, told apart only by a single string. Flip or lose `type` and the profile silently
- *    becomes a different person.
- *
- * Recovery from a dead key is therefore one browser login — `neon profile create <name>
- * --mint --force` — which is what the retained session was supposed to save and never did.
- *
- * ## Older releases
- *
- * A CLI predating this reads the pointer, finds no `type` it understands, ignores it, and
- * looks for `access_token`. An `api_key` profile has none, so an older release falls through
- * to its browser login rather than crashing. That it does not crash is why `credentials`
- * stays a required pointer: an entry without one makes 2.41 and 2.42 throw
- * `ERR_INVALID_ARG_TYPE` from `resolveEntryPath`.
- */
-import { readFileSync } from "node:fs";
 import { writeSecretFile } from "./secure_file.js";
-export const OAUTH = "oauth";
-export const API_KEY = "api_key";
+import { readFileSync } from "node:fs";
+//#region src/_shared/credentials.ts
+/**
+* # Stored credentials — one file per account, two kinds
+*
+* A profile points at exactly one credentials file (see `./profiles.ts`), and that file says
+* what kind of credential it holds. Adding API-key support this way rather than adding a
+* second pointer to `profiles.json` keeps a profile what it already was — one name, one path
+* — and means `profiles.json` needs no schema change at all.
+*
+* ```json
+* // oauth: every file written before this existed. An absent `type` means this.
+* { "access_token": "…", "refresh_token": "…", "expires_at": 1786…, "user_id": "…" }
+*
+* // api_key, stored by `neon profile create --api-key`
+* { "type": "api_key", "api_key": "napi_…", "user_id": "…" }
+*
+* // api_key minted by `--mint --org-id`, which records the scope it was issued at
+* { "type": "api_key", "api_key": "napi_…", "key_id": 123, "org_id": "org-…" }
+* ```
+*
+* ## One profile, one kind
+*
+* A credentials file holds an API key or an OAuth session, never both, and `type` states
+* which. An earlier draft let the two coexist — the idea being that a key could keep the
+* session it was minted from and so rotate without a browser. It did not survive review, for
+* two reasons that are worth recording so nobody rebuilds it:
+*
+* 1. **It never worked.** The resolver returned the key without testing it, so a revoked key
+*    failed to mint and never fell back to the session sitting beside it.
+* 2. **It could mix accounts.** Nothing compared the identity of the credential being written
+*    with the one already there, so a profile could hold one account's session and another's
+*    key, told apart only by a single string. Flip or lose `type` and the profile silently
+*    becomes a different person.
+*
+* Recovery from a dead key is therefore one browser login — `neon profile create <name>
+* --mint --force` — which is what the retained session was supposed to save and never did.
+*
+* ## Older releases
+*
+* A CLI predating this reads the pointer, finds no `type` it understands, ignores it, and
+* looks for `access_token`. An `api_key` profile has none, so an older release falls through
+* to its browser login rather than crashing. That it does not crash is why `credentials`
+* stays a required pointer: an entry without one makes 2.41 and 2.42 throw
+* `ERR_INVALID_ARG_TYPE` from `resolveEntryPath`.
+*/
+const OAUTH = "oauth";
+const API_KEY = "api_key";
 /**
- * Which credential in this file authenticates, by declaration alone.
- *
- * An unrecognised `type` throws rather than falling back to `oauth`. A file we cannot
- * interpret is a misconfiguration the user has to see: treating it as OAuth would send them
- * to a browser login that silently replaces a credential they meant to keep, and treating it
- * as an API key would authenticate with whatever `api_key` happened to be there.
- *
- * This deliberately does not check that an `api_key` file has a key — `neon profile list`
- * needs the kind of a file it is not about to authenticate with, and must be able to report a
- * broken one rather than throwing halfway through a table.
- */
-export const credentialKind = (credentials, at) => {
-    const declared = credentials.type;
-    if (declared === undefined || declared === OAUTH)
-        return OAUTH;
-    if (declared === API_KEY)
-        return API_KEY;
-    // The value is not quoted back. Everything in this file is secret material, and a
-    // corrupted or hand-edited file can put a key anywhere in it — including here. Naming the
-    // file is enough to act on, and it cannot leak what the file holds.
-    throw new Error(`${at.path} declares a "type" this version does not understand. Expected "${OAUTH}" or "${API_KEY}". ${repair(at)}`);
+* Which credential in this file authenticates, by declaration alone.
+*
+* An unrecognised `type` throws rather than falling back to `oauth`. A file we cannot
+* interpret is a misconfiguration the user has to see: treating it as OAuth would send them
+* to a browser login that silently replaces a credential they meant to keep, and treating it
+* as an API key would authenticate with whatever `api_key` happened to be there.
+*
+* This deliberately does not check that an `api_key` file has a key — `neon profile list`
+* needs the kind of a file it is not about to authenticate with, and must be able to report a
+* broken one rather than throwing halfway through a table.
+*/
+const credentialKind = (credentials, at) => {
+	const declared = credentials.type;
+	if (declared === void 0 || declared === "oauth") return OAUTH;
+	if (declared === "api_key") return API_KEY;
+	throw new Error(`${at.path} declares a "type" this version does not understand. Expected "${OAUTH}" or "${API_KEY}". ${repair(at)}`);
 };
 /**
- * The way out of a credentials file that cannot be read.
- *
- * One sentence, shared by every such error, because they all have the same two answers: write
- * a new credential over it, or delete it and start again.
- */
+* The way out of a credentials file that cannot be read.
+*
+* One sentence, shared by every such error, because they all have the same two answers: write
+* a new credential over it, or delete it and start again.
+*/
 const repair = (at) => `Replace it deliberately with \`neon profile create ${at.profile} --force\`, or delete the file.`;
 /**
- * Resolve what to authenticate with, validating that the declared kind is actually usable.
- *
- * An `api_key` file with no key is a hard error rather than a fall-through to OAuth: the user
- * asked for a key, and quietly opening a browser instead would replace the credential they
- * were trying to fix.
- */
-export const interpretCredentials = (credentials, at) => {
-    if (credentialKind(credentials, at) === OAUTH)
-        return { kind: OAUTH };
-    const apiKey = nonEmpty(credentials.api_key);
-    if (apiKey === undefined) {
-        throw new Error(`${at.path} declares "type": "${API_KEY}" but has no "api_key" value. ${repair(at)}`);
-    }
-    return { kind: API_KEY, apiKey };
+* Resolve what to authenticate with, validating that the declared kind is actually usable.
+*
+* An `api_key` file with no key is a hard error rather than a fall-through to OAuth: the user
+* asked for a key, and quietly opening a browser instead would replace the credential they
+* were trying to fix.
+*/
+const interpretCredentials = (credentials, at) => {
+	if (credentialKind(credentials, at) === "oauth") return { kind: OAUTH };
+	const apiKey = nonEmpty(credentials.api_key);
+	if (apiKey === void 0) throw new Error(`${at.path} declares "type": "${API_KEY}" but has no "api_key" value. ${repair(at)}`);
+	return {
+		kind: API_KEY,
+		apiKey
+	};
 };
 /**
- * Read and classify a credentials file, without deciding what to do about it.
- *
- * A permission or I/O error still throws: there may be a perfectly good credential here that
- * we cannot see, and treating that as absent would send the user to a browser login that
- * overwrites it.
- */
-export const inspectCredentials = (path) => {
-    let contents;
-    try {
-        contents = readFileSync(path, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return { kind: "absent" };
-        throw err;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(contents);
-    }
-    catch {
-        // The parser's message is deliberately discarded. V8 quotes a window of the input
-        // around the syntax error — on Node 24 a truncated credentials file produced
-        // `Unexpected token 'a', ..."api_key":napi_SUPERS"... is not valid JSON` — and this
-        // reason is printed by `profile list` and by every failed authentication. A malformed
-        // secret file is exactly when a diagnostic must say less, not more.
-        return {
-            kind: "unusable",
-            reason: `${path} is not valid JSON, so the credential in it cannot be read`,
-        };
-    }
-    if (parsed === null ||
-        typeof parsed !== "object" ||
-        Array.isArray(parsed)) {
-        return {
-            kind: "unusable",
-            reason: `${path} does not contain a credentials object`,
-        };
-    }
-    return { kind: "ok", credentials: parsed };
+* Read and classify a credentials file, without deciding what to do about it.
+*
+* A permission or I/O error still throws: there may be a perfectly good credential here that
+* we cannot see, and treating that as absent would send the user to a browser login that
+* overwrites it.
+*/
+const inspectCredentials = (path) => {
+	let contents;
+	try {
+		contents = readFileSync(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return { kind: "absent" };
+		throw err;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		return {
+			kind: "unusable",
+			reason: `${path} is not valid JSON, so the credential in it cannot be read`
+		};
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {
+		kind: "unusable",
+		reason: `${path} does not contain a credentials object`
+	};
+	return {
+		kind: "ok",
+		credentials: parsed
+	};
 };
 /**
- * The credential at `path`, or `null` when the file is not there.
- *
- * A damaged file is an error, not an absence. Treating it as absent — which is what this used to
- * do — meant any read-only command could repair it by starting a browser sign-in and overwriting
- * it, **possibly as a different account**, with the user never having asked for a repair and no
- * way back to whatever was in the file. Failing here costs one deliberate command; the message
- * names it.
- *
- * `profile list` and telemetry use {@link inspectCredentials} instead, because describing a
- * broken credential is not the same as using one.
- */
-export const readCredentials = (at) => {
-    const read = inspectCredentials(at.path);
-    if (read.kind === "unusable") {
-        throw new Error(`${read.reason}. ${repair(at)}`);
-    }
-    return read.kind === "ok" ? read.credentials : null;
+* The credential at `path`, or `null` when the file is not there.
+*
+* A damaged file is an error, not an absence. Treating it as absent — which is what this used to
+* do — meant any read-only command could repair it by starting a browser sign-in and overwriting
+* it, **possibly as a different account**, with the user never having asked for a repair and no
+* way back to whatever was in the file. Failing here costs one deliberate command; the message
+* names it.
+*
+* `profile list` and telemetry use {@link inspectCredentials} instead, because describing a
+* broken credential is not the same as using one.
+*/
+const readCredentials = (at) => {
+	const read = inspectCredentials(at.path);
+	if (read.kind === "unusable") throw new Error(`${read.reason}. ${repair(at)}`);
+	return read.kind === "ok" ? read.credentials : null;
 };
-export const writeCredentials = (path, credentials) => {
-    writeSecretFile(path, JSON.stringify(credentials));
+const writeCredentials = (path, credentials) => {
+	writeSecretFile(path, JSON.stringify(credentials));
 };
 /**
- * Build an `api_key` credentials object. Nothing from a previous credential is carried over.
- *
- * The scope is stored because it is not recoverable from the secret: `rotate-key` has to mint
- * the replacement on the same endpoint, and an org or project key minted as an account key
- * would silently widen what the profile reaches.
- */
-export const apiKeyCredentials = ({ apiKey, keyId, userId, scope, }) => ({
-    type: API_KEY,
-    api_key: apiKey,
-    ...(keyId !== undefined ? { key_id: keyId } : {}),
-    ...(userId !== undefined ? { user_id: userId } : {}),
-    ...(scope?.orgId !== undefined ? { org_id: scope.orgId } : {}),
-    ...(scope?.projectId !== undefined ? { project_id: scope.projectId } : {}),
+* Build an `api_key` credentials object. Nothing from a previous credential is carried over.
+*
+* The scope is stored because it is not recoverable from the secret: `rotate-key` has to mint
+* the replacement on the same endpoint, and an org or project key minted as an account key
+* would silently widen what the profile reaches.
+*/
+const apiKeyCredentials = ({ apiKey, keyId, userId, scope }) => ({
+	type: API_KEY,
+	api_key: apiKey,
+	...keyId !== void 0 ? { key_id: keyId } : {},
+	...userId !== void 0 ? { user_id: userId } : {},
+	...scope?.orgId !== void 0 ? { org_id: scope.orgId } : {},
+	...scope?.projectId !== void 0 ? { project_id: scope.projectId } : {}
 });
 /** The scope recorded on a stored credential. */
-export const scopeOf = (credentials) => ({
-    ...(typeof credentials.org_id === "string"
-        ? { orgId: credentials.org_id }
-        : {}),
-    ...(typeof credentials.project_id === "string"
-        ? { projectId: credentials.project_id }
-        : {}),
+const scopeOf = (credentials) => ({
+	...typeof credentials.org_id === "string" ? { orgId: credentials.org_id } : {},
+	...typeof credentials.project_id === "string" ? { projectId: credentials.project_id } : {}
 });
 /** How to describe a scope in output. */
-export const describeScope = (scope) => {
-    if (scope.projectId !== undefined)
-        return `project ${scope.projectId}`;
-    if (scope.orgId !== undefined)
-        return `org ${scope.orgId}`;
-    return "account";
+const describeScope = (scope) => {
+	if (scope.projectId !== void 0) return `project ${scope.projectId}`;
+	if (scope.orgId !== void 0) return `org ${scope.orgId}`;
+	return "account";
 };
 function nonEmpty(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed === "" ? undefined : trimmed;
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
 }
 /**
- * Whether a stored credential is the same secret as the one about to replace it.
- *
- * Re-storing the key a profile already holds is a no-op, not a replacement — and retiring it
- * would revoke the credential the command has just committed to. Trimmed on both sides, because
- * a key read from a file or a pipe arrives with a trailing newline.
- */
-export const isSameCredential = (existingKey, replacementKey) => {
-    if (existingKey === undefined || replacementKey === undefined)
-        return false;
-    const trimmed = existingKey.trim();
-    return trimmed !== "" && trimmed === replacementKey.trim();
+* Whether a stored credential is the same secret as the one about to replace it.
+*
+* Re-storing the key a profile already holds is a no-op, not a replacement — and retiring it
+* would revoke the credential the command has just committed to. Trimmed on both sides, because
+* a key read from a file or a pipe arrives with a trailing newline.
+*/
+const isSameCredential = (existingKey, replacementKey) => {
+	if (existingKey === void 0 || replacementKey === void 0) return false;
+	const trimmed = existingKey.trim();
+	return trimmed !== "" && trimmed === replacementKey.trim();
 };
+//#endregion
+export { API_KEY, OAUTH, apiKeyCredentials, credentialKind, describeScope, inspectCredentials, interpretCredentials, isSameCredential, readCredentials, scopeOf, writeCredentials };