neon 4.3.1 → 4.5.0

package/README.md

@@ -64,6 +64,57 @@ neon projects list --api-key <neon_api_key>
 
 For information about obtaining an Neon API key, see [Authentication](https://neon.com/docs/reference/api/get-started), in the _Neon API Reference_.
 
+## Create a project without an account
+
+`neon claim create` provisions a temporary Claimable Neon project for an agent without
+requiring a Neon account or opening a browser:
+
+```bash
+# Lakebase Postgres is always included
+neon claim create
+
+# Request Managed Better Auth and the Data API too
+neon claim create --service auth --service data-api
+```
+
+When the current directory has a `neon.ts`, `claim create` also requests every service
+declared there. Explicit `--service` values are added to that set. Object Storage, Functions,
+and the AI Gateway are sent to the service so demand is recorded, but are reported as
+unavailable until the project is claimed; the CLI does not silently remove them.
+
+The command writes:
+
+- a `.neon` context that identifies the project and Claimable Neon service;
+- an owner-only identity assertion under the CLI config directory;
+- `DATABASE_URL` and any granted Auth or Data API variables to `.env` or `.env.local`
+  (disable this with `--no-env-pull`).
+
+Subsequent project commands automatically exchange the assertion for a short-lived agent
+token and send API calls to Claimable Neon. The service decides which operations are
+allowed before claim.
+
+```bash
+neon claim status                 # lifecycle and transfer status
+neon projects get <project-id>    # regular CLI command, same agent token
+neon psql --role-name neondb_owner -- -c "select now()"
+neon config plan
+neon env pull --service postgres --service auth --service data-api
+
+neon claim accept                 # create a claim code and open the transfer URL
+neon claim delete --yes           # permanently delete an unclaimed project
+neon claim list                   # local records, including expired
+neon claim delete <project-id> --yes
+```
+
+`status`, `accept`, and `delete` take an optional project id from `claim list`, so a
+project stays manageable after its original directory is gone. `list` prints `state`
+(`unclaimed` or `expired`) from the identity assertion clock and the project
+expiry, plus `project_expires_at`. `delete` also drops a
+local record whose identity assertion has expired or been revoked.
+
+`neon claimable` is an alias for `neon claim`. For local service development, set
+`CLAIMABLE_NEON_HOST=http://localhost:8787`; non-local origins must use HTTPS.
+
 ## Project and branch creation
 
 Choose the PostgreSQL version when creating a project:
@@ -791,6 +842,34 @@ On a TTY the command asks which agents and which skills, then shows a summary to
 
 `--agent` names match `neon mcp`, minus agents that cannot install skills: `antigravity`, `cline`, `cline-cli`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `opencode`, `vscode`, `windsurf`, `zed`. `mcporter` is a known MCP name that is then skipped.
 
+## Install the Neon plugin (`plugins`)
+
+`neon plugins` installs the Neon agent plugin (`neon-postgres`) by running `npx plugins add`. It does not call the Neon API.
+
+```bash
+# Interactive: agents, then confirm.
+$ neon plugins
+
+# Skip prompts. Every detected agent.
+$ neon plugins -y
+
+$ neon plugins --agent cursor --agent claude-code
+
+# User-level install.
+$ neon plugins --global
+$ neon plugins --global --agent vscode
+```
+
+On a TTY the command asks which agents, then shows a summary to confirm. Detected agents start selected from project-folder markers such as `.cursor`. There is one plugin (`neon-postgres`); there is no plugin picker and no `update` subcommand.
+
+`-y` skips those questions and installs into every detected agent. `--agent` names specific agents and skips the agent picker. Without a TTY, pass `-y` or `--agent`. `--agent` alone is enough because the plugin is fixed.
+
+Default scope is `project`. `--global` is `user`. On macOS and Linux, Cursor and Claude Code store the plugin cache under `~/.claude/plugins`; on Windows, Cursor installs into Cursor extensions. `project` vs `user` is the scope field the plugins CLI records, not a directory in the repo. VS Code, GitHub Copilot CLI, and Grok Build only install user-level: they are skipped at the default scope with a warning, and `--agent vscode` without `--global` fails if nothing else is selected.
+
+`--agent` names with a plugins mapping: `claude-code`, `claude-desktop`, `codex`, `cursor`, `github-copilot-cli`, `grok-build`, `vscode`. `claude-desktop` installs as Claude Code; naming both produces one install and lists both names in the table. `mcporter` is a known MCP name that is then skipped.
+
+The plugins CLI installs every plugin it finds in the Neon plugin package. Today that is `neon-postgres`.
+
 ## Snapshots (`snapshots`)
 
 `neon snapshots` (alias `neon snapshot`) manages **snapshots** — point-in-time backups of a branch that you can list, rename, expire, restore into a branch, or schedule automatically. Snapshots are a Beta Neon feature and were previously only available in the Console and REST API; this command group brings them to the CLI.
@@ -1145,6 +1224,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | Command                                                                    | Subcommands                                                                                                  | Description                        |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
 | [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                                              | Authenticate                       |
+| 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                    |
 | [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                                  | Manage projects                    |
@@ -1171,6 +1251,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | bootstrap                                                                  |                                                                                                              | Scaffold a project from a template |
 | init                                                                       |                                                                                                              | Set up a project for a coding agent |
 | mcp                                                                        |                                                                                                              | Install the Neon MCP server         |
+| plugins                                                                    |                                                                                                              | Install the Neon plugin             |
 | skills                                                                     | `update`                                                                                                     | Install Neon agent skills           |
 | bucket                                                                     | `create`, `list`, `delete`, `object list`, `object get`, `object put`, `object delete` (incl. `--recursive`) | Manage buckets and their objects   |
 | [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                                              | Generate a completion script       |

package/dist/_chunks/{auth_selection-Bx2NAgkk.js → auth_selection-ktL6uoEe.js}

@@ -1,4 +1,4 @@
-import "./profiles-CVXNvU2r.js";
+import "./profiles-D95AeZ5v.js";
 //#region ../../internals/cli-core/dist/auth_selection.js
 /**
 * # Which credential an invocation authenticates with

package/dist/_chunks/{credential_io-D2vw1UOw.js → credential_io-B1JxWELN.js}

@@ -1,5 +1,6 @@
-import { b as writeSecretFile, f as profilesFilePath, v as CRED_STORAGE_FILE, y as CRED_STORAGE_KEYRING } from "./profiles-CVXNvU2r.js";
+import { t as writeSecretFile } from "./secure_file-BucZj4yQ.js";
 import { o as isOwnedCredentialPath } from "./paths-g3DRqJiD.js";
+import { f as profilesFilePath, v as CRED_STORAGE_FILE, y as CRED_STORAGE_KEYRING } from "./profiles-D95AeZ5v.js";
 import { tryLoadKeyring } from "../keyring.js";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { dirname } from "node:path";

package/dist/_chunks/{profiles-CVXNvU2r.js → profiles-D95AeZ5v.js}

@@ -1,42 +1,7 @@
+import { t as writeSecretFile } from "./secure_file-BucZj4yQ.js";
 import { i as defaultDir, r as credentialsPath, s as resolveConfigFile } from "./paths-g3DRqJiD.js";
-import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-//#region ../../internals/cli-core/dist/secure_file.js
-/**
-* Write a secret to disk owner-only, by creating a temporary file in the same directory and
-* renaming it over the target.
-*
-* The rename is what makes this correct rather than merely tidy. `writeFileSync`'s `mode`
-* applies only when it *creates* the file, so writing over an existing credentials file
-* leaves whatever permissions it already had — a file created `0700` by an older release
-* stays `0700` forever, and one created before a umask change stays world-readable. Renaming
-* a fresh inode into place means every write lands at {@link SECRET_FILE_MODE}, so the
-* permissions repair themselves instead of being inherited.
-*
-* It also closes the window where a reader could see the file at default permissions: the
-* temporary file is created `0600` *before* it holds the secret's final name, and `rename`
-* is atomic within a directory, so there is no moment at which the target is readable by
-* anyone else and no moment at which it is half-written.
-*
-* The temporary name carries the pid so two processes writing at once cannot collide on it.
-*/
-const writeSecretFile = (path, contents) => {
-	const directory = dirname(path);
-	const temporary = join(directory, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
-	try {
-		writeFileSync(temporary, contents, {
-			encoding: "utf8",
-			mode: 384
-		});
-		renameSync(temporary, path);
-	} catch (err) {
-		try {
-			unlinkSync(temporary);
-		} catch {}
-		throw err;
-	}
-};
-//#endregion
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
 //#region ../../internals/cli-core/dist/cli_config.js
 const CRED_STORAGE_FILE = "file";
 const CRED_STORAGE_KEYRING = "keyring";
@@ -254,4 +219,4 @@ function nonEmpty(value) {
 	return trimmed === "" ? void 0 : trimmed;
 }
 //#endregion
-export { upsertProfile as _, canDropProfilesFile as a, writeSecretFile as b, listProfiles as c, newProfileLocation as d, profilesFilePath as f, selectProfileName as g, resolveProfile as h, assertValidProfileName as i, locationForName as l, readProfiles as m, KEYRING_CREDENTIALS as n, credentialsDisplay as o, profilesUsingPath as p, assertProfilesUsable as r, isKeyringPointer as s, DEFAULT_PROFILE as t, locationOf as u, CRED_STORAGE_FILE as v, CRED_STORAGE_KEYRING as y };
+export { upsertProfile as _, canDropProfilesFile as a, listProfiles as c, newProfileLocation as d, profilesFilePath as f, selectProfileName as g, resolveProfile as h, assertValidProfileName as i, locationForName as l, readProfiles as m, KEYRING_CREDENTIALS as n, credentialsDisplay as o, profilesUsingPath as p, assertProfilesUsable as r, isKeyringPointer as s, DEFAULT_PROFILE as t, locationOf as u, CRED_STORAGE_FILE as v, CRED_STORAGE_KEYRING as y };

package/dist/_chunks/secure_file-BucZj4yQ.js

@@ -0,0 +1,39 @@
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+//#region ../../internals/cli-core/dist/secure_file.js
+/**
+* Write a secret to disk owner-only, by creating a temporary file in the same directory and
+* renaming it over the target.
+*
+* The rename is what makes this correct rather than merely tidy. `writeFileSync`'s `mode`
+* applies only when it *creates* the file, so writing over an existing credentials file
+* leaves whatever permissions it already had — a file created `0700` by an older release
+* stays `0700` forever, and one created before a umask change stays world-readable. Renaming
+* a fresh inode into place means every write lands at {@link SECRET_FILE_MODE}, so the
+* permissions repair themselves instead of being inherited.
+*
+* It also closes the window where a reader could see the file at default permissions: the
+* temporary file is created `0600` *before* it holds the secret's final name, and `rename`
+* is atomic within a directory, so there is no moment at which the target is readable by
+* anyone else and no moment at which it is half-written.
+*
+* The temporary name carries the pid so two processes writing at once cannot collide on it.
+*/
+const writeSecretFile = (path, contents) => {
+	const directory = dirname(path);
+	const temporary = join(directory, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+	try {
+		writeFileSync(temporary, contents, {
+			encoding: "utf8",
+			mode: 384
+		});
+		renameSync(temporary, path);
+	} catch (err) {
+		try {
+			unlinkSync(temporary);
+		} catch {}
+		throw err;
+	}
+};
+//#endregion
+export { writeSecretFile as t };

package/dist/analytics.js

@@ -1,5 +1,5 @@
-import { a as OAUTH, t as storeFor } from "./_chunks/credential_io-D2vw1UOw.js";
-import { getGithubEnvVars, isCi } from "./env.js";
+import { a as OAUTH, t as storeFor } from "./_chunks/credential_io-B1JxWELN.js";
+import { getCliAgent, getGithubEnvVars, isCi } from "./env.js";
 import { log } from "./log.js";
 import pkg_default from "./pkg.js";
 import { getApiClient, isNeonApiError } from "./api.js";
@@ -190,13 +190,15 @@ const trackEvent = (event, properties) => {
 };
 const getErrorAnalyticsEventContext = (_args) => ({
 	version: pkg_default.version,
-	ci: isCi()
+	ci: isCi(),
+	agent: getCliAgent(process.env)
 });
 const getAnalyticsEventProperties = (args) => ({
 	version: pkg_default.version,
 	command: args._.join(" "),
 	flags: { output: args.output },
 	ci: isCi(),
+	agent: getCliAgent(process.env),
 	githubEnvVars: getGithubEnvVars(process.env)
 });
 //#endregion

package/dist/api.js

@@ -52,6 +52,13 @@ function messageFromBody(body) {
 		const message = body.message;
 		if (typeof message === "string") return message;
 	}
+	if (body && typeof body === "object" && "error" in body) {
+		const error = body.error;
+		if (error && typeof error === "object" && "message" in error) {
+			const message = error.message;
+			if (typeof message === "string") return message;
+		}
+	}
 }
 /** Extract a machine-readable `code` string from a parsed error body, if present. */
 function codeFromBody(body) {
@@ -59,6 +66,13 @@ function codeFromBody(body) {
 		const code = body.code;
 		if (typeof code === "string") return code;
 	}
+	if (body && typeof body === "object" && "error" in body) {
+		const error = body.error;
+		if (error && typeof error === "object" && "code" in error) {
+			const code = error.code;
+			if (typeof code === "string") return code;
+		}
+	}
 }
 /**
 * Adapt a WHATWG `ReadableStream` (what `fetch` gives us as `response.body`) to

package/dist/auth_context.js

@@ -38,6 +38,7 @@ const authFailureMessage = (context) => {
 	const profile = context?.profile ?? "the selected profile";
 	const where = context?.storage === "keyring" ? " (OS keyring)" : context?.credentialsPath !== void 0 ? ` (${context.credentialsPath})` : "";
 	if (context?.source === "profile-api-key") return `Authentication failed: the Neon API rejected profile "${profile}"'s API key${where}. Replace it with \`neon profile create ${profile} --mint\`, or store another with \`neon profile create ${profile} --api-key -\`.`;
+	if (context?.source === "claimable") return `Authentication failed: Claimable Neon rejected the linked project's short-lived access token${where}. Retry the command to exchange the saved identity assertion again; if it still fails, run \`neon claim status\`.`;
 	if (context?.source === "stored-credentials") {
 		if (context.storage === "keyring") return `Authentication failed: the Neon API rejected profile "${profile}"'s stored session (OS keyring). Sign in again with \`neon auth --profile ${profile}\`.`;
 		return `Authentication failed: the Neon API rejected profile "${profile}"'s stored session${where}. That file was not created by neon, so it was left alone — sign in again with \`neon auth --profile ${profile}\`.`;

package/dist/claimable/api.js

@@ -0,0 +1,242 @@
+//#region src/claimable/api.ts
+const REQUEST_TIMEOUT_MS = 6e4;
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+const DEFAULT_CLAIMABLE_ORIGIN = "https://claimable.neon.tech";
+var ClaimableServiceError = class extends Error {
+	constructor(status, metadata, details) {
+		super(metadata.message);
+		this.name = "ClaimableServiceError";
+		this.status = status;
+		this.code = metadata.code;
+		this.retryable = metadata.retryable;
+		this.requestId = metadata.requestId;
+		this.details = details;
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const record = (value, action) => {
+	if (!isRecord(value)) throw invalidResponse(action);
+	return value;
+};
+const stringField = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "string" || field.length === 0) throw invalidResponse(action);
+	return field;
+};
+const stringFieldAllowEmpty = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "string") throw invalidResponse(action);
+	return field;
+};
+const numberField = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "number" || !Number.isFinite(field) || field <= 0) throw invalidResponse(action);
+	return field;
+};
+const booleanField = (value, key, action) => {
+	const field = value[key];
+	if (typeof field !== "boolean") throw invalidResponse(action);
+	return field;
+};
+const stringArrayField = (value, key, action) => {
+	const field = value[key];
+	if (!Array.isArray(field) || !field.every((item) => typeof item === "string" && item.length > 0)) throw invalidResponse(action);
+	return field;
+};
+const invalidResponse = (action) => /* @__PURE__ */ new Error(`Claimable Neon returned an invalid response while ${action}. The response was not used.`);
+const parseCapabilityDecision = (value, action) => {
+	const decision = record(value, action);
+	const capability = stringField(decision, "capability", action);
+	if (booleanField(decision, "granted", action)) return {
+		capability,
+		granted: true
+	};
+	return {
+		capability,
+		granted: false,
+		reason: stringField(decision, "reason", action),
+		message: stringField(decision, "message", action)
+	};
+};
+const parseRegistrationResponse = (value) => {
+	const action = "registering an anonymous identity";
+	const response = record(value, action);
+	const project = record(response.project, action);
+	const capabilities = response.capabilities;
+	if (!Array.isArray(capabilities)) throw invalidResponse(action);
+	return {
+		registrationId: stringField(response, "registration_id", action),
+		identityAssertion: stringField(response, "identity_assertion", action),
+		assertionExpires: numberField(response, "assertion_expires", action),
+		scopes: stringArrayField(response, "scopes", action),
+		project: {
+			id: stringField(project, "id", action),
+			branchId: stringField(project, "branch_id", action),
+			expiresAt: stringField(project, "expires_at", action)
+		},
+		capabilities: capabilities.map((item) => parseCapabilityDecision(item, action))
+	};
+};
+const parseTokenResponse = (value) => {
+	const action = "exchanging the identity assertion";
+	const response = record(value, action);
+	if (response.token_type !== "Bearer") throw invalidResponse(action);
+	return {
+		accessToken: stringField(response, "access_token", action),
+		expiresIn: numberField(response, "expires_in", action),
+		scope: stringFieldAllowEmpty(response, "scope", action)
+	};
+};
+const parseCredentialsResponse = (value) => {
+	const action = "fetching project credentials";
+	const response = record(value, action);
+	const services = record(response.services, action);
+	const authValue = services.auth;
+	const dataApiValue = services.data_api;
+	const auth = authValue === void 0 ? void 0 : (() => {
+		const parsed = record(authValue, action);
+		return {
+			baseUrl: stringField(parsed, "base_url", action),
+			jwksUrl: stringField(parsed, "jwks_url", action)
+		};
+	})();
+	const dataApi = dataApiValue === void 0 ? void 0 : (() => {
+		const parsed = record(dataApiValue, action);
+		return { url: stringField(parsed, "url", action) };
+	})();
+	return {
+		projectId: stringField(response, "project_id", action),
+		branchId: stringField(response, "branch_id", action),
+		databaseUrl: stringField(response, "database_url", action),
+		expiresAt: stringField(response, "expires_at", action),
+		services: {
+			...auth === void 0 ? {} : { auth },
+			...dataApi === void 0 ? {} : { dataApi }
+		}
+	};
+};
+const parseClaimCodeResponse = (value) => {
+	const action = "creating a claim code";
+	const response = record(value, action);
+	return {
+		userCode: stringField(response, "user_code", action),
+		verificationUri: stringField(response, "verification_uri", action),
+		verificationUriComplete: stringField(response, "verification_uri_complete", action),
+		expiresIn: numberField(response, "expires_in", action),
+		interval: numberField(response, "interval", action)
+	};
+};
+const parseClaimStatusResponse = (value) => {
+	const action = "fetching claim status";
+	const response = record(value, action);
+	return {
+		state: stringField(response, "state", action),
+		expiresAt: stringField(response, "expires_at", action),
+		reconciled: booleanField(response, "reconciled", action)
+	};
+};
+const normalizeOrigin = (origin) => {
+	let url;
+	try {
+		url = new URL(origin);
+	} catch {
+		throw new Error(`Invalid Claimable Neon origin "${origin}".`);
+	}
+	if (url.username || url.password || url.search || url.hash || url.pathname !== "/") throw new Error(`Claimable Neon origin must contain only a scheme and host, got "${origin}".`);
+	if (url.protocol !== "https:" && url.hostname !== "localhost") throw new Error("Claimable Neon requires HTTPS except when testing against localhost.");
+	return url.origin;
+};
+const parseErrorMetadata = (status, statusText, payload) => {
+	if (!isRecord(payload) || !isRecord(payload.error)) return {
+		code: "unknown_error",
+		message: `Claimable Neon returned HTTP ${status} ${statusText}.`,
+		retryable: status === 429 || status >= 500
+	};
+	const error = payload.error;
+	return {
+		code: typeof error.code === "string" && error.code.length > 0 ? error.code : "unknown_error",
+		message: typeof error.message === "string" && error.message.length > 0 ? error.message : `Claimable Neon returned HTTP ${status} ${statusText}.`,
+		retryable: typeof error.retryable === "boolean" ? error.retryable : status === 429 || status >= 500,
+		requestId: typeof error.request_id === "string" ? error.request_id : void 0
+	};
+};
+const readJson = async (response) => {
+	const text = await response.text();
+	if (text.trim() === "") return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new Error(`Claimable Neon returned non-JSON content with HTTP ${response.status}.`);
+	}
+};
+var ClaimableClient = class {
+	constructor(origin = DEFAULT_CLAIMABLE_ORIGIN) {
+		this.origin = normalizeOrigin(origin);
+	}
+	async register(input) {
+		return parseRegistrationResponse(await this.request("/v1/agent/identity", {
+			method: "POST",
+			json: {
+				type: "anonymous",
+				capabilities: input.capabilities,
+				source: input.source
+			}
+		}));
+	}
+	async exchange(identityAssertion) {
+		return parseTokenResponse(await this.request("/v1/oauth2/token", {
+			method: "POST",
+			form: new URLSearchParams({
+				grant_type: JWT_BEARER_GRANT,
+				assertion: identityAssertion,
+				resource: `${this.origin}/`
+			})
+		}));
+	}
+	async credentials(projectId, accessToken) {
+		return parseCredentialsResponse(await this.request(`/v1/projects/${encodeURIComponent(projectId)}/credentials`, { accessToken }));
+	}
+	async createClaim(projectId, accessToken) {
+		return parseClaimCodeResponse(await this.request(`/v1/projects/${encodeURIComponent(projectId)}/claim`, {
+			method: "POST",
+			accessToken
+		}));
+	}
+	async claimStatus(projectId, accessToken) {
+		return parseClaimStatusResponse(await this.request(`/v1/projects/${encodeURIComponent(projectId)}/claim`, { accessToken }));
+	}
+	async deleteProject(projectId, accessToken) {
+		await this.request(`/v1/projects/${encodeURIComponent(projectId)}`, {
+			method: "DELETE",
+			accessToken
+		});
+	}
+	async request(path, options = {}) {
+		const headers = new Headers({ accept: "application/json" });
+		if (options.accessToken) headers.set("authorization", `Bearer ${options.accessToken}`);
+		let body;
+		if (options.json !== void 0) {
+			headers.set("content-type", "application/json");
+			body = JSON.stringify(options.json);
+		} else if (options.form !== void 0) {
+			headers.set("content-type", "application/x-www-form-urlencoded");
+			body = options.form.toString();
+		}
+		let response;
+		try {
+			response = await fetch(new URL(path, `${this.origin}/`), {
+				method: options.method ?? "GET",
+				headers,
+				body,
+				signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+			});
+		} catch {
+			throw new Error(`Could not reach Claimable Neon at ${this.origin}. Check the connection and retry.`);
+		}
+		const payload = await readJson(response);
+		if (!response.ok) throw new ClaimableServiceError(response.status, parseErrorMetadata(response.status, response.statusText, payload), payload);
+		return payload;
+	}
+};
+//#endregion
+export { ClaimableClient, ClaimableServiceError, DEFAULT_CLAIMABLE_ORIGIN, parseClaimCodeResponse, parseClaimStatusResponse, parseCredentialsResponse, parseRegistrationResponse, parseTokenResponse };

package/dist/claimable/state.js

@@ -0,0 +1,92 @@
+import { t as writeSecretFile } from "../_chunks/secure_file-BucZj4yQ.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+//#region src/claimable/state.ts
+const FILE_PREFIX = "claimable-credential.";
+const FILE_SUFFIX = ".json";
+const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0;
+const assertProjectId = (projectId) => {
+	if (!PROJECT_ID.test(projectId)) throw new Error(`Invalid Claimable Neon project ID "${projectId}".`);
+};
+const claimableCredentialsPath = (configDir, projectId) => {
+	assertProjectId(projectId);
+	return join(configDir, `${FILE_PREFIX}${projectId}${FILE_SUFFIX}`);
+};
+const parseStoredCredentials = (value, path, expectedProjectId) => {
+	if (!isRecord(value) || value.version !== 1 || !nonEmptyString(value.origin) || !nonEmptyString(value.registrationId) || !nonEmptyString(value.projectId) || !nonEmptyString(value.branchId) || !nonEmptyString(value.identityAssertion) || !nonEmptyString(value.expiresAt)) throw new Error(`${path} does not contain a valid Claimable Neon credential. Delete it and run \`neon claim create\` again.`);
+	assertProjectId(value.projectId);
+	if (expectedProjectId !== void 0 && value.projectId !== expectedProjectId) throw new Error(`${path} belongs to a different Claimable Neon project. Delete it and run \`neon claim create\` again.`);
+	const assertionExpires = optionalUnixSeconds(value.assertionExpires, path);
+	return {
+		version: 1,
+		origin: value.origin,
+		registrationId: value.registrationId,
+		projectId: value.projectId,
+		branchId: value.branchId,
+		identityAssertion: value.identityAssertion,
+		expiresAt: value.expiresAt,
+		...assertionExpires === void 0 ? {} : { assertionExpires }
+	};
+};
+const optionalUnixSeconds = (value, path) => {
+	if (value === void 0) return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error(`${path} does not contain a valid Claimable Neon credential. Delete it and run \`neon claim create\` again.`);
+	return value;
+};
+const assertionHasExpired = (credentials, now = Date.now()) => credentials.assertionExpires !== void 0 && credentials.assertionExpires * 1e3 <= now;
+const writeClaimableCredentials = (configDir, credentials) => {
+	mkdirSync(configDir, { recursive: true });
+	const path = claimableCredentialsPath(configDir, credentials.projectId);
+	writeSecretFile(path, JSON.stringify(credentials));
+};
+const readClaimableCredentials = (configDir, projectId) => {
+	const path = claimableCredentialsPath(configDir, projectId);
+	if (!existsSync(path)) return null;
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new Error(`${path} is not valid JSON, so the Claimable Neon credential cannot be read. Delete it and run \`neon claim create\` again.`);
+	}
+	return parseStoredCredentials(parsed, path, projectId);
+};
+const listClaimableCredentials = (configDir) => {
+	if (!existsSync(configDir)) return [];
+	return readdirSync(configDir).filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX)).sort().map((name) => {
+		const path = join(configDir, name);
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(path, "utf8"));
+		} catch {
+			throw new Error(`${path} is not valid JSON, so the Claimable Neon credential cannot be listed. Delete it and run \`neon claim create\` again.`);
+		}
+		return parseStoredCredentials(parsed, path);
+	}).sort((left, right) => left.projectId.localeCompare(right.projectId));
+};
+const removeClaimableCredentials = (configDir, projectId) => {
+	const path = claimableCredentialsPath(configDir, projectId);
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if (isRecord(error) && typeof error.code === "string" && error.code === "ENOENT") return;
+		throw error;
+	}
+};
+const resolveClaimableContext = (context) => {
+	const marker = context.claimable;
+	if (marker === void 0) return null;
+	if (!isRecord(marker)) throw new Error("The linked .neon file has an invalid \"claimable\" marker. Delete the claimable field from .neon, or delete .neon.");
+	if (marker.version !== 1) throw new Error(`Unsupported Claimable Neon context version in .neon. Update the Neon CLI before using this project.`);
+	if (!nonEmptyString(marker.origin) || !nonEmptyString(context.projectId)) throw new Error("The linked .neon file has an incomplete \"claimable\" marker. Delete the claimable field from .neon, or delete .neon.");
+	assertProjectId(context.projectId);
+	return {
+		origin: marker.origin,
+		projectId: context.projectId,
+		...nonEmptyString(context.branch) ? { branch: context.branch } : {}
+	};
+};
+const shouldUseClaimableCredentials = (inputs, profileFlag, context) => inputs.apiKeyFlag.trim() === "" && inputs.apiKeyEnv.trim() === "" && inputs.profileEnv.trim() === "" && (profileFlag === void 0 || profileFlag.trim() === "") && resolveClaimableContext(context) !== null;
+//#endregion
+export { assertionHasExpired, claimableCredentialsPath, listClaimableCredentials, readClaimableCredentials, removeClaimableCredentials, resolveClaimableContext, shouldUseClaimableCredentials, writeClaimableCredentials };