@meistrari/tela-sdk-js 1.0.1 → 2.0.0

package/dist/index.cjs

@@ -1,7 +1,8 @@
 'use strict';
 
 const changeCase = require('change-case');
-const micromatch = require('micromatch');
+const minimatch = require('minimatch');
+const z = require('zod');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
 
@@ -18,14 +19,14 @@ function _interopNamespaceCompat(e) {
 }
 
 const changeCase__namespace = /*#__PURE__*/_interopNamespaceCompat(changeCase);
-const micromatch__default = /*#__PURE__*/_interopDefaultCompat(micromatch);
+const z__default = /*#__PURE__*/_interopDefaultCompat(z);
 
-const version = "1.0.1";
+const version = "2.0.0";
 
-var __defProp$5 = Object.defineProperty;
-var __defNormalProp$5 = (obj, key, value) => key in obj ? __defProp$5(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$5 = (obj, key, value) => {
-  __defNormalProp$5(obj, typeof key !== "symbol" ? key + "" : key, value);
+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;
+var __publicField$7 = (obj, key, value) => {
+  __defNormalProp$7(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
 class TelaError extends Error {
@@ -51,16 +52,35 @@ class InvalidFileURL extends TelaError {
   }
 }
 class FileUploadError extends TelaError {
+  constructor(message, statusCode) {
+    super(`Failed to upload file: ${message} (Status code: ${statusCode})`);
+    __publicField$7(this, "statusCode");
+    this.statusCode = statusCode;
+  }
+}
+class ExecutionNotStartedError extends TelaError {
+  constructor() {
+    super("Execution has not started yet");
+  }
+}
+class InvalidExecutionModeError extends TelaError {
   constructor(message) {
-    super(`Failed to upload file: ${message}`);
+    super(message);
+  }
+}
+class ExecutionFailedError extends TelaError {
+  constructor(rawOutput) {
+    super(`Execution failed: ${JSON.stringify(rawOutput)}`);
+    __publicField$7(this, "rawOutput");
+    this.rawOutput = rawOutput;
   }
 }
 class APIError extends TelaError {
   constructor(statusCode, error, _message) {
     const message = error?.message ? typeof error.message === "string" ? error.message : JSON.stringify(error.message) : error ? JSON.stringify(error) : _message;
     super(message);
-    __publicField$5(this, "statusCode");
-    __publicField$5(this, "error");
+    __publicField$7(this, "statusCode");
+    __publicField$7(this, "error");
     this.statusCode = statusCode;
     this.error = error;
   }
@@ -102,7 +122,7 @@ class APIError extends TelaError {
 class UserAbortError extends APIError {
   constructor({ message } = {}) {
     super(void 0, void 0, message || "User aborted.");
-    __publicField$5(this, "statusCode");
+    __publicField$7(this, "statusCode");
   }
 }
 class ConnectionError extends APIError {
@@ -111,7 +131,7 @@ class ConnectionError extends APIError {
     cause
   }) {
     super(void 0, void 0, message || "Connection error.");
-    __publicField$5(this, "statusCode");
+    __publicField$7(this, "statusCode");
     if (cause)
       this.cause = cause;
   }
@@ -121,57 +141,57 @@ class ConnectionTimeout extends APIError {
     message
   } = {}) {
     super(void 0, void 0, message || "Request timed out.");
-    __publicField$5(this, "statusCode");
+    __publicField$7(this, "statusCode");
   }
 }
 class BadRequestError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 400);
+    __publicField$7(this, "statusCode", 400);
   }
   // todo: handle validation errors from zod/typebox
 }
 class AuthenticationError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 401);
+    __publicField$7(this, "statusCode", 401);
   }
 }
 class AuthorizationError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 403);
+    __publicField$7(this, "statusCode", 403);
   }
 }
 class NotFoundError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 404);
+    __publicField$7(this, "statusCode", 404);
   }
 }
 class ConflictError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 409);
+    __publicField$7(this, "statusCode", 409);
   }
 }
 class UnprocessableEntityError extends APIError {
   constructor() {
     super(...arguments);
     // todo: check if tela returns 400 or 422 for zod errors
-    __publicField$5(this, "statusCode", 422);
+    __publicField$7(this, "statusCode", 422);
   }
 }
 class RateLimitError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 429);
+    __publicField$7(this, "statusCode", 429);
   }
 }
 class InternalServerError extends APIError {
   constructor() {
     super(...arguments);
-    __publicField$5(this, "statusCode", 500);
+    __publicField$7(this, "statusCode", 500);
   }
 }
 function toError(err) {
@@ -210,8 +230,12 @@ const DEFAULT_FIELDS_TRANSFORMATION_EXCLUSIONS = [
 
 function isExcluded(path, exclusions) {
   return exclusions.some((pattern) => {
-    const isMatch = micromatch__default.isMatch(path, pattern);
-    return isMatch;
+    return minimatch.minimatch(path, pattern, {
+      dot: true,
+      nobrace: false,
+      noglobstar: false,
+      matchBase: false
+    });
   });
 }
 function transformObjectFromCamelCaseToSnakeCase(obj, exclusions = []) {
@@ -279,10 +303,10 @@ function transformObjectFromSnakeCaseToCamelCase(obj, exclusions = []) {
   return result;
 }
 
-var __defProp$4 = Object.defineProperty;
-var __defNormalProp$4 = (obj, key, value) => key in obj ? __defProp$4(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$4 = (obj, key, value) => {
-  __defNormalProp$4(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$6 = Object.defineProperty;
+var __defNormalProp$6 = (obj, key, value) => key in obj ? __defProp$6(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$6 = (obj, key, value) => {
+  __defNormalProp$6(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
 class Stream {
@@ -297,7 +321,7 @@ class Stream {
     /**
      * The AbortController associated with this stream.
      */
-    __publicField$4(this, "controller");
+    __publicField$6(this, "controller");
     this.controller = controller;
   }
   /**
@@ -338,6 +362,10 @@ class Stream {
             if (data && data.error) {
               throw new APIError(void 0, data.error, void 0);
             }
+            data = data.message.content;
+            if (!data) {
+              continue;
+            }
             yield data;
           } else {
             let data;
@@ -351,6 +379,10 @@ class Stream {
             if (sse.event === "error") {
               throw new APIError(void 0, data.error, data.message);
             }
+            data = data.message.content;
+            if (!data) {
+              continue;
+            }
             yield { event: sse.event, data };
           }
         }
@@ -540,9 +572,9 @@ function findDoubleNewlineIndex(buffer) {
 }
 class SSEDecoder {
   constructor() {
-    __publicField$4(this, "data");
-    __publicField$4(this, "event");
-    __publicField$4(this, "chunks");
+    __publicField$6(this, "data");
+    __publicField$6(this, "event");
+    __publicField$6(this, "chunks");
     this.event = null;
     this.data = [];
     this.chunks = [];
@@ -583,9 +615,9 @@ class SSEDecoder {
 const _LineDecoder = class _LineDecoder {
   // TextDecoder found in browsers; not typed to avoid pulling in either "dom" or "node" types.
   constructor() {
-    __publicField$4(this, "buffer");
-    __publicField$4(this, "trailingCR");
-    __publicField$4(this, "textDecoder");
+    __publicField$6(this, "buffer");
+    __publicField$6(this, "trailingCR");
+    __publicField$6(this, "textDecoder");
     this.buffer = [];
     this.trailingCR = false;
   }
@@ -660,8 +692,8 @@ const _LineDecoder = class _LineDecoder {
   }
 };
 // prettier-ignore
-__publicField$4(_LineDecoder, "NEWLINE_CHARS", /* @__PURE__ */ new Set(["\n", "\r"]));
-__publicField$4(_LineDecoder, "NEWLINE_REGEXP", /\r\n|[\n\r]/g);
+__publicField$6(_LineDecoder, "NEWLINE_CHARS", /* @__PURE__ */ new Set(["\n", "\r"]));
+__publicField$6(_LineDecoder, "NEWLINE_REGEXP", /\r\n|[\n\r]/g);
 let LineDecoder = _LineDecoder;
 function partition(str, delimiter) {
   const index = str.indexOf(delimiter);
@@ -698,10 +730,10 @@ function readableStreamAsyncIterable(stream) {
   };
 }
 
-var __defProp$3 = Object.defineProperty;
-var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$3 = (obj, key, value) => {
-  __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$5 = Object.defineProperty;
+var __defNormalProp$5 = (obj, key, value) => key in obj ? __defProp$5(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$5 = (obj, key, value) => {
+  __defNormalProp$5(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
 async function defaultParseResponse(props) {
@@ -726,10 +758,10 @@ async function defaultParseResponse(props) {
 }
 class BaseClient {
   constructor({ baseURL, maxRetries = 5, timeout = 0 }) {
-    __publicField$3(this, "baseURL");
-    __publicField$3(this, "maxRetries");
-    __publicField$3(this, "timeout");
-    __publicField$3(this, "fetch");
+    __publicField$5(this, "baseURL");
+    __publicField$5(this, "maxRetries");
+    __publicField$5(this, "timeout");
+    __publicField$5(this, "fetch");
     this.baseURL = baseURL;
     this.maxRetries = validateMaxRetries(maxRetries);
     this.timeout = validateTimeout(timeout);
@@ -751,9 +783,6 @@ class BaseClient {
   getUserAgent() {
     return `tela-sdk-node/${version}`;
   }
-  getAuthHeaders() {
-    return {};
-  }
   get(path, opts) {
     return this.methodRequest("GET", path, opts);
   }
@@ -1006,12 +1035,15 @@ async function getStreamSize(stream) {
   return size;
 }
 
-var __defProp$2 = Object.defineProperty;
-var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$2 = (obj, key, value) => {
-  __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$4 = Object.defineProperty;
+var __defNormalProp$4 = (obj, key, value) => key in obj ? __defProp$4(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$4 = (obj, key, value) => {
+  __defNormalProp$4(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
+function TelaFileSchema() {
+  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`.
@@ -1021,14 +1053,31 @@ class TelaFile {
    * @throws {InvalidFileURL} If the provided URL is not valid.
    * @throws {EmptyFileError} If the provided file is empty.
    */
-  constructor(file, options) {
-    __publicField$2(this, "_file");
-    __publicField$2(this, "_options");
-    __publicField$2(this, "_size", null);
+  constructor(file, options = {}) {
+    __publicField$4(this, "_file");
+    __publicField$4(this, "_options");
+    __publicField$4(this, "_size", null);
+    __publicField$4(this, "_mimeType");
+    __publicField$4(this, "_name");
     this._file = file;
+    if (file instanceof File || file instanceof Blob) {
+      this._size = file.size;
+    }
+    if (file instanceof File || file instanceof Blob) {
+      this._mimeType = file.type;
+    }
+    if ("name" in options) {
+      this._name = options.name;
+    }
+    if ("mimeType" in options) {
+      this._mimeType = options.mimeType;
+    }
     this._options = options;
     this.validateFile();
   }
+  static create(file, options) {
+    return new TelaFile(file, options);
+  }
   /**
    * Retrieves the options provided during instantiation.
    *
@@ -1043,7 +1092,15 @@ class TelaFile {
    * @returns `true` if the file source is a valid URL string, otherwise `false`.
    */
   get isURL() {
-    return typeof this._file === "string" && this.isValidURL(this._file);
+    return this.isValidURL(this._file);
+  }
+  /**
+   * Determines whether the file source is a valid Vault reference.
+   *
+   * @returns `true` if the file source is a valid Vault reference, otherwise `false`.
+   */
+  get isVaultReference() {
+    return this.isValidVaultReference(this._file);
   }
   /**
    * Gets the size of the file in bytes.
@@ -1053,6 +1110,22 @@ class TelaFile {
   get size() {
     return this._size;
   }
+  /**
+   * Gets the name of the file.
+   *
+   * @returns The name of the file if available, otherwise `null`.
+   */
+  get name() {
+    return this._name ?? null;
+  }
+  /**
+   * Gets the type of the file.
+   *
+   * @returns The type of the file if available, otherwise `null`.
+   */
+  get type() {
+    return this._mimeType ?? null;
+  }
   /**
    * Retrieves the content of the file in a format suitable for uploading.
    *
@@ -1063,11 +1136,11 @@ class TelaFile {
    * @returns A promise that resolves to the uploadable content.
    */
   async getUploadableContent() {
-    if (this.isURL && typeof this._file === "string") {
+    if (this.isValidURL(this._file) || this.isValidVaultReference(this._file)) {
       return this._file;
     }
     if (this._file instanceof Uint8Array) {
-      return new File([this._file], "file", {
+      return new File([this._file.buffer], "file", {
         type: "application/octet-stream"
       });
     }
@@ -1108,6 +1181,9 @@ class TelaFile {
    * @returns `true` if the URL is valid, otherwise `false`.
    */
   isValidURL(url) {
+    if (typeof url !== "string") {
+      return false;
+    }
     try {
       new URL(url);
       return true;
@@ -1115,43 +1191,604 @@ class TelaFile {
       return false;
     }
   }
+  /**
+   * Checks if the provided string is a valid Vault reference.
+   *
+   * @param url - The Vault reference string to validate.
+   * @returns `true` if the Vault reference is valid, otherwise `false`.
+   */
+  isValidVaultReference(url) {
+    if (typeof url !== "string") {
+      return false;
+    }
+    return url.startsWith("vault://");
+  }
+}
+
+function compareSchemas(clientSchema, serverSchema, path = "$") {
+  const mismatches = [];
+  if (clientSchema.type !== serverSchema.type) {
+    mismatches.push({
+      path,
+      issue: `Type mismatch: client has "${clientSchema.type}", server has "${serverSchema.type}"`
+    });
+    return mismatches;
+  }
+  if (clientSchema.type === "object") {
+    const clientProps = clientSchema.properties || {};
+    const serverProps = serverSchema.properties || {};
+    const clientRequired = clientSchema.required || [];
+    const serverRequired = serverSchema.required || [];
+    for (const reqProp of serverRequired) {
+      if (!clientProps[reqProp]) {
+        mismatches.push({
+          path: `${path}.${reqProp}`,
+          issue: `Property is required on server but missing on client`
+        });
+        continue;
+      }
+      if (!clientRequired.includes(reqProp)) {
+        mismatches.push({
+          path: `${path}.${reqProp}`,
+          issue: `Property is required on server but optional on client`
+        });
+      }
+    }
+    for (const clientProp of Object.keys(clientProps)) {
+      if (!serverProps[clientProp]) {
+        mismatches.push({
+          path: `${path}.${clientProp}`,
+          issue: `Extra property not expected by server`
+        });
+      }
+    }
+    for (const prop of Object.keys(serverProps)) {
+      if (!clientProps[prop]) {
+        continue;
+      }
+      const nestedMismatches = compareSchemas(
+        clientProps[prop],
+        serverProps[prop],
+        `${path}.${prop}`
+      );
+      mismatches.push(...nestedMismatches);
+    }
+  }
+  if (clientSchema.type === "array") {
+    const clientItems = clientSchema.items;
+    const serverItems = serverSchema.items;
+    if (!clientItems || !serverItems) {
+      if (clientItems !== serverItems) {
+        mismatches.push({
+          path: `${path}[]`,
+          issue: `Array items schema mismatch: one side has items definition, other doesn't`
+        });
+      }
+      return mismatches;
+    }
+    const itemMismatches = compareSchemas(
+      clientItems,
+      serverItems,
+      `${path}[]`
+    );
+    mismatches.push(...itemMismatches);
+  }
+  return mismatches;
 }
-function createTelaFile(file, options) {
-  return new TelaFile(file, options);
+function mapServerTypeToJsonSchemaType(serverType) {
+  const typeMap = {
+    text: "string",
+    number: "number",
+    boolean: "boolean",
+    file: "string",
+    // z.file() generates type: "string" with format: "binary", contentEncoding: "binary"
+    array: "array",
+    object: "object"
+  };
+  return typeMap[serverType.toLowerCase()] || null;
+}
+function validateInputSchema(clientSchema, serverVariables) {
+  const mismatches = [];
+  const clientProps = clientSchema.properties || {};
+  const clientRequired = clientSchema.required || [];
+  for (const serverVar of serverVariables) {
+    if (serverVar.required) {
+      if (!clientProps[serverVar.name]) {
+        mismatches.push({
+          path: `$.${serverVar.name}`,
+          issue: `Property is required on server but missing on client`
+        });
+        continue;
+      }
+      if (!clientRequired.includes(serverVar.name)) {
+        mismatches.push({
+          path: `$.${serverVar.name}`,
+          issue: `Variable is required on server but optional on client`
+        });
+      }
+    }
+    if (!clientProps[serverVar.name]) {
+      continue;
+    }
+    {
+      const clientProp = clientProps[serverVar.name];
+      const clientType = clientProp.type;
+      const expectedType = mapServerTypeToJsonSchemaType(serverVar.type);
+      if (serverVar.type.toLowerCase() === "file") {
+        const isFileSchema = clientProp.isTelaFile;
+        if (isFileSchema) {
+          continue;
+        }
+        if (clientProp.format === "binary") {
+          mismatches.push({
+            path: `$.${serverVar.name}`,
+            issue: `Type mismatch: file is expected to be a \`telaFile()\` but is a regular file instead.`
+          });
+          continue;
+        }
+        if (clientType === "string" && !clientProp.format && !clientProp.contentEncoding) {
+          mismatches.push({
+            path: `$.${serverVar.name}`,
+            issue: `Type mismatch: server expects file, client has plain string. Did you mean to use \`telaFile()\`?`
+          });
+          continue;
+        }
+        mismatches.push({
+          path: `$.${serverVar.name}`,
+          issue: `Type mismatch: server expects file, client has "${clientType}"`
+        });
+        continue;
+      }
+      if (expectedType && clientType !== expectedType) {
+        mismatches.push({
+          path: `$.${serverVar.name}`,
+          issue: `Type mismatch: server expects "${serverVar.type}", client has "${clientType}"`
+        });
+      }
+    }
+  }
+  const serverVarNames = serverVariables.map((v) => v.name);
+  for (const clientProp of Object.keys(clientProps)) {
+    if (!serverVarNames.includes(clientProp)) {
+      mismatches.push({
+        path: `$.${clientProp}`,
+        issue: `Extra property not expected by server`
+      });
+    }
+  }
+  return mismatches;
+}
+function validateOutputSchema(clientSchema, serverSchema) {
+  return compareSchemas(clientSchema, serverSchema);
 }
 
-var __defProp$1 = Object.defineProperty;
-var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField$1 = (obj, key, value) => {
-  __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+var __defProp$3 = Object.defineProperty;
+var __defNormalProp$3 = (obj, key, value) => key in obj ? __defProp$3(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$3 = (obj, key, value) => {
+  __defNormalProp$3(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-class Resource {
-  constructor(client) {
-    __publicField$1(this, "_client");
-    this._client = client;
+function timeout(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    if (signal) {
+      signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      }, { once: true });
+    }
+  });
+}
+class Poller {
+  constructor({ interval, timeout: timeout2, abortSignal }) {
+    __publicField$3(this, "_interval");
+    __publicField$3(this, "_timeout");
+    __publicField$3(this, "_abortSignal");
+    __publicField$3(this, "_internalAbortController");
+    if (interval <= 0) {
+      throw new TelaError("Interval must be greater than 0");
+    }
+    if (timeout2 <= 0) {
+      throw new TelaError("Timeout must be greater than 0");
+    }
+    this._interval = interval;
+    this._timeout = timeout2;
+    this._abortSignal = abortSignal ?? new AbortController().signal;
+    this._internalAbortController = new AbortController();
+  }
+  async startTimeout() {
+    await timeout(this._timeout, this._internalAbortController.signal);
+    throw new ConnectionTimeout({
+      message: `Reached timeout of ${this._timeout}ms when polling`
+    });
+  }
+  /**
+   * Starts the polling operation, repeatedly calling the callback until completion.
+   * The callback is invoked at the configured interval and must return a PollerResult
+   * indicating whether polling should continue or if the final value is ready.
+   *
+   * @param callback - Function called on each polling iteration.
+   * @returns A promise resolving to the final result value.
+   * @throws {Error} If the polling operation times out.
+   * @throws {Error} If the operation is aborted via the AbortSignal.
+   * @throws Any error thrown by the callback function.
+   *
+   * @example
+   * ```typescript
+   * const result = await poller.start(async (signal) => {
+   *   const response = await fetch('/api/status', { signal });
+   *   const data = await response.json();
+   *
+   *   if (data.status === 'completed') {
+   *     return { done: true, value: data.result };
+   *   }
+   *   return { done: false };
+   * });
+   * ```
+   */
+  start(callback) {
+    const resultPromise = async () => {
+      try {
+        while (!this._abortSignal.aborted) {
+          const result = await Promise.try(callback, this._abortSignal);
+          if (result.done) {
+            return result.value;
+          }
+          await timeout(this._interval, this._abortSignal);
+        }
+        throw new UserAbortError({ message: "Polling aborted" });
+      } finally {
+        this._internalAbortController.abort();
+      }
+    };
+    return Promise.race([this.startTimeout(), resultPromise()]);
   }
 }
 
-class ChatCompletions extends Resource {
-  async create(body, opts) {
-    const processedBody = { ...body };
-    if (body.variables) {
-      const processedVariables = {};
-      for await (const [key, value] of Object.entries(body.variables)) {
-        if (value instanceof TelaFile) {
-          const fileWithUrl = await this.uploadFile(value);
-          processedVariables[key] = fileWithUrl;
-        } else {
-          processedVariables[key] = value;
+async function calculateSha256sum(content) {
+  const stream = content instanceof File || content instanceof Blob ? content.stream() : content;
+  const reader = stream.getReader();
+  try {
+    const { createHash } = await import('node:crypto');
+    const hash = createHash("sha256");
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      hash.update(value);
+    }
+    return hash.digest("hex");
+  } catch {
+    const chunks = [];
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      chunks.push(value);
+    }
+    const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+    const buffer = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      buffer.set(chunk, offset);
+      offset += chunk.length;
+    }
+    const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    return hashHex;
+  }
+}
+
+var __defProp$2 = Object.defineProperty;
+var __defNormalProp$2 = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$2 = (obj, key, value) => {
+  __defNormalProp$2(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+function isTelaFile(obj) {
+  return obj instanceof TelaFile;
+}
+function isTelaFileArray(obj) {
+  return Array.isArray(obj) && obj.length > 0 && obj.every(isTelaFile);
+}
+class CanvasExecution {
+  /**
+   * Creates a new canvas execution instance.
+   *
+   * @param variables - Input variables to be passed to the canvas template.
+   * @param params - Execution parameters controlling sync/async/stream behavior.
+   * @param outputSchema - Zod schema or object schema for validating/parsing output.
+   * @param client - HTTP client instance for making API requests.
+   */
+  constructor(variables, params = { async: false }, outputSchema, client) {
+    __publicField$2(this, "_id");
+    __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");
+    this._variables = variables;
+    this._params = params;
+    this._outputSchema = outputSchema;
+    this._skipResultValidation = params.skipResultValidation ?? false;
+    this._client = client;
+    this._abortController = new AbortController();
+  }
+  /**
+   * Gets the unique execution ID assigned by the server.
+   *
+   * @throws {Error} If the execution has not been started yet.
+   * @returns The execution ID.
+   */
+  get id() {
+    if (!this._id) {
+      throw new ExecutionNotStartedError();
+    }
+    return this._id;
+  }
+  /**
+   * Gets the input variables provided to this execution.
+   *
+   * @returns The variables object.
+   */
+  get variables() {
+    return this._variables;
+  }
+  /**
+   * Gets the execution parameters configured for this instance.
+   *
+   * @returns The execution parameters or undefined.
+   */
+  get params() {
+    return this._params;
+  }
+  /**
+   * Checks if this execution is configured for asynchronous processing.
+   *
+   * @returns True if async mode is enabled.
+   */
+  get isAsync() {
+    return this._isAsync(this._params);
+  }
+  /**
+   * Checks if this execution is configured for synchronous processing.
+   *
+   * @returns True if sync mode is enabled (not async).
+   */
+  get isSync() {
+    return !this._isAsync(this._params) && !this.isStream;
+  }
+  /**
+   * Checks if this execution is configured for streaming responses.
+   *
+   * @returns True if stream mode is enabled.
+   */
+  get isStream() {
+    return Boolean(this._params.stream);
+  }
+  /**
+   * Type guard to check if params indicate async execution.
+   *
+   * @param params - Execution parameters to check.
+   * @returns True if params indicate async mode.
+   */
+  _isAsync(params) {
+    return Boolean(params.async);
+  }
+  /**
+   * Starts the execution based on configured parameters.
+   * Routes to the appropriate execution method (sync, async, or stream).
+   *
+   * @returns A promise or async generator depending on execution mode.
+   */
+  start() {
+    if (this._resultPromise || this._stream) {
+      return this._resultPromise ?? this._stream;
+    }
+    if (this._params.stream) {
+      return this.startStream();
+    }
+    if (this.isSync) {
+      return this.startSync();
+    }
+    return this.startAsync();
+  }
+  /**
+   * Gets the execution result. For async executions, automatically starts polling.
+   * For sync executions, returns the result promise. For streams, returns the generator.
+   *
+   * @returns The execution result as a promise or async generator.
+   */
+  get result() {
+    if (this.isSync) {
+      if (!this._resultPromise) {
+        throw new ExecutionNotStartedError();
+      }
+      return this._resultPromise;
+    }
+    if (this.isStream) {
+      if (!this._stream) {
+        throw new ExecutionNotStartedError();
+      }
+      return this._stream;
+    }
+    if (this._resultPromise) {
+      return this._resultPromise;
+    }
+    this._resultPromise = this.startPolling();
+    return this._resultPromise;
+  }
+  /**
+   * Cancels the ongoing execution by aborting all active requests and polling operations.
+   */
+  cancel() {
+    this._abortController.abort();
+  }
+  /**
+   * Builds the base request body shared across all execution types.
+   * Includes messages, overrides, and structured output configuration.
+   *
+   * @returns The base request body object.
+   */
+  get baseBody() {
+    const body = {
+      canvasId: this._params.canvasId,
+      applicationId: this._params.applicationId,
+      versionId: this._params.versionId,
+      messages: this._params.messages
+    };
+    if (this._params.override && this._outputSchema instanceof z__default.ZodType) {
+      return {
+        ...body,
+        override: {
+          ...this._params.override,
+          structured_output: z__default.toJSONSchema(this._outputSchema)
         }
+      };
+    }
+    return body;
+  }
+  /**
+   * Processes variables and uploads any TelaFile instances to the server.
+   * Replaces TelaFile objects with their uploaded URLs while preserving other values.
+   *
+   * @returns A promise resolving to the processed variables object.
+   */
+  async resolveVariables() {
+    const variables = {};
+    for (const [key, value] of Object.entries(this._variables)) {
+      if (isTelaFileArray(value)) {
+        variables[key] = await this.uploadFiles(value);
+        continue;
+      }
+      if (isTelaFile(value)) {
+        variables[key] = await this.uploadFile(value);
+        continue;
       }
-      processedBody.variables = processedVariables;
+      variables[key] = value;
     }
-    return this._client.post("/v2/chat/completions", {
-      body: processedBody,
-      ...opts,
-      stream: body.stream ?? false
+    return variables;
+  }
+  /**
+   * Initiates a synchronous execution that waits for the complete result.
+   * The result is validated against the output schema if provided.
+   *
+   * @returns A promise resolving to the parsed execution result.
+   */
+  async startSync() {
+    const resolvedVariables = await this.resolveVariables();
+    const body = {
+      async: this._params.async ?? false,
+      stream: false,
+      ...this.baseBody,
+      variables: resolvedVariables
+    };
+    this._resultPromise = this._client.post("/v2/chat/completions", {
+      body,
+      stream: false,
+      signal: this._abortController.signal
+    }).then((response) => {
+      this._id = response.id;
+      return response.choices?.[0]?.message?.content;
+    }).then((content) => {
+      if (this._skipResultValidation || !(this._outputSchema instanceof z__default.ZodType)) {
+        return content;
+      }
+      return this._outputSchema.parse(content);
+    });
+    return this._resultPromise;
+  }
+  /**
+   * Initiates an asynchronous execution that returns immediately with an execution ID.
+   * Results must be retrieved separately via polling using the `result` getter.
+   *
+   * @returns A promise that resolves when the execution is queued.
+   */
+  async startAsync() {
+    const resolvedVariables = await this.resolveVariables();
+    const body = {
+      async: true,
+      stream: false,
+      ...this.baseBody,
+      variables: resolvedVariables
+    };
+    return await this._client.post("/v2/chat/completions", {
+      body,
+      stream: false,
+      signal: this._abortController.signal
+    }).then((response) => {
+      this._id = response.id;
+      return response;
+    });
+  }
+  /**
+   * Initiates a streaming execution that returns results incrementally as they're generated.
+   *
+   * @returns A promise resolving to an async generator yielding result chunks.
+   */
+  async startStream() {
+    const resolvedVariables = await this.resolveVariables();
+    const body = {
+      ...this.baseBody,
+      stream: true,
+      variables: resolvedVariables
+    };
+    this._stream = await this._client.post("/v2/chat/completions", {
+      body,
+      stream: true,
+      signal: this._abortController.signal
+    });
+    return this._stream;
+  }
+  /**
+   * Polls the server for async execution results at regular intervals.
+   * Continues polling until the execution completes or the timeout is reached.
+   *
+   * @throws {Error} If called on a non-async execution.
+   * @throws {Error} If the execution fails on the server.
+   * @throws {Error} If the polling operation times out.
+   * @returns A promise resolving to the final execution result.
+   */
+  async startPolling() {
+    if (!this._isAsync(this._params)) {
+      throw new InvalidExecutionModeError("Polling is only supported for async executions");
+    }
+    return new Poller({
+      interval: this._params.pollingInterval ?? 1e3,
+      // 1 second
+      timeout: this._params.pollingTimeout ?? 6e4,
+      // 1 minute
+      abortSignal: this._abortController.signal
+    }).start(async (signal) => {
+      const response = await this._client.get(
+        `/v2/chat/completions/${this.id}`,
+        {
+          signal
+        }
+      );
+      if (response.status === "failed") {
+        throw new ExecutionFailedError(response.rawOutput);
+      }
+      if (response.status !== "succeeded") {
+        return {
+          done: false,
+          value: void 0
+        };
+      }
+      return {
+        done: response.status === "succeeded",
+        value: response.outputContent.content
+      };
+    }).then((value) => {
+      if (this._skipResultValidation || !(this._outputSchema instanceof z__default.ZodType)) {
+        return value;
+      }
+      return this._outputSchema.parse(value);
     });
   }
   /**
@@ -1167,36 +1804,303 @@ class ChatCompletions extends Resource {
    * ```typescript
    * const file = new TelaFile({ /* file options *\/ });
    * const uploadedFile = await this.uploadFile(file);
-   * console.log(uploadedFile.file_url);
+   * console.log(uploadedFile.fileUrl);
    * ```
    */
   async uploadFile(file) {
-    const content = await file.getUploadableContent();
-    if (file.isURL && typeof content === "string") {
+    let content = await file.getUploadableContent();
+    let sha256sumStream;
+    if (typeof content === "string") {
       return { fileUrl: content, options: file.options };
     }
-    const response = await this._client.post(
-      "/v2/file"
-    );
-    const { uploadUrl, downloadUrl } = response;
-    let contentType = "application/octet-stream";
-    if (content instanceof File || content instanceof Blob) {
-      contentType = content.type;
+    const filename = file.name ?? void 0;
+    const fileType = file.type ?? void 0;
+    const contentLength = file.size ?? void 0;
+    if (content instanceof ReadableStream) {
+      const [hashStream, contentStream] = content.tee();
+      content = contentStream;
+      sha256sumStream = hashStream;
+    }
+    const sha256sum = await calculateSha256sum(sha256sumStream ?? content);
+    const { id, uploadUrl } = await this._client.post("/_services/vault/files", {
+      body: {
+        fileName: filename,
+        mimeType: fileType,
+        size: contentLength ?? void 0,
+        sha256sum
+      }
+    });
+    if (content instanceof ReadableStream && typeof Bun !== "undefined") {
+      console.warn(
+        "[Tela SDK - WARNING] Buffering file upload due to Bun fetch implementation. Large files may cause memory issues. Consider using Node.js for streaming uploads.",
+        { fileName: filename, fileSize: contentLength }
+      );
+      const chunks = [];
+      const reader = content.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+          break;
+        chunks.push(value);
+      }
+      content = new Blob(chunks, { type: fileType ?? "application/octet-stream" });
     }
-    const uploadResponse = await fetch(uploadUrl, {
+    const request = new Request(uploadUrl, {
       method: "PUT",
       body: content,
       headers: {
-        "Content-Type": contentType,
+        "Content-Type": fileType ?? "application/octet-stream",
         ...file.size ? { "Content-Length": file.size.toString() } : {}
-      },
-      // duplex is not supported
-      duplex: "half"
+      }
     });
+    const uploadResponse = await fetch(request);
     if (!uploadResponse.ok) {
-      throw new FileUploadError(await uploadResponse.text());
+      throw new FileUploadError(await uploadResponse.text(), uploadResponse.status);
+    }
+    return { fileUrl: `vault://${id}`, options: file.options };
+  }
+  /**
+   * Uploads multiple files and returns their URLs and options.
+   *
+   * This is used internally to handle multiple file uploads associated with chat completions.
+   *
+   * @param files - An array of TelaFile instances to be uploaded.
+   * @returns A Promise that resolves to an array of objects containing file URLs and options.
+   * @throws {FileUploadError} If any file upload fails.
+   */
+  async uploadFiles(files) {
+    const uploadPromises = files.map((file) => this.uploadFile(file));
+    return Promise.all(uploadPromises);
+  }
+}
+
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => {
+  __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+const zod = {
+  string: z.string,
+  number: z.number,
+  boolean: z.boolean,
+  object: z.object,
+  array: z.array,
+  file: TelaFileSchema,
+  any: z.any,
+  unknown: z.unknown
+};
+function fetchById(id, client) {
+  return client.get(`/prompt/${id}/promoted-version`);
+}
+function fetchByVersionId(versionId, client) {
+  return client.get(`/prompt-version/${versionId}`);
+}
+function fetchByApplicationId(applicationId, client) {
+  return client.get(`/prompt-application/${applicationId}/targetPromptVersion`);
+}
+function fetchByAny({ id, versionId, applicationId, client }) {
+  if (applicationId) {
+    return fetchByApplicationId(applicationId, client);
+  }
+  if (versionId) {
+    return fetchByVersionId(versionId, client);
+  }
+  if (id) {
+    return fetchById(id, client);
+  }
+  throw new Error("Either id, versionId, or applicationId must be provided");
+}
+function validateSchemas(input, output, promptVersion) {
+  const canvasIdentifier = `${promptVersion.title} (${promptVersion.promptId})`;
+  if (input instanceof z.z.ZodType) {
+    try {
+      const inputSchema = z.z.toJSONSchema(input, { unrepresentable: "any" });
+      const mismatches = validateInputSchema(inputSchema, promptVersion.variables);
+      if (mismatches.length === 0) {
+        return;
+      }
+      console.warn(
+        `[Tela SDK - Canvas Input Validation] Input schema mismatches for canvas "${canvasIdentifier}":`
+      );
+      for (const mismatch of mismatches) {
+        console.warn(`  - ${mismatch.path}: ${mismatch.issue}`);
+      }
+    } catch (error) {
+      console.warn(
+        `[Tela SDK - Canvas Input Validation] Failed to validate input schema for canvas "${canvasIdentifier}":`,
+        error
+      );
+    }
+  }
+  if (output instanceof z.z.ZodType) {
+    try {
+      const outputSchema = z.z.toJSONSchema(output);
+      const serverOutput = promptVersion.configuration.structuredOutput;
+      if (!serverOutput.enabled) {
+        console.warn(
+          `[Tela SDK - Canvas Output Validation] Output schema provided for canvas "${canvasIdentifier}", but structured output is not enabled on the server. The schema may not be enforced.`
+        );
+        return;
+      }
+      const mismatches = validateOutputSchema(outputSchema, serverOutput.schema);
+      if (mismatches.length === 0) {
+        return;
+      }
+      console.warn(
+        `[Tela SDK - Canvas Output Validation] Output schema mismatches for canvas "${canvasIdentifier}":`
+      );
+      for (const mismatch of mismatches) {
+        console.warn(`  - ${mismatch.path}: ${mismatch.issue}`);
+      }
+    } catch (error) {
+      console.warn(
+        `[Tela SDK - Canvas Output Validation] Failed to validate output schema for canvas "${canvasIdentifier}":`,
+        error
+      );
     }
-    return { fileUrl: downloadUrl, options: file.options };
+  }
+}
+class Canvas {
+  /**
+   * Creates a new instance of the Canvas class. Usage of this constructor is not recommended.
+   * Use the `tela.getCanvas` method instead.
+   *
+   * @private
+   */
+  constructor({ id, applicationId, name, versionId, input, output, client, variables }) {
+    __publicField$1(this, "_id");
+    __publicField$1(this, "_versionId");
+    __publicField$1(this, "_applicationId");
+    __publicField$1(this, "_name");
+    __publicField$1(this, "_input");
+    __publicField$1(this, "_output");
+    __publicField$1(this, "_client");
+    __publicField$1(this, "_variables");
+    this._id = id;
+    this._applicationId = applicationId;
+    this._name = name;
+    this._versionId = versionId;
+    this._input = input && input(zod);
+    this._output = output && output(zod);
+    this._client = client;
+    this._variables = variables;
+  }
+  /**
+   * Gets a canvas by its ID.
+   *
+   * @param options - The options to use to get the canvas.
+   * @param options.id - The ID of the canvas to get.
+   * @param options.versionId - The version ID of the canvas to get.
+   * @param options.applicationId - The application ID of the canvas to get.
+   * @param options.client - The client to use to make the request.
+   * @param options.input - The input schema of the canvas to get.
+   * @param options.output - The output schema of the canvas to get.
+   * @returns The canvas.
+   */
+  static async get(options) {
+    const { id, versionId, applicationId, client, input, output, skipSchemaValidation = false } = options;
+    const promptVersion = await fetchByAny({ id, versionId, applicationId, client });
+    const inputSchema = input && input(zod);
+    const outputSchema = output && output(zod);
+    if (!skipSchemaValidation) {
+      validateSchemas(inputSchema, outputSchema, promptVersion);
+    }
+    return new Canvas({
+      id: promptVersion.promptId,
+      name: promptVersion.title,
+      versionId: promptVersion.id,
+      input,
+      output,
+      client,
+      variables: promptVersion.variables
+    });
+  }
+  /**
+   * Gets the unique identifier of this canvas.
+   *
+   * @returns The canvas ID.
+   */
+  get id() {
+    if (!this._id) {
+      throw new Error("Canvas ID is not set");
+    }
+    return this._id;
+  }
+  /**
+   * Gets the name of this canvas, if provided.
+   *
+   * @returns The canvas name or undefined.
+   */
+  get name() {
+    if (!this._name) {
+      throw new Error("Canvas name is not set");
+    }
+    return this._name;
+  }
+  /**
+   * Gets the version identifier of this canvas, if specified.
+   * When undefined, the latest promoted version is used.
+   *
+   * @returns The version ID or undefined.
+   */
+  get versionId() {
+    if (!this._versionId) {
+      throw new Error("Canvas version ID is not set");
+    }
+    return this._versionId;
+  }
+  get applicationId() {
+    if (!this._applicationId) {
+      throw new Error("Canvas application ID is not set");
+    }
+    return this._applicationId;
+  }
+  /**
+   * Gets the variables of this canvas.
+   *
+   * @returns The variables of the canvas.
+   */
+  get variables() {
+    return this._variables;
+  }
+  /**
+   * Validates and parses input variables using the canvas input schema.
+   *
+   * @param variables - Raw input variables to validate.
+   * @returns Parsed and validated variables.
+   * @throws {ZodError} If validation fails when a Zod schema is configured.
+   */
+  parseVariables(variables) {
+    try {
+      if (this._input instanceof z.z.ZodType) {
+        return this._input.parse(variables);
+      }
+      return variables;
+    } catch (error) {
+      if (!(error instanceof z.ZodError)) {
+        throw error;
+      }
+      throw new Error(z.z.prettifyError(error));
+    }
+  }
+  execute(variables, params) {
+    const parsedInput = this.parseVariables(variables);
+    const fullParams = {
+      ...params ?? { async: false },
+      versionId: this._versionId,
+      canvasId: this._id,
+      applicationId: this._applicationId
+    };
+    const execution = new CanvasExecution(parsedInput, fullParams, this._output, this._client);
+    return {
+      then(onfulfilled, onrejected) {
+        return Promise.resolve(execution.start()).then(() => onfulfilled?.(execution) ?? execution).catch(onrejected);
+      },
+      get result() {
+        return Promise.resolve(execution.start()).then(() => execution.result);
+      }
+    };
   }
 }
 
@@ -1217,31 +2121,56 @@ const _TelaSDK = class _TelaSDK extends BaseClient {
     __publicField(this, "apiKey");
     __publicField(this, "jwt");
     /**
-     * The ChatCompletions resource for interacting with Tela's chat completion API.
+     * Creates a new `TelaFile` instance from the provided file input.
      *
-     * Use this to generate chat completions based on provided messages.
+     * @param file - The file input to create a `TelaFile` instance from.
+     * @returns A new `TelaFile` instance.
+     */
+    __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.
+     *
+     * @param options - Options for retrieving the canvas.
+     * @returns A promise resolving to a Canvas instance.
      *
      * @example
      * ```typescript
-     * const completion = await tela.completions.create({
-     *   canvasId: "your-canvas-id",
-     *   messages: [{ role: "user", content: "Hello!" }],
+     * 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() })
      * });
-     * ```
-     */
-    __publicField(this, "completions", new ChatCompletions(this));
-    /**
-     * Creates a new `TelaFile` instance from the provided file input.
      *
-     * @param file - The file input to create a `TelaFile` instance from.
-     * @returns A new `TelaFile` instance.
+     * // Get canvas by application ID
+     * const canvas = await tela.canvas.get({
+     *   applicationId: 'app-id'
+     * });
+     *
+     * // Execute the canvas
+     * const execution = await canvas.execute({ query: 'Hello' });
+     * const result = await execution.result;
+     * ```
      */
-    __publicField(this, "createFile", createTelaFile.bind(this));
+    __publicField(this, "canvas", {
+      get: async (options) => {
+        return Canvas.get({
+          ...options,
+          client: this
+        });
+      }
+    });
     this.opts = { baseURL, ...rest };
     this.apiKey = apiKey;
     this.jwt = jwt;
     this.validateAuth();
   }
+  get authToken() {
+    return this.apiKey || this.jwt;
+  }
   validateAuth() {
     if (!this.apiKey && !this.jwt) {
       throw new MissingApiKeyOrJWTError();
@@ -1298,6 +2227,30 @@ function createTelaClient(opts) {
   return new TelaSDK(opts);
 }
 
+exports.APIError = APIError;
+exports.AuthenticationError = AuthenticationError;
+exports.AuthorizationError = AuthorizationError;
+exports.BadRequestError = BadRequestError;
+exports.BaseClient = BaseClient;
+exports.ConflictApiKeyAndJWTError = ConflictApiKeyAndJWTError;
+exports.ConflictError = ConflictError;
+exports.ConnectionError = ConnectionError;
+exports.ConnectionTimeout = ConnectionTimeout;
+exports.EmptyFileError = EmptyFileError;
+exports.ExecutionFailedError = ExecutionFailedError;
+exports.ExecutionNotStartedError = ExecutionNotStartedError;
+exports.FileUploadError = FileUploadError;
+exports.InternalServerError = InternalServerError;
+exports.InvalidExecutionModeError = InvalidExecutionModeError;
+exports.InvalidFileURL = InvalidFileURL;
+exports.MissingApiKeyOrJWTError = MissingApiKeyOrJWTError;
+exports.NotFoundError = NotFoundError;
+exports.RateLimitError = RateLimitError;
+exports.TelaError = TelaError;
 exports.TelaFile = TelaFile;
+exports.TelaFileSchema = TelaFileSchema;
 exports.TelaSDK = TelaSDK;
+exports.UnprocessableEntityError = UnprocessableEntityError;
+exports.UserAbortError = UserAbortError;
 exports.createTelaClient = createTelaClient;
+exports.toError = toError;