@theholocron/http-client 1.58.0-alpha.3 → 1.58.0-alpha.4

package/dist/index.d.mts

@@ -1,7 +1,10 @@
 import { ErrorSink, Logger } from "@theholocron/observability/core";
+/** Thrown by a token resolver when no token was found in any source. */
 export declare class AuthError extends Error {
+  /** The error name, `AuthError`. */
   name: string;
 }
+/** Where `resolveToken` looks for a token. */
 interface ResolveTokenInput {
   /** From `--token` CLI flag. */
   cliToken?: string;
@@ -12,6 +15,7 @@ interface ResolveTokenInput {
   /** Active org name — drives namespaced keyring lookup (`<service>.<org>`). */
   org?: string;
 }
+/** How `createResolveToken` finds a vendor's token. */
 interface ResolveTokenConfig {
   /** HOLOCRON_* env var (e.g. `"HOLOCRON_GH_TOKEN"`). */
   envName: string;
@@ -26,8 +30,15 @@ interface ResolveTokenConfig {
 }
 /**
  * Returns a `resolveToken(input?)` function wired to the given env vars
- * and keyring service. Plugins call this once at module level:
+ * and keyring service. Plugins call this once at module level.
  *
+ * @remarks
+ * The resolver tries, in order: the `cliToken` input (the `--token` flag), the
+ * `HOLOCRON_*` env var, the vendor's own env var, the keyring entry
+ * `<service>.<org>` (only when an org is known), then the keyring entry
+ * `<service>`. It throws {@link AuthError} when none has a token.
+ *
+ * @example
  * ```ts
  * export const resolveToken = createResolveToken({
  *   envName: "HOLOCRON_GITHUB_TOKEN",
@@ -45,11 +56,19 @@ export declare function createResolveToken(config: ResolveTokenConfig): (input?:
  * 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,8 +123,11 @@ 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>;
@@ -118,16 +140,22 @@ interface RequestOptions {
    */
   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

package/dist/index.mjs

@@ -1,13 +1,22 @@
 import { createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
 import { NoopErrorSink, NoopLogger } from "@theholocron/observability/core";
 // src/auth-resolver.ts
+/** Thrown by a token resolver when no token was found in any source. */
 var AuthError = class extends Error {
+	/** The error name, `AuthError`. */
 	name = "AuthError";
 };
 /**
 * Returns a `resolveToken(input?)` function wired to the given env vars
-* and keyring service. Plugins call this once at module level:
+* and keyring service. Plugins call this once at module level.
 *
+* @remarks
+* The resolver tries, in order: the `cliToken` input (the `--token` flag), the
+* `HOLOCRON_*` env var, the vendor's own env var, the keyring entry
+* `<service>.<org>` (only when an org is known), then the keyring entry
+* `<service>`. It throws {@link AuthError} when none has a token.
+*
+* @example
 * ```ts
 * export const resolveToken = createResolveToken({
 *   envName: "HOLOCRON_GITHUB_TOKEN",
@@ -38,6 +47,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 +133,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 ?? "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/http-client",
-  "version": "1.58.0-alpha.3",
+  "version": "1.58.0-alpha.4",
   "description": "Shared HTTP primitives for theholocron — REST client factory, auth resolver, and error types",
   "keywords": [
     "typescript",
@@ -36,7 +36,7 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/env-utils": "^1.16.1-alpha.1",
+    "@theholocron/env-utils": "^1.16.1-alpha.3",
     "@theholocron/observability": "^0.6.1-alpha.1"
   },
   "devDependencies": {
@@ -49,10 +49,10 @@
     "tsdown": "^0.23.3",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3"
+    "@theholocron/tsconfig": "^8.9.0-alpha.5",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.5",
+    "@theholocron/eslint-config": "^8.9.0-alpha.5",
+    "@theholocron/vitest-config": "^8.9.0-alpha.5"
   },
   "peerDependencies": {
     "vitest": ">=4.0.0"