@theholocron/http-client 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,94 @@
+//#region src/errors.d.ts
+/**
+ * Surfaced from every capability call that hits a vendor API. Wraps
+ * the underlying error with `status` (HTTP) and `details` so
+ * orchestrators can soft-skip rather than abort.
+ */
+declare class ProviderApiError extends Error {
+  readonly status: number | undefined;
+  readonly details?: unknown | undefined;
+  name: string;
+  constructor(message: string, status: number | undefined, details?: unknown | undefined);
+}
+//#endregion
+//#region src/rest-client.d.ts
+interface RestClientConfig {
+  /** Default base URL (e.g. "https://api.github.com"). */
+  baseUrl: string;
+  /** Auth token. */
+  token: string;
+  /**
+   * How the token is sent.
+   * - `"bearer"` (default): `Authorization: Bearer <token>`
+   * - `"apikey"`: uses `apiKeyHeader` (e.g. `x-api-key`)
+   */
+  tokenScheme?: "bearer" | "apikey";
+  /** Header name when `tokenScheme` is `"apikey"`. Defaults to `"x-api-key"`. */
+  apiKeyHeader?: string;
+  /**
+   * Static headers merged into every request. Applied after the auth header
+   * so they can override defaults (e.g. GitHub's `accept` override).
+   */
+  extraHeaders?: Record<string, string>;
+  /** Query params appended to every request URL (e.g. Vercel's `teamId`). */
+  defaultQuery?: Record<string, string>;
+  /** Vendor label used in error messages (e.g. `"GitHub"`). */
+  vendor?: string;
+  /** Override `fetch` for tests. Defaults to `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+interface RequestOptions {
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  body?: unknown;
+  /** Per-request query params, merged after `defaultQuery`. */
+  query?: Record<string, string>;
+  /** Return `undefined` without parsing even on a 200 response. */
+  expectNoContent?: boolean;
+}
+interface RestClient {
+  readonly baseUrl: string;
+  request<T>(path: string, opts?: RequestOptions): Promise<T>;
+}
+declare function createRestClient(config: RestClientConfig): RestClient;
+//#endregion
+//#region src/auth-resolver.d.ts
+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. */
+  keyring?: (provider: string) => string | null;
+}
+interface ResolveTokenConfig {
+  /** HOLOCRON_* env var (e.g. `"HOLOCRON_GH_TOKEN"`). */
+  envName: string;
+  /** Vendor's own env var (e.g. `"GITHUB_TOKEN"`). */
+  vendorEnvName: string;
+  /** Keyring service key (e.g. `"github"`). */
+  keyringService: string;
+  /** Full error message shown when no token is found. */
+  errorMessage: string;
+  /** Keyring backend — injected by the CLI layer. Defaults to no-op. */
+  getKeyringToken?: (provider: string) => string | null;
+}
+/**
+ * Returns a `resolveToken(input?)` function wired to the given env vars
+ * and keyring service. Plugins call this once at module level:
+ *
+ * ```ts
+ * export const resolveToken = createResolveToken({
+ *   envName: "HOLOCRON_GITHUB_TOKEN",
+ *   vendorEnvName: "GITHUB_TOKEN",
+ *   keyringService: "github",
+ *   errorMessage: "no GitHub token found ...",
+ *   getKeyringToken,          // injected from @theholocron/cli
+ * });
+ * ```
+ */
+declare function createResolveToken(config: ResolveTokenConfig): (input?: ResolveTokenInput) => string;
+//#endregion
+export { AuthError, ProviderApiError, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, type RestClient, type RestClientConfig, createResolveToken, createRestClient };

package/dist/index.mjs

@@ -0,0 +1,91 @@
+//#region src/errors.ts
+/**
+* Surfaced from every capability call that hits a vendor API. Wraps
+* the underlying error with `status` (HTTP) and `details` so
+* orchestrators can soft-skip rather than abort.
+*/
+var ProviderApiError = class extends Error {
+	status;
+	details;
+	name = "ProviderApiError";
+	constructor(message, status, details) {
+		super(message);
+		this.status = status;
+		this.details = details;
+	}
+};
+//#endregion
+//#region src/rest-client.ts
+function createRestClient(config) {
+	const fetchImpl = config.fetch ?? globalThis.fetch;
+	const vendor = config.vendor ?? "";
+	let baseUrl = config.baseUrl;
+	while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
+	const staticHeaders = { accept: "application/json" };
+	if (config.tokenScheme === "apikey") staticHeaders[config.apiKeyHeader ?? "x-api-key"] = config.token;
+	else staticHeaders["authorization"] = `Bearer ${config.token}`;
+	Object.assign(staticHeaders, config.extraHeaders);
+	return {
+		baseUrl,
+		async request(path, opts = {}) {
+			const url = new URL(`${baseUrl}${path.startsWith("/") ? path : "/" + path}`);
+			for (const [k, v] of Object.entries(config.defaultQuery ?? {})) url.searchParams.set(k, v);
+			for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
+			const headers = { ...staticHeaders };
+			const init = {
+				method: opts.method ?? "GET",
+				headers
+			};
+			if (opts.body !== void 0) {
+				headers["content-type"] = "application/json";
+				init.body = JSON.stringify(opts.body);
+			}
+			const tag = vendor ? `${vendor} ${init.method} ${path}` : `${init.method} ${path}`;
+			let res;
+			try {
+				res = await fetchImpl(url.toString(), init);
+			} catch (err) {
+				throw new ProviderApiError(`${tag} failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`, 0, void 0);
+			}
+			if (!res.ok) {
+				const body = await res.text().catch(() => "");
+				throw new ProviderApiError(`${tag} → ${res.status}`, res.status, body);
+			}
+			if (opts.expectNoContent || res.status === 204) return void 0;
+			const text = await res.text();
+			if (!text) return void 0;
+			return JSON.parse(text);
+		}
+	};
+}
+//#endregion
+//#region src/auth-resolver.ts
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+/**
+* Returns a `resolveToken(input?)` function wired to the given env vars
+* and keyring service. Plugins call this once at module level:
+*
+* ```ts
+* export const resolveToken = createResolveToken({
+*   envName: "HOLOCRON_GITHUB_TOKEN",
+*   vendorEnvName: "GITHUB_TOKEN",
+*   keyringService: "github",
+*   errorMessage: "no GitHub token found ...",
+*   getKeyringToken,          // injected from @theholocron/cli
+* });
+* ```
+*/
+function createResolveToken(config) {
+	const defaultKeyring = config.getKeyringToken ?? (() => null);
+	return function resolveToken(input = {}) {
+		const env = input.env ?? process.env;
+		const keyring = input.keyring ?? defaultKeyring;
+		const token = input.cliToken || env[config.envName] || env[config.vendorEnvName] || keyring(config.keyringService);
+		if (!token) throw new AuthError(config.errorMessage);
+		return token;
+	};
+}
+//#endregion
+export { AuthError, ProviderApiError, createResolveToken, createRestClient };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@theholocron/http-client",
+  "version": "0.1.0",
+  "description": "Shared HTTP primitives for theholocron \u2014 REST client factory, auth resolver, and error types",
+  "homepage": "https://github.com/theholocron/clients/tree/main/packages/http-client#readme",
+  "bugs": "https://github.com/theholocron/clients/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/clients.git",
+    "directory": "packages/http-client"
+  },
+  "license": "GPL-3.0",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@theholocron/eslint-config": "catalog:",
+    "@theholocron/tsconfig": "catalog:",
+    "@theholocron/tsdown-config": "catalog:",
+    "@theholocron/vitest-config": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "@vitest/eslint-plugin": "catalog:",
+    "eslint": "catalog:",
+    "eslint-plugin-n": "catalog:",
+    "globals": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "releases": "https://github.com/theholocron/clients/releases",
+  "wiki": "https://github.com/theholocron/clients/wiki"
+}