@synova-cloud/sdk 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -60,6 +60,7 @@ declare const SCHEMA_METADATA_KEYS: {
60
60
  readonly MIN_ITEMS: "synova:schema:minItems";
61
61
  readonly MAX_ITEMS: "synova:schema:maxItems";
62
62
  readonly UNIQUE_ITEMS: "synova:schema:uniqueItems";
63
+ readonly ADDITIONAL_PROPERTIES: "synova:schema:additionalProperties";
63
64
  };
64
65
  /**
65
66
  * Options for schema generation
@@ -178,6 +179,8 @@ interface ISynovaExecuteOptions {
178
179
  parameters?: Record<string, unknown>;
179
180
  /** JSON Schema for structured output */
180
181
  responseSchema?: IJsonSchema;
182
+ /** Session ID for trace grouping (enables multi-call trace view in observability) */
183
+ sessionId?: string;
181
184
  }
182
185
  interface ISynovaExecutionUsage {
183
186
  /** Usage type: 'tokens' for LLM, 'images' for image generation, 'time' for time-based billing */
@@ -210,8 +213,10 @@ interface ISynovaExecutionErrorDetails {
210
213
  promptId?: string;
211
214
  /** Prompt version (if execution was via prompt) */
212
215
  promptVersion?: string;
213
- /** Execution log ID for debugging */
216
+ /** @deprecated Use spanDataId instead */
214
217
  executionLogId?: string;
218
+ /** SpanData ID for debugging */
219
+ spanDataId?: string;
215
220
  /** Input tokens count (for CONTEXT_TOO_LONG errors) */
216
221
  inputTokens?: number;
217
222
  /** Model context window limit (for CONTEXT_TOO_LONG errors) */
@@ -260,6 +265,14 @@ interface ISynovaExecuteResponse {
260
265
  error?: ISynovaExecutionError;
261
266
  /** Execution usage statistics (tokens, images, or time-based) */
262
267
  executionUsage?: ISynovaExecutionUsage;
268
+ /** @deprecated Use spanDataId instead */
269
+ executionId?: string;
270
+ /** SpanData ID (contains execution details: messages, response, usage) */
271
+ spanDataId?: string;
272
+ /** Trace ID (for observability - grouping multiple calls) */
273
+ traceId?: string;
274
+ /** Span ID (for observability - individual call within trace) */
275
+ spanId?: string;
263
276
  }
264
277
  interface ISynovaModelCapabilities {
265
278
  text_generation?: boolean;
@@ -334,6 +347,81 @@ interface ISynovaUploadOptions {
334
347
  /** Project ID to associate files with */
335
348
  projectId: string;
336
349
  }
350
+ type TSynovaSpanType = 'generation' | 'tool' | 'retriever' | 'embedding' | 'custom';
351
+ type TSynovaSpanStatus = 'pending' | 'completed' | 'error';
352
+ type TSynovaSpanLevel = 'default' | 'debug' | 'warning' | 'error';
353
+ interface ISynovaCreateSpanOptions {
354
+ /** Span type */
355
+ type: TSynovaSpanType;
356
+ /** Parent span ID (for nested spans) */
357
+ parentSpanId?: string;
358
+ /** Span name (defaults to toolName for tool spans) */
359
+ name?: string;
360
+ /** Input data (for custom/retriever/embedding spans) */
361
+ input?: unknown;
362
+ /** Tool name (for tool spans) */
363
+ toolName?: string;
364
+ /** Tool arguments (for tool spans) */
365
+ toolArguments?: Record<string, unknown>;
366
+ /** Custom metadata */
367
+ metadata?: Record<string, string>;
368
+ }
369
+ interface ISynovaEndSpanOptions {
370
+ /** Span completion status */
371
+ status?: TSynovaSpanStatus;
372
+ /** Span level (for filtering/highlighting) */
373
+ level?: TSynovaSpanLevel;
374
+ /** Status message (e.g., error message) */
375
+ statusMessage?: string;
376
+ /** Output data (for custom/retriever/embedding spans) */
377
+ output?: unknown;
378
+ /** Tool execution result (for tool spans) */
379
+ toolResult?: unknown;
380
+ /** Duration in milliseconds (auto-calculated if not provided) */
381
+ durationMs?: number;
382
+ }
383
+ interface ISynovaSpanData {
384
+ id: string;
385
+ type: TSynovaSpanType;
386
+ toolName?: string;
387
+ toolArguments?: unknown;
388
+ toolResult?: unknown;
389
+ input?: unknown;
390
+ output?: unknown;
391
+ messages?: ISynovaMessage[];
392
+ response?: {
393
+ type: TSynovaResponseType;
394
+ content?: string;
395
+ object?: unknown;
396
+ toolCalls?: ISynovaToolCall[];
397
+ };
398
+ usage?: ISynovaExecutionUsage;
399
+ provider?: string;
400
+ model?: string;
401
+ executionTimeMs?: number;
402
+ errorMessage?: string;
403
+ metadata?: Record<string, string>;
404
+ createdAt: string;
405
+ }
406
+ interface ISynovaSpan {
407
+ id: string;
408
+ traceId: string;
409
+ parentSpanId?: string;
410
+ type: TSynovaSpanType;
411
+ name?: string;
412
+ status: TSynovaSpanStatus;
413
+ level: TSynovaSpanLevel;
414
+ statusMessage?: string;
415
+ startTime: string;
416
+ endTime?: string;
417
+ durationMs?: number;
418
+ provider?: string;
419
+ model?: string;
420
+ metadata?: Record<string, string>;
421
+ createdAt: string;
422
+ /** SpanData (included when fetching span details) */
423
+ spanData?: ISynovaSpanData;
424
+ }
337
425
  interface IApiErrorResponse {
338
426
  code: string;
339
427
  httpCode: number;
@@ -361,7 +449,7 @@ interface IHttpClientConfig {
361
449
  logger: ISynovaLogger;
362
450
  }
363
451
  interface IRequestOptions {
364
- method: 'GET' | 'POST' | 'PUT' | 'DELETE';
452
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
365
453
  path: string;
366
454
  body?: unknown;
367
455
  query?: Record<string, string | undefined>;
@@ -556,6 +644,120 @@ declare class FilesResource {
556
644
  upload(files: (File | Blob)[], options: ISynovaUploadOptions): Promise<ISynovaUploadResponse>;
557
645
  }
558
646
 
647
+ /**
648
+ * Options for wrapping a function with span tracking
649
+ */
650
+ interface ISynovaWrapOptions {
651
+ /** Trace ID */
652
+ traceId: string;
653
+ /** Span type */
654
+ type: TSynovaSpanType;
655
+ /** Span name */
656
+ name?: string;
657
+ /** Parent span ID */
658
+ parentSpanId?: string;
659
+ /** Custom metadata */
660
+ metadata?: Record<string, string>;
661
+ }
662
+ /**
663
+ * Options for wrapping a tool function
664
+ */
665
+ interface ISynovaWrapToolOptions {
666
+ /** Trace ID */
667
+ traceId: string;
668
+ /** Tool name */
669
+ toolName: string;
670
+ /** Parent span ID */
671
+ parentSpanId?: string;
672
+ /** Custom metadata */
673
+ metadata?: Record<string, string>;
674
+ }
675
+ /**
676
+ * Spans resource for observability
677
+ *
678
+ * @example
679
+ * ```ts
680
+ * // Manual: create and end span
681
+ * const span = await client.spans.create('trc_123', {
682
+ * type: 'tool',
683
+ * toolName: 'fetch_weather',
684
+ * toolArguments: { city: 'NYC' },
685
+ * });
686
+ * const result = await fetchWeather('NYC');
687
+ * await client.spans.end(span.id, { status: 'completed', toolResult: result });
688
+ *
689
+ * // Wrapper: automatic span lifecycle
690
+ * const weather = await client.spans.wrapTool(
691
+ * { traceId: 'trc_123', toolName: 'fetch_weather' },
692
+ * { city: 'NYC' },
693
+ * (args) => fetchWeather(args.city),
694
+ * );
695
+ *
696
+ * // Generic wrapper for custom spans
697
+ * const result = await client.spans.wrap(
698
+ * { traceId: 'trc_123', type: 'custom', name: 'validate' },
699
+ * { input: data },
700
+ * async () => validateData(data),
701
+ * );
702
+ * ```
703
+ */
704
+ declare class SpansResource {
705
+ private readonly http;
706
+ constructor(http: HttpClient);
707
+ /**
708
+ * Create a new span within a trace
709
+ *
710
+ * @param traceId - The trace ID to create span in
711
+ * @param options - Span creation options
712
+ * @returns Created span
713
+ */
714
+ create(traceId: string, options: ISynovaCreateSpanOptions): Promise<ISynovaSpan>;
715
+ /**
716
+ * End/complete a span
717
+ *
718
+ * @param spanId - The span ID to end
719
+ * @param options - Span end options
720
+ * @returns Updated span
721
+ */
722
+ end(spanId: string, options?: ISynovaEndSpanOptions): Promise<ISynovaSpan>;
723
+ /**
724
+ * Wrap an async function with automatic span tracking
725
+ *
726
+ * @param options - Span options (traceId, type, name, etc.)
727
+ * @param input - Input data to record in span
728
+ * @param fn - Async function to execute
729
+ * @returns Result of the function
730
+ *
731
+ * @example
732
+ * ```ts
733
+ * const result = await client.spans.wrap(
734
+ * { traceId: 'trc_123', type: 'retriever', name: 'vector_search' },
735
+ * { query: 'how to...', topK: 5 },
736
+ * async () => vectorDb.search(query),
737
+ * );
738
+ * ```
739
+ */
740
+ wrap<T>(options: ISynovaWrapOptions, input: unknown, fn: () => Promise<T>): Promise<T>;
741
+ /**
742
+ * Wrap a tool function with automatic span tracking
743
+ *
744
+ * @param options - Tool span options (traceId, toolName, etc.)
745
+ * @param args - Tool arguments to record
746
+ * @param fn - Tool function to execute
747
+ * @returns Result of the tool
748
+ *
749
+ * @example
750
+ * ```ts
751
+ * const weather = await client.spans.wrapTool(
752
+ * { traceId: 'trc_123', toolName: 'fetch_weather', parentSpanId: 'spn_abc' },
753
+ * { city: 'NYC' },
754
+ * async (args) => fetchWeather(args.city),
755
+ * );
756
+ * ```
757
+ */
758
+ wrapTool<TArgs extends Record<string, unknown>, TResult>(options: ISynovaWrapToolOptions, args: TArgs, fn: (args: TArgs) => Promise<TResult>): Promise<TResult>;
759
+ }
760
+
559
761
  /**
560
762
  * Synova Cloud SDK client
561
763
  *
@@ -605,6 +807,7 @@ declare class SynovaCloudSdk {
605
807
  readonly prompts: PromptsResource;
606
808
  readonly models: ModelsResource;
607
809
  readonly files: FilesResource;
810
+ readonly spans: SpansResource;
608
811
  private readonly http;
609
812
  /**
610
813
  * Create a new Synova Cloud SDK client
@@ -1007,4 +1210,4 @@ declare function SchemaUniqueItems(): PropertyDecorator;
1007
1210
  */
1008
1211
  declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
1009
1212
 
1010
- 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 };
1213
+ 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 CHANGED
@@ -60,6 +60,7 @@ declare const SCHEMA_METADATA_KEYS: {
60
60
  readonly MIN_ITEMS: "synova:schema:minItems";
61
61
  readonly MAX_ITEMS: "synova:schema:maxItems";
62
62
  readonly UNIQUE_ITEMS: "synova:schema:uniqueItems";
63
+ readonly ADDITIONAL_PROPERTIES: "synova:schema:additionalProperties";
63
64
  };
64
65
  /**
65
66
  * Options for schema generation
@@ -178,6 +179,8 @@ interface ISynovaExecuteOptions {
178
179
  parameters?: Record<string, unknown>;
179
180
  /** JSON Schema for structured output */
180
181
  responseSchema?: IJsonSchema;
182
+ /** Session ID for trace grouping (enables multi-call trace view in observability) */
183
+ sessionId?: string;
181
184
  }
182
185
  interface ISynovaExecutionUsage {
183
186
  /** Usage type: 'tokens' for LLM, 'images' for image generation, 'time' for time-based billing */
@@ -210,8 +213,10 @@ interface ISynovaExecutionErrorDetails {
210
213
  promptId?: string;
211
214
  /** Prompt version (if execution was via prompt) */
212
215
  promptVersion?: string;
213
- /** Execution log ID for debugging */
216
+ /** @deprecated Use spanDataId instead */
214
217
  executionLogId?: string;
218
+ /** SpanData ID for debugging */
219
+ spanDataId?: string;
215
220
  /** Input tokens count (for CONTEXT_TOO_LONG errors) */
216
221
  inputTokens?: number;
217
222
  /** Model context window limit (for CONTEXT_TOO_LONG errors) */
@@ -260,6 +265,14 @@ interface ISynovaExecuteResponse {
260
265
  error?: ISynovaExecutionError;
261
266
  /** Execution usage statistics (tokens, images, or time-based) */
262
267
  executionUsage?: ISynovaExecutionUsage;
268
+ /** @deprecated Use spanDataId instead */
269
+ executionId?: string;
270
+ /** SpanData ID (contains execution details: messages, response, usage) */
271
+ spanDataId?: string;
272
+ /** Trace ID (for observability - grouping multiple calls) */
273
+ traceId?: string;
274
+ /** Span ID (for observability - individual call within trace) */
275
+ spanId?: string;
263
276
  }
264
277
  interface ISynovaModelCapabilities {
265
278
  text_generation?: boolean;
@@ -334,6 +347,81 @@ interface ISynovaUploadOptions {
334
347
  /** Project ID to associate files with */
335
348
  projectId: string;
336
349
  }
350
+ type TSynovaSpanType = 'generation' | 'tool' | 'retriever' | 'embedding' | 'custom';
351
+ type TSynovaSpanStatus = 'pending' | 'completed' | 'error';
352
+ type TSynovaSpanLevel = 'default' | 'debug' | 'warning' | 'error';
353
+ interface ISynovaCreateSpanOptions {
354
+ /** Span type */
355
+ type: TSynovaSpanType;
356
+ /** Parent span ID (for nested spans) */
357
+ parentSpanId?: string;
358
+ /** Span name (defaults to toolName for tool spans) */
359
+ name?: string;
360
+ /** Input data (for custom/retriever/embedding spans) */
361
+ input?: unknown;
362
+ /** Tool name (for tool spans) */
363
+ toolName?: string;
364
+ /** Tool arguments (for tool spans) */
365
+ toolArguments?: Record<string, unknown>;
366
+ /** Custom metadata */
367
+ metadata?: Record<string, string>;
368
+ }
369
+ interface ISynovaEndSpanOptions {
370
+ /** Span completion status */
371
+ status?: TSynovaSpanStatus;
372
+ /** Span level (for filtering/highlighting) */
373
+ level?: TSynovaSpanLevel;
374
+ /** Status message (e.g., error message) */
375
+ statusMessage?: string;
376
+ /** Output data (for custom/retriever/embedding spans) */
377
+ output?: unknown;
378
+ /** Tool execution result (for tool spans) */
379
+ toolResult?: unknown;
380
+ /** Duration in milliseconds (auto-calculated if not provided) */
381
+ durationMs?: number;
382
+ }
383
+ interface ISynovaSpanData {
384
+ id: string;
385
+ type: TSynovaSpanType;
386
+ toolName?: string;
387
+ toolArguments?: unknown;
388
+ toolResult?: unknown;
389
+ input?: unknown;
390
+ output?: unknown;
391
+ messages?: ISynovaMessage[];
392
+ response?: {
393
+ type: TSynovaResponseType;
394
+ content?: string;
395
+ object?: unknown;
396
+ toolCalls?: ISynovaToolCall[];
397
+ };
398
+ usage?: ISynovaExecutionUsage;
399
+ provider?: string;
400
+ model?: string;
401
+ executionTimeMs?: number;
402
+ errorMessage?: string;
403
+ metadata?: Record<string, string>;
404
+ createdAt: string;
405
+ }
406
+ interface ISynovaSpan {
407
+ id: string;
408
+ traceId: string;
409
+ parentSpanId?: string;
410
+ type: TSynovaSpanType;
411
+ name?: string;
412
+ status: TSynovaSpanStatus;
413
+ level: TSynovaSpanLevel;
414
+ statusMessage?: string;
415
+ startTime: string;
416
+ endTime?: string;
417
+ durationMs?: number;
418
+ provider?: string;
419
+ model?: string;
420
+ metadata?: Record<string, string>;
421
+ createdAt: string;
422
+ /** SpanData (included when fetching span details) */
423
+ spanData?: ISynovaSpanData;
424
+ }
337
425
  interface IApiErrorResponse {
338
426
  code: string;
339
427
  httpCode: number;
@@ -361,7 +449,7 @@ interface IHttpClientConfig {
361
449
  logger: ISynovaLogger;
362
450
  }
363
451
  interface IRequestOptions {
364
- method: 'GET' | 'POST' | 'PUT' | 'DELETE';
452
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
365
453
  path: string;
366
454
  body?: unknown;
367
455
  query?: Record<string, string | undefined>;
@@ -556,6 +644,120 @@ declare class FilesResource {
556
644
  upload(files: (File | Blob)[], options: ISynovaUploadOptions): Promise<ISynovaUploadResponse>;
557
645
  }
558
646
 
647
+ /**
648
+ * Options for wrapping a function with span tracking
649
+ */
650
+ interface ISynovaWrapOptions {
651
+ /** Trace ID */
652
+ traceId: string;
653
+ /** Span type */
654
+ type: TSynovaSpanType;
655
+ /** Span name */
656
+ name?: string;
657
+ /** Parent span ID */
658
+ parentSpanId?: string;
659
+ /** Custom metadata */
660
+ metadata?: Record<string, string>;
661
+ }
662
+ /**
663
+ * Options for wrapping a tool function
664
+ */
665
+ interface ISynovaWrapToolOptions {
666
+ /** Trace ID */
667
+ traceId: string;
668
+ /** Tool name */
669
+ toolName: string;
670
+ /** Parent span ID */
671
+ parentSpanId?: string;
672
+ /** Custom metadata */
673
+ metadata?: Record<string, string>;
674
+ }
675
+ /**
676
+ * Spans resource for observability
677
+ *
678
+ * @example
679
+ * ```ts
680
+ * // Manual: create and end span
681
+ * const span = await client.spans.create('trc_123', {
682
+ * type: 'tool',
683
+ * toolName: 'fetch_weather',
684
+ * toolArguments: { city: 'NYC' },
685
+ * });
686
+ * const result = await fetchWeather('NYC');
687
+ * await client.spans.end(span.id, { status: 'completed', toolResult: result });
688
+ *
689
+ * // Wrapper: automatic span lifecycle
690
+ * const weather = await client.spans.wrapTool(
691
+ * { traceId: 'trc_123', toolName: 'fetch_weather' },
692
+ * { city: 'NYC' },
693
+ * (args) => fetchWeather(args.city),
694
+ * );
695
+ *
696
+ * // Generic wrapper for custom spans
697
+ * const result = await client.spans.wrap(
698
+ * { traceId: 'trc_123', type: 'custom', name: 'validate' },
699
+ * { input: data },
700
+ * async () => validateData(data),
701
+ * );
702
+ * ```
703
+ */
704
+ declare class SpansResource {
705
+ private readonly http;
706
+ constructor(http: HttpClient);
707
+ /**
708
+ * Create a new span within a trace
709
+ *
710
+ * @param traceId - The trace ID to create span in
711
+ * @param options - Span creation options
712
+ * @returns Created span
713
+ */
714
+ create(traceId: string, options: ISynovaCreateSpanOptions): Promise<ISynovaSpan>;
715
+ /**
716
+ * End/complete a span
717
+ *
718
+ * @param spanId - The span ID to end
719
+ * @param options - Span end options
720
+ * @returns Updated span
721
+ */
722
+ end(spanId: string, options?: ISynovaEndSpanOptions): Promise<ISynovaSpan>;
723
+ /**
724
+ * Wrap an async function with automatic span tracking
725
+ *
726
+ * @param options - Span options (traceId, type, name, etc.)
727
+ * @param input - Input data to record in span
728
+ * @param fn - Async function to execute
729
+ * @returns Result of the function
730
+ *
731
+ * @example
732
+ * ```ts
733
+ * const result = await client.spans.wrap(
734
+ * { traceId: 'trc_123', type: 'retriever', name: 'vector_search' },
735
+ * { query: 'how to...', topK: 5 },
736
+ * async () => vectorDb.search(query),
737
+ * );
738
+ * ```
739
+ */
740
+ wrap<T>(options: ISynovaWrapOptions, input: unknown, fn: () => Promise<T>): Promise<T>;
741
+ /**
742
+ * Wrap a tool function with automatic span tracking
743
+ *
744
+ * @param options - Tool span options (traceId, toolName, etc.)
745
+ * @param args - Tool arguments to record
746
+ * @param fn - Tool function to execute
747
+ * @returns Result of the tool
748
+ *
749
+ * @example
750
+ * ```ts
751
+ * const weather = await client.spans.wrapTool(
752
+ * { traceId: 'trc_123', toolName: 'fetch_weather', parentSpanId: 'spn_abc' },
753
+ * { city: 'NYC' },
754
+ * async (args) => fetchWeather(args.city),
755
+ * );
756
+ * ```
757
+ */
758
+ wrapTool<TArgs extends Record<string, unknown>, TResult>(options: ISynovaWrapToolOptions, args: TArgs, fn: (args: TArgs) => Promise<TResult>): Promise<TResult>;
759
+ }
760
+
559
761
  /**
560
762
  * Synova Cloud SDK client
561
763
  *
@@ -605,6 +807,7 @@ declare class SynovaCloudSdk {
605
807
  readonly prompts: PromptsResource;
606
808
  readonly models: ModelsResource;
607
809
  readonly files: FilesResource;
810
+ readonly spans: SpansResource;
608
811
  private readonly http;
609
812
  /**
610
813
  * Create a new Synova Cloud SDK client
@@ -1007,4 +1210,4 @@ declare function SchemaUniqueItems(): PropertyDecorator;
1007
1210
  */
1008
1211
  declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
1009
1212
 
1010
- 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 };
1213
+ 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 };