@theholocron/http-client 1.58.0-alpha.1 → 1.58.0-alpha.11

package/README.md

@@ -1,6 +1,8 @@
+<!-- alex disable fires -->
+
 # @theholocron/http-client
 
-Shared HTTP primitives for theholocron tooling — REST client factory, token resolver, and base error types. Used internally by `@theholocron/cli` and all plugin packages; publish your own clients on top of it.
+Shared HTTP primitives for theholocron tooling — REST client factory, retry events, and base error types. Used internally by `@theholocron/cli` and all plugin packages; publish your own clients on top of it.
 
 ## Installation
 
@@ -89,38 +91,6 @@ stop();
 
 It is per process, not per client, so nothing has to be handed to each client. It needs one copy of this package in the process (a workspace pins it); with two, the other copy's retries go unseen. A listener that throws is ignored.
 
-### `createResolveToken(config)`
-
-Factory for the standard token resolution used by all holocron plugins. Resolution order:
-
-1. `cliToken` — value from `--token` CLI flag
-2. `HOLOCRON_*` env var (e.g. `HOLOCRON_EXAMPLE_TOKEN`)
-3. Vendor env var (e.g. `EXAMPLE_TOKEN`)
-4. Keyring `<service>.<org>` — only when an org is active (see `ResolveTokenInput.org`)
-5. Keyring `<service>` — unnamespaced fallback; backward-compatible default
-
-```ts
-import { createResolveToken, AuthError } from "@theholocron/http-client";
-
-export const resolveToken = createResolveToken({
-  envName: "HOLOCRON_EXAMPLE_TOKEN",
-  vendorEnvName: "EXAMPLE_TOKEN",
-  keyringService: "example",
-  errorMessage:
-    "no Example token found. Pass --token <TOKEN>, set HOLOCRON_EXAMPLE_TOKEN / EXAMPLE_TOKEN, " +
-    "or run: holocron auth set example <TOKEN>",
-});
-```
-
-The returned `resolveToken(input?)` function accepts a `ResolveTokenInput`:
-
-| Field      | Type                                   | Description                                                                                                                                        |
-| ---------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cliToken` | `string`                               | Token from `--token` CLI flag; takes highest priority                                                                                              |
-| `env`      | `NodeJS.ProcessEnv`                    | Env vars to consult; defaults to `process.env`                                                                                                     |
-| `keyring`  | `(provider: string) => string \| null` | Keyring lookup fn; defaults to the keyring injected by `@theholocron/cli`                                                                          |
-| `org`      | `string`                               | Active org name; tries `keyring("<service>.<org>")` before the unnamespaced fallback. Also auto-read from `env["HOLOCRON_ORG"]` when not provided. |
-
 ### `ProviderApiError`
 
 Thrown by `createRestClient` on non-2xx responses and transport failures. Carries `status` (HTTP code, `0` for transport failures) and `details` (raw response text).
@@ -137,10 +107,6 @@ try {
 }
 ```
 
-### `AuthError`
-
-Thrown by `createResolveToken` when no token can be found in any of the four resolution steps.
-
 ## License
 
 MIT © [Newton Koumantzelis](https://github.com/iamnewton)

package/dist/index.d.mts

@@ -1,55 +1,23 @@
 import { ErrorSink, Logger } from "@theholocron/observability/core";
-export 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;
-  /** Active org name — drives namespaced keyring lookup (`<service>.<org>`). */
-  org?: string;
-}
-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
- * });
- * ```
- */
-export declare function createResolveToken(config: ResolveTokenConfig): (input?: ResolveTokenInput) => string;
 /**
  * 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.
  */
 export declare class ProviderApiError extends Error {
+  /** The HTTP status code; `0` for a transport failure that got no response. */
   readonly status: number | undefined;
+  /** The raw response body as a string (not parsed JSON); `undefined` when there is none. */
   readonly details?: unknown | undefined;
+  /** The error name, `ProviderApiError`. */
   name: string;
-  constructor(message: string, status: number | undefined, details?: unknown | undefined);
+  constructor(message: string,
+  /** The HTTP status code; `0` for a transport failure that got no response. */
+  status: number | undefined,
+  /** The raw response body as a string (not parsed JSON); `undefined` when there is none. */
+  details?: unknown | undefined);
 }
+/** Settings for `createRestClient`. */
 interface RestClientConfig {
   /** Default base URL (e.g. "https://api.github.com"). */
   baseUrl: string;
@@ -104,24 +72,39 @@ interface RestClientConfig {
    */
   retryStatuses?: readonly number[];
 }
+/** Options for one `RestClient.request` call. */
 interface RequestOptions {
+  /** The HTTP method. Defaults to `"GET"`. */
   method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  /** The request body; sent as JSON with a `content-type` header. Left out or `undefined`, no body is sent. */
   body?: unknown;
   /** Per-request query params, merged after `defaultQuery`. */
   query?: Record<string, string>;
   /** Return `undefined` without parsing even on a 200 response. */
   expectNoContent?: boolean;
+  /**
+   * Called with the response headers of a successful (2xx) response, before the body is read. For a value the
+   * vendor returns in a header rather than the body (GitHub's token expiry). A failed response throws as before
+   * and does not call it.
+   */
+  onResponse?: (headers: Headers) => void;
 }
+/** A JSON REST client bound to one vendor's base URL and credentials. */
 interface RestClient {
+  /** The base URL with any trailing slashes removed. */
   readonly baseUrl: string;
+  /** Sends a request to `path` and resolves with the parsed JSON body, or `undefined` for an empty or 204 response; rejects with a `ProviderApiError`. */
   request<T>(path: string, opts?: RequestOptions): Promise<T>;
 }
+/** Creates a `RestClient` that sends the configured auth header and retries safe transport failures. */
 export declare function createRestClient(config: RestClientConfig): RestClient;
 /** A request about to be sent again after a transport failure, or an HTTP status the client was told to retry. */
 interface RetryEvent {
   /** The client's `vendor` label, e.g. `GitHub`. */
   vendor?: string;
+  /** The HTTP method of the request, such as `GET`. */
   method: string;
+  /** The request path, relative to the client's base URL. */
   path: string;
   /**
    * What went wrong (`ECONNRESET`, `UND_ERR_CONNECT_TIMEOUT`, or `HTTP 503` for a retried status); a failure with no
@@ -144,4 +127,4 @@ interface RetryEvent {
  * being one copy of this package, which the workspace already requires; with two, retries by the other copy go unseen.
  */
 export declare function onRetry(listener: (event: RetryEvent) => void): () => void;
-export type { RequestOptions, ResolveTokenConfig, ResolveTokenInput, RestClient, RestClientConfig, RetryEvent };
+export type { RequestOptions, RestClient, RestClientConfig, RetryEvent };

package/dist/index.mjs

@@ -1,34 +1,4 @@
-import { createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
 import { NoopErrorSink, NoopLogger } from "@theholocron/observability/core";
-// 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 = createEnvLookup(input.env ?? process.env);
-		const keyring = input.keyring ?? defaultKeyring;
-		const org = input.org ?? env.get("HOLOCRON_ORG");
-		const token = input.cliToken || firstEnv(env, [config.envName, config.vendorEnvName]) || (org ? keyring(`${config.keyringService}.${org}`) : null) || keyring(config.keyringService);
-		if (!token) throw new AuthError(config.errorMessage);
-		return token;
-	};
-}
 // src/errors.ts
 /**
 * Surfaced from every capability call that hits a vendor API. Wraps
@@ -38,6 +8,7 @@ function createResolveToken(config) {
 var ProviderApiError = class extends Error {
 	status;
 	details;
+	/** The error name, `ProviderApiError`. */
 	name = "ProviderApiError";
 	constructor(message, status, details) {
 		super(message);
@@ -123,6 +94,7 @@ function retriedNote(res, attempt) {
 	const header = REQUEST_ID_HEADERS.find((name) => res.headers.has(name));
 	return ` (after ${attempt + 1} attempts${header ? `; ${header}: ${res.headers.get(header)}` : ""})`;
 }
+/** Creates a `RestClient` that sends the configured auth header and retries safe transport failures. */
 function createRestClient(config) {
 	const fetchImpl = config.fetch ?? globalThis.fetch;
 	const vendor = config.vendor ?? "";
@@ -213,6 +185,7 @@ function createRestClient(config) {
 				path,
 				status: res.status
 			}, "response");
+			opts.onResponse?.(res.headers);
 			if (opts.expectNoContent || res.status === 204) return void 0;
 			const text = await res.text();
 			if (!text) return void 0;
@@ -220,4 +193,4 @@ function createRestClient(config) {
 		}
 	};
 }
-export { AuthError, ProviderApiError, createResolveToken, createRestClient, onRetry };
+export { ProviderApiError, createRestClient, onRetry };

package/dist/testing.d.mts

@@ -1,13 +1,23 @@
+/** One request a stubbed `fetch` received. */
 export interface FetchCall {
+  /** The address that was requested. */
   url: string;
+  /** The HTTP method, upper-cased; `GET` when none was given. */
   method: string;
+  /** The request headers, as given. */
   headers: Record<string, string>;
+  /** The body: parsed when it was a JSON string, as given otherwise, and `null` when there was none. */
   body: unknown;
 }
+/**
+ * A `fetch` that answers each call with the next of `responses` (a 200 with an empty body once they run out) and
+ * records every call it receives.
+ */
 export declare function stubFetch(responses: Array<{
   status?: number;
   body?: unknown;
   text?: string;
+  headers?: Record<string, string>;
 }>): {
   fetch: typeof fetch;
   calls: FetchCall[];

package/dist/testing.mjs

@@ -3,6 +3,10 @@ import { vi } from "vitest";
 /* v8 ignore file -- exercised by other packages' test suites, not this package's own; a source-level
 * directive survives regardless of which vitest config resolves (local vs. shared), unlike a
 * config-file `coverage.exclude` entry. */
+/**
+* A `fetch` that answers each call with the next of `responses` (a 200 with an empty body once they run out) and
+* records every call it receives.
+*/
 function stubFetch(responses) {
 	const calls = [];
 	let i = 0;
@@ -21,9 +25,15 @@ function stubFetch(responses) {
 				body: {}
 			};
 			const status = next.status ?? 200;
-			if (status === 204) return new Response(null, { status });
+			if (status === 204) return new Response(null, {
+				status,
+				headers: next.headers
+			});
 			const text = next.text ?? JSON.stringify(next.body ?? {});
-			return new Response(text, { status });
+			return new Response(text, {
+				status,
+				headers: next.headers
+			});
 		}),
 		calls
 	};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theholocron/http-client",
-  "version": "1.58.0-alpha.1",
-  "description": "Shared HTTP primitives for theholocron — REST client factory, auth resolver, and error types",
+  "version": "1.58.0-alpha.11",
+  "description": "Shared HTTP primitives for theholocron — REST client factory, retry events, and error types",
   "keywords": [
     "typescript",
     "http",
@@ -36,23 +36,22 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/observability": "^0.6.1-alpha.1",
-    "@theholocron/env-utils": "^1.16.1-alpha.1"
+    "@theholocron/observability": "^0.7.0-alpha.1"
   },
   "devDependencies": {
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
-    "@vitest/eslint-plugin": "^1.6.27",
-    "eslint": "^10.8.1",
-    "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.11.0",
-    "tsdown": "^0.23.3",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.4",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3"
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/tsconfig": "^8.9.0-alpha.8"
   },
   "peerDependencies": {
     "vitest": ">=4.0.0"
@@ -69,10 +68,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown && node ../scripts/check-bundle-size.mjs",
-    "sourceQuality.staticAnalysis": "eslint .",
+    "build": "tsdown && node ../scripts/check-bundle-size.mjs",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "tsc --noEmit",
-    "verification.unitTests": "vitest run"
+    "typecheck": "tsc --noEmit"
   }
 }