@providerkit/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+<img src="brand/providerkit-mark.svg" alt="" width="76" align="left" hspace="4" vspace="2">
+
+# providerkit
+
+**The layer under your agent loop.** One seam for every LLM provider, plus the failure
+handling you only learn in production.
+
+```bash
+bun add @providerkit/core   # npm / pnpm / yarn all fine
+```
+
+Zero runtime dependencies. `fetch` only — no vendor SDKs, no Node built-ins — so the same
+build runs in Bun, Node, Cloudflare Workers, Deno and a Chrome MV3 service worker.
+
+## What this is
+
+Most "unified LLM interface" libraries stop at the interface. That part is easy, and it is
+not where the time goes. The time goes here:
+
+- a stream that opens, sends nothing, and never ends
+- a socket that dies four `cause` levels down, with no HTTP status to read
+- quota exhaustion arriving as `429` from one vendor, `402` from another, `403` from a
+  third and `400` from a fourth — with "retry" being the wrong advice for all of them
+- a `429` that is really a context overflow, where waiting fixes nothing and compaction
+  fixes everything
+- a plan that never included the API, which neither a new key nor a top-up will fix
+- Anthropic reporting cache tokens _outside_ the input count while OpenAI reports them
+  _inside_ it — so the same conversation costs two different things
+- `reasoning_content` that must be replayed on tool-call turns, and must _not_ be sent
+  when thinking is off
+- a tool call's JSON truncated mid-argument, throwing away an answer that was right there
+
+providerkit is that knowledge, as a library.
+
+## What this is not
+
+**Not an agent framework.** There is no loop here, no prompt, no memory, no graph. Your
+loop is where your product lives; it should stay yours. This is everything underneath it.
+
+## Use
+
+```ts
+import { createAnthropicProvider, drainStream } from "@providerkit/core";
+
+const provider = createAnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-5",
+});
+
+for await (const chunk of provider.createStream(messages, tools, { effort: "medium" })) {
+  if (chunk.content) process.stdout.write(chunk.content);
+  if (chunk.usage) console.log(chunk.usage); // one meaning across every provider
+}
+```
+
+`createOpenAIProvider` speaks the dialect most gateways do, so it serves OpenAI, OpenRouter,
+DeepSeek, GLM, Kimi, Groq, Together, vLLM, Ollama and LM Studio:
+
+```ts
+const provider = createOpenAIProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  baseUrl: "https://openrouter.ai/api",
+  id: "openrouter",
+  model: "deepseek/deepseek-v4-pro",
+  // Keep the prompt cache warm: it lives on the upstream host's account, and
+  // OpenRouter's default routing hops hosts between rounds — every hop is a
+  // cold cache, in both latency and effective input cost.
+  providerOrder: ["deepinfra", "fireworks"],
+});
+```
+
+### Failures, named by what fixes them
+
+```ts
+import { ProviderError, isTransient, isBackupEligible } from "@providerkit/core";
+
+try {
+  // …
+} catch (raw) {
+  const err = ProviderError.from("anthropic", raw);
+
+  err.kind; // "overload" | "rate" | "quota" | "entitlement" | "auth" | "context" | …
+  err.retryAfterMs; // honoured from Retry-After, vendor reset headers, or Gemini's RetryInfo
+  err.body; // the provider's actual words, never "400 status code (no body)"
+
+  if (err.kind === "context") compactAndRetry();
+  else if (isBackupEligible(err.kind)) tryAnotherModel();
+  else if (isTransient(err.kind)) retry();
+  else surface(err);
+}
+```
+
+### Retrying, safely
+
+```ts
+import { withStreamRetry, streamWithBackupModels } from "@providerkit/core";
+
+// Retries only while NOTHING has been emitted. Past the first chunk the stream
+// is committed — a retry would replay tokens already on the reader's screen.
+const stream = withStreamRetry((signal) => provider.createStream(messages, tools, { signal }));
+
+// Walks [primary, ...backups] on overload and rate limits only; an auth failure
+// or an invalid request would land identically on every backup.
+const withFallback = streamWithBackupModels((model) => run(model), {
+  models: ["claude-opus-5", "claude-sonnet-5"],
+});
+```
+
+### The watchdog
+
+```ts
+import { streamWatch, watchChunks } from "@providerkit/core";
+
+const watch = streamWatch({ provider: "openai", signal: userSignal });
+for await (const chunk of watchChunks(
+  watch,
+  provider.createStream(messages, tools, {
+    signal: watch.signal,
+  }),
+)) {
+  // any byte re-arms the deadline
+}
+watch.firstChunkMs(); // TTFT — the number a prompt-cache pin exists to shrink
+```
+
+A stream that goes 60 seconds without a byte is aborted and surfaced as a transient
+`timeout`. The watchdog aborts its _own_ controller and only bridges the caller's, so your
+user's Stop stays distinguishable from our deadline: one is never retried, the other always
+is.
+
+### Tools
+
+JSON Schema by default, so the core needs no zod:
+
+```ts
+import { defineTool, ToolRegistry } from "@providerkit/core";
+
+const search = defineTool({
+  name: "search",
+  description: "Search the corpus",
+  inputSchema: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },
+  run: async ({ q }, ctx) => findAll(q, { signal: ctx.signal }),
+});
+
+const outcome = await search.invoke(rawArgsFromModel);
+// { ok: false, kind: "invalid_input" | "timeout" | "aborted" | "failed", error }
+```
+
+A failing tool is **data**, not an exception — the loop feeds `error` back so the model can
+correct itself. Only a caller's abort escapes.
+
+With zod, from the optional entry point:
+
+```ts
+import { zodTool } from "@providerkit/core/zod";
+
+const submit = zodTool({
+  name: "submit",
+  description: "Submit the final answer",
+  isTerminal: true,
+  clampOverflow: true, // a terminal tool gets no second chance
+  input: z.object({ summary: z.string().max(2000) }),
+  run: async (input) => input,
+});
+```
+
+### Truncated tool calls
+
+```ts
+import { parseToolArgs, isCompleteJson } from "@providerkit/core";
+
+// Never throws. A turn cut off mid-argument keeps every field that closed
+// before the cut, plus the half-written one the cut landed in.
+const args = parseToolArgs(rawArgumentString);
+```
+
+### Compaction
+
+The decisions, not the prompt — the summary is yours to write:
+
+```ts
+import { needsCompaction, pickCut, applyCompaction, historyBudgetTokens } from "@providerkit/core";
+
+if (needsCompaction(lastInputTokens, contextWindow)) {
+  const cut = pickCut(messages, historyBudgetTokens(contextWindow));
+  messages = applyCompaction(messages, cut, await summarize(messages.slice(0, cut)));
+}
+```
+
+`pickCut` never splits a tool call from its result (every provider rejects the orphan with a
+400 — the failure compaction was called to avoid), never cuts into the system prompt, and
+always keeps the newest message.
+
+### Cost
+
+The arithmetic, not the rates. A price table is volatile data about a catalogue that differs
+per application, and a wrong number shipped in a library is a wrong number in everyone's
+ledger — so you keep the numbers, verifiable line by line against a vendor's price sheet:
+
+```ts
+import { UsageTracker } from "@providerkit/core";
+
+const tracker = new UsageTracker();
+tracker.add(usage, { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 }); // USD per Mtok
+tracker.costUsd;
+tracker.cacheSavingsUsd; // what the cache saved, for the "is caching even working" question
+```
+
+## Origin
+
+This was extracted from five production codebases that had each independently grown the same
+layer — about 9,100 lines solving one ~2,000-line problem. They had three separate
+60-second idle watchdogs, identical down to the constant. On one day in September 2026, two
+of them shipped the same five fixes independently.
+
+They had also each learned a _different_ part of the problem. One walked the `cause` chain
+for dead sockets; one parsed Gemini's `RetryInfo`; one read the body before the status and
+knew the quota wordings in five languages; one knew Anthropic's `529` and when a failure is
+worth a different model; one could rescue an answer from a tool call the model truncated.
+
+The classifier here is the union of all five, and the suite is every failure any of them
+ever saw. That is the part worth having.
+
+## Repo
+
+```
+core/    the npm package `providerkit`
+site/    providerkit.dev — also open source
+```
+
+`bun install`, then `cd core && bun run test`. See [AGENTS.md](./AGENTS.md) for the layout,
+the invariants worth not regressing, and what is left to build.
+
+## Status
+
+Working and tested (218 tests): the seam, the error classifier, retry and backup-model
+fallback, the idle watchdog, cost math, the fetch/SSE transport, tool-argument salvage, the
+Anthropic and OpenAI-shape adapters, the tool kernel, schema clamping, and the compaction
+decisions.
+
+Not yet: the Gemini and Responses adapters, and the multi-key rotation pool.
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,69 @@
+import type { ChatMessage } from "./types.ts";
+/**
+ * What the answer needs after the prompt: an output budget, plus the tools'
+ * own schemas, plus the slack no provider documents.
+ *
+ * Absolute rather than a percentage on purpose — a 1M window does not need a
+ * 100k cushion, and a 128k window needs more than 12k.
+ */
+export declare const CONTEXT_RESERVE_TOKENS = 32000;
+/**
+ * Four characters per token — the rule of thumb every provider's own
+ * calculator agrees with to within a fifth, which is all the precision this
+ * needs. It decides WHEN to fold: folding one turn early costs a cheap model
+ * call, folding one turn late costs the whole turn.
+ */
+export declare function estimateTokens(text: string): number;
+/** What one message costs to re-send: its words, its reasoning, and the
+ *  arguments of any calls it made. */
+export declare function messageTokens(message: ChatMessage): number;
+export declare function conversationTokens(messages: readonly ChatMessage[]): number;
+/**
+ * The provider's own input count says the wall is close — fold before the next
+ * step rather than after the 400.
+ *
+ * Takes the REPORTED count, not an estimate, because it is the only figure
+ * that is not a guess. Estimate only when there is no reported count yet.
+ */
+export declare function needsCompaction(inputTokens: number, contextWindow: number): boolean;
+/**
+ * How much of the window the history BEHIND the current turn may spend: a
+ * tenth, floored so a small window still gets a usable memory. The tail stays
+ * verbatim and the summary is short, so the rest is what folding buys back.
+ */
+export declare function historyBudgetTokens(contextWindow: number): number;
+/**
+ * Where to cut so the messages AFTER the cut fit `budget`, walking backwards
+ * from the newest.
+ *
+ * Two invariants the cut must respect, and both are correctness rather than
+ * taste:
+ *
+ *  1. Never split a tool call from its result. Every provider rejects a tool
+ *     result whose call is missing, so a cut landing between them produces a
+ *     400 on the very next turn — the failure compaction was called to avoid.
+ *  2. Never cut into the system prompt. It is not history.
+ *
+ * Returns the index the kept tail starts at, or 0 when everything already fits.
+ */
+export declare function pickCut(messages: readonly ChatMessage[], budget: number): number;
+/**
+ * Fold `messages` into `[…system, summary, …tail]`.
+ *
+ * The summary arrives as a user turn rather than a system one: a system
+ * message added mid-conversation reads to the model as a new instruction, and
+ * several providers require the system block to be first and singular anyway.
+ */
+export declare function applyCompaction(messages: readonly ChatMessage[], cut: number, summary: string): ChatMessage[];
+/**
+ * The context window for a model, when nothing volunteered one.
+ *
+ * The ladder exists because the endpoints disagree about whether to tell you:
+ * OpenRouter, LM Studio and Ollama publish `context_length`; Anthropic and
+ * OpenAI do not. A reported number always wins; this is the floor under it.
+ *
+ * A conservative default is the right failure: too small folds one turn early
+ * and costs a cheap call, too large hits a hard 400 mid-run.
+ */
+export declare function guessContextWindow(model: string): number;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAWD;sCACsC;AACtC,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAO1D;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA0BhF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,WAAW,EAAE,EAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,WAAW,EAAE,CAQf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxD"}

package/dist/context.js

@@ -0,0 +1,132 @@
+/**
+ * What the answer needs after the prompt: an output budget, plus the tools'
+ * own schemas, plus the slack no provider documents.
+ *
+ * Absolute rather than a percentage on purpose — a 1M window does not need a
+ * 100k cushion, and a 128k window needs more than 12k.
+ */
+export const CONTEXT_RESERVE_TOKENS = 32_000;
+/**
+ * Four characters per token — the rule of thumb every provider's own
+ * calculator agrees with to within a fifth, which is all the precision this
+ * needs. It decides WHEN to fold: folding one turn early costs a cheap model
+ * call, folding one turn late costs the whole turn.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function textOf(message) {
+    if (message.role === "user" && typeof message.content !== "string") {
+        // Only the words are countable; an image's cost is the provider's own
+        // arithmetic and no character count approximates it.
+        return message.content.map((part) => (part.type === "text" ? part.text : "")).join("");
+    }
+    return typeof message.content === "string" ? message.content : "";
+}
+/** What one message costs to re-send: its words, its reasoning, and the
+ *  arguments of any calls it made. */
+export function messageTokens(message) {
+    const extra = message.role === "assistant"
+        ? (message.reasoning ?? "") +
+            (message.toolCalls?.map((call) => call.name + call.arguments).join("") ?? "")
+        : "";
+    return estimateTokens(textOf(message) + extra);
+}
+export function conversationTokens(messages) {
+    return messages.reduce((total, message) => total + messageTokens(message), 0);
+}
+/**
+ * The provider's own input count says the wall is close — fold before the next
+ * step rather than after the 400.
+ *
+ * Takes the REPORTED count, not an estimate, because it is the only figure
+ * that is not a guess. Estimate only when there is no reported count yet.
+ */
+export function needsCompaction(inputTokens, contextWindow) {
+    return inputTokens >= contextWindow - CONTEXT_RESERVE_TOKENS;
+}
+/**
+ * How much of the window the history BEHIND the current turn may spend: a
+ * tenth, floored so a small window still gets a usable memory. The tail stays
+ * verbatim and the summary is short, so the rest is what folding buys back.
+ */
+export function historyBudgetTokens(contextWindow) {
+    return Math.max(6_000, Math.floor(contextWindow * 0.1));
+}
+/**
+ * Where to cut so the messages AFTER the cut fit `budget`, walking backwards
+ * from the newest.
+ *
+ * Two invariants the cut must respect, and both are correctness rather than
+ * taste:
+ *
+ *  1. Never split a tool call from its result. Every provider rejects a tool
+ *     result whose call is missing, so a cut landing between them produces a
+ *     400 on the very next turn — the failure compaction was called to avoid.
+ *  2. Never cut into the system prompt. It is not history.
+ *
+ * Returns the index the kept tail starts at, or 0 when everything already fits.
+ */
+export function pickCut(messages, budget) {
+    const firstNonSystem = messages.findIndex((message) => message.role !== "system");
+    // Nothing but a system prompt: there is no history to fold.
+    if (firstNonSystem === -1)
+        return messages.length;
+    // The newest message is always kept, budget or not. A conversation whose
+    // latest turn alone overruns the budget is not fixable by cutting history,
+    // and answering a summary instead of the question the person just asked is
+    // never the right failure.
+    const latest = messages.length - 1;
+    let cut = latest;
+    let total = messageTokens(messages[latest]);
+    for (let i = latest - 1; i >= firstNonSystem; i--) {
+        total += messageTokens(messages[i]);
+        if (total > budget)
+            break;
+        cut = i;
+    }
+    // Walk back off any tool result whose assistant turn would be left behind
+    // it. Bounded by the first non-system message, so it can never run off the
+    // front. This can exceed the budget by a message or two, which is the right
+    // trade: an orphaned tool result is a hard 400, not an overrun.
+    while (cut > firstNonSystem && messages[cut].role === "tool")
+        cut--;
+    return cut;
+}
+/**
+ * Fold `messages` into `[…system, summary, …tail]`.
+ *
+ * The summary arrives as a user turn rather than a system one: a system
+ * message added mid-conversation reads to the model as a new instruction, and
+ * several providers require the system block to be first and singular anyway.
+ */
+export function applyCompaction(messages, cut, summary) {
+    const system = messages.filter((message) => message.role === "system");
+    const tail = messages.slice(cut).filter((message) => message.role !== "system");
+    return [
+        ...system,
+        { role: "user", content: `[Earlier conversation, summarized]\n\n${summary}` },
+        ...tail,
+    ];
+}
+/**
+ * The context window for a model, when nothing volunteered one.
+ *
+ * The ladder exists because the endpoints disagree about whether to tell you:
+ * OpenRouter, LM Studio and Ollama publish `context_length`; Anthropic and
+ * OpenAI do not. A reported number always wins; this is the floor under it.
+ *
+ * A conservative default is the right failure: too small folds one turn early
+ * and costs a cheap call, too large hits a hard 400 mid-run.
+ */
+export function guessContextWindow(model) {
+    const id = model.toLowerCase();
+    if (/gemini|gpt-4\.1|grok-4|llama-4/.test(id))
+        return 1_000_000;
+    if (/claude|gpt-5|o[34]|deepseek|kimi|glm|qwen/.test(id))
+        return 200_000;
+    if (/gpt-4o|mistral|command-r/.test(id))
+        return 128_000;
+    return 128_000;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,86 @@
+/** What kind of failure this is, named by what actually fixes it. */
+export type ErrorKind = 
+/** Our own cancel — the caller pressed Stop. Never retried. */
+"aborted"
+/** Our own deadline, or the provider's 408. Retry. */
+ | "timeout"
+/** The request never reached the provider: socket died, DNS, proxy. Retry. */
+ | "network"
+/** Theirs, and temporary: 5xx, Anthropic's 529, "overloaded". Retry, and
+ *  worth trying a different model. */
+ | "overload"
+/** 429 per-minute throttle. Wait — or rotate to another key or model. */
+ | "rate"
+/** Balance or usage window exhausted. Waiting minutes will not fix it. */
+ | "quota"
+/** The plan never included this API. Neither a new key nor a top-up fixes it. */
+ | "entitlement"
+/** 401/403 — the key is wrong, not the request. */
+ | "auth"
+/** The model id does not exist or is not served here. */
+ | "model"
+/** The prompt outgrew the context window. The fix is to send less. */
+ | "context"
+/** Safety filter or refusal. */
+ | "content"
+/** Any other 4xx — a bug in what we sent. */
+ | "invalid" | "unknown";
+export declare function isTransient(kind: ErrorKind): boolean;
+export declare function isBackupEligible(kind: ErrorKind): boolean;
+export declare class ProviderError extends Error {
+    readonly provider: string;
+    readonly kind: ErrorKind;
+    readonly status?: number;
+    readonly code?: string;
+    /** Honoured when the provider said how long to wait (Retry-After, or
+     *  Gemini's RetryInfo.retryDelay). */
+    readonly retryAfterMs?: number;
+    /** The provider's own response body, truncated — the actual reason, which is
+     *  otherwise lost behind "400 status code (no body)". */
+    readonly body?: string;
+    constructor(provider: string, kind: ErrorKind, message: string, opts?: {
+        status?: number;
+        code?: string;
+        retryAfterMs?: number;
+        body?: string;
+        cause?: unknown;
+    });
+    get isTransient(): boolean;
+    get isBackupEligible(): boolean;
+    /** Wrap anything thrown into a classified ProviderError. Already-wrapped
+     *  errors pass through untouched, so classification happens exactly once. */
+    static from(provider: string, err: unknown): ProviderError;
+}
+export declare function messageOf(err: unknown): string;
+/**
+ * A transport fault: the socket died before or during the response, so there
+ * is NO status and no body for the patterns below to read.
+ *
+ * The chain is walked because the useful code is rarely on the thrown error —
+ * it sits on `cause`, sometimes several wrappers deep. Without this walk every
+ * network blip classifies as permanent, and a long run dies on its first
+ * hiccup, which is the single likeliest way to lose a minutes-long job.
+ *
+ * A deliberate abort short-circuits to false: the caller pressed Stop, and
+ * retrying that just re-fails against the same dead signal.
+ */
+export declare function isTransportFailure(err: unknown): boolean;
+/**
+ * The kind of failure, from whatever was thrown.
+ *
+ * Body patterns outrank status for the 4xx family; within them, context beats
+ * entitlement beats quota beats auth — each earlier category's fix is useless
+ * for the later ones.
+ */
+export declare function classify(err: unknown, status?: number, body?: string): ErrorKind;
+/**
+ * How long the provider asked us to wait, in ms. Two dialects: Gemini's
+ * RetryInfo (`"retryDelay": "52s"`, inside the body) and the `Retry-After`
+ * header, which SDKs keep on the error. Honouring it beats guessing — a
+ * backoff shorter than the window just burns an attempt.
+ */
+export declare function parseRetryAfterMs(err: unknown, body?: string): number | undefined;
+/** The loggable surface of a failure — so a dead run never reads
+ *  "400 status code (no body)". */
+export declare function describeProviderError(err: unknown): Record<string, unknown>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAYA,qEAAqE;AACrE,MAAM,MAAM,SAAS;AACnB,+DAA+D;AAC7D,SAAS;AACX,sDAAsD;GACpD,SAAS;AACX,8EAA8E;GAC5E,SAAS;AACX;sCACsC;GACpC,UAAU;AACZ,yEAAyE;GACvE,MAAM;AACR,0EAA0E;GACxE,OAAO;AACT,iFAAiF;GAC/E,aAAa;AACf,mDAAmD;GACjD,MAAM;AACR,yDAAyD;GACvD,OAAO;AACT,sEAAsE;GACpE,SAAS;AACX,gCAAgC;GAC9B,SAAS;AACX,6CAA6C;GAC3C,SAAS,GACT,SAAS,CAAC;AAcd,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEpD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEzD;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;0CACsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;6DACyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAGrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;IAYR,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAED;iFAC6E;IAC7E,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,aAAa;CAc3D;AAgBD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAU9C;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAiBxD;AAqFD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAgChF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkBjF;AAED;mCACmC;AACnC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa3E"}