@skailar-ai/sdk 0.0.1

package/dist/index.cjs

@@ -0,0 +1,861 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/errors.ts
+function parseErrorBody(body) {
+  if (typeof body !== "object" || body === null) {
+    return { code: void 0, message: void 0 };
+  }
+  const root = body;
+  const err = root["error"];
+  if (typeof err === "string") {
+    const message = typeof root["message"] === "string" ? root["message"] : err;
+    return { code: err, message };
+  }
+  if (typeof err === "object" && err !== null) {
+    const nested = err;
+    const code = typeof nested["type"] === "string" ? nested["type"] : typeof nested["code"] === "string" ? nested["code"] : void 0;
+    const message = typeof nested["message"] === "string" ? nested["message"] : void 0;
+    return { code, message };
+  }
+  const topMessage = typeof root["message"] === "string" ? root["message"] : void 0;
+  return { code: void 0, message: topMessage };
+}
+var SkailarError = class extends Error {
+  /** HTTP status code, or `null` for non-HTTP failures (e.g. network). */
+  status;
+  /** Machine-readable error code from the body, if any. */
+  code;
+  /** Correlation id from the `x-request-id` response header, if any. */
+  requestId;
+  /** The raw response body captured for debugging. */
+  raw;
+  /**
+   * @param status - HTTP status, or `null` when not applicable.
+   * @param options - Message, code, request id, raw body and cause.
+   */
+  constructor(status, options = {}) {
+    super(options.message ?? "Skailar SDK error", { cause: options.cause });
+    this.name = new.target.name;
+    this.status = status;
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.raw = options.raw;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var SkailarConnectionError = class extends SkailarError {
+  /** @param options - Message and originating cause. */
+  constructor(options = {}) {
+    super(null, {
+      message: options.message ?? "Failed to connect to the Skailar API",
+      cause: options.cause
+    });
+  }
+};
+var SkailarAPIError = class _SkailarAPIError extends SkailarError {
+  /**
+   * @param status - The HTTP status code of the response.
+   * @param options - Message, code, request id and raw body.
+   */
+  constructor(status, options = {}) {
+    super(status, options);
+  }
+  /**
+   * Build the most specific {@link SkailarAPIError} subclass for a status code.
+   *
+   * @param status - The HTTP status code returned by the gateway.
+   * @param parsed - The normalized `{ code, message }` from {@link parseErrorBody}.
+   * @param requestId - The `x-request-id` header value, if present.
+   * @param raw - The raw response body for diagnostics.
+   * @param retryAfter - Seconds from a `Retry-After` header, for 429 responses.
+   * @returns A {@link SkailarAuthError}, {@link SkailarBadRequestError},
+   * {@link SkailarNotFoundError}, {@link SkailarRateLimitError},
+   * {@link SkailarUpstreamError}, or a plain {@link SkailarAPIError}.
+   */
+  static from(status, parsed, requestId, raw, retryAfter) {
+    const options = {
+      message: parsed.message,
+      code: parsed.code,
+      requestId,
+      raw
+    };
+    switch (status) {
+      case 401:
+        return new SkailarAuthError(options);
+      case 400:
+        return new SkailarBadRequestError(options);
+      case 404:
+        return new SkailarNotFoundError(options);
+      case 429:
+        return new SkailarRateLimitError({ ...options, retryAfter });
+      default:
+        if (status >= 500) return new SkailarUpstreamError(status, options);
+        return new _SkailarAPIError(status, options);
+    }
+  }
+};
+var SkailarAuthError = class extends SkailarAPIError {
+  /** @param options - Error details. */
+  constructor(options = {}) {
+    super(401, { message: "Invalid or missing API key", ...options });
+  }
+};
+var SkailarBadRequestError = class extends SkailarAPIError {
+  /** @param options - Error details. */
+  constructor(options = {}) {
+    super(400, { message: "Bad request", ...options });
+  }
+};
+var SkailarNotFoundError = class extends SkailarAPIError {
+  /** @param options - Error details. */
+  constructor(options = {}) {
+    super(404, { message: "Resource not found", ...options });
+  }
+};
+var SkailarRateLimitError = class extends SkailarAPIError {
+  /** Seconds to wait before retrying, parsed from `Retry-After`; `undefined` if absent/unparseable. */
+  retryAfter;
+  /** @param options - Error details plus the optional `retryAfter` seconds. */
+  constructor(options = {}) {
+    super(429, { message: "Rate limit exceeded", ...options });
+    this.retryAfter = options.retryAfter;
+  }
+};
+var SkailarUpstreamError = class extends SkailarAPIError {
+  /**
+   * @param status - The specific 5xx status code.
+   * @param options - Error details.
+   */
+  constructor(status, options = {}) {
+    super(status, { message: "Upstream provider error", ...options });
+  }
+};
+
+// src/streaming.ts
+async function* parseSSE(stream, signal) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        throw new SkailarConnectionError({ message: "Stream aborted", cause: signal.reason });
+      }
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newlineIndex;
+      while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+        const rawLine = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        if (line === "" || line.startsWith(":")) continue;
+        if (!line.startsWith("data:")) continue;
+        const data = line.slice(5).trimStart();
+        if (data === "[DONE]") return;
+        yield data;
+      }
+    }
+    const tail = buffer.trim();
+    if (tail.startsWith("data:")) {
+      const data = tail.slice(5).trimStart();
+      if (data !== "[DONE]" && data !== "") yield data;
+    }
+  } catch (err) {
+    if (err instanceof SkailarConnectionError) throw err;
+    throw new SkailarConnectionError({ message: "Stream read failed", cause: err });
+  } finally {
+    await reader.cancel().catch(() => {
+    });
+    reader.releaseLock();
+  }
+}
+var ChatCompletionStream = class {
+  /**
+   * The {@link AbortController} governing the underlying HTTP request. Call
+   * `stream.controller.abort()` to cancel an in-flight stream; the active
+   * `for await` loop then terminates promptly.
+   */
+  controller;
+  /** The raw SSE byte stream backing this iterator. */
+  body;
+  /**
+   * @param body - The response body stream of SSE bytes.
+   * @param controller - The abort controller tied to the originating request.
+   */
+  constructor(body, controller) {
+    this.body = body;
+    this.controller = controller;
+  }
+  /**
+   * Decode the SSE byte stream into typed chunks.
+   *
+   * Each `data:` payload is `JSON.parse`d. If a payload carries an `error` field
+   * (the gateway's in-band failure signal), iteration throws the corresponding
+   * {@link SkailarAPIError} instead of yielding. Malformed JSON payloads are
+   * skipped defensively.
+   *
+   * @returns An async generator over {@link ChatCompletionChunk} values.
+   * @throws {@link SkailarAPIError} When the stream delivers an in-band error event.
+   * @throws {@link SkailarConnectionError} When the stream is aborted or read fails.
+   */
+  async *decode() {
+    for await (const data of parseSSE(this.body, this.controller.signal)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (parsed !== null && typeof parsed === "object" && "error" in parsed) {
+        const { code, message } = parseErrorBody(parsed);
+        throw SkailarAPIError.from(
+          500,
+          { code, message: message ?? "Streaming error" },
+          void 0,
+          parsed
+        );
+      }
+      yield parsed;
+    }
+  }
+  /**
+   * Iterate the decoded chunks. Abandoning the iteration early (a `break` or
+   * `return` inside a `for await`) invokes the returned iterator's `return()`,
+   * which aborts {@link ChatCompletionStream.controller} so the underlying fetch
+   * request is cancelled — not merely the body reader — and then runs the
+   * generator's own cleanup ({@link parseSSE}'s `finally`: reader cancel +
+   * lock release). Normal completion and thrown errors are unaffected.
+   *
+   * @returns An async iterator over {@link ChatCompletionChunk} values.
+   */
+  [Symbol.asyncIterator]() {
+    const inner = this.decode();
+    const controller = this.controller;
+    return {
+      next: () => inner.next(),
+      async return(value) {
+        controller.abort();
+        if (inner.return) await inner.return(value);
+        return { done: true, value: void 0 };
+      },
+      throw: (err) => inner.throw ? inner.throw(err) : Promise.reject(err)
+    };
+  }
+};
+
+// src/resources/chat.ts
+var ChatCompletions = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Implementation backing the public overloads.
+   *
+   * @param body - The chat completion request.
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns Either a {@link ChatCompletion} or a {@link ChatCompletionStream}
+   * depending on `body.stream`.
+   * @throws {@link SkailarBadRequestError} On HTTP 400 (malformed request).
+   * @throws {@link SkailarAuthError} On HTTP 401 (bad key).
+   * @throws {@link SkailarRateLimitError} On HTTP 429 (after exhausting retries).
+   * @throws {@link SkailarUpstreamError} On HTTP 5xx (after exhausting retries).
+   * @throws {@link SkailarConnectionError} On network failure, timeout or abort.
+   */
+  create(body, options) {
+    if (body.stream === true) {
+      return this.client.request({
+        method: "POST",
+        path: "/v1/chat/completions",
+        body,
+        expect: "stream",
+        signal: options?.signal,
+        timeout: options?.timeout,
+        headers: options?.headers
+      });
+    }
+    return this.client.request({
+      method: "POST",
+      path: "/v1/chat/completions",
+      body,
+      expect: "json",
+      signal: options?.signal,
+      timeout: options?.timeout,
+      headers: options?.headers
+    });
+  }
+};
+var ChatResource = class {
+  /** The chat completions namespace. */
+  completions;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.completions = new ChatCompletions(client);
+  }
+};
+
+// src/resources/models.ts
+var ModelsResource = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List every model the gateway can route to. Unwraps the
+   * `{ object: "list", data }` envelope and returns just `data` as a plain array.
+   *
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns A promise resolving to the array of {@link ModelSummary} cards.
+   */
+  async list(options) {
+    const res = await this.client.request({
+      method: "GET",
+      path: "/v1/models",
+      expect: "json",
+      signal: options?.signal,
+      timeout: options?.timeout,
+      headers: options?.headers
+    });
+    return res.data;
+  }
+  /**
+   * Retrieve the full detail card for a single model.
+   *
+   * @param id - The model identifier; may contain slashes (e.g.
+   * `"google/gemini-2.5-pro"`), which are preserved in the path.
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns A promise resolving to the {@link Model} detail.
+   * @throws {@link SkailarNotFoundError} If no model matches the id.
+   */
+  retrieve(id, options) {
+    const encoded = id.split("/").map(encodeURIComponent).join("/");
+    return this.client.request({
+      method: "GET",
+      path: `/v1/models/${encoded}`,
+      expect: "json",
+      signal: options?.signal,
+      timeout: options?.timeout,
+      headers: options?.headers
+    });
+  }
+};
+
+// src/resources/images.ts
+var ImagesResource = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Generate one or more images from a text prompt. Named `generate` to match
+   * `openai`'s `images.generate(...)`.
+   *
+   * @param body - The generation request; see {@link ImageGenerationRequest}.
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns A promise resolving to the {@link ImageGenerationResponse}, whose
+   * `data` entries carry either a `url` or inline `b64_json`.
+   * @throws {@link SkailarBadRequestError} On HTTP 400.
+   * @throws {@link SkailarRateLimitError} On HTTP 429 (after exhausting retries).
+   */
+  generate(body, options) {
+    return this.client.request({
+      method: "POST",
+      path: "/v1/images/generations",
+      body,
+      expect: "json",
+      signal: options?.signal,
+      timeout: options?.timeout,
+      headers: options?.headers
+    });
+  }
+};
+
+// src/internal/binary.ts
+function bytesToBase64(bytes) {
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) {
+    return maybeBuffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  const chunkSize = 32768;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    const chunk = bytes.subarray(i, i + chunkSize);
+    binary += String.fromCharCode(...chunk);
+  }
+  return btoa(binary);
+}
+async function toBase64(input) {
+  if (typeof input === "string") return input;
+  if (input instanceof Uint8Array) return bytesToBase64(input);
+  if (input instanceof ArrayBuffer) return bytesToBase64(new Uint8Array(input));
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    const buffer = await input.arrayBuffer();
+    return bytesToBase64(new Uint8Array(buffer));
+  }
+  throw new TypeError("Unsupported binary input; expected Uint8Array, ArrayBuffer, Blob or base64 string");
+}
+
+// src/resources/audio.ts
+var AudioTranscriptions = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Transcribe an audio clip to text. The supplied bytes are base64-encoded
+   * client-side into the gateway's `base64` field. When `mime` is omitted and
+   * `file` is a {@link Blob} carrying a `type`, that type is used; otherwise the
+   * gateway default (`audio/wav`) applies.
+   *
+   * @param params - The audio and its MIME type; see {@link TranscriptionCreateParams}.
+   * `file` may be a {@link Uint8Array}, {@link ArrayBuffer}, {@link Blob} or a
+   * pre-encoded base64 string.
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns A promise resolving to the {@link TranscriptionResponse}.
+   */
+  async create(params, options) {
+    const base64 = await toBase64(params.file);
+    const mime = params.mime ?? (typeof Blob !== "undefined" && params.file instanceof Blob && params.file.type ? params.file.type : void 0);
+    return this.client.request({
+      method: "POST",
+      path: "/v1/audio/transcriptions",
+      body: { base64, mime },
+      expect: "json",
+      signal: options?.signal,
+      timeout: options?.timeout,
+      headers: options?.headers
+    });
+  }
+};
+var AudioSpeech = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Synthesize speech and return the raw MP3 audio stream. Unlike the JSON
+   * endpoints, this returns the response body stream directly so large audio
+   * payloads need not be buffered in memory.
+   *
+   * Pass `options.signal` to cancel the request: aborting it before the response
+   * arrives rejects this call, and aborting it while the MP3 is still downloading
+   * tears down the underlying connection so the body stops mid-stream.
+   *
+   * @param params - The text and voice; see {@link SpeechCreateParams}.
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns A promise resolving to a `ReadableStream<Uint8Array>` of
+   * `audio/mpeg` bytes, suitable for piping to a file, an HTTP response, or an
+   * audio element.
+   * @throws {@link SkailarConnectionError} If the response unexpectedly lacks a body.
+   * @throws {@link SkailarBadRequestError} On HTTP 400 (e.g. text exceeding 4000 chars).
+   */
+  async create(params, options) {
+    const response = await this.client.request({
+      method: "POST",
+      path: "/v1/audio/speech",
+      body: { input: params.input, voice: params.voice },
+      headers: { Accept: "audio/mpeg", ...options?.headers },
+      expect: "response",
+      signal: options?.signal,
+      timeout: options?.timeout
+    });
+    if (!response.body) {
+      throw new SkailarConnectionError({ message: "Speech response had no audio body" });
+    }
+    return response.body;
+  }
+};
+var AudioResource = class {
+  /** Speech-to-text operations. */
+  transcriptions;
+  /** Text-to-speech operations. */
+  speech;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.transcriptions = new AudioTranscriptions(client);
+    this.speech = new AudioSpeech(client);
+  }
+};
+
+// src/resources/uploads.ts
+var ImageUploads = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upload an image and obtain a URL usable as vision input. `data` may be a
+   * {@link Uint8Array}, {@link ArrayBuffer}, {@link Blob} or a pre-encoded base64
+   * string; it is base64-encoded client-side into the gateway's `base64` field.
+   *
+   * @param params - The image bytes and content type; see {@link ImageUploadCreateParams}.
+   * @returns A promise resolving to the {@link UploadResponse} whose `url` can be
+   * embedded in a chat completion as an `image_url` content part.
+   */
+  async create(params) {
+    const base64 = await toBase64(params.data);
+    return this.client.request({
+      method: "POST",
+      path: "/v1/uploads/images",
+      body: { base64, content_type: params.contentType },
+      expect: "json"
+    });
+  }
+};
+var FileUploads = class {
+  /** The owning client used to dispatch requests. */
+  client;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upload a document (`application/pdf` or `text/plain`). `data` accepts the
+   * same forms as image upload and is base64-encoded client-side.
+   *
+   * @param params - The document bytes and content type; see {@link FileUploadCreateParams}.
+   * @returns A promise resolving to the {@link UploadResponse} with the stored asset URL.
+   */
+  async create(params) {
+    const base64 = await toBase64(params.data);
+    return this.client.request({
+      method: "POST",
+      path: "/v1/uploads/files",
+      body: { base64, content_type: params.contentType },
+      expect: "json"
+    });
+  }
+};
+var UploadsResource = class {
+  /** Image upload operations. */
+  images;
+  /** File/document upload operations. */
+  files;
+  /** @param client - The owning {@link Skailar} client. */
+  constructor(client) {
+    this.images = new ImageUploads(client);
+    this.files = new FileUploads(client);
+  }
+};
+
+// src/client.ts
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new SkailarConnectionError({ message: "Aborted", cause: signal.reason }));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new SkailarConnectionError({ message: "Aborted", cause: signal?.reason }));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds);
+  const date = Date.parse(header);
+  if (Number.isFinite(date)) return Math.max(0, Math.ceil((date - Date.now()) / 1e3));
+  return void 0;
+}
+function withCleanup(source, onDone) {
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    onDone();
+  };
+  const reader = source.getReader();
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done: streamDone, value } = await reader.read();
+        if (streamDone) {
+          finish();
+          controller.close();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (err) {
+        finish();
+        controller.error(err);
+      }
+    },
+    async cancel(reason) {
+      finish();
+      await reader.cancel(reason);
+    }
+  });
+}
+function extractRequestId(headers) {
+  return headers.get("x-request-id") ?? headers.get("x-skailar-request-id") ?? headers.get("request-id") ?? void 0;
+}
+var Skailar = class {
+  /** Resolved API key sent as the bearer token. */
+  apiKey;
+  /** Resolved base URL with any trailing slash removed. */
+  baseURL;
+  /** Resolved per-attempt timeout in milliseconds. */
+  timeout;
+  /** Resolved maximum retry count. */
+  maxRetries;
+  /** Default headers merged into every request. */
+  defaultHeaders;
+  /** The `fetch` implementation used for all requests. */
+  fetchImpl;
+  /** Chat completions (OpenAI-compatible). */
+  chat;
+  /** Model discovery. */
+  models;
+  /** Image generation. */
+  images;
+  /** Speech synthesis and transcription. */
+  audio;
+  /** Direct uploads to Skailar storage. */
+  uploads;
+  /**
+   * @param options - Client configuration; see {@link SkailarOptions}.
+   * @throws If no API key is resolvable (neither `options.apiKey` nor
+   * `SKAILAR_API_KEY`). A key that is present but malformed is **not** rejected
+   * here; it fails at the first request with a {@link SkailarAuthError}.
+   */
+  constructor(options = {}) {
+    const env = typeof process !== "undefined" && process.env ? process.env["SKAILAR_API_KEY"] : void 0;
+    const apiKey = options.apiKey ?? env;
+    if (!apiKey) {
+      throw new Error(
+        "Missing Skailar API key. Pass { apiKey } or set the SKAILAR_API_KEY environment variable."
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseURL = (options.baseURL ?? "https://api.skailar.com").replace(/\/+$/, "");
+    this.timeout = options.timeout ?? 6e4;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error("No fetch implementation available; pass { fetch } explicitly.");
+    }
+    this.chat = new ChatResource(this);
+    this.models = new ModelsResource(this);
+    this.images = new ImagesResource(this);
+    this.audio = new AudioResource(this);
+    this.uploads = new UploadsResource(this);
+  }
+  /**
+   * Verify the configured API key against `GET /v1/ping-key`.
+   *
+   * @param options - Optional per-call signal, timeout and headers.
+   * @returns The `{ status, user_id }` payload when the key is valid.
+   * @throws {@link SkailarAuthError} If the key is missing, invalid or revoked.
+   */
+  ping(options) {
+    return this.request({
+      method: "GET",
+      path: "/v1/ping-key",
+      expect: "json",
+      signal: options?.signal,
+      timeout: options?.timeout,
+      headers: options?.headers
+    });
+  }
+  /**
+   * Core dispatch implementation shared by all resources.
+   *
+   * Applies, per attempt: header assembly with bearer auth, a timeout-derived
+   * {@link AbortSignal} composed with any caller signal, execution of
+   * {@link SkailarOptions.fetch}, and error mapping. Retries HTTP 429, HTTP 5xx
+   * and transient connection failures up to {@link Skailar.maxRetries}, backing
+   * off with full-jitter exponential delay and honoring a server `Retry-After`
+   * when present. Non-429 4xx responses fail fast.
+   *
+   * Transport failures are reported as {@link SkailarConnectionError} with a
+   * message distinguishing three causes: an external `signal` abort
+   * (non-retryable), an internal timeout once {@link Skailar.timeout} elapses
+   * (retryable), and a generic network failure (retryable).
+   *
+   * @param options - The request description.
+   * @returns The parsed JSON, raw `Response`, or {@link ChatCompletionStream}
+   * depending on `options.expect`.
+   */
+  async request(options) {
+    const url = `${this.baseURL}${options.path}`;
+    const isStream = options.expect === "stream";
+    const timeoutMs = options.timeout ?? this.timeout;
+    let attempt = 0;
+    while (true) {
+      const controller = new AbortController();
+      const onExternalAbort = () => controller.abort(options.signal?.reason);
+      if (options.signal) {
+        if (options.signal.aborted) controller.abort(options.signal.reason);
+        else options.signal.addEventListener("abort", onExternalAbort);
+      }
+      const detachExternal = () => options.signal?.removeEventListener("abort", onExternalAbort);
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new Error("Request timed out"));
+      }, timeoutMs);
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method: options.method,
+          headers: this.buildHeaders(options),
+          body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+          signal: controller.signal
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        detachExternal();
+        const externallyAborted = options.signal?.aborted ?? false;
+        const connErr = new SkailarConnectionError({
+          message: externallyAborted ? "Request aborted" : timedOut ? `Request timed out after ${timeoutMs}ms` : "Network request to the Skailar API failed",
+          cause: err
+        });
+        if (externallyAborted || !this.shouldRetry(attempt)) throw connErr;
+        attempt += 1;
+        await delay(this.backoff(attempt), options.signal);
+        continue;
+      }
+      clearTimeout(timer);
+      if (!response.ok) {
+        detachExternal();
+        const apiError = await this.toApiError(response);
+        const retryAfterMs = apiError instanceof SkailarRateLimitError && apiError.retryAfter !== void 0 ? apiError.retryAfter * 1e3 : void 0;
+        if (this.isRetryableStatus(response.status) && this.shouldRetry(attempt)) {
+          attempt += 1;
+          await delay(retryAfterMs ?? this.backoff(attempt), options.signal);
+          continue;
+        }
+        throw apiError;
+      }
+      if (isStream || options.expect === "response") {
+        if (!response.body) {
+          detachExternal();
+          throw new SkailarConnectionError({
+            message: isStream ? "Streaming response had no body" : "Response had no body"
+          });
+        }
+        const body = withCleanup(response.body, detachExternal);
+        if (isStream) return new ChatCompletionStream(body, controller);
+        return new Response(body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers
+        });
+      }
+      detachExternal();
+      return await response.json();
+    }
+  }
+  /**
+   * Assemble the outgoing header set for a request, applying defaults, auth,
+   * content-type and accept in precedence order.
+   *
+   * @param options - The request description.
+   * @returns The header record to send.
+   */
+  buildHeaders(options) {
+    const headers = {
+      ...this.defaultHeaders,
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: options.expect === "stream" ? "text/event-stream" : "application/json"
+    };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (options.headers) Object.assign(headers, options.headers);
+    return headers;
+  }
+  /**
+   * Convert a non-2xx {@link Response} into the most specific
+   * {@link SkailarAPIError} subclass. Reads the body once, attempting JSON first
+   * and falling back to raw text, then defers classification to
+   * {@link SkailarAPIError.from}.
+   *
+   * @param response - The failed HTTP response.
+   * @returns The mapped error.
+   */
+  async toApiError(response) {
+    const text = await response.text().catch(() => "");
+    let raw = text;
+    try {
+      raw = text ? JSON.parse(text) : void 0;
+    } catch {
+      raw = text;
+    }
+    const parsed = parseErrorBody(raw);
+    const requestId = extractRequestId(response.headers);
+    const retryAfter = response.status === 429 ? parseRetryAfter(response.headers.get("retry-after")) : void 0;
+    return SkailarAPIError.from(response.status, parsed, requestId, raw, retryAfter);
+  }
+  /**
+   * Whether a status code is eligible for automatic retry (429 and any 5xx).
+   *
+   * @param status - The HTTP status code.
+   * @returns `true` if retryable.
+   */
+  isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+  }
+  /**
+   * Whether another attempt remains within the retry budget.
+   *
+   * @param attempt - The count of attempts already made (before increment).
+   * @returns `true` if a retry is permitted.
+   */
+  shouldRetry(attempt) {
+    return attempt < this.maxRetries;
+  }
+  /**
+   * Compute a full-jitter exponential backoff delay: a random value in
+   * `[0, min(cap, base * 2^attempt))`, capped at 8000ms. Jitter spreads retries
+   * from many clients to avoid synchronized thundering-herd load on the gateway.
+   *
+   * @param attempt - The retry number, starting at 1 for the first retry.
+   * @returns A randomized delay in milliseconds.
+   */
+  backoff(attempt) {
+    const base = 500;
+    const cap = 8e3;
+    const exponential = Math.min(cap, base * 2 ** attempt);
+    return Math.random() * exponential;
+  }
+};
+
+// src/index.ts
+var index_default = Skailar;
+
+exports.ChatCompletionStream = ChatCompletionStream;
+exports.Skailar = Skailar;
+exports.SkailarAPIError = SkailarAPIError;
+exports.SkailarAuthError = SkailarAuthError;
+exports.SkailarBadRequestError = SkailarBadRequestError;
+exports.SkailarConnectionError = SkailarConnectionError;
+exports.SkailarError = SkailarError;
+exports.SkailarNotFoundError = SkailarNotFoundError;
+exports.SkailarRateLimitError = SkailarRateLimitError;
+exports.SkailarUpstreamError = SkailarUpstreamError;
+exports.default = index_default;
+exports.parseSSE = parseSSE;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map