skytells 1.0.2 → 1.0.4

package/dist/client.d.ts

@@ -1,45 +1,794 @@
-import { PredictionRequest, PredictionResponse, Model, ClientOptions } from './types/index.js';
+/**
+ * Skytells prediction client: models catalog, create/poll/wait predictions, queue batching, and
+ * optional per-request inference compatibility guard (second argument `{ compatibilityCheck: true }` on `predict` / `create`, fourth on `run`).
+ *
+ * **Memory / lifecycle (for long‑lived servers):**
+ * - Sub-APIs (`chat`, `embeddings`, …) are created lazily on first access.
+ * - When a call passes `{ compatibilityCheck: true }`, model metadata is cached per slug with TTL
+ *   {@link PREFETCHED_MODEL_CACHE_TTL_MS} and a cap from {@link SkytellsClient.config | config.prefetchMaxSlugs}
+ *   (smaller when {@link ClientOptions.runtime} is `"edge"`).
+ * - {@link SkytellsClient.wait} / `run(..., onProgress)` use `setTimeout` between polls; pass {@link WaitOptions.signal}
+ *   (or `RunOptions.signal` with `onProgress`) to abort and stop scheduling further delays.
+ * - {@link Prediction} holds the shared {@link HTTP} client and a snapshot of the API response (expected).
+ * - {@link SkytellsClient.queue} is an unbounded in-memory array — call {@link SkytellsClient.dispatch} or avoid piling
+ *   requests if you need a hard limit (enforce in your app).
+ * - Timeouts, stream cleanup, and polling guards: see **Reliability.md** in the repo docs.
+ *
+ * @module client
+ */
+import { HTTP } from './http.js';
+import { Orchestrator } from './orchestrator.js';
+import { Chat } from './chat.js';
+import { Responses } from './responses.js';
+import { Embeddings } from './embeddings.js';
+import { Safety } from './safety.js';
+import type { PredictionRequest, PredictionResponse, RunOptions, PredictionsListOptions, OnProgressCallback, WaitOptions, PredictionSdkOptions, PaginatedResponse, Model, ModelFieldsOptions, ClientOptions, SkytellsRuntime } from './types/index.js';
+import { PredictionStatus } from './types/index.js';
+import type { WebhookListener } from './webhooks.js';
+import { type WebhookListenerOptions } from './webhooks.js';
+/**
+ * Time-to-live for in-memory cache of `GET /model/{slug}` responses used when
+ * a guarded predict/create/run uses `compatibilityCheck: true`. After this interval the next guarded request refetches the model.
+ */
+export declare const PREFETCHED_MODEL_CACHE_TTL_MS: number;
+/**
+ * Max distinct model slugs kept in the compatibility-check cache. Oldest entries are removed (FIFO) when exceeded.
+ * Prevents unbounded growth if callers use many unique `model` strings over time.
+ */
+export declare const PREFETCHED_MODEL_CACHE_MAX_SLUGS = 64;
+/**
+ * Default request timeout when {@link ClientOptions.runtime} is `"edge"` and `timeout` is omitted
+ * (aligns with common ~25–30s serverless / edge ceilings).
+ */
+export declare const EDGE_DEFAULT_REQUEST_TIMEOUT_MS = 25000;
+/** Max model slugs in the inference-compat cache when `runtime` is `"edge"` (lower memory). */
+export declare const EDGE_PREFETCH_MAX_SLUGS = 16;
+/**
+ * Represents a completed prediction with convenience methods for accessing output
+ * and managing the prediction lifecycle (cancel, delete).
+ *
+ * Returned by {@link SkytellsClient.run}. Wraps a {@link PredictionResponse} and
+ * exposes `.output` to get results as a normalized `string[]`, plus `.cancel()`
+ * and `.delete()` for lifecycle management.
+ *
+ * @example
+ * ```ts
+ * const prediction = await client.run("flux-pro", { input: { prompt: "a cat" } });
+ * const [imageUrl] = prediction.output;
+ * console.log(prediction.id, prediction.status);
+ * const streamMeta = await prediction.stream(); // stream endpoint info (uses urls.stream)
+ * // Clean up when done
+ * await prediction.delete();
+ * ```
+ */
+export declare class Prediction {
+    private http;
+    private data;
+    /** @internal Use {@link SkytellsClient.run} to create a Prediction. */
+    constructor(http: HTTP, data: PredictionResponse);
+    /**
+     * The full prediction response object from the API.
+     * Contains all fields: status, id, input, output, metrics, metadata, urls, etc.
+     */
+    get response(): PredictionResponse;
+    /**
+     * The unique prediction identifier.
+     * Use this to fetch, cancel, or delete the prediction later via the client.
+     */
+    get id(): string;
+    /**
+     * The current status of the prediction.
+     * Possible values: `pending`, `starting`, `started`, `processing`, `succeeded`, `failed`, `cancelled`.
+     */
+    get status(): PredictionStatus;
+    /**
+     * The raw prediction output as returned by the API.
+     *
+     * Can be a single `string`, a `string[]`, or `undefined` if incomplete.
+     *
+     * @example
+     * ```ts
+     * // Single output (string)
+     * console.log(prediction.output); // "https://..."
+     *
+     * // Multiple outputs (string[])
+     * console.log(prediction.output[0]); // "https://..."
+     *
+     * // Check type
+     * if (Array.isArray(prediction.output)) {
+     *   for (const item of prediction.output) { console.log(item); }
+     * }
+     * ```
+     */
+    get output(): string | string[] | undefined;
+    /**
+     * Returns the output, normalized to a single value:
+     *
+     * - `undefined` / `null` → `undefined`
+     * - `"https://..."` → `"https://..."`
+     * - `["https://..."]` → `"https://..."` (single-element array unwrapped)
+     * - `["a", "b"]` → `["a", "b"]` (multi-element array kept as-is)
+     *
+     * @example
+     * ```ts
+     * const result = prediction.outputs();
+     * // string if single output, string[] if multiple, undefined if none
+     * ```
+     */
+    outputs(): string | string[] | undefined;
+    /**
+     * Returns the full raw prediction response as a plain JSON object.
+     *
+     * @returns The raw `PredictionResponse` data from the API.
+     *
+     * @example
+     * ```ts
+     * const prediction = await client.run("flux-pro", { input: { prompt: "a cat" } });
+     * const json = prediction.raw();
+     * console.log(json.id, json.status, json.output, json.metrics);
+     * ```
+     */
+    raw(): PredictionResponse;
+    /**
+     * Fetches streaming metadata for this prediction (`GET` using `urls.stream` when present).
+     * Same behavior as the deprecated {@link SkytellsClient.streamPrediction} with this prediction’s id and urls.
+     *
+     * @returns The prediction response from the stream-info endpoint (includes `urls`, etc.).
+     */
+    stream(): Promise<PredictionResponse>;
+    /**
+     * Cancels this prediction. Only works if the prediction is still in progress
+     * (status is `pending`, `starting`, `started`, or `processing`).
+     *
+     * @returns The updated prediction response with `status: 'cancelled'`.
+     * @throws {SkytellsError} If the prediction cannot be cancelled or the request fails.
+     *
+     * @example
+     * ```ts
+     * const prediction = await client.run("flux-pro", { input: { prompt: "a cat" } });
+     * await prediction.cancel();
+     * ```
+     */
+    cancel(): Promise<PredictionResponse>;
+    /**
+     * Deletes this prediction and its associated output/assets from storage.
+     *
+     * @returns The prediction response confirming deletion.
+     * @throws {SkytellsError} If the prediction cannot be deleted or the request fails.
+     *
+     * @example
+     * ```ts
+     * const prediction = await client.run("flux-pro", { input: { prompt: "a cat" } });
+     * const [url] = prediction.output;
+     * // ... use the output ...
+     * await prediction.delete(); // clean up
+     * ```
+     */
+    delete(): Promise<PredictionResponse>;
+}
+/**
+ * Sub-API for managing predictions. Accessible via `client.predictions`.
+ *
+ * Provides methods to create predictions in the background, fetch them by ID,
+ * and list them with filters.
+ *
+ * @example
+ * ```ts
+ * // Create a background prediction
+ * const prediction = await client.predictions.create({
+ *   model: "flux-pro",
+ *   input: { prompt: "A sunset" },
+ * });
+ *
+ * // Fetch it later
+ * const result = await client.predictions.get(prediction.id);
+ *
+ * // List recent predictions by model
+ * const { data } = await client.predictions.list({ model: "flux-pro", since: "2026-01-01" });
+ * ```
+ */
+export declare class PredictionsAPI {
+    private http;
+    private onBeforePredict?;
+    /** @internal */
+    constructor(http: HTTP, onBeforePredict?: (payload: PredictionRequest, sdk?: PredictionSdkOptions) => Promise<void>);
+    /**
+     * Creates a prediction in the background (does not wait for completion).
+     *
+     * The prediction starts processing asynchronously. Use {@link get} to poll,
+     * or {@link SkytellsClient.wait} to block until it finishes.
+     *
+     * @param payload - The prediction request parameters.
+     * @param payload.model - The model slug (e.g. `"flux-pro"`).
+     * @param payload.input - Key-value input parameters for the model.
+     * @param payload.webhook - Optional webhook to receive events.
+     * @param payload.stream - Enable streaming (default: `false`).
+     * @param sdk - SDK-only options (not sent in JSON). When `sdk.compatibilityCheck === true`, runs inference compatibility guard before POST.
+     * @returns The initial prediction response with `status: 'pending'` or `'starting'`.
+     * @throws {SkytellsError} On API errors (invalid input, model not found, insufficient credits).
+     *
+     * @example
+     * ```ts
+     * const prediction = await client.predictions.create({
+     *   model: "flux-pro",
+     *   input: { prompt: "An astronaut riding a unicorn" },
+     * });
+     * console.log(prediction.id, prediction.status); // "pending"
+     *
+     * // Wait for it to finish
+     * const result = await client.wait(prediction);
+     * console.log(result.output);
+     * ```
+     */
+    create(payload: PredictionRequest, sdk?: PredictionSdkOptions): Promise<PredictionResponse>;
+    /**
+     * Fetches a prediction by its ID.
+     *
+     * @param id - The prediction ID.
+     * @param urls - Optional `urls` from a prior `PredictionResponse`. When `urls.get` is set, that absolute URL is used (API protocol); otherwise `GET {baseUrl}/predictions/{id}`.
+     * @returns The prediction response with current status, output, metrics, etc.
+     * @throws {SkytellsError} If the prediction is not found or the request fails.
+     *
+     * @example
+     * ```ts
+     * const prediction = await client.predictions.get("pred_abc123");
+     * if (prediction.status === "succeeded") {
+     *   console.log(prediction.output);
+     * }
+     * ```
+     */
+    get(id: string, urls?: PredictionResponse['urls']): Promise<PredictionResponse>;
+    /**
+     * Lists predictions with optional filters and pagination.
+     *
+     * @param options - Filter and pagination options.
+     * @param options.page - Page number (default: 1).
+     * @param options.since - Only include predictions created on or after this date (`YYYY-MM-DD`).
+     * @param options.until - Only include predictions created on or before this date (`YYYY-MM-DD`).
+     * @param options.model - Filter by model slug.
+     * @returns A paginated response with `data` (predictions array) and `pagination` metadata.
+     * @throws {SkytellsError} On authentication failure or invalid parameters.
+     *
+     * @example
+     * ```ts
+     * // List all predictions
+     * const { data, pagination } = await client.predictions.list();
+     *
+     * // Filter by model and date range
+     * const filtered = await client.predictions.list({
+     *   model: "flux-pro",
+     *   since: "2026-01-01",
+     *   until: "2026-03-15",
+     *   page: 2,
+     * });
+     * ```
+     */
+    list(options?: PredictionsListOptions): Promise<PaginatedResponse<PredictionResponse>>;
+}
+/**
+ * Sub-API for browsing and fetching models. Accessible via `client.models`.
+ *
+ * Provides `.list()` to get all models and `.get()` to fetch a single model by slug.
+ *
+ * @example
+ * ```ts
+ * const allModels = await client.models.list();
+ * const model = await client.models.get("flux-pro", { fields: ["input_schema"] });
+ * ```
+ */
+export declare class ModelsAPI {
+    private http;
+    /** @internal */
+    constructor(http: HTTP);
+    /**
+     * Lists all available models on the Skytells platform.
+     *
+     * @param options - Optional configuration.
+     * @param options.fields - Additional fields to include in the response
+     *   (e.g. `["input_schema", "output_schema"]`). By default, schemas are not included.
+     * @returns An array of model objects with name, type, pricing, metadata, etc.
+     * @throws {SkytellsError} On authentication failure or server error.
+     *
+     * @example
+     * ```ts
+     * const allModels = await client.models.list();
+     * for (const m of allModels) {
+     *   console.log(m.name, m.type);
+     * }
+     *
+     * // Include input schemas
+     * const withSchemas = await client.models.list({ fields: ["input_schema"] });
+     * ```
+     */
+    list(options?: ModelFieldsOptions): Promise<Model[]>;
+    /**
+     * Fetches a single model by its slug.
+     *
+     * @param slug - The model slug identifier (e.g. `"flux-pro"`, `"truefusion"`, `"beatfusion"`).
+     * @param options - Optional configuration.
+     * @param options.fields - Additional fields to include (e.g. `["input_schema", "output_schema"]`).
+     * @returns The model object with name, type, pricing, metadata, and optionally schemas.
+     * @throws {SkytellsError} If the model is not found (`MODEL_NOT_FOUND`) or the request fails.
+     *
+     * @example
+     * ```ts
+     * const model = await client.models.get("flux-pro");
+     * console.log(model.name, model.pricing);
+     *
+     * // With schemas
+     * const detailed = await client.models.get("flux-pro", {
+     *   fields: ["input_schema", "output_schema"],
+     * });
+     * console.log(detailed.input_schema);
+     * ```
+     */
+    get(slug: string, options?: ModelFieldsOptions): Promise<Model>;
+}
+/**
+ * The main Skytells API client. Provides methods to run predictions, list models,
+ * and manage prediction lifecycle.
+ *
+ * Create an instance using {@link Skytells} or the constructor directly.
+ *
+ * @example
+ * ```ts
+ * import Skytells from "skytells";
+ *
+ * const client = Skytells("sk-your-api-key", {
+ *   timeout: 30000,
+ *   retry: { retries: 2 },
+ * });
+ *
+ * // Run a model and get output
+ * const prediction = await client.run("flux-pro", {
+ *   input: { prompt: "An astronaut riding a unicorn" },
+ * });
+ * const [imageUrl] = prediction.output;
+ *
+ * // List and fetch models
+ * const allModels = await client.models.list();
+ * const model = await client.models.get("flux-pro");
+ *
+ * // Background prediction
+ * const bg = await client.predictions.create({
+ *   model: "flux-pro",
+ *   input: { prompt: "A sunset" },
+ * });
+ * const result = await client.wait(bg);
+ *
+ * // Queue multiple predictions
+ * client.queue({ model: "flux-pro", input: { prompt: "Cat" } });
+ * client.queue({ model: "flux-pro", input: { prompt: "Dog" } });
+ * const results = await client.dispatch();
+ * ```
+ */
 export declare class SkytellsClient {
     private http;
+    private readonly _runtime;
+    private readonly _requestTimeoutMs;
+    private readonly _prefetchCap;
+    private _queue;
+    private _predictions?;
+    private _models?;
+    private _chat?;
+    private _responses?;
+    private _embeddings?;
+    private _safety?;
+    private _orchestrator?;
+    private readonly _orchestratorApiKey?;
+    private readonly _orchestratorBaseUrl;
+    private readonly _orchestratorHttpBundle;
+    /**
+     * Sub-API for managing predictions.
+     * Provides `.create()`, `.get()`, and `.list()` methods.
+     */
+    get predictions(): PredictionsAPI;
+    /**
+     * Alias of {@link predictions} (singular). Same instance — use whichever reads best.
+     *
+     * @example
+     * ```ts
+     * await client.prediction.create({ model: 'flux-pro', input: { prompt: '…' } });
+     * // same as client.predictions.create(...)
+     * ```
+     */
+    get prediction(): PredictionsAPI;
+    /**
+     * Sub-API for browsing and fetching models.
+     * Provides `.list()` and `.get()` methods.
+     */
+    get models(): ModelsAPI;
     /**
-     * Creates a new Skytells client
-     * @param apiKey Your Skytells API key
-     * @param options Configuration options
+     * Chat completions. Same as OpenAI's client.chat.completions.
+     *
+     * @example
+     * ```ts
+     * const completion = await client.chat.completions.create({
+     *   model: 'deepbrain-router',
+     *   messages: [{ role: 'user', content: 'Hello' }],
+     * });
+     * ```
+     */
+    get chat(): Chat;
+    /**
+     * Responses API (`POST /v1/responses`). Same as `client.chat.responses`.
+     *
+     * Follows the OpenAI Responses API schema. Supports both non-streaming and streaming modes.
+     *
+     * @example Non-streaming:
+     * ```ts
+     * const response = await client.responses.create({
+     *   model: 'gpt-5.3-codex',
+     *   input: [{ role: 'user', content: 'Explain recursion simply.' }],
+     *   instructions: 'You are a helpful tutor.',
+     * });
+     * console.log(response.output[0].content[0].text);
+     * ```
+     *
+     * @example Streaming:
+     * ```ts
+     * const stream = await client.responses.create({
+     *   model: 'gpt-5.3-codex',
+     *   input: [{ role: 'user', content: 'Explain recursion simply.' }],
+     *   stream: true,
+     * });
+     * for await (const event of stream) {
+     *   console.log(event.type, event);
+     * }
+     * ```
+     */
+    get responses(): Responses;
+    /**
+     * Embeddings. Same as OpenAI's client.embeddings.
+     *
+     * @example
+     * ```ts
+     * const embedding = await client.embeddings.create({
+     *   model: 'text-embedding-3-small',
+     *   input: 'Hello world',
+     * });
+     * ```
+     */
+    get embeddings(): Embeddings;
+    /**
+     * Safety checks. Proactive (checkText, checkImage) and response parsing (wasFiltered, evaluate).
+     * evaluate() accepts text, image URLs, choices, completions, prediction results, or arrays of any.
+     *
+     * @example
+     * ```ts
+     * const result = await client.safety.checkText('user input');
+     * if (client.safety.wasFiltered(completion)) { ... }
+     * const evalResult = await client.safety.evaluate('user text', SafetyTemplates.STRICT);
+     * ```
+     */
+    get safety(): Safety;
+    /**
+     * [Skytells Orchestrator](https://learn.skytells.ai/docs/products/orchestrator/api-reference) — workflows,
+     * executions, webhook triggers, integrations, etc.
+     *
+     * Requires **`ClientOptions.orchestratorApiKey`** (`wfb_…`). Uses an internal HTTP stack aimed at the Orchestrator
+     * host ({@link ORCHESTRATOR_BASE_URL}): Bearer only, no `x-api-key`. Same `timeout`, `headers`, `retry`, and
+     * `fetch` as the main Skytells client — pass both keys on one {@link SkytellsClient} when you need both products.
+     *
+     * @throws {SkytellsError} `SDK_ERROR` if `orchestratorApiKey` was not set.
+     */
+    get orchestrator(): Orchestrator;
+    /**
+     * Target runtime from {@link ClientOptions.runtime} (`"default"` when omitted).
+     */
+    get runtime(): SkytellsRuntime;
+    /**
+     * Read-only resolved settings (timeouts, cache cap) for debugging and tests.
+     */
+    get config(): Readonly<{
+        runtime: SkytellsRuntime;
+        requestTimeoutMs: number;
+        prefetchMaxSlugs: number;
+    }>;
+    /**
+     * In-memory `GET /model/{slug}` results for the per-prediction guard. Lazy-allocated; bounded by
+     * {@link SkytellsClient.config | config.prefetchMaxSlugs} and TTL {@link PREFETCHED_MODEL_CACHE_TTL_MS}.
+     */
+    private _prefetchedModelCache;
+    /**
+     * Creates a new Skytells API client.
+     *
+     * @param apiKey - Your Skytells API key (starts with `sk-`). Required for authenticated endpoints.
+     * @param options - Client configuration options.
+     * @param options.baseUrl - Override the default API base URL.
+     * @param options.timeout - Request timeout in milliseconds (default: 60000, or 25000 when `runtime: "edge"` and omitted).
+     * @param options.headers - Custom headers to include in every request.
+     * @param options.retry - Retry configuration: `retries`, `retryDelay`, `retryOn` status codes.
+     * @param options.fetch - Custom `fetch` implementation (useful for testing, proxying, or
+     *   disabling Next.js fetch caching).
+     * @param options.runtime - `"edge"` for Workers / Vercel Edge / etc.: shorter default timeout, smaller compat cache, one-time hints.
+     *
+     * @example
+     * ```ts
+     * const client = new SkytellsClient("sk-your-api-key");
+     *
+     * // With options:
+     * const client = new SkytellsClient("sk-your-api-key", {
+     *   timeout: 30000,
+     *   retry: { retries: 3, retryDelay: 1000 },
+     *   headers: { "X-Custom-Header": "value" },
+     * });
+     *
+     * // Next.js App Router — disable fetch caching:
+     * const client = new SkytellsClient("sk-your-api-key", {
+     *   fetch: (url, opts) => fetch(url, { ...opts, cache: "no-store" }),
+     * });
+     *
+     * // Edge / serverless:
+     * const edge = new SkytellsClient("sk-…", { runtime: "edge" });
+     *
+     * // Skytells + Orchestrator (optional wfb_… key — same client):
+     * const both = new SkytellsClient("sk-…", { orchestratorApiKey: "wfb_…" });
+     * ```
      */
     constructor(apiKey?: string, options?: ClientOptions);
     /**
-     * Send a prediction request to the Skytells API
-     * @param payload The prediction request parameters
-     * @returns A promise that resolves to the prediction response
+     * Build a {@link WebhookListener} for your HTTP server. Verifies `X-Skytells-Signature` per
+     * [Skytells webhooks](https://docs.skytells.ai/webhooks/).
+     *
+     * - **`mode: 'general'`** (default): HMAC key is your API key — omitted `apiKey` uses this client’s key.
+     * - **`mode: 'enterprise'`**: pass `secret` from the dashboard.
+     *
+     * @example
+     * ```ts
+     * const hooks = client.webhookListener({ mode: 'general' });
+     * hooks.on(WebhookEvent.COMPLETED, async (p) => console.log(p.id));
+     * // Next.js: export async function POST(req: Request) { return hooks.handleRequest(req); }
+     * ```
+     */
+    webhookListener(options?: WebhookListenerOptions): WebhookListener;
+    /**
+     * Alias of {@link SkytellsClient.webhookListener}. Chain handlers: `client.listen().on(WebhookEvent.COMPLETED, fn)`.
+     */
+    listen(options?: WebhookListenerOptions): WebhookListener;
+    /**
+     * Clears cached model metadata used when guarded predict/create/run passes `compatibilityCheck: true`.
+     *
+     * @param modelSlug - If set, only evicts that slug; otherwise clears the entire cache.
+     *
+     * @example
+     * ```ts
+     * // After a model was updated server-side, force the next predict to refetch metadata:
+     * client.purgePrefetchedModelCache("flux-pro");
+     *
+     * // Clear all cached slugs
+     * client.purgePrefetchedModelCache();
+     * ```
+     */
+    purgePrefetchedModelCache(modelSlug?: string): void;
+    /**
+     * Returns model metadata for the inference compatibility check, using {@link _prefetchedModelCache} when fresh.
+     */
+    private _getModelForCompatibilityCheck;
+    /**
+     * @internal When `compatibilityCheck === true`, throws SDK_ERROR if the model is chat-only here.
+     */
+    private _maybeCompatibilityGuard;
+    /**
+     * Sends a prediction request to the Skytells API.
+     *
+     * This is the low-level prediction method. For most use cases, prefer {@link run}
+     * which waits for completion and returns a {@link Prediction} object with convenience methods.
+     *
+     * @param payload - The prediction request parameters.
+     * @param payload.model - The model slug to run (e.g. `"flux-pro"`, `"truefusion"`).
+     * @param payload.input - Key-value input parameters for the model (e.g. `{ prompt: "..." }`).
+     * @param payload.await - If `true`, the request blocks until the prediction completes (default: `false`).
+     * @param payload.stream - If `true`, enables streaming for the prediction (default: `false`).
+     * @param payload.webhook - Optional webhook configuration to receive prediction events.
+     * @param sdk - SDK-only options (not sent in JSON). When `sdk.compatibilityCheck === true`, runs inference compatibility guard before POST.
+     * @returns The prediction response object.
+     * @throws {SkytellsError} On API errors (invalid input, model not found, insufficient credits, etc.).
+     *
+     * @example
+     * ```ts
+     * // Fire-and-forget (returns immediately with status: "pending")
+     * const response = await client.predict({
+     *   model: "flux-pro",
+     *   input: { prompt: "A sunset over mountains" },
+     * });
+     * console.log(response.id); // use predictions.get(id) to poll
+     *
+     * // Wait for completion
+     * const result = await client.predict({
+     *   model: "flux-pro",
+     *   input: { prompt: "A sunset over mountains" },
+     *   await: true,
+     * });
+     * console.log(result.output); // ["https://..."]
+     * ```
+     */
+    predict(payload: PredictionRequest, sdk?: PredictionSdkOptions): Promise<PredictionResponse>;
+    /**
+     * Runs a model, waits for completion, and returns a {@link Prediction} object.
+     *
+     * This is the recommended way to generate content. It automatically sets `await: true`,
+     * checks for failures, and returns a `Prediction` with `.output`, `.cancel()`, and `.delete()`.
+     *
+     * If an `onProgress` callback is provided, the prediction is created in the background
+     * and polled every 5 seconds. The callback is invoked on each poll with the latest
+     * prediction state, allowing you to track progress.
+     *
+     * @param model - The model slug to run (e.g. `"flux-pro"`, `"truefusion"`, `"beatfusion"`).
+     * @param options - Run options.
+     * @param options.input - Key-value input parameters for the model.
+     * @param options.stream - If `true`, enables streaming (default: `false`).
+     * @param options.webhook - Optional webhook configuration.
+     * @param onProgress - Optional callback invoked on each poll with the current prediction state.
+     * @param sdk - SDK-only options. When `sdk.compatibilityCheck === true`, runs inference guard before predict/create. Use `undefined` for `onProgress` when you only need `sdk` (e.g. `run(m, o, undefined, { compatibilityCheck: true })`).
+     * @remarks With `onProgress`, uses `predictions.create` + {@link wait}. Then {@link RunOptions.interval},
+     *   {@link RunOptions.maxWait}, and {@link RunOptions.signal} apply (same as {@link WaitOptions}).
+     * @returns A {@link Prediction} object with output and lifecycle methods.
+     * @throws {SkytellsError} On API errors or if the prediction fails (`PREDICTION_FAILED`).
+     *
+     * @example
+     * ```ts
+     * // Simple run (blocks until complete)
+     * const prediction = await client.run("flux-pro", {
+     *   input: { prompt: "An astronaut riding a rainbow unicorn" },
+     * });
+     * const [imageUrl] = prediction.output;
+     *
+     * // With progress tracking
+     * const prediction = await client.run("flux-pro", {
+     *   input: { prompt: "An astronaut riding a unicorn" },
+     * }, (p) => {
+     *   // Note: metrics.progress may not be available during early processing stages
+     *   console.log(`Status: ${p.status}, Progress: ${p.metrics?.progress ?? 'n/a'}`);
+     * });
+     * ```
+     */
+    run(model: string, options: RunOptions, onProgress?: OnProgressCallback, sdk?: PredictionSdkOptions): Promise<Prediction>;
+    /**
+     * Polls a prediction until it reaches a terminal status (`succeeded`, `failed`, or `cancelled`).
+     *
+     * @param prediction - The prediction response to wait on (must have an `id`).
+     * @param options - Polling options.
+     * @param options.interval - Polling interval in milliseconds (default: 5000).
+     * @param options.maxWait - Maximum wait time in milliseconds. Throws if exceeded.
+     * @param options.signal - If aborted, stops polling and throws `ABORTED` (no further poll timers scheduled).
+     * @param onProgress - Optional callback invoked on each poll with the latest prediction state.
+     * @returns The final prediction response.
+     * @throws {SkytellsError} If `maxWait` is exceeded (`WAIT_TIMEOUT`) or `signal` is aborted (`ABORTED`).
+     *
+     * @example
+     * ```ts
+     * const bg = await client.predictions.create({
+     *   model: "flux-pro",
+     *   input: { prompt: "A cat" },
+     * });
+     *
+     * const result = await client.wait(bg);
+     * console.log(result.output);
+     *
+     * // With progress and timeout
+     * const result = await client.wait(bg, { interval: 2000, maxWait: 120000 }, (p) => {
+     *   console.log(p.status, p.metrics?.progress);
+     * });
+     * ```
+     */
+    wait(prediction: PredictionResponse, options?: WaitOptions, onProgress?: OnProgressCallback): Promise<PredictionResponse>;
+    /**
+     * Adds a prediction request to the local queue.
+     *
+     * Queued items are not sent to the API until {@link dispatch} is called.
+     * Useful for batching multiple predictions together.
+     *
+     * @param payload - The prediction request to queue.
+     * @param sdk - Optional SDK options for this item (e.g. `{ compatibilityCheck: true }`), forwarded to {@link PredictionsAPI.create} on {@link dispatch}.
+     *
+     * @example
+     * ```ts
+     * client.queue({ model: "flux-pro", input: { prompt: "Cat" } });
+     * client.queue({ model: "flux-pro", input: { prompt: "Dog" } });
+     * client.queue({ model: "flux-pro", input: { prompt: "Bird" } });
+     *
+     * const results = await client.dispatch();
+     * // results is an array of PredictionResponse for each queued item
+     * ```
+     */
+    queue(payload: PredictionRequest, sdk?: PredictionSdkOptions): void;
+    /**
+     * Dispatches all queued predictions, sending them to the API concurrently.
+     *
+     * Clears the queue after dispatching. Each prediction is created in the background
+     * (non-blocking). Use {@link wait} on individual results if you need to wait for completion.
+     *
+     * @returns An array of prediction responses, one for each queued item.
+     * @throws {SkytellsError} Uses **`Promise.all`**: if **any** `predictions.create` rejects, the whole
+     *   `dispatch()` rejects with that error (fail-fast). Partial successes are not returned.
+     *
+     * @example
+     * ```ts
+     * client.queue({ model: "flux-pro", input: { prompt: "Cat" } });
+     * client.queue({ model: "flux-pro", input: { prompt: "Dog" } });
+     *
+     * const results = await client.dispatch();
+     * for (const pred of results) {
+     *   console.log(pred.id, pred.status);
+     * }
+     *
+     * // Wait for all to complete
+     * const completed = await Promise.all(results.map(p => client.wait(p)));
+     * ```
+     */
+    dispatch(): Promise<PredictionResponse[]>;
+    /**
+     * Retrieves the streaming endpoint for a prediction.
+     *
+     * @deprecated Use {@link Prediction.stream} on the {@link Prediction} from {@link SkytellsClient.run} instead,
+     * or pass `urls` from a stored `PredictionResponse` when calling without a `Prediction` instance.
+     *
+     * @param id - The prediction ID to stream.
+     * @param urls - Optional `urls` from a prior `PredictionResponse`. When `urls.stream` is set, that URL is used.
+     * @returns The prediction response with streaming URL info.
+     * @throws {SkytellsError} If the prediction is not found or streaming is not available.
+     *
+     * @example
+     * ```ts
+     * const stream = await client.streamPrediction("pred_abc123");
+     * console.log(stream.urls?.stream);
+     * ```
+     */
+    streamPrediction(id: string, urls?: PredictionResponse['urls']): Promise<PredictionResponse>;
+    /**
+     * Cancels a running prediction by its ID.
+     *
+     * @deprecated Use {@link Prediction.cancel} on the {@link Prediction} from {@link SkytellsClient.run} instead.
+     * Only predictions with status `pending`, `starting`, `started`, or `processing` can be cancelled.
+     *
+     * @param id - The prediction ID to cancel.
+     * @param urls - Optional `urls` from a prior `PredictionResponse`. When `urls.cancel` is set, that URL is used.
+     * @returns The updated prediction response with `status: 'cancelled'`.
+     * @throws {SkytellsError} If the prediction cannot be cancelled or is not found.
+     *
+     * @example
+     * ```ts
+     * await client.cancelPrediction("pred_abc123");
+     * ```
+     */
+    cancelPrediction(id: string, urls?: PredictionResponse['urls']): Promise<PredictionResponse>;
+    /**
+     * Deletes a prediction and its associated output/assets.
+     *
+     * @deprecated Use {@link Prediction.delete} on the {@link Prediction} from {@link SkytellsClient.run} instead.
+     *
+     * @param id - The prediction ID to delete.
+     * @param urls - Optional `urls` from a prior `PredictionResponse`. When `urls.delete` is set, that URL is used.
+     * @returns The prediction response confirming deletion.
+     * @throws {SkytellsError} If the prediction is not found or the request fails.
+     *
+     * @example
+     * ```ts
+     * await client.deletePrediction("pred_abc123");
+     * ```
      */
-    predict(payload: PredictionRequest): Promise<PredictionResponse>;
+    deletePrediction(id: string, urls?: PredictionResponse['urls']): Promise<PredictionResponse>;
+    /** Stops {@link wait} polling when `signal` aborts; clears the pending timer so nothing keeps firing. */
+    private static abortWaitError;
     /**
-     * Get a prediction by ID
-     * @param id The prediction ID
-     * @returns A promise that resolves to the prediction response
+     * @param signal - When present and aborted, the promise rejects with `ABORTED` and the timer is cleared.
      */
-    getPrediction(id: string): Promise<PredictionResponse>;
+    private delay;
     /**
-     * List all available models
-     * @returns A promise that resolves to an array of models
+     * @deprecated Use {@link predictions}.list() instead. This method will be removed in a future version.
      */
-    listModels(): Promise<Model[]>;
+    listPredictions(page?: number): Promise<PaginatedResponse<PredictionResponse>>;
     /**
-     * Stream a prediction by ID
-     * @param id The prediction ID
-     * @returns A promise that resolves to the prediction response
+     * @deprecated Use {@link models}.list() instead. This method will be removed in a future version.
      */
-    streamPrediction(id: string): Promise<PredictionResponse>;
+    listModels(options?: ModelFieldsOptions): Promise<Model[]>;
     /**
-     * Cancel a prediction by ID
-     * @param id The prediction ID
-     * @returns A promise that resolves to the prediction response
+     * @deprecated Use {@link predictions}.get() instead. This method will be removed in a future version.
      */
-    cancelPrediction(id: string): Promise<PredictionResponse>;
+    getPrediction(id: string, urls?: PredictionResponse['urls']): Promise<PredictionResponse>;
     /**
-     * Delete a prediction by ID
-     * @param id The prediction ID
-     * @returns A promise that resolves to the prediction response
+     * @deprecated Use {@link models}.get() instead. This method will be removed in a future version.
      */
-    deletePrediction(id: string): Promise<PredictionResponse>;
+    getModel(slug: string, options?: ModelFieldsOptions): Promise<Model>;
 }