neon 2.29.2 → 2.30.0

package/README.md

@@ -8,7 +8,7 @@ The Neon CLI is a command-line interface that lets you manage [Neon Serverless P
 npm i -g neon
 ```
 
-Requires Node.js 18.0 or higher.
+Requires Node.js 20.19 or higher.
 
 **Howebrew**
 
@@ -28,7 +28,7 @@ Download a binary file [here](https://github.com/neondatabase/neonctl/releases).
 npm update -g neon
 ```
 
-Requires Node.js 18.0 or higher.
+Requires Node.js 20.19 or higher.
 
 **Howebrew**
 

package/dist/api.js

@@ -287,6 +287,12 @@ export const getApiClient = ({ apiKey, apiHost }) => {
             headers["Content-Type"] = ContentType.Json;
             payload = JSON.stringify(params.body);
         }
+        // Caller-supplied headers win over the defaults set above.
+        if (params.headers) {
+            for (const [key, value] of Object.entries(params.headers)) {
+                headers[key] = value;
+            }
+        }
         let response;
         try {
             response = await timedFetch(url, {

package/dist/commands/api.js

@@ -0,0 +1,278 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import YAML from "yaml";
+import { DEFAULT_SPEC_URL, getEndpoints, loadSpec } from "../utils/openapi.js";
+import { writer } from "../writer.js";
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+// ── Pure helpers (unit-tested) ───────────────────────────────────────────────
+/**
+ * Coerce a raw string into a typed JSON value: booleans, `null`, integers,
+ * floats, and JSON arrays/objects are parsed; everything else stays a string.
+ */
+export 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 `=`. */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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. */
+export 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(", ")}.`);
+    }
+}
+// ── I/O helpers ──────────────────────────────────────────────────────────────
+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.",
+    });
+}
+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 !== undefined) {
+        body = await readData(args.data);
+    }
+    else if (fields.length > 0 || rawFields.length > 0) {
+        body = buildBody(fields, rawFields);
+    }
+    const hasBody = body !== undefined;
+    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 } : {}),
+    };
+    const response = await args.apiClient.request(params);
+    const out = process.stdout;
+    if (args.include) {
+        out.write(`HTTP ${response.status} ${response.statusText}\n`);
+        for (const [key, value] of Object.entries(response.headers)) {
+            out.write(`${key}: ${value}\n`);
+        }
+        out.write("\n");
+    }
+    if (response.data === undefined) {
+        return;
+    }
+    if (args.output === "yaml") {
+        out.write(YAML.stringify(response.data));
+    }
+    else {
+        out.write(`${JSON.stringify(response.data, null, 2)}\n`);
+    }
+}
+export const command = "api [path]";
+export const describe = "Call any Neon API route directly (authenticated passthrough)";
+export 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.",
+    },
+    refresh: {
+        type: "boolean",
+        default: false,
+        describe: "Refresh the cached OpenAPI spec (used with --list).",
+    },
+    "spec-url": {
+        type: "string",
+        default: process.env.NEON_API_SPEC_URL ?? DEFAULT_SPEC_URL,
+        hidden: true,
+        describe: "OpenAPI spec URL used by --list.",
+    },
+})
+    .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");
+export const handler = async (args) => {
+    const apiArgs = args;
+    if (apiArgs.list || apiArgs.path === "list" || apiArgs.path === "ls") {
+        await listEndpoints(apiArgs);
+        return;
+    }
+    await runRequest(apiArgs);
+};

package/dist/commands/index.js

@@ -1,3 +1,4 @@
+import * as api from "./api.js";
 import * as auth from "./auth.js";
 import * as bootstrap from "./bootstrap.js";
 import * as branches from "./branches.js";
@@ -26,6 +27,7 @@ import * as users from "./user.js";
 import * as vpcEndpoints from "./vpc_endpoints.js";
 export default [
     auth,
+    api,
     users,
     orgs,
     projects,

package/dist/index.js

@@ -14,6 +14,9 @@ import { log } from "./log.js";
 import pkg from "./pkg.js";
 import { fillInArgs } from "./utils/middlewares.js";
 const NO_SUBCOMMANDS_VERBS = [
+    // `api <path>` has a handler but no subcommands (like `status`), so the
+    // help-fallback middleware must not intercept a bare `neon api /projects`.
+    "api",
     // aliases
     "auth",
     "login",

package/dist/utils/openapi.js

@@ -0,0 +1,114 @@
+// Lightweight loader for the Neon OpenAPI spec, used by `neon api --list` to
+// enumerate the available routes. The `neon api <path>` request path does NOT
+// depend on this module — it is a pure passthrough — so a stale or unreachable
+// spec never blocks a real API call. Listing degrades gracefully: fresh cache →
+// live fetch → stale cache → clear error.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { log } from "../log.js";
+/** Public URL of the released Neon OpenAPI v2 spec. */
+export const DEFAULT_SPEC_URL = "https://neon.com/api_spec/release/v2.json";
+const CACHE_FILE = "openapi-spec.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10000;
+const HTTP_METHODS = new Set([
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+]);
+async function fetchSpec(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: { Accept: "application/json" },
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to fetch OpenAPI spec (${res.status} ${res.statusText})`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function readCache(cachePath) {
+    try {
+        return JSON.parse(readFileSync(cachePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cachePath, data) {
+    try {
+        mkdirSync(dirname(cachePath), { recursive: true });
+        writeFileSync(cachePath, JSON.stringify(data));
+    }
+    catch (err) {
+        log.debug("Failed to cache OpenAPI spec: %s", err);
+    }
+}
+/**
+ * Load the Neon OpenAPI spec, preferring a fresh on-disk cache, then a live
+ * fetch (which refreshes the cache), then a stale cache as a last resort.
+ * Returns `null` when no spec can be obtained.
+ */
+export async function loadSpec(opts) {
+    const { configDir, specUrl, refresh } = opts;
+    const cachePath = join(configDir, CACHE_FILE);
+    if (!refresh) {
+        const cached = readCache(cachePath);
+        if (cached &&
+            cached.specUrl === specUrl &&
+            Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+            log.debug("Using cached OpenAPI spec from %s", cachePath);
+            return cached.spec;
+        }
+    }
+    try {
+        log.debug("Fetching OpenAPI spec from %s", specUrl);
+        const spec = await fetchSpec(specUrl);
+        writeCache(cachePath, { fetchedAt: Date.now(), specUrl, spec });
+        return spec;
+    }
+    catch (err) {
+        log.debug("Failed to fetch OpenAPI spec: %s", err);
+        const stale = readCache(cachePath);
+        if (stale && stale.specUrl === specUrl) {
+            log.debug("Falling back to stale cached OpenAPI spec");
+            return stale.spec;
+        }
+        return null;
+    }
+}
+/** Flatten a spec into a sorted list of routes (by path, then method). */
+export function getEndpoints(spec) {
+    const endpoints = [];
+    for (const [path, item] of Object.entries(spec.paths ?? {})) {
+        for (const [method, op] of Object.entries(item)) {
+            if (!HTTP_METHODS.has(method.toLowerCase())) {
+                continue;
+            }
+            const operation = (op ?? {});
+            endpoints.push({
+                method: method.toUpperCase(),
+                path,
+                summary: operation.summary,
+                operationId: operation.operationId,
+                tags: operation.tags ?? [],
+            });
+        }
+    }
+    endpoints.sort((a, b) => a.path === b.path
+        ? a.method.localeCompare(b.method)
+        : a.path.localeCompare(b.path));
+    return endpoints;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "2.29.2",
+  "version": "2.30.0",
   "description": "CLI tool for Neon Serverless Postgres",
   "keywords": [
     "neon",
@@ -31,7 +31,7 @@
     "package.json"
   ],
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=20.19.0"
   },
   "dependencies": {
     "@hono/node-server": "2.0.4",
@@ -42,7 +42,7 @@
     "cliui": "8.0.1",
     "diff": "5.2.0",
     "fflate": "^0.8.3",
-    "neon-init": "0.19.0",
+    "neon-init": "0.20.0",
     "open": "10.1.0",
     "openid-client": "6.8.1",
     "pg-protocol": "^1.14.0",
@@ -51,10 +51,10 @@
     "which": "3.0.1",
     "yaml": "2.4.5",
     "yargs": "17.7.2",
-    "@neon/sdk": "0.1.0",
-    "@neon/config": "0.8.1",
-    "@neon/config-runtime": "0.8.1",
-    "@neon/env": "0.9.0"
+    "@neon/config": "0.9.0",
+    "@neon/sdk": "0.2.0",
+    "@neon/config-runtime": "0.9.0",
+    "@neon/env": "0.10.0"
   },
   "optionalDependencies": {
     "esbuild": "0.28.0"