aura-llm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the `aura-llm` TypeScript SDK are documented here.
+This SDK is versioned independently from the gateway.
+
+## [0.1.0] - 2026-06-28
+
+Initial alpha release.
+
+### Added
+- `AuraClient` with a `responses.create()` resource (one-shot + streaming).
+- Universal runtime support (Node 20+, browsers, Deno, Bun, Vercel Edge,
+  Cloudflare Workers) via global `fetch` + Web Streams — no Node-only deps.
+- `AsyncIterable<StreamEvent>` streaming with back-pressure and SSE parsing.
+- Typed error hierarchy (`AuraError` → `APIError` → `AuthenticationError` /
+  `BadRequestError` / `NotFoundError` / `RateLimitError`; plus
+  `APIConnectionError`, `APITimeoutError`) with `instanceof` support.
+- Exponential-backoff retry with jitter; honors `Retry-After`; configurable;
+  off by default for streams.
+- `onRequest` / `onResponse` / `onError` lifecycle hooks.
+- Conversation threading via `previous_response_id`; tools via `functionTool`;
+  multi-tenant `user`; `compression` / `validation` / `consistency` blocks.
+- Response helpers: `outputText`, `toolCalls`, `hasToolCalls`, `isComplete`,
+  `isFailed`.
+- ESM + CJS builds with generated `.d.ts` (tsup).

package/README.md

@@ -0,0 +1,200 @@
+# Aura LLM Gateway — TypeScript SDK
+
+[![npm](https://img.shields.io/npm/v/aura-llm.svg)](https://www.npmjs.com/package/aura-llm)
+
+TypeScript/JavaScript SDK for the [Aura LLM Gateway](https://aura-llm.dev) and
+its Open Responses API. Universal (Node 20+, browsers, Deno, Bun, Vercel Edge,
+Cloudflare Workers) — built on the global `fetch` and Web Streams, with no
+Node-only dependencies. Streaming is exposed as an `AsyncIterable`, and errors
+are a typed hierarchy you can `instanceof`.
+
+This mirrors the [Python SDK](../python/) feature set. There is **one** client
+(JS is async by default) — every call returns a `Promise`, and streaming
+returns an `AsyncIterable`.
+
+## Installation
+
+```bash
+npm install aura-llm
+# or: pnpm add aura-llm / yarn add aura-llm / bun add aura-llm
+```
+
+## Quick start
+
+```ts
+import { AuraClient, outputText } from 'aura-llm'
+
+const client = new AuraClient({
+  apiKey: process.env.AURA_API_KEY, // or set AURA_API_KEY in the environment
+  baseUrl: 'http://localhost:8080', // or AURA_BASE_URL (default localhost:8080)
+})
+
+const response = await client.responses.create({
+  model: 'gpt-5.4-mini',
+  input: 'What is the capital of France?',
+})
+
+console.log(outputText(response))
+// → The capital of France is Paris.
+```
+
+## Streaming
+
+`create({ stream: true })` returns an `AsyncIterable<StreamEvent>` with full
+back-pressure — you only pull events as fast as you consume them.
+
+```ts
+const stream = await client.responses.create({
+  model: 'gpt-5.4-mini',
+  input: 'Tell me a story',
+  stream: true,
+})
+
+for await (const event of stream) {
+  if (event.type === 'response.output_text.delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+> Streaming requests are **not** retried — re-issuing a partial stream would
+> replay events. Errors before the first byte still surface as typed errors.
+
+## Conversation threading
+
+Use `previous_response_id` (the canonical Open Responses mechanism):
+
+```ts
+const r1 = await client.responses.create({ model: 'gpt-5.4-mini', input: 'My name is Alice.' })
+const r2 = await client.responses.create({
+  model: 'gpt-5.4-mini',
+  input: 'What is my name?',
+  previous_response_id: r1.id,
+})
+console.log(outputText(r2)) // → Your name is Alice.
+```
+
+## Tools
+
+```ts
+import { functionTool, toolCalls } from 'aura-llm'
+
+const response = await client.responses.create({
+  model: 'gpt-5.4-mini',
+  input: "What's the weather in Tokyo?",
+  tools: [
+    functionTool('get_weather', 'Get current weather', {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+    }),
+  ],
+})
+
+for (const call of toolCalls(response)) {
+  console.log(call.name, call.arguments)
+}
+```
+
+## Multi-tenancy & config blocks
+
+```ts
+await client.responses.create({
+  model: 'gpt-5.4-mini',
+  input: 'Hello',
+  user: 'customer_42', // end-user cost tracking
+  compression: { strategy: 'toon', auto_select: true },
+  validation: { strategy: 'best_of_n', n: 3, min_confidence: 0.85 },
+  consistency: { style_profile: 'concise' },
+})
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey` | `AURA_API_KEY` env | Bearer token |
+| `baseUrl` | `AURA_BASE_URL` env / `http://localhost:8080` | Gateway URL |
+| `timeout` | `60000` | Per-request timeout (ms); guards time-to-first-byte for streams |
+| `maxRetries` | `2` | Retries for 408/429/5xx + network errors; `0` disables |
+| `headers` | — | Extra headers merged into every request |
+| `fetch` | global `fetch` | Custom fetch (edge runtimes / tests) |
+| `onRequest` / `onResponse` / `onError` | — | Lifecycle hooks |
+
+## Response helpers
+
+Interfaces can't carry methods, so the Python `@property` accessors are
+functions here:
+
+```ts
+import { outputText, toolCalls, hasToolCalls, isComplete, isFailed } from 'aura-llm'
+
+outputText(response)   // assistant text ('' if none)
+toolCalls(response)    // FunctionCallItem[]
+hasToolCalls(response) // boolean
+isComplete(response)   // status === 'completed'
+isFailed(response)     // status === 'failed'
+```
+
+## Error handling
+
+```ts
+import { AuraError, RateLimitError, AuthenticationError } from 'aura-llm'
+
+try {
+  await client.responses.create({ model: 'gpt-5.4-mini', input: 'Hi' })
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    console.log(`Retry after ${err.retryAfter}s`)
+  } else if (err instanceof AuthenticationError) {
+    console.log('Check your API key')
+  } else if (err instanceof AuraError) {
+    console.log(err.status, err.code, err.message, err.requestId)
+  }
+}
+```
+
+Hierarchy: `AuraError` → `APIError` → `AuthenticationError` (401) /
+`BadRequestError` (400) / `NotFoundError` (404) / `RateLimitError` (429); plus
+`APIConnectionError` (network) and `APITimeoutError` (timeout).
+
+## Retry policy
+
+- Retries on: 408, 429, 500, 502, 503, 504, and network errors.
+- Never retries other 4xx, or streaming requests.
+- Exponential backoff with jitter, capped at 30s; honors `Retry-After`.
+
+## Edge runtimes
+
+No Node-only APIs — works on Vercel Edge, Cloudflare Workers, Deno, and Bun
+out of the box. Inject a custom `fetch` if your runtime needs it:
+
+```ts
+const client = new AuraClient({ apiKey, fetch: myFetch })
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `AURA_API_KEY` | API key (used if `apiKey` not passed) |
+| `AURA_BASE_URL` | Gateway base URL (used if `baseUrl` not passed) |
+
+## Development
+
+```bash
+npm install
+npm run build         # tsup → ESM + CJS + .d.ts
+npm test              # vitest
+npm run test:coverage
+npm run typecheck
+```
+
+## Compatibility
+
+Versioned independently from the gateway. This SDK targets the Open Responses
+API as served by aura-proxy ≥ v0.13.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,413 @@
+'use strict';
+
+// src/errors.ts
+var AuraError = class extends Error {
+  /** Gateway error code (e.g. `invalid_model`), when present. */
+  code;
+  /** Offending request parameter, when the gateway reports one. */
+  param;
+  /** HTTP status code, when the error originated from a response. */
+  status;
+  /** Gateway request id for support/correlation, when present. */
+  requestId;
+  /** Raw parsed response body, for debugging. */
+  responseBody;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code;
+    this.param = options.param;
+    this.status = options.status;
+    this.requestId = options.requestId;
+    this.responseBody = options.responseBody;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var APIError = class extends AuraError {
+};
+var AuthenticationError = class extends APIError {
+  constructor(message = "Invalid or missing API key", options = {}) {
+    super(message, { code: "authentication_error", status: 401, ...options });
+  }
+};
+var BadRequestError = class extends APIError {
+  constructor(message, options = {}) {
+    super(message, { code: "invalid_request", status: 400, ...options });
+  }
+};
+var NotFoundError = class extends APIError {
+  constructor(message, options = {}) {
+    super(message, { code: "not_found", status: 404, ...options });
+  }
+};
+var RateLimitError = class extends APIError {
+  /** Seconds to wait before retrying, from the `Retry-After` header. */
+  retryAfter;
+  constructor(message = "Rate limit exceeded", options = {}) {
+    const { retryAfter, ...rest } = options;
+    super(message, { code: "rate_limit_exceeded", status: 429, ...rest });
+    this.retryAfter = retryAfter;
+  }
+};
+var APIConnectionError = class extends AuraError {
+  constructor(message = "Failed to connect to Aura API", options = {}) {
+    super(message, { code: "connection_error", ...options });
+  }
+};
+var APITimeoutError = class extends AuraError {
+  constructor(message = "Request timed out", options = {}) {
+    super(message, { code: "timeout", ...options });
+  }
+};
+function errorFromResponse(status, body, headers) {
+  let code = "unknown_error";
+  let message = `HTTP ${status}`;
+  let param;
+  if (body && typeof body === "object") {
+    const err = body.error;
+    if (err && typeof err === "object") {
+      if (typeof err.code === "string") code = err.code;
+      if (typeof err.message === "string") message = err.message;
+      if (typeof err.param === "string") param = err.param;
+    }
+  }
+  const requestId = headers.get("x-request-id") ?? headers.get("x-aura-request-id") ?? void 0;
+  const base = { code, param, status, requestId, responseBody: body };
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message, base);
+    case 400:
+      return new BadRequestError(message, base);
+    case 404:
+      return new NotFoundError(message, base);
+    case 429: {
+      const ra = headers.get("retry-after");
+      return new RateLimitError(message, {
+        ...base,
+        retryAfter: ra ? Number.parseInt(ra, 10) : void 0
+      });
+    }
+    default:
+      return new APIError(message, base);
+  }
+}
+
+// src/types.ts
+function functionTool(name, description, parameters) {
+  return {
+    type: "function",
+    function: { name, ...description ? { description } : {}, ...parameters ? { parameters } : {} }
+  };
+}
+function outputText(response) {
+  for (const item of response.output) {
+    if (item.type === "message" && item.role === "assistant") {
+      return item.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+    }
+  }
+  return "";
+}
+function toolCalls(response) {
+  return response.output.filter(
+    (item) => item.type === "function_call"
+  );
+}
+var hasToolCalls = (r) => toolCalls(r).length > 0;
+var isComplete = (r) => r.status === "completed";
+var isFailed = (r) => r.status === "failed";
+var STREAM_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "response.created",
+  "response.in_progress",
+  "response.completed",
+  "response.failed",
+  "response.output_item.added",
+  "response.output_item.done",
+  "response.output_text.delta",
+  "response.output_text.done",
+  "response.function_call.delta",
+  "response.function_call.done",
+  "error"
+]);
+var userMessage = (content) => ({ role: "user", content });
+var assistantMessage = (content) => ({
+  role: "assistant",
+  content
+});
+var systemMessage = (content) => ({
+  role: "system",
+  content
+});
+
+// src/streaming.ts
+function parseSSEChunk(chunk) {
+  let eventType = null;
+  const dataLines = [];
+  for (const line of chunk.split("\n")) {
+    if (line.startsWith("event:")) {
+      eventType = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trim());
+    }
+  }
+  if (dataLines.length === 0) return null;
+  const dataStr = dataLines.join("\n");
+  if (dataStr === "[DONE]") return null;
+  let data;
+  try {
+    data = JSON.parse(dataStr);
+  } catch {
+    return null;
+  }
+  const type = eventType ?? (typeof data?.type === "string" ? data.type : null);
+  if (!type || !STREAM_EVENT_TYPES.has(type)) return null;
+  return data;
+}
+async function* parseSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n\n")) !== -1) {
+        const chunk = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 2);
+        const event = parseSSEChunk(chunk);
+        if (event) yield event;
+      }
+    }
+    const tail = (buffer + decoder.decode()).trim();
+    if (tail) {
+      const event = parseSSEChunk(tail);
+      if (event) yield event;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "http://localhost:8080";
+var DEFAULT_TIMEOUT = 6e4;
+var DEFAULT_MAX_RETRIES = 2;
+var SDK_VERSION = "0.1.0";
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+function readEnv(name) {
+  const proc = globalThis.process;
+  return proc?.env?.[name];
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var Responses = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  create(params) {
+    const { stream = false } = params;
+    const payload = this.buildPayload(params);
+    if (stream) {
+      return this.client._stream("/v1/responses", payload);
+    }
+    return this.client._request("POST", "/v1/responses", payload);
+  }
+  buildPayload(params) {
+    const { input, stream = false, ...rest } = params;
+    let inputItems;
+    if (typeof input === "string") {
+      inputItems = [{ role: "user", content: input }];
+    } else {
+      inputItems = input;
+    }
+    const payload = { ...rest, input: inputItems, stream };
+    for (const k of Object.keys(payload)) {
+      if (payload[k] === void 0) delete payload[k];
+    }
+    return payload;
+  }
+};
+var AuraClient = class {
+  baseUrl;
+  timeout;
+  maxRetries;
+  responses;
+  apiKey;
+  headers;
+  fetchFn;
+  opts;
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? readEnv("AURA_API_KEY");
+    this.baseUrl = (options.baseUrl ?? readEnv("AURA_BASE_URL") ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.opts = options;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error(
+        "No global fetch available. Pass a `fetch` implementation in AuraClientOptions."
+      );
+    }
+    this.fetchFn = fetchImpl;
+    this.headers = {
+      "Content-Type": "application/json",
+      "User-Agent": `aura-typescript/${SDK_VERSION}`,
+      ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {},
+      ...options.headers ?? {}
+    };
+    this.responses = new Responses(this);
+  }
+  /** Build an absolute URL + Headers for a request. */
+  prepare(path) {
+    return { url: `${this.baseUrl}${path}`, headers: new Headers(this.headers) };
+  }
+  /** Exponential backoff with jitter, capped at 30s; honors Retry-After. */
+  backoffMs(attempt, retryAfter) {
+    if (retryAfter && Number.isFinite(retryAfter)) return retryAfter * 1e3;
+    return Math.min(2 ** attempt * 1e3 + Math.random() * 1e3, 3e4);
+  }
+  /** Non-streaming JSON request with retry + typed error mapping. */
+  async _request(method, path, body) {
+    const { url, headers } = this.prepare(path);
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      const started = Date.now();
+      this.opts.onRequest?.({ method, url, headers });
+      try {
+        const res = await this.fetchFn(url, {
+          method,
+          headers,
+          body: body !== void 0 ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        this.opts.onResponse?.({ status: res.status, url }, Date.now() - started);
+        if (res.ok) {
+          return await res.json();
+        }
+        const parsed = await safeJson(res);
+        const err = errorFromResponse(res.status, parsed, res.headers);
+        if (RETRYABLE_STATUS.has(res.status) && attempt < this.maxRetries) {
+          lastError = err;
+          const retryAfter = "retryAfter" in err ? err.retryAfter : void 0;
+          await sleep(this.backoffMs(attempt, retryAfter));
+          continue;
+        }
+        this.opts.onError?.(err);
+        throw err;
+      } catch (e) {
+        const mapped = this.mapNetworkError(e);
+        if (mapped) {
+          if (attempt < this.maxRetries) {
+            lastError = mapped;
+            await sleep(this.backoffMs(attempt));
+            continue;
+          }
+          this.opts.onError?.(mapped);
+          throw mapped;
+        }
+        throw e;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw lastError ?? new APIConnectionError("Request failed after retries");
+  }
+  /**
+   * Streaming request → AsyncIterable<StreamEvent>. Streams are NOT retried
+   * (re-issuing a partial stream would replay events); errors before the
+   * first byte still surface as typed errors.
+   */
+  async _stream(path, body) {
+    const { url, headers } = this.prepare(path);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    const started = Date.now();
+    this.opts.onRequest?.({ method: "POST", url, headers });
+    let res;
+    try {
+      res = await this.fetchFn(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (e) {
+      clearTimeout(timer);
+      const mapped = this.mapNetworkError(e);
+      if (mapped) {
+        this.opts.onError?.(mapped);
+        throw mapped;
+      }
+      throw e;
+    }
+    this.opts.onResponse?.({ status: res.status, url }, Date.now() - started);
+    if (!res.ok) {
+      clearTimeout(timer);
+      const parsed = await safeJson(res);
+      const err = errorFromResponse(res.status, parsed, res.headers);
+      this.opts.onError?.(err);
+      throw err;
+    }
+    if (!res.body) {
+      clearTimeout(timer);
+      throw new APIConnectionError("Streaming response had no body");
+    }
+    clearTimeout(timer);
+    return parseSSE(res.body);
+  }
+  /** Map a thrown fetch error to a typed AuraError, or null if not ours. */
+  mapNetworkError(e) {
+    if (e instanceof Error) {
+      if (e.name === "AbortError") return new APITimeoutError(`Request timed out: ${e.message}`);
+      if (e.name === "TypeError" || /fetch failed|network|ECONN|ENOTFOUND/i.test(e.message)) {
+        return new APIConnectionError(`Failed to connect: ${e.message}`);
+      }
+    }
+    return null;
+  }
+};
+async function safeJson(res) {
+  try {
+    return await res.json();
+  } catch {
+    try {
+      return { error: { message: await res.text() } };
+    } catch {
+      return void 0;
+    }
+  }
+}
+
+exports.APIConnectionError = APIConnectionError;
+exports.APIError = APIError;
+exports.APITimeoutError = APITimeoutError;
+exports.AuraClient = AuraClient;
+exports.AuraError = AuraError;
+exports.AuthenticationError = AuthenticationError;
+exports.BadRequestError = BadRequestError;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_MAX_RETRIES = DEFAULT_MAX_RETRIES;
+exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
+exports.NotFoundError = NotFoundError;
+exports.RateLimitError = RateLimitError;
+exports.Responses = Responses;
+exports.STREAM_EVENT_TYPES = STREAM_EVENT_TYPES;
+exports.assistantMessage = assistantMessage;
+exports.functionTool = functionTool;
+exports.hasToolCalls = hasToolCalls;
+exports.isComplete = isComplete;
+exports.isFailed = isFailed;
+exports.outputText = outputText;
+exports.parseSSE = parseSSE;
+exports.parseSSEChunk = parseSSEChunk;
+exports.systemMessage = systemMessage;
+exports.toolCalls = toolCalls;
+exports.userMessage = userMessage;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map