vern-llm 1.4.0 → 1.6.0

package/README.md

@@ -20,14 +20,16 @@
   <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
 </p>
 
-Production-ready resilience for LLM calls: retries, timeouts, caching, and circuit breaking behind one typed interface, with adapters for OpenAI-compatible APIs (OpenAI, Groq, and more), Anthropic, Gemini, and Bedrock.
+<p align="center">Production-ready resilience for LLM calls</p>
+
+Retries, timeouts, caching, and circuit breaking behind one typed interface, with adapters for OpenAI-compatible APIs (OpenAI, Groq, and more), Anthropic, Gemini, and Bedrock.
 
 **Full documentation: [vernllm.vercel.app](https://vernllm.vercel.app)** — installation, structured output, caching, circuit breaker, every adapter, and the complete API reference all live there and are kept up to date. This README is a quick pitch, not the manual.
 
 ## Install
 
 ```bash
-pnpm add vern-llm openai
+pnpm add vern-llm
 ```
 
 ## Quick start
@@ -62,19 +64,6 @@ const result = await llm.call({
 
 See the [docs](https://vernllm.vercel.app) for adapter setup, caching, the circuit breaker, and structured output in depth.
 
-## Development
-
-```bash
-pnpm install
-pnpm run build            # tsdown → dist (ESM + CJS + types)
-pnpm run typecheck        # tsc --noEmit on src, since tsdown doesn't fully type-check
-pnpm run test             # vitest run
-pnpm run test:coverage    # vitest run --coverage (v8 provider)
-pnpm run changeset        # record a change for the next release
-```
-
-Tests live in `tests/`, mirroring `src/`, and cover retry/backoff/timeout/abort/schema/model-override/usage behavior, the circuit breaker (unit + integration), caching, the injectable logger, and every provider adapter's request/response translation against a fake client — no real API calls anywhere in the suite.
-
 ## License
 
 [MIT](https://github.com/LakBud/vernLLM/blob/main/LICENSE.md) © LakBud

package/dist/index.cjs

@@ -26,11 +26,13 @@ const crypto = __toESM(require("crypto"));
 
 //#region src/types/errors.ts
 var LLMError = class extends Error {
-	constructor(message, type, status, issues) {
+	constructor(message, type, status, issues, cause, retryAfterMs) {
 		super(message);
 		this.type = type;
 		this.status = status;
 		this.issues = issues;
+		this.cause = cause;
+		this.retryAfterMs = retryAfterMs;
 		this.name = "LLMError";
 	}
 };
@@ -126,6 +128,32 @@ function extractStatus(err) {
 	if (typeof error.statusCode === "number") return error.statusCode;
 	return void 0;
 }
+function formatSafely(value) {
+	try {
+		return JSON.stringify(value, null, 2) ?? String(value);
+	} catch {
+		try {
+			return String(value);
+		} catch {
+			return "[unprintable error]";
+		}
+	}
+}
+/**
+* Looks inside an unknown thrown value and pulls out a human-readable
+* description of it. Checks the `error` field first (the provider's raw
+* rejection body, JSON-stringified if possible) then falls back to the
+* message` field. Always returns a safe string, even when the thrown value
+* has hostile properties or cannot be serialized normally.
+*/
+function describeError(err) {
+	if (err && typeof err === "object") try {
+		const error = err;
+		if (error.error !== void 0) return formatSafely(error.error);
+		if (typeof error.message === "string") return error.message;
+	} catch {}
+	return formatSafely(err);
+}
 /**
 * Runs an async function and cancels it if it takes longer than the given
 * timeout. Creates an internal abort controller that fires after the
@@ -382,13 +410,16 @@ var VernLLM = class {
 		this.breaker?.assertClosed();
 		if (params.signal?.aborted) throw new LLMError("LLM request aborted", "aborted");
 		const requestId = params.requestId ?? (0, crypto.randomUUID)();
-		try {
-			const result = await this.retryWithBackoff(() => this.executeCall(params, requestId), requestId, params.signal);
-			return result;
-		} catch (error) {
-			this.breaker?.recordFailure();
-			throw this.normalizeError(error, params.signal);
-		}
+		return this.withReservedUsage(params, false, async () => {
+			try {
+				return await this.retryWithBackoff(() => this.executeCall(params, requestId), requestId, params.signal);
+			} catch (error) {
+				const normalized = this.normalizeError(error, params.signal);
+				if (normalized.type !== "validation" && normalized.type !== "parse" && normalized.type !== "aborted") this.breaker?.recordFailure();
+				this.logger.debug(`[vern:${requestId}] error:\n${describeError(error)}`);
+				throw normalized;
+			}
+		}, params.signal);
 	}
 	/**
 	* Runs `fn`, retrying with backoff according to `shouldRetry` policy
@@ -416,8 +447,9 @@ var VernLLM = class {
 		if (signal?.aborted) return new LLMError("LLM request aborted", "aborted");
 		if (error instanceof LLMError) return error;
 		const status = extractStatus(error);
-		if (status !== void 0) return new LLMError("LLM request failed", "api", status);
-		return new LLMError("LLM request failed", "unknown");
+		const retryAfterMs = extractRetryAfterMs(error);
+		if (status !== void 0) return new LLMError("LLM request failed", "api", status, void 0, error, retryAfterMs);
+		return new LLMError("LLM request failed", "unknown", void 0, void 0, error, retryAfterMs);
 	}
 	/**
 	* Performs a single attempt: builds the request, dispatches it with a
@@ -432,9 +464,13 @@ var VernLLM = class {
 		if (!content) throw new LLMError("Empty LLM response", "api");
 		this.logger.debug(`[vern:${requestId}] output:\n${content.slice(0, 800)}`);
 		this.recordUsage(response, requestId, model);
+		if (!useJson) {
+			this.breaker?.recordSuccess();
+			return content;
+		}
+		const result = this.parseAndValidate(content, params.schema);
 		this.breaker?.recordSuccess();
-		if (!useJson) return content;
-		return this.parseAndValidate(content, params.schema);
+		return result;
 	}
 	/**
 	* Anthropic and Gemini both require strict user/assistant alternation
@@ -462,6 +498,7 @@ var VernLLM = class {
 	buildRequestPayload(params) {
 		const { systemPrompt, userContent, history = [], temperature = .2, jsonMode = true, maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema } = params;
 		const useJson = jsonMode || Boolean(jsonSchema);
+		if (params.schema && !useJson) throw new LLMError("schema was provided but jsonMode: false disables JSON parsing, so nothing would validate it. Remove jsonMode: false, set jsonSchema, or remove schema.", "validation");
 		const responseFormat = this.buildResponseFormat(jsonSchema, useJson);
 		this.validateHistory(history);
 		const request = {
@@ -514,16 +551,24 @@ var VernLLM = class {
 	* Reports token usage to the caller supplied onUsage callback, when
 	* both a callback was configured and the provider actually returned
 	* usage data on this response. A no op otherwise.
+	*
+	* A throwing onUsage callback is logged and swallowed rather than
+	* propagated, so a broken billing/metrics hook can't fail or retrigger
+	* retries on an otherwise-successful call.
 	*/
 	recordUsage(response, requestId, model) {
 		if (!response.usage || !this.onUsage) return;
-		this.onUsage({
-			promptTokens: response.usage.prompt_tokens ?? 0,
-			completionTokens: response.usage.completion_tokens ?? 0,
-			totalTokens: response.usage.total_tokens ?? 0,
-			requestId,
-			model
-		});
+		try {
+			this.onUsage({
+				promptTokens: response.usage.prompt_tokens ?? 0,
+				completionTokens: response.usage.completion_tokens ?? 0,
+				totalTokens: response.usage.total_tokens ?? 0,
+				requestId,
+				model
+			});
+		} catch (error) {
+			this.logger.error("[VernLLM] onUsage failed", { message: error instanceof Error ? error.message : "unknown" });
+		}
 	}
 	/**
 	* Parses the raw response content as JSON and, when a schema is
@@ -597,19 +642,12 @@ var VernLLM = class {
 		if (cached.hit) return cached.value;
 		const existing = this.inFlight.get(params.cacheKey);
 		const coalesced = existing !== void 0;
-		const resultPromise = existing ?? this.registerTrigger(params, coalesced);
-		if (coalesced) return this.withRefundOnFailure(params, coalesced, async () => {
-			await params.reserveUsage?.({ coalesced });
-			return resultPromise;
-		});
-		return this.withRefundOnFailure(params, coalesced, () => resultPromise);
+		if (coalesced) return this.withReservedUsage(params, coalesced, () => existing, params.signal);
+		return this.registerTrigger(params, coalesced);
 	}
 	/** Starts the shared fn() call for a cache miss, reserving usage first, and registers it in the in-flight map until it settles */
 	registerTrigger(params, coalesced) {
-		const resultPromise = (async () => {
-			await params.reserveUsage?.({ coalesced });
-			return this.runAndCache(params);
-		})();
+		const resultPromise = this.withReservedUsage(params, coalesced, () => this.runAndCache(params), params.signal);
 		this.inFlight.set(params.cacheKey, resultPromise);
 		resultPromise.catch(() => {}).finally(() => {
 			this.inFlight.delete(params.cacheKey);
@@ -626,13 +664,48 @@ var VernLLM = class {
 		}
 		return result;
 	}
-	/** Awaits `run`, calling this caller's own refundUsage (tagged with whether it was coalesced) if it rejects, then rethrows the original error */
-	async withRefundOnFailure(params, coalesced, run) {
+	/**
+	* Runs `getResult` after reserving usage, if a `reserveUsage` hook was
+	* provided. `refundUsage` fires only if a reservation was actually made,
+	* i.e. `reserveUsage` was provided and it resolved successfully. If
+	* `reserveUsage` is omitted entirely, or if it throws, there is nothing to
+	* refund, so `refundUsage` is not invoked in either case.
+	*
+	* Shared by `cachedCall()`/`registerTrigger()` and `call()`, so it only
+	* depends on the usage hooks rather than LLM request concerns.
+	*/
+	async withReservedUsage(params, coalesced, getResult, signal) {
+		let reserved = false;
 		try {
-			return await run();
+			if (params.reserveUsage) {
+				await params.reserveUsage({
+					coalesced,
+					signal
+				});
+				reserved = true;
+			}
 		} catch (error) {
-			try {
-				await params.refundUsage?.({ coalesced });
+			throw new LLMError(error instanceof Error ? error.message : "Usage reservation failed", "quota_exceeded", void 0, void 0, error);
+		}
+		if (signal?.aborted) {
+			if (reserved) try {
+				await params.refundUsage?.({
+					coalesced,
+					signal
+				});
+			} catch (refundError) {
+				this.logger.error("[VernLLM] refundUsage failed after abort", { message: refundError instanceof Error ? refundError.message : "unknown" });
+			}
+			throw new LLMError("LLM request aborted", "aborted");
+		}
+		try {
+			return await getResult();
+		} catch (error) {
+			if (reserved) try {
+				await params.refundUsage?.({
+					coalesced,
+					signal
+				});
 			} catch (refundError) {
 				this.logger.error("[VernLLM] refundUsage failed", { message: refundError instanceof Error ? refundError.message : "unknown" });
 			}
@@ -642,13 +715,20 @@ var VernLLM = class {
 	/**
 	* Convenience wrapper composing `call` + `cachedCall`, so cached LLM calls
 	* automatically get retry/timeout/circuit-breaker behavior without callers
-	* having to remember to wire `fn: () => this.call(...)` themselves
+	* having to remember to wire `fn: () => this.call(...)` themselves.
+	*
+	* `reserveUsage`/`refundUsage` are read from the top-level params only — if
+	* `call` also sets them, they're ignored, since `call()` now performs its
+	* own reservation. Honoring both would reserve/refund twice per logical
+	* cachedLLMCall (once via cachedCall's wrapping, once via the inner call()).
 	*/
 	async cachedLLMCall(params) {
 		const { call: callParams,...cacheParams } = params;
+		const { reserveUsage: _innerReserveUsage, refundUsage: _innerRefundUsage,...restCallParams } = callParams;
+		if (_innerReserveUsage || _innerRefundUsage) this.logger.warn("[VernLLM] reserveUsage/refundUsage on `call` are ignored by cachedLLMCall; set them at the top level instead.");
 		return this.cachedCall({
 			...cacheParams,
-			fn: () => this.call(callParams)
+			fn: () => this.call(restCallParams)
 		});
 	}
 	/**