ql-agent-sdk 1.0.2 → 1.2.0

package/README.md

@@ -74,7 +74,7 @@ Create keys in your Quanton Labs dashboard → **API Keys** page. Each key is sc
 
 | Scope | Grants access to |
 |-------|-----------------|
-| `workspace` | `ql.workspace.get()` |
+| `workspace` | `ql.workspace.get()`, `ql.workspace.getModels()`, `ql.workspace.update()`, `ql.workspace.updateModels()`, `ql.workspace.listCatalogModels()`, `ql.workspace.verifyOpenRouterKey()`, `ql.workspace.listKeys()` |
 | `agents` | `ql.agents.list()`, `ql.agents.get()` |
 | `capabilities` | `ql.agents.capabilities()`, `ql.agents.runCapability()` |
 | `chat` | `ql.agents.chat()`, `ql.agents.chatStream()` |
@@ -133,6 +133,53 @@ ws.plan;     // "standard" | "premium" | "enterprise" | undefined
 ws.createdAt; // string (ISO 8601)
 ```
 
+#### `ql.workspace.getModels()` → `Promise<WorkspaceModelsResult>`
+
+**Scope:** `workspace`
+
+Returns the per-role model configuration (director panel): defaults for
+`reasoning`, `instruct`, `response`, `vision`, `image`, `video` plus ordered
+fallback lists. The OpenRouter key is always masked (`keyMasked`).
+
+#### `ql.workspace.update(input)` / `ql.workspace.updateModels(input)` → `Promise<Workspace>`
+
+**Scope:** `workspace`
+
+Partially updates the workspace. `update()` accepts `{ name?, config?: { openrouter? } }`;
+`updateModels()` is a shortcut that only touches `config.openrouter`. Model fields may be
+set to `""` to clear a default; each `fallbacks.<role>` list holds at most 3 model ids.
+
+```ts
+await ql.workspace.update({ name: "Robinson Mfg. Co., Inc." });
+await ql.workspace.updateModels({
+  reasoning: "deepseek/deepseek-v4-flash-0731",
+  vision: "anthropic/claude-sonnet-5.5",
+  fallbacks: { reasoning: ["openai/gpt-oss-20b"] },
+});
+```
+
+#### `ql.workspace.listCatalogModels()` → `Promise<CatalogResult>`
+
+**Scope:** `workspace`
+
+OpenRouter model catalog (`{ id, name, contextLength, promptPrice, completionPrice }[]`),
+cached server-side for 10 minutes. May return `stale: true` when upstream is down.
+
+#### `ql.workspace.verifyOpenRouterKey(key, model?, baseUrl?)` → `Promise<VerifyKeyResult>`
+
+**Scope:** `workspace`
+
+Checks an OpenRouter key with a 1-token completion (default model
+`openai/gpt-oss-20b`). Returns `{ valid: true }` or `{ valid: false, error }`.
+
+#### `ql.workspace.listKeys()` → `Promise<KeysResult>`
+
+**Scope:** `workspace`
+
+Lists the workspace's v1 API keys with rotation metadata. Every key is auto-deleted
+`lifetimeDays` (90) days after creation; `rotatesAt`/`daysLeft` show time remaining.
+Mint replacements from the Quanton Labs site when one expires.
+
 ---
 
 ### Agents
@@ -633,6 +680,127 @@ try {
 
 ---
 
+### Videos (Tiered Generation)
+
+Async video generation: submit a job, then poll until it completes. Reference images may be base64 data URLs or https URLs; reference (style) videos must be https URLs — upload local files with `ql.files.upload` first.
+
+#### `ql.videos.listModels()` → `Promise<VideoModelsResult>`
+
+Lists the tiered video models plus runtime engine availability: `{ models: VideoModelInfo[], engine: { available, detail } }`. Each model reports its tier, supported aspect ratios/resolutions, duration range, reference-image/video limits, voiceover support, and pricing.
+
+**Example:**
+```ts
+const { models, engine } = await ql.videos.listModels();
+if (!engine.available) console.warn("Video engine unavailable:", engine.detail);
+const recommended = models.find((m) => m.recommended && m.available);
+```
+
+#### `ql.videos.generate(agentId, input)` → `Promise<VideoTaskCreated>`
+
+Starts a video job (HTTP 202) and returns `{ taskId, status: "queued" }`.
+
+| Field | Description |
+|-------|-------------|
+| `prompt` | The creative brief / script for the video |
+| `model`? | Explicit registry model id (wins over `tier`) |
+| `tier`? | Tier to resolve a model from when `model` is omitted |
+| `images_list`? | Product/reference images — base64 data URLs or https URLs (order defines IMG_0..N) |
+| `video_files`? | Reference (style) videos — https URLs only |
+| `aspect_ratio`? | e.g. `"16:9"`, `"9:16"`, `"1:1"` (default `"16:9"`) |
+| `duration`? | Seconds, within the model's `durationRange` |
+| `resolution`? | e.g. `"720p"` / `"1080p"` (default `"720p"`) |
+| `generate_audio`? | Bake a voiceover into the render (requires `narration`) |
+| `narration`? | Voiceover text (max 3000 chars) |
+
+**Example:**
+```ts
+const created = await ql.videos.generate("marketing", {
+  prompt: "A 10-second product reel for the new sneaker drop, studio lighting.",
+  model: "motion/reel",
+  images_list: ["data:image/png;base64,..."], // or https URLs
+  video_files: ["https://cdn.example.com/style-ref.mp4"],
+  aspect_ratio: "9:16",
+  duration: 10,
+  resolution: "1080p",
+  generate_audio: true,
+  narration: "Introducing the all-new AirFlex.",
+});
+```
+
+#### `ql.videos.getTask(taskId, signal?)` → `Promise<VideoTask>`
+
+Fetches the current job snapshot: `{ taskId, status, progress?, outputUrl?, mime?, ext?, durationSec?, error?, model?, tier?, latencyMs?, createdAt, completedAt }`.
+
+#### `ql.videos.cancelTask(taskId)` → `Promise<VideoTask>`
+
+Cancels a queued/rendering job and returns the updated snapshot. Throws a `QLError` with code `"conflict"` (HTTP 409) if the job is already terminal.
+
+#### `ql.videos.handle(taskId)` → `VideoTaskHandle`
+
+Same `poll()` / `wait(opts?)` pattern as `TaskHandle`, polling `/api/v1/video-tasks/:taskId`. Terminal statuses: `completed` (check `outputUrl`), `failed` (check `error`), `cancelled`. Wait options and non-terminal exits (`timeout` / `aborted`) are identical to tasks.
+
+**Example:**
+```ts
+const done = await ql.videos.handle(created.taskId).wait({
+  intervalMs: 2000,
+  timeoutMs: 10 * 60_000,
+  onTick: (job) => {
+    if (job.progress?.message) process.stdout.write(`\r${job.progress.message}`);
+  },
+});
+if (done.status === "completed" && done.outputUrl) {
+  console.log("Video ready:", `${ql.baseUrl}${done.outputUrl}`);
+}
+```
+
+### Audio (Text-to-Speech)
+
+#### `ql.audio.voices()` → `Promise<VoicesResult>`
+
+Lists available TTS voices: `{ voices: { id, name }[], source: "live" | "none", note? }`. `source === "none"` means no provider key is configured server-side.
+
+#### `ql.audio.textToSpeech(agentId, input)` → `Promise<TtsResult>`
+
+Synchronous synthesis (no polling). Returns `{ url, voiceId, modelId, bytes, latencyMs }` where `url` is a served media path (e.g. `/generated/tts-….mp3`).
+
+| Field | Description |
+|-------|-------------|
+| `text` | Text to synthesize (max 3000 chars) |
+| `voiceId`? | Voice id from `ql.audio.voices()` (defaults to the platform voice) |
+| `stability`? | Voice stability 0..1 (default 0.5) |
+| `similarityBoost`? | Similarity boost 0..1 (default 0.75) |
+
+**Example:**
+```ts
+const { voices } = await ql.audio.voices();
+const result = await ql.audio.textToSpeech("marketing", {
+  text: "Say hello to the all-new AirFlex.",
+  voiceId: voices[0]?.id,
+});
+console.log(`${ql.baseUrl}${result.url}`);
+```
+
+### Files (Media Upload)
+
+#### `ql.files.upload(file, opts?)` → `Promise<UploadedFile>`
+
+Uploads a media file as multipart form data (field `"file"`) and returns `{ url, filename, size, contentType }`. The returned `url` is a stable served path (e.g. `/uploads/<workspace>/<file>`) that can be used directly as a media input URL — e.g. in `videos.generate({ video_files: [res.url] })`.
+
+| Option | Description |
+|--------|-------------|
+| `filename`? | Override the stored display name (extension is kept from the file) |
+| `onProgress`? | Coarse progress callback — fetch does not expose byte progress, so it reports 0 at start and 100 on completion only |
+
+**Example:**
+```ts
+const blob = await file.arrayBuffer(); // or any Blob source
+const uploaded = await ql.files.upload(new Blob([blob], { type: "video/mp4" }), {
+  filename: "style-ref.mp4",
+});
+```
+
+---
+
 ## Error Handling
 
 All API failures throw a typed **`QLError`**:

package/dist/index.cjs

@@ -22,12 +22,16 @@ var index_exports = {};
 __export(index_exports, {
   API_ERROR_CODES: () => API_ERROR_CODES,
   AgentsApi: () => AgentsApi,
+  AudioApi: () => AudioApi,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  FilesApi: () => FilesApi,
   ImagesApi: () => ImagesApi,
   QLClient: () => QLClient,
   QLError: () => QLError,
   TaskHandle: () => TaskHandle,
   TasksApi: () => TasksApi,
+  VideoTaskHandle: () => VideoTaskHandle,
+  VideosApi: () => VideosApi,
   WorkflowsApi: () => WorkflowsApi,
   WorkspaceApi: () => WorkspaceApi,
   isTerminalTaskStatus: () => isTerminalTaskStatus
@@ -135,6 +139,12 @@ function createTransport(opts) {
       if (!res.ok) throw toHttpError(res.status, text, { method, url: res.url });
       return unwrap(text, { method, url: res.url });
     },
+    async form(path, reqOpts) {
+      const res = await doFormFetch(path, reqOpts);
+      const text = await res.text();
+      if (!res.ok) throw toHttpError(res.status, text, { method: "POST", url: res.url });
+      return unwrap(text, { method: "POST", url: res.url });
+    },
     async stream(method, path, reqOpts = {}) {
       const res = await doFetch(method, path, {
         ...reqOpts,
@@ -175,6 +185,22 @@ function createTransport(opts) {
       throw toNetworkError(err, { method, url });
     });
   }
+  function doFormFetch(path, reqOpts) {
+    const url = buildUrl(baseUrl, path);
+    const headers = {
+      authorization: `Bearer ${apiKey}`,
+      accept: "application/json",
+      ...reqOpts.headers ?? {}
+    };
+    return fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: reqOpts.form,
+      signal: reqOpts.signal
+    }).catch((err) => {
+      throw toNetworkError(err, { method: "POST", url });
+    });
+  }
 }
 function unwrap(text, ctx) {
   const parsed = safeParse(text);
@@ -313,6 +339,27 @@ var TERMINAL_TASK_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "ca
 function isTerminalTaskStatus(status) {
   return TERMINAL_TASK_STATUSES.has(status);
 }
+async function pollUntilTerminal(fetchSnapshot, isTerminal, onTick, opts) {
+  const intervalMs = opts.intervalMs ?? 2e3;
+  const maxIntervalMs = opts.maxIntervalMs ?? 15e3;
+  const signal = opts.signal;
+  const startedAt = Date.now();
+  let delay = intervalMs;
+  for (; ; ) {
+    if (signal?.aborted) throw abortError();
+    if (opts.timeoutMs !== void 0 && Date.now() - startedAt >= opts.timeoutMs) {
+      throw timeoutError(opts.timeoutMs);
+    }
+    const snapshot = await fetchSnapshot(signal);
+    onTick?.(snapshot);
+    if (isTerminal(snapshot)) return snapshot;
+    if (opts.timeoutMs !== void 0 && Date.now() - startedAt >= opts.timeoutMs) {
+      throw timeoutError(opts.timeoutMs);
+    }
+    await sleep(delay, signal);
+    delay = Math.min(maxIntervalMs, Math.round(delay * 1.5));
+  }
+}
 var TaskHandle = class {
   constructor(transport, taskId) {
     this.transport = transport;
@@ -326,33 +373,37 @@ var TaskHandle = class {
   poll(signal) {
     return this.get(signal);
   }
-  /**
-   * 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). */
   async wait(opts = {}) {
-    const intervalMs = opts.intervalMs ?? 2e3;
-    const maxIntervalMs = opts.maxIntervalMs ?? 15e3;
-    const signal = opts.signal;
-    const startedAt = Date.now();
-    let delay = intervalMs;
-    for (; ; ) {
-      if (signal?.aborted) throw abortError();
-      if (opts.timeoutMs !== void 0 && Date.now() - startedAt >= opts.timeoutMs) {
-        throw timeoutError(opts.timeoutMs);
-      }
-      const task = await this.get(signal);
-      opts.onTick?.(task);
-      if (isTerminalTaskStatus(task.status)) return task;
-      if (opts.timeoutMs !== void 0 && Date.now() - startedAt >= opts.timeoutMs) {
-        throw timeoutError(opts.timeoutMs);
-      }
-      await sleep(delay, signal);
-      delay = Math.min(maxIntervalMs, Math.round(delay * 1.5));
-    }
+    return pollUntilTerminal(
+      (signal) => this.get(signal),
+      (task) => isTerminalTaskStatus(task.status),
+      opts.onTick,
+      opts
+    );
+  }
+};
+var VideoTaskHandle = class {
+  constructor(transport, taskId) {
+    this.transport = transport;
+    this.taskId = taskId;
+  }
+  /** Fetch the current job snapshot (single request). */
+  get(signal) {
+    return this.transport.json("GET", `/api/v1/video-tasks/${encodeURIComponent(this.taskId)}`, { signal });
+  }
+  /** Alias of `get()` — perform one poll and return the latest snapshot. */
+  poll(signal) {
+    return this.get(signal);
+  }
+  /** Poll until the job reaches a terminal status (completed/failed/cancelled). */
+  async wait(opts = {}) {
+    return pollUntilTerminal(
+      (signal) => this.get(signal),
+      (task) => isTerminalTaskStatus(task.status),
+      opts.onTick,
+      opts
+    );
   }
 };
 function sleep(ms, signal) {
@@ -387,6 +438,30 @@ var WorkspaceApi = class {
   get() {
     return this.t.json("GET", "/api/v1/workspace");
   }
+  /** GET /api/v1/workspace/models — current model config (OpenRouter key masked). */
+  getModels() {
+    return this.t.json("GET", "/api/v1/workspace/models");
+  }
+  /** PATCH /api/v1/workspace — update the workspace name and/or OpenRouter model config (partial). */
+  update(input) {
+    return this.t.json("PATCH", "/api/v1/workspace", { body: input });
+  }
+  /** PATCH /api/v1/workspace — convenience wrapper that only touches `config.openrouter`. */
+  updateModels(input) {
+    return this.t.json("PATCH", "/api/v1/workspace", { body: { config: { openrouter: input } } });
+  }
+  /** GET /api/v1/workspace/models/catalog — OpenRouter model catalog (server-side cached). */
+  listCatalogModels() {
+    return this.t.json("GET", "/api/v1/workspace/models/catalog");
+  }
+  /** POST /api/v1/workspace/models/verify — check an OpenRouter key with a 1-token completion. */
+  verifyOpenRouterKey(key, model, baseUrl) {
+    return this.t.json("POST", "/api/v1/workspace/models/verify", { body: { key, model, baseUrl } });
+  }
+  /** GET /api/v1/workspace/keys — API keys with rotation metadata (rotatesAt, daysLeft). */
+  listKeys() {
+    return this.t.json("GET", "/api/v1/workspace/keys");
+  }
 };
 var AgentsApi = class {
   constructor(t) {
@@ -490,6 +565,62 @@ var ImagesApi = class {
     return this.t.json("POST", `/api/v1/agents/${encodeURIComponent(agentId)}/images`, { body: input });
   }
 };
+var VideosApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/videos/models — list tiered video models + engine availability. */
+  listModels() {
+    return this.t.json("GET", "/api/v1/videos/models");
+  }
+  /** POST /api/v1/agents/:agentId/videos — start a video job (returns the queued task, HTTP 202). */
+  generate(agentId, input) {
+    return this.t.json("POST", `/api/v1/agents/${encodeURIComponent(agentId)}/videos`, { body: input });
+  }
+  /** GET /api/v1/video-tasks/:taskId — fetch the current job snapshot. */
+  getTask(taskId, signal) {
+    return this.t.json("GET", `/api/v1/video-tasks/${encodeURIComponent(taskId)}`, { signal });
+  }
+  /** DELETE /api/v1/video-tasks/:taskId — cancel a queued/rendering job (409 if already terminal). */
+  cancelTask(taskId) {
+    return this.t.json("DELETE", `/api/v1/video-tasks/${encodeURIComponent(taskId)}`);
+  }
+  /** Get a handle for polling / waiting on a video job (poll(), wait()). */
+  handle(taskId) {
+    return new VideoTaskHandle(this.t, taskId);
+  }
+};
+var AudioApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/audio/voices — list available TTS voices. */
+  voices() {
+    return this.t.json("GET", "/api/v1/audio/voices");
+  }
+  /** POST /api/v1/agents/:agentId/tts — synthesize speech (synchronous). */
+  textToSpeech(agentId, input) {
+    return this.t.json("POST", `/api/v1/agents/${encodeURIComponent(agentId)}/tts`, { body: input });
+  }
+};
+var FilesApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** POST /api/v1/files — upload a media file (multipart field "file"). */
+  async upload(file, opts = {}) {
+    const form = new FormData();
+    if (opts.filename !== void 0) {
+      form.append("file", file, opts.filename);
+    } else {
+      form.append("file", file);
+    }
+    opts.onProgress?.(0);
+    const result = await this.t.form("/api/v1/files", { form });
+    opts.onProgress?.(100);
+    return result;
+  }
+};
 function readEnvBaseUrl() {
   try {
     if (typeof process !== "undefined" && process?.env) {
@@ -512,6 +643,9 @@ var QLClient = class {
     this.workflows = new WorkflowsApi(this.transport);
     this.tasks = new TasksApi(this.transport);
     this.images = new ImagesApi(this.transport);
+    this.videos = new VideosApi(this.transport);
+    this.audio = new AudioApi(this.transport);
+    this.files = new FilesApi(this.transport);
   }
   /** The normalized base URL in use (not secret). */
   get baseUrl() {