neon 8.11.1 → 8.11.2

package/README.md

@@ -1111,7 +1111,7 @@ Variables a template needs are declared on each function in `neon.ts` (`env: { A
 
 Nothing is written until every check passes: a file that already exists with different contents needs `--force`, and a slug `neon.ts` already declares needs `--slug`, `--force`, or `--no-add-to-config`. A `separate` template sets its own slugs, so `--slug` only changes its directory; remove the existing declarations from `neon.ts`, or use `--force` or `--no-add-to-config`.
 
-The registry lives in [`registry/`](https://github.com/neondatabase/examples/tree/main/registry) in `neondatabase/examples`. The CLI reads the index from `https://neon.com/functions/registry/registry.json`, which serves `main` through a CDN cache, and falls back to raw GitHub when neon.com is unreachable. Template files are always read from raw GitHub. Set `NEON_FUNCTION_REGISTRY_DIR` to a local checkout to try templates before they are merged, or `NEON_FUNCTION_REGISTRY_URL` to read an index from somewhere else.
+The registry lives in [`registry/`](https://github.com/neondatabase/examples/tree/main/registry) in `neondatabase/examples`. The CLI reads the index from `https://neon.com/functions/registry/registry.json`, which serves `main` through a CDN cache, and falls back to raw GitHub when neon.com is unreachable. Template files are always read from raw GitHub. Index and template JSON are validated against the schemas at `https://neon.com/functions/registry/schemas/` (same GitHub fallback). Set `NEON_FUNCTION_REGISTRY_DIR` to a local checkout to try templates before they are merged, or `NEON_FUNCTION_REGISTRY_URL` to read an index from somewhere else.
 
 ## Function triggers (`triggers`)
 

package/dist/_chunks/api-GbEaBZJ5.js

@@ -0,0 +1,388 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { codeFromBody, isNeonApiError } from "../api.js";
+import { writer } from "../writer.js";
+import { describeOperation, getEndpoints, loadSpec } from "../utils/openapi.js";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import YAML from "yaml";
+//#region src/commands/api.ts
+var api_exports = /* @__PURE__ */ __exportAll({
+	buildBody: () => buildBody,
+	buildQuery: () => buildQuery,
+	builder: () => builder,
+	colorizeJson: () => colorizeJson,
+	command: () => command,
+	describe: () => describe,
+	handler: () => handler,
+	parseHeaders: () => parseHeaders,
+	parseKeyValue: () => parseKeyValue,
+	parseTypedValue: () => parseTypedValue,
+	setDeep: () => setDeep
+});
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
+/**
+* Coerce a raw string into a typed JSON value: booleans, `null`, integers,
+* floats, and JSON arrays/objects are parsed; everything else stays a string.
+*/
+function parseTypedValue(raw) {
+	if (raw === "true") return true;
+	if (raw === "false") return false;
+	if (raw === "null") return null;
+	if (/^-?\d+$/.test(raw)) return Number.parseInt(raw, 10);
+	if (/^-?\d*\.\d+$/.test(raw)) return Number.parseFloat(raw);
+	if (raw.startsWith("[") || raw.startsWith("{")) try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+	return raw;
+}
+/** Split a `key=value` pair on the first `=`. */
+function parseKeyValue(input) {
+	const eq = input.indexOf("=");
+	if (eq === -1) throw new Error(`Invalid "key=value" pair: "${input}".`);
+	return {
+		key: input.slice(0, eq),
+		value: input.slice(eq + 1)
+	};
+}
+/**
+* Assign `value` into `target` at a dot-delimited path, creating intermediate
+* objects as needed. Enables `-F branch.name=dev` → `{ branch: { name: "dev" } }`,
+* matching the nested shape of Neon request bodies.
+*/
+function setDeep(target, dottedKey, value) {
+	const parts = dottedKey.split(".");
+	let node = target;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const part = parts[i];
+		const next = node[part];
+		if (typeof next !== "object" || next === null || Array.isArray(next)) node[part] = {};
+		node = node[part];
+	}
+	node[parts[parts.length - 1]] = value;
+}
+/** Build a JSON body object from typed `-F` and string `-f` field pairs. */
+function buildBody(fields, rawFields) {
+	const body = {};
+	for (const field of fields) {
+		const { key, value } = parseKeyValue(field);
+		setDeep(body, key, parseTypedValue(value));
+	}
+	for (const field of rawFields) {
+		const { key, value } = parseKeyValue(field);
+		setDeep(body, key, value);
+	}
+	return body;
+}
+/** Build a query-string map from `-Q key=value` pairs. */
+function buildQuery(pairs) {
+	const query = {};
+	for (const pair of pairs) {
+		const { key, value } = parseKeyValue(pair);
+		query[key] = value;
+	}
+	return query;
+}
+/** Build a header map from `-H key:value` pairs. */
+function parseHeaders(pairs) {
+	const headers = {};
+	for (const pair of pairs) {
+		const idx = pair.indexOf(":");
+		if (idx === -1) throw new Error(`Invalid header "${pair}". Expected "key:value".`);
+		headers[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+	}
+	return headers;
+}
+function assertMethod(method) {
+	if (!HTTP_METHODS.includes(method)) throw new Error(`Unsupported method "${method}". Use one of: ${HTTP_METHODS.join(", ")}.`);
+}
+const JSON_TOKEN = /("(?:\\.|[^"\\])*")(\s*:)?|\b(true|false)\b|\bnull\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g;
+/** Color the tokens of serialized JSON without changing a byte of the text itself. */
+function colorizeJson(json) {
+	return json.replace(JSON_TOKEN, (token, string, colon, bool) => {
+		if (string !== void 0) return colon !== void 0 ? `${chalk.cyan(string)}${colon}` : chalk.green(string);
+		if (bool !== void 0) return chalk.magenta(token);
+		if (token === "null") return chalk.dim(token);
+		return chalk.yellow(token);
+	});
+}
+const METHOD_COLORS = {
+	GET: chalk.green,
+	POST: chalk.cyan,
+	PUT: chalk.yellow,
+	PATCH: chalk.yellow,
+	DELETE: chalk.red
+};
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Resolve `--data`: `-` reads stdin, `@file` reads a file, else the literal string. Parsed as JSON when possible. */
+async function readData(data) {
+	let raw;
+	if (data === "-") raw = await readStdin();
+	else if (data.startsWith("@")) raw = readFileSync(resolve(data.slice(1)), "utf8");
+	else raw = data;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+}
+const toStrings = (values) => (values ?? []).map(String);
+async function listEndpoints(args) {
+	const spec = await loadSpec({
+		configDir: args.configDir,
+		specUrl: args.specUrl,
+		refresh: args.refresh
+	});
+	if (!spec) throw new Error(`Could not load the Neon OpenAPI spec from ${args.specUrl}. Check your network connection or pass --spec-url.`);
+	const endpoints = getEndpoints(spec).map((endpoint) => ({
+		method: endpoint.method,
+		path: endpoint.path,
+		summary: endpoint.summary ?? ""
+	}));
+	writer(args).end(endpoints, {
+		fields: [
+			"method",
+			"path",
+			"summary"
+		],
+		title: `Neon API endpoints (${endpoints.length})`,
+		emptyMessage: "No endpoints found in the spec.",
+		renderColumns: { method: (endpoint) => useColor(args) ? (METHOD_COLORS[endpoint.method] ?? String)(endpoint.method) : endpoint.method }
+	});
+}
+function isListing(args) {
+	return args.list || args.path === "list" || args.path === "ls";
+}
+function describeType(field) {
+	const enumText = (values) => Array.isArray(values) && values.length > 0 ? ` (${values.map(String).join(", ")})` : "";
+	if (field.type === "array" && field.items) {
+		const props = field.items.properties;
+		if (props && props.length > 0) return `array (${props.map((prop) => `${prop.name}${enumText(prop.enum)}`).join(", ")})`;
+		return `array of ${field.items.type}${enumText(field.items.enum)}`;
+	}
+	return `${field.type}${enumText(field.enum)}`;
+}
+async function describeRoute(args) {
+	const path = args.path;
+	if (!path) throw new Error("Missing API path. Usage: neon api <path> --describe (e.g. neon api /projects --describe). Run `neon api --list` to see available routes.");
+	if (!path.startsWith("/")) throw new Error(`Invalid path "${path}". API paths must start with "/". Run \`neon api --list\` to see available routes.`);
+	if ([
+		...toStrings(args.field),
+		...toStrings(args.rawField),
+		...toStrings(args.query),
+		...toStrings(args.header)
+	].length > 0 || args.data !== void 0 || args.include) throw new Error("--describe prints the field list; it does not send a request. Drop -F, -f, -d, -Q, -H, and -i.");
+	const spec = await loadSpec({
+		configDir: args.configDir,
+		specUrl: args.specUrl,
+		refresh: args.refresh
+	});
+	if (!spec) throw new Error(`Could not load the Neon OpenAPI spec from ${args.specUrl}. Check your network connection or pass --spec-url.`);
+	const method = String(args.method ?? "GET").toUpperCase();
+	assertMethod(method);
+	const description = describeOperation(spec, path, method);
+	const endpoint = {
+		method: description.method,
+		path: description.path,
+		summary: description.summary,
+		operationId: description.operationId,
+		bodyRequired: description.bodyRequired,
+		...description.contentType !== "" && description.contentType !== "application/json" ? { contentType: description.contentType } : {}
+	};
+	let title = description.summary ? `${description.method} ${description.path} - ${description.summary}` : `${description.method} ${description.path}`;
+	if (description.bodyRequired) title = `${title} (body required)`;
+	if (description.contentType !== "" && description.contentType !== "application/json") title = `${title} (${description.contentType})`;
+	if (args.output === "json" || args.output === "yaml") {
+		writer(args).write(endpoint, {
+			fields: [
+				"method",
+				"path",
+				"summary",
+				"operationId",
+				"bodyRequired"
+			],
+			title: "Endpoint"
+		}).end(description.fields, {
+			fields: [
+				"in",
+				"name",
+				"required",
+				"type",
+				"description"
+			],
+			title: "Parameters"
+		});
+		return;
+	}
+	writer(args).end(description.fields, {
+		fields: [
+			"in",
+			"name",
+			"required",
+			"type",
+			"description"
+		],
+		title,
+		emptyMessage: "No path, query, or body fields in the spec.",
+		renderColumns: {
+			required: (field) => field.required ? "required" : "optional",
+			type: (field) => describeType(field)
+		}
+	});
+}
+async function runRequest(args) {
+	const path = args.path;
+	if (!path) throw new Error("Missing API path. Usage: neon api <path> (e.g. neon api /projects). Run `neon api --list` to see available routes.");
+	if (!path.startsWith("/")) throw new Error(`Invalid path "${path}". API paths must start with "/". Run \`neon api --list\` to see available routes.`);
+	const fields = toStrings(args.field);
+	const rawFields = toStrings(args.rawField);
+	let body;
+	if (args.data !== void 0) body = await readData(args.data);
+	else if (fields.length > 0 || rawFields.length > 0) body = buildBody(fields, rawFields);
+	const hasBody = body !== void 0;
+	const method = String(args.method ?? (hasBody ? "POST" : "GET")).toUpperCase();
+	assertMethod(method);
+	const query = buildQuery(toStrings(args.query));
+	const headers = parseHeaders(toStrings(args.header));
+	const params = {
+		path,
+		method,
+		...Object.keys(query).length > 0 ? { query } : {},
+		...hasBody ? { body } : {},
+		...Object.keys(headers).length > 0 ? { headers } : {}
+	};
+	let response;
+	try {
+		response = await args.apiClient.request(params);
+	} catch (err) {
+		if (args.include && isNeonApiError(err) && err.status !== void 0 && err.status !== 401 && !isSsoCode(codeFromBody(err.data))) await writeResponse(args, {
+			status: err.status,
+			statusText: err.statusText ?? "",
+			headers: err.headers ?? {},
+			data: err.data
+		});
+		throw err;
+	}
+	await writeResponse(args, response);
+}
+const isSsoCode = (code) => code === "SSO_AUTHORIZATION_REQUIRED" || code === "SSO_ORG_CREDS_ONLY";
+/** Pipes stay plain regardless of FORCE_COLOR, so `neon api … | jq` never sees escapes. */
+const useColor = (args) => process.stdout.isTTY === true && args.color !== false && !process.env.NO_COLOR && chalk.level > 0;
+/** Resolves once stdout has taken the text, so a following `process.exit` can't cut it off. */
+async function writeResponse(args, response) {
+	const color = useColor(args);
+	let text = "";
+	if (args.include) {
+		const status = `HTTP ${response.status} ${response.statusText}`;
+		const statusColor = response.status < 400 ? chalk.green : chalk.red;
+		text += `${color ? statusColor.bold(status) : status}\n`;
+		for (const [key, value] of Object.entries(response.headers)) text += `${color ? chalk.cyan(key) : key}: ${value}\n`;
+		text += "\n";
+	}
+	if (response.data !== void 0) {
+		if (args.output === "yaml") text += YAML.stringify(response.data);
+		else {
+			const json = JSON.stringify(response.data, null, 2);
+			text += `${color ? colorizeJson(json) : json}\n`;
+		}
+	}
+	if (text === "") return;
+	await new Promise((resolve, reject) => {
+		process.stdout.write(text, (err) => err ? reject(err) : resolve());
+	});
+}
+const command = "api [path]";
+const describe = "Call any Neon API route directly (authenticated passthrough)";
+const builder = (argv) => argv.usage("$0 api <path> [options]").positional("path", {
+	type: "string",
+	describe: "API path beginning with \"/\" (e.g. /projects or /projects/{project_id}/branches). Use `list` to list endpoints."
+}).options({
+	method: {
+		alias: "X",
+		type: "string",
+		describe: "HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to GET, or POST when a body is provided."
+	},
+	field: {
+		alias: "F",
+		type: "array",
+		string: true,
+		describe: "Body field key=value (repeatable). Dot-notation nests objects (e.g. -F branch.name=dev); values are typed (numbers, booleans, null, JSON)."
+	},
+	"raw-field": {
+		alias: "f",
+		type: "array",
+		string: true,
+		describe: "Body field key=value with the value kept as a raw string."
+	},
+	data: {
+		alias: "d",
+		type: "string",
+		describe: "Raw request body: a JSON string, @file, or - for stdin. Overrides --field."
+	},
+	query: {
+		alias: "Q",
+		type: "array",
+		string: true,
+		describe: "Query parameter key=value (repeatable)."
+	},
+	header: {
+		alias: "H",
+		type: "array",
+		string: true,
+		describe: "Extra request header key:value (repeatable)."
+	},
+	include: {
+		alias: "i",
+		type: "boolean",
+		default: false,
+		describe: "Print the response status and headers before the body."
+	},
+	list: {
+		type: "boolean",
+		default: false,
+		describe: "List available API endpoints from the OpenAPI spec."
+	},
+	describe: {
+		type: "boolean",
+		default: false,
+		describe: "Print path, query, and body fields from the OpenAPI spec without calling the API. Body names are dotted for -F."
+	},
+	refresh: {
+		type: "boolean",
+		default: false,
+		describe: "Refresh the cached OpenAPI spec (used with --list and --describe)."
+	},
+	"spec-url": {
+		type: "string",
+		default: process.env.NEON_API_SPEC_URL ?? "https://neon.com/api_spec/release/v2.json",
+		hidden: true,
+		describe: "OpenAPI spec URL used by --list and --describe."
+	}
+}).example("$0 api /projects", "List your projects").example("$0 api /projects/{id}/branches -X POST -F branch.name=dev", "Create a branch").example("$0 api --list", "List every available API route").example("$0 api /projects --describe", "Show GET /projects query parameters").example("$0 api /projects -X POST --describe", "Show the create-project body fields");
+const handler = async (args) => {
+	const apiArgs = args;
+	if (isListing(apiArgs) && apiArgs.describe) throw new Error("Pass either --list or --describe, not both.");
+	if (isListing(apiArgs)) {
+		await listEndpoints(apiArgs);
+		return;
+	}
+	if (apiArgs.describe) {
+		await describeRoute(apiArgs);
+		return;
+	}
+	await runRequest(apiArgs);
+};
+//#endregion
+export { colorizeJson as a, handler as c, parseTypedValue as d, setDeep as f, builder as i, parseHeaders as l, buildBody as n, command as o, buildQuery as r, describe as s, api_exports as t, parseKeyValue as u };

package/dist/_chunks/api_keys-CNnnugbQ.js

@@ -0,0 +1,281 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { log } from "../log.js";
+import { isNeonApiError } from "../api.js";
+import { writer } from "../writer.js";
+import { noPassthrough, single } from "../utils/flags.js";
+//#region src/commands/api_keys.ts
+var api_keys_exports = /* @__PURE__ */ __exportAll({
+	aliases: () => aliases,
+	builder: () => builder,
+	command: () => command,
+	describe: () => describe,
+	handler: () => handler,
+	orgIdForProject: () => orgIdForProject
+});
+const ACCOUNT_FIELDS = [
+	"id",
+	"name",
+	"created_at",
+	"last_used_at",
+	"last_used_from_addr"
+];
+/**
+* Table view of an org listing. `project` is the rendered column; the raw `project_id` is
+* what structured output keeps. See {@link list} for why the two differ.
+*/
+const ORG_TABLE_FIELDS = [
+	"id",
+	"name",
+	"project",
+	"created_at",
+	"last_used_at",
+	"last_used_from_addr"
+];
+const ORG_FIELDS = [
+	"id",
+	"name",
+	"project_id",
+	"created_at",
+	"last_used_at",
+	"last_used_from_addr"
+];
+const CREATE_FIELDS = [
+	"id",
+	"name",
+	"key"
+];
+/** Metadata only: the secret is printed separately so it can be copied cleanly. */
+const CREATE_TABLE_FIELDS = ["id", "name"];
+const CREATE_TABLE_FIELDS_SCOPED = [
+	"id",
+	"name",
+	"project"
+];
+const CREATE_FIELDS_SCOPED = [
+	"id",
+	"name",
+	"project_id",
+	"key"
+];
+/** Rendered for an org key that was not narrowed to a project. Table output only. */
+const ALL_PROJECTS = "(all projects)";
+/**
+* "This key should carry no project scope."
+*
+* A symbol rather than a string, because project ids are `^[a-z0-9-]{1,60}$` — any sentinel
+* spelled as a string is a legal project id, and a project genuinely called that would have
+* its correctly-scoped key rejected and revoked.
+*/
+const NO_PROJECT = Symbol("no-project");
+const command = "api-keys";
+const aliases = ["api-key"];
+const describe = "Manage API keys";
+const builder = (argv) => argv.usage("$0 api-keys <sub-command> [options]").command("list", "List API keys for your account, or for an organization", (yargs) => yargs.options({ "org-id": {
+	describe: "List the organization's keys instead of your account's",
+	type: "string",
+	coerce: single("org-id")
+} }).strict().check(noPassthrough("api-keys")), async (args) => await list(args)).command("create", "Create an API key. The key is shown once and cannot be retrieved again", (yargs) => yargs.options({
+	name: {
+		describe: "A name to identify the key later",
+		type: "string",
+		demandOption: true,
+		coerce: single("name", { required: true })
+	},
+	"org-id": {
+		describe: "Create a key for this organization instead of your account",
+		type: "string",
+		coerce: single("org-id")
+	},
+	"project-id": {
+		describe: "Create a key that can access only this project. Its organization is looked up from the project",
+		type: "string",
+		coerce: single("project-id")
+	}
+}).conflicts("org-id", "project-id").strict().check(noPassthrough("api-keys")), async (args) => await create(args)).command("revoke <id>", "Revoke an API key. Anything using it stops working immediately", (yargs) => yargs.positional("id", {
+	describe: "The API key id, from `api-keys list`",
+	type: "string",
+	demandOption: true,
+	coerce: (value) => {
+		const id = Number(value);
+		if (typeof value !== "string" || !/^\d+$/.test(value.trim()) || !Number.isSafeInteger(id) || id <= 0) throw new Error(`api-keys revoke needs a numeric key id, from \`neon api-keys list\`. Got \`${String(value)}\`.`);
+		return id;
+	}
+}).options({ "org-id": {
+	describe: "Revoke an organization key instead of an account key",
+	type: "string",
+	coerce: single("org-id")
+} }).strict().check(noPassthrough("api-keys")), async (args) => await revoke(args));
+const handler = (args) => args;
+const list = async (props) => {
+	const out = writer(props);
+	if (props.orgId) {
+		const { data } = await props.apiClient.listOrgApiKeys(props.orgId);
+		if (props.output === "table") out.write(data.map((key) => ({
+			...key,
+			project: key.project_id ?? ALL_PROJECTS
+		})), {
+			fields: ORG_TABLE_FIELDS,
+			title: `API keys in ${props.orgId}`,
+			emptyMessage: `No API keys in ${props.orgId}.`
+		});
+		else out.write(data, {
+			fields: ORG_FIELDS,
+			title: `API keys in ${props.orgId}`,
+			emptyMessage: `No API keys in ${props.orgId}.`
+		});
+		out.end();
+		return;
+	}
+	const { data } = await props.apiClient.listApiKeys();
+	out.write(data, {
+		fields: ACCOUNT_FIELDS,
+		title: "Account API keys",
+		emptyMessage: "You have no account API keys."
+	});
+	out.end();
+	if (props.output === "table") log.info("Organization keys are listed separately: neon api-keys list --org-id <org> (see `neon orgs list`).");
+};
+const create = async (props) => {
+	const { name, projectId, orgId } = props;
+	if (!projectId && !orgId) {
+		const { data } = await props.apiClient.createApiKey({ key_name: name });
+		await assertUsable(props, data, {
+			orgId: null,
+			expect: NO_PROJECT
+		});
+		report(props, data, CREATE_FIELDS, CREATE_TABLE_FIELDS);
+		log.warning("This key reaches everything your account can, in every organization. Pass --org-id or --project-id to narrow it.");
+		return;
+	}
+	if (!projectId && orgId) {
+		const { data } = await props.apiClient.createOrgApiKey(orgId, { key_name: name });
+		await assertUsable(props, data, {
+			orgId,
+			expect: NO_PROJECT
+		});
+		report(props, data, CREATE_FIELDS, CREATE_TABLE_FIELDS);
+		log.warning("This key reaches every project in %s, including ones created later. Pass --project-id instead to restrict it to one.", orgId);
+		return;
+	}
+	const scopeTo = projectId;
+	const resolvedOrgId = await orgIdForProject(props.apiClient, scopeTo);
+	const { data } = await props.apiClient.createOrgApiKey(resolvedOrgId, {
+		key_name: name,
+		project_id: scopeTo
+	});
+	await assertUsable(props, data, {
+		orgId: resolvedOrgId,
+		expect: scopeTo
+	});
+	report(props, data, CREATE_FIELDS_SCOPED, CREATE_TABLE_FIELDS_SCOPED);
+	log.info("Limited to %s: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.", scopeTo);
+};
+/**
+* The key is shown only once, so human output keeps it on a selectable line.
+* Structured output keeps it in the object for scripts.
+*/
+const report = (props, data, fields, tableFields) => {
+	const out = writer(props);
+	if (props.output === "table") {
+		const row = typeof data.project_id === "string" ? {
+			...data,
+			project: data.project_id
+		} : data;
+		out.write(row, {
+			fields: tableFields,
+			title: "API key"
+		});
+		out.end();
+		out.text(`\n${data.key}\n`);
+	} else {
+		out.write(data, {
+			fields,
+			title: "API key"
+		});
+		out.end();
+	}
+	log.warning("Store this key now: it is not shown again.");
+};
+/**
+* Refuse to report a key that isn't what we asked for, and take it back.
+*
+* Two ways a 2xx can still be wrong: no `key` in the body, which leaves a live credential
+* the user can never see or use; and a `project_id` that doesn't match the requested
+* project, which would mean announcing a scope the key does not have. Both withdraw the key
+* before throwing.
+*
+* The thrown message states whether the withdrawal actually succeeded. Saying "the key has
+* been revoked" when the revoke itself failed would be worse than saying nothing — it would
+* leave an unverified credential live while telling the user it is gone.
+*/
+const assertUsable = async (props, data, scope) => {
+	const wanted = scope.expect === NO_PROJECT ? void 0 : scope.expect;
+	const problem = typeof data.key !== "string" || data.key.trim() === "" ? "Neon returned no key." : data.project_id !== wanted ? `Neon returned a key scoped to ${data.project_id ?? "nothing"} rather than ${wanted ?? "the whole organization"}.` : null;
+	if (!problem) return;
+	const withdrawn = await withdraw(props, scope.orgId, data.id);
+	throw new Error(`${problem} ${withdrawn ? "The key has been revoked; nothing was issued." : `The key could NOT be revoked and may still be live${data.id === void 0 ? "" : `. Remove it with \`neon api-keys revoke ${data.id}${scope.orgId ? ` --org-id ${scope.orgId}` : ""}\``}.`}`);
+};
+/**
+* Revoke, turning the most likely mistake into a usable message.
+*
+* Account and organization keys live on different endpoints, and `api-keys list --org-id X`
+* shows ids that the account endpoint cannot see. Copying one and forgetting the flag — or
+* leaving it on for an account key — is the easy error, and a bare "API key not found" sends
+* the user looking for a deleted key rather than a misplaced flag.
+*
+* Only the key id is worth second-guessing here: an org id that is wrong or not yours does
+* not reach this path at all, because the API answers "not an organization member" (verified
+* against production) rather than a 404.
+*/
+const revokeOrExplain = async (props) => {
+	try {
+		return props.orgId ? await props.apiClient.revokeOrgApiKey(props.orgId, props.id) : await props.apiClient.revokeApiKey(props.id);
+	} catch (err) {
+		if (isNeonApiError(err) && err.status === 404) throw new Error(props.orgId ? `No API key with id ${props.id} in ${props.orgId}. If it is one of your account's own keys, drop --org-id.` : `No account API key with id ${props.id}. If it belongs to an organization, pass --org-id. Organization keys are not visible to your account.`);
+		throw err;
+	}
+};
+/** Best-effort withdrawal of a key we are refusing to report. Never throws. */
+const withdraw = async (props, orgId, keyId) => {
+	if (!Number.isSafeInteger(keyId) || keyId <= 0) return false;
+	try {
+		const { data } = orgId ? await props.apiClient.revokeOrgApiKey(orgId, keyId) : await props.apiClient.revokeApiKey(keyId);
+		return data.revoked === true && data.id === keyId;
+	} catch (err) {
+		log.warning("Failed to revoke API key %d: %s", keyId, err instanceof Error ? err.message : String(err));
+		return false;
+	}
+};
+const revoke = async (props) => {
+	const out = writer(props);
+	const { data } = await revokeOrExplain(props);
+	out.write(data, {
+		fields: [
+			"id",
+			"name",
+			"revoked",
+			"last_used_at"
+		],
+		title: "API key"
+	});
+	out.end();
+};
+/**
+* The organization a project belongs to. A project outside any organization cannot have a
+* scoped key — the endpoint that accepts `project_id` is org-only — so that case fails here
+* with the reason, rather than as a 404 from a URL the user never typed.
+*/
+const orgIdForProject = async (client, projectId, usage = "api-keys") => {
+	let orgId;
+	try {
+		const { data: { project } } = await client.getProject(projectId);
+		orgId = project.org_id;
+	} catch (err) {
+		if (isNeonApiError(err) && err.status === 404) throw new Error(projectId.startsWith("org-") ? usage === "mcp" ? `Project ${projectId} not found. That looks like an organization id. neon mcp takes a project id on --project-id.` : `Project ${projectId} not found. That looks like an organization id. Pass it as --org-id instead.` : `Project ${projectId} not found. Check the id with \`neon projects list\`.`);
+		throw err;
+	}
+	if (!orgId) throw new Error(usage === "mcp" ? `Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Pass --oauth to pin tools without minting, or omit --project-id to mint an account-wide key.` : `Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Omit --project-id to create an account key.`);
+	return orgId;
+};
+//#endregion
+export { describe as a, command as i, api_keys_exports as n, handler as o, builder as r, orgIdForProject as s, aliases as t };