neon 4.8.0 → 4.10.0

package/README.md

@@ -133,6 +133,18 @@ automation:
 neon branches create --project-id <project-id> --name production --protected
 ```
 
+Project and branch creation include connection credentials in their output by
+default for backward compatibility. When the output may be logged or passed to
+an agent, use `--no-secrets` to return only the created resource metadata:
+
+```bash
+neon projects create --name my-project --output json --no-secrets
+neon branches create --project-id <project-id> --name preview --output json --no-secrets
+```
+
+The flag omits the complete `connection_uris` block rather than redacting one
+field. Retrieve a connection string separately when it is actually needed.
+
 ### Enable logical replication
 
 Enable logical replication for every endpoint in an existing project:
@@ -1096,6 +1108,20 @@ When both are only environment variables the key wins, which keeps a CI pipeline
 
 `neon init` forwards `--profile` and `--config-dir` to the commands it runs. An explicit `--api-key` is passed to those children through `NEON_API_KEY`, not argv.
 
+## API passthrough (`api`)
+
+`neon api` sends an authenticated request to any Neon API route. `neon api --list` catalogs the routes. `neon api <path> --describe` prints the OpenAPI request shape for one operation so you can fill `-F` and `-Q` without guessing. Body field names are dotted to match `-F`.
+
+```bash
+neon api --list
+neon api /projects --describe
+neon api /projects -X POST --describe -o json
+neon api /projects/{project_id}/branches -X POST --describe
+neon api /projects/foo-bar-123/branches -X POST -F branch.name=dev
+```
+
+`--describe` does not send the selected API request. It uses the same CLI authentication as `--list`. `-X` defaults to GET; if that method is missing, the error names the methods that exist.
+
 ## API keys (`api-keys`)
 
 ```bash
@@ -1170,6 +1196,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | claim (`claimable`)                                                        | `create`, `status`, `accept`, `list`, `delete`                                                               | Manage claimable projects          |
 | profile                                                                    | `list`, `create`, `rotate-key`, `remove`                                                                     | Manage named sets of credentials   |
 | api-keys                                                                   | `list`, `create`, `revoke`                                                                                   | Manage API keys                    |
+| api                                                                        |                                                                                                              | Call any Neon API route            |
 | [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                                  | Manage projects                    |
 | [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                                             | Manage IP Allow                    |
 | [me](https://neon.com/docs/reference/cli-me)                               |                                                                                                              | Show current user                  |

package/dist/commands/api.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
-import { getEndpoints, loadSpec } from "../utils/openapi.js";
+import { describeOperation, getEndpoints, loadSpec } from "../utils/openapi.js";
 import { writer } from "../writer.js";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -141,6 +141,86 @@ async function listEndpoints(args) {
 		emptyMessage: "No endpoints found in the spec."
 	});
 }
+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.");
@@ -224,24 +304,34 @@ const builder = (argv) => argv.usage("$0 api <path> [options]").positional("path
 		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)."
+		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."
+		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", "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 (apiArgs.list || apiArgs.path === "list" || apiArgs.path === "ls") {
+	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

package/dist/commands/branches.js

@@ -44,6 +44,11 @@ const builder = (argv) => argv.usage("$0 branches <sub-command> [options]").opti
 } }).middleware(fillSingleProject).middleware((args) => {
 	args.branchId ??= args.id;
 }).command("list", "List branches", (yargs) => yargs, (args) => list(args)).command("create", "Create a branch", (yargs) => yargs.options({
+	secrets: {
+		describe: "Include connection credentials in command output. Use --no-secrets to omit them",
+		type: "boolean",
+		default: true
+	},
 	name: branchCreateRequest["branch.name"],
 	parent: {
 		describe: "Parent branch name or id or timestamp or LSN. Defaults to the default branch",
@@ -220,21 +225,31 @@ const create = async (props) => {
 	}));
 	if (branches.find((b) => b.id === data.branch.parent_id)?.protected) log.warning("The parent branch is protected; a unique role password has been generated for the new branch.");
 	const out = writer(props);
-	out.write(data.branch, {
-		fields: BRANCH_FIELDS,
-		title: "branch",
-		emptyMessage: "No branches have been found."
-	});
-	if (data.endpoints?.length > 0) out.write(data.endpoints, {
-		fields: ["id", "created_at"],
-		title: "endpoints",
-		emptyMessage: "No endpoints have been found."
-	});
-	if (data.connection_uris?.length) out.write(data.connection_uris, {
-		fields: ["connection_uri"],
-		title: "connection_uris",
-		emptyMessage: "No connection uris have been found"
+	const endpoints = data.endpoints ?? [];
+	const connectionUris = data.connection_uris ?? [];
+	const writeEndpoints = endpoints.length > 0;
+	const writeUris = props.secrets && connectionUris.length > 0;
+	if (!props.secrets && (props.output === "json" || props.output === "yaml") && !writeEndpoints) out.write({ branch: data.branch }, {
+		fields: ["branch"],
+		title: "branch"
 	});
+	else {
+		out.write(data.branch, {
+			fields: BRANCH_FIELDS,
+			title: "branch",
+			emptyMessage: "No branches have been found."
+		});
+		if (writeEndpoints) out.write(endpoints, {
+			fields: ["id", "created_at"],
+			title: "endpoints",
+			emptyMessage: "No endpoints have been found."
+		});
+		if (writeUris) out.write(connectionUris, {
+			fields: ["connection_uri"],
+			title: "connection_uris",
+			emptyMessage: "No connection uris have been found"
+		});
+	}
 	out.end();
 	if (props.psql) {
 		if (!data.connection_uris?.length) throw new Error(`Branch ${data.branch.id} doesn't have a connection uri`);

package/dist/commands/projects.js

@@ -62,6 +62,11 @@ const builder = (argv) => {
 	}), async (args) => {
 		await handleMissingOrgId(args, list);
 	}).command("create", "Create a project", (yargs) => yargs.options({
+		secrets: {
+			describe: "Include connection credentials in command output. Use --no-secrets to omit them",
+			type: "boolean",
+			default: true
+		},
 		"block-public-connections": {
 			describe: projectCreateRequest["project.settings.block_public_connections"].description,
 			type: "boolean"
@@ -230,14 +235,20 @@ const create = async (props) => {
 	const { data } = await props.apiClient.createProject({ project });
 	if (props.setContext) updateContextFile(props.contextFile, { projectId: data.project.id });
 	const out = writer(props);
-	out.write(data.project, {
-		fields: PROJECT_FIELDS,
+	if (!props.secrets && (props.output === "json" || props.output === "yaml")) out.write({ project: data.project }, {
+		fields: ["project"],
 		title: "Project"
 	});
-	out.write(data.connection_uris, {
-		fields: ["connection_uri"],
-		title: "Connection URIs"
-	});
+	else {
+		out.write(data.project, {
+			fields: PROJECT_FIELDS,
+			title: "Project"
+		});
+		if (props.secrets) out.write(data.connection_uris, {
+			fields: ["connection_uri"],
+			title: "Connection URIs"
+		});
+	}
 	out.end();
 	if (props.psql) {
 		const connection_uri = data.connection_uris[0].connection_uri;

package/dist/utils/openapi.js

@@ -16,6 +16,13 @@ const HTTP_METHODS = /* @__PURE__ */ new Set([
 	"head",
 	"options"
 ]);
+const DESCRIBE_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
 async function fetchSpec(url) {
 	const controller = new AbortController();
 	const timer = setTimeout(() => {
@@ -98,5 +105,356 @@ function getEndpoints(spec) {
 	endpoints.sort((a, b) => a.path === b.path ? a.method.localeCompare(b.method) : a.path.localeCompare(b.path));
 	return endpoints;
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asStringArray(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((item) => typeof item === "string");
+}
+function stringDesc(value) {
+	if (!isRecord(value) || typeof value.description !== "string") return "";
+	return value.description.trim();
+}
+function specRecord(spec) {
+	return spec;
+}
+function resolveRef(spec, ref) {
+	if (!ref.startsWith("#/")) throw new Error(`Unsupported $ref "${ref}". Only document-local refs are resolved.`);
+	let node = specRecord(spec);
+	for (const part of ref.slice(2).split("/")) {
+		const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+		if (!isRecord(node) || !(key in node)) throw new Error(`Unresolved $ref ${ref}.`);
+		node = node[key];
+	}
+	return node;
+}
+function schemaType(schema) {
+	const t = schema.type;
+	if (typeof t === "string") return t;
+	if (Array.isArray(t)) {
+		const first = t.find((item) => typeof item === "string");
+		if (first) return first;
+	}
+	if (schema.items !== void 0) return "array";
+	if (isRecord(schema.properties) || schema.additionalProperties !== void 0) return "object";
+	if (Array.isArray(schema.enum)) return "string";
+	return "object";
+}
+function optionalEnum(schema) {
+	return Array.isArray(schema.enum) ? { enum: schema.enum } : {};
+}
+function optionalNullable(schema) {
+	return schema.nullable === true ? { nullable: true } : {};
+}
+function mergeSchema(base, overlay) {
+	const properties = {
+		...isRecord(base.properties) ? base.properties : {},
+		...isRecord(overlay.properties) ? overlay.properties : {}
+	};
+	const required = [.../* @__PURE__ */ new Set([...asStringArray(base.required), ...asStringArray(overlay.required)])];
+	const description = stringDesc(overlay) || stringDesc(base);
+	return {
+		...base,
+		...overlay,
+		properties,
+		required,
+		...description ? { description } : {}
+	};
+}
+function resolveSchema(spec, schema, stack) {
+	if (!isRecord(schema)) return {};
+	if (typeof schema.$ref === "string") {
+		const ref = schema.$ref;
+		const { $ref: _ref, ...siblings } = schema;
+		if (stack.includes(ref)) return {
+			type: "object",
+			...siblings
+		};
+		return mergeSchema(resolveSchema(spec, resolveRef(spec, ref), [...stack, ref]), siblings);
+	}
+	if (Array.isArray(schema.allOf)) {
+		const { allOf, ...rest } = schema;
+		let merged = {
+			type: "object",
+			properties: {},
+			required: []
+		};
+		for (const part of allOf) merged = mergeSchema(merged, resolveSchema(spec, part, stack));
+		return mergeSchema(merged, rest);
+	}
+	return schema;
+}
+function fieldFromSchema(location, name, required, schema) {
+	return {
+		in: location,
+		name,
+		required,
+		type: schemaType(schema),
+		description: stringDesc(schema),
+		...optionalEnum(schema),
+		...optionalNullable(schema)
+	};
+}
+function pushedRefs(schema, stack) {
+	if (!isRecord(schema)) return stack;
+	let next = stack;
+	if (typeof schema.$ref === "string" && !next.includes(schema.$ref)) next = [...next, schema.$ref];
+	if (Array.isArray(schema.allOf)) for (const part of schema.allOf) next = pushedRefs(part, next);
+	return next;
+}
+function arrayField(spec, name, required, schema, stack) {
+	const items = isRecord(schema.items) ? resolveSchema(spec, schema.items, stack) : {};
+	const itemType = schemaType(items);
+	const properties = isRecord(items.properties) ? items.properties : void 0;
+	const requiredItems = new Set(asStringArray(items.required));
+	return {
+		in: "body",
+		name,
+		required,
+		type: "array",
+		description: stringDesc(schema),
+		items: {
+			type: itemType,
+			...optionalEnum(items),
+			...optionalNullable(items),
+			...properties ? { properties: Object.entries(properties).map(([propName, propSchema]) => {
+				const resolved = resolveSchema(spec, propSchema, stack);
+				return {
+					name: propName,
+					type: schemaType(resolved),
+					required: requiredItems.has(propName),
+					description: stringDesc(resolved),
+					...optionalEnum(resolved),
+					...optionalNullable(resolved)
+				};
+			}) } : {}
+		}
+	};
+}
+function unionMembers(schema) {
+	if (Array.isArray(schema.oneOf)) return schema.oneOf;
+	if (Array.isArray(schema.anyOf)) return schema.anyOf;
+	return [];
+}
+function discriminatorField(schema, prefix) {
+	if (!isRecord(schema.discriminator)) return null;
+	const propertyName = schema.discriminator.propertyName;
+	if (typeof propertyName !== "string") return null;
+	const mapping = schema.discriminator.mapping;
+	const values = isRecord(mapping) ? Object.keys(mapping) : [];
+	return {
+		in: "body",
+		name: prefix ? `${prefix}.${propertyName}` : propertyName,
+		required: true,
+		type: "string",
+		description: "",
+		...values.length > 0 ? { enum: values } : {}
+	};
+}
+function flattenUnion(spec, schema, prefix, stack) {
+	const members = unionMembers(schema);
+	const byName = /* @__PURE__ */ new Map();
+	for (const member of members) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const field of flattenBody(spec, member, prefix, stack)) {
+			if (seen.has(field.name)) continue;
+			seen.add(field.name);
+			const copies = byName.get(field.name) ?? [];
+			copies.push(field);
+			byName.set(field.name, copies);
+		}
+	}
+	const fields = [];
+	for (const copies of byName.values()) fields.push({
+		...copies[0],
+		required: copies.length === members.length && copies.every((field) => field.required)
+	});
+	const discriminator = discriminatorField(schema, prefix);
+	if (discriminator && !byName.has(discriminator.name)) fields.unshift(discriminator);
+	else if (discriminator) {
+		const existing = fields.find((field) => field.name === discriminator.name);
+		if (existing) {
+			existing.required = true;
+			if (!existing.enum && discriminator.enum) existing.enum = discriminator.enum;
+		}
+	}
+	return fields;
+}
+function flattenBody(spec, schema, prefix, stack = []) {
+	const nextStack = pushedRefs(schema, stack);
+	const resolved = resolveSchema(spec, schema, stack);
+	if (unionMembers(resolved).length > 0) return flattenUnion(spec, resolved, prefix, nextStack);
+	const properties = isRecord(resolved.properties) ? resolved.properties : void 0;
+	if (!properties) {
+		if (prefix === "") return [];
+		if (schemaType(resolved) === "array") return [arrayField(spec, prefix, false, resolved, nextStack)];
+		return [fieldFromSchema("body", prefix, false, resolved)];
+	}
+	const requiredSet = new Set(asStringArray(resolved.required));
+	const fields = [];
+	for (const [key, prop] of Object.entries(properties)) {
+		const name = prefix ? `${prefix}.${key}` : key;
+		const required = requiredSet.has(key);
+		const resolvedProp = resolveSchema(spec, prop, nextStack);
+		const type = schemaType(resolvedProp);
+		if (type === "object" && isRecord(resolvedProp.properties)) {
+			fields.push(...flattenBody(spec, prop, name, nextStack));
+			continue;
+		}
+		if (type === "array") {
+			fields.push(arrayField(spec, name, required, resolvedProp, nextStack));
+			continue;
+		}
+		fields.push(fieldFromSchema("body", name, required, resolvedProp));
+	}
+	return fields;
+}
+function resolveParameter(spec, parameter) {
+	if (!isRecord(parameter)) return null;
+	if (typeof parameter.$ref === "string") {
+		const resolved = resolveRef(spec, parameter.$ref);
+		if (!isRecord(resolved)) throw new Error(`Unresolved $ref ${parameter.$ref}.`);
+		const { $ref: _ref, ...siblings } = parameter;
+		const description = stringDesc(siblings) || stringDesc(resolved);
+		return {
+			...resolved,
+			...siblings,
+			...description ? { description } : {}
+		};
+	}
+	return parameter;
+}
+function paramToField(spec, param) {
+	const location = param.in;
+	if (location !== "path" && location !== "query" && location !== "header") return null;
+	if (typeof param.name !== "string") return null;
+	const schema = isRecord(param.schema) ? resolveSchema(spec, param.schema, []) : {};
+	const required = location === "path" ? param.required !== false : param.required === true;
+	const type = schemaType(schema);
+	const itemSchema = type === "array" && isRecord(schema.items) ? resolveSchema(spec, schema.items, []) : null;
+	return {
+		in: location,
+		name: param.name,
+		required,
+		type,
+		description: stringDesc(param) || stringDesc(schema),
+		...optionalEnum(schema),
+		...optionalNullable(schema),
+		...itemSchema ? { items: {
+			type: schemaType(itemSchema),
+			...optionalEnum(itemSchema),
+			...optionalNullable(itemSchema)
+		} } : {}
+	};
+}
+function pathParamNames(template) {
+	return [...template.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+}
+function pathMatchesTemplate(path, template) {
+	const pathParts = path.split("/");
+	const templateParts = template.split("/");
+	if (pathParts.length !== templateParts.length) return false;
+	return templateParts.every((part, i) => {
+		if (part.startsWith("{") && part.endsWith("}")) return pathParts[i] !== "";
+		return part === pathParts[i];
+	});
+}
+function matchPath(spec, requestPath) {
+	const path = requestPath.split("?")[0] ?? requestPath;
+	const paths = spec.paths ?? {};
+	const exact = paths[path];
+	if (isRecord(exact)) return {
+		template: path,
+		pathItem: exact
+	};
+	const matches = Object.entries(paths).filter(([template, item]) => isRecord(item) && pathMatchesTemplate(path, template));
+	if (matches.length === 0) throw new Error(`No route matches "${path}". Run \`neon api --list\` to see available routes.`);
+	matches.sort((a, b) => {
+		const staticA = a[0].split("/").filter((p) => !p.startsWith("{")).length;
+		return b[0].split("/").filter((p) => !p.startsWith("{")).length - staticA;
+	});
+	const [template, pathItem] = matches[0];
+	if (!isRecord(pathItem)) throw new Error(`No route matches "${path}". Run \`neon api --list\` to see available routes.`);
+	return {
+		template,
+		pathItem
+	};
+}
+function availableMethods(pathItem) {
+	return DESCRIBE_METHODS.filter((method) => isRecord(pathItem[method.toLowerCase()]));
+}
+function collectParameters(spec, pathItem, operation, template) {
+	const raw = [...Array.isArray(pathItem.parameters) ? pathItem.parameters : [], ...Array.isArray(operation.parameters) ? operation.parameters : []];
+	const byKey = /* @__PURE__ */ new Map();
+	for (const entry of raw) {
+		const resolved = resolveParameter(spec, entry);
+		if (!resolved) continue;
+		const field = paramToField(spec, resolved);
+		if (!field) continue;
+		byKey.set(`${field.in}:${field.name}`, field);
+	}
+	const pathFields = pathParamNames(template).map((name) => {
+		const existing = byKey.get(`path:${name}`);
+		if (existing) return existing;
+		return {
+			in: "path",
+			name,
+			required: true,
+			type: "string",
+			description: ""
+		};
+	});
+	const query = [...byKey.values()].filter((field) => field.in === "query");
+	const header = [...byKey.values()].filter((field) => field.in === "header");
+	return [
+		...pathFields,
+		...query,
+		...header
+	];
+}
+function jsonBodySchema(spec, operation) {
+	let requestBody = operation.requestBody;
+	if (isRecord(requestBody) && typeof requestBody.$ref === "string") requestBody = resolveRef(spec, requestBody.$ref);
+	if (!isRecord(requestBody)) return null;
+	const content = requestBody.content;
+	if (!isRecord(content)) return null;
+	const json = content["application/json"];
+	let contentType = "application/json";
+	let selected = json;
+	if (!isRecord(json)) {
+		const entry = Object.entries(content).find(([, value]) => isRecord(value));
+		if (!entry) return null;
+		contentType = entry[0];
+		selected = entry[1];
+	}
+	if (!isRecord(selected) || selected.schema === void 0) return null;
+	return {
+		schema: selected.schema,
+		required: requestBody.required === true,
+		contentType
+	};
+}
+function describeOperation(spec, path, method) {
+	const methodUpper = method.toUpperCase();
+	const { template, pathItem } = matchPath(spec, path);
+	const available = availableMethods(pathItem);
+	const operation = pathItem[methodUpper.toLowerCase()];
+	if (!isRecord(operation)) {
+		const hint = available.length > 0 ? ` Available: ${available.join(", ")}. Pass -X ${available[0]}.` : " Run `neon api --list` to see available routes.";
+		throw new Error(`No ${methodUpper} ${template} in the spec.${hint}`);
+	}
+	const body = jsonBodySchema(spec, operation);
+	const fields = [...collectParameters(spec, pathItem, operation, template), ...body ? flattenBody(spec, body.schema, "") : []];
+	return {
+		method: methodUpper,
+		path: template,
+		summary: typeof operation.summary === "string" ? operation.summary : "",
+		operationId: typeof operation.operationId === "string" ? operation.operationId : "",
+		bodyRequired: body?.required === true,
+		contentType: body?.contentType ?? "",
+		fields
+	};
+}
 //#endregion
-export { DEFAULT_SPEC_URL, getEndpoints, loadSpec };
+export { DEFAULT_SPEC_URL, describeOperation, getEndpoints, loadSpec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,8 +64,8 @@
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
     "@neon/config": "1.0.5",
-    "@neon/config-runtime": "1.0.5",
-    "@neon/sdk": "3.0.0"
+    "@neon/sdk": "3.0.0",
+    "@neon/config-runtime": "1.0.5"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",