ai-lcr 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to `ai-lcr` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.2.5] — 2026-06-01
+
+Pre-launch failover-robustness + media-provider pass — closing cases where a
+real provider failure slipped past the switch criterion and killed the request,
+and making fal a live failover target.
+
+### Fixed
+
+- **A network-unreachable provider didn't fail over.** `isRetryableError` only
+  matched HTTP statuses and English keywords, but a provider that's down throws
+  a `fetch` `TypeError` with *no* status — and wraps the real cause
+  (`ECONNREFUSED`/`ECONNRESET`/`ENOTFOUND`/connect-timeout, with the Node `code`)
+  in `error.cause`. Those read as a non-retryable client error, so the cheapest
+  provider going down killed the request instead of falling over — the most
+  common outage mode. The engine now walks the `cause` chain and treats Node
+  network codes / transport-failure messages as retryable. Applies to both the
+  text and media routers. New exported helper `isNetworkError`.
+- **Non-English billing failures didn't fail over.** Out-of-credit detection was
+  English-only, but Chinese providers (e.g. Kunavo) report a failed charge as
+  `余额不足`/`账户欠费`/`扣费失败` in a 200/400 body with no billing status.
+  Those are now matched (plus `balance`/`exhausted`), so a failed charge fails
+  over and is tagged `billing` by `classifyErrorKind` for alerting.
+- **An out-of-balance 403 was mis-tagged as `auth`.** Providers report an
+  exhausted account as 403 (e.g. fal "exhausted balance") — a top-up problem,
+  not a revoked key. `classifyErrorKind` now lets billing wording win over a
+  bare 401/403 status, so it's tagged `billing` (a plain 403 stays `auth`).
+- **A throwing observer could fail a successful request.** `onCost`/`onCall`/
+  `onError` were invoked unguarded; a logging sink that threw (e.g. a flaky db9
+  write) turned an otherwise-successful generation into a thrown error. All
+  observer callbacks are now fire-and-forget — wrapped so a throw can never
+  affect routing or the request outcome. Applies to both routers.
+
+### Added
+
+- **fal media adapter** (`createFalMediaAdapter`). fal was in the price table
+  but had no adapter, so its routes were silently skipped at runtime — now it's
+  a real cheapest-first / failover target for image models. Synchronous
+  `https://fal.run/<model>` with `Authorization: Key`, generic input pass-
+  through, HTTP-status-bearing errors (403 out-of-balance → fails over; 422 bad
+  input → doesn't). Image only; fal video (queue) is on the roadmap.
+- **Status-page liveness probes for Runware + fal** (`website`). Both are now
+  monitored with a free, generation-free reachability probe: Runware's `ping`
+  task (→ `pong`, 0 cost) and fal's `GET /v1/account/billing` (2xx ⇒ endpoint up
+  + key valid). Generalized via a new `ReachProbe` so a "reachable" check can
+  hit a provider-specific free endpoint instead of `GET /v1/models`. Requires
+  `RUNWARE_API_KEY` and `FAL_KEY` env vars to be set.
+
 ## [0.2.3] — 2026-06-01
 
 Release-quality and engine-correctness pass.
@@ -57,4 +104,5 @@ Release-quality and engine-correctness pass.
 - Dual ESM/CJS build. Media (image/video) least-cost routing with the Runware
   and Kunavo adapters; cap-aware failover for the text router.
 
+[0.2.5]: https://github.com/victorzhrn/ai-lcr/releases/tag/v0.2.5
 [0.2.3]: https://github.com/victorzhrn/ai-lcr/releases/tag/v0.2.3

package/README.md

@@ -156,7 +156,7 @@ Any OpenAI-compatible endpoint works — and so does any AI SDK provider package
 
 - **Model vendors' own APIs (native):** route straight to [DeepSeek](https://platform.deepseek.com), [OpenAI](https://openai.com), [Anthropic](https://anthropic.com), [Google](https://ai.google.dev), [xAI](https://x.ai), etc. via their AI SDK provider packages — no markup, full native features. See [Route to a model vendor's own API](#route-to-a-model-vendors-own-api-native-providers).
 - **Text aggregators:** [OpenRouter](https://openrouter.ai) (widest coverage, list pricing) · [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off** every model) · [TokenMart](https://thetokenmart.ai) (15–65% off, varies by model)
-- **Image / video:** [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off**) · [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — image routing available via `createMediaLCR` (Kunavo + Runware adapters); video on the roadmap
+- **Image / video:** [Kunavo](https://kunavo.com/?ref=victorimf) (**20% off**) · [TokenMart](https://thetokenmart.ai) · [fal.ai](https://fal.ai) · [Runware](https://runware.ai) — image routing available via `createMediaLCR` (Kunavo + Runware + fal adapters); video on the roadmap
 
 ## Text model pricing
 

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   classifyError: () => classifyError,
   classifyErrorKind: () => classifyErrorKind,
   comparePrices: () => comparePrices,
+  createFalMediaAdapter: () => createFalMediaAdapter,
   createKunavoMediaAdapter: () => createKunavoMediaAdapter,
   createLCR: () => createLCR,
   createMediaLCR: () => createMediaLCR,
@@ -57,43 +58,126 @@ 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"];
+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 = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
-  if (typeof status === "number" && AUTH_STATUS.has(status)) return "auth";
+  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;
@@ -162,6 +246,27 @@ var LcrFallbackModel = class {
   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() };
   }
@@ -181,14 +286,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,
@@ -203,7 +308,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,
@@ -238,7 +343,7 @@ 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);
       }
     }
@@ -274,7 +379,7 @@ 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);
         tried++;
         if (tried >= n) {
@@ -310,7 +415,7 @@ var LcrFallbackModel = class {
           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) {
             const nextTried = triedBeforeServing + 1;
@@ -434,6 +539,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) {
@@ -444,7 +567,7 @@ function createMediaLCR(config) {
     const startedAt = Date.now();
     const attempts = [];
     let lastErr;
-    const emitFail = () => onCall?.({
+    const emitFail = () => safeCall({
       id: newMediaCallId(),
       model: modelId,
       attempts,
@@ -466,8 +589,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,
@@ -489,7 +612,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;
@@ -779,6 +902,63 @@ var RunwareMediaError = class extends Error {
   status;
 };
 
+// src/adapters/fal-media.ts
+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("; ");
+  }
+  return body.error || body.message || "unknown";
+}
+function createFalMediaAdapter(config) {
+  const { apiKey, baseUrl = DEFAULT_BASE3, fetchImpl = fetch } = config;
+  return {
+    provider: "fal",
+    async run(req) {
+      const res = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Key ${apiKey}`,
+          accept: "application/json"
+        },
+        body: JSON.stringify(req.input)
+      });
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        body = {};
+      }
+      if (!res.ok) {
+        throw new FalMediaError(res.status, errorMessage2(body));
+      }
+      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 };
+    }
+  };
+}
+var FalMediaError = class extends Error {
+  constructor(status, body) {
+    super(`fal media HTTP ${status}: ${body.slice(0, 300)}`);
+    this.status = status;
+    this.name = "FalMediaError";
+  }
+  status;
+};
+
 // src/index.ts
 function isLanguageModel(entry) {
   return typeof entry.doGenerate === "function";
@@ -827,6 +1007,7 @@ function createLCR(config) {
   classifyError,
   classifyErrorKind,
   comparePrices,
+  createFalMediaAdapter,
   createKunavoMediaAdapter,
   createLCR,
   createMediaLCR,

package/dist/index.d.cts

@@ -358,6 +358,41 @@ interface RunwareMediaConfig {
 }
 declare function createRunwareMediaAdapter(config: RunwareMediaConfig): MediaAdapter;
 
+/**
+ * fal.ai media adapter — image generation (synchronous).
+ *
+ * fal exposes every model at `https://fal.run/<model-id>` (the synchronous API):
+ * POST the model's inputs as a flat JSON body, get the result back in the same
+ * response. This adapter passes the caller's `input` straight through, so any
+ * fal image model and any of its parameters (prompt, image_size, num_images,
+ * image_url for i2i/edit, …) work without this adapter knowing about them — it
+ * stays generic, not tied to one model family.
+ *
+ * Auth: fal uses `Authorization: Key <FAL_KEY>` (NOT a Bearer token).
+ *
+ * Errors: fal returns a proper HTTP status — 401 (bad key), 403 (insufficient
+ * balance / no permission), 422 (bad input), 429 (rate limit), 5xx. We surface
+ * the status on the thrown error so the router's `isRetryableError` can decide
+ * whether to fail over. A 403 "exhausted balance" is retryable (fall over to the
+ * next provider); a 422 bad-input is not (don't waste the fallbacks).
+ *
+ * Cost: the synchronous response does NOT carry a per-call price (fal billing is
+ * a separate account-level API), so `costCents` stays undefined and the router
+ * falls back to its normalized estimate — same contract as the Kunavo adapter.
+ *
+ * Video: fal video (e.g. veo3.1) is a long-running queue job, a different code
+ * path — out of scope here, like the Runware adapter. Image inference only.
+ */
+
+interface FalMediaConfig {
+    apiKey: string;
+    /** Override for testing. Defaults to https://fal.run. */
+    baseUrl?: string;
+    /** Injected for testing; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+declare function createFalMediaAdapter(config: FalMediaConfig): MediaAdapter;
+
 /**
  * ai-lcr — Least Cost Routing for LLMs.
  *
@@ -411,4 +446,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };
+export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };

package/dist/index.d.ts

@@ -358,6 +358,41 @@ interface RunwareMediaConfig {
 }
 declare function createRunwareMediaAdapter(config: RunwareMediaConfig): MediaAdapter;
 
+/**
+ * fal.ai media adapter — image generation (synchronous).
+ *
+ * fal exposes every model at `https://fal.run/<model-id>` (the synchronous API):
+ * POST the model's inputs as a flat JSON body, get the result back in the same
+ * response. This adapter passes the caller's `input` straight through, so any
+ * fal image model and any of its parameters (prompt, image_size, num_images,
+ * image_url for i2i/edit, …) work without this adapter knowing about them — it
+ * stays generic, not tied to one model family.
+ *
+ * Auth: fal uses `Authorization: Key <FAL_KEY>` (NOT a Bearer token).
+ *
+ * Errors: fal returns a proper HTTP status — 401 (bad key), 403 (insufficient
+ * balance / no permission), 422 (bad input), 429 (rate limit), 5xx. We surface
+ * the status on the thrown error so the router's `isRetryableError` can decide
+ * whether to fail over. A 403 "exhausted balance" is retryable (fall over to the
+ * next provider); a 422 bad-input is not (don't waste the fallbacks).
+ *
+ * Cost: the synchronous response does NOT carry a per-call price (fal billing is
+ * a separate account-level API), so `costCents` stays undefined and the router
+ * falls back to its normalized estimate — same contract as the Kunavo adapter.
+ *
+ * Video: fal video (e.g. veo3.1) is a long-running queue job, a different code
+ * path — out of scope here, like the Runware adapter. Image inference only.
+ */
+
+interface FalMediaConfig {
+    apiKey: string;
+    /** Override for testing. Defaults to https://fal.run. */
+    baseUrl?: string;
+    /** Injected for testing; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+declare function createFalMediaAdapter(config: FalMediaConfig): MediaAdapter;
+
 /**
  * ai-lcr — Least Cost Routing for LLMs.
  *
@@ -411,4 +446,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };
+export { type CallRecord, type CostEvent, DEFAULT_REFERENCE, type ErrorKind, type FormatOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaUnit, type PriceComparisonRow, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createFalMediaAdapter, createKunavoMediaAdapter, createLCR, createMediaLCR, createRunwareMediaAdapter, formatCallRecord, normalizedCents, rankRoutes, referenceMegapixels };

package/dist/index.js

@@ -18,43 +18,126 @@ 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"];
+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 = (e?.message ? String(e.message) : safeStringify(error)).toLowerCase();
-  if (typeof status === "number" && AUTH_STATUS.has(status)) return "auth";
+  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;
@@ -123,6 +206,27 @@ var LcrFallbackModel = class {
   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() };
   }
@@ -142,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,
@@ -164,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,
@@ -199,7 +303,7 @@ 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);
       }
     }
@@ -235,7 +339,7 @@ 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);
         tried++;
         if (tried >= n) {
@@ -271,7 +375,7 @@ var LcrFallbackModel = class {
           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) {
             const nextTried = triedBeforeServing + 1;
@@ -395,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) {
@@ -405,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,
@@ -427,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,
@@ -450,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;
@@ -740,6 +862,63 @@ var RunwareMediaError = class extends Error {
   status;
 };
 
+// src/adapters/fal-media.ts
+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("; ");
+  }
+  return body.error || body.message || "unknown";
+}
+function createFalMediaAdapter(config) {
+  const { apiKey, baseUrl = DEFAULT_BASE3, fetchImpl = fetch } = config;
+  return {
+    provider: "fal",
+    async run(req) {
+      const res = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Key ${apiKey}`,
+          accept: "application/json"
+        },
+        body: JSON.stringify(req.input)
+      });
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        body = {};
+      }
+      if (!res.ok) {
+        throw new FalMediaError(res.status, errorMessage2(body));
+      }
+      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 };
+    }
+  };
+}
+var FalMediaError = class extends Error {
+  constructor(status, body) {
+    super(`fal media HTTP ${status}: ${body.slice(0, 300)}`);
+    this.status = status;
+    this.name = "FalMediaError";
+  }
+  status;
+};
+
 // src/index.ts
 function isLanguageModel(entry) {
   return typeof entry.doGenerate === "function";
@@ -787,6 +966,7 @@ export {
   classifyError,
   classifyErrorKind,
   comparePrices,
+  createFalMediaAdapter,
   createKunavoMediaAdapter,
   createLCR,
   createMediaLCR,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.2.3",
+  "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",