@synova-cloud/sdk 1.6.0 → 1.8.0

package/dist/index.js

@@ -1,3 +1,12 @@
+import 'reflect-metadata';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/errors/index.ts
 var SynovaError = class extends Error {
   constructor(message) {
@@ -69,9 +78,34 @@ var NetworkSynovaError = class extends SynovaError {
     this.cause = cause;
   }
 };
+var ExecutionSynovaError = class extends SynovaError {
+  code;
+  provider;
+  retryable;
+  retryAfterMs;
+  details;
+  constructor(error) {
+    super(error.message);
+    this.name = "ExecutionSynovaError";
+    this.code = error.code;
+    this.provider = error.provider;
+    this.retryable = error.retryable;
+    this.retryAfterMs = error.retryAfterMs;
+    this.details = error.details;
+  }
+};
+var ValidationSynovaError = class extends SynovaError {
+  violations;
+  constructor(violations) {
+    const message = `Validation failed: ${violations.map((v) => v.property).join(", ")}`;
+    super(message);
+    this.name = "ValidationSynovaError";
+    this.violations = violations;
+  }
+};
 
 // src/version.ts
-var SDK_VERSION = "1.6.0" ;
+var SDK_VERSION = "1.8.0" ;
 
 // src/utils/http.ts
 var HttpClient = class {
@@ -282,6 +316,451 @@ var HttpClient = class {
   }
 };
 
+// src/schema/types.ts
+var SCHEMA_METADATA_KEYS = {
+  // Metadata
+  DESCRIPTION: "synova:schema:description",
+  EXAMPLES: "synova:schema:examples",
+  DEFAULT: "synova:schema:default",
+  // Type helpers
+  FORMAT: "synova:schema:format",
+  ARRAY_ITEM_TYPE: "synova:schema:arrayItemType",
+  NULLABLE: "synova:schema:nullable",
+  ENUM: "synova:schema:enum",
+  // String constraints
+  MIN_LENGTH: "synova:schema:minLength",
+  MAX_LENGTH: "synova:schema:maxLength",
+  PATTERN: "synova:schema:pattern",
+  // Number constraints
+  MINIMUM: "synova:schema:minimum",
+  MAXIMUM: "synova:schema:maximum",
+  EXCLUSIVE_MINIMUM: "synova:schema:exclusiveMinimum",
+  EXCLUSIVE_MAXIMUM: "synova:schema:exclusiveMaximum",
+  MULTIPLE_OF: "synova:schema:multipleOf",
+  // Array constraints
+  MIN_ITEMS: "synova:schema:minItems",
+  MAX_ITEMS: "synova:schema:maxItems",
+  UNIQUE_ITEMS: "synova:schema:uniqueItems"
+};
+function createMetadataDecorator(key, value) {
+  return function(target, propertyKey) {
+    Reflect.defineMetadata(key, value, target, propertyKey);
+  };
+}
+function Description(description) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.DESCRIPTION, description);
+}
+function Example(...examples) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.EXAMPLES, examples);
+}
+function Default(value) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.DEFAULT, value);
+}
+function ArrayItems(itemType) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.ARRAY_ITEM_TYPE, itemType);
+}
+function Format(format) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.FORMAT, format);
+}
+function Nullable() {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.NULLABLE, true);
+}
+function SchemaMinLength(length) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MIN_LENGTH, length);
+}
+function SchemaMaxLength(length) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MAX_LENGTH, length);
+}
+function SchemaPattern(pattern) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.PATTERN, pattern);
+}
+function SchemaMin(value) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MINIMUM, value);
+}
+function SchemaMax(value) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MAXIMUM, value);
+}
+function ExclusiveMin(value) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.EXCLUSIVE_MINIMUM, value);
+}
+function ExclusiveMax(value) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.EXCLUSIVE_MAXIMUM, value);
+}
+function MultipleOf(value) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MULTIPLE_OF, value);
+}
+function SchemaMinItems(count) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MIN_ITEMS, count);
+}
+function SchemaMaxItems(count) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.MAX_ITEMS, count);
+}
+function SchemaUniqueItems() {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.UNIQUE_ITEMS, true);
+}
+function SchemaEnum(values) {
+  return createMetadataDecorator(SCHEMA_METADATA_KEYS.ENUM, values);
+}
+function getSchemaMetadata(key, target, propertyKey) {
+  return Reflect.getMetadata(key, target, propertyKey);
+}
+
+// src/schema/class-schema.ts
+var ClassSchema = class {
+  /**
+   * Generate JSON Schema from a class
+   */
+  static generate(targetClass, options = {}) {
+    const { additionalProperties = false } = options;
+    const properties = this.getProperties(targetClass);
+    const required = this.getRequiredProperties(targetClass, properties);
+    return {
+      type: "object",
+      properties,
+      required: required.length > 0 ? required : void 0,
+      additionalProperties
+    };
+  }
+  /**
+   * Get all properties with their schemas
+   */
+  static getProperties(targetClass) {
+    const properties = {};
+    const prototype = targetClass.prototype;
+    const classValidatorProperties = this.getClassValidatorProperties(targetClass);
+    const decoratorProperties = this.getDecoratorProperties(prototype);
+    const allProperties = /* @__PURE__ */ new Set([...classValidatorProperties, ...decoratorProperties]);
+    for (const propertyName of allProperties) {
+      properties[propertyName] = this.getPropertySchema(targetClass, propertyName);
+    }
+    return properties;
+  }
+  /**
+   * Get property names from class-validator metadata
+   */
+  static getClassValidatorProperties(targetClass) {
+    try {
+      const { getMetadataStorage } = __require("class-validator");
+      const metadataStorage = getMetadataStorage();
+      const targetMetadatas = metadataStorage.getTargetValidationMetadatas(
+        targetClass,
+        "",
+        true,
+        false
+      );
+      const propertyNames = targetMetadatas.map((m) => m.propertyName);
+      return [...new Set(propertyNames)];
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Get property names from our decorator metadata
+   */
+  static getDecoratorProperties(prototype) {
+    const properties = [];
+    const ownKeys = Reflect.ownKeys(prototype);
+    for (const key of ownKeys) {
+      if (typeof key === "string" && key !== "constructor") {
+        for (const metaKey of Object.values(SCHEMA_METADATA_KEYS)) {
+          if (Reflect.hasMetadata(metaKey, prototype, key)) {
+            properties.push(key);
+            break;
+          }
+        }
+      }
+    }
+    return properties;
+  }
+  /**
+   * Get JSON Schema for a single property
+   */
+  static getPropertySchema(targetClass, propertyName) {
+    const prototype = targetClass.prototype;
+    const schema = {};
+    const designType = Reflect.getMetadata("design:type", prototype, propertyName);
+    const baseSchema = this.getBaseTypeSchema(designType, targetClass, propertyName);
+    Object.assign(schema, baseSchema);
+    this.applyClassValidatorConstraints(schema, targetClass, propertyName);
+    this.applyDecoratorMetadata(schema, prototype, propertyName);
+    const isNullable = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.NULLABLE,
+      prototype,
+      propertyName
+    );
+    if (isNullable && schema.type && typeof schema.type === "string") {
+      schema.type = [schema.type, "null"];
+    }
+    return schema;
+  }
+  /**
+   * Get base schema from TypeScript type
+   */
+  static getBaseTypeSchema(designType, targetClass, propertyName) {
+    if (designType === String) {
+      return { type: "string" };
+    }
+    if (designType === Number) {
+      return { type: "number" };
+    }
+    if (designType === Boolean) {
+      return { type: "boolean" };
+    }
+    if (designType === Array) {
+      const itemType = getSchemaMetadata(
+        SCHEMA_METADATA_KEYS.ARRAY_ITEM_TYPE,
+        targetClass.prototype,
+        propertyName
+      );
+      return {
+        type: "array",
+        items: this.getArrayItemSchema(itemType)
+      };
+    }
+    if (designType === Object) {
+      return { type: "object" };
+    }
+    if (typeof designType === "function" && designType.prototype) {
+      return this.generate(designType);
+    }
+    return { type: "string" };
+  }
+  /**
+   * Get schema for array items
+   */
+  static getArrayItemSchema(itemType) {
+    if (!itemType) {
+      return { type: "string" };
+    }
+    if (itemType === String) {
+      return { type: "string" };
+    }
+    if (itemType === Number) {
+      return { type: "number" };
+    }
+    if (itemType === Boolean) {
+      return { type: "boolean" };
+    }
+    return this.generate(itemType);
+  }
+  /**
+   * Apply class-validator constraints to schema
+   */
+  static applyClassValidatorConstraints(schema, targetClass, propertyName) {
+    try {
+      const { getMetadataStorage } = __require("class-validator");
+      const metadataStorage = getMetadataStorage();
+      const targetMetadatas = metadataStorage.getTargetValidationMetadatas(
+        targetClass,
+        "",
+        true,
+        false
+      );
+      const propertyMetadatas = targetMetadatas.filter(
+        (m) => m.propertyName === propertyName
+      );
+      for (const metadata of propertyMetadatas) {
+        this.applyValidationConstraint(schema, metadata);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Apply a single class-validator constraint
+   */
+  static applyValidationConstraint(schema, metadata) {
+    const constraintType = metadata.name || metadata.type || "";
+    const constraints = metadata.constraints || [];
+    switch (constraintType) {
+      case "isString":
+        schema.type = "string";
+        break;
+      case "isNumber":
+      case "isInt":
+        schema.type = constraintType === "isInt" ? "integer" : "number";
+        break;
+      case "isBoolean":
+        schema.type = "boolean";
+        break;
+      case "isArray":
+        schema.type = "array";
+        break;
+      case "isEnum":
+        if (constraints[0]) {
+          schema.enum = Object.values(constraints[0]);
+        }
+        break;
+      case "minLength":
+        schema.minLength = constraints[0];
+        break;
+      case "maxLength":
+        schema.maxLength = constraints[0];
+        break;
+      case "min":
+        schema.minimum = constraints[0];
+        break;
+      case "max":
+        schema.maximum = constraints[0];
+        break;
+      case "isEmail":
+        schema.format = "email";
+        break;
+      case "isUrl":
+      case "isURL":
+        schema.format = "uri";
+        break;
+      case "isUUID":
+        schema.format = "uuid";
+        break;
+      case "isDateString":
+      case "isISO8601":
+        schema.format = "date-time";
+        break;
+      case "matches":
+        if (constraints[0] instanceof RegExp) {
+          schema.pattern = constraints[0].source;
+        } else if (typeof constraints[0] === "string") {
+          schema.pattern = constraints[0];
+        }
+        break;
+      case "arrayMinSize":
+        schema.minItems = constraints[0];
+        break;
+      case "arrayMaxSize":
+        schema.maxItems = constraints[0];
+        break;
+      case "arrayUnique":
+        schema.uniqueItems = true;
+        break;
+    }
+  }
+  /**
+   * Apply our decorator metadata to schema.
+   * Our decorators take precedence over class-validator if both are used.
+   */
+  static applyDecoratorMetadata(schema, prototype, propertyName) {
+    const description = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.DESCRIPTION,
+      prototype,
+      propertyName
+    );
+    if (description) schema.description = description;
+    const examples = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.EXAMPLES,
+      prototype,
+      propertyName
+    );
+    if (examples) schema.examples = examples;
+    const defaultValue = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.DEFAULT,
+      prototype,
+      propertyName
+    );
+    if (defaultValue !== void 0) schema.default = defaultValue;
+    const format = getSchemaMetadata(SCHEMA_METADATA_KEYS.FORMAT, prototype, propertyName);
+    if (format) schema.format = format;
+    const enumValues = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.ENUM,
+      prototype,
+      propertyName
+    );
+    if (enumValues) schema.enum = enumValues;
+    const minLength = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MIN_LENGTH,
+      prototype,
+      propertyName
+    );
+    if (minLength !== void 0) schema.minLength = minLength;
+    const maxLength = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MAX_LENGTH,
+      prototype,
+      propertyName
+    );
+    if (maxLength !== void 0) schema.maxLength = maxLength;
+    const pattern = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.PATTERN,
+      prototype,
+      propertyName
+    );
+    if (pattern) schema.pattern = pattern;
+    const minimum = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MINIMUM,
+      prototype,
+      propertyName
+    );
+    if (minimum !== void 0) schema.minimum = minimum;
+    const maximum = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MAXIMUM,
+      prototype,
+      propertyName
+    );
+    if (maximum !== void 0) schema.maximum = maximum;
+    const exclusiveMinimum = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.EXCLUSIVE_MINIMUM,
+      prototype,
+      propertyName
+    );
+    if (exclusiveMinimum !== void 0) schema.exclusiveMinimum = exclusiveMinimum;
+    const exclusiveMaximum = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.EXCLUSIVE_MAXIMUM,
+      prototype,
+      propertyName
+    );
+    if (exclusiveMaximum !== void 0) schema.exclusiveMaximum = exclusiveMaximum;
+    const multipleOf = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MULTIPLE_OF,
+      prototype,
+      propertyName
+    );
+    if (multipleOf !== void 0) schema.multipleOf = multipleOf;
+    const minItems = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MIN_ITEMS,
+      prototype,
+      propertyName
+    );
+    if (minItems !== void 0) schema.minItems = minItems;
+    const maxItems = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.MAX_ITEMS,
+      prototype,
+      propertyName
+    );
+    if (maxItems !== void 0) schema.maxItems = maxItems;
+    const uniqueItems = getSchemaMetadata(
+      SCHEMA_METADATA_KEYS.UNIQUE_ITEMS,
+      prototype,
+      propertyName
+    );
+    if (uniqueItems) schema.uniqueItems = uniqueItems;
+  }
+  /**
+   * Get required properties (properties without @IsOptional)
+   */
+  static getRequiredProperties(targetClass, properties) {
+    const required = [];
+    try {
+      const { getMetadataStorage } = __require("class-validator");
+      const metadataStorage = getMetadataStorage();
+      const targetMetadatas = metadataStorage.getTargetValidationMetadatas(
+        targetClass,
+        "",
+        true,
+        false
+      );
+      for (const propertyName of Object.keys(properties)) {
+        const isOptional = targetMetadatas.some(
+          (m) => m.propertyName === propertyName && (m.type === "isOptional" || m.type === "conditionalValidation")
+        );
+        if (!isOptional) {
+          required.push(propertyName);
+        }
+      }
+    } catch {
+      required.push(...Object.keys(properties));
+    }
+    return required;
+  }
+};
+
 // src/resources/prompts.ts
 var PromptsResource = class {
   constructor(http) {
@@ -289,22 +768,6 @@ var PromptsResource = class {
   }
   /**
    * Get a prompt by ID (returns version with 'latest' tag)
-   *
-   * @param promptId - The prompt ID (e.g., 'prm_abc123')
-   * @param options - Optional settings
-   * @returns The prompt data
-   *
-   * @example
-   * ```ts
-   * // Get default (latest) version
-   * const prompt = await client.prompts.get('prm_abc123');
-   *
-   * // Get by specific tag
-   * const production = await client.prompts.get('prm_abc123', { tag: 'production' });
-   *
-   * // Get specific version
-   * const v2 = await client.prompts.get('prm_abc123', { version: '2.0.0' });
-   * ```
    */
   async get(promptId, options) {
     if (options?.version) {
@@ -325,38 +788,23 @@ var PromptsResource = class {
       path: `/api/v1/prompts/${promptId}/tags/${tag}`
     });
   }
+  async execute(promptId, options) {
+    if ("responseClass" in options && options.responseClass) {
+      return this.executeTyped(promptId, options);
+    }
+    return this.executeRaw(promptId, options);
+  }
+  async executeByTag(promptId, tag, options) {
+    return this.execute(promptId, { ...options, tag });
+  }
+  async executeByVersion(promptId, version, options) {
+    return this.execute(promptId, { ...options, version });
+  }
   /**
-   * Execute a prompt with 'latest' tag
-   *
-   * @param promptId - The prompt ID
-   * @param options - Execution options including provider, model and variables
-   * @returns The execution response
-   *
-   * @example
-   * ```ts
-   * const result = await client.prompts.execute('prm_abc123', {
-   *   provider: 'openai',
-   *   model: 'gpt-4o',
-   *   variables: { topic: 'TypeScript' },
-   * });
-   *
-   * if (result.type === 'message') {
-   *   console.log(result.content);
-   * }
-   *
-   * // Image generation
-   * const imageResult = await client.prompts.execute('prm_image123', {
-   *   provider: 'google',
-   *   model: 'gemini-2.0-flash-exp',
-   *   variables: { style: 'modern' },
-   * });
-   *
-   * if (imageResult.type === 'image') {
-   *   console.log('Generated images:', imageResult.files);
-   * }
-   * ```
+   * Execute raw request without typed response
+   * @throws {ExecutionSynovaError} If LLM returns an error
    */
-  async execute(promptId, options) {
+  async executeRaw(promptId, options) {
     const body = {
       provider: options.provider,
       model: options.model
@@ -370,79 +818,60 @@ var PromptsResource = class {
     if (options.metadata !== void 0) body.metadata = options.metadata;
     if (options.parameters !== void 0) body.parameters = options.parameters;
     if (options.responseSchema !== void 0) body.responseSchema = options.responseSchema;
-    return this.http.request({
+    if (options.sessionId !== void 0) body.sessionId = options.sessionId;
+    const response = await this.http.request({
       method: "POST",
       path: `/api/v1/prompts/${promptId}/run`,
       body
     });
+    if (response.type === "error" && response.error) {
+      throw new ExecutionSynovaError(response.error);
+    }
+    return response;
   }
   /**
-   * Execute a prompt by tag
-   *
-   * @param promptId - The prompt ID
-   * @param tag - The tag (e.g., 'latest', 'production', 'staging')
-   * @param options - Execution options
-   * @returns The execution response
-   *
-   * @example
-   * ```ts
-   * const result = await client.prompts.executeByTag('prm_abc123', 'production', {
-   *   provider: 'openai',
-   *   model: 'gpt-4o',
-   *   variables: { topic: 'TypeScript' },
-   * });
-   * ```
+   * Execute with typed response class
    */
-  async executeByTag(promptId, tag, options) {
-    return this.http.request({
-      method: "POST",
-      path: `/api/v1/prompts/${promptId}/run`,
-      body: {
-        tag,
-        provider: options.provider,
-        model: options.model,
-        apiKey: options.apiKey,
-        azureEndpoint: options.azureEndpoint,
-        variables: options.variables,
-        messages: options.messages,
-        metadata: options.metadata,
-        parameters: options.parameters
-      }
+  async executeTyped(promptId, options) {
+    const { responseClass, validate = true, ...executeOptions } = options;
+    const responseSchema = ClassSchema.generate(responseClass);
+    const response = await this.executeRaw(promptId, {
+      ...executeOptions,
+      responseSchema
     });
+    const object = response.object;
+    if (validate) {
+      await this.validateObject(object, responseClass);
+    }
+    return object;
   }
   /**
-   * Execute a prompt by version
-   *
-   * @param promptId - The prompt ID
-   * @param version - The semantic version (e.g., '1.0.0', '2.1.0')
-   * @param options - Execution options
-   * @returns The execution response
-   *
-   * @example
-   * ```ts
-   * const result = await client.prompts.executeByVersion('prm_abc123', '1.2.0', {
-   *   provider: 'openai',
-   *   model: 'gpt-4o',
-   *   variables: { topic: 'TypeScript' },
-   * });
-   * ```
+   * Validate object using class-validator
    */
-  async executeByVersion(promptId, version, options) {
-    return this.http.request({
-      method: "POST",
-      path: `/api/v1/prompts/${promptId}/run`,
-      body: {
-        version,
-        provider: options.provider,
-        model: options.model,
-        apiKey: options.apiKey,
-        azureEndpoint: options.azureEndpoint,
-        variables: options.variables,
-        messages: options.messages,
-        metadata: options.metadata,
-        parameters: options.parameters
+  async validateObject(object, responseClass) {
+    try {
+      const { plainToInstance } = __require("class-transformer");
+      const { validate } = __require("class-validator");
+      const instance = plainToInstance(responseClass, object);
+      const errors = await validate(instance);
+      if (errors.length > 0) {
+        const violations = errors.map(
+          (error) => ({
+            property: error.property,
+            constraints: error.constraints || {},
+            value: error.value
+          })
+        );
+        throw new ValidationSynovaError(violations);
       }
-    });
+    } catch (error) {
+      if (error instanceof ValidationSynovaError) {
+        throw error;
+      }
+      console.warn(
+        "[Synova SDK] Validation skipped: class-validator or class-transformer not installed. Install them with: npm install class-validator class-transformer"
+      );
+    }
   }
 };
 
@@ -574,6 +1003,137 @@ var FilesResource = class {
   }
 };
 
+// src/resources/spans.ts
+var SpansResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new span within a trace
+   *
+   * @param traceId - The trace ID to create span in
+   * @param options - Span creation options
+   * @returns Created span
+   */
+  async create(traceId, options) {
+    const body = {
+      type: options.type
+    };
+    if (options.parentSpanId !== void 0) body.parentSpanId = options.parentSpanId;
+    if (options.name !== void 0) body.name = options.name;
+    if (options.input !== void 0) body.input = options.input;
+    if (options.toolName !== void 0) body.toolName = options.toolName;
+    if (options.toolArguments !== void 0) body.toolArguments = options.toolArguments;
+    if (options.metadata !== void 0) body.metadata = options.metadata;
+    return this.http.request({
+      method: "POST",
+      path: `/api/v1/traces/${traceId}/spans`,
+      body
+    });
+  }
+  /**
+   * End/complete a span
+   *
+   * @param spanId - The span ID to end
+   * @param options - Span end options
+   * @returns Updated span
+   */
+  async end(spanId, options) {
+    const body = {};
+    if (options?.status !== void 0) body.status = options.status;
+    if (options?.level !== void 0) body.level = options.level;
+    if (options?.statusMessage !== void 0) body.statusMessage = options.statusMessage;
+    if (options?.output !== void 0) body.output = options.output;
+    if (options?.toolResult !== void 0) body.toolResult = options.toolResult;
+    if (options?.durationMs !== void 0) body.durationMs = options.durationMs;
+    return this.http.request({
+      method: "PATCH",
+      path: `/api/v1/spans/${spanId}`,
+      body
+    });
+  }
+  /**
+   * Wrap an async function with automatic span tracking
+   *
+   * @param options - Span options (traceId, type, name, etc.)
+   * @param input - Input data to record in span
+   * @param fn - Async function to execute
+   * @returns Result of the function
+   *
+   * @example
+   * ```ts
+   * const result = await client.spans.wrap(
+   *   { traceId: 'trc_123', type: 'retriever', name: 'vector_search' },
+   *   { query: 'how to...', topK: 5 },
+   *   async () => vectorDb.search(query),
+   * );
+   * ```
+   */
+  async wrap(options, input, fn) {
+    const span = await this.create(options.traceId, {
+      type: options.type,
+      name: options.name,
+      parentSpanId: options.parentSpanId,
+      input,
+      metadata: options.metadata
+    });
+    try {
+      const result = await fn();
+      await this.end(span.id, {
+        status: "completed",
+        output: result
+      });
+      return result;
+    } catch (error) {
+      await this.end(span.id, {
+        status: "error",
+        statusMessage: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  /**
+   * Wrap a tool function with automatic span tracking
+   *
+   * @param options - Tool span options (traceId, toolName, etc.)
+   * @param args - Tool arguments to record
+   * @param fn - Tool function to execute
+   * @returns Result of the tool
+   *
+   * @example
+   * ```ts
+   * const weather = await client.spans.wrapTool(
+   *   { traceId: 'trc_123', toolName: 'fetch_weather', parentSpanId: 'spn_abc' },
+   *   { city: 'NYC' },
+   *   async (args) => fetchWeather(args.city),
+   * );
+   * ```
+   */
+  async wrapTool(options, args, fn) {
+    const span = await this.create(options.traceId, {
+      type: "tool",
+      toolName: options.toolName,
+      toolArguments: args,
+      parentSpanId: options.parentSpanId,
+      metadata: options.metadata
+    });
+    try {
+      const result = await fn(args);
+      await this.end(span.id, {
+        status: "completed",
+        toolResult: result
+      });
+      return result;
+    } catch (error) {
+      await this.end(span.id, {
+        status: "error",
+        statusMessage: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.synova.cloud";
 var DEFAULT_TIMEOUT = 3e4;
@@ -594,6 +1154,7 @@ var SynovaCloudSdk = class {
   prompts;
   models;
   files;
+  spans;
   http;
   /**
    * Create a new Synova Cloud SDK client
@@ -622,9 +1183,10 @@ var SynovaCloudSdk = class {
     this.prompts = new PromptsResource(this.http);
     this.models = new ModelsResource(this.http);
     this.files = new FilesResource(this.http);
+    this.spans = new SpansResource(this.http);
   }
 };
 
-export { ApiSynovaError, AuthSynovaError, NetworkSynovaError, NotFoundSynovaError, RateLimitSynovaError, ServerSynovaError, SynovaCloudSdk, SynovaError, TimeoutSynovaError };
+export { ApiSynovaError, ArrayItems, AuthSynovaError, ClassSchema, Default, Description, Example, ExclusiveMax, ExclusiveMin, ExecutionSynovaError, Format, MultipleOf, NetworkSynovaError, NotFoundSynovaError, Nullable, RateLimitSynovaError, SCHEMA_METADATA_KEYS, SchemaEnum, SchemaMax, SchemaMaxItems, SchemaMaxLength, SchemaMin, SchemaMinItems, SchemaMinLength, SchemaPattern, SchemaUniqueItems, ServerSynovaError, SynovaCloudSdk, SynovaError, TimeoutSynovaError, ValidationSynovaError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map