@skailar-ai/sdk 0.0.3 → 0.0.4

package/dist/index.d.ts

@@ -309,11 +309,11 @@ interface ChatCompletionChunk {
  * arrival order, excluding the terminal `[DONE]` sentinel.
  *
  * Implements just the slice of the SSE grammar the gateway emits: UTF-8 `data:`
- * lines separated by `\n`, events delimited by blank lines, terminated by a
- * literal `data: [DONE]`. A partial line left in the buffer across reads is
- * preserved and completed by the next chunk. Comment lines (`:` prefix) and
- * non-`data:` fields are ignored. Yielding stops at `[DONE]`; reaching
- * end-of-stream without `[DONE]` simply ends the generator.
+ * lines terminated by any of `\n`, `\r\n` or `\r` (per the SSE spec), events
+ * delimited by blank lines, terminated by a literal `data: [DONE]`. A partial
+ * line left in the buffer across reads is preserved and completed by the next
+ * chunk. Comment lines (`:` prefix) and non-`data:` fields are ignored. Yielding
+ * stops at `[DONE]`; reaching end-of-stream without `[DONE]` simply ends the generator.
  *
  * On any exit — normal completion, `[DONE]`, an error, or the consumer
  * abandoning the `for await` early — the reader is cancelled before its lock is
@@ -365,12 +365,15 @@ declare class ChatCompletionStream implements AsyncIterable<ChatCompletionChunk>
      *
      * 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.
+     * {@link SkailarAPIError} instead of yielding. A payload that is not valid JSON
+     * (e.g. a plain-text error injected by an intermediary) throws a
+     * {@link SkailarConnectionError} rather than being dropped, so a malformed
+     * stream cannot truncate the response silently.
      *
      * @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.
+     * @throws {@link SkailarConnectionError} When a payload is malformed, or the
+     * stream is aborted or fails to read.
      */
     private decode;
     /**
@@ -890,7 +893,11 @@ interface SkailarOptions {
      * The format is **not** validated locally — only emptiness is checked. A
      * malformed or wrong-provider key (e.g. an OpenAI `sk-...` key passed by
      * mistake) is accepted here and rejected at the first request with a
-     * {@link SkailarAuthError} (HTTP 401).
+     * {@link SkailarAuthError} (HTTP 401). Note this means such a key is **sent to
+     * {@link SkailarOptions.baseURL}** before it is rejected; if you point
+     * `baseURL` at a third-party host, take care not to forward a credential meant
+     * for a different provider. Keep the default `baseURL` unless you control the
+     * endpoint.
      */
     apiKey?: string;
     /**
@@ -900,9 +907,18 @@ interface SkailarOptions {
      */
     baseURL?: string;
     /**
-     * Per-request timeout in milliseconds (default `60000`). Applies to each
-     * attempt independently; a timed-out attempt becomes a
-     * {@link SkailarConnectionError} and is eligible for retry.
+     * Timeout in milliseconds applied to **each attempt** (default `60000`). A
+     * timed-out attempt becomes a {@link SkailarConnectionError} and, for
+     * idempotent requests, is eligible for retry.
+     *
+     * @remarks
+     * This is **per attempt, not a total deadline**. With retries enabled the
+     * worst-case wall-clock for one call is roughly
+     * `(maxRetries + 1) × timeout + backoff` — e.g. the defaults (60s, 2 retries)
+     * can keep a call pending for ~3 minutes on a persistently slow endpoint. In
+     * environments with their own hard limits (serverless/Lambda, HTTP handlers),
+     * enforce an end-to-end bound by passing an `AbortSignal` (and/or a smaller
+     * per-call `timeout`) in the request options, or set `maxRetries: 0`.
      */
     timeout?: number;
     /**
@@ -918,8 +934,9 @@ interface SkailarOptions {
      */
     fetch?: typeof fetch;
     /**
-     * Headers merged into every request. The SDK's own `Authorization`,
-     * `Content-Type` and `Accept`, plus explicit per-call headers, take precedence.
+     * Headers merged into every request. Per-call `options.headers` override these.
+     * The SDK's `Authorization` always wins and cannot be overridden; `Accept` and
+     * `Content-Type` default to SDK values but may be overridden here or per call.
      */
     defaultHeaders?: Record<string, string>;
 }
@@ -942,7 +959,11 @@ interface RequestOptions {
      * for this request only.
      */
     timeout?: number;
-    /** Extra headers merged into this request, overriding client defaults. */
+    /**
+     * Extra headers merged into this request, overriding client `defaultHeaders`.
+     * Cannot override `Authorization` (always set by the SDK); may override `Accept`
+     * and `Content-Type`.
+     */
     headers?: Record<string, string>;
 }
 /** Internal description of a single HTTP request to dispatch. */
@@ -963,6 +984,15 @@ interface InternalRequest {
     signal?: AbortSignal;
     /** Per-call timeout override in ms; falls back to {@link Skailar.timeout}. */
     timeout?: number;
+    /**
+     * Whether the request is safe to replay after a 5xx, timeout or connection
+     * failure — i.e. the server either did not execute it or executing it twice is
+     * harmless. `GET`s and text completions are idempotent; operations with billed
+     * side effects (image generation, speech, transcription, uploads) are not, and
+     * must not be retried once the request may have reached the server. A `429` is
+     * always retryable regardless, since it is rejected before execution.
+     */
+    idempotent?: boolean;
 }
 /**
  * The official Skailar API client. Construct once and reuse. Resource namespaces
@@ -1049,8 +1079,14 @@ declare class Skailar {
         expect: "stream";
     }): Promise<ChatCompletionStream>;
     /**
-     * Assemble the outgoing header set for a request, applying defaults, auth,
-     * content-type and accept in precedence order.
+     * Assemble the outgoing header set for a request.
+     *
+     * Precedence (later wins): client `defaultHeaders` → the SDK's default `Accept`
+     * and `Content-Type` → per-call `options.headers` → `Authorization`.
+     * `Authorization` is applied **last** so a caller-supplied header (including a
+     * blindly proxied incoming one) can never override or drop the bearer token and
+     * leak it elsewhere. `Accept`/`Content-Type` remain overridable on purpose —
+     * e.g. audio speech sends `Accept: audio/mpeg`.
      *
      * @param options - The request description.
      * @returns The header record to send.
@@ -1067,9 +1103,15 @@ declare class Skailar {
      */
     private toApiError;
     /**
-     * Whether a status code is eligible for automatic retry (429 and any 5xx).
+     * Whether an HTTP error status is eligible for automatic retry.
+     *
+     * A `429` is always retryable: the gateway rejects it before executing the
+     * request, so replaying it cannot duplicate side effects. A `5xx` may mean the
+     * request already executed server-side, so it is retried only when the caller
+     * marked the request idempotent.
      *
      * @param status - The HTTP status code.
+     * @param idempotent - Whether replaying the request is safe.
      * @returns `true` if retryable.
      */
     private isRetryableStatus;
@@ -1140,7 +1182,14 @@ declare abstract class SkailarError extends Error {
     readonly status: number | null;
     /** Machine-readable error code from the body, if any. */
     readonly code: string | undefined;
-    /** Correlation id from the `x-request-id` response header, if any. */
+    /**
+     * Correlation id from the `x-request-id` response header, if any, for support.
+     *
+     * @remarks
+     * Populated on error responses. It is **not** currently surfaced for successful
+     * streaming or audio responses (which return a stream rather than a wrapper),
+     * so capture it from a thrown {@link SkailarError} when filing a ticket.
+     */
     readonly requestId: string | undefined;
     /** The raw response body captured for debugging. */
     readonly raw: unknown;

package/dist/index.js

@@ -23,7 +23,14 @@ var SkailarError = class extends Error {
   status;
   /** Machine-readable error code from the body, if any. */
   code;
-  /** Correlation id from the `x-request-id` response header, if any. */
+  /**
+   * Correlation id from the `x-request-id` response header, if any, for support.
+   *
+   * @remarks
+   * Populated on error responses. It is **not** currently surfaced for successful
+   * streaming or audio responses (which return a stream rather than a wrapper),
+   * so capture it from a thrown {@link SkailarError} when filing a ticket.
+   */
   requestId;
   /** The raw response body captured for debugging. */
   raw;
@@ -134,6 +141,25 @@ async function* parseSSE(stream, signal) {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
+  function nextLine() {
+    let i = -1;
+    for (let j = 0; j < buffer.length; j++) {
+      const c = buffer[j];
+      if (c === "\n" || c === "\r") {
+        i = j;
+        break;
+      }
+    }
+    if (i === -1) return null;
+    const line = buffer.slice(0, i);
+    if (buffer[i] === "\r") {
+      if (i === buffer.length - 1) return null;
+      buffer = buffer.slice(i + (buffer[i + 1] === "\n" ? 2 : 1));
+    } else {
+      buffer = buffer.slice(i + 1);
+    }
+    return line;
+  }
   try {
     while (true) {
       if (signal?.aborted) {
@@ -142,11 +168,8 @@ async function* parseSSE(stream, signal) {
       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;
+      let line;
+      while ((line = nextLine()) !== null) {
         if (line === "" || line.startsWith(":")) continue;
         if (!line.startsWith("data:")) continue;
         const data = line.slice(5).trimStart();
@@ -154,7 +177,7 @@ async function* parseSSE(stream, signal) {
         yield data;
       }
     }
-    const tail = buffer.trim();
+    const tail = buffer.replace(/[\r\n]+$/, "");
     if (tail.startsWith("data:")) {
       const data = tail.slice(5).trimStart();
       if (data !== "[DONE]" && data !== "") yield data;
@@ -190,12 +213,15 @@ var ChatCompletionStream = class {
    *
    * 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.
+   * {@link SkailarAPIError} instead of yielding. A payload that is not valid JSON
+   * (e.g. a plain-text error injected by an intermediary) throws a
+   * {@link SkailarConnectionError} rather than being dropped, so a malformed
+   * stream cannot truncate the response silently.
    *
    * @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.
+   * @throws {@link SkailarConnectionError} When a payload is malformed, or the
+   * stream is aborted or fails to read.
    */
   async *decode() {
     for await (const data of parseSSE(this.body, this.controller.signal)) {
@@ -203,7 +229,9 @@ var ChatCompletionStream = class {
       try {
         parsed = JSON.parse(data);
       } catch {
-        continue;
+        throw new SkailarConnectionError({
+          message: `Malformed streaming event (not JSON): ${data.slice(0, 200)}`
+        });
       }
       if (parsed !== null && typeof parsed === "object" && "error" in parsed) {
         const { code, message } = parseErrorBody(parsed);
@@ -270,6 +298,8 @@ var ChatCompletions = class {
         path: "/v1/chat/completions",
         body,
         expect: "stream",
+        // Text generation is safe to replay before the stream starts.
+        idempotent: true,
         signal: options?.signal,
         timeout: options?.timeout,
         headers: options?.headers
@@ -280,6 +310,8 @@ var ChatCompletions = class {
       path: "/v1/chat/completions",
       body,
       expect: "json",
+      // Text generation is safe to replay.
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -315,6 +347,7 @@ var ModelsResource = class {
       method: "GET",
       path: "/v1/models",
       expect: "json",
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -336,6 +369,7 @@ var ModelsResource = class {
       method: "GET",
       path: `/v1/models/${encoded}`,
       expect: "json",
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -368,6 +402,8 @@ var ImagesResource = class {
       path: "/v1/images/generations",
       body,
       expect: "json",
+      // Billed image generation: never replay on 5xx/timeout to avoid double charges.
+      idempotent: false,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -428,6 +464,8 @@ var AudioTranscriptions = class {
       path: "/v1/audio/transcriptions",
       body: { base64, mime },
       expect: "json",
+      // Billed transcription: never replay on 5xx/timeout to avoid double charges.
+      idempotent: false,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -465,6 +503,8 @@ var AudioSpeech = class {
       body: { input: params.input, voice: params.voice },
       headers: { Accept: "audio/mpeg", ...options?.headers },
       expect: "response",
+      // Billed speech synthesis: never replay on 5xx/timeout to avoid double charges.
+      idempotent: false,
       signal: options?.signal,
       timeout: options?.timeout
     });
@@ -509,7 +549,9 @@ var ImageUploads = class {
       method: "POST",
       path: "/v1/uploads/images",
       body: { base64, content_type: params.contentType },
-      expect: "json"
+      expect: "json",
+      // Upload creates a stored asset: never replay to avoid duplicate uploads.
+      idempotent: false
     });
   }
 };
@@ -533,7 +575,9 @@ var FileUploads = class {
       method: "POST",
       path: "/v1/uploads/files",
       body: { base64, content_type: params.contentType },
-      expect: "json"
+      expect: "json",
+      // Upload creates a stored asset: never replay to avoid duplicate uploads.
+      idempotent: false
     });
   }
 };
@@ -550,6 +594,11 @@ var UploadsResource = class {
 };
 
 // src/client.ts
+var MAX_RETRY_DELAY_MS = 6e4;
+function capRetryDelay(retryAfterSeconds) {
+  if (retryAfterSeconds === void 0) return void 0;
+  return Math.min(Math.max(0, retryAfterSeconds) * 1e3, MAX_RETRY_DELAY_MS);
+}
 function delay(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -671,6 +720,7 @@ var Skailar = class {
       method: "GET",
       path: "/v1/ping-key",
       expect: "json",
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -681,15 +731,22 @@ var Skailar = class {
    *
    * 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.
+   * {@link SkailarOptions.fetch}, and error mapping. Backs off with full-jitter
+   * exponential delay, honoring a server `Retry-After` when present (capped at
+   * {@link MAX_RETRY_DELAY_MS} so an oversized value cannot stall the call), up
+   * to {@link Skailar.maxRetries}. Non-429 4xx responses fail fast.
+   *
+   * Retries are scoped to avoid duplicating side effects: an HTTP `429` is always
+   * retryable (rejected before execution), while a `5xx`, timeout or connection
+   * failure is retried **only** when `options.idempotent` is set — because the
+   * request may already have executed server-side. Requests with billed side
+   * effects (image generation, speech, transcription, uploads) leave it unset and
+   * are therefore never replayed once they may have reached the gateway.
    *
    * 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).
+   * (non-retryable), an internal timeout once {@link Skailar.timeout} elapses,
+   * and a generic network failure.
    *
    * @param options - The request description.
    * @returns The parsed JSON, raw `Response`, or {@link ChatCompletionStream}
@@ -699,6 +756,7 @@ var Skailar = class {
     const url = `${this.baseURL}${options.path}`;
     const isStream = options.expect === "stream";
     const timeoutMs = options.timeout ?? this.timeout;
+    const idempotent = options.idempotent ?? false;
     let attempt = 0;
     while (true) {
       const controller = new AbortController();
@@ -729,7 +787,7 @@ var Skailar = class {
           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;
+        if (externallyAborted || !idempotent || !this.shouldRetry(attempt)) throw connErr;
         attempt += 1;
         await delay(this.backoff(attempt), options.signal);
         continue;
@@ -738,8 +796,8 @@ var Skailar = class {
       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)) {
+        const retryAfterMs = apiError instanceof SkailarRateLimitError ? capRetryDelay(apiError.retryAfter) : void 0;
+        if (this.isRetryableStatus(response.status, idempotent) && this.shouldRetry(attempt)) {
           attempt += 1;
           await delay(retryAfterMs ?? this.backoff(attempt), options.signal);
           continue;
@@ -766,8 +824,14 @@ var Skailar = class {
     }
   }
   /**
-   * Assemble the outgoing header set for a request, applying defaults, auth,
-   * content-type and accept in precedence order.
+   * Assemble the outgoing header set for a request.
+   *
+   * Precedence (later wins): client `defaultHeaders` → the SDK's default `Accept`
+   * and `Content-Type` → per-call `options.headers` → `Authorization`.
+   * `Authorization` is applied **last** so a caller-supplied header (including a
+   * blindly proxied incoming one) can never override or drop the bearer token and
+   * leak it elsewhere. `Accept`/`Content-Type` remain overridable on purpose —
+   * e.g. audio speech sends `Accept: audio/mpeg`.
    *
    * @param options - The request description.
    * @returns The header record to send.
@@ -775,11 +839,14 @@ var Skailar = class {
   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);
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === "authorization") delete headers[key];
+    }
+    headers["Authorization"] = `Bearer ${this.apiKey}`;
     return headers;
   }
   /**
@@ -805,13 +872,20 @@ var Skailar = class {
     return SkailarAPIError.from(response.status, parsed, requestId, raw, retryAfter);
   }
   /**
-   * Whether a status code is eligible for automatic retry (429 and any 5xx).
+   * Whether an HTTP error status is eligible for automatic retry.
+   *
+   * A `429` is always retryable: the gateway rejects it before executing the
+   * request, so replaying it cannot duplicate side effects. A `5xx` may mean the
+   * request already executed server-side, so it is retried only when the caller
+   * marked the request idempotent.
    *
    * @param status - The HTTP status code.
+   * @param idempotent - Whether replaying the request is safe.
    * @returns `true` if retryable.
    */
-  isRetryableStatus(status) {
-    return status === 429 || status >= 500;
+  isRetryableStatus(status, idempotent) {
+    if (status === 429) return true;
+    return status >= 500 && idempotent;
   }
   /**
    * Whether another attempt remains within the retry budget.