ql-agent-sdk 1.0.2 → 1.2.0

package/dist/index.d.cts

@@ -4,6 +4,11 @@ interface JsonRequestOptions {
     signal?: AbortSignal;
     headers?: Record<string, string>;
 }
+interface FormRequestOptions {
+    form: FormData;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
 /**
  * Internal transport used by the API namespaces. Keeps the API key inside a
  * closure (never exposed) and normalizes responses/errors for the caller.
@@ -11,6 +16,8 @@ interface JsonRequestOptions {
 interface Transport {
     /** Perform a JSON request and return the unwrapped `data` payload. */
     json<T>(method: string, path: string, opts?: JsonRequestOptions): Promise<T>;
+    /** Perform a multipart/form-data request and return the unwrapped `data` payload. */
+    form<T>(path: string, opts: FormRequestOptions): Promise<T>;
     /**
      * Perform a request expected to stream SSE. Returns the response body stream
      * after verifying a 2xx + text/event-stream; throws QLError otherwise.
@@ -49,6 +56,8 @@ interface ChatInput {
     messages: ChatMessage[];
     /** Optional internal user id; defaults to the key's workspace when omitted. */
     userId?: string;
+    /** Optional OpenRouter model id override — wins over the workspace director-panel default. */
+    modelId?: string;
     /** Optional OpenRouter response-format hint (e.g. `{ type: "json_object" }`). */
     response_format?: Record<string, unknown>;
 }
@@ -328,6 +337,8 @@ interface ImageReferenceInput {
 /** Input for `images.generate`. */
 interface ImageGenerateInput {
     prompt: string;
+    /** Explicit registry model id override (wins over `model`, the workspace default, and `tier`). */
+    modelId?: string;
     /** Explicit OpenRouter model id (wins over `tier`). */
     model?: string;
     /** Tier to resolve a model from (used when `model` is omitted). */
@@ -359,6 +370,263 @@ interface ImageGenerateResult {
     tier: string;
     latencyMs: number;
 }
+type VideoTier = "standard" | "professional" | "advanced";
+/** A single pricing entry for a video model. */
+interface VideoPricingEntry {
+    /** What is billed, e.g. "output_video" / "voiceover". */
+    billable: string;
+    /** Billing unit: per rendered second, or flat per request. */
+    unit: "second" | "request";
+    costUsd: number;
+}
+/** A tiered video-generation model as returned by `videos.listModels`. */
+interface VideoModelInfo {
+    id: string;
+    name: string;
+    tier: VideoTier;
+    description: string;
+    /** Short best-use-case label for UI copy. */
+    bestFor: string;
+    /** Execution engine (e.g. "motion-graphics"). */
+    engine: string;
+    supportsProductImages: boolean;
+    maxReferenceImages: number;
+    supportsReferenceVideos: boolean;
+    maxReferenceVideos: number;
+    supportedAspectRatios: string[];
+    supportedResolutions: string[];
+    /** Inclusive [min, max] duration in seconds. */
+    durationRange: [number, number];
+    voiceoverSupport: boolean;
+    pricing: {
+        summary: string;
+        entries: VideoPricingEntry[];
+    };
+    recommended: boolean;
+    enabled: boolean;
+    /** Runtime engine availability (render toolchain present). */
+    available: boolean;
+}
+/** Result of `videos.listModels`. */
+interface VideoModelsResult {
+    models: VideoModelInfo[];
+    engine: {
+        available: boolean;
+        detail: string;
+    };
+}
+/** Input for `videos.generate`. */
+interface VideoGenerateInput {
+    /** The creative brief / script for the video. */
+    prompt: string;
+    /** Explicit registry model id override (wins over `model`, the workspace default, and `tier`). */
+    modelId?: string;
+    /** Explicit registry model id (wins over `tier`). */
+    model?: string;
+    /** Tier to resolve a model from (used when `model` is omitted). */
+    tier?: VideoTier | string;
+    /** Product/reference images — base64 data URLs or https URLs. Order defines IMG_0..N. */
+    images_list?: string[];
+    /** Reference (style) videos — https URLs only (upload local files via `files.upload`). */
+    video_files?: string[];
+    /** e.g. "16:9", "9:16", "1:1". Default "16:9". */
+    aspect_ratio?: string;
+    /** Duration in seconds (must be within the model's durationRange). */
+    duration?: number;
+    /** e.g. "720p" | "1080p". Default "720p". */
+    resolution?: string;
+    /** Bake an ElevenLabs voiceover into the render (requires `narration`). */
+    generate_audio?: boolean;
+    /** Voiceover text (used when `generate_audio` is true). Max 3000 chars. */
+    narration?: string;
+}
+/** Returned when a video job is created (HTTP 202). */
+interface VideoTaskCreated {
+    taskId: string;
+    status: "queued";
+}
+type VideoTaskStatus = "queued" | "rendering" | "completed" | "failed" | "cancelled" | (string & {});
+/** A video job snapshot, as returned by `videos.getTask`. */
+interface VideoTask {
+    taskId: string;
+    status: VideoTaskStatus;
+    progress?: {
+        current: number;
+        total: number;
+        message?: string;
+    };
+    /** Served media path (e.g. /generated/video-….mp4) once completed. */
+    outputUrl?: string;
+    mime?: string;
+    ext?: string;
+    /** Actual rendered duration in seconds. */
+    durationSec?: number;
+    error?: string;
+    model?: string;
+    tier?: string;
+    latencyMs?: number;
+    createdAt: string | Date;
+    completedAt: string | Date | null;
+}
+/** Options for polling / waiting on a video job. */
+interface VideoWaitOptions {
+    /** Base delay between polls in ms (default 2000). Grows with backoff up to `maxIntervalMs`. */
+    intervalMs?: number;
+    /** Upper bound for the backoff delay in ms (default 15000). */
+    maxIntervalMs?: number;
+    /** Stop waiting after this many ms and throw a timeout error. Omit to wait until terminal or abort. */
+    timeoutMs?: number;
+    /** Abort polling at any time. */
+    signal?: AbortSignal;
+    /** Called after each poll with the latest job snapshot. */
+    onTick?: (task: VideoTask) => void;
+}
+/** Per-role model defaults as configured in the director panel. */
+interface WorkspaceModelConfig {
+    status: "active" | "inactive";
+    /** Masked OpenRouter key — the raw key is never returned by the API. */
+    keyMasked: string;
+    /** Optional chat-completions base URL override (empty = public OpenRouter API). */
+    baseUrl: string;
+    reasoning: string;
+    instruct: string;
+    response: string;
+    vision: string;
+    image: string;
+    video: string;
+    /** Ordered per-role fallback model ids (max 3 each), tried on provider failure. */
+    fallbacks: {
+        reasoning: string[];
+        instruct: string[];
+        response: string[];
+        vision: string[];
+        image: string[];
+        video: string[];
+    };
+}
+/** Result of `workspace.getModels`. */
+interface WorkspaceModelsResult {
+    openrouter: WorkspaceModelConfig;
+}
+/** Partial model-config update for `workspace.update` / `workspace.updateModels`. */
+interface WorkspaceModelsUpdateInput {
+    status?: "active" | "inactive";
+    /** Full OpenRouter API key to store/rotate. Omit to leave unchanged. */
+    key?: string;
+    /** Optional chat-completions base URL override (defaults to the public OpenRouter API). */
+    baseUrl?: string;
+    reasoning?: string;
+    instruct?: string;
+    response?: string;
+    vision?: string;
+    image?: string;
+    video?: string;
+    /** Ordered per-role fallback model ids (max 3 each). */
+    fallbacks?: {
+        reasoning?: string[];
+        instruct?: string[];
+        response?: string[];
+        vision?: string[];
+        image?: string[];
+        video?: string[];
+    };
+}
+/** Input for `workspace.update`. */
+interface WorkspaceUpdateInput {
+    name?: string;
+    config?: {
+        openrouter?: WorkspaceModelsUpdateInput;
+    };
+}
+/** A single OpenRouter catalog model. */
+interface CatalogModel {
+    id: string;
+    name: string;
+    contextLength: number | null;
+    promptPrice: number | null;
+    completionPrice: number | null;
+}
+/** Result of `workspace.listCatalogModels`. */
+interface CatalogResult {
+    models: CatalogModel[];
+    /** True when the upstream fetch failed and a cached snapshot was served. */
+    stale?: boolean;
+}
+/** Result of `workspace.verifyOpenRouterKey`. */
+interface VerifyKeyResult {
+    valid: boolean;
+    error?: string;
+}
+/** A v1 API key with rotation metadata (hashes never leave the server). */
+interface ApiKeyInfo {
+    _id: string;
+    name: string;
+    prefix: string;
+    scopes: string[];
+    createdAt: string | Date;
+    lastUsedAt: string | Date | null;
+    revokedAt: string | Date | null;
+    /** When the key is auto-deleted (createdAt + lifetime). */
+    rotatesAt: string | Date;
+    /** Whole days remaining until rotation (0 when expired). */
+    daysLeft: number;
+}
+/** Result of `workspace.listKeys`. */
+interface KeysResult {
+    /** Key lifetime in days before auto-deletion. */
+    lifetimeDays: number;
+    keys: ApiKeyInfo[];
+}
+/** Input for `audio.textToSpeech`. */
+interface TtsInput {
+    /** Text to synthesize (max 3000 chars). */
+    text: string;
+    /** ElevenLabs voice id (list via `audio.voices`). Defaults to the platform voice. */
+    voiceId?: string;
+    /** Voice stability 0..1 (default 0.5). */
+    stability?: number;
+    /** Similarity boost 0..1 (default 0.75). */
+    similarityBoost?: number;
+}
+/** Result of `audio.textToSpeech`. */
+interface TtsResult {
+    /** Served audio path (e.g. /generated/tts-….mp3). */
+    url: string;
+    voiceId: string;
+    modelId: string;
+    bytes: number;
+    latencyMs: number;
+}
+/** A single ElevenLabs voice as returned by `audio.voices`. */
+interface VoiceInfo {
+    id: string;
+    name: string;
+}
+/** Result of `audio.voices`. */
+interface VoicesResult {
+    voices: VoiceInfo[];
+    /** "live" = fetched from the provider; "none" = no provider key configured. */
+    source: "live" | "none";
+    note?: string;
+}
+/** Result of `files.upload`. */
+interface UploadedFile {
+    /** Stable served path (e.g. /uploads/<workspace>/<file>) usable as a media input URL. */
+    url: string;
+    filename: string;
+    size: number;
+    contentType: string;
+}
+/** Options for `files.upload`. */
+interface FileUploadOptions {
+    /** Override the stored display name (extension is kept from the file). */
+    filename?: string;
+    /**
+     * Coarse progress callback. Fetch does not expose upload byte progress, so this
+     * reports 0 at start and 100 on completion.
+     */
+    onProgress?: (percent: number) => void;
+}
 
 declare function isTerminalTaskStatus(status: string): boolean;
 /**
@@ -377,15 +645,24 @@ declare class TaskHandle {
     get(signal?: AbortSignal): Promise<Task>;
     /** Alias of `get()` — perform one poll and return the latest snapshot. */
     poll(signal?: AbortSignal): Promise<Task>;
-    /**
-     * Poll until the task reaches a terminal status.
-     *
-     * - Uses exponential-ish backoff from `intervalMs` up to `maxIntervalMs`.
-     * - Throws a QLError with code "timeout" if `timeoutMs` elapses first.
-     * - Throws a QLError with code "aborted" if `signal` aborts.
-     */
+    /** Poll until the task reaches a terminal status (see pollUntilTerminal for semantics). */
     wait(opts?: WaitOptions): Promise<Task>;
 }
+/**
+ * A handle to a video job created via `videos.generate`.
+ * Polls the video-tasks endpoint until the job reaches a terminal status.
+ */
+declare class VideoTaskHandle {
+    private readonly transport;
+    readonly taskId: string;
+    constructor(transport: Transport, taskId: string);
+    /** Fetch the current job snapshot (single request). */
+    get(signal?: AbortSignal): Promise<VideoTask>;
+    /** Alias of `get()` — perform one poll and return the latest snapshot. */
+    poll(signal?: AbortSignal): Promise<VideoTask>;
+    /** Poll until the job reaches a terminal status (completed/failed/cancelled). */
+    wait(opts?: VideoWaitOptions): Promise<VideoTask>;
+}
 
 declare const DEFAULT_BASE_URL = "https://app.quantonlabs.com";
 interface QLClientOptions {
@@ -402,6 +679,18 @@ declare class WorkspaceApi {
     constructor(t: Transport);
     /** GET /api/v1/workspace */
     get(): Promise<Workspace>;
+    /** GET /api/v1/workspace/models — current model config (OpenRouter key masked). */
+    getModels(): Promise<WorkspaceModelsResult>;
+    /** PATCH /api/v1/workspace — update the workspace name and/or OpenRouter model config (partial). */
+    update(input: WorkspaceUpdateInput): Promise<Workspace>;
+    /** PATCH /api/v1/workspace — convenience wrapper that only touches `config.openrouter`. */
+    updateModels(input: WorkspaceModelsUpdateInput): Promise<Workspace>;
+    /** GET /api/v1/workspace/models/catalog — OpenRouter model catalog (server-side cached). */
+    listCatalogModels(): Promise<CatalogResult>;
+    /** POST /api/v1/workspace/models/verify — check an OpenRouter key with a 1-token completion. */
+    verifyOpenRouterKey(key: string, model?: string, baseUrl?: string): Promise<VerifyKeyResult>;
+    /** GET /api/v1/workspace/keys — API keys with rotation metadata (rotatesAt, daysLeft). */
+    listKeys(): Promise<KeysResult>;
 }
 /** Agents namespace. */
 declare class AgentsApi {
@@ -458,6 +747,37 @@ declare class ImagesApi {
     /** POST /api/v1/agents/:agentId/images — generate image(s) via a tiered model. */
     generate(agentId: string, input: ImageGenerateInput): Promise<ImageGenerateResult>;
 }
+/** Videos namespace (tiered video generation: submit → poll). */
+declare class VideosApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/videos/models — list tiered video models + engine availability. */
+    listModels(): Promise<VideoModelsResult>;
+    /** POST /api/v1/agents/:agentId/videos — start a video job (returns the queued task, HTTP 202). */
+    generate(agentId: string, input: VideoGenerateInput): Promise<VideoTaskCreated>;
+    /** GET /api/v1/video-tasks/:taskId — fetch the current job snapshot. */
+    getTask(taskId: string, signal?: AbortSignal): Promise<VideoTask>;
+    /** DELETE /api/v1/video-tasks/:taskId — cancel a queued/rendering job (409 if already terminal). */
+    cancelTask(taskId: string): Promise<VideoTask>;
+    /** Get a handle for polling / waiting on a video job (poll(), wait()). */
+    handle(taskId: string): VideoTaskHandle;
+}
+/** Audio namespace (text-to-speech). */
+declare class AudioApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/audio/voices — list available TTS voices. */
+    voices(): Promise<VoicesResult>;
+    /** POST /api/v1/agents/:agentId/tts — synthesize speech (synchronous). */
+    textToSpeech(agentId: string, input: TtsInput): Promise<TtsResult>;
+}
+/** Files namespace (media uploads). */
+declare class FilesApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** POST /api/v1/files — upload a media file (multipart field "file"). */
+    upload(file: Blob, opts?: FileUploadOptions): Promise<UploadedFile>;
+}
 /**
  * The public client. Example:
  *   const ql = new QLClient({ apiKey: process.env.QL_API_KEY });
@@ -469,6 +789,9 @@ declare class QLClient {
     readonly workflows: WorkflowsApi;
     readonly tasks: TasksApi;
     readonly images: ImagesApi;
+    readonly videos: VideosApi;
+    readonly audio: AudioApi;
+    readonly files: FilesApi;
     private readonly transport;
     private readonly base;
     constructor(opts: QLClientOptions);
@@ -512,4 +835,4 @@ declare class QLError extends Error {
     get isNetworkError(): boolean;
 }
 
-export { API_ERROR_CODES, type AgentDetail, type AgentListResult, type AgentSummary, AgentsApi, type ApiErrorCode, type CapParamKind, type CapabilitiesResult, type CapabilityInfo, type CapabilityParam, type CapabilityResult, type CapabilityTemplate, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamEvent, DEFAULT_BASE_URL, type GeneratedImage, type HistoryPage, type HistoryParams, type ImageGenerateInput, type ImageGenerateResult, type ImageModelInfo, type ImageModelsResult, type ImagePricingEntry, type ImageReferenceInput, type ImageTier, type ImageUsage, ImagesApi, type MessageItem, QLClient, type QLClientOptions, QLError, type QLErrorContext, type RunCapabilityInput, type RunCapabilityResult, type StreamOptions, type Task, type TaskCreateInput, type TaskCreated, TaskHandle, type TaskPriority, type TaskStatus, TasksApi, type WaitOptions, type WorkflowRun, type WorkflowRunInput, type WorkflowRunStart, type WorkflowRunStatus, WorkflowsApi, type Workspace, WorkspaceApi, isTerminalTaskStatus };
+export { API_ERROR_CODES, type AgentDetail, type AgentListResult, type AgentSummary, AgentsApi, type ApiErrorCode, AudioApi, type CapParamKind, type CapabilitiesResult, type CapabilityInfo, type CapabilityParam, type CapabilityResult, type CapabilityTemplate, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamEvent, DEFAULT_BASE_URL, type FileUploadOptions, FilesApi, type GeneratedImage, type HistoryPage, type HistoryParams, type ImageGenerateInput, type ImageGenerateResult, type ImageModelInfo, type ImageModelsResult, type ImagePricingEntry, type ImageReferenceInput, type ImageTier, type ImageUsage, ImagesApi, type MessageItem, QLClient, type QLClientOptions, QLError, type QLErrorContext, type RunCapabilityInput, type RunCapabilityResult, type StreamOptions, type Task, type TaskCreateInput, type TaskCreated, TaskHandle, type TaskPriority, type TaskStatus, TasksApi, type TtsInput, type TtsResult, type UploadedFile, type VideoGenerateInput, type VideoModelInfo, type VideoModelsResult, type VideoPricingEntry, type VideoTask, type VideoTaskCreated, VideoTaskHandle, type VideoTaskStatus, type VideoTier, type VideoWaitOptions, VideosApi, type VoiceInfo, type VoicesResult, type WaitOptions, type WorkflowRun, type WorkflowRunInput, type WorkflowRunStart, type WorkflowRunStatus, WorkflowsApi, type Workspace, WorkspaceApi, isTerminalTaskStatus };