@absolutejs/ai 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -6,12 +6,15 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
-## 0.6.3 — 2026-10-22
+## 0.6.4 — 2026-10-22
+
+### Added
+
+- **Stream approved fallback models before output or tool execution** (`streamWithProviderFallback`)
 
 ### Changed
 
-- **Accepts @absolutejs/sync 3**
-  The `@absolutejs/sync` peer range stopped below 3, so an app on sync 3 (built against Elysia 2.0.0-rc.0) installed a second copy for ai. sync 3.0.0 changed no API, so the range now runs from 2.14.0 below 4.
+- **Expose provider billing rejection and credential-scoped suppression** (`ProviderError`, `ProviderErrorInit`)
 
 ## 0.6.2 — 2026-10-22
 

package/README.md

@@ -590,3 +590,6 @@ progress/CTA semantics. A funding pause offers Add credits; only confirmed
 funding changes it to Continue research. Completed work offers View results;
 uncertain work offers Check status, never replay. The host persists the work ID,
 polls or subscribes to actual progress, and binds actions to authenticated routes.
+
+
+`streamWithProviderFallback` accepts approved model IDs, an individually metered `stream(model)` callback, and an optional `onFallback` hook. It never restarts after a chunk or caller cancellation. `ProviderError.billingUnavailable` identifies provider billing failures; `notSent` identifies requests blocked locally. Billing suppression is scoped to the configured provider instance, with a five-minute probe interval.

package/changelog.json

@@ -5,13 +5,23 @@
 		{
 			"changes": [
 				{
-					"detail": "The `@absolutejs/sync` peer range stopped below 3, so an app on sync 3 (built against Elysia 2.0.0-rc.0) installed a second copy for ai. sync 3.0.0 changed no API, so the range now runs from 2.14.0 below 4.",
 					"kind": "changed",
-					"summary": "Accepts @absolutejs/sync 3"
+					"summary": "Expose provider billing rejection and credential-scoped suppression",
+					"symbols": [
+						"ProviderError",
+						"ProviderErrorInit"
+					]
+				},
+				{
+					"kind": "added",
+					"summary": "Stream approved fallback models before output or tool execution",
+					"symbols": [
+						"streamWithProviderFallback"
+					]
 				}
 			],
 			"date": "2026-10-22",
-			"version": "0.6.3"
+			"version": "0.6.4"
 		},
 		{
 			"changes": [

package/dist/ai/index.js

@@ -2233,12 +2233,21 @@ var CONNECTION_ERROR_PATTERNS = [
 ];
 var isAbortError = (err) => err instanceof Error && (err.name === "AbortError" || /\babort(ed)?\b/i.test(err.message));
 var providerStatusPage = (provider) => PROVIDER_STATUS_PAGES[provider] ?? null;
+var BILLING_ERROR_TYPES = new Set([
+  "credit_balance_exhausted",
+  "insufficient_quota",
+  "billing_hard_limit_reached",
+  "billing_not_active",
+  "insufficient_credits"
+]);
 
 class ProviderError extends Error {
   provider;
   status;
   type;
   retryable;
+  billingUnavailable;
+  notSent;
   metadata;
   statusPageUrl;
   constructor(init) {
@@ -2246,8 +2255,10 @@ class ProviderError extends Error {
     this.name = "ProviderError";
     this.provider = init.provider;
     this.status = init.status ?? null;
-    this.type = init.type ?? null;
-    this.retryable = init.retryable;
+    this.type = init.type ?? (typeof init.metadata?.code === "string" ? init.metadata.code : typeof init.metadata?.type === "string" ? init.metadata.type : null);
+    this.billingUnavailable = BILLING_ERROR_TYPES.has(this.type ?? "") || init.status === 402;
+    this.notSent = init.notSent === true;
+    this.retryable = !this.billingUnavailable && init.retryable;
     this.metadata = init.metadata;
     this.statusPageUrl = providerStatusPage(init.provider);
   }
@@ -2332,6 +2343,7 @@ var errorPayload = (error) => {
     message: providerError.message,
     provider: providerError.provider,
     retryable: providerError.retryable,
+    notSent: providerError.notSent,
     status: providerError.status,
     type: providerError.type
   };
@@ -2446,6 +2458,7 @@ var parseRemoteStream = async function* (response) {
         const parsed = JSON.parse(data);
         if (event === "error") {
           throw new ProviderError({
+            notSent: "notSent" in parsed && parsed.notSent === true,
             message: "message" in parsed && typeof parsed.message === "string" ? parsed.message : "Remote provider stream failed",
             provider: "provider" in parsed && typeof parsed.provider === "string" ? parsed.provider : "remote",
             retryable: "retryable" in parsed && typeof parsed.retryable === "boolean" ? parsed.retryable : true,
@@ -4894,6 +4907,7 @@ var circuitOpen = (provider) => {
       message: `${provider} API is reported down${record.external.reason ? `: ${record.external.reason}` : ""}`,
       provider,
       retryable: true,
+      notSent: true,
       status: null,
       type: record.external.indicator
     });
@@ -4909,11 +4923,16 @@ var circuitOpen = (provider) => {
     message: `${provider} is temporarily unavailable (circuit open after ${record.consecutiveFailures} failures): ${detail}`,
     provider,
     retryable: true,
+    notSent: true,
     status: record.lastError?.status ?? null,
     type: record.lastError?.type ?? null
   });
 };
 var withResilience = (provider, providerName = "unknown") => {
+  let billingFailure = null;
+  let billingRetryAt = 0;
+  let billingProbe = false;
+  const billingCooldownMs = 5 * 60000;
   const attempt = async function* (params, attemptNo) {
     let yielded = false;
     try {
@@ -4921,9 +4940,16 @@ var withResilience = (provider, providerName = "unknown") => {
         yielded = true;
         yield chunk;
       }
+      billingFailure = null;
+      billingProbe = false;
       noteSuccess(providerName);
     } catch (err) {
       const providerError = ProviderError.from(err, providerName);
+      if (providerError.billingUnavailable) {
+        billingFailure = providerError;
+        billingRetryAt = Date.now() + billingCooldownMs;
+      }
+      billingProbe = false;
       const canRetry = !yielded && providerError.retryable && attemptNo < (params.maxRetries === undefined ? config.maxRetries : Math.max(0, Math.min(config.maxRetries, params.maxRetries))) && !params.signal?.aborted;
       if (canRetry) {
         await sleep(backoffDelay(attemptNo), params.signal);
@@ -4938,6 +4964,21 @@ var withResilience = (provider, providerName = "unknown") => {
   return {
     ...provider,
     stream: (params) => {
+      if (billingFailure && (Date.now() < billingRetryAt || billingProbe)) {
+        const failure = billingFailure;
+        return async function* () {
+          throw new ProviderError({
+            provider: providerName,
+            message: "Provider billing is unavailable",
+            type: failure.type,
+            status: failure.status,
+            retryable: false,
+            notSent: true
+          });
+        }();
+      }
+      if (billingFailure)
+        billingProbe = true;
       const tripped = circuitOpen(providerName);
       if (tripped) {
         return async function* () {
@@ -9228,6 +9269,29 @@ var createAIProviderRouter = (routes) => {
     stream: (params) => resolve(params).stream(params)
   };
 };
+// src/ai/providerFallback.ts
+async function* streamWithProviderFallback(options) {
+  const models = [...new Set(options.models)];
+  if (!models.length)
+    throw new Error("At least one approved model is required");
+  for (const [index, model] of models.entries()) {
+    options.signal?.throwIfAborted();
+    let emitted = false;
+    try {
+      for await (const chunk of options.stream(model)) {
+        emitted = true;
+        yield chunk;
+      }
+      return;
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      const next = models[index + 1];
+      if (emitted || !next || !(error instanceof ProviderError) || !(error.billingUnavailable || error.retryable || error.notSent))
+        throw error;
+      await options.onFallback?.({ from: model, to: next, error });
+    }
+  }
+}
 export {
   AIInputError,
   BUILTIN_UI_CARDS,
@@ -9339,6 +9403,7 @@ export {
   streamAIToSSE,
   streamAIWithTools,
   streamWithAIContext,
+  streamWithProviderFallback,
   tableCard,
   toolOutputText,
   verifyOpenRouterWebhookSignature,
@@ -9346,5 +9411,5 @@ export {
   xai
 };
 
-//# debugId=577984AE55403A4664756E2164756E21
+//# debugId=15DF9981B943EAAB64756E2164756E21
 //# sourceMappingURL=index.js.map