@theholocron/holocron-plugin-neon 2.0.0-alpha.9 → 2.0.0

package/README.md

@@ -1,3 +1,5 @@
+<!-- editorconfig-checker-disable-file -->
+
 # `@theholocron/holocron-plugin-neon`
 
 Neon plugin for [Holocron](../cli). Implements the `storage`
@@ -5,8 +7,10 @@ capability against [Neon's REST API](https://api-docs.neon.tech/reference/gettin
 
 ## Install
 
+<!-- prettier-ignore -->
 ```bash
 pnpm add -D @theholocron/holocron-plugin-neon@alpha
+
 ```
 
 ## Auth
@@ -19,16 +23,18 @@ Token resolution order:
 
 ## Config
 
+<!-- prettier-ignore -->
 ```jsonc
 {
-	"providers": {
-		"storage": ["neon", { "projectId": "ancient-resonance-…" }],
-	},
+  "providers": {
+    "storage": ["neon", { "projectId": "ancient-resonance-…" }],
+  },
 }
+
 ```
 
 - `projectId` (required) — the Neon project id. The plugin binds to
-	this project; every method operates within it.
+  this project; every method operates within it.
 
 ## What's implemented
 

package/dist/index.d.mts

@@ -1,67 +1,19 @@
-import { ConnectionStringOptions, Storage, StorageBranch } from "@theholocron/cli";
+import { AuthError, ConnectionStringOptions, ResolveTokenInput, Storage, StorageBranch } from "@theholocron/cli";
+import { NeonClient, NeonClient as NeonClient$1, createNeonClient } from "@theholocron/neon-client";
 
 //#region src/auth.d.ts
-/**
- * Token resolution for the Neon plugin.
- *
- * Resolution order (matches the standard 4-step precedence set by
- * `.notes/tech-auth-bootstrap.spec.md`):
- *   1. explicit `cliToken` argument (from `--token` flag)
- *   2. HOLOCRON_NEON_API_KEY env var (preferred — explicit intent)
- *   3. NEON_API_KEY env var (the default Neon CLI reads)
- *   4. keyring (com.theholocron.cli / "neon")
- *   5. AuthError naming all four options + the bootstrap hint
- */
-declare class AuthError extends Error {
-  name: string;
-}
-interface ResolveTokenInput {
-  /** From `--token` CLI flag. */
-  cliToken?: string;
-  /** Env vars; passed in for testability. Defaults to `process.env`. */
-  env?: NodeJS.ProcessEnv;
-  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
-  keyring?: (provider: string) => string | null;
-}
-declare function resolveToken(input?: ResolveTokenInput): string;
-//#endregion
-//#region src/rest.d.ts
-/**
- * Thin REST wrapper around console.neon.tech/api/v2.
- *
- * Same pattern as the GitHub + Vercel REST clients — bearer auth,
- * JSON-only bodies, transport-failure wrapping with status: 0 so the
- * orchestrator's soft-skip path sees a clear "Neon GET /path failed"
- * message instead of a generic `TypeError: fetch failed`.
- */
-interface RestClientOptions {
-  token: string;
-  fetch?: typeof fetch;
-  baseUrl?: string;
-}
-interface RequestOptions {
-  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
-  body?: unknown;
-  query?: Record<string, string>;
-}
-declare class NeonRestClient {
-  private readonly token;
-  private readonly fetchImpl;
-  readonly baseUrl: string;
-  constructor(opts: RestClientOptions);
-  request<T>(path: string, opts?: RequestOptions): Promise<T>;
-}
+declare const resolveToken: (input?: import("@theholocron/http-client").ResolveTokenInput) => string;
 //#endregion
 //#region src/capabilities/storage.d.ts
 interface StorageOptions {
   projectId: string;
 }
 declare class NeonStorage implements Storage {
-  private readonly rest;
+  private readonly client;
+  private readonly opts;
   readonly key: "storage";
   readonly providerName = "neon";
-  private readonly base;
-  constructor(rest: NeonRestClient, opts: StorageOptions);
+  constructor(client: NeonClient$1, opts: StorageOptions);
   getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
   listBranches(): Promise<StorageBranch[]>;
   createBranch(input: {
@@ -118,7 +70,7 @@ interface NeonPluginOptions extends ResolveTokenInput {
 }
 interface PluginContext {
   options: NeonPluginOptions;
-  rest: NeonRestClient;
+  client: NeonClient;
 }
 declare function createContext(options: NeonPluginOptions): PluginContext;
 declare function storage(ctx: PluginContext): Storage;
@@ -136,4 +88,4 @@ declare function createPlugin(options: NeonPluginOptions): {
  */
 declare const AUTH_HINT: string;
 //#endregion
-export { AUTH_HINT, AuthError, NeonPluginOptions, NeonRestClient, NeonStorage, PluginContext, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, resolveToken, storage, verifyToken };
+export { AUTH_HINT, AuthError, type NeonClient, NeonPluginOptions, NeonStorage, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createNeonClient, createPlugin, resolveToken, storage, verifyToken };

package/dist/index.mjs

@@ -1,26 +1,12 @@
-import { ProviderApiError, getToken } from "@theholocron/cli";
+import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { createNeonClient } from "@theholocron/neon-client";
 //#region src/auth.ts
-/**
-* Token resolution for the Neon plugin.
-*
-* Resolution order (matches the standard 4-step precedence set by
-* `.notes/tech-auth-bootstrap.spec.md`):
-*   1. explicit `cliToken` argument (from `--token` flag)
-*   2. HOLOCRON_NEON_API_KEY env var (preferred — explicit intent)
-*   3. NEON_API_KEY env var (the default Neon CLI reads)
-*   4. keyring (com.theholocron.cli / "neon")
-*   5. AuthError naming all four options + the bootstrap hint
-*/
-var AuthError = class extends Error {
-	name = "AuthError";
-};
-function resolveToken(input = {}) {
-	const env = input.env ?? process.env;
-	const keyring = input.keyring ?? getToken;
-	const token = input.cliToken || env["HOLOCRON_NEON_API_KEY"] || env["NEON_API_KEY"] || keyring("neon");
-	if (!token) throw new AuthError("no Neon API key found. Pass --token <KEY>, set HOLOCRON_NEON_API_KEY / NEON_API_KEY, or run: holocron auth set neon <KEY>");
-	return token;
-}
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_NEON_API_KEY",
+	vendorEnvName: "NEON_API_KEY",
+	keyringService: "neon",
+	errorMessage: "no Neon API key found. Pass --token <KEY>, set HOLOCRON_NEON_API_KEY / NEON_API_KEY, or run: holocron auth set neon <KEY>"
+});
 //#endregion
 //#region src/capabilities/storage.ts
 /**
@@ -42,55 +28,46 @@ function resolveToken(input = {}) {
 * via `projectId` in options.
 */
 var NeonStorage = class {
-	rest;
+	client;
+	opts;
 	key = "storage";
 	providerName = "neon";
-	base;
-	constructor(rest, opts) {
-		this.rest = rest;
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
 		if (!opts.projectId) throw new Error("NeonStorage requires `projectId` in options");
-		this.base = `/projects/${opts.projectId}`;
 	}
 	async getConnectionString(scope, options = {}) {
 		const db = await this.firstDatabase(scope);
-		const params = {
+		const { uri } = await this.client.connection.uri(this.opts.projectId, {
 			branch_id: scope,
 			database_name: db.name,
 			role_name: db.owner_name,
 			pooled: options.pooled ? "true" : "false"
-		};
-		return (await this.rest.request(`${this.base}/connection_uri`, { query: params })).uri;
+		});
+		return uri;
 	}
 	async listBranches() {
-		return (await this.rest.request(`${this.base}/branches`)).branches.map(mapBranch);
+		const { branches } = await this.client.branches.list(this.opts.projectId);
+		return branches.map(mapBranch);
 	}
 	async createBranch(input) {
-		return mapBranch((await this.rest.request(`${this.base}/branches`, {
-			method: "POST",
-			body: {
-				branch: {
-					name: input.name,
-					...input.from ? { parent_id: input.from } : {}
-				},
-				endpoints: [{ type: "read_write" }]
-			}
-		})).branch);
+		const { branch } = await this.client.branches.create(this.opts.projectId, {
+			name: input.name,
+			...input.from ? { parent_id: input.from } : {},
+			endpoints: [{ type: "read_write" }]
+		});
+		return mapBranch(branch);
 	}
 	async destroyBranch(branch) {
-		await this.rest.request(`${this.base}/branches/${encodeURIComponent(branch)}`, { method: "DELETE" });
+		await this.client.branches.destroy(this.opts.projectId, branch);
 	}
 	async resetBranch(input) {
-		await this.rest.request(`${this.base}/branches/${encodeURIComponent(input.branch)}/restore`, {
-			method: "POST",
-			body: { source_branch_id: input.from }
-		});
+		await this.client.branches.restore(this.opts.projectId, input.branch, input.from);
 	}
 	async enableExtension(input) {
 		const db = await this.firstDatabase(input.branch);
-		await this.rest.request(`${this.base}/branches/${encodeURIComponent(input.branch)}/databases/${encodeURIComponent(db.name)}/run_sql`, {
-			method: "POST",
-			body: { query: `CREATE EXTENSION IF NOT EXISTS "${input.extension}"` }
-		});
+		await this.client.databases.runSql(this.opts.projectId, input.branch, db.name, `CREATE EXTENSION IF NOT EXISTS "${input.extension}"`);
 	}
 	/**
 	* The first database on a branch — the "default" for connection-string
@@ -98,7 +75,8 @@ var NeonStorage = class {
 	* means it was created without an endpoint and needs initialization).
 	*/
 	async firstDatabase(branchId) {
-		const db = (await this.rest.request(`${this.base}/branches/${encodeURIComponent(branchId)}/databases`)).databases[0];
+		const { databases } = await this.client.databases.list(this.opts.projectId, branchId);
+		const db = databases[0];
 		if (!db) throw new ProviderApiError(`Neon branch ${branchId} has no databases — initialize the branch first`, 404, void 0);
 		return db;
 	}
@@ -112,60 +90,6 @@ function mapBranch(raw) {
 	};
 }
 //#endregion
-//#region src/rest.ts
-/**
-* Thin REST wrapper around console.neon.tech/api/v2.
-*
-* Same pattern as the GitHub + Vercel REST clients — bearer auth,
-* JSON-only bodies, transport-failure wrapping with status: 0 so the
-* orchestrator's soft-skip path sees a clear "Neon GET /path failed"
-* message instead of a generic `TypeError: fetch failed`.
-*/
-var NeonRestClient = class {
-	token;
-	fetchImpl;
-	baseUrl;
-	constructor(opts) {
-		this.token = opts.token;
-		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-		let url = opts.baseUrl ?? "https://console.neon.tech/api/v2";
-		while (url.endsWith("/")) url = url.slice(0, -1);
-		this.baseUrl = url;
-	}
-	async request(path, opts = {}) {
-		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
-		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
-		const fullUrl = url.toString();
-		const headers = {
-			authorization: `Bearer ${this.token}`,
-			accept: "application/json"
-		};
-		const init = {
-			method: opts.method ?? "GET",
-			headers
-		};
-		if (opts.body !== void 0) {
-			headers["content-type"] = "application/json";
-			init.body = JSON.stringify(opts.body);
-		}
-		let res;
-		try {
-			res = await this.fetchImpl(fullUrl, init);
-		} catch (err) {
-			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
-			throw new ProviderApiError(`Neon ${init.method} ${path} failed: ${detail}`, 0, void 0);
-		}
-		if (!res.ok) {
-			const body = await res.text().catch(() => "");
-			throw new ProviderApiError(`Neon ${init.method} ${path} → ${res.status}`, res.status, body);
-		}
-		if (res.status === 204) return void 0;
-		const text = await res.text();
-		if (!text) return void 0;
-		return JSON.parse(text);
-	}
-};
-//#endregion
 //#region src/verify-token.ts
 /**
 * `verifyToken` — plugin-level export used by `holocron auth set` +
@@ -174,12 +98,13 @@ var NeonRestClient = class {
 * shape.
 */
 async function verifyToken(token, opts = {}) {
-	const restOpts = { token };
-	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
-	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
-	const rest = new NeonRestClient(restOpts);
+	const client = createNeonClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
 	try {
-		const me = await rest.request("/users/me");
+		const me = await client.users.me();
 		return {
 			ok: true,
 			subject: `user @ ${me?.email ?? me?.login ?? me?.name ?? me?.id ?? "unknown"}`
@@ -195,16 +120,17 @@ async function verifyToken(token, opts = {}) {
 //#region src/index.ts
 function createContext(options) {
 	if (!options.projectId) throw new Error("@theholocron/holocron-plugin-neon requires `projectId` in options");
-	const restOpts = { token: resolveToken(options) };
-	if (options.baseUrl !== void 0) restOpts.baseUrl = options.baseUrl;
-	if (options.fetch !== void 0) restOpts.fetch = options.fetch;
 	return {
 		options,
-		rest: new NeonRestClient(restOpts)
+		client: createNeonClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
 	};
 }
 function storage(ctx) {
-	return new NeonStorage(ctx.rest, { projectId: ctx.options.projectId });
+	return new NeonStorage(ctx.client, { projectId: ctx.options.projectId });
 }
 function createPlugin(options) {
 	const ctx = createContext(options);
@@ -221,4 +147,4 @@ function createPlugin(options) {
 */
 const AUTH_HINT = "generate a Neon API key at https://console.neon.tech/app/settings/api-keys, then run: holocron auth set neon <KEY>";
 //#endregion
-export { AUTH_HINT, AuthError, NeonRestClient, NeonStorage, createContext, createPlugin, resolveToken, storage, verifyToken };
+export { AUTH_HINT, AuthError, NeonStorage, createContext, createNeonClient, createPlugin, resolveToken, storage, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-neon",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0",
   "description": "Holocron plugin for Neon. Implements the storage capability against Neon's REST API — branch ops, connection strings, extensions.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-neon#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,19 +21,31 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.9"
+    "@theholocron/neon-client": "^1.1.0",
+    "@theholocron/cli": "2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@theholocron/neon-client": {
+      "optional": false
+    }
   },
   "devDependencies": {
-    "@theholocron/tsconfig": "^4.1.0",
-    "@tsconfig/node-lts": "^24.0.0",
-    "@vitest/coverage-v8": "^3.2.6",
-    "eslint": "^9.36.0",
-    "globals": "^16.5.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.6",
+    "@theholocron/eslint-config": "^7.3.0",
+    "@theholocron/neon-client": "^1.1.0",
+    "@theholocron/tsconfig": "^7.3.0",
+    "@theholocron/tsdown-config": "^7.3.0",
+    "@theholocron/vitest-config": "^7.3.0",
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "eslint": "^10.7.0",
+    "eslint-plugin-n": "^18.2.2",
+    "globals": "^17.7.0",
     "tsdown": "^0.22.3",
     "tsx": "^4.22.4",
-    "@theholocron/cli": "2.0.0-alpha.9"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@theholocron/cli": "2.0.0"
   },
   "publishConfig": {
     "access": "public"