@synova-cloud/sdk 1.7.0 → 1.8.0

package/dist/index.d.cts

@@ -178,6 +178,8 @@ interface ISynovaExecuteOptions {
     parameters?: Record<string, unknown>;
     /** JSON Schema for structured output */
     responseSchema?: IJsonSchema;
+    /** Session ID for trace grouping (enables multi-call trace view in observability) */
+    sessionId?: string;
 }
 interface ISynovaExecutionUsage {
     /** Usage type: 'tokens' for LLM, 'images' for image generation, 'time' for time-based billing */
@@ -210,8 +212,10 @@ interface ISynovaExecutionErrorDetails {
     promptId?: string;
     /** Prompt version (if execution was via prompt) */
     promptVersion?: string;
-    /** Execution log ID for debugging */
+    /** @deprecated Use spanDataId instead */
     executionLogId?: string;
+    /** SpanData ID for debugging */
+    spanDataId?: string;
     /** Input tokens count (for CONTEXT_TOO_LONG errors) */
     inputTokens?: number;
     /** Model context window limit (for CONTEXT_TOO_LONG errors) */
@@ -260,6 +264,14 @@ interface ISynovaExecuteResponse {
     error?: ISynovaExecutionError;
     /** Execution usage statistics (tokens, images, or time-based) */
     executionUsage?: ISynovaExecutionUsage;
+    /** @deprecated Use spanDataId instead */
+    executionId?: string;
+    /** SpanData ID (contains execution details: messages, response, usage) */
+    spanDataId?: string;
+    /** Trace ID (for observability - grouping multiple calls) */
+    traceId?: string;
+    /** Span ID (for observability - individual call within trace) */
+    spanId?: string;
 }
 interface ISynovaModelCapabilities {
     text_generation?: boolean;
@@ -334,6 +346,81 @@ interface ISynovaUploadOptions {
     /** Project ID to associate files with */
     projectId: string;
 }
+type TSynovaSpanType = 'generation' | 'tool' | 'retriever' | 'embedding' | 'custom';
+type TSynovaSpanStatus = 'pending' | 'completed' | 'error';
+type TSynovaSpanLevel = 'default' | 'debug' | 'warning' | 'error';
+interface ISynovaCreateSpanOptions {
+    /** Span type */
+    type: TSynovaSpanType;
+    /** Parent span ID (for nested spans) */
+    parentSpanId?: string;
+    /** Span name (defaults to toolName for tool spans) */
+    name?: string;
+    /** Input data (for custom/retriever/embedding spans) */
+    input?: unknown;
+    /** Tool name (for tool spans) */
+    toolName?: string;
+    /** Tool arguments (for tool spans) */
+    toolArguments?: Record<string, unknown>;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+interface ISynovaEndSpanOptions {
+    /** Span completion status */
+    status?: TSynovaSpanStatus;
+    /** Span level (for filtering/highlighting) */
+    level?: TSynovaSpanLevel;
+    /** Status message (e.g., error message) */
+    statusMessage?: string;
+    /** Output data (for custom/retriever/embedding spans) */
+    output?: unknown;
+    /** Tool execution result (for tool spans) */
+    toolResult?: unknown;
+    /** Duration in milliseconds (auto-calculated if not provided) */
+    durationMs?: number;
+}
+interface ISynovaSpanData {
+    id: string;
+    type: TSynovaSpanType;
+    toolName?: string;
+    toolArguments?: unknown;
+    toolResult?: unknown;
+    input?: unknown;
+    output?: unknown;
+    messages?: ISynovaMessage[];
+    response?: {
+        type: TSynovaResponseType;
+        content?: string;
+        object?: unknown;
+        toolCalls?: ISynovaToolCall[];
+    };
+    usage?: ISynovaExecutionUsage;
+    provider?: string;
+    model?: string;
+    executionTimeMs?: number;
+    errorMessage?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+}
+interface ISynovaSpan {
+    id: string;
+    traceId: string;
+    parentSpanId?: string;
+    type: TSynovaSpanType;
+    name?: string;
+    status: TSynovaSpanStatus;
+    level: TSynovaSpanLevel;
+    statusMessage?: string;
+    startTime: string;
+    endTime?: string;
+    durationMs?: number;
+    provider?: string;
+    model?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+    /** SpanData (included when fetching span details) */
+    spanData?: ISynovaSpanData;
+}
 interface IApiErrorResponse {
     code: string;
     httpCode: number;
@@ -361,7 +448,7 @@ interface IHttpClientConfig {
     logger: ISynovaLogger;
 }
 interface IRequestOptions {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     path: string;
     body?: unknown;
     query?: Record<string, string | undefined>;
@@ -556,6 +643,120 @@ declare class FilesResource {
     upload(files: (File | Blob)[], options: ISynovaUploadOptions): Promise<ISynovaUploadResponse>;
 }
 
+/**
+ * Options for wrapping a function with span tracking
+ */
+interface ISynovaWrapOptions {
+    /** Trace ID */
+    traceId: string;
+    /** Span type */
+    type: TSynovaSpanType;
+    /** Span name */
+    name?: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for wrapping a tool function
+ */
+interface ISynovaWrapToolOptions {
+    /** Trace ID */
+    traceId: string;
+    /** Tool name */
+    toolName: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Spans resource for observability
+ *
+ * @example
+ * ```ts
+ * // Manual: create and end span
+ * const span = await client.spans.create('trc_123', {
+ *   type: 'tool',
+ *   toolName: 'fetch_weather',
+ *   toolArguments: { city: 'NYC' },
+ * });
+ * const result = await fetchWeather('NYC');
+ * await client.spans.end(span.id, { status: 'completed', toolResult: result });
+ *
+ * // Wrapper: automatic span lifecycle
+ * const weather = await client.spans.wrapTool(
+ *   { traceId: 'trc_123', toolName: 'fetch_weather' },
+ *   { city: 'NYC' },
+ *   (args) => fetchWeather(args.city),
+ * );
+ *
+ * // Generic wrapper for custom spans
+ * const result = await client.spans.wrap(
+ *   { traceId: 'trc_123', type: 'custom', name: 'validate' },
+ *   { input: data },
+ *   async () => validateData(data),
+ * );
+ * ```
+ */
+declare class SpansResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new span within a trace
+     *
+     * @param traceId - The trace ID to create span in
+     * @param options - Span creation options
+     * @returns Created span
+     */
+    create(traceId: string, options: ISynovaCreateSpanOptions): Promise<ISynovaSpan>;
+    /**
+     * End/complete a span
+     *
+     * @param spanId - The span ID to end
+     * @param options - Span end options
+     * @returns Updated span
+     */
+    end(spanId: string, options?: ISynovaEndSpanOptions): Promise<ISynovaSpan>;
+    /**
+     * 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),
+     * );
+     * ```
+     */
+    wrap<T>(options: ISynovaWrapOptions, input: unknown, fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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),
+     * );
+     * ```
+     */
+    wrapTool<TArgs extends Record<string, unknown>, TResult>(options: ISynovaWrapToolOptions, args: TArgs, fn: (args: TArgs) => Promise<TResult>): Promise<TResult>;
+}
+
 /**
  * Synova Cloud SDK client
  *
@@ -605,6 +806,7 @@ declare class SynovaCloudSdk {
     readonly prompts: PromptsResource;
     readonly models: ModelsResource;
     readonly files: FilesResource;
+    readonly spans: SpansResource;
     private readonly http;
     /**
      * Create a new Synova Cloud SDK client
@@ -1007,4 +1209,4 @@ declare function SchemaUniqueItems(): PropertyDecorator;
  */
 declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
 
-export { ApiSynovaError, ArrayItems, AuthSynovaError, ClassSchema, Default, Description, Example, ExclusiveMax, ExclusiveMin, ExecutionSynovaError, Format, type IGenerateSchemaOptions, type IJsonSchema, type ISynovaConfig, type ISynovaExecuteOptions, type ISynovaExecuteResponse, type ISynovaExecuteTypedOptions, type ISynovaExecutionError, type ISynovaExecutionErrorDetails, type ISynovaExecutionUsage, type ISynovaFileAttachment, type ISynovaFileThumbnails, type ISynovaGetPromptOptions, type ISynovaListModelsOptions, type ISynovaLogger, type ISynovaMessage, type ISynovaModel, type ISynovaModelCapabilities, type ISynovaModelLimits, type ISynovaModelPricing, type ISynovaModelsResponse, type ISynovaPrompt, type ISynovaPromptVariable, type ISynovaProvider, type ISynovaProviderResponse, type ISynovaRetryConfig, type ISynovaToolCall, type ISynovaToolResult, type ISynovaUploadOptions, type ISynovaUploadResponse, type ISynovaUploadedFile, type IValidationViolation, MultipleOf, NetworkSynovaError, NotFoundSynovaError, Nullable, RateLimitSynovaError, SCHEMA_METADATA_KEYS, SchemaEnum, SchemaMax, SchemaMaxItems, SchemaMaxLength, SchemaMin, SchemaMinItems, SchemaMinLength, SchemaPattern, SchemaUniqueItems, ServerSynovaError, SynovaCloudSdk, SynovaError, type TClassConstructor, type TJsonSchemaFormat, type TJsonSchemaType, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, type TSynovaUsageType, TimeoutSynovaError, ValidationSynovaError };
+export { ApiSynovaError, ArrayItems, AuthSynovaError, ClassSchema, Default, Description, Example, ExclusiveMax, ExclusiveMin, ExecutionSynovaError, Format, type IGenerateSchemaOptions, type IJsonSchema, type ISynovaConfig, type ISynovaCreateSpanOptions, type ISynovaEndSpanOptions, type ISynovaExecuteOptions, type ISynovaExecuteResponse, type ISynovaExecuteTypedOptions, type ISynovaExecutionError, type ISynovaExecutionErrorDetails, type ISynovaExecutionUsage, type ISynovaFileAttachment, type ISynovaFileThumbnails, type ISynovaGetPromptOptions, type ISynovaListModelsOptions, type ISynovaLogger, type ISynovaMessage, type ISynovaModel, type ISynovaModelCapabilities, type ISynovaModelLimits, type ISynovaModelPricing, type ISynovaModelsResponse, type ISynovaPrompt, type ISynovaPromptVariable, type ISynovaProvider, type ISynovaProviderResponse, type ISynovaRetryConfig, type ISynovaSpan, type ISynovaSpanData, type ISynovaToolCall, type ISynovaToolResult, type ISynovaUploadOptions, type ISynovaUploadResponse, type ISynovaUploadedFile, type ISynovaWrapOptions, type ISynovaWrapToolOptions, type IValidationViolation, MultipleOf, NetworkSynovaError, NotFoundSynovaError, Nullable, RateLimitSynovaError, SCHEMA_METADATA_KEYS, SchemaEnum, SchemaMax, SchemaMaxItems, SchemaMaxLength, SchemaMin, SchemaMinItems, SchemaMinLength, SchemaPattern, SchemaUniqueItems, ServerSynovaError, SynovaCloudSdk, SynovaError, type TClassConstructor, type TJsonSchemaFormat, type TJsonSchemaType, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, type TSynovaSpanLevel, type TSynovaSpanStatus, type TSynovaSpanType, type TSynovaUsageType, TimeoutSynovaError, ValidationSynovaError };

package/dist/index.d.ts

@@ -178,6 +178,8 @@ interface ISynovaExecuteOptions {
     parameters?: Record<string, unknown>;
     /** JSON Schema for structured output */
     responseSchema?: IJsonSchema;
+    /** Session ID for trace grouping (enables multi-call trace view in observability) */
+    sessionId?: string;
 }
 interface ISynovaExecutionUsage {
     /** Usage type: 'tokens' for LLM, 'images' for image generation, 'time' for time-based billing */
@@ -210,8 +212,10 @@ interface ISynovaExecutionErrorDetails {
     promptId?: string;
     /** Prompt version (if execution was via prompt) */
     promptVersion?: string;
-    /** Execution log ID for debugging */
+    /** @deprecated Use spanDataId instead */
     executionLogId?: string;
+    /** SpanData ID for debugging */
+    spanDataId?: string;
     /** Input tokens count (for CONTEXT_TOO_LONG errors) */
     inputTokens?: number;
     /** Model context window limit (for CONTEXT_TOO_LONG errors) */
@@ -260,6 +264,14 @@ interface ISynovaExecuteResponse {
     error?: ISynovaExecutionError;
     /** Execution usage statistics (tokens, images, or time-based) */
     executionUsage?: ISynovaExecutionUsage;
+    /** @deprecated Use spanDataId instead */
+    executionId?: string;
+    /** SpanData ID (contains execution details: messages, response, usage) */
+    spanDataId?: string;
+    /** Trace ID (for observability - grouping multiple calls) */
+    traceId?: string;
+    /** Span ID (for observability - individual call within trace) */
+    spanId?: string;
 }
 interface ISynovaModelCapabilities {
     text_generation?: boolean;
@@ -334,6 +346,81 @@ interface ISynovaUploadOptions {
     /** Project ID to associate files with */
     projectId: string;
 }
+type TSynovaSpanType = 'generation' | 'tool' | 'retriever' | 'embedding' | 'custom';
+type TSynovaSpanStatus = 'pending' | 'completed' | 'error';
+type TSynovaSpanLevel = 'default' | 'debug' | 'warning' | 'error';
+interface ISynovaCreateSpanOptions {
+    /** Span type */
+    type: TSynovaSpanType;
+    /** Parent span ID (for nested spans) */
+    parentSpanId?: string;
+    /** Span name (defaults to toolName for tool spans) */
+    name?: string;
+    /** Input data (for custom/retriever/embedding spans) */
+    input?: unknown;
+    /** Tool name (for tool spans) */
+    toolName?: string;
+    /** Tool arguments (for tool spans) */
+    toolArguments?: Record<string, unknown>;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+interface ISynovaEndSpanOptions {
+    /** Span completion status */
+    status?: TSynovaSpanStatus;
+    /** Span level (for filtering/highlighting) */
+    level?: TSynovaSpanLevel;
+    /** Status message (e.g., error message) */
+    statusMessage?: string;
+    /** Output data (for custom/retriever/embedding spans) */
+    output?: unknown;
+    /** Tool execution result (for tool spans) */
+    toolResult?: unknown;
+    /** Duration in milliseconds (auto-calculated if not provided) */
+    durationMs?: number;
+}
+interface ISynovaSpanData {
+    id: string;
+    type: TSynovaSpanType;
+    toolName?: string;
+    toolArguments?: unknown;
+    toolResult?: unknown;
+    input?: unknown;
+    output?: unknown;
+    messages?: ISynovaMessage[];
+    response?: {
+        type: TSynovaResponseType;
+        content?: string;
+        object?: unknown;
+        toolCalls?: ISynovaToolCall[];
+    };
+    usage?: ISynovaExecutionUsage;
+    provider?: string;
+    model?: string;
+    executionTimeMs?: number;
+    errorMessage?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+}
+interface ISynovaSpan {
+    id: string;
+    traceId: string;
+    parentSpanId?: string;
+    type: TSynovaSpanType;
+    name?: string;
+    status: TSynovaSpanStatus;
+    level: TSynovaSpanLevel;
+    statusMessage?: string;
+    startTime: string;
+    endTime?: string;
+    durationMs?: number;
+    provider?: string;
+    model?: string;
+    metadata?: Record<string, string>;
+    createdAt: string;
+    /** SpanData (included when fetching span details) */
+    spanData?: ISynovaSpanData;
+}
 interface IApiErrorResponse {
     code: string;
     httpCode: number;
@@ -361,7 +448,7 @@ interface IHttpClientConfig {
     logger: ISynovaLogger;
 }
 interface IRequestOptions {
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     path: string;
     body?: unknown;
     query?: Record<string, string | undefined>;
@@ -556,6 +643,120 @@ declare class FilesResource {
     upload(files: (File | Blob)[], options: ISynovaUploadOptions): Promise<ISynovaUploadResponse>;
 }
 
+/**
+ * Options for wrapping a function with span tracking
+ */
+interface ISynovaWrapOptions {
+    /** Trace ID */
+    traceId: string;
+    /** Span type */
+    type: TSynovaSpanType;
+    /** Span name */
+    name?: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for wrapping a tool function
+ */
+interface ISynovaWrapToolOptions {
+    /** Trace ID */
+    traceId: string;
+    /** Tool name */
+    toolName: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Spans resource for observability
+ *
+ * @example
+ * ```ts
+ * // Manual: create and end span
+ * const span = await client.spans.create('trc_123', {
+ *   type: 'tool',
+ *   toolName: 'fetch_weather',
+ *   toolArguments: { city: 'NYC' },
+ * });
+ * const result = await fetchWeather('NYC');
+ * await client.spans.end(span.id, { status: 'completed', toolResult: result });
+ *
+ * // Wrapper: automatic span lifecycle
+ * const weather = await client.spans.wrapTool(
+ *   { traceId: 'trc_123', toolName: 'fetch_weather' },
+ *   { city: 'NYC' },
+ *   (args) => fetchWeather(args.city),
+ * );
+ *
+ * // Generic wrapper for custom spans
+ * const result = await client.spans.wrap(
+ *   { traceId: 'trc_123', type: 'custom', name: 'validate' },
+ *   { input: data },
+ *   async () => validateData(data),
+ * );
+ * ```
+ */
+declare class SpansResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new span within a trace
+     *
+     * @param traceId - The trace ID to create span in
+     * @param options - Span creation options
+     * @returns Created span
+     */
+    create(traceId: string, options: ISynovaCreateSpanOptions): Promise<ISynovaSpan>;
+    /**
+     * End/complete a span
+     *
+     * @param spanId - The span ID to end
+     * @param options - Span end options
+     * @returns Updated span
+     */
+    end(spanId: string, options?: ISynovaEndSpanOptions): Promise<ISynovaSpan>;
+    /**
+     * 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),
+     * );
+     * ```
+     */
+    wrap<T>(options: ISynovaWrapOptions, input: unknown, fn: () => Promise<T>): Promise<T>;
+    /**
+     * 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),
+     * );
+     * ```
+     */
+    wrapTool<TArgs extends Record<string, unknown>, TResult>(options: ISynovaWrapToolOptions, args: TArgs, fn: (args: TArgs) => Promise<TResult>): Promise<TResult>;
+}
+
 /**
  * Synova Cloud SDK client
  *
@@ -605,6 +806,7 @@ declare class SynovaCloudSdk {
     readonly prompts: PromptsResource;
     readonly models: ModelsResource;
     readonly files: FilesResource;
+    readonly spans: SpansResource;
     private readonly http;
     /**
      * Create a new Synova Cloud SDK client
@@ -1007,4 +1209,4 @@ declare function SchemaUniqueItems(): PropertyDecorator;
  */
 declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
 
-export { ApiSynovaError, ArrayItems, AuthSynovaError, ClassSchema, Default, Description, Example, ExclusiveMax, ExclusiveMin, ExecutionSynovaError, Format, type IGenerateSchemaOptions, type IJsonSchema, type ISynovaConfig, type ISynovaExecuteOptions, type ISynovaExecuteResponse, type ISynovaExecuteTypedOptions, type ISynovaExecutionError, type ISynovaExecutionErrorDetails, type ISynovaExecutionUsage, type ISynovaFileAttachment, type ISynovaFileThumbnails, type ISynovaGetPromptOptions, type ISynovaListModelsOptions, type ISynovaLogger, type ISynovaMessage, type ISynovaModel, type ISynovaModelCapabilities, type ISynovaModelLimits, type ISynovaModelPricing, type ISynovaModelsResponse, type ISynovaPrompt, type ISynovaPromptVariable, type ISynovaProvider, type ISynovaProviderResponse, type ISynovaRetryConfig, type ISynovaToolCall, type ISynovaToolResult, type ISynovaUploadOptions, type ISynovaUploadResponse, type ISynovaUploadedFile, type IValidationViolation, MultipleOf, NetworkSynovaError, NotFoundSynovaError, Nullable, RateLimitSynovaError, SCHEMA_METADATA_KEYS, SchemaEnum, SchemaMax, SchemaMaxItems, SchemaMaxLength, SchemaMin, SchemaMinItems, SchemaMinLength, SchemaPattern, SchemaUniqueItems, ServerSynovaError, SynovaCloudSdk, SynovaError, type TClassConstructor, type TJsonSchemaFormat, type TJsonSchemaType, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, type TSynovaUsageType, TimeoutSynovaError, ValidationSynovaError };
+export { ApiSynovaError, ArrayItems, AuthSynovaError, ClassSchema, Default, Description, Example, ExclusiveMax, ExclusiveMin, ExecutionSynovaError, Format, type IGenerateSchemaOptions, type IJsonSchema, type ISynovaConfig, type ISynovaCreateSpanOptions, type ISynovaEndSpanOptions, type ISynovaExecuteOptions, type ISynovaExecuteResponse, type ISynovaExecuteTypedOptions, type ISynovaExecutionError, type ISynovaExecutionErrorDetails, type ISynovaExecutionUsage, type ISynovaFileAttachment, type ISynovaFileThumbnails, type ISynovaGetPromptOptions, type ISynovaListModelsOptions, type ISynovaLogger, type ISynovaMessage, type ISynovaModel, type ISynovaModelCapabilities, type ISynovaModelLimits, type ISynovaModelPricing, type ISynovaModelsResponse, type ISynovaPrompt, type ISynovaPromptVariable, type ISynovaProvider, type ISynovaProviderResponse, type ISynovaRetryConfig, type ISynovaSpan, type ISynovaSpanData, type ISynovaToolCall, type ISynovaToolResult, type ISynovaUploadOptions, type ISynovaUploadResponse, type ISynovaUploadedFile, type ISynovaWrapOptions, type ISynovaWrapToolOptions, type IValidationViolation, MultipleOf, NetworkSynovaError, NotFoundSynovaError, Nullable, RateLimitSynovaError, SCHEMA_METADATA_KEYS, SchemaEnum, SchemaMax, SchemaMaxItems, SchemaMaxLength, SchemaMin, SchemaMinItems, SchemaMinLength, SchemaPattern, SchemaUniqueItems, ServerSynovaError, SynovaCloudSdk, SynovaError, type TClassConstructor, type TJsonSchemaFormat, type TJsonSchemaType, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, type TSynovaSpanLevel, type TSynovaSpanStatus, type TSynovaSpanType, type TSynovaUsageType, TimeoutSynovaError, ValidationSynovaError };

package/dist/index.js

@@ -105,7 +105,7 @@ var ValidationSynovaError = class extends SynovaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "1.7.0" ;
+var SDK_VERSION = "1.8.0" ;
 
 // src/utils/http.ts
 var HttpClient = class {
@@ -818,6 +818,7 @@ 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;
+    if (options.sessionId !== void 0) body.sessionId = options.sessionId;
     const response = await this.http.request({
       method: "POST",
       path: `/api/v1/prompts/${promptId}/run`,
@@ -1002,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;
@@ -1022,6 +1154,7 @@ var SynovaCloudSdk = class {
   prompts;
   models;
   files;
+  spans;
   http;
   /**
    * Create a new Synova Cloud SDK client
@@ -1050,6 +1183,7 @@ 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);
   }
 };