ai-lcr 0.2.2 → 0.2.5

package/dist/index.js

@@ -18,35 +18,128 @@ var RETRYABLE_PATTERNS = [
   "504",
   "429",
   // Billing caps — a capped provider should fall over, not kill the request.
+  // Include non-English wording: Chinese providers (e.g. Kunavo) report a failed
+  // charge as "余额不足"/"账户欠费"/"扣费失败" with a 200/400 body, which no
+  // English keyword and no HTTP status would catch — so without these a billing
+  // failure would die instead of failing over, the exact opposite of what we want.
   "insufficient",
   "credit",
   "quota",
   "billing",
-  "payment required"
+  "payment required",
+  "balance",
+  "\u4F59\u989D",
+  "\u6B20\u8D39",
+  "\u6263\u8D39",
+  "\u6263\u6B3E"
 ];
+var NETWORK_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ETIMEDOUT",
+  "EPIPE",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPROTO",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT"
+]);
+var NETWORK_PATTERNS = [
+  "fetch failed",
+  "failed to fetch",
+  "socket hang up",
+  "socket disconnected",
+  "econnrefused",
+  "econnreset",
+  "enotfound",
+  "etimedout",
+  "ehostunreach",
+  "enetunreach",
+  "eai_again",
+  "getaddrinfo",
+  "connect timeout",
+  "connection refused",
+  "connection reset",
+  "connection error",
+  "network error",
+  "dns"
+];
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+function errorSignals(error) {
+  const parts = [];
+  const codes = [];
+  const seen = /* @__PURE__ */ new Set();
+  let cur = error;
+  for (let depth = 0; depth < 6 && cur && typeof cur === "object" && !seen.has(cur); depth++) {
+    seen.add(cur);
+    const e = cur;
+    if (typeof e.message === "string") parts.push(e.message);
+    if (typeof e.name === "string") parts.push(e.name);
+    if (typeof e.code === "string") {
+      parts.push(e.code);
+      codes.push(e.code);
+    }
+    cur = e.cause;
+  }
+  if (parts.length === 0) parts.push(safeStringify(error));
+  return { text: parts.join(" ").toLowerCase(), codes };
+}
+function isNetworkError(error) {
+  const { text, codes } = errorSignals(error);
+  if (codes.some((c) => NETWORK_CODES.has(c))) return true;
+  return NETWORK_PATTERNS.some((p) => text.includes(p));
+}
 function isRetryableError(error) {
   const e = error;
   const status = e?.statusCode ?? e?.status;
   if (typeof status === "number" && (RETRYABLE_STATUS.has(status) || status > 500)) {
     return true;
   }
-  const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
+  if (isNetworkError(error)) return true;
+  const { text } = errorSignals(error);
   return RETRYABLE_PATTERNS.some((p) => text.includes(p));
 }
-function safeStringify(value) {
-  try {
-    return JSON.stringify(value) ?? "";
-  } catch {
-    return String(value);
-  }
-}
 function classifyError(error) {
   const e = error;
   const status = e?.statusCode ?? e?.status;
   if (typeof status === "number") return String(status);
-  const text = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
+  if (isNetworkError(error)) return "network";
+  const { text } = errorSignals(error);
   return RETRYABLE_PATTERNS.find((p) => text.includes(p)) ?? "error";
 }
+var AUTH_STATUS = /* @__PURE__ */ new Set([401, 403]);
+var BILLING_PATTERNS = [
+  "insufficient",
+  "credit",
+  "quota",
+  "billing",
+  "payment required",
+  "balance",
+  "exhausted",
+  "\u4F59\u989D",
+  "\u6B20\u8D39",
+  "\u6263\u8D39",
+  "\u6263\u6B3E"
+];
+function classifyErrorKind(error) {
+  const e = error;
+  const status = e?.statusCode ?? e?.status;
+  const { text } = errorSignals(error);
+  if (status === 402 || BILLING_PATTERNS.some((p) => text.includes(p))) return "billing";
+  if (typeof status === "number" && AUTH_STATUS.has(status)) return "auth";
+  return isRetryableError(error) ? "transient" : "client";
+}
 var callSeq = 0;
 function newCallId() {
   const c = globalThis.crypto;
@@ -63,11 +156,20 @@ var LcrFallbackModel = class {
   }
   opts;
   specificationVersion = "v3";
-  index = 0;
-  lastReset = Date.now();
+  // Cross-request *hint* for where the next request starts: after a failover we
+  // remember the provider that worked so we don't re-probe a dead cheap one on
+  // every call. This is the ONLY shared mutable state — and crucially it is read
+  // once per request (snapshotted into a local cursor) and written once on
+  // settle, never used as a per-request loop bound. The within-request iteration
+  // is fully local, so concurrent requests can't corrupt each other's routing.
+  sticky = 0;
+  // When `sticky` was last advanced (a failover). The re-probe timer measures
+  // from THIS, not from the last call — so it fires under sustained traffic too,
+  // instead of being pushed forward forever by a busy stream of requests.
+  lastFailoverAt = Date.now();
   resetIntervalMs;
   get current() {
-    return this.opts.providers[this.index];
+    return this.opts.providers[this.sticky];
   }
   get modelId() {
     return this.current.model.modelId;
@@ -78,18 +180,53 @@ var LcrFallbackModel = class {
   get supportedUrls() {
     return this.current.model.supportedUrls;
   }
-  checkReset() {
-    if (this.index !== 0 && Date.now() - this.lastReset >= this.resetIntervalMs) {
-      this.index = 0;
+  /**
+   * Index a new request should start at. If we're parked on a non-cheapest
+   * provider and it's been `resetIntervalMs` since the failover, snap back to
+   * the cheapest and re-probe it — this is what lets routing recover to the
+   * cheap source even during continuous traffic.
+   */
+  startIndex() {
+    if (this.sticky !== 0 && Date.now() - this.lastFailoverAt >= this.resetIntervalMs) {
+      this.sticky = 0;
     }
-    this.lastReset = Date.now();
-  }
-  switchNext() {
-    this.index = (this.index + 1) % this.opts.providers.length;
+    return this.sticky;
+  }
+  /**
+   * A request settled on `winIndex`. Park there so the next request skips the
+   * providers we just learned are down. Stamp the failover time only when the
+   * parked provider actually CHANGES — so a steady stream of successful calls
+   * on the same fallback doesn't keep pushing the re-probe timer forward.
+   */
+  settleSticky(winIndex) {
+    if (winIndex === this.sticky) return;
+    this.sticky = winIndex;
+    this.lastFailoverAt = Date.now();
   }
   shouldRetry(error) {
     return (this.opts.shouldRetry ?? isRetryableError)(error);
   }
+  // Observer callbacks are caller-supplied logging hooks: a throw from one of
+  // them must NEVER turn a successful (or already-failed) request into a
+  // different outcome. Swallow anything they throw — they are fire-and-forget.
+  emitError(error, provider) {
+    try {
+      this.opts.onError?.(error, provider);
+    } catch {
+    }
+  }
+  emitCost(event) {
+    try {
+      this.opts.onCost?.(event);
+    } catch {
+    }
+  }
+  emitCall(record) {
+    try {
+      this.opts.onCall?.(record);
+    } catch {
+    }
+  }
   startCall() {
     return { id: newCallId(), attempts: [], startedAt: Date.now() };
   }
@@ -99,7 +236,8 @@ var LcrFallbackModel = class {
       provider: provider.label,
       ok: false,
       latencyMs: Date.now() - attemptStart,
-      errorClass: classifyError(error)
+      errorClass: classifyError(error),
+      kind: classifyErrorKind(error)
     });
   }
   /** Winner settled: record the attempt, fire `onCost` (compat) + `onCall`. */
@@ -108,14 +246,14 @@ var LcrFallbackModel = class {
     const inputTokens = usage?.inputTokens?.total ?? 0;
     const outputTokens = usage?.outputTokens?.total ?? 0;
     const costUsd = provider.cost ? inputTokens / 1e6 * provider.cost.input + outputTokens / 1e6 * provider.cost.output : 0;
-    this.opts.onCost?.({
+    this.emitCost({
       model: this.opts.modelName,
       provider: provider.label,
       inputTokens,
       outputTokens,
       costUsd
     });
-    this.opts.onCall?.({
+    this.emitCall({
       id: ctx.id,
       model: this.opts.modelName,
       attempts: ctx.attempts,
@@ -130,7 +268,7 @@ var LcrFallbackModel = class {
   }
   /** Every provider failed: fire `onCall` with no winner. */
   finalizeFail(ctx) {
-    this.opts.onCall?.({
+    this.emitCall({
       id: ctx.id,
       model: this.opts.modelName,
       attempts: ctx.attempts,
@@ -144,15 +282,18 @@ var LcrFallbackModel = class {
     });
   }
   async doGenerate(options) {
-    this.checkReset();
     const ctx = this.startCall();
-    const start = this.index;
+    const providers = this.opts.providers;
+    const n = providers.length;
+    const start = this.startIndex();
     let lastError;
-    for (; ; ) {
-      const provider = this.current;
+    for (let tried = 0; tried < n; tried++) {
+      const idx = (start + tried) % n;
+      const provider = providers[idx];
       const attemptStart = Date.now();
       try {
         const result = await provider.model.doGenerate(options);
+        this.settleSticky(idx);
         this.finalizeOk(ctx, provider, attemptStart, result.usage);
         return result;
       } catch (error) {
@@ -162,31 +303,32 @@ var LcrFallbackModel = class {
           this.finalizeFail(ctx);
           throw error;
         }
-        this.opts.onError?.(error, provider.label);
+        this.emitError(error, provider.label);
         this.recordFail(ctx, provider, attemptStart, error);
-        this.switchNext();
-        if (this.index === start) {
-          this.finalizeFail(ctx);
-          throw lastError;
-        }
       }
     }
+    this.finalizeFail(ctx);
+    throw lastError;
   }
   async doStream(options) {
-    this.checkReset();
-    return this.doStreamWithCtx(options, this.startCall());
-  }
-  // The stream's failover recursion re-enters here with the SAME `ctx`, so a
-  // mid-stream switch keeps appending to one CallRecord instead of starting a
-  // fresh one. `finalizeOk`/`finalizeFail` fire exactly once per outer request.
-  async doStreamWithCtx(options, ctx) {
+    return this.doStreamWithCtx(options, this.startCall(), this.startIndex(), 0);
+  }
+  // The stream's failover recursion re-enters here with the SAME `ctx` and a
+  // threaded-through local cursor (`idx`/`tried`), so a mid-stream switch keeps
+  // appending to one CallRecord and bounds itself on the local `tried` count —
+  // never on shared instance state. `finalizeOk`/`finalizeFail` fire exactly
+  // once per outer request.
+  async doStreamWithCtx(options, ctx, startIdx, alreadyTried) {
     const self = this;
-    const start = this.index;
+    const providers = this.opts.providers;
+    const n = providers.length;
     let result;
     let serving;
     let servingStart;
+    let idx = startIdx;
+    let tried = alreadyTried;
     for (; ; ) {
-      serving = this.current;
+      serving = providers[idx];
       servingStart = Date.now();
       try {
         result = await serving.model.doStream(options);
@@ -197,17 +339,20 @@ var LcrFallbackModel = class {
           this.finalizeFail(ctx);
           throw error;
         }
-        this.opts.onError?.(error, serving.label);
+        this.emitError(error, serving.label);
         this.recordFail(ctx, serving, servingStart, error);
-        this.switchNext();
-        if (this.index === start) {
+        tried++;
+        if (tried >= n) {
           this.finalizeFail(ctx);
           throw error;
         }
+        idx = (idx + 1) % n;
       }
     }
     const servingProvider = serving;
     const servingAttemptStart = servingStart;
+    const servingIdx = idx;
+    const triedBeforeServing = tried;
     let usage;
     let streamedAny = false;
     const stream = new ReadableStream({
@@ -226,20 +371,26 @@ var LcrFallbackModel = class {
             controller.enqueue(value);
             if (value.type !== "stream-start") streamedAny = true;
           }
+          self.settleSticky(servingIdx);
           self.finalizeOk(ctx, servingProvider, servingAttemptStart, usage);
           controller.close();
         } catch (error) {
-          self.opts.onError?.(error, servingProvider.label);
+          self.emitError(error, servingProvider.label);
           self.recordFail(ctx, servingProvider, servingAttemptStart, error);
           if (!streamedAny) {
-            self.switchNext();
-            if (self.index === start) {
+            const nextTried = triedBeforeServing + 1;
+            if (nextTried >= n) {
               self.finalizeFail(ctx);
               controller.error(error);
               return;
             }
             try {
-              const next = await self.doStreamWithCtx(options, ctx);
+              const next = await self.doStreamWithCtx(
+                options,
+                ctx,
+                (servingIdx + 1) % n,
+                nextTried
+              );
               const nextReader = next.stream.getReader();
               try {
                 for (; ; ) {
@@ -348,6 +499,24 @@ function newMediaCallId() {
 }
 function createMediaLCR(config) {
   const { registry, adapters, reference = DEFAULT_REFERENCE, onError, onCost, onCall } = config;
+  const safeError = (error, provider) => {
+    try {
+      onError?.(error, provider);
+    } catch {
+    }
+  };
+  const safeCost = (event) => {
+    try {
+      onCost?.(event);
+    } catch {
+    }
+  };
+  const safeCall = (record) => {
+    try {
+      onCall?.(record);
+    } catch {
+    }
+  };
   return async function generate(modelId, input) {
     const def = registry[modelId];
     if (!def) {
@@ -358,7 +527,7 @@ function createMediaLCR(config) {
     const startedAt = Date.now();
     const attempts = [];
     let lastErr;
-    const emitFail = () => onCall?.({
+    const emitFail = () => safeCall({
       id: newMediaCallId(),
       model: modelId,
       attempts,
@@ -380,8 +549,8 @@ function createMediaLCR(config) {
         const estimated = result.costCents === void 0;
         const costCents = estimated ? route.refCents * (result.units ?? 1) : result.costCents;
         attempts.push({ provider: route.provider, ok: true, latencyMs: Date.now() - attemptStart });
-        onCost?.({ modelId, provider: route.provider, costCents, estimated });
-        onCall?.({
+        safeCost({ modelId, provider: route.provider, costCents, estimated });
+        safeCall({
           id: newMediaCallId(),
           model: modelId,
           attempts,
@@ -403,7 +572,7 @@ function createMediaLCR(config) {
           latencyMs: Date.now() - attemptStart,
           errorClass: classifyError(err)
         });
-        onError?.(err, route.provider);
+        safeError(err, route.provider);
         if (!isRetryableError(err)) {
           emitFail();
           throw err;
@@ -694,84 +863,49 @@ var RunwareMediaError = class extends Error {
 };
 
 // src/adapters/fal-media.ts
-var DEFAULT_BASE3 = "https://queue.fal.run";
-function extractOutputs(raw) {
-  if (!raw || typeof raw !== "object") return [];
-  const data = raw;
-  const out = [];
-  const pushUrl = (url, type) => {
-    if (typeof url === "string" && url.length > 0) out.push({ url, type });
-  };
-  if (Array.isArray(data.images)) {
-    for (const img of data.images) pushUrl(img?.url, "image");
-  }
-  pushUrl(data.image?.url, "image");
-  if (Array.isArray(data.videos)) {
-    for (const v of data.videos) pushUrl(v?.url, "video");
+var DEFAULT_BASE3 = "https://fal.run";
+function extractImageUrls2(body) {
+  const fromArray = (body.images ?? []).map((im) => im?.url).filter((u) => typeof u === "string" && u.length > 0);
+  if (fromArray.length > 0) return fromArray;
+  const single = body.image?.url;
+  return typeof single === "string" && single.length > 0 ? [single] : [];
+}
+function errorMessage2(body) {
+  if (typeof body.detail === "string") return body.detail;
+  if (Array.isArray(body.detail)) {
+    const msgs = body.detail.map((d) => d?.msg).filter(Boolean);
+    if (msgs.length > 0) return msgs.join("; ");
   }
-  pushUrl(data.video?.url, "video");
-  return out;
+  return body.error || body.message || "unknown";
 }
 function createFalMediaAdapter(config) {
-  const {
-    apiKey,
-    baseUrl = DEFAULT_BASE3,
-    pollIntervalMs = 3e3,
-    pollTimeoutMs = 3e5,
-    fetchImpl = fetch
-  } = config;
-  const headers = {
-    "content-type": "application/json",
-    authorization: `Key ${apiKey}`
-  };
+  const { apiKey, baseUrl = DEFAULT_BASE3, fetchImpl = fetch } = config;
   return {
     provider: "fal",
     async run(req) {
-      const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+      const res = await fetchImpl(`${baseUrl}/${req.externalId}`, {
         method: "POST",
-        headers,
+        headers: {
+          "content-type": "application/json",
+          authorization: `Key ${apiKey}`,
+          accept: "application/json"
+        },
         body: JSON.stringify(req.input)
       });
-      if (!submitRes.ok) {
-        throw new FalMediaError(submitRes.status, await safeText2(submitRes));
-      }
-      const submit = await submitRes.json();
-      const statusUrl = submit.status_url;
-      const responseUrl = submit.response_url;
-      if (!statusUrl || !responseUrl) {
-        throw new Error(
-          `ai-lcr: fal submit for "${req.externalId}" returned no status/response URL (keys: ${Object.keys(
-            submit
-          ).join(", ")})`
-        );
-      }
-      const deadline = Date.now() + pollTimeoutMs;
-      let completed = false;
-      while (Date.now() < deadline) {
-        const statusRes = await fetchImpl(statusUrl, { headers });
-        if (!statusRes.ok) {
-          throw new FalMediaError(statusRes.status, await safeText2(statusRes));
-        }
-        const status = String((await statusRes.json()).status ?? "");
-        if (status === "COMPLETED") {
-          completed = true;
-          break;
-        }
-        await sleep2(pollIntervalMs);
-      }
-      if (!completed) {
-        throw new Error(
-          `ai-lcr: fal job for "${req.externalId}" timed out after ${pollTimeoutMs}ms`
-        );
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        body = {};
       }
-      const resultRes = await fetchImpl(responseUrl, { headers });
-      if (!resultRes.ok) {
-        throw new FalMediaError(resultRes.status, await safeText2(resultRes));
+      if (!res.ok) {
+        throw new FalMediaError(res.status, errorMessage2(body));
       }
-      const outputs = extractOutputs(await resultRes.json());
-      if (outputs.length === 0) {
-        throw new Error(`ai-lcr: fal returned no media URL for "${req.externalId}"`);
+      const urls = extractImageUrls2(body);
+      if (urls.length === 0) {
+        throw new Error(`ai-lcr: fal returned no image URL for "${req.externalId}"`);
       }
+      const outputs = urls.map((url) => ({ url, type: "image" }));
       return { outputs, units: outputs.length };
     }
   };
@@ -784,16 +918,6 @@ var FalMediaError = class extends Error {
   }
   status;
 };
-function sleep2(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-async function safeText2(res) {
-  try {
-    return await res.text();
-  } catch {
-    return "<no body>";
-  }
-}
 
 // src/index.ts
 function isLanguageModel(entry) {
@@ -837,10 +961,10 @@ function createLCR(config) {
 }
 export {
   DEFAULT_REFERENCE,
-  FalMediaError,
   MEDIA_PRICING,
   cheapestRoute,
   classifyError,
+  classifyErrorKind,
   comparePrices,
   createFalMediaAdapter,
   createKunavoMediaAdapter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "Least Cost Routing for LLMs — route every model call to the cheapest available provider, fall back automatically, and track real cost. Built for the Vercel AI SDK.",
   "keywords": [
     "ai",
@@ -39,13 +39,15 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test"
   },
   "peerDependencies": {
     "ai": "^6.0.0"