@caether/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaetherAI
+
+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,61 @@
+# @caether/sdk
+
+Official JavaScript/Node.js SDK for the [CaetherAI](https://caether.ai) API.
+
+## Installation
+
+```bash
+npm install @caether/sdk
+```
+
+Requires Node.js 18+ (uses the global `fetch`).
+
+## Quickstart
+
+```js
+import { Client } from "@caether/sdk";
+import { user, system } from "@caether/sdk/chat";
+
+const client = new Client({ apiKey: process.env.CAETHER_API_KEY });
+
+const chat = client.chat.create({ model: "caether-1.1" });
+chat.append(system("You are Caether, an AI agent built to answer helpful questions."));
+chat.append(user("How big is the universe?"));
+
+const response = await chat.sample();
+console.log(String(response)); // text content
+console.log(response.id);      // response ID to continue later
+```
+
+### Streaming
+
+```js
+const chat = client.chat.create({ model: "caether-1.1" });
+chat.append(user("Write a haiku about the sea."));
+
+const { response, stream } = chat.stream();
+for await (const chunk of stream) {
+  process.stdout.write(chunk.content);
+}
+console.log("\n", response.content);
+```
+
+### Chaining the conversation
+
+```js
+const chat2 = client.chat.create({
+  model: "caether-1.1",
+  previousResponseId: response.id,
+});
+chat2.append(user("How do stars form?"));
+const second = await chat2.sample();
+```
+
+### Retrieve / delete a stored response
+
+```js
+const stored = await client.chat.getStoredCompletion("<response id>");
+await client.chat.deleteStoredCompletion("<response id>");
+```
+
+See [docs.caether.ai](https://docs.caether.ai) for full documentation.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@caether/sdk",
+  "version": "0.1.0",
+  "description": "Official JavaScript/Node.js SDK for the CaetherAI API",
+  "type": "module",
+  "license": "MIT",
+  "author": "CaetherAI",
+  "homepage": "https://caether.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./chat": {
+      "types": "./src/chat/index.d.ts",
+      "import": "./src/chat/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "caether",
+    "caetherai",
+    "ai",
+    "llm",
+    "sdk",
+    "api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/chat/chat.js

@@ -0,0 +1,139 @@
+import { Response, ResponseChunk } from "./types.js";
+
+export class Chat {
+  constructor(transport, options) {
+    this._transport = transport;
+    this._path = options.path;
+    this.model = options.model;
+    this.storeMessages = options.storeMessages ?? true;
+    this.previousResponseId = options.previousResponseId ?? null;
+    this.useEncryptedContent = options.useEncryptedContent ?? false;
+    this.temperature = options.temperature;
+    this.topP = options.topP;
+    this.maxOutputTokens = options.maxOutputTokens;
+    this.reasoningEffort = options.reasoningEffort;
+    this.tools = options.tools;
+    this.toolChoice = options.toolChoice;
+    this.extraBody = options.extraBody || {};
+    this.messages = [];
+  }
+
+  append(message) {
+    if (message instanceof Response) {
+      this.previousResponseId = message.id || this.previousResponseId;
+      for (const item of message.output) this.messages.push(item);
+    } else {
+      this.messages.push(message);
+    }
+    return this;
+  }
+
+  _buildBody(stream) {
+    const body = {
+      model: this.model,
+      messages: this.messages,
+      stream,
+      store: this.storeMessages,
+    };
+    if (this.previousResponseId !== null && this.previousResponseId !== undefined)
+      body.previous_response_id = this.previousResponseId;
+    if (this.temperature !== undefined) body.temperature = this.temperature;
+    if (this.topP !== undefined) body.top_p = this.topP;
+    if (this.maxOutputTokens !== undefined)
+      body.max_output_tokens = this.maxOutputTokens;
+    if (this.reasoningEffort !== undefined)
+      body.reasoning_effort = this.reasoningEffort;
+    if (this.tools !== undefined) body.tools = this.tools;
+    if (this.toolChoice !== undefined) body.tool_choice = this.toolChoice;
+    if (this.useEncryptedContent) body.include = ["reasoning.encrypted_content"];
+    Object.assign(body, this.extraBody);
+    return body;
+  }
+
+  async sample() {
+    const data = await this._transport.request("POST", this._path, {
+      body: this._buildBody(false),
+    });
+    const response = Response.fromObject(data);
+    if (response.id) this.previousResponseId = response.id;
+    return response;
+  }
+
+  stream() {
+    const accumulator = new Response({ model: this.model, output: [] });
+    const events = this._transport.stream("POST", this._path, {
+      body: this._buildBody(true),
+    });
+
+    async function* generator() {
+      const contentParts = [];
+      const reasoningParts = [];
+      for await (const event of events) {
+        const chunk = ResponseChunk.fromEvent(event);
+        if (chunk.content) {
+          contentParts.push(chunk.content);
+          accumulator.content = contentParts.join("");
+        }
+        if (chunk.reasoningContent) {
+          reasoningParts.push(chunk.reasoningContent);
+          accumulator.reasoningContent = reasoningParts.join("");
+        }
+        if (chunk.usage) accumulator.usage = chunk.usage;
+        if (chunk.functionCall) accumulator.functionCalls.push(chunk.functionCall);
+        yield chunk;
+      }
+    }
+
+    return { response: accumulator, stream: generator() };
+  }
+}
+
+export class ChatClient {
+  constructor(transport, { path = "/chat/completions" } = {}) {
+    this._transport = transport;
+    this._path = path;
+  }
+
+  create(options = {}) {
+    const {
+      model,
+      storeMessages,
+      previousResponseId,
+      useEncryptedContent,
+      temperature,
+      topP,
+      maxOutputTokens,
+      reasoningEffort,
+      tools,
+      toolChoice,
+      ...extraBody
+    } = options;
+    if (!model) throw new Error("model is required");
+    return new Chat(this._transport, {
+      path: this._path,
+      model,
+      storeMessages,
+      previousResponseId,
+      useEncryptedContent,
+      temperature,
+      topP,
+      maxOutputTokens,
+      reasoningEffort,
+      tools,
+      toolChoice,
+      extraBody,
+    });
+  }
+
+  async getStoredCompletion(responseId) {
+    const data = await this._transport.request(
+      "GET",
+      `${this._path}/${responseId}`,
+    );
+    return Response.fromObject(data);
+  }
+
+  async deleteStoredCompletion(responseId) {
+    return this._transport.request("DELETE", `${this._path}/${responseId}`);
+  }
+}

package/src/chat/content.js

@@ -0,0 +1,41 @@
+export function text(value) {
+  return { type: "text", text: value };
+}
+
+export function image(url) {
+  return { type: "image", image: url };
+}
+
+export function video(url) {
+  return { type: "video", video: url };
+}
+
+export function file(value, name) {
+  const part = { type: "file", file: value };
+  if (name !== undefined) part.name = name;
+  return part;
+}
+
+function message(role, parts) {
+  if (parts.length === 1 && typeof parts[0] === "string") {
+    return { role, content: parts[0] };
+  }
+  const content = parts.map((p) => (typeof p === "string" ? text(p) : p));
+  return { role, content };
+}
+
+export function system(...parts) {
+  return message("system", parts);
+}
+
+export function user(...parts) {
+  return message("user", parts);
+}
+
+export function assistant(...parts) {
+  return message("assistant", parts);
+}
+
+export function toolResult(callId, output) {
+  return { type: "function_call_output", call_id: callId, output };
+}

package/src/chat/index.d.ts

@@ -0,0 +1,93 @@
+export type Role = "system" | "user" | "assistant" | string;
+
+export interface ContentPart {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface Message {
+  role: Role;
+  content: string | ContentPart[];
+}
+
+export function text(value: string): ContentPart;
+export function image(url: string): ContentPart;
+export function video(url: string): ContentPart;
+export function file(value: string, name?: string): ContentPart;
+export function system(...parts: Array<string | ContentPart>): Message;
+export function user(...parts: Array<string | ContentPart>): Message;
+export function assistant(...parts: Array<string | ContentPart>): Message;
+export function toolResult(callId: string, output: string): {
+  type: "function_call_output";
+  call_id: string;
+  output: string;
+};
+
+export class Usage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  costInUsdTicks: number | null;
+  raw: Record<string, unknown>;
+  static fromObject(data: unknown): Usage;
+}
+
+export class FunctionCall {
+  name: string;
+  arguments: string;
+  callId: string | null;
+}
+
+export class Response {
+  id: string | null;
+  model: string | null;
+  content: string;
+  reasoningContent: string | null;
+  output: Array<Record<string, unknown>>;
+  functionCalls: FunctionCall[];
+  usage: Usage;
+  raw: Record<string, unknown>;
+  static fromObject(data: unknown): Response;
+  toString(): string;
+}
+
+export class ResponseChunk {
+  type: string | null;
+  content: string;
+  reasoningContent: string;
+  status: string | null;
+  usage: Usage | null;
+  functionCall: FunctionCall | null;
+  raw: Record<string, unknown>;
+  static fromEvent(event: unknown): ResponseChunk;
+}
+
+export interface CreateChatOptions {
+  model: string;
+  storeMessages?: boolean;
+  previousResponseId?: string | null;
+  useEncryptedContent?: boolean;
+  temperature?: number;
+  topP?: number;
+  maxOutputTokens?: number;
+  reasoningEffort?: "low" | "medium" | "high";
+  tools?: unknown[];
+  toolChoice?: unknown;
+  [extra: string]: unknown;
+}
+
+export class Chat {
+  model: string;
+  storeMessages: boolean;
+  previousResponseId: string | null;
+  messages: Array<Message | Record<string, unknown>>;
+  append(message: Message | Response | Record<string, unknown>): this;
+  sample(): Promise<Response>;
+  stream(): { response: Response; stream: AsyncIterableIterator<ResponseChunk> };
+}
+
+export class ChatClient {
+  create(options: CreateChatOptions): Chat;
+  getStoredCompletion(responseId: string): Promise<Response>;
+  deleteStoredCompletion(responseId: string): Promise<Record<string, unknown>>;
+}

package/src/chat/index.js

@@ -0,0 +1,17 @@
+export { Chat, ChatClient } from "./chat.js";
+export {
+  Response,
+  ResponseChunk,
+  Usage,
+  FunctionCall,
+} from "./types.js";
+export {
+  system,
+  user,
+  assistant,
+  text,
+  image,
+  video,
+  file,
+  toolResult,
+} from "./content.js";

package/src/chat/types.js

@@ -0,0 +1,113 @@
+export class Usage {
+  constructor(data = {}) {
+    this.inputTokens = Number(data.input_tokens || 0);
+    this.outputTokens = Number(data.output_tokens || 0);
+    this.totalTokens = Number(data.total_tokens || 0);
+    this.costInUsdTicks =
+      data.cost_in_usd_ticks !== undefined ? data.cost_in_usd_ticks : null;
+    this.raw = data || {};
+  }
+
+  static fromObject(data) {
+    return new Usage(data || {});
+  }
+}
+
+export class FunctionCall {
+  constructor({ name = "", arguments: args = "", call_id = null } = {}) {
+    this.name = name;
+    this.arguments = args;
+    this.callId = call_id;
+  }
+}
+
+function extractOutputText(output) {
+  const parts = [];
+  for (const item of output) {
+    if (item.type === "message") {
+      for (const block of item.content || []) {
+        if (block.type === "output_text" && block.text) parts.push(block.text);
+      }
+    } else if (item.type === "output_text" && item.text) {
+      parts.push(item.text);
+    } else if (item.type === "text" && item.text) {
+      parts.push(item.text);
+    }
+  }
+  return parts.join("");
+}
+
+function extractReasoning(output) {
+  for (const item of output) {
+    if (item.type === "reasoning") {
+      if (Array.isArray(item.summary)) {
+        const joined = item.summary.map((s) => s.text || "").join("");
+        if (joined) return joined;
+      }
+      if (item.encrypted_content) return item.encrypted_content;
+    }
+  }
+  return null;
+}
+
+export class Response {
+  constructor(data) {
+    const output = Array.isArray(data.output) ? data.output : [];
+    this.id = data.id ?? null;
+    this.model = data.model ?? null;
+    this.content = extractOutputText(output);
+    this.reasoningContent = extractReasoning(output);
+    this.output = output;
+    this.functionCalls = (data.function_calls || []).map(
+      (fc) => new FunctionCall(fc),
+    );
+    this.usage = Usage.fromObject(data.usage);
+    this.raw = data;
+  }
+
+  static fromObject(data) {
+    return new Response(data);
+  }
+
+  toString() {
+    return this.content;
+  }
+}
+
+export class ResponseChunk {
+  constructor(event) {
+    this.type = event.type ?? null;
+    this.content = "";
+    this.reasoningContent = "";
+    this.status = null;
+    this.usage = null;
+    this.functionCall = null;
+    this.raw = event;
+
+    if (event.usage && typeof event.usage === "object") {
+      this.usage = Usage.fromObject(event.usage);
+    }
+    if (event.type === "reasoning_delta") {
+      this.reasoningContent = event.content || "";
+    } else if (event.type === "function_call") {
+      this.functionCall = new FunctionCall({
+        name: event.name,
+        arguments: event.arguments,
+      });
+    } else if (
+      ["tool_update", "search_status", "search_query", "search_started"].includes(
+        event.type,
+      )
+    ) {
+      this.status = event.status ?? null;
+    }
+    if (Array.isArray(event.choices) && event.choices.length) {
+      const delta = event.choices[0].delta || {};
+      this.content = delta.content || "";
+    }
+  }
+
+  static fromEvent(event) {
+    return new ResponseChunk(event);
+  }
+}

package/src/client.js

@@ -0,0 +1,48 @@
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_TIMEOUT,
+} from "./constants.js";
+import { CaetherError } from "./errors.js";
+import { Transport } from "./transport.js";
+import { ChatClient } from "./chat/chat.js";
+
+function resolveApiKey(apiKey) {
+  const key = apiKey || (typeof process !== "undefined" && process.env?.CAETHER_API_KEY);
+  if (!key) {
+    throw new CaetherError(
+      "No API key provided. Pass { apiKey } or set the CAETHER_API_KEY environment variable.",
+    );
+  }
+  return key;
+}
+
+export class Client {
+  constructor({
+    apiKey,
+    baseUrl,
+    timeout = DEFAULT_TIMEOUT,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    defaultHeaders,
+    fetch: fetchImpl,
+  } = {}) {
+    this.apiKey = resolveApiKey(apiKey);
+    this.baseUrl = (
+      baseUrl ||
+      (typeof process !== "undefined" && process.env?.CAETHER_BASE_URL) ||
+      DEFAULT_BASE_URL
+    ).replace(/\/+$/, "");
+
+    this._transport = new Transport({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      timeout,
+      maxRetries,
+      defaultHeaders,
+      fetch: fetchImpl,
+    });
+
+    this.chat = new ChatClient(this._transport, { path: "/chat/completions" });
+    this.code = new ChatClient(this._transport, { path: "/code/stream" });
+  }
+}

package/src/constants.js

@@ -0,0 +1,8 @@
+export const DEFAULT_API_HOST = "api.caether.ai";
+export const DEFAULT_BASE_URL = `https://${DEFAULT_API_HOST}`;
+
+export const DEFAULT_TIMEOUT = 3600000;
+export const DEFAULT_MAX_RETRIES = 2;
+
+export const USER_AGENT = "caetherai-js";
+export const SDK_VERSION = "0.1.0";

package/src/errors.js

@@ -0,0 +1,82 @@
+export class CaetherError extends Error {
+  constructor(message, { statusCode = null, code = null, body = null } = {}) {
+    super(message);
+    this.name = "CaetherError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.body = body;
+  }
+}
+
+export class APIConnectionError extends CaetherError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "APIConnectionError";
+  }
+}
+
+export class APITimeoutError extends APIConnectionError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "APITimeoutError";
+  }
+}
+
+export class APIStatusError extends CaetherError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "APIStatusError";
+  }
+}
+
+export class AuthenticationError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "AuthenticationError"; }
+}
+export class PermissionDeniedError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "PermissionDeniedError"; }
+}
+export class NotFoundError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "NotFoundError"; }
+}
+export class RateLimitError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "RateLimitError"; }
+}
+export class BadRequestError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "BadRequestError"; }
+}
+export class UnprocessableEntityError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "UnprocessableEntityError"; }
+}
+export class InternalServerError extends APIStatusError {
+  constructor(m, o) { super(m, o); this.name = "InternalServerError"; }
+}
+
+const STATUS_TO_ERROR = {
+  400: BadRequestError,
+  401: AuthenticationError,
+  403: PermissionDeniedError,
+  404: NotFoundError,
+  422: UnprocessableEntityError,
+  429: RateLimitError,
+};
+
+export function errorFromResponse(statusCode, body) {
+  let message = `HTTP ${statusCode}`;
+  let code = null;
+  if (body && typeof body === "object") {
+    const err = body.error;
+    if (err && typeof err === "object") {
+      message = err.message || message;
+      code = err.code || null;
+    } else if (typeof err === "string") {
+      message = err;
+    } else if (typeof body.message === "string") {
+      message = body.message;
+    }
+  }
+  let Cls;
+  if (STATUS_TO_ERROR[statusCode]) Cls = STATUS_TO_ERROR[statusCode];
+  else if (statusCode >= 500) Cls = InternalServerError;
+  else Cls = APIStatusError;
+  return new Cls(message, { statusCode, code, body });
+}

package/src/index.d.ts

@@ -0,0 +1,47 @@
+import { ChatClient } from "./chat/index.js";
+
+export * as chat from "./chat/index.js";
+
+export const DEFAULT_BASE_URL: string;
+export const SDK_VERSION: string;
+
+export interface ClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+  defaultHeaders?: Record<string, string>;
+  fetch?: typeof fetch;
+}
+
+export class Client {
+  apiKey: string;
+  baseUrl: string;
+  chat: ChatClient;
+  code: ChatClient;
+  constructor(options?: ClientOptions);
+}
+
+export interface CaetherErrorOptions {
+  statusCode?: number | null;
+  code?: string | null;
+  body?: unknown;
+}
+
+export class CaetherError extends Error {
+  statusCode: number | null;
+  code: string | null;
+  body: unknown;
+  constructor(message: string, options?: CaetherErrorOptions);
+}
+
+export class APIConnectionError extends CaetherError {}
+export class APITimeoutError extends APIConnectionError {}
+export class APIStatusError extends CaetherError {}
+export class AuthenticationError extends APIStatusError {}
+export class PermissionDeniedError extends APIStatusError {}
+export class NotFoundError extends APIStatusError {}
+export class RateLimitError extends APIStatusError {}
+export class BadRequestError extends APIStatusError {}
+export class UnprocessableEntityError extends APIStatusError {}
+export class InternalServerError extends APIStatusError {}

package/src/index.js

@@ -0,0 +1,17 @@
+export { Client } from "./client.js";
+export { DEFAULT_BASE_URL, SDK_VERSION } from "./constants.js";
+export {
+  CaetherError,
+  APIConnectionError,
+  APITimeoutError,
+  APIStatusError,
+  AuthenticationError,
+  PermissionDeniedError,
+  NotFoundError,
+  RateLimitError,
+  BadRequestError,
+  UnprocessableEntityError,
+  InternalServerError,
+} from "./errors.js";
+
+export * as chat from "./chat/index.js";

package/src/transport.js

@@ -0,0 +1,167 @@
+import {
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_TIMEOUT,
+  SDK_VERSION,
+  USER_AGENT,
+} from "./constants.js";
+import {
+  APIConnectionError,
+  APITimeoutError,
+  errorFromResponse,
+} from "./errors.js";
+
+const RETRY_STATUS = new Set([408, 409, 429, 500, 502, 503, 504]);
+
+function buildHeaders(apiKey, extra) {
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "User-Agent": `${USER_AGENT}/${SDK_VERSION}`,
+  };
+  if (extra) {
+    for (const [k, v] of Object.entries(extra)) {
+      if (v !== undefined && v !== null) headers[k] = v;
+    }
+  }
+  return headers;
+}
+
+function retryDelay(attempt) {
+  return Math.min(500 * 2 ** attempt, 8000);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function parseBody(response) {
+  const ct = response.headers.get("content-type") || "";
+  if (ct.includes("application/json")) {
+    try {
+      return await response.json();
+    } catch {
+      return await response.text();
+    }
+  }
+  return await response.text();
+}
+
+export class Transport {
+  constructor({
+    baseUrl,
+    apiKey,
+    timeout = DEFAULT_TIMEOUT,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    defaultHeaders = {},
+    fetch: fetchImpl,
+  }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.timeout = timeout;
+    this.maxRetries = maxRetries;
+    this.defaultHeaders = defaultHeaders || {};
+    this.fetch = fetchImpl || globalThis.fetch;
+    if (!this.fetch) {
+      throw new APIConnectionError(
+        "No fetch implementation available. Use Node 18+ or pass a fetch option.",
+      );
+    }
+  }
+
+  url(path) {
+    return `${this.baseUrl}/${path.replace(/^\/+/, "")}`;
+  }
+
+  async request(method, path, { body, params, headers, accept } = {}) {
+    const merged = buildHeaders(this.apiKey, {
+      ...this.defaultHeaders,
+      ...(headers || {}),
+    });
+    if (accept) merged.Accept = accept;
+
+    let target = this.url(path);
+    if (params) {
+      const qs = new URLSearchParams(
+        Object.entries(params).filter(([, v]) => v !== undefined && v !== null),
+      ).toString();
+      if (qs) target += `?${qs}`;
+    }
+
+    let lastErr = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      let response;
+      try {
+        response = await this.fetch(target, {
+          method,
+          headers: merged,
+          body: body !== undefined ? JSON.stringify(body) : undefined,
+          signal: controller.signal,
+        });
+      } catch (e) {
+        clearTimeout(timer);
+        if (e.name === "AbortError") {
+          lastErr = new APITimeoutError("Request timed out");
+        } else {
+          lastErr = new APIConnectionError(`Connection error: ${e.message}`);
+        }
+        if (attempt < this.maxRetries) {
+          await sleep(retryDelay(attempt));
+          continue;
+        }
+        throw lastErr;
+      }
+      clearTimeout(timer);
+
+      if (RETRY_STATUS.has(response.status) && attempt < this.maxRetries) {
+        await sleep(retryDelay(attempt));
+        continue;
+      }
+      if (response.status >= 400) {
+        throw errorFromResponse(response.status, await parseBody(response));
+      }
+      return parseBody(response);
+    }
+    throw lastErr || new APIConnectionError("Request failed");
+  }
+
+  async *stream(method, path, { body, headers } = {}) {
+    const merged = buildHeaders(this.apiKey, {
+      ...this.defaultHeaders,
+      ...(headers || {}),
+    });
+    merged.Accept = "text/event-stream";
+
+    const response = await this.fetch(this.url(path), {
+      method,
+      headers: merged,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (response.status >= 400) {
+      throw errorFromResponse(response.status, await parseBody(response));
+    }
+    if (!response.body) return;
+
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const reader = response.body.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop();
+      for (const raw of lines) {
+        const line = raw.trim();
+        if (!line || !line.startsWith("data:")) continue;
+        const data = line.slice(5).trim();
+        if (data === "[DONE]") return;
+        try {
+          yield JSON.parse(data);
+        } catch {
+          /* skip malformed */
+        }
+      }
+    }
+  }
+}