@pkent/aigateway 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pkent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# AIGateway
+
+A provider-neutral LLM client library. One class routes chat / vision /
+streaming requests to OpenAI, Anthropic, Qwen (Alibaba DashScope), GLM (Zhipu
+AI), or OpenRouter based on the model name, and normalizes every response into a
+single shape.
+
+No server, no `.env` — all configuration is passed into the constructor.
+
+## Install
+
+```bash
+npm install @pkent/aigateway
+```
+
+Requires Node.js 18+ (uses native ESM and async iterators). The package is
+ES-module only.
+
+## Quick start
+
+```js
+import AIGateway from '@pkent/aigateway';
+
+const g = new AIGateway('anthropic/claude-opus-4.8', process.env.ANTHROPIC_API_KEY);
+
+const res = await g.chat([{ role: 'user', content: 'Hello' }]);
+console.log(res.content[0].text);
+console.log(res.usage.total_tokens);
+```
+
+Models are addressed as **`<provider>/<model>`** (e.g. `anthropic/claude-opus-4.8`,
+`openai/gpt-4o`). The leading provider segment selects the provider; the rest is
+the model id sent upstream.
+
+One instance is bound to one model and one API key. To use a different model,
+construct another instance.
+
+## Constructor
+
+```js
+new AIGateway(model, key, options?)
+```
+
+- **`model`** *(string, required)* — `<provider>/<model>`. The provider segment
+  selects the provider (see the [routing table](#model-routing)); an unknown or
+  missing segment throws `AIGatewayError` (`code: 'unsupported_model'`).
+- **`key`** *(string, required)* — the API key for the resolved provider.
+- **`options`** *(object, optional)*:
+
+| Option      | Type   | Applies to      | Default          | Description |
+|-------------|--------|-----------------|------------------|-------------|
+| `baseURL`   | string | all             | provider default | Override the upstream endpoint (regional endpoints, proxies, self-hosted). |
+| `maxTokens` | number | all             | unset (see below)| Default max output tokens; a per-call `maxTokens` overrides it. |
+| `referer`   | string | OpenRouter only | omitted          | Sent as the `HTTP-Referer` attribution header. |
+| `title`     | string | OpenRouter only | omitted          | Sent as the `X-Title` attribution header. |
+| `client`    | object | advanced        | —                | Inject a pre-built SDK client (or a compatible fake for testing). When set, `key`/`baseURL`/`referer`/`title` are not used to build a client. |
+
+The constructor performs **no** network calls and throws `AIGatewayError` for an
+invalid `model` (`code: 'invalid_model'`) or missing `key`
+(`code: 'invalid_api_key'`, unless a `client` is injected).
+
+### Read-only properties & discovery
+
+```js
+g.model            // the bound model string, e.g. 'anthropic/claude-opus-4.8'
+g.provider         // resolved provider id, e.g. 'anthropic'
+AIGateway.providers()
+// => [
+//   { id: 'openrouter', prefix: 'openrouter/' },
+//   { id: 'anthropic',  prefix: 'anthropic/' },
+//   { id: 'qwen',       prefix: 'qwen/' },
+//   { id: 'glm',        prefix: 'glm/' },
+//   { id: 'openai',     prefix: 'openai/' }
+// ]
+```
+
+## Methods
+
+### `await g.chat(messages, options?)`
+### `await g.vision(messages, options?)`
+
+`vision` is `chat` with image content blocks in `messages`. Both return the
+[v2 response shape](#response-shape). `options` may include `temperature`,
+`maxTokens`, and `responseFormat` (mapped to OpenAI-compatible `response_format`;
+ignored by Anthropic).
+
+```js
+const g = new AIGateway('openai/gpt-4o', OPENAI_KEY);
+const res = await g.vision([
+  {
+    role: 'user',
+    content: [
+      { type: 'text', text: 'What is in this image?' },
+      { type: 'image_url', image_url: { url: 'https://example.com/cat.png' } },
+    ],
+  },
+], { temperature: 0.2 });
+```
+
+### `g.stream(messages, options?)`
+
+Returns a `ChatStream` (not a promise). It is async-iterable — yielding
+`{ type: 'text_delta', text }` deltas — and exposes a `.final` promise that
+resolves to the full response once streaming completes.
+
+```js
+const stream = g.stream([{ role: 'user', content: 'Write a haiku' }], { temperature: 0.7 });
+
+for await (const delta of stream) {
+  process.stdout.write(delta.text);
+}
+
+const final = await stream.final;
+console.log('\n', final.stop_reason, final.usage);
+```
+
+If the upstream errors, the iterator throws and `.final` rejects with the same
+error. You may await `.final` without iterating (deltas buffer in memory), or
+iterate without awaiting `.final`.
+
+## Model routing
+
+Every model is addressed as `<provider>/<model>`. The leading provider segment
+selects the provider and is stripped before the upstream call. There is no
+catch-all — an unknown or missing segment throws `AIGatewayError`
+(`code: 'unsupported_model'`).
+
+| Model id                       | Provider     | Upstream model | Notes |
+|--------------------------------|--------------|----------------|-------|
+| `anthropic/<model>`            | `anthropic`  | `<model>`      | Anthropic SDK. |
+| `openai/<model>`               | `openai`     | `<model>`      | OpenAI-compatible. |
+| `qwen/<model>`                 | `qwen`       | `<model>`      | OpenAI-compatible. Default base URL `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`. |
+| `glm/<model>`                  | `glm`        | `<model>`      | OpenAI-compatible. Default base URL `https://open.bigmodel.cn/api/paas/v4`. |
+| `openrouter/<vendor>/<model>`  | `openrouter` | `<vendor>/<model>` | Only the `openrouter/` segment is stripped, leaving OpenRouter's native id. Default base URL `https://openrouter.ai/api/v1`. |
+
+OpenRouter is opt-in: send `openrouter/anthropic/claude-opus-4.8` to route
+through OpenRouter, or `anthropic/claude-opus-4.8` to hit Anthropic directly.
+
+**Adding a provider:** drop a module into [src/providers/](src/providers/)
+exporting `{ id, prefix, matches, create }` (where `matches` tests the
+`<id>/` segment) and register it in
+[src/providers/registry.js](src/providers/registry.js). `create(config)` returns
+`{ id, chat, vision, stream }`.
+
+## Response shape
+
+```json
+{
+  "id": "msg_01ABCXYZ",
+  "object": "response",
+  "created": 1776675600,
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-5",
+  "role": "assistant",
+  "stop_reason": "end_turn",
+  "content": [{ "type": "text", "text": "Hello! How can I help you today?" }],
+  "usage": {
+    "input_tokens": 10,
+    "output_tokens": 9,
+    "total_tokens": 19,
+    "cached_input_tokens": 6,
+    "cache_creation_input_tokens": 0,
+    "cache_read_input_tokens": 6
+  }
+}
+```
+
+Cache-related `usage` fields are optional and only present when the upstream
+provider reports them.
+
+## Cache hints
+
+Request content blocks may include a provider-neutral cache hint:
+
+- `cache: true` — prefer caching this stable block.
+- `cache: false` or omission — no cache hint.
+
+Mapping:
+- **Anthropic** — `cache: true` on a text block becomes `cache_control`.
+- **OpenAI-compatible providers** — the hint is accepted but stripped before the
+  upstream request, so caller intent is preserved without breaking compatibility.
+
+```js
+await g.chat([
+  {
+    role: 'system',
+    content: [
+      { type: 'text', text: 'Core instructions', cache: true },
+      { type: 'text', text: 'Output valid JSON', cache: true },
+    ],
+  },
+  { role: 'user', content: [{ type: 'text', text: 'Live request data' }] },
+]);
+```
+
+## `maxTokens` behavior
+
+`maxTokens` defaults to **unset**, which preserves each provider's native
+behavior:
+
+- **Anthropic** requires `max_tokens`, so it falls back to `4096` when none is
+  supplied.
+- **OpenAI-compatible providers** do not require a cap, so none is sent — output
+  is not truncated by the library.
+
+Supply `maxTokens` (in the constructor or per call) to apply a cap to every
+provider. A per-call value overrides the constructor default.
+
+## Errors
+
+- **Input errors** (invalid model/key/messages) throw `AIGatewayError` with a
+  `code` (`invalid_model`, `unsupported_model`, `invalid_api_key`,
+  `invalid_messages`, `invalid_message`, `invalid_message_role`,
+  `invalid_message_content`).
+- **Upstream/provider errors** propagate as the underlying SDK error — `chat` /
+  `vision` reject; `stream` throws on the iterator and rejects `.final`.
+
+```js
+import AIGateway, { AIGatewayError } from '@pkent/aigateway';
+
+try {
+  await g.chat(messages);
+} catch (err) {
+  if (err instanceof AIGatewayError) {
+    console.error('Bad request:', err.code, err.message);
+  } else {
+    console.error('Provider error:', err);
+  }
+}
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+Tests run fully offline via injected fake clients (`options.client`). They cover
+provider resolution, constructor validation, the v2 response shape for chat /
+vision, streaming deltas + `.final`, error propagation, the OpenRouter prefix
+strip, cache-hint mapping, and `maxTokens` behavior.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pkent/aigateway",
+  "version": "1.0.0",
+  "description": "A provider-neutral LLM client library for OpenAI, Anthropic, Qwen, GLM, and OpenRouter",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test test/aigateway.test.js test/cache-hints.test.js test/usage-normalization.test.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pkent/aigateway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pkent/aigateway/issues"
+  },
+  "homepage": "https://github.com/pkent/aigateway#readme",
+  "keywords": [
+    "llm",
+    "openai",
+    "anthropic",
+    "openrouter",
+    "qwen",
+    "glm",
+    "gateway",
+    "ai"
+  ],
+  "author": "pkent",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.104.2",
+    "openai": "^6.34.0"
+  }
+}

package/src/AIGateway.js

@@ -0,0 +1,97 @@
+import { resolveProviderEntry, listProviderEntries } from './providers/registry.js';
+import { AIGatewayError } from './errors.js';
+import { validateMessages } from './validation.js';
+import { ChatStream } from './stream/ChatStream.js';
+import { buildV2Response } from './lib/v2.js';
+
+// A provider-neutral LLM client bound to one model + one API key. The model
+// string selects the provider via prefix matching; the key is that provider's
+// credential. No environment variables are read — all config is injected.
+export class AIGateway {
+  #model;
+  #providerId;
+  #provider;
+  #defaults;
+
+  constructor(model, key, options = {}) {
+    if (typeof model !== 'string' || model.trim() === '') {
+      throw new AIGatewayError('Missing or invalid "model"', { code: 'invalid_model' });
+    }
+
+    const entry = resolveProviderEntry(model);
+    if (!entry) {
+      const known = listProviderEntries().map(p => p.id).join(', ');
+      throw new AIGatewayError(
+        `Unsupported model "${model}". Use "<provider>/<model>" (e.g. "anthropic/claude-opus-4.8"). Known providers: ${known}.`,
+        { code: 'unsupported_model' },
+      );
+    }
+
+    const { baseURL, maxTokens, referer, title, client } = options;
+
+    if (!client && (typeof key !== 'string' || key.trim() === '')) {
+      throw new AIGatewayError('Missing or invalid API key', { code: 'invalid_api_key' });
+    }
+
+    this.#model = model;
+    this.#providerId = entry.id;
+    this.#provider = entry.create({ apiKey: key, baseURL, referer, title, client });
+    this.#defaults = { maxTokens };
+  }
+
+  get model() {
+    return this.#model;
+  }
+
+  get provider() {
+    return this.#providerId;
+  }
+
+  // Discovery helper: the registered providers and their model prefixes.
+  static providers() {
+    return listProviderEntries();
+  }
+
+  #mergeOptions(callOptions = {}) {
+    return {
+      maxTokens: callOptions.maxTokens ?? this.#defaults.maxTokens,
+      temperature: callOptions.temperature,
+      responseFormat: callOptions.responseFormat,
+    };
+  }
+
+  async chat(messages, callOptions = {}) {
+    validateMessages(messages);
+    return this.#provider.chat(this.#model, messages, this.#mergeOptions(callOptions));
+  }
+
+  async vision(messages, callOptions = {}) {
+    validateMessages(messages);
+    return this.#provider.vision(this.#model, messages, this.#mergeOptions(callOptions));
+  }
+
+  stream(messages, callOptions = {}) {
+    validateMessages(messages);
+    const options = this.#mergeOptions(callOptions);
+    const model = this.#model;
+    const providerId = this.#providerId;
+    const provider = this.#provider;
+
+    return new ChatStream(async (emit) => {
+      // Providers hand us raw text strings; wrap each into a delta object.
+      const emitDelta = (text) => emit({ type: 'text_delta', text });
+      const final = await provider.stream(model, messages, options, { emitDelta });
+      return buildV2Response({
+        id: final.id,
+        created: final.created,
+        provider: providerId,
+        model,
+        stopReason: final.stopReason,
+        content: final.content,
+        usage: final.usage,
+      });
+    });
+  }
+}
+
+export default AIGateway;

package/src/errors.js

@@ -0,0 +1,7 @@
+export class AIGatewayError extends Error {
+  constructor(message, { code } = {}) {
+    super(message);
+    this.name = 'AIGatewayError';
+    this.code = code;
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { default, AIGateway } from './AIGateway.js';
+export { AIGatewayError } from './errors.js';

package/src/lib/v2.js

@@ -0,0 +1,136 @@
+export function buildUsage({
+  inputTokens = 0,
+  outputTokens = 0,
+  cachedInputTokens,
+  cacheCreationInputTokens,
+  cacheReadInputTokens,
+} = {}) {
+  return {
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    total_tokens: inputTokens + outputTokens,
+    ...(cachedInputTokens !== undefined && { cached_input_tokens: cachedInputTokens }),
+    ...(cacheCreationInputTokens !== undefined && { cache_creation_input_tokens: cacheCreationInputTokens }),
+    ...(cacheReadInputTokens !== undefined && { cache_read_input_tokens: cacheReadInputTokens }),
+  };
+}
+
+export function extractOpenAIUsage(usage = {}) {
+  return buildUsage({
+    inputTokens: usage.prompt_tokens ?? 0,
+    outputTokens: usage.completion_tokens ?? 0,
+    cachedInputTokens: usage.prompt_tokens_details?.cached_tokens,
+  });
+}
+
+export function extractAnthropicUsage(usage = {}) {
+  return buildUsage({
+    inputTokens: usage.input_tokens ?? 0,
+    outputTokens: usage.output_tokens ?? 0,
+    cachedInputTokens: usage.cache_read_input_tokens,
+    cacheCreationInputTokens: usage.cache_creation_input_tokens,
+    cacheReadInputTokens: usage.cache_read_input_tokens,
+  });
+}
+
+export function normalizeContentBlocks(provider, content) {
+  if (provider === 'anthropic') {
+    return (content || []).map(block => {
+      if (block.type === 'text') {
+        return { type: 'text', text: block.text };
+      }
+
+      if (block.type === 'tool_use') {
+        return {
+          type: 'tool_use',
+          id: block.id,
+          name: block.name,
+          input: block.input,
+        };
+      }
+
+      if (block.type === 'image') {
+        return {
+          type: 'image',
+          source: block.source,
+        };
+      }
+
+      return block;
+    });
+  }
+
+  if (typeof content === 'string') {
+    return [{ type: 'text', text: content }];
+  }
+
+  if (Array.isArray(content)) {
+    return content.map(block => {
+      if (block.type === 'text') {
+        return { type: 'text', text: block.text ?? '' };
+      }
+
+      if (block.type === 'image_url') {
+        return {
+          type: 'image',
+          source: {
+            type: 'image_url',
+            url: block.image_url?.url,
+          },
+        };
+      }
+
+      if (block.type === 'tool_call') {
+        return {
+          type: 'tool_use',
+          id: block.id,
+          name: block.function?.name,
+          input: block.function?.arguments,
+        };
+      }
+
+      return block;
+    });
+  }
+
+  return [];
+}
+
+export function buildV2Response({ id, created, provider, model, role = 'assistant', stopReason, content, usage }) {
+  return {
+    id,
+    object: 'response',
+    created,
+    provider,
+    model,
+    role,
+    stop_reason: stopReason,
+    content,
+    usage,
+  };
+}
+
+export function normalizeOpenAIResponse(completion) {
+  const choice = completion.choices[0];
+  return buildV2Response({
+    id: completion.id,
+    created: completion.created,
+    provider: 'openai',
+    model: completion.model,
+    stopReason: choice.finish_reason,
+    content: normalizeContentBlocks('openai', choice.message.content),
+    usage: extractOpenAIUsage(completion.usage),
+  });
+}
+
+export function normalizeAnthropicResponse(response) {
+  return buildV2Response({
+    id: response.id,
+    created: Math.floor(Date.now() / 1000),
+    provider: 'anthropic',
+    model: response.model,
+    stopReason: response.stop_reason,
+    content: normalizeContentBlocks('anthropic', response.content),
+    usage: extractAnthropicUsage(response.usage),
+  });
+}

package/src/providers/anthropic.js

@@ -0,0 +1,111 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { convertMessagesForAnthropic } from './messageTransforms.js';
+import { stripProviderPrefix } from './modelId.js';
+import {
+  buildV2Response,
+  extractAnthropicUsage,
+  normalizeContentBlocks,
+} from '../lib/v2.js';
+
+function buildRequest(model, messages, options = {}) {
+  // The Anthropic SDK requires max_tokens, so fall back to 4096 when the caller
+  // does not supply one (OpenAI-compatible providers omit the cap instead).
+  const { maxTokens = 4096, temperature } = options;
+  const { system, messages: converted } = convertMessagesForAnthropic(messages);
+  return {
+    model: stripProviderPrefix(model),
+    max_tokens: maxTokens,
+    messages: converted,
+    ...(system && { system }),
+    ...(temperature != null && { temperature }),
+  };
+}
+
+function normalize(response, originalModel) {
+  return buildV2Response({
+    id: response.id,
+    created: Math.floor(Date.now() / 1000),
+    provider: 'anthropic',
+    model: originalModel,
+    stopReason: response.stop_reason,
+    content: normalizeContentBlocks('anthropic', response.content),
+    usage: extractAnthropicUsage(response.usage),
+  });
+}
+
+function createProvider({ apiKey, baseURL, client }) {
+  const anthropic = client || new Anthropic({ apiKey, ...(baseURL && { baseURL }) });
+
+  return {
+    id: 'anthropic',
+
+    async chat(model, messages, options = {}) {
+      return normalize(await anthropic.messages.create(buildRequest(model, messages, options)), model);
+    },
+
+    async vision(model, messages, options = {}) {
+      return normalize(await anthropic.messages.create(buildRequest(model, messages, options)), model);
+    },
+
+    async stream(model, messages, options = {}, { emitDelta }) {
+      const upstream = await anthropic.messages.create({ ...buildRequest(model, messages, options), stream: true });
+
+      let streamId = `anthropic_${Date.now()}`;
+      const created = Math.floor(Date.now() / 1000);
+      let outputText = '';
+      let stopReason = null;
+      let usage = extractAnthropicUsage();
+
+      for await (const event of upstream) {
+        if (event.type === 'message_start') {
+          streamId = event.message?.id || streamId;
+          if (event.message?.usage) {
+            usage = extractAnthropicUsage({
+              ...event.message.usage,
+              output_tokens: usage.output_tokens,
+            });
+          }
+          continue;
+        }
+
+        if (event.type === 'content_block_delta') {
+          const text = event.delta?.text || '';
+          if (!text) continue;
+          outputText += text;
+          emitDelta(text);
+          continue;
+        }
+
+        if (event.type === 'message_delta') {
+          if (event.usage) {
+            usage = extractAnthropicUsage({
+              input_tokens: usage.input_tokens,
+              cache_creation_input_tokens: usage.cache_creation_input_tokens,
+              cache_read_input_tokens: usage.cache_read_input_tokens,
+              output_tokens: event.usage.output_tokens,
+            });
+          }
+          if (event.delta?.stop_reason) stopReason = event.delta.stop_reason;
+          continue;
+        }
+
+        if (event.type === 'message_stop') break;
+      }
+
+      return {
+        id: streamId,
+        created,
+        stopReason: stopReason || 'end_turn',
+        content: [{ type: 'text', text: outputText }],
+        usage,
+      };
+    },
+  };
+}
+
+export default {
+  id: 'anthropic',
+  prefix: 'anthropic/',
+  matches: model => typeof model === 'string' && model.startsWith('anthropic/'),
+  create: createProvider,
+};

package/src/providers/glm.js

@@ -0,0 +1,18 @@
+import { createOpenAICompatibleProvider } from './openaiCompatible.js';
+
+const DEFAULT_BASE_URL = 'https://open.bigmodel.cn/api/paas/v4';
+
+// Models addressed as "glm/<model>", e.g. "glm/glm-4".
+export default {
+  id: 'glm',
+  prefix: 'glm/',
+  matches: model => typeof model === 'string' && model.startsWith('glm/'),
+  create({ apiKey, baseURL, client }) {
+    return createOpenAICompatibleProvider({
+      id: 'glm',
+      apiKey,
+      baseURL: baseURL || DEFAULT_BASE_URL,
+      client,
+    });
+  },
+};

package/src/providers/messageTransforms.js

@@ -0,0 +1,102 @@
+export function stripCacheHintsFromContentBlock(block) {
+  if (!block || typeof block !== 'object' || Array.isArray(block)) {
+    return block;
+  }
+
+  const { cache, ...rest } = block;
+  return rest;
+}
+
+export function stripCacheHintsFromMessages(messages = []) {
+  return messages.map(message => {
+    if (!Array.isArray(message.content)) {
+      return message;
+    }
+
+    return {
+      ...message,
+      content: message.content.map(stripCacheHintsFromContentBlock),
+    };
+  });
+}
+
+function toAnthropicTextBlock(block) {
+  const textBlock = {
+    type: 'text',
+    text: block.text,
+  };
+
+  if (block.cache === true) {
+    textBlock.cache_control = { type: 'ephemeral' };
+  }
+
+  return textBlock;
+}
+
+export function convertMessagesForAnthropic(messages = []) {
+  const systemBlocks = [];
+  const convertedMessages = [];
+
+  for (const msg of messages) {
+    if (msg.role === 'system') {
+      if (typeof msg.content === 'string') {
+        systemBlocks.push({ type: 'text', text: msg.content });
+        continue;
+      }
+
+      for (const block of msg.content) {
+        if (block.type === 'text') {
+          systemBlocks.push(toAnthropicTextBlock(block));
+        }
+      }
+      continue;
+    }
+
+    if (typeof msg.content === 'string') {
+      convertedMessages.push({ role: msg.role, content: msg.content });
+      continue;
+    }
+
+    const convertedContent = msg.content.map(block => {
+      if (block.type === 'text') {
+        return toAnthropicTextBlock(block);
+      }
+
+      if (block.type === 'image_url') {
+        const url = block.image_url?.url || '';
+
+        if (url.startsWith('data:')) {
+          const match = url.match(/^data:([^;]+);base64,(.+)$/s);
+          if (!match) {
+            throw new Error('Invalid base64 image data URL');
+          }
+          return {
+            type: 'image',
+            source: {
+              type: 'base64',
+              media_type: match[1],
+              data: match[2],
+            },
+          };
+        }
+
+        return {
+          type: 'image',
+          source: {
+            type: 'url',
+            url,
+          },
+        };
+      }
+
+      return stripCacheHintsFromContentBlock(block);
+    });
+
+    convertedMessages.push({ role: msg.role, content: convertedContent });
+  }
+
+  return {
+    system: systemBlocks.length > 0 ? systemBlocks : undefined,
+    messages: convertedMessages,
+  };
+}

package/src/providers/modelId.js

@@ -0,0 +1,8 @@
+// Models are addressed as "<provider>/<model>". The leading provider segment
+// selects the provider and is stripped before the upstream request. For
+// OpenRouter this leaves its native "<vendor>/<model>" id intact, e.g.
+// "openrouter/anthropic/claude-opus-4.8" -> "anthropic/claude-opus-4.8".
+export function stripProviderPrefix(model) {
+  const slash = model.indexOf('/');
+  return slash === -1 ? model : model.slice(slash + 1);
+}

package/src/providers/openai.js

@@ -0,0 +1,11 @@
+import { createOpenAICompatibleProvider } from './openaiCompatible.js';
+
+// Models addressed as "openai/<model>", e.g. "openai/gpt-4o".
+export default {
+  id: 'openai',
+  prefix: 'openai/',
+  matches: model => typeof model === 'string' && model.startsWith('openai/'),
+  create({ apiKey, baseURL, client }) {
+    return createOpenAICompatibleProvider({ id: 'openai', apiKey, baseURL, client });
+  },
+};

package/src/providers/openaiCompatible.js

@@ -0,0 +1,96 @@
+import OpenAI from 'openai';
+import { stripCacheHintsFromMessages } from './messageTransforms.js';
+import { stripProviderPrefix } from './modelId.js';
+import {
+  buildV2Response,
+  extractOpenAIUsage,
+  normalizeContentBlocks,
+} from '../lib/v2.js';
+
+// Shared implementation for every OpenAI-compatible provider (OpenAI, Qwen,
+// GLM, OpenRouter). Builds an OpenAI SDK client from the injected config, or
+// uses a pre-built `client` (testing / advanced wiring). The "<provider>/"
+// segment is stripped from the model before the upstream call.
+export function createOpenAICompatibleProvider({
+  id,
+  apiKey,
+  baseURL,
+  defaultHeaders,
+  client,
+}) {
+  const openai = client || new OpenAI({
+    apiKey,
+    ...(baseURL && { baseURL }),
+    ...(defaultHeaders && { defaultHeaders }),
+  });
+
+  function buildRequest(model, messages, options, { stream = false } = {}) {
+    const { maxTokens, temperature, responseFormat } = options;
+    return {
+      model: stripProviderPrefix(model),
+      messages: stripCacheHintsFromMessages(messages),
+      ...(maxTokens != null && { max_completion_tokens: maxTokens }),
+      ...(temperature != null && { temperature }),
+      ...(responseFormat && { response_format: responseFormat }),
+      ...(stream && { stream: true, stream_options: { include_usage: true } }),
+    };
+  }
+
+  function normalize(completion, originalModel) {
+    const choice = completion.choices[0];
+    return buildV2Response({
+      id: completion.id,
+      created: completion.created,
+      provider: id,
+      model: originalModel,
+      stopReason: choice.finish_reason,
+      content: normalizeContentBlocks('openai', choice.message.content),
+      usage: extractOpenAIUsage(completion.usage),
+    });
+  }
+
+  return {
+    id,
+
+    async chat(model, messages, options = {}) {
+      return normalize(await openai.chat.completions.create(buildRequest(model, messages, options)), model);
+    },
+
+    async vision(model, messages, options = {}) {
+      return normalize(await openai.chat.completions.create(buildRequest(model, messages, options)), model);
+    },
+
+    async stream(model, messages, options = {}, { emitDelta }) {
+      const upstream = await openai.chat.completions.create(buildRequest(model, messages, options, { stream: true }));
+
+      let streamId = `${id}_${Date.now()}`;
+      let created = Math.floor(Date.now() / 1000);
+      let outputText = '';
+      let finishReason = null;
+      let usage = extractOpenAIUsage();
+
+      for await (const chunk of upstream) {
+        if (chunk.id) streamId = chunk.id;
+        if (chunk.created) created = chunk.created;
+        if (chunk.usage) usage = extractOpenAIUsage(chunk.usage);
+
+        for (const choice of chunk.choices || []) {
+          const text = choice.delta?.content || '';
+          if (text) {
+            outputText += text;
+            emitDelta(text);
+          }
+          if (choice.finish_reason) finishReason = choice.finish_reason;
+        }
+      }
+
+      return {
+        id: streamId,
+        created,
+        stopReason: finishReason || 'stop',
+        content: [{ type: 'text', text: outputText }],
+        usage,
+      };
+    },
+  };
+}

package/src/providers/openrouter.js

@@ -0,0 +1,26 @@
+import { createOpenAICompatibleProvider } from './openaiCompatible.js';
+
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1';
+
+// Meta-provider addressed as "openrouter/<vendor>/<model>", e.g.
+// "openrouter/anthropic/claude-opus-4.8". The leading "openrouter/" segment is
+// stripped before the upstream call, leaving OpenRouter's native "<vendor>/<model>"
+// id. `referer`/`title` are optional OpenRouter attribution headers, sent only
+// when provided.
+export default {
+  id: 'openrouter',
+  prefix: 'openrouter/',
+  matches: model => typeof model === 'string' && model.startsWith('openrouter/'),
+  create({ apiKey, baseURL, referer, title, client }) {
+    return createOpenAICompatibleProvider({
+      id: 'openrouter',
+      apiKey,
+      baseURL: baseURL || DEFAULT_BASE_URL,
+      defaultHeaders: {
+        ...(referer && { 'HTTP-Referer': referer }),
+        ...(title && { 'X-Title': title }),
+      },
+      client,
+    });
+  },
+};

package/src/providers/qwen.js

@@ -0,0 +1,18 @@
+import { createOpenAICompatibleProvider } from './openaiCompatible.js';
+
+const DEFAULT_BASE_URL = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1';
+
+// Models addressed as "qwen/<model>", e.g. "qwen/qwen-turbo".
+export default {
+  id: 'qwen',
+  prefix: 'qwen/',
+  matches: model => typeof model === 'string' && model.startsWith('qwen/'),
+  create({ apiKey, baseURL, client }) {
+    return createOpenAICompatibleProvider({
+      id: 'qwen',
+      apiKey,
+      baseURL: baseURL || DEFAULT_BASE_URL,
+      client,
+    });
+  },
+};

package/src/providers/registry.js

@@ -0,0 +1,20 @@
+import openrouter from './openrouter.js';
+import anthropic from './anthropic.js';
+import qwen from './qwen.js';
+import glm from './glm.js';
+import openai from './openai.js';
+
+// Every model is addressed as "<provider>/<model>". The provider segments are
+// disjoint, so resolution order does not matter; there is no catch-all.
+const ENTRIES = [openrouter, anthropic, qwen, glm, openai];
+
+export function resolveProviderEntry(model) {
+  for (const entry of ENTRIES) {
+    if (entry.matches(model)) return entry;
+  }
+  return null;
+}
+
+export function listProviderEntries() {
+  return ENTRIES.map(({ id, prefix }) => ({ id, prefix }));
+}

package/src/stream/ChatStream.js

@@ -0,0 +1,54 @@
+// Bridges the providers' push-based streaming (an `emitDelta` callback plus a
+// returned final aggregate) to a pull-based async iterator, while also exposing
+// a `.final` promise that resolves to the full v2 response envelope.
+//
+// Usage:
+//   const stream = gateway.stream(messages);
+//   for await (const delta of stream) process.stdout.write(delta.text);
+//   const final = await stream.final;
+//
+// Each yielded delta is an object: { type: 'text_delta', text: string }.
+export class ChatStream {
+  #queue = []; // buffered deltas not yet pulled
+  #waiters = []; // resolvers for pending next() calls
+  #done = false;
+  #error = null;
+
+  constructor(run) {
+    // run(emit) performs the upstream stream and resolves the final envelope.
+    // `emit` receives a delta OBJECT ({ type:'text_delta', text }) — the caller
+    // (AIGateway.stream) is responsible for wrapping provider raw strings.
+    this.final = run((delta) => this.#emit(delta)).then(
+      (finalResponse) => { this.#finish(null); return finalResponse; },
+      (err) => { this.#finish(err); throw err; },
+    );
+    // Prevent an unhandled rejection if the caller iterates but never awaits .final.
+    this.final.catch(() => {});
+  }
+
+  #emit(delta) {
+    if (this.#waiters.length) this.#waiters.shift()({ value: delta, done: false });
+    else this.#queue.push(delta);
+  }
+
+  #finish(err) {
+    this.#error = err;
+    this.#done = true;
+    while (this.#waiters.length) {
+      const resolve = this.#waiters.shift();
+      if (err) resolve(Promise.reject(err));
+      else resolve({ value: undefined, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.#queue.length) return Promise.resolve({ value: this.#queue.shift(), done: false });
+        if (this.#error) return Promise.reject(this.#error);
+        if (this.#done) return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => this.#waiters.push(resolve));
+      },
+    };
+  }
+}

package/src/validation.js

@@ -0,0 +1,32 @@
+import { AIGatewayError } from './errors.js';
+
+const ALLOWED_ROLES = new Set(['user', 'assistant', 'system', 'tool']);
+
+// Validates the provider-neutral message array. The model is bound at
+// construction, so only messages are validated here. Throws AIGatewayError.
+export function validateMessages(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new AIGatewayError('Missing or invalid "messages" field', { code: 'invalid_messages' });
+  }
+
+  for (const msg of messages) {
+    if (!msg || !msg.role) {
+      throw new AIGatewayError('Each message must have a "role" field', { code: 'invalid_message' });
+    }
+    if (!ALLOWED_ROLES.has(msg.role)) {
+      throw new AIGatewayError(
+        'Message role must be "user", "assistant", "system", or "tool"',
+        { code: 'invalid_message_role' },
+      );
+    }
+    if (msg.content === undefined || msg.content === null) {
+      throw new AIGatewayError('Each message must have a "content" field', { code: 'invalid_message' });
+    }
+    if (typeof msg.content !== 'string' && !Array.isArray(msg.content)) {
+      throw new AIGatewayError(
+        '"content" must be a string or an array of content blocks',
+        { code: 'invalid_message_content' },
+      );
+    }
+  }
+}