skytells 1.0.2 → 1.0.4

package/dist/http.d.ts

@@ -1,7 +1,141 @@
+/**
+ * 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
+ */
+import type { RetryOptions } from './types/shared.types.js';
+/** Default request timeout (ms) for JSON and SSE requests. */
+export declare const HTTP_DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+/**
+ * Which product this {@link HTTP} instance calls. Set only by {@link SkytellsClient} — app code uses
+ * `Skytells('sk-…', { orchestratorApiKey: 'wfb_…' })`; the client wires the correct transport per API.
+ *
+ * - **`skytells`** — platform API (`sk-…`): `x-api-key` + `Authorization: Bearer`
+ * - **`orchestrator`** — Orchestrator (`wfb_…`): `Authorization: Bearer` only (no `x-api-key`)
+ *
+ * @internal
+ */
+type HttpTransport = 'skytells' | 'orchestrator';
+type HttpJsonMethod = 'GET' | 'POST' | 'DELETE' | 'PATCH' | 'PUT';
+/**
+ * Fetch-based client for one API origin (`baseUrl`) and one auth policy (`transport`).
+ *
+ * @internal Constructed only by {@link SkytellsClient} (and Orchestrator sub-client).
+ */
 export declare class HTTP {
     private apiKey?;
     private baseUrl;
     private timeout;
-    constructor(apiKey?: string, baseUrl?: string, timeout?: number);
-    request<T>(method: 'GET' | 'POST' | 'DELETE', path: string, data?: Record<string, unknown>): Promise<T>;
+    private customHeaders;
+    private retry;
+    private fetchFn;
+    private transport;
+    /**
+     * @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?: string, baseUrl?: string, timeout?: number, headers?: Record<string, string>, retry?: RetryOptions, fetchFn?: typeof fetch, transport?: HttpTransport);
+    /**
+     * 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`.
+     */
+    private applyAuthHeaders;
+    /**
+     * 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(): string;
+    /**
+     * API key for this instance (`sk-…` or `wfb_…`), if any.
+     *
+     * @returns `undefined` for unauthenticated clients. Used by {@link SkytellsClient.webhookListener} for General HMAC.
+     */
+    getApiKey(): string | undefined;
+    /**
+     * 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.
+     */
+    request<T>(method: HttpJsonMethod, path: string, data?: Record<string, unknown>): Promise<T>;
+    private delay;
+    private executeRequest;
+    /**
+     * **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`.
+     */
+    requestStream<T>(path: string, data: Record<string, unknown>): AsyncIterable<T>;
+    /**
+     * 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}.
+     */
+    requestText(method: 'GET', path: string): Promise<string>;
+    /**
+     * 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}.
+     */
+    requestBuffer(method: 'GET', path: string): Promise<ArrayBuffer>;
+    /**
+     * Fire **`OPTIONS`** (CORS preflight for Orchestrator webhooks). **No retries.**
+     *
+     * @param path - Full path under `baseUrl`.
+     * @throws {SkytellsError} If `!response.ok`, timeout, or network error.
+     */
+    requestOptions(path: string): Promise<void>;
+    /**
+     * **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}.
+     */
+    requestNdjsonStream<T = Record<string, unknown>>(path: string, data: Record<string, unknown>): AsyncIterable<T>;
+    private executeRequestRawText;
+    private executeRequestRawBuffer;
+    private throwFromTextErrorResponse;
 }
+export {};