@x12i/openrouter-runtime 1.0.3 → 1.0.4

package/dist/index.cjs

@@ -32,6 +32,7 @@ module.exports = __toCommonJS(index_exports);
 function resolveRuntimeOptions(options) {
   return {
     ...options,
+    apiKey: options.apiKey ?? readOpenRouterApiKeyFromEnv() ?? "",
     baseUrl: options.baseUrl ?? "https://openrouter.ai/api/v1",
     defaultHeaders: options.defaultHeaders ?? {},
     fetch: options.fetch ?? globalThis.fetch
@@ -59,6 +60,10 @@ function resolveDefaults(options) {
     }
   };
 }
+function readOpenRouterApiKeyFromEnv() {
+  const env = typeof process === "undefined" ? void 0 : process.env;
+  return env?.OPENROUTER_API_KEY || env?.OPEN_ROUTER_KEY;
+}
 
 // src/openrouter/errors.ts
 var RuntimeConfigError = class extends Error {
@@ -72,18 +77,20 @@ var RuntimeConfigError = class extends Error {
   details;
 };
 var OpenRouterHttpError = class extends Error {
-  constructor(status, code, message, body, retryable = false) {
+  constructor(status, code, message, body, retryable = false, providerAttempts = []) {
     super(message);
     this.status = status;
     this.code = code;
     this.body = body;
     this.retryable = retryable;
+    this.providerAttempts = providerAttempts;
     this.name = "OpenRouterHttpError";
   }
   status;
   code;
   body;
   retryable;
+  providerAttempts;
 };
 
 // src/utils/delay.ts
@@ -100,13 +107,35 @@ function retryDelay(attempt, baseDelayMs, maxDelayMs) {
 async function sendOpenRouterRequest(compiled, options, defaults, timeoutMs) {
   const attempts = defaults.retry.enabled ? defaults.retry.maxAttempts : 1;
   let lastError;
+  const providerAttempts = [];
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
       return await sendOnce(compiled, options, timeoutMs);
     } catch (error) {
       lastError = error;
+      if (error instanceof OpenRouterHttpError) {
+        const providerAttempt = toProviderAttempt(error, compiled);
+        providerAttempts.push(providerAttempt);
+        options.logger?.warn?.("openrouter.provider_attempt.failed", {
+          ...providerAttempt,
+          attempt,
+          maxAttempts: attempts
+        });
+      }
       const retryable = error instanceof OpenRouterHttpError ? error.retryable : true;
-      if (!retryable || attempt >= attempts) throw error;
+      if (!retryable || attempt >= attempts) {
+        if (error instanceof OpenRouterHttpError) {
+          throw new OpenRouterHttpError(
+            error.status,
+            error.code,
+            error.message,
+            error.body,
+            error.retryable,
+            providerAttempts
+          );
+        }
+        throw error;
+      }
       await delay(retryDelay(attempt, defaults.retry.baseDelayMs, defaults.retry.maxDelayMs));
     }
   }
@@ -125,10 +154,11 @@ async function sendOnce(compiled, options, timeoutMs) {
     const text = await response.text();
     const body = text ? parseBody(text) : void 0;
     if (!response.ok) {
+      const message = extractMessage(body) ?? `OpenRouter request failed with status ${response.status}.`;
       throw new OpenRouterHttpError(
         response.status,
-        statusToCode(response.status),
-        extractMessage(body) ?? `OpenRouter request failed with status ${response.status}.`,
+        classifyProviderFailure(response.status, message, body),
+        message,
         body,
         isRetryableStatus(response.status)
       );
@@ -137,9 +167,15 @@ async function sendOnce(compiled, options, timeoutMs) {
   } catch (error) {
     if (error instanceof OpenRouterHttpError) throw error;
     if (error instanceof Error && error.name === "AbortError") {
-      throw new OpenRouterHttpError(408, "OPENROUTER_TIMEOUT", "OpenRouter request timed out.", void 0, true);
+      throw new OpenRouterHttpError(408, "PROVIDER_GATEWAY_UNREACHABLE", "OpenRouter request timed out.", void 0, true);
     }
-    throw error;
+    throw new OpenRouterHttpError(
+      503,
+      "PROVIDER_GATEWAY_UNREACHABLE",
+      error instanceof Error ? error.message : "OpenRouter request failed before receiving a response.",
+      void 0,
+      true
+    );
   } finally {
     clearTimeout(timeout);
   }
@@ -160,10 +196,31 @@ function extractMessage(body) {
   }
   return typeof record.message === "string" ? record.message : void 0;
 }
-function statusToCode(status) {
-  if (status === 401) return "OPENROUTER_AUTH_FAILED";
-  if (status === 429) return "OPENROUTER_RATE_LIMITED";
-  return "OPENROUTER_REQUEST_FAILED";
+function toProviderAttempt(error, compiled) {
+  const modelId = typeof compiled.body.model === "string" ? compiled.body.model : void 0;
+  return {
+    provider: "openrouter",
+    ...modelId ? { modelId } : {},
+    httpStatus: error.status,
+    code: error.code,
+    message: error.message,
+    retryable: error.retryable
+  };
+}
+function classifyProviderFailure(status, message, body) {
+  const haystack = `${message} ${JSON.stringify(body ?? "")}`.toLowerCase();
+  if (status === 401 || status === 403) return "PROVIDER_AUTH_FAILED";
+  if (status === 402 || mentionsQuota(haystack)) return "PROVIDER_QUOTA_EXCEEDED";
+  if (status === 404 || mentionsMissingModel(haystack)) return "PROVIDER_MODEL_NOT_FOUND";
+  if (status === 429) return "PROVIDER_RATE_LIMITED";
+  if (status === 408 || status >= 500) return "PROVIDER_GATEWAY_UNREACHABLE";
+  return "PROVIDER_REQUEST_FAILED";
+}
+function mentionsQuota(text) {
+  return /\b(quota|credit|credits|billing|balance|insufficient funds|insufficient credit)\b/.test(text);
+}
+function mentionsMissingModel(text) {
+  return /\bmodel\b.*\b(not found|not a valid|invalid|unavailable)\b/.test(text) || /\b(no endpoints found|not a valid model id)\b/.test(text);
 }
 function isRetryableStatus(status) {
   return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
@@ -1304,6 +1361,7 @@ function normalizeError(error) {
       code: error.code,
       message: error.message,
       source: "validation",
+      ...optionalErrorField("operatorHint", operatorHintFor(error.code)),
       details: error.details
     };
   }
@@ -1313,7 +1371,11 @@ function normalizeError(error) {
       message: error.message,
       source: "openrouter",
       retryable: error.retryable,
-      details: error.body
+      ...optionalErrorField("operatorHint", operatorHintFor(error.code)),
+      details: {
+        providerAttempts: error.providerAttempts,
+        ...error.body === void 0 ? {} : { response: error.body }
+      }
     };
   }
   return {
@@ -1322,6 +1384,27 @@ function normalizeError(error) {
     source: "runtime"
   };
 }
+function optionalErrorField(key, value) {
+  return value === void 0 ? {} : { [key]: value };
+}
+function operatorHintFor(code) {
+  switch (code) {
+    case "OPENROUTER_API_KEY_MISSING":
+      return "Set OPENROUTER_API_KEY or OPEN_ROUTER_KEY, or pass apiKey when creating the runtime.";
+    case "PROVIDER_AUTH_FAILED":
+      return "Check that the OpenRouter API key is present, valid, and authorized for this route.";
+    case "PROVIDER_RATE_LIMITED":
+      return "Retry after the provider rate limit resets or reduce request concurrency.";
+    case "PROVIDER_QUOTA_EXCEEDED":
+      return "Check provider billing, credits, quota, and project limits.";
+    case "PROVIDER_MODEL_NOT_FOUND":
+      return "Verify the model id and whether it is available through OpenRouter for this account.";
+    case "PROVIDER_GATEWAY_UNREACHABLE":
+      return "Retry later; the provider gateway was unreachable or timed out.";
+    default:
+      return void 0;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   OpenRouterHttpError,