@meistrari/tela-sdk-js 2.9.4 → 2.11.0

package/README.md

@@ -17,6 +17,8 @@ The Tela SDK for JavaScript provides a simple and powerful way to interact with
     - [Webhook Notifications](#webhook-notifications)
     - [Execution Tags](#execution-tags)
   - [File Handling](#file-handling)
+  - [Tasks API](#tasks-api)
+  - [Vault API](#vault-api)
 - [Migration Guide from v1.x to v2](#migration-guide-from-v1x-to-v2)
   - [Breaking Changes](#breaking-changes)
   - [Migration Checklist](#migration-checklist)
@@ -608,6 +610,111 @@ const fileWithRange = TelaFile.create(
 )
 ```
 
+### Tasks API
+
+The Tasks API exposes the persistent task records that workstation (application) canvases create. Use it to fetch, list, update, approve, edit, re-run, or delete tasks without dropping down to raw HTTP.
+
+```typescript
+import { TelaSDK, extractTaskOutput, normalizeTaskStatus } from '@meistrari/tela-sdk-js'
+
+const tela = new TelaSDK({ apiKey: 'your-api-key' })
+
+// Fetch a task by id
+const task = await tela.tasks.get('task-id')
+
+// Read the parsed output (handles canvas vs workflow shape automatically)
+const output = await tela.tasks.getOutput<MyOutput>('task-id')
+// or, if you already have the task in hand:
+const sameOutput = extractTaskOutput<MyOutput>(task)
+
+// List input files attached to the task (e.g. uploaded PDFs)
+const files = await tela.tasks.getInputFiles('task-id')
+
+// List tasks with filters
+const { data, meta } = await tela.tasks.list({
+    promptApplicationId: 'app-id',
+    status: ['validating', 'completed'],
+    tags: 'product:my-app',
+    createdAtSince: new Date('2024-01-01'),
+    excludeInputOutputColumns: true, // omit raw input/input content/original output
+    orderBy: ['createdAt'],
+    order: 'desc',
+    limit: 50,
+})
+
+// Lean list rows still include outputContent and flattened inputFiles.
+// Fetch a single task when you need raw input or original output payloads.
+const fullTask = await tela.tasks.get(data[0].id)
+
+// Mutations
+await tela.tasks.rename('task-id', 'New name')
+await tela.tasks.approve('task-id') // sets status: 'completed'
+await tela.tasks.setTags('task-id', ['reviewed', 'q2'])
+
+// ─── Updating output content ────────────────────────────────────
+// The server uses *deep-merge* semantics on outputContent.content.
+// Keys you do not provide are left untouched. There is no way to
+// delete a field through this API. Three methods cover different
+// use-cases:
+
+// 1. Top-level partial patch (single PATCH, no fetch)
+await tela.tasks.patchOutputContent('task-id', { reviewedBy: 'me' })
+
+// 2. Single-field shortcut for nested *object* paths
+//    Do NOT use this for array indices — use updateOutputContent below.
+await tela.tasks.patchOutputField('task-id', 'profile.email', 'b@x.com')
+
+// 3. Read-modify-write — safe for arrays, multiple edits, and any
+//    change that needs the previous value. SDK fetches current,
+//    runs your updater, then sends the full content via patchOutputContent.
+await tela.tasks.updateOutputContent<MenuOutput>('task-id', (current) => {
+    current.menu.items[2].price = 9.99 // mutate in place
+    current.menu.items.push({ name: 'New', price: 5 }) // grow arrays
+})
+// Updaters can also return a new value:
+await tela.tasks.updateOutputContent('task-id', current => ({ ...current, reviewed: true }))
+
+// Re-run a task (only allowed when status === 'failed')
+const rerun = await tela.tasks.rerun('task-id')
+console.log(rerun.executionRunId)
+
+// Delete
+await tela.tasks.delete('task-id') // → { success: true }
+await tela.tasks.deleteBulk(['id1', 'id2']) // → { deleted: 2, deletedIds: [...] }
+await tela.tasks.undoApprovalBulk(['id1', 'id2']) // → { undoApproval: 2, undoApprovalIds: [...] }
+
+// Map server statuses to coarse client-friendly buckets
+const uiStatus = normalizeTaskStatus(task.status)
+// 'created' | 'running'   → 'running'
+// 'validating'            → 'pending'
+// 'completed'             → 'succeeded'
+// 'failed' | 'cancelled'  → 'failed'
+```
+
+The full `Task`, `TaskListItem`, `TaskInputFile`, `TaskListQuery`, `TaskUpdatePayload`, and `TaskStatus` types are exported from the package root, so you don't need to type any task-related responses by hand.
+
+### Vault API
+
+The Vault API resolves and downloads files stored in the Tela vault. It accepts both `vault://<id>` references and bare ids, and passes through plain `https://` URLs unchanged.
+
+```typescript
+const tela = new TelaSDK({ apiKey: 'your-api-key' })
+
+// Get a temporary signed URL
+const signedUrl = await tela.vault.getSignedUrl('vault://abc-123')
+
+// Resolve any reference (vault:// or https://) to a downloadable URL
+const downloadUrl = await tela.vault.resolve(file.url)
+
+// Download as a Blob
+const blob = await tela.vault.download('vault://abc-123')
+
+// Stream the file
+const stream = await tela.vault.stream('vault://abc-123')
+```
+
+This is particularly useful when reading task input files: `tela.tasks.getInputFiles(id)` returns the file references, and `tela.vault.download(file.url)` downloads them in one call.
+
 ## Migration Guide from v1.x to v2
 
 Version 2.0 of the Tela SDK introduces significant improvements to type safety, schema validation, and API design. This guide will help you migrate your code from v1.x to v2.
@@ -1097,5 +1204,6 @@ When you execute a canvas using `applicationId`, it creates a task in the applic
 
 If you encounter issues during migration, please:
 - Check the [examples](./examples/) directory for updated usage patterns
-- Review the [API documentation](./docs/)
+- Review the [API documentation](https://sdk-js.tela.tools/)
+- Generate the API reference locally with `bun run docs` when checking changes
 - Open an issue at [GitHub Issues](https://github.com/meistrari/tela-sdk-js/issues)

package/dist/index.cjs

@@ -23,7 +23,7 @@ const changeCase__namespace = /*#__PURE__*/_interopNamespaceCompat(changeCase);
 const z__default = /*#__PURE__*/_interopDefaultCompat(z);
 const Emittery__default = /*#__PURE__*/_interopDefaultCompat(Emittery);
 
-const version = "2.9.4";
+const version = "2.11.0";
 
 var __defProp$a = Object.defineProperty;
 var __defNormalProp$a = (obj, key, value) => key in obj ? __defProp$a(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -1761,7 +1761,11 @@ async function uploadFiles(files, client) {
 async function downloadFile(vaultReference, client) {
   const vaultId = vaultReference.replace("vault://", "");
   const response = await client.get(`/_services/vault/files/${vaultId}`);
-  return fetch(response.url).then((res) => res.blob());
+  const res = await fetch(response.url);
+  if (!res.ok) {
+    throw new Error(`Failed to download file: ${res.status} ${res.statusText}`);
+  }
+  return res.blob();
 }
 async function streamFile(vaultReference, client) {
   const vaultId = vaultReference.replace("vault://", "");
@@ -3933,6 +3937,7 @@ const TaskListFilters = z__default.looseObject({
 const TaskListOptions = z__default.looseObject({
   limit: z__default.number().optional(),
   offset: z__default.number().optional(),
+  excludeInputOutputColumns: z__default.boolean().optional(),
   order: z__default.object({
     by: z__default.enum(["createdAt", "updatedAt", "approvedAt", "status", "reference", "name"]),
     direction: z__default.enum(["asc", "desc"])
@@ -4235,6 +4240,7 @@ class Workstation {
   async *iterateTasks({ filters, options }) {
     let rawQuery;
     let hasMore = true;
+    const validatedOptions = TaskListOptions.optional().parse(options);
     while (hasMore) {
       const { tasks, meta } = await this.listTasks({
         filters,
@@ -4247,7 +4253,8 @@ class Workstation {
       if (meta.links.next !== null) {
         rawQuery = {
           ...meta.links.next,
-          objectLinks: true
+          objectLinks: true,
+          ...validatedOptions?.excludeInputOutputColumns !== void 0 ? { excludeInputOutputColumns: validatedOptions.excludeInputOutputColumns } : {}
         };
       } else {
         hasMore = false;
@@ -4256,6 +4263,393 @@ class Workstation {
   }
 }
 
+function extractTaskOutput(task) {
+  const oc = task.outputContent;
+  if (!oc)
+    return null;
+  if (oc.output && typeof oc.output === "object" && "output" in oc.output) {
+    return oc.output.output ?? null;
+  }
+  if ("content" in oc && oc.content !== void 0) {
+    return oc.content ?? null;
+  }
+  return null;
+}
+function normalizeTaskStatus(status) {
+  switch (status) {
+    case "created":
+    case "running":
+      return "running";
+    case "validating":
+      return "pending";
+    case "completed":
+      return "succeeded";
+    case "failed":
+    case "cancelled":
+      return "failed";
+  }
+}
+
+const NO_TRANSFORM = { transformCase: false };
+class Tasks {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Fetches a task by id.
+   *
+   * @param id - The task id.
+   * @param options - Optional flags.
+   * @param options.includeAnalytics - Include analytics data on the task.
+   */
+  async get(id, options) {
+    return this.client.get(`/task/${id}`, {
+      query: options?.includeAnalytics ? { includeAnalytics: "true" } : void 0,
+      ...NO_TRANSFORM
+    });
+  }
+  async list(query = {}) {
+    const serialized = serializeTaskListQuery(query);
+    return this.client.get("/task", {
+      query: serialized,
+      // The list endpoint expects pre-serialized array fields (JSON strings),
+      // so disable automatic case transformation of the query payload.
+      transformCase: false
+    });
+  }
+  /**
+   * Updates one or more fields of a task.
+   *
+   * Only `name`, `status`, `tags`, and `outputContent` may be updated.
+   */
+  async update(id, payload) {
+    return this.client.patch(`/task/${id}`, {
+      body: payload,
+      ...NO_TRANSFORM
+    });
+  }
+  /**
+   * Renames a task. Convenience wrapper around {@link update}.
+   */
+  async rename(id, name) {
+    return this.update(id, { name });
+  }
+  /**
+   * Approves a task by setting its status to `completed`.
+   * Convenience wrapper around {@link update}.
+   */
+  async approve(id) {
+    return this.update(id, { status: "completed" });
+  }
+  /**
+   * Patches a task's output content with a **deep merge** against the existing
+   * content.
+   *
+   * ⚠️ **Merge semantics, not replace.** The server iterates the keys of the
+   * provided payload and overlays them onto the current `outputContent.content`:
+   *
+   * - Keys you provide overwrite the existing values at the same path.
+   * - Nested objects are merged recursively.
+   * - Arrays of objects are merged positionally by index.
+   * - **Keys you do not provide are left untouched** — there is no way to
+   *   delete a field through this API.
+   *
+   * If you only need to update a single (possibly nested) field, prefer
+   * {@link patchOutputField} which handles building the nested payload for you.
+   *
+   * @example Top-level patch
+   * ```typescript
+   * // Existing content: { name: 'foo', price: 10 }
+   * await tela.tasks.patchOutputContent(id, { price: 12 })
+   * // Result: { name: 'foo', price: 12 }
+   * ```
+   *
+   * @example Nested patch
+   * ```typescript
+   * // Existing content: { menu: { items: [{ name: 'A', price: 5 }] } }
+   * await tela.tasks.patchOutputContent(id, { menu: { items: [{ price: 6 }] } })
+   * // Result: { menu: { items: [{ name: 'A', price: 6 }] } }
+   * ```
+   */
+  async patchOutputContent(id, content) {
+    return this.update(id, { outputContent: { content } });
+  }
+  /**
+   * Patches a single field of a task's output content using a dot-notation path.
+   *
+   * Internally builds a nested object that mirrors the path and submits it via
+   * {@link patchOutputContent}, relying on the server's deep-merge to leave
+   * sibling fields untouched.
+   *
+   * Path syntax:
+   * - `foo.bar.baz` — nested object keys
+   * - `items.0.price` — numeric segments are treated as array indices
+   *
+   * ⚠️ **Use {@link updateOutputContent} for any change inside arrays.** The
+   * server's deep-merge replaces an entire array whenever the patched array's
+   * length differs from the current one. This method only sends a sparse
+   * single-element array (e.g. `[{ price: 7 }]`), so an array index path will
+   * truncate the rest of the items. It is safe for **object paths only**
+   * (e.g. `profile.email`).
+   *
+   * @example Nested object update — safe
+   * ```typescript
+   * // Existing: { profile: { name: 'A', email: 'a@x' } }
+   * await tela.tasks.patchOutputField(id, 'profile.email', 'b@x')
+   * // Result:   { profile: { name: 'A', email: 'b@x' } }
+   * ```
+   *
+   * @example Array element update — UNSAFE, prefer updateOutputContent
+   * ```typescript
+   * // ❌ Do NOT use patchOutputField for array indices:
+   * //    await tela.tasks.patchOutputField(id, 'items.0.price', 7)
+   * //    → server replaces items[] with the single-element sparse array.
+   *
+   * // ✅ Use updateOutputContent instead:
+   * await tela.tasks.updateOutputContent(id, (current) => {
+   *     current.items[0].price = 7
+   * })
+   * ```
+   */
+  async patchOutputField(id, path, value) {
+    if (path.length === 0) {
+      throw new Error("tasks.patchOutputField: path cannot be empty");
+    }
+    const payload = buildNestedPayload(path, value);
+    return this.patchOutputContent(id, payload);
+  }
+  /**
+   * Read-modify-write helper for safely updating any part of a task's output
+   * content — including array elements.
+   *
+   * Fetches the current output, hands you a deep clone via the `updater`
+   * callback (which can mutate it in place or return a new value), then
+   * submits the full updated content via {@link patchOutputContent}. Because
+   * the entire arrays are sent back, the server's "replace on length mismatch"
+   * array behavior never triggers — array element edits, additions, removals,
+   * and reorders all work correctly.
+   *
+   * Use this whenever:
+   * - You're modifying anything inside an array
+   * - You need the previous value to compute the new one
+   * - You're making multiple field changes in one logical operation
+   *
+   * For simple top-level patches without needing the current value, prefer
+   * {@link patchOutputContent}.
+   *
+   * @example Update one menu item's price
+   * ```typescript
+   * await tela.tasks.updateOutputContent<MenuOutput>(id, (current) => {
+   *     current.menu.items[2].price = 9.99
+   * })
+   * ```
+   *
+   * @example Add a new array item
+   * ```typescript
+   * await tela.tasks.updateOutputContent<TodoOutput>(id, (current) => {
+   *     current.todos.push({ text: 'new task', done: false })
+   * })
+   * ```
+   *
+   * @example Return a brand-new value
+   * ```typescript
+   * await tela.tasks.updateOutputContent(id, (current) => ({
+   *     ...current,
+   *     reviewed: true,
+   * }))
+   * ```
+   *
+   * @throws If the task has no output content yet (still running).
+   */
+  async updateOutputContent(id, updater) {
+    const task = await this.get(id);
+    const current = extractTaskOutput(task);
+    if (current === null || current === void 0) {
+      throw new Error(`tasks.updateOutputContent: task ${id} has no output content yet`);
+    }
+    const draft = structuredClone(current);
+    const result = updater(draft);
+    const next = result === void 0 ? draft : result;
+    return this.patchOutputContent(id, next);
+  }
+  /**
+   * Replaces a task's tags. Convenience wrapper around {@link update}.
+   */
+  async setTags(id, tags) {
+    return this.update(id, { tags });
+  }
+  /**
+   * Soft-deletes a task.
+   */
+  async delete(id) {
+    return this.client.delete(`/task/${id}`, NO_TRANSFORM);
+  }
+  /**
+   * Bulk soft-deletes multiple tasks.
+   *
+   * @throws If `ids` is empty.
+   */
+  async deleteBulk(ids) {
+    if (ids.length === 0) {
+      throw new Error("tasks.deleteBulk: ids array cannot be empty");
+    }
+    return this.client.delete("/task/bulk", {
+      body: ids,
+      ...NO_TRANSFORM
+    });
+  }
+  /**
+   * Reverts approval on multiple tasks (sets them back to `validating`).
+   * Only tasks currently in `completed` status are eligible.
+   *
+   * @throws If `ids` is empty.
+   */
+  async undoApprovalBulk(ids) {
+    if (ids.length === 0) {
+      throw new Error("tasks.undoApprovalBulk: ids array cannot be empty");
+    }
+    return this.client.post("/task/bulk/undo-approval", {
+      body: ids,
+      ...NO_TRANSFORM
+    });
+  }
+  /**
+   * Re-runs a task. Returns the new execution metadata.
+   *
+   * Note: the server only allows re-running tasks in `failed` status. Calling
+   * this on a task in any other state will result in a 400 response.
+   */
+  async rerun(id) {
+    return this.client.post(`/task/${id}/rerun`, NO_TRANSFORM);
+  }
+  /**
+   * Returns the input files attached to a task.
+   *
+   * Convenience helper around {@link get} that extracts and normalizes the
+   * `inputContent.files[]` array.
+   */
+  async getInputFiles(id) {
+    const task = await this.get(id);
+    return task.inputContent?.files ?? [];
+  }
+  /**
+   * Returns the parsed output of a task regardless of whether it came from a
+   * canvas execution or a workflow execution.
+   *
+   * Returns `null` if the task has no output yet.
+   */
+  async getOutput(id) {
+    const task = await this.get(id);
+    return extractTaskOutput(task);
+  }
+}
+function buildNestedPayload(path, value) {
+  const segments = path.split(".");
+  let current = value;
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const seg = segments[i];
+    if (/^\d+$/.test(seg)) {
+      const arr = [];
+      arr[Number(seg)] = current;
+      current = arr;
+    } else {
+      current = { [seg]: current };
+    }
+  }
+  return current;
+}
+function serializeTaskListQuery(query) {
+  const out = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0)
+      continue;
+    if (key === "ids" || key === "status" || key === "approvedBy" || key === "createdBy") {
+      out[key] = JSON.stringify(value);
+      continue;
+    }
+    if (key === "orderBy") {
+      out[key] = Array.isArray(value) ? JSON.stringify(value) : value;
+      continue;
+    }
+    if (value instanceof Date) {
+      out[key] = value.toISOString();
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+function toVaultId(ref) {
+  if (ref.startsWith("vault://"))
+    return ref.slice("vault://".length);
+  if (/^https?:\/\//i.test(ref))
+    return null;
+  return ref;
+}
+class Vault {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Returns a temporary signed URL for a vault file.
+   *
+   * @param ref - A `vault://<id>` reference or a bare vault id.
+   * @throws If `ref` is an `https://` URL (already resolved). Use {@link resolve} for that case.
+   */
+  async getSignedUrl(ref) {
+    const id = toVaultId(ref);
+    if (id === null) {
+      throw new Error(`vault.getSignedUrl: '${ref}' is already an http(s) URL; use vault.resolve() instead`);
+    }
+    const response = await this.client.get(`/_services/vault/files/${id}`);
+    return response.url;
+  }
+  /**
+   * Resolves any file reference to a downloadable URL.
+   *
+   * - `vault://<id>` and bare ids are resolved through the vault service.
+   * - `https://` / `http://` URLs are returned as-is.
+   */
+  async resolve(ref) {
+    if (toVaultId(ref) === null)
+      return ref;
+    return this.getSignedUrl(ref);
+  }
+  /**
+   * Downloads a vault file as a Blob.
+   *
+   * @param ref - A `vault://<id>` reference or a bare vault id.
+   */
+  async download(ref) {
+    const id = toVaultId(ref);
+    if (id === null) {
+      const res = await fetch(ref);
+      if (!res.ok) {
+        throw new Error(`vault.download: failed to fetch ${ref}: ${res.status} ${res.statusText}`);
+      }
+      return res.blob();
+    }
+    return downloadFile(`vault://${id}`, this.client);
+  }
+  /**
+   * Streams a vault file as a `ReadableStream`.
+   *
+   * @param ref - A `vault://<id>` reference or a bare vault id.
+   */
+  async stream(ref) {
+    const id = toVaultId(ref);
+    if (id === null) {
+      const res = await fetch(ref);
+      if (!res.ok || !res.body) {
+        throw new Error(`vault.stream: failed to fetch ${ref}: ${res.status} ${res.statusText}`);
+      }
+      return res.body;
+    }
+    return streamFile(`vault://${id}`, this.client);
+  }
+}
+
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => {
@@ -4318,6 +4712,30 @@ const _TelaSDK = class _TelaSDK extends BaseClient {
         });
       }
     });
+    /**
+     * Tasks API resource for managing workstation tasks (fetch, list, update,
+     * approve, rename, edit output, re-run, etc.).
+     *
+     * @example
+     * ```typescript
+     * const task = await tela.tasks.get('task-id')
+     * await tela.tasks.approve('task-id')
+     * await tela.tasks.rename('task-id', 'New name')
+     * const files = await tela.tasks.getInputFiles('task-id')
+     * ```
+     */
+    __publicField(this, "tasks", new Tasks(this));
+    /**
+     * Vault API resource for resolving, downloading, and streaming files
+     * stored in the Tela vault.
+     *
+     * @example
+     * ```typescript
+     * const url = await tela.vault.getSignedUrl('vault://abc-123')
+     * const blob = await tela.vault.download('vault://abc-123')
+     * ```
+     */
+    __publicField(this, "vault", new Vault(this));
     __publicField(this, "workstation", {
       get: async (options) => {
         return Workstation.get({
@@ -4437,13 +4855,17 @@ exports.MissingAuthError = MissingAuthError;
 exports.NotFoundError = NotFoundError;
 exports.RateLimitError = RateLimitError;
 exports.TaskFailedError = TaskFailedError;
+exports.Tasks = Tasks;
 exports.TelaError = TelaError;
 exports.TelaFile = TelaFile;
 exports.TelaFileSchema = TelaFileSchema;
 exports.TelaSDK = TelaSDK;
 exports.UnprocessableEntityError = UnprocessableEntityError;
 exports.UserAbortError = UserAbortError;
+exports.Vault = Vault;
 exports.createTelaClient = createTelaClient;
+exports.extractTaskOutput = extractTaskOutput;
 exports.isTelaFile = isTelaFile;
 exports.isTelaFileArray = isTelaFileArray;
+exports.normalizeTaskStatus = normalizeTaskStatus;
 exports.toError = toError;