@meistrari/tela-sdk-js 2.0.0 → 2.1.0

package/dist/index.mjs

@@ -1,8 +1,10 @@
 import * as changeCase from 'change-case';
 import { minimatch } from 'minimatch';
-import z, { z as z$1, ZodError, string, number, boolean, object, array, any, unknown } from 'zod';
+import * as z from 'zod';
+import z__default, { z as z$1, ZodError } from 'zod';
+import Emittery from 'emittery';
 
-const version = "2.0.0";
+const version = "2.1.0";
 
 var __defProp$7 = Object.defineProperty;
 var __defNormalProp$7 = (obj, key, value) => key in obj ? __defProp$7(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -1023,17 +1025,9 @@ var __publicField$4 = (obj, key, value) => {
   return value;
 };
 function TelaFileSchema() {
-  return z.custom((value) => value instanceof TelaFile, { message: "Value must be an instance of TelaFile" }).meta({ isTelaFile: true });
+  return z__default.custom((value) => value instanceof TelaFile, { message: "Value must be an instance of TelaFile" }).meta({ isTelaFile: true });
 }
 class TelaFile {
-  /**
-   * Creates an instance of `TelaFile`.
-   *
-   * @param file - The source of the file. Can be a URL string, Uint8Array, ReadableStream, ReadStream, Blob, or File.
-   * @param options - Optional configuration options such as byte range.
-   * @throws {InvalidFileURL} If the provided URL is not valid.
-   * @throws {EmptyFileError} If the provided file is empty.
-   */
   constructor(file, options = {}) {
     __publicField$4(this, "_file");
     __publicField$4(this, "_options");
@@ -1411,7 +1405,7 @@ class Poller {
     const resultPromise = async () => {
       try {
         while (!this._abortSignal.aborted) {
-          const result = await Promise.try(callback, this._abortSignal);
+          const result = await callback(this._abortSignal);
           if (result.done) {
             return result.value;
           }
@@ -1473,7 +1467,11 @@ function isTelaFile(obj) {
 function isTelaFileArray(obj) {
   return Array.isArray(obj) && obj.length > 0 && obj.every(isTelaFile);
 }
-class CanvasExecution {
+function isUUID(str) {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(str);
+}
+class CanvasExecution extends Emittery {
   /**
    * Creates a new canvas execution instance.
    *
@@ -1483,16 +1481,18 @@ class CanvasExecution {
    * @param client - HTTP client instance for making API requests.
    */
   constructor(variables, params = { async: false }, outputSchema, client) {
+    super();
     __publicField$2(this, "_id");
+    __publicField$2(this, "_status");
     __publicField$2(this, "_variables");
     __publicField$2(this, "_params");
     __publicField$2(this, "_client");
     __publicField$2(this, "_outputSchema");
     __publicField$2(this, "_skipResultValidation");
     __publicField$2(this, "_abortController");
-    __publicField$2(this, "_startPropmise");
     __publicField$2(this, "_resultPromise");
     __publicField$2(this, "_stream");
+    __publicField$2(this, "_rawResultValue");
     this._variables = variables;
     this._params = params;
     this._outputSchema = outputSchema;
@@ -1500,18 +1500,138 @@ class CanvasExecution {
     this._client = client;
     this._abortController = new AbortController();
   }
+  /**
+   * Fetches an existing asynchronous execution by its ID.
+   *
+   * This method retrieves the current state of an async execution and creates a new
+   * CanvasExecution instance with the fetched data. Only async executions can be
+   * fetched, as they are the only ones with persistent UUIDs on the server.
+   *
+   * @param id - The UUID of the async execution to fetch.
+   * @param outputSchema - Zod schema or object schema for validating/parsing output.
+   * @param client - HTTP client instance for making API requests.
+   * @param options - Optional configuration for polling behavior.
+   * @param options.pollingInterval - Time in milliseconds between polling attempts (default: 1000).
+   * @param options.pollingTimeout - Maximum time in milliseconds to wait for completion (default: 60000).
+   * @throws {InvalidExecutionModeError} If the provided ID is not a valid UUID.
+   * @returns A promise resolving to a CanvasExecution instance with the fetched state.
+   *
+   * @example
+   * ```typescript
+   * const execution = await CanvasExecution.fetch(
+   *   'execution-uuid',
+   *   z.object({ result: z.string() }),
+   *   client,
+   *   { pollingInterval: 2000, pollingTimeout: 120000 }
+   * )
+   * console.log(execution.status) // 'running' or 'succeeded' or 'failed'
+   * ```
+   */
+  static async fetch(id, outputSchema, client, options) {
+    if (!isUUID(id)) {
+      throw new InvalidExecutionModeError(
+        "Only async executions can be fetched by ID. The provided ID is not a valid UUID."
+      );
+    }
+    const response = await client.get(
+      `/v2/chat/completions/${id}`
+    );
+    const params = {
+      async: true,
+      pollingInterval: options?.pollingInterval,
+      pollingTimeout: options?.pollingTimeout
+    };
+    const execution = new CanvasExecution(
+      {},
+      // No variables needed for fetched execution
+      params,
+      outputSchema,
+      client
+    );
+    execution._id = response.id;
+    execution.status = response.status;
+    if (response.status === "succeeded") {
+      execution._rawResultValue = response;
+      const content = response.outputContent.content;
+      try {
+        const validatedContent = execution._skipResultValidation || !(outputSchema instanceof z__default.ZodType) ? content : outputSchema.parse(content);
+        execution._resultPromise = Promise.resolve(validatedContent);
+      } catch (error) {
+        execution._resultPromise = Promise.reject(error);
+        execution._resultPromise.catch(() => {
+        });
+      }
+    } else if (response.status === "failed") {
+      execution._rawResultValue = response;
+      const error = new ExecutionFailedError(response.rawOutput);
+      execution._resultPromise = Promise.reject(error);
+      execution._resultPromise.catch(() => {
+      });
+    }
+    return execution;
+  }
   /**
    * Gets the unique execution ID assigned by the server.
    *
-   * @throws {Error} If the execution has not been started yet.
+   * Note: Streaming executions do not have an ID as they don't create a tracked execution on the server.
+   *
+   * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+   * @throws {InvalidExecutionModeError} If called on a streaming execution (streams don't have IDs).
    * @returns The execution ID.
    */
   get id() {
+    if (this.isStream) {
+      throw new InvalidExecutionModeError("Streaming executions do not have an execution ID");
+    }
     if (!this._id) {
       throw new ExecutionNotStartedError();
     }
     return this._id;
   }
+  /**
+   * Gets the latest known status of the execution.
+   *
+   * Status values and transitions:
+   * - **Sync**: `succeeded` (after validation) or `failed` (on any error)
+   * - **Async**: `created` → `running` → `succeeded` or `failed`
+   * - **Stream**: `streaming` (once started)
+   *
+   * **Important:** Status is set to `succeeded` only after successful validation.
+   * If validation fails, status will be `failed` even if the API request succeeded.
+   *
+   * Use the `statusChange` event to track status transitions in real-time.
+   *
+   * @throws {ExecutionNotStartedError} If the execution has not been started yet.
+   * @returns The current status of the execution.
+   *
+   * @example
+   * ```typescript
+   * const execution = await canvas.execute({ query: 'test' }, { async: true })
+   * console.log(execution.status) // 'created'
+   *
+   * await execution.result
+   * console.log(execution.status) // 'succeeded' or 'failed'
+   * ```
+   */
+  get status() {
+    if (!this._status) {
+      throw new ExecutionNotStartedError();
+    }
+    return this._status;
+  }
+  /**
+   * Sets the status of the execution.
+   *
+   * @param status - The new status of the execution.
+   * @private
+   */
+  set status(status) {
+    const changed = this._status !== status;
+    this._status = status;
+    if (changed) {
+      this.emit("statusChange", status);
+    }
+  }
   /**
    * Gets the input variables provided to this execution.
    *
@@ -1552,6 +1672,31 @@ class CanvasExecution {
   get isStream() {
     return Boolean(this._params.stream);
   }
+  /**
+   * Gets the raw API response without any processing or validation.
+   * Automatically starts execution and waits for completion (including polling for async executions).
+   *
+   * For sync executions, returns the complete API response.
+   * For async executions, returns the polling response with status and output.
+   *
+   * @throws {InvalidExecutionModeError} If called on a streaming execution.
+   * @returns A promise resolving to the raw API result.
+   */
+  get rawResult() {
+    if (this.isStream) {
+      throw new InvalidExecutionModeError("rawResult is not available for streaming executions");
+    }
+    if (this.isSync) {
+      if (!this._resultPromise) {
+        throw new ExecutionNotStartedError();
+      }
+      return this._resultPromise.then(() => this._rawResultValue);
+    }
+    if (!this._resultPromise) {
+      this._resultPromise = this.startPolling();
+    }
+    return this._resultPromise.then(() => this._rawResultValue);
+  }
   /**
    * Type guard to check if params indicate async execution.
    *
@@ -1610,25 +1755,95 @@ class CanvasExecution {
   cancel() {
     this._abortController.abort();
   }
+  /**
+   * Starts polling for the execution result without waiting for the promise to resolve.
+   * This allows users to track execution progress via events rather than awaiting a promise.
+   *
+   * The following events will be emitted during polling:
+   * - `statusChange`: Emitted when the execution status changes (e.g., 'created' → 'running' → 'succeeded')
+   * - `poll`: Emitted on each polling attempt with the server response
+   * - `success`: Emitted when the execution completes successfully with the final result
+   * - `error`: Emitted if the execution fails
+   *
+   * **Important:** Events are only emitted while polling is active. You must either call `poll()` or
+   * await `execution.result` to start polling. Simply setting up event listeners without starting
+   * polling will not trigger any events.
+   *
+   * **Note:** If the execution has already completed (succeeded or failed) when fetched, the `success`
+   * and `error` events will not fire since no polling is needed. Check the `status` property and
+   * access the `result` directly for already-completed executions.
+   *
+   * @throws {InvalidExecutionModeError} If called on a non-async execution (sync or stream).
+   * @throws {ExecutionNotStartedError} If the execution has not been started yet (no ID assigned).
+   *
+   * @example
+   * ```typescript
+   * const execution = await canvas.getExecution('execution-id')
+   *
+   * // Check if already completed
+   * if (execution.status === 'succeeded' || execution.status === 'failed') {
+   *   // Access result directly - events won't fire
+   *   const result = await execution.result
+   *   console.log('Already completed:', result)
+   * } else {
+   *   // Still running - set up events and start polling
+   *   execution.on('statusChange', (status) => {
+   *     console.log('Status:', status)
+   *   })
+   *
+   *   execution.on('success', (result) => {
+   *     console.log('Completed:', result)
+   *   })
+   *
+   *   execution.on('error', (error) => {
+   *     console.error('Failed:', error)
+   *   })
+   *
+   *   // Start polling without waiting
+   *   execution.poll()
+   * }
+   * ```
+   */
+  poll() {
+    if (!this.isAsync) {
+      throw new InvalidExecutionModeError("Polling is only supported for async executions");
+    }
+    if (!this._id) {
+      throw new ExecutionNotStartedError();
+    }
+    if (this._resultPromise) {
+      return;
+    }
+    this._resultPromise = this.startPolling();
+    this._resultPromise.catch(() => {
+    });
+  }
   /**
    * Builds the base request body shared across all execution types.
-   * Includes messages, overrides, and structured output configuration.
+   * Includes messages, overrides, tags, label, and structured output configuration.
    *
    * @returns The base request body object.
    */
   get baseBody() {
+    if (this._params.label && !this._params.applicationId) {
+      console.warn(
+        '[Tela SDK - WARNING] The "label" field is only applicable when using applicationId. It will be ignored since no applicationId is provided.'
+      );
+    }
     const body = {
       canvasId: this._params.canvasId,
       applicationId: this._params.applicationId,
       versionId: this._params.versionId,
-      messages: this._params.messages
+      messages: this._params.messages,
+      tags: this._params.tags,
+      label: this._params.label
     };
-    if (this._params.override && this._outputSchema instanceof z.ZodType) {
+    if (this._params.override && this._outputSchema instanceof z__default.ZodType) {
       return {
         ...body,
         override: {
           ...this._params.override,
-          structured_output: z.toJSONSchema(this._outputSchema)
+          structured_output: z__default.toJSONSchema(this._outputSchema)
         }
       };
     }
@@ -1675,12 +1890,20 @@ class CanvasExecution {
       signal: this._abortController.signal
     }).then((response) => {
       this._id = response.id;
+      this._rawResultValue = response;
       return response.choices?.[0]?.message?.content;
     }).then((content) => {
-      if (this._skipResultValidation || !(this._outputSchema instanceof z.ZodType)) {
-        return content;
+      const validatedContent = this._skipResultValidation || !(this._outputSchema instanceof z__default.ZodType) ? content : this._outputSchema.parse(content);
+      this.status = "succeeded";
+      this.emit("success", validatedContent);
+      return validatedContent;
+    }).catch((error) => {
+      this.status = "failed";
+      if (this.listenerCount("error") > 0) {
+        this.emit("error", error);
+        return;
       }
-      return this._outputSchema.parse(content);
+      throw error;
     });
     return this._resultPromise;
   }
@@ -1704,6 +1927,13 @@ class CanvasExecution {
       signal: this._abortController.signal
     }).then((response) => {
       this._id = response.id;
+      this.status = response.status;
+      this.emit("poll", {
+        id: response.id,
+        status: response.status,
+        outputContent: response.output_content,
+        rawOutput: response.raw_output
+      });
       return response;
     });
   }
@@ -1724,6 +1954,7 @@ class CanvasExecution {
       stream: true,
       signal: this._abortController.signal
     });
+    this.status = "streaming";
     return this._stream;
   }
   /**
@@ -1752,8 +1983,12 @@ class CanvasExecution {
           signal
         }
       );
+      this.status = response.status;
+      this.emit("poll", response);
       if (response.status === "failed") {
-        throw new ExecutionFailedError(response.rawOutput);
+        const error = new ExecutionFailedError(response.rawOutput);
+        this.emit("error", error);
+        throw error;
       }
       if (response.status !== "succeeded") {
         return {
@@ -1761,15 +1996,28 @@ class CanvasExecution {
           value: void 0
         };
       }
+      this._rawResultValue = response;
+      this.emit("success", response.outputContent.content);
       return {
         done: response.status === "succeeded",
         value: response.outputContent.content
       };
     }).then((value) => {
-      if (this._skipResultValidation || !(this._outputSchema instanceof z.ZodType)) {
+      if (this._skipResultValidation || !(this._outputSchema instanceof z__default.ZodType)) {
         return value;
       }
       return this._outputSchema.parse(value);
+    }).catch((error) => {
+      if (this._status !== "failed") {
+        this.status = "failed";
+      }
+      if (this.listenerCount("error") > 0) {
+        if (!(error instanceof ExecutionFailedError)) {
+          this.emit("error", error);
+        }
+        return;
+      }
+      throw error;
     });
   }
   /**
@@ -1862,14 +2110,8 @@ var __publicField$1 = (obj, key, value) => {
   return value;
 };
 const zod = {
-  string,
-  number,
-  boolean,
-  object,
-  array,
-  file: TelaFileSchema,
-  any,
-  unknown
+  ...z,
+  file: TelaFileSchema
 };
 function fetchById(id, client) {
   return client.get(`/prompt/${id}/promoted-version`);
@@ -2083,6 +2325,43 @@ class Canvas {
       }
     };
   }
+  /**
+   * Fetches an existing async execution by its ID.
+   *
+   * This method retrieves the current state of an async execution that was previously
+   * started on this canvas. Only async executions can be fetched, as they are the only
+   * ones with persistent UUIDs on the server.
+   *
+   * @param id - The UUID of the async execution to fetch.
+   * @param options - Optional configuration for polling behavior.
+   * @param options.pollingInterval - Time in milliseconds between polling attempts (default: 1000).
+   * @param options.pollingTimeout - Maximum time in milliseconds to wait for completion (default: 60000).
+   * @throws {InvalidExecutionModeError} If the provided ID is not a valid UUID.
+   * @returns A promise resolving to a CanvasExecution instance with the fetched state.
+   *
+   * @example
+   * ```typescript
+   * // Start an async execution
+   * const execution = await canvas.execute({ query: 'test' }, { async: true })
+   * const executionId = execution.id
+   *
+   * // Later, fetch the execution by ID
+   * const fetched = await canvas.getExecution(executionId)
+   * console.log(fetched.status) // 'running', 'succeeded', or 'failed'
+   *
+   * // Use poll() for event-driven progress tracking
+   * fetched.on('statusChange', (status) => console.log('Status:', status))
+   * fetched.poll()
+   * ```
+   */
+  async getExecution(id, options) {
+    return CanvasExecution.fetch(
+      id,
+      this._output,
+      this._client,
+      options
+    );
+  }
 }
 
 var __defProp = Object.defineProperty;
@@ -2110,20 +2389,22 @@ const _TelaSDK = class _TelaSDK extends BaseClient {
     __publicField(this, "createFile", TelaFile.create.bind(this));
     /**
      * Retrieves a canvas by its ID, version ID, or application ID.
-     * Validates input and output schemas if Zod schemas are provided.
+     * Validates input and output schemas if provided via schema builder functions.
      *
      * @param options - Options for retrieving the canvas.
      * @returns A promise resolving to a Canvas instance.
      *
      * @example
      * ```typescript
-     * import { z } from 'zod';
-     *
      * // Get canvas by ID with schemas
      * const canvas = await tela.canvas.get({
      *   id: 'canvas-id',
-     *   input: z.object({ query: z.string() }),
-     *   output: z.object({ response: z.string() })
+     *   input: schema => schema.object({
+     *     query: schema.string()
+     *   }),
+     *   output: schema => schema.object({
+     *     response: schema.string()
+     *   })
      * });
      *
      * // Get canvas by application ID

package/package.json

@@ -1,14 +1,38 @@
 {
   "name": "@meistrari/tela-sdk-js",
-  "version": "2.0.0",
-  "type": "module",
+  "version": "2.1.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/meistrari/tela-sdk-js.git"
   },
-  "types": "dist/index.d.ts",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
+  "dependencies": {
+    "change-case": "5.4.4",
+    "emittery": "^1.2.0",
+    "minimatch": "10.0.1",
+    "zod": "4.1.12"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "3.0.0",
+    "@types/bun": "1.2.23",
+    "@types/node": "22.5.5",
+    "@typhonjs-typedoc/typedoc-theme-dmt": "0.4.0",
+    "@vitest/browser": "3.0.8",
+    "husky": "9.1.6",
+    "lint-staged": "15.2.10",
+    "playwright": "1.51.0",
+    "typedoc": "0.28.14",
+    "typedoc-plugin-merge-modules": "7.0.0",
+    "typedoc-unhoax-theme": "0.5.3",
+    "typescript": "5.6.3",
+    "unbuild": "2.0.0",
+    "unenv": "2.0.0-rc.14",
+    "vitest": "3.0.8"
+  },
+  "peerDependencies": {
+    "typescript": "5.6.3"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -16,11 +40,16 @@
       "require": "./dist/index.cjs"
     }
   },
+  "engines": {
+    "node": "^20.15.1"
+  },
   "files": [
     "dist"
   ],
-  "engines": {
-    "node": "^20.15.1"
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix"
+    ]
   },
   "scripts": {
     "prepublishOnly": "bun run build",
@@ -39,34 +68,6 @@
     "docs": "typedoc",
     "docs:serve": "bunx http-server docs"
   },
-  "dependencies": {
-    "@meistrari/vault-http-client": "2.3.6",
-    "change-case": "5.4.4",
-    "minimatch": "10.0.1",
-    "zod": "4.1.12"
-  },
-  "devDependencies": {
-    "@antfu/eslint-config": "3.0.0",
-    "@types/bun": "1.2.23",
-    "@types/node": "22.5.5",
-    "@typhonjs-typedoc/typedoc-theme-dmt": "0.4.0",
-    "@vitest/browser": "3.0.8",
-    "husky": "9.1.6",
-    "lint-staged": "15.2.10",
-    "playwright": "1.51.0",
-    "typedoc": "0.28.14",
-    "typedoc-plugin-merge-modules": "7.0.0",
-    "typedoc-unhoax-theme": "0.5.3",
-    "unbuild": "2.0.0",
-    "unenv": "2.0.0-rc.14",
-    "vitest": "3.0.8"
-  },
-  "peerDependencies": {
-    "typescript": "5.8.2"
-  },
-  "lint-staged": {
-    "*.{js,ts}": [
-      "eslint --fix"
-    ]
-  }
+  "type": "module",
+  "types": "dist/index.d.ts"
 }