@pkent/aigateway 1.0.0 → 1.1.0

package/README.md

@@ -51,6 +51,7 @@ new AIGateway(model, key, options?)
 |-------------|--------|-----------------|------------------|-------------|
 | `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. |
+| `timeout`   | number | all             | unset (SDK default) | Default per-call request timeout in ms; a per-call `timeout` 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. |
@@ -81,8 +82,9 @@ AIGateway.providers()
 
 `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).
+`maxTokens`, `responseFormat`, `signal` (an `AbortSignal` to cancel the
+request), and `timeout` (ms). (`responseFormat` is mapped to OpenAI-compatible
+`response_format`; ignored by Anthropic.)
 
 ```js
 const g = new AIGateway('openai/gpt-4o', OPENAI_KEY);
@@ -118,6 +120,9 @@ 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`.
 
+Accepts the same `signal`/`timeout` options; aborting the signal rejects both
+the iterator and `.final`.
+
 ## Model routing
 
 Every model is addressed as `<provider>/<model>`. The leading provider segment
@@ -206,6 +211,32 @@ behavior:
 Supply `maxTokens` (in the constructor or per call) to apply a cap to every
 provider. A per-call value overrides the constructor default.
 
+## Cancellation & timeouts
+
+Pass an `AbortSignal` as `signal` to cancel an in-flight request; pass
+`timeout` (ms) to bound it. Both are forwarded to the underlying provider
+SDK's request options and apply to `chat`, `vision`, and `stream`.
+
+```js
+const controller = new AbortController();
+const res = g.chat(messages, { signal: controller.signal });
+// ...later:
+controller.abort();   // res rejects with the SDK's APIUserAbortError
+```
+
+For a hard wall-clock cap that also honors an external cancel, combine a
+timeout signal with your own:
+
+```js
+const signal = AbortSignal.any([AbortSignal.timeout(120_000), runSignal]);
+const res = await g.chat(messages, { signal });
+```
+
+The `timeout` option is a per-attempt connection timeout and may be retried
+by the SDK; prefer a combined `signal` (as above) when you need a guaranteed
+wall-clock bound. Aborting a stream rejects both the async iterator and the
+`.final` promise.
+
 ## Errors
 
 - **Input errors** (invalid model/key/messages) throw `AIGatewayError` with a
@@ -214,6 +245,9 @@ provider. A per-call value overrides the constructor default.
   `invalid_message_content`).
 - **Upstream/provider errors** propagate as the underlying SDK error — `chat` /
   `vision` reject; `stream` throws on the iterator and rejects `.final`.
+- An aborted request rejects with the SDK's `APIUserAbortError`; a timed-out
+  request with `APIConnectionTimeoutError`. Like other provider errors, these
+  propagate unchanged (not wrapped in `AIGatewayError`).
 
 ```js
 import AIGateway, { AIGatewayError } from '@pkent/aigateway';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pkent/aigateway",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A provider-neutral LLM client library for OpenAI, Anthropic, Qwen, GLM, and OpenRouter",
   "main": "src/index.js",
   "type": "module",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "prepublishOnly": "node --test test/aigateway.test.js test/cache-hints.test.js test/usage-normalization.test.js"
+    "prepublishOnly": "node --test test/aigateway.test.js test/cache-hints.test.js test/usage-normalization.test.js test/cancellation.test.js"
   },
   "files": [
     "src",

package/src/AIGateway.js

@@ -27,7 +27,7 @@ export class AIGateway {
       );
     }
 
-    const { baseURL, maxTokens, referer, title, client } = options;
+    const { baseURL, maxTokens, timeout, referer, title, client } = options;
 
     if (!client && (typeof key !== 'string' || key.trim() === '')) {
       throw new AIGatewayError('Missing or invalid API key', { code: 'invalid_api_key' });
@@ -36,7 +36,7 @@ export class AIGateway {
     this.#model = model;
     this.#providerId = entry.id;
     this.#provider = entry.create({ apiKey: key, baseURL, referer, title, client });
-    this.#defaults = { maxTokens };
+    this.#defaults = { maxTokens, timeout };
   }
 
   get model() {
@@ -57,6 +57,8 @@ export class AIGateway {
       maxTokens: callOptions.maxTokens ?? this.#defaults.maxTokens,
       temperature: callOptions.temperature,
       responseFormat: callOptions.responseFormat,
+      signal: callOptions.signal,
+      timeout: callOptions.timeout ?? this.#defaults.timeout,
     };
   }
 

package/src/providers/anthropic.js

@@ -1,6 +1,7 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { convertMessagesForAnthropic } from './messageTransforms.js';
 import { stripProviderPrefix } from './modelId.js';
+import { buildRequestOptions } from './requestOptions.js';
 import {
   buildV2Response,
   extractAnthropicUsage,
@@ -40,15 +41,18 @@ function createProvider({ apiKey, baseURL, client }) {
     id: 'anthropic',
 
     async chat(model, messages, options = {}) {
-      return normalize(await anthropic.messages.create(buildRequest(model, messages, options)), model);
+      return normalize(await anthropic.messages.create(buildRequest(model, messages, options), buildRequestOptions(options)), model);
     },
 
     async vision(model, messages, options = {}) {
-      return normalize(await anthropic.messages.create(buildRequest(model, messages, options)), model);
+      return normalize(await anthropic.messages.create(buildRequest(model, messages, options), buildRequestOptions(options)), model);
     },
 
     async stream(model, messages, options = {}, { emitDelta }) {
-      const upstream = await anthropic.messages.create({ ...buildRequest(model, messages, options), stream: true });
+      const upstream = await anthropic.messages.create(
+        { ...buildRequest(model, messages, options), stream: true },
+        buildRequestOptions(options),
+      );
 
       let streamId = `anthropic_${Date.now()}`;
       const created = Math.floor(Date.now() / 1000);

package/src/providers/openaiCompatible.js

@@ -1,6 +1,7 @@
 import OpenAI from 'openai';
 import { stripCacheHintsFromMessages } from './messageTransforms.js';
 import { stripProviderPrefix } from './modelId.js';
+import { buildRequestOptions } from './requestOptions.js';
 import {
   buildV2Response,
   extractOpenAIUsage,
@@ -53,15 +54,24 @@ export function createOpenAICompatibleProvider({
     id,
 
     async chat(model, messages, options = {}) {
-      return normalize(await openai.chat.completions.create(buildRequest(model, messages, options)), model);
+      return normalize(
+        await openai.chat.completions.create(buildRequest(model, messages, options), buildRequestOptions(options)),
+        model,
+      );
     },
 
     async vision(model, messages, options = {}) {
-      return normalize(await openai.chat.completions.create(buildRequest(model, messages, options)), model);
+      return normalize(
+        await openai.chat.completions.create(buildRequest(model, messages, options), buildRequestOptions(options)),
+        model,
+      );
     },
 
     async stream(model, messages, options = {}, { emitDelta }) {
-      const upstream = await openai.chat.completions.create(buildRequest(model, messages, options, { stream: true }));
+      const upstream = await openai.chat.completions.create(
+        buildRequest(model, messages, options, { stream: true }),
+        buildRequestOptions(options),
+      );
 
       let streamId = `${id}_${Date.now()}`;
       let created = Math.floor(Date.now() / 1000);

package/src/providers/requestOptions.js

@@ -0,0 +1,14 @@
+// Maps the provider-neutral transport options onto the SDK's per-call
+// "request options" object — the SECOND argument to anthropic.messages.create /
+// openai.chat.completions.create. Both SDKs accept { signal, timeout } there.
+//
+// These are transport concerns and must NEVER be placed in the request body.
+// Each field is included only when set (mirroring the conditional-spread style
+// used for body fields), so an absent signal/timeout leaves SDK defaults intact
+// and an omitted-options call sends an empty {} — a no-op for both SDKs.
+export function buildRequestOptions({ signal, timeout } = {}) {
+  return {
+    ...(signal != null && { signal }),
+    ...(timeout != null && { timeout }),
+  };
+}