@sprqvntrs/llm 3.13.1 → 3.14.0

package/README.md

@@ -95,6 +95,7 @@ const client = LLM.getClient(provider, model, options?);
   debug?: boolean;                  // Enable debug logging
   useReasoningMode?: boolean;       // Enable reasoning endpoints (OpenAI only)
   openaiApiKey?: string;            // OpenAI key for Anthropic formatting
+  baseUrl?: string;                 // OpenRouter endpoint (OpenRouter only), see "OpenRouter endpoints"
 }
 ```
 
@@ -247,6 +248,66 @@ try {
 }
 ```
 
+## OpenRouter endpoints
+
+The OpenRouter client can talk to two hosts:
+
+| Host | Base URL | Use |
+|------|----------|-----|
+| Global (default) | `https://openrouter.ai/api/v1` | All models |
+| EU in-region | `https://eu.openrouter.ai/api/v1` | OpenRouter Business. Fails closed and routes only to EU endpoints. |
+
+Pick the host with the `baseUrl` option or the `OPENROUTER_BASE_URL` environment variable.
+The order is: the `baseUrl` option, then `OPENROUTER_BASE_URL`, then the global default.
+
+```typescript
+import { LLM, OpenRouterClient, EU_OPENROUTER_BASE_URL } from '@sprqvntrs/llm';
+
+// Through the factory (or set OPENROUTER_BASE_URL=https://eu.openrouter.ai/api/v1)
+const client = LLM.getClient('openrouter', 'openai/gpt-4o-mini', {
+  baseUrl: EU_OPENROUTER_BASE_URL,
+});
+
+// Or directly. The resolved value is exposed read-only, for logging.
+const direct = new OpenRouterClient({ apiKey, model: 'openai/gpt-4o-mini', baseUrl: EU_OPENROUTER_BASE_URL });
+direct.baseUrl; // 'https://eu.openrouter.ai/api/v1'
+```
+
+The OpenAI and Anthropic clients ignore `baseUrl`.
+
+### Validation
+
+The value fails closed. The client throws at construction, and the message names the offending
+value (never the API key), when the value is not all of these:
+
+- a URL with the `https:` protocol
+- a host that is exactly `openrouter.ai` or ends with `.openrouter.ai`
+- free of credentials, a port, a query and a fragment
+- on the path `/api/v1` (one trailing slash is accepted and stripped)
+
+An empty string is also rejected. It never falls back to the global host.
+
+Apps can check their configuration at boot with the same validator:
+
+```typescript
+import { resolveOpenRouterBaseUrl } from '@sprqvntrs/llm';
+
+// Throws on a bad value. Returns the normalised URL otherwise.
+const baseUrl = resolveOpenRouterBaseUrl(config.openrouterBaseUrl); // falls back to process.env, then the default
+```
+
+Signature: `resolveOpenRouterBaseUrl(explicit?: string, env?: NodeJS.ProcessEnv): string`.
+
+### What changes on the EU host
+
+- **Fewer models.** The EU host lacks some models. For example there is no Gemini 3.7 or 3.8 Flash,
+  and no preview models. `openai/gpt-5.4-mini` has zero data retention (ZDR) endpoints only on Azure US.
+- **Price.** The EU host carries about a 10 percent surcharge.
+- **Missing model means HTTP 404.** A model with no endpoint on the chosen host fails with
+  HTTP 404 and the message "no endpoints available". Retrying never helps. Treat it as a
+  **configuration error** (wrong model for this host), not as a retryable error. Check the model
+  list for the host before you switch.
+
 ## Helper Functions
 
 ### isContentInLanguage()

package/index.ts

@@ -49,5 +49,11 @@ export {
 } from './src/helpers';
 
 // Response normalization utilities
+export {
+  resolveOpenRouterBaseUrl,
+  DEFAULT_OPENROUTER_BASE_URL,
+  EU_OPENROUTER_BASE_URL,
+  OPENROUTER_BASE_URL_ENV,
+} from './src/utils/openrouter-base-url';
 export { stripJsonArtifacts } from './src/utils/strip-json-artifacts';
 export type { SanitizationResult } from './src/utils/strip-json-artifacts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprqvntrs/llm",
-  "version": "3.13.1",
+  "version": "3.14.0",
   "type": "module",
   "main": "./index.ts",
   "types": "./index.ts",

package/src/clients/openrouter-client.ts

@@ -19,6 +19,7 @@ import {
   type LlmErrorContext,
 } from '../utils/errors';
 import { normalizeNullStrings } from '../utils/normalize-null-strings';
+import { resolveOpenRouterBaseUrl } from '../utils/openrouter-base-url';
 import { resolveRefs } from '../utils/resolve-refs';
 import { stripJsonArtifacts } from '../utils/strip-json-artifacts';
 
@@ -76,6 +77,16 @@ export interface OpenRouterClientConfig extends Omit<BaseLlmClientConfig, 'model
    * This parameter is kept for backward compatibility but has no effect.
    */
   openaiApiKey?: string;
+
+  /**
+   * OpenRouter endpoint. Resolution order: this option, then the `OPENROUTER_BASE_URL`
+   * environment variable, then `https://openrouter.ai/api/v1`.
+   *
+   * Must be `https://openrouter.ai/api/v1` or `https://<sub>.openrouter.ai/api/v1`
+   * (for example the EU host `https://eu.openrouter.ai/api/v1`). Anything else throws.
+   * See `resolveOpenRouterBaseUrl`.
+   */
+  baseUrl?: string;
 }
 
 /**
@@ -101,6 +112,9 @@ export class OpenRouterClient implements LlmClientInterface {
   private retryConfig: OpenRouterRetryConfig;
   private _lastUsage: LlmTokenUsage | null = null;
 
+  /** The validated endpoint this client talks to, without a trailing slash. Read-only. */
+  readonly baseUrl: string;
+
   get lastUsage(): LlmTokenUsage | null {
     return this._lastUsage;
   }
@@ -109,9 +123,10 @@ export class OpenRouterClient implements LlmClientInterface {
    * Creates a new OpenRouterClient instance
    *
    * @param config Configuration options
-   * @throws Error if the API key is not configured
+   * @throws Error if the base URL is invalid (see `resolveOpenRouterBaseUrl`)
    */
   constructor(config: OpenRouterClientConfig) {
+    this.baseUrl = resolveOpenRouterBaseUrl(config.baseUrl);
     // Use config timeout or default to 120 seconds (2 minutes)
     // OpenRouter acts as a proxy, so we use a more conservative default
     this.timeout = config.timeout ?? 120000;
@@ -126,6 +141,7 @@ export class OpenRouterClient implements LlmClientInterface {
 
     this.client = new OpenRouter({
       apiKey: config.apiKey,
+      serverURL: this.baseUrl,
       timeoutMs: this.timeout,
       retryConfig: this.retryConfig,
     });

package/src/llm.ts

@@ -24,6 +24,13 @@ export type LlmClientOptions = {
    * If provided, these clients will use OpenAI for reliable structured output formatting.
    */
   openaiApiKey?: string;
+  /**
+   * OpenRouter endpoint (OpenRouter only). Falls back to the `OPENROUTER_BASE_URL`
+   * environment variable, then `https://openrouter.ai/api/v1`. Must be an
+   * `openrouter.ai` host with the path `/api/v1`, for example the EU host
+   * `https://eu.openrouter.ai/api/v1`. Any other value throws.
+   */
+  baseUrl?: string;
 };
 
 /**
@@ -101,6 +108,7 @@ export class LLM {
       apiKey,
       model,
       openaiApiKey: options?.openaiApiKey,
+      baseUrl: options?.baseUrl,
       debug: options?.debug,
     });
   }

package/src/utils/openrouter-base-url.ts

@@ -0,0 +1,71 @@
+/** Global OpenRouter endpoint. Used when no base URL is configured. */
+export const DEFAULT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+
+/** EU in-region OpenRouter endpoint (OpenRouter Business, fails closed, EU endpoints only). */
+export const EU_OPENROUTER_BASE_URL = 'https://eu.openrouter.ai/api/v1';
+
+/** Environment variable read when no explicit `baseUrl` is given. */
+export const OPENROUTER_BASE_URL_ENV = 'OPENROUTER_BASE_URL';
+
+const REQUIRED_PATH = '/api/v1';
+const ROOT_HOST = 'openrouter.ai';
+
+/** Hides userinfo (`user:pass@`) so a credential never reaches an error message. */
+function redact(raw: string): string {
+  return raw.replace(/\/\/[^/?#]*@/, '//***@');
+}
+
+function reject(raw: string, source: string, reason: string): never {
+  throw new Error(`Invalid OpenRouter base URL ${JSON.stringify(redact(raw))} (from ${source}): ${reason}`);
+}
+
+function validate(raw: string, source: string): string {
+  const trimmed = raw.trim();
+  if (trimmed === '') reject(raw, source, 'the value is empty');
+
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return reject(raw, source, 'it is not a valid URL');
+  }
+
+  if (url.protocol !== 'https:') reject(raw, source, 'the protocol must be https');
+  if (url.hostname !== ROOT_HOST && !url.hostname.endsWith(`.${ROOT_HOST}`)) {
+    reject(raw, source, `the host must be ${ROOT_HOST} or a subdomain of it`);
+  }
+  if (url.username !== '' || url.password !== '') reject(raw, source, 'credentials in the URL are not allowed');
+  if (url.port !== '') reject(raw, source, 'a port is not allowed');
+  if (url.pathname !== REQUIRED_PATH && url.pathname !== `${REQUIRED_PATH}/`) {
+    reject(raw, source, `the path must be ${REQUIRED_PATH}`);
+  }
+  if (url.search !== '' || url.hash !== '') reject(raw, source, 'a query or fragment is not allowed');
+
+  // Catch-all: the parser normalises away a default port (:443), an empty "?" or "#" and other
+  // oddities. The only accepted input is the canonical form, with at most one trailing slash.
+  const canonical = `https://${url.hostname}${REQUIRED_PATH}`;
+  const withoutSlash = trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+  if (withoutSlash.toLowerCase() !== canonical) {
+    reject(raw, source, `the value must be exactly ${canonical}`);
+  }
+  return canonical;
+}
+
+/**
+ * Resolves and validates the OpenRouter base URL. Fails closed.
+ *
+ * Order: the explicit value, then `OPENROUTER_BASE_URL`, then the global default. An empty string
+ * counts as a value and is rejected, so a blank setting cannot silently fall back to the global host.
+ *
+ * Accepted: `https://openrouter.ai/api/v1` and `https://<sub>.openrouter.ai/api/v1`, with an optional
+ * trailing slash (stripped). Anything else throws, and the message names the offending value but
+ * never an API key.
+ *
+ * Apps can call this at boot to check their configuration.
+ */
+export function resolveOpenRouterBaseUrl(explicit?: string, env: NodeJS.ProcessEnv = process.env): string {
+  if (explicit !== undefined) return validate(explicit, 'the baseUrl option');
+  const fromEnv = env[OPENROUTER_BASE_URL_ENV];
+  if (fromEnv !== undefined) return validate(fromEnv, `the ${OPENROUTER_BASE_URL_ENV} environment variable`);
+  return DEFAULT_OPENROUTER_BASE_URL;
+}