skytells 1.0.2 → 1.0.4

package/dist/http.cjs

@@ -1,27 +1,179 @@
+/**
+ * Internal HTTP transport: JSON REST, retries, per-request timeouts, SSE chat streams, NDJSON, raw text/binary.
+ *
+ * **Not a public import** — use {@link SkytellsClient} (`Skytells()` factory). This module documents behavior for
+ * maintainers, LLMs, and IDE hover.
+ *
+ * | Concern | Behavior |
+ * |--------|------------|
+ * | **Timeouts** | `AbortController` + `clearTimeout` in `finally` (no orphaned timers). |
+ * | **Retries** | Only non-streaming JSON/text/buffer helpers; linear delay `retryDelay * (attempt + 1)`. |
+ * | **Streams** | `ReadableStream` reader `cancel()` in `finally`; body `cancel()` if `getReader()` missing. |
+ * | **Auth** | `skytells`: `x-api-key` + `Authorization`. `orchestrator`: Bearer only (see `transport`). |
+ * | **Errors** | Throws {@link SkytellsError} (`errorId`, `httpStatus`, optional `requestId`). |
+ *
+ * @see docs/Reliability.md — resource and option clamping.
+ * @module http
+ */
 const { API_BASE_URL } = require("./endpoints.js");
 const { SkytellsError } = require("./types/shared.types.js");
-// Default timeout in milliseconds
-// 60 seconds
-const DEFAULT_TIMEOUT = 60000;
+/** Default request timeout (ms) for JSON and SSE requests. */
+const HTTP_DEFAULT_REQUEST_TIMEOUT_MS = module.exports.HTTP_DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+const DEFAULT_RETRY_ON = [429, 500, 502, 503, 504];
+/** `setTimeout` is capped in practice (~2^31-1 ms); avoid overflow / infinite timers. */
+const MAX_TIMER_MS = 2147483647;
+function isAbsoluteHttpUrl(pathOrUrl) {
+    return pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://');
+}
+/** Fetch / `AbortController` timeout — same `name` in browsers, Node, and Edge runtimes. */
+function isAbortError(error) {
+    return (error !== null &&
+        typeof error === 'object' &&
+        'name' in error &&
+        error.name === 'AbortError');
+}
+/**
+ * Append a decoded chunk, return complete `\n`-terminated lines (strip trailing `\r`) and the leftover tail.
+ * Avoids `split('\n')` on the full buffer each chunk (CPU + allocations on long SSE / NDJSON streams).
+ */
+function appendAndExtractCompleteLines(buffer, chunk) {
+    const buf = buffer.length > 0 ? buffer + chunk : chunk;
+    const lines = [];
+    let start = 0;
+    let nl = buf.indexOf('\n', start);
+    while (nl >= 0) {
+        let line = buf.slice(start, nl);
+        if (line.endsWith('\r')) {
+            line = line.slice(0, -1);
+        }
+        lines.push(line);
+        start = nl + 1;
+        nl = buf.indexOf('\n', start);
+    }
+    return { lines, rest: start === 0 ? buf : buf.slice(start) };
+}
+/**
+ * Fetch-based client for one API origin (`baseUrl`) and one auth policy (`transport`).
+ *
+ * @internal Constructed only by {@link SkytellsClient} (and Orchestrator sub-client).
+ */
 export class HTTP {
-    constructor(apiKey, baseUrl = API_BASE_URL, timeout = DEFAULT_TIMEOUT) {
+    /**
+     * @param apiKey - Platform `sk-…` or Orchestrator `wfb_…` depending on `transport`.
+     * @param baseUrl - API origin (`api.skytells.ai/v1` or `orchestrator.skytells.ai`).
+     * @param timeout - Per-request/stream abort time in ms.
+     * @param headers - Merged into every request (JSON and SSE).
+     * @param retry - Retries only for non-streaming {@link HTTP.request}.
+     * @param fetchFn - Inject mock/proxy/`cache: 'no-store'` fetch.
+     * @param transport - **`orchestrator`** for `client.orchestrator` only; default **`skytells`** for predictions/inference.
+     */
+    constructor(apiKey, baseUrl = API_BASE_URL, timeout = HTTP_DEFAULT_REQUEST_TIMEOUT_MS, headers = {}, retry = {}, fetchFn, transport = 'skytells') {
+        var _a, _b;
         this.apiKey = apiKey;
         this.baseUrl = baseUrl;
-        this.timeout = timeout;
+        this.timeout =
+            timeout === Infinity
+                ? MAX_TIMER_MS
+                : Number.isFinite(timeout) && timeout >= 0
+                    ? Math.min(timeout, MAX_TIMER_MS)
+                    : HTTP_DEFAULT_REQUEST_TIMEOUT_MS;
+        this.customHeaders = headers;
+        this.transport = transport;
+        const rawRetries = (_a = retry.retries) !== null && _a !== void 0 ? _a : 0;
+        const rawDelay = (_b = retry.retryDelay) !== null && _b !== void 0 ? _b : 1000;
+        this.retry = {
+            retries: Math.max(0, Math.min(Math.floor(rawRetries), 100)),
+            retryDelay: Math.max(0, Math.min(Number.isFinite(rawDelay) ? rawDelay : 1000, MAX_TIMER_MS)),
+            retryOn: Array.isArray(retry.retryOn) && retry.retryOn.length > 0 ? retry.retryOn : DEFAULT_RETRY_ON,
+        };
+        this.fetchFn = fetchFn !== null && fetchFn !== void 0 ? fetchFn : globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Orchestrator transport must not send `x-api-key` — only `Authorization: Bearer wfb_…` per
+     * [Orchestrator webhooks](https://learn.skytells.ai/docs/products/orchestrator/webhooks). Strip any
+     * `x-api-key` copied from shared **`ClientOptions.headers`** so the Skytells `sk-…` key is never
+     * forwarded to `orchestrator.skytells.ai`.
+     */
+    applyAuthHeaders(headers) {
+        if (this.transport === 'orchestrator') {
+            delete headers['x-api-key'];
+        }
+        if (!this.apiKey) {
+            return;
+        }
+        if (this.transport === 'skytells') {
+            headers['x-api-key'] = this.apiKey;
+        }
+        headers['Authorization'] = `Bearer ${this.apiKey}`;
     }
+    /**
+     * Resolved API origin (no trailing slash), e.g. `https://api.skytells.ai/v1`.
+     *
+     * @returns Same string passed to the constructor (or default {@link API_BASE_URL}).
+     */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * API key for this instance (`sk-…` or `wfb_…`), if any.
+     *
+     * @returns `undefined` for unauthenticated clients. Used by {@link SkytellsClient.webhookListener} for General HMAC.
+     */
+    getApiKey() {
+        return this.apiKey;
+    }
+    /**
+     * Non-streaming JSON `fetch`: read `response.text()` once, `JSON.parse`, map API errors to {@link SkytellsError}.
+     *
+     * @typeParam T - Expected successful JSON body shape (caller-supplied; not validated at runtime).
+     * @param method - HTTP verb. Body sent only for `POST`, `PATCH`, `PUT`.
+     * @param path - Relative to `baseUrl`, or absolute `http(s)://…`.
+     * @param data - Serializable JSON object. **Circular references** → `SDK_ERROR`. Omit for GET/DELETE.
+     * @returns Parsed response JSON.
+     * @throws {SkytellsError} `REQUEST_TIMEOUT`, `NETWORK_ERROR`, `INVALID_JSON`, `SERVER_ERROR`, or API `error.error_id`.
+     * @remarks Retries when `httpStatus` is in `retry.retryOn` and attempts remain. Skytells prediction “queued” envelopes are normalized inside the internal fetch path.
+     */
     async request(method, path, data) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retry.retries; attempt++) {
+            try {
+                return await this.executeRequest(method, path, data);
+            }
+            catch (error) {
+                if (error instanceof SkytellsError) {
+                    lastError = error;
+                    const isRetryable = this.retry.retryOn.includes(error.httpStatus);
+                    if (isRetryable && attempt < this.retry.retries) {
+                        await this.delay(Math.min(this.retry.retryDelay * (attempt + 1), MAX_TIMER_MS));
+                        continue;
+                    }
+                }
+                throw error;
+            }
+        }
+        throw (lastError !== null && lastError !== void 0 ? lastError : new SkytellsError('Request failed after retries', 'UNKNOWN_ERROR', 'No error details', 0));
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+    }
+    async executeRequest(method, path, data) {
+        var _a, _b, _c, _d;
         const headers = {
             'Content-Type': 'application/json',
+            ...this.customHeaders,
         };
-        if (this.apiKey) {
-            headers['x-api-key'] = this.apiKey;
-        }
+        this.applyAuthHeaders(headers);
         const options = {
             method,
             headers,
         };
-        if (method === 'POST' && data) {
-            options.body = JSON.stringify(data);
+        if ((method === 'POST' || method === 'PATCH' || method === 'PUT') && data !== undefined) {
+            try {
+                options.body = JSON.stringify(data);
+            }
+            catch (_e) {
+                throw new SkytellsError('Request body could not be serialized to JSON', 'SDK_ERROR', 'Remove circular references or non-JSON values from the payload.', 0);
+            }
         }
         // Add AbortController for timeout handling
         const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
@@ -36,56 +188,58 @@ export class HTTP {
             }, this.timeout);
         }
         try {
+            const fetchUrl = isAbsoluteHttpUrl(path) ? path : `${this.baseUrl}${path}`;
             // Use native fetch which is available in modern browsers and edge environments
-            const response = await fetch(`${this.baseUrl}${path}`, options);
-            // Get the response content type to check if it's JSON
+            const response = await this.fetchFn(fetchUrl, options);
             const contentType = response.headers.get('content-type') || '';
             const isJsonResponse = contentType.includes('application/json');
-            // Handle non-JSON responses properly
+            const bodyText = await response.text();
             if (!isJsonResponse) {
-                // If not JSON, get the text for error details
-                let responseText = '';
-                try {
-                    responseText = await response.text();
-                    // Truncate if too long to avoid huge error messages
-                    if (responseText.length > 500) {
-                        responseText = responseText.substring(0, 500) + '... [truncated]';
-                    }
-                }
-                catch (textError) {
-                    responseText = 'Could not read response body';
-                }
-                throw new SkytellsError(`Server responded with non-JSON content (${contentType})`, 'SERVER_ERROR', `Status: ${response.status}, Content: ${responseText}`, response.status);
+                const responseText = bodyText.length > 500 ? `${bodyText.slice(0, 500)}... [truncated]` : bodyText;
+                throw new SkytellsError(`Server responded with non-JSON content (${contentType})`, 'SERVER_ERROR', `Status: ${response.status}, Content: ${responseText || '(empty)'}`, response.status);
             }
-            // Try to parse as JSON
             let responseData;
             try {
-                responseData = await response.json();
+                responseData =
+                    bodyText.length === 0 ? null : JSON.parse(bodyText);
             }
-            catch (error) {
-                // Get response text for better error details
-                let responseText = '';
-                try {
-                    // Need to clone response since we already tried to read it as JSON
-                    responseText = await response.clone().text();
-                    if (responseText.length > 500) {
-                        responseText = responseText.substring(0, 500) + '... [truncated]';
-                    }
-                }
-                catch (textError) {
-                    responseText = 'Could not read response body';
-                }
-                throw new SkytellsError('Invalid JSON response', 'INVALID_JSON', `The server returned invalid JSON. Status: ${response.status}, Content: ${responseText}`, response.status);
+            catch (_f) {
+                const preview = bodyText.length > 500 ? `${bodyText.slice(0, 500)}... [truncated]` : bodyText;
+                throw new SkytellsError('Invalid JSON response', 'INVALID_JSON', `The server returned invalid JSON. Status: ${response.status}, Content: ${preview}`, response.status);
+            }
+            /**
+             * Prediction endpoints always return a prediction object with `id`. Some responses also set
+             * top-level `status: false` with `error.message` while the job is still queued — treat as success
+             * when HTTP is OK and `id` is present (matches dashboard `processing` / `started`).
+             */
+            const data = responseData;
+            if (this.transport === 'skytells' &&
+                response.ok &&
+                data &&
+                data.status === false &&
+                typeof data.id === 'string' &&
+                data.id.length > 0) {
+                return responseData;
             }
             // Check if the response indicates an error
             if (!response.ok || (responseData && responseData.status === false)) {
-                if (responseData && responseData.error) {
-                    // API returned a structured error
-                    throw new SkytellsError(responseData.error.message || responseData.response || 'API error occurred', responseData.error.error_id || 'UNKNOWN_ERROR', responseData.error.details || responseData.response || 'No additional details', responseData.error.http_status || response.status);
+                const errObj = responseData === null || responseData === void 0 ? void 0 : responseData.error;
+                if (responseData && errObj) {
+                    const httpStatus = (_b = (_a = errObj.status) !== null && _a !== void 0 ? _a : errObj.http_status) !== null && _b !== void 0 ? _b : response.status;
+                    const requestId = errObj.request_id;
+                    const err = new SkytellsError(errObj.message || responseData.response || 'API error occurred', errObj.error_id || 'UNKNOWN_ERROR', (_d = (_c = errObj.details) !== null && _c !== void 0 ? _c : responseData.response) !== null && _d !== void 0 ? _d : 'No additional details', httpStatus, requestId);
+                    if (errObj.type) {
+                        err.errorType = errObj.type;
+                    }
+                    if (errObj.code) {
+                        err.errorCode = errObj.code;
+                    }
+                    throw err;
                 }
-                else if (responseData && responseData.response) {
+                else if (responseData === null || responseData === void 0 ? void 0 : responseData.response) {
                     // Simple error with just a response message
-                    throw new SkytellsError(responseData.response, 'API_ERROR', responseData.response, response.status);
+                    const msg = String(responseData.response);
+                    throw new SkytellsError(msg, 'API_ERROR', msg, response.status);
                 }
                 else {
                     // Generic HTTP error
@@ -96,23 +250,454 @@ export class HTTP {
         }
         catch (error) {
             // Check if it's an abort error (timeout)
-            if (error && typeof error === 'object' && 'name' in error && error.name === 'AbortError') {
-                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', `The request took longer than ${this.timeout}ms to complete`, 408 // Request Timeout status code
-                );
+            if (isAbortError(error)) {
+                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', `The request took longer than ${this.timeout}ms to complete`, 408);
             }
             // Re-throw original error
             if (error instanceof SkytellsError) {
                 throw error;
             }
             // Network or other errors
-            throw new SkytellsError(error instanceof Error ? error.message : 'Network error occurred', 'NETWORK_ERROR', 'A network error occurred while communicating with the API', 0 // No HTTP status for network errors
-            );
+            throw new SkytellsError(error instanceof Error ? error.message : 'Network error occurred', 'NETWORK_ERROR', 'A network error occurred while communicating with the API', 0);
+        }
+        finally {
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    /**
+     * **SSE** streaming `POST`: parses `data: …` lines as JSON (chat completions when `stream: true`).
+     *
+     * @typeParam T - Usually {@link ChatCompletionChunk} from inference types.
+     * @param path - e.g. `/chat/completions`.
+     * @param data - Must include `stream: true`. Must be JSON-serializable or throws `SDK_ERROR`.
+     * @returns Async iterable; consume with `for await`. Malformed lines skipped; `[DONE]` ignored.
+     * @throws {SkytellsError} Non-OK HTTP, timeout (`REQUEST_TIMEOUT`), or missing body reader.
+     * @remarks **Not retried.** Abandoning the loop still runs `reader.cancel()` in `finally`. Timeout cleared in outer `finally`.
+     */
+    async *requestStream(path, data) {
+        var _a, _b, _c;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'text/event-stream',
+            ...this.customHeaders,
+        };
+        this.applyAuthHeaders(headers);
+        const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        let bodyJson;
+        try {
+            bodyJson = JSON.stringify(data);
+        }
+        catch (_d) {
+            throw new SkytellsError('Request body could not be serialized to JSON', 'SDK_ERROR', 'Remove circular references or non-JSON values from the payload.', 0);
+        }
+        const options = {
+            method: 'POST',
+            headers,
+            body: bodyJson,
+            signal: controller === null || controller === void 0 ? void 0 : controller.signal,
+        };
+        let timeoutId = null;
+        if (controller) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        }
+        try {
+            const fetchUrl = isAbsoluteHttpUrl(path) ? path : `${this.baseUrl}${path}`;
+            const response = await this.fetchFn(fetchUrl, options);
+            if (!response.ok) {
+                const text = await response.text();
+                let errData;
+                try {
+                    errData = JSON.parse(text);
+                }
+                catch (_e) {
+                    throw new SkytellsError(`HTTP ${response.status}: ${text.slice(0, 200)}`, 'HTTP_ERROR', text.slice(0, 500), response.status);
+                }
+                if (errData === null || errData === void 0 ? void 0 : errData.error) {
+                    throw new SkytellsError(errData.error.message || 'API error', errData.error.error_id || 'UNKNOWN_ERROR', errData.error.message || '', (_a = errData.error.status) !== null && _a !== void 0 ? _a : response.status, errData.error.request_id);
+                }
+                throw new SkytellsError(`HTTP error ${response.status}`, 'HTTP_ERROR', text.slice(0, 500), response.status);
+            }
+            const reader = (_b = response.body) === null || _b === void 0 ? void 0 : _b.getReader();
+            if (!reader) {
+                try {
+                    await ((_c = response.body) === null || _c === void 0 ? void 0 : _c.cancel());
+                }
+                catch (_f) {
+                    /* ignore */
+                }
+                throw new SkytellsError('No response body', 'SERVER_ERROR', 'Stream not available', 0);
+            }
+            const decoder = new TextDecoder();
+            let buffer = '';
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    const { lines, rest } = appendAndExtractCompleteLines(buffer, decoder.decode(value, { stream: true }));
+                    buffer = rest;
+                    for (const line of lines) {
+                        if (line.startsWith('data: ')) {
+                            const payload = line.slice(6).trim();
+                            if (payload === '[DONE]') {
+                                continue;
+                            }
+                            try {
+                                yield JSON.parse(payload);
+                            }
+                            catch (_g) {
+                                // Skip malformed lines
+                            }
+                        }
+                    }
+                }
+                // Flush any remaining buffered data after the stream closes (handles servers that omit
+                // the final newline — rare in SSE but safe to handle uniformly with requestNdjsonStream).
+                if (buffer.startsWith('data: ')) {
+                    const payload = buffer.slice(6).trim();
+                    if (payload && payload !== '[DONE]') {
+                        try {
+                            yield JSON.parse(payload);
+                        }
+                        catch (_h) {
+                            // ignore incomplete trailing data
+                        }
+                    }
+                }
+            }
+            finally {
+                try {
+                    await reader.cancel();
+                }
+                catch (_j) {
+                    // Reader may already be closed; ignore
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof SkytellsError) {
+                throw error;
+            }
+            if (isAbortError(error)) {
+                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', 'Stream timeout', 408);
+            }
+            throw new SkytellsError(error instanceof Error ? error.message : 'Stream error', 'NETWORK_ERROR', 'Stream failed', 0);
         }
         finally {
-            // Clear timeout if it was set
             if (timeoutId !== null) {
                 clearTimeout(timeoutId);
             }
         }
     }
+    /**
+     * Successful response read as **plain text** (not JSON-validated). Used for code export, etc.
+     *
+     * @param method - Currently **`GET`** only in SDK call sites.
+     * @param path - Relative or absolute URL.
+     * @returns Full response body string.
+     * @throws {SkytellsError} Same families as {@link HTTP.request} for HTTP/network/timeout errors.
+     * @remarks Uses same **retry** policy as {@link HTTP.request}.
+     */
+    async requestText(method, path) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retry.retries; attempt++) {
+            try {
+                return await this.executeRequestRawText(method, path);
+            }
+            catch (error) {
+                if (error instanceof SkytellsError) {
+                    lastError = error;
+                    const isRetryable = this.retry.retryOn.includes(error.httpStatus);
+                    if (isRetryable && attempt < this.retry.retries) {
+                        await this.delay(Math.min(this.retry.retryDelay * (attempt + 1), MAX_TIMER_MS));
+                        continue;
+                    }
+                }
+                throw error;
+            }
+        }
+        throw (lastError !== null && lastError !== void 0 ? lastError : new SkytellsError('Request failed after retries', 'UNKNOWN_ERROR', 'No error details', 0));
+    }
+    /**
+     * Successful response as **binary** (`arrayBuffer()`), e.g. ZIP downloads.
+     *
+     * @param method - **`GET`** in practice.
+     * @param path - Relative or absolute URL.
+     * @returns Raw bytes.
+     * @throws {SkytellsError} On HTTP error, timeout, or network failure.
+     * @remarks Same **retry** policy as {@link HTTP.request}.
+     */
+    async requestBuffer(method, path) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retry.retries; attempt++) {
+            try {
+                return await this.executeRequestRawBuffer(method, path);
+            }
+            catch (error) {
+                if (error instanceof SkytellsError) {
+                    lastError = error;
+                    const isRetryable = this.retry.retryOn.includes(error.httpStatus);
+                    if (isRetryable && attempt < this.retry.retries) {
+                        await this.delay(Math.min(this.retry.retryDelay * (attempt + 1), MAX_TIMER_MS));
+                        continue;
+                    }
+                }
+                throw error;
+            }
+        }
+        throw (lastError !== null && lastError !== void 0 ? lastError : new SkytellsError('Request failed after retries', 'UNKNOWN_ERROR', 'No error details', 0));
+    }
+    /**
+     * Fire **`OPTIONS`** (CORS preflight for Orchestrator webhooks). **No retries.**
+     *
+     * @param path - Full path under `baseUrl`.
+     * @throws {SkytellsError} If `!response.ok`, timeout, or network error.
+     */
+    async requestOptions(path) {
+        var _a;
+        const headers = { ...this.customHeaders };
+        this.applyAuthHeaders(headers);
+        const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        const options = {
+            method: 'OPTIONS',
+            headers,
+            signal: (_a = controller === null || controller === void 0 ? void 0 : controller.signal) !== null && _a !== void 0 ? _a : undefined,
+        };
+        let timeoutId = null;
+        if (controller) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        }
+        try {
+            const fetchUrl = isAbsoluteHttpUrl(path) ? path : `${this.baseUrl}${path}`;
+            const response = await this.fetchFn(fetchUrl, options);
+            if (!response.ok) {
+                const text = await response.text();
+                throw new SkytellsError(`HTTP error ${response.status}`, 'HTTP_ERROR', text.slice(0, 500) || `Status ${response.status}`, response.status);
+            }
+        }
+        catch (error) {
+            if (error instanceof SkytellsError) {
+                throw error;
+            }
+            if (isAbortError(error)) {
+                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', 'OPTIONS request timed out', 408);
+            }
+            throw new SkytellsError(error instanceof Error ? error.message : 'Network error', 'NETWORK_ERROR', 'OPTIONS request failed', 0);
+        }
+        finally {
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    /**
+     * **NDJSON / JSONL** `POST`: one JSON object per line (Orchestrator AI workflow generation).
+     *
+     * @typeParam T - Line shape; default `Record<string, unknown>`.
+     * @param path - e.g. `/api/ai/generate`.
+     * @param data - Serialized as JSON body; circular data → `SDK_ERROR`.
+     * @returns Async iterable of parsed lines; invalid JSON lines skipped.
+     * @throws {SkytellsError} HTTP error, timeout, or missing stream body.
+     * @remarks **Not retried** after bytes flow. Reader/body cleanup same as {@link HTTP.requestStream}.
+     */
+    async *requestNdjsonStream(path, data) {
+        var _a, _b, _c;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/x-ndjson, application/jsonlines+json, text/plain, */*',
+            ...this.customHeaders,
+        };
+        this.applyAuthHeaders(headers);
+        const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        let ndjsonBody;
+        try {
+            ndjsonBody = JSON.stringify(data);
+        }
+        catch (_d) {
+            throw new SkytellsError('Request body could not be serialized to JSON', 'SDK_ERROR', 'Remove circular references or non-JSON values from the payload.', 0);
+        }
+        const options = {
+            method: 'POST',
+            headers,
+            body: ndjsonBody,
+            signal: controller === null || controller === void 0 ? void 0 : controller.signal,
+        };
+        let timeoutId = null;
+        if (controller) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        }
+        try {
+            const fetchUrl = isAbsoluteHttpUrl(path) ? path : `${this.baseUrl}${path}`;
+            const response = await this.fetchFn(fetchUrl, options);
+            if (!response.ok) {
+                const text = await response.text();
+                let errData;
+                try {
+                    errData = JSON.parse(text);
+                }
+                catch (_e) {
+                    throw new SkytellsError(`HTTP ${response.status}: ${text.slice(0, 200)}`, 'HTTP_ERROR', text.slice(0, 500), response.status);
+                }
+                if (errData === null || errData === void 0 ? void 0 : errData.error) {
+                    throw new SkytellsError(errData.error.message || 'API error', errData.error.error_id || 'UNKNOWN_ERROR', errData.error.message || '', (_a = errData.error.status) !== null && _a !== void 0 ? _a : response.status, errData.error.request_id);
+                }
+                throw new SkytellsError(`HTTP error ${response.status}`, 'HTTP_ERROR', text.slice(0, 500), response.status);
+            }
+            const reader = (_b = response.body) === null || _b === void 0 ? void 0 : _b.getReader();
+            if (!reader) {
+                try {
+                    await ((_c = response.body) === null || _c === void 0 ? void 0 : _c.cancel());
+                }
+                catch (_f) {
+                    /* ignore */
+                }
+                throw new SkytellsError('No response body', 'SERVER_ERROR', 'Stream not available', 0);
+            }
+            const decoder = new TextDecoder();
+            let buffer = '';
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    const { lines, rest } = appendAndExtractCompleteLines(buffer, decoder.decode(value, { stream: true }));
+                    buffer = rest;
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        if (!trimmed) {
+                            continue;
+                        }
+                        try {
+                            yield JSON.parse(trimmed);
+                        }
+                        catch (_g) {
+                            // skip malformed JSONL line
+                        }
+                    }
+                }
+                const tail = buffer.trim();
+                if (tail) {
+                    try {
+                        yield JSON.parse(tail);
+                    }
+                    catch (_h) {
+                        // ignore trailing garbage
+                    }
+                }
+            }
+            finally {
+                try {
+                    await reader.cancel();
+                }
+                catch (_j) {
+                    /* ignore */
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof SkytellsError) {
+                throw error;
+            }
+            if (isAbortError(error)) {
+                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', 'NDJSON stream timeout', 408);
+            }
+            throw new SkytellsError(error instanceof Error ? error.message : 'Stream error', 'NETWORK_ERROR', 'NDJSON stream failed', 0);
+        }
+        finally {
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    async executeRequestRawText(method, path) {
+        const headers = { Accept: '*/*', ...this.customHeaders };
+        this.applyAuthHeaders(headers);
+        const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        const options = { method, headers, signal: controller === null || controller === void 0 ? void 0 : controller.signal };
+        let timeoutId = null;
+        if (controller) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        }
+        try {
+            const fetchUrl = isAbsoluteHttpUrl(path) ? path : `${this.baseUrl}${path}`;
+            const response = await this.fetchFn(fetchUrl, options);
+            const bodyText = await response.text();
+            if (!response.ok) {
+                this.throwFromTextErrorResponse(response.status, bodyText);
+            }
+            return bodyText;
+        }
+        catch (error) {
+            if (error instanceof SkytellsError) {
+                throw error;
+            }
+            if (isAbortError(error)) {
+                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', `The request took longer than ${this.timeout}ms to complete`, 408);
+            }
+            throw new SkytellsError(error instanceof Error ? error.message : 'Network error occurred', 'NETWORK_ERROR', 'A network error occurred while communicating with the API', 0);
+        }
+        finally {
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    async executeRequestRawBuffer(method, path) {
+        const headers = { Accept: '*/*', ...this.customHeaders };
+        this.applyAuthHeaders(headers);
+        const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        const options = { method, headers, signal: controller === null || controller === void 0 ? void 0 : controller.signal };
+        let timeoutId = null;
+        if (controller) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        }
+        try {
+            const fetchUrl = isAbsoluteHttpUrl(path) ? path : `${this.baseUrl}${path}`;
+            const response = await this.fetchFn(fetchUrl, options);
+            if (!response.ok) {
+                const text = await response.text();
+                this.throwFromTextErrorResponse(response.status, text);
+            }
+            return await response.arrayBuffer();
+        }
+        catch (error) {
+            if (error instanceof SkytellsError) {
+                throw error;
+            }
+            if (isAbortError(error)) {
+                throw new SkytellsError(`Request timed out after ${this.timeout}ms`, 'REQUEST_TIMEOUT', `The request took longer than ${this.timeout}ms to complete`, 408);
+            }
+            throw new SkytellsError(error instanceof Error ? error.message : 'Network error occurred', 'NETWORK_ERROR', 'A network error occurred while communicating with the API', 0);
+        }
+        finally {
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    throwFromTextErrorResponse(status, bodyText) {
+        var _a, _b;
+        let responseData = null;
+        try {
+            responseData =
+                bodyText.length === 0 ? null : JSON.parse(bodyText);
+        }
+        catch (_c) {
+            throw new SkytellsError(`HTTP error ${status}`, 'HTTP_ERROR', bodyText.slice(0, 500) || `Status ${status}`, status);
+        }
+        const errObj = responseData === null || responseData === void 0 ? void 0 : responseData.error;
+        if (responseData && errObj) {
+            const httpStatus = (_b = (_a = errObj.status) !== null && _a !== void 0 ? _a : errObj.http_status) !== null && _b !== void 0 ? _b : status;
+            throw new SkytellsError(errObj.message || responseData.response || 'API error occurred', errObj.error_id || 'UNKNOWN_ERROR', errObj.details || responseData.response || 'No additional details', httpStatus, errObj.request_id);
+        }
+        if (responseData === null || responseData === void 0 ? void 0 : responseData.response) {
+            const msg = String(responseData.response);
+            throw new SkytellsError(msg, 'API_ERROR', msg, status);
+        }
+        throw new SkytellsError(`HTTP error ${status}`, 'HTTP_ERROR', bodyText.slice(0, 500) || `The server returned status code ${status}`, status);
+    }
 }