@skailar-ai/sdk 0.0.2 → 0.0.4

package/dist/index.cjs

@@ -27,7 +27,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;
@@ -138,6 +145,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) {
@@ -146,11 +172,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();
@@ -158,7 +181,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;
@@ -194,12 +217,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)) {
@@ -207,7 +233,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);
@@ -274,6 +302,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
@@ -284,6 +314,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
@@ -319,6 +351,7 @@ var ModelsResource = class {
       method: "GET",
       path: "/v1/models",
       expect: "json",
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -340,6 +373,7 @@ var ModelsResource = class {
       method: "GET",
       path: `/v1/models/${encoded}`,
       expect: "json",
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -372,6 +406,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
@@ -432,6 +468,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
@@ -469,6 +507,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
     });
@@ -513,7 +553,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
     });
   }
 };
@@ -537,7 +579,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
     });
   }
 };
@@ -554,6 +598,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) {
@@ -675,6 +724,7 @@ var Skailar = class {
       method: "GET",
       path: "/v1/ping-key",
       expect: "json",
+      idempotent: true,
       signal: options?.signal,
       timeout: options?.timeout,
       headers: options?.headers
@@ -685,15 +735,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}
@@ -703,6 +760,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();
@@ -733,7 +791,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;
@@ -742,8 +800,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;
@@ -770,8 +828,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.
@@ -779,11 +843,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;
   }
   /**
@@ -809,13 +876,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.