@synova-cloud/sdk 1.6.0 → 1.8.0

package/dist/index.d.cts

@@ -1,24 +1,82 @@
-type TSynovaMessageRole = 'system' | 'user' | 'assistant' | 'tool';
-type TSynovaResponseType = 'message' | 'tool_calls' | 'image' | 'audio' | 'error';
-type TSynovaModelType = 'text' | 'image';
-type TSynovaUsageType = 'tokens' | 'images' | 'time';
-type TSynovaJsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
-interface ISynovaJsonSchema {
-    /** Schema type */
-    type?: TSynovaJsonSchemaType;
-    /** Description of the field */
+/**
+ * JSON Schema primitive types
+ */
+type TJsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+/**
+ * JSON Schema string formats
+ * @see https://json-schema.org/understanding-json-schema/reference/string#built-in-formats
+ */
+type TJsonSchemaFormat = 'date-time' | 'date' | 'time' | 'duration' | 'email' | 'idn-email' | 'hostname' | 'idn-hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uri-reference' | 'iri' | 'iri-reference' | 'uuid' | 'json-pointer' | 'relative-json-pointer' | 'regex';
+/**
+ * JSON Schema definition
+ * @see https://json-schema.org/specification
+ */
+interface IJsonSchema {
+    type?: TJsonSchemaType | TJsonSchemaType[];
     description?: string;
-    /** Allowed values (for enum-like fields) */
+    examples?: unknown[];
+    default?: unknown;
     enum?: (string | number | boolean | null)[];
-    /** Schema for array items (when type='array') */
-    items?: ISynovaJsonSchema;
-    /** Object properties (when type='object') */
-    properties?: Record<string, ISynovaJsonSchema>;
-    /** Required property names (when type='object') */
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: TJsonSchemaFormat;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    items?: IJsonSchema;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    properties?: Record<string, IJsonSchema>;
     required?: string[];
-    /** Whether additional properties are allowed (when type='object') */
+    additionalProperties?: boolean | IJsonSchema;
+    allOf?: IJsonSchema[];
+    anyOf?: IJsonSchema[];
+    oneOf?: IJsonSchema[];
+    not?: IJsonSchema;
+}
+/**
+ * Metadata keys used by schema decorators
+ */
+declare const SCHEMA_METADATA_KEYS: {
+    readonly DESCRIPTION: "synova:schema:description";
+    readonly EXAMPLES: "synova:schema:examples";
+    readonly DEFAULT: "synova:schema:default";
+    readonly FORMAT: "synova:schema:format";
+    readonly ARRAY_ITEM_TYPE: "synova:schema:arrayItemType";
+    readonly NULLABLE: "synova:schema:nullable";
+    readonly ENUM: "synova:schema:enum";
+    readonly MIN_LENGTH: "synova:schema:minLength";
+    readonly MAX_LENGTH: "synova:schema:maxLength";
+    readonly PATTERN: "synova:schema:pattern";
+    readonly MINIMUM: "synova:schema:minimum";
+    readonly MAXIMUM: "synova:schema:maximum";
+    readonly EXCLUSIVE_MINIMUM: "synova:schema:exclusiveMinimum";
+    readonly EXCLUSIVE_MAXIMUM: "synova:schema:exclusiveMaximum";
+    readonly MULTIPLE_OF: "synova:schema:multipleOf";
+    readonly MIN_ITEMS: "synova:schema:minItems";
+    readonly MAX_ITEMS: "synova:schema:maxItems";
+    readonly UNIQUE_ITEMS: "synova:schema:uniqueItems";
+};
+/**
+ * Options for schema generation
+ */
+interface IGenerateSchemaOptions {
+    /** Allow additional properties on objects (default: false) */
     additionalProperties?: boolean;
 }
+/**
+ * Constructor type for classes
+ */
+type TClassConstructor<T = unknown> = new (...args: any[]) => T;
+
+type TSynovaMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+type TSynovaResponseType = 'message' | 'tool_calls' | 'image' | 'audio' | 'error';
+type TSynovaModelType = 'text' | 'image';
+type TSynovaUsageType = 'tokens' | 'images' | 'time';
 interface ISynovaLogger {
     debug: (message: string, ...args: unknown[]) => void;
     info: (message: string, ...args: unknown[]) => void;
@@ -119,7 +177,9 @@ interface ISynovaExecuteOptions {
     /** Model parameters (temperature, maxTokens, topP, topK, etc.) */
     parameters?: Record<string, unknown>;
     /** JSON Schema for structured output */
-    responseSchema?: ISynovaJsonSchema;
+    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 */
@@ -152,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) */
@@ -202,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;
@@ -276,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;
@@ -303,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>;
@@ -327,97 +472,82 @@ declare class HttpClient {
     private log;
 }
 
+/**
+ * Execute options with optional responseClass for typed responses
+ */
+interface ISynovaExecuteTypedOptions<T> extends Omit<ISynovaExecuteOptions, 'responseSchema'> {
+    /** Class to use for response typing and schema generation */
+    responseClass: TClassConstructor<T>;
+    /** Enable class-validator validation (default: true) */
+    validate?: boolean;
+}
 declare class PromptsResource {
     private readonly http;
     constructor(http: HttpClient);
     /**
      * 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
+     */
+    get(promptId: string, options?: ISynovaGetPromptOptions): Promise<ISynovaPrompt>;
+    /**
+     * Execute a prompt with typed response
      *
      * @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' });
+     * // With responseClass - returns typed object
+     * const topic = await client.prompts.execute('prm_abc123', {
+     *   provider: 'openai',
+     *   model: 'gpt-4o',
+     *   responseClass: TopicDto,
+     * });
+     * console.log(topic.title); // Typed as string
      * ```
      */
-    get(promptId: string, options?: ISynovaGetPromptOptions): Promise<ISynovaPrompt>;
+    execute<T>(promptId: string, options: ISynovaExecuteTypedOptions<T>): Promise<T>;
     /**
-     * Execute a prompt with 'latest' tag
-     *
-     * @param promptId - The prompt ID
-     * @param options - Execution options including provider, model and variables
-     * @returns The execution response
+     * Execute a prompt
      *
      * @example
      * ```ts
+     * // Without responseClass - returns ISynovaExecuteResponse
      * 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(promptId: string, options: ISynovaExecuteOptions): Promise<ISynovaExecuteResponse>;
+    /**
+     * Execute a prompt by tag with typed response
+     */
+    executeByTag<T>(promptId: string, tag: string, options: ISynovaExecuteTypedOptions<T>): Promise<T>;
     /**
      * 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' },
-     * });
-     * ```
      */
     executeByTag(promptId: string, tag: string, options: ISynovaExecuteOptions): Promise<ISynovaExecuteResponse>;
+    /**
+     * Execute a prompt by version with typed response
+     */
+    executeByVersion<T>(promptId: string, version: string, options: ISynovaExecuteTypedOptions<T>): Promise<T>;
     /**
      * 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' },
-     * });
-     * ```
      */
     executeByVersion(promptId: string, version: string, options: ISynovaExecuteOptions): Promise<ISynovaExecuteResponse>;
+    /**
+     * Execute raw request without typed response
+     * @throws {ExecutionSynovaError} If LLM returns an error
+     */
+    private executeRaw;
+    /**
+     * Execute with typed response class
+     */
+    private executeTyped;
+    /**
+     * Validate object using class-validator
+     */
+    private validateObject;
 }
 
 declare class ModelsResource {
@@ -513,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
  *
@@ -562,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
@@ -632,5 +877,336 @@ declare class NetworkSynovaError extends SynovaError {
     readonly cause?: Error;
     constructor(message: string, cause?: Error);
 }
+/**
+ * Error thrown when LLM execution fails (returned in response with type='error')
+ */
+declare class ExecutionSynovaError extends SynovaError {
+    readonly code: string;
+    readonly provider?: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly details?: ISynovaExecutionError['details'];
+    constructor(error: ISynovaExecutionError);
+}
+/**
+ * Validation violation details
+ */
+interface IValidationViolation {
+    property: string;
+    constraints: Record<string, string>;
+    value?: unknown;
+}
+/**
+ * Error thrown when LLM response fails class-validator validation
+ */
+declare class ValidationSynovaError extends SynovaError {
+    readonly violations: IValidationViolation[];
+    constructor(violations: IValidationViolation[]);
+}
+
+/**
+ * Generates JSON Schema from TypeScript classes decorated with schema decorators.
+ *
+ * @example
+ * ```typescript
+ * import { ClassSchema, Description, Example, SchemaMin, SchemaMax } from '@synova-cloud/sdk';
+ *
+ * class User {
+ *   @Description('User ID')
+ *   @Example('usr_123')
+ *   id: string;
+ *
+ *   @Description('User age')
+ *   @SchemaMin(0)
+ *   @SchemaMax(150)
+ *   age: number;
+ * }
+ *
+ * const schema = ClassSchema.generate(User);
+ * ```
+ */
+declare class ClassSchema {
+    /**
+     * Generate JSON Schema from a class
+     */
+    static generate<T>(targetClass: TClassConstructor<T>, options?: IGenerateSchemaOptions): IJsonSchema;
+    /**
+     * Get all properties with their schemas
+     */
+    private static getProperties;
+    /**
+     * Get property names from class-validator metadata
+     */
+    private static getClassValidatorProperties;
+    /**
+     * Get property names from our decorator metadata
+     */
+    private static getDecoratorProperties;
+    /**
+     * Get JSON Schema for a single property
+     */
+    private static getPropertySchema;
+    /**
+     * Get base schema from TypeScript type
+     */
+    private static getBaseTypeSchema;
+    /**
+     * Get schema for array items
+     */
+    private static getArrayItemSchema;
+    /**
+     * Apply class-validator constraints to schema
+     */
+    private static applyClassValidatorConstraints;
+    /**
+     * Apply a single class-validator constraint
+     */
+    private static applyValidationConstraint;
+    /**
+     * Apply our decorator metadata to schema.
+     * Our decorators take precedence over class-validator if both are used.
+     */
+    private static applyDecoratorMetadata;
+    /**
+     * Get required properties (properties without @IsOptional)
+     */
+    private static getRequiredProperties;
+}
+
+/**
+ * Adds a description to the property schema.
+ * Helps LLMs understand the expected content.
+ *
+ * @example
+ * ```typescript
+ * class Article {
+ *   @Description('SEO-optimized article title, 50-60 characters')
+ *   title: string;
+ * }
+ * ```
+ */
+declare function Description(description: string): PropertyDecorator;
+/**
+ * Adds example values to the property schema.
+ * Helps LLMs understand the expected format.
+ *
+ * @example
+ * ```typescript
+ * class Article {
+ *   @Example('How to Optimize SQL Queries', '10 Tips for Better Code')
+ *   title: string;
+ * }
+ * ```
+ */
+declare function Example(...examples: unknown[]): PropertyDecorator;
+/**
+ * Sets the default value for the property.
+ *
+ * @example
+ * ```typescript
+ * class Settings {
+ *   @Default('en')
+ *   language: string;
+ * }
+ * ```
+ */
+declare function Default(value: unknown): PropertyDecorator;
+/**
+ * Sets the type of array items.
+ * Required since TypeScript loses array item types at runtime.
+ *
+ * @example
+ * ```typescript
+ * class Article {
+ *   @ArrayItems(String)
+ *   keywords: string[];
+ *
+ *   @ArrayItems(Comment)
+ *   comments: Comment[];
+ * }
+ * ```
+ */
+declare function ArrayItems(itemType: TClassConstructor | StringConstructor | NumberConstructor | BooleanConstructor): PropertyDecorator;
+/**
+ * Sets semantic format for string (email, uri, uuid, date-time, etc.).
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @Format('email')
+ *   email: string;
+ *
+ *   @Format('date-time')
+ *   createdAt: string;
+ * }
+ * ```
+ */
+declare function Format(format: TJsonSchemaFormat): PropertyDecorator;
+/**
+ * Marks the property as nullable (can be null).
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @Nullable()
+ *   middleName: string | null;
+ * }
+ * ```
+ */
+declare function Nullable(): PropertyDecorator;
+/**
+ * Sets minimum string length.
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @SchemaMinLength(3)
+ *   username: string;
+ * }
+ * ```
+ */
+declare function SchemaMinLength(length: number): PropertyDecorator;
+/**
+ * Sets maximum string length.
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @SchemaMaxLength(100)
+ *   bio: string;
+ * }
+ * ```
+ */
+declare function SchemaMaxLength(length: number): PropertyDecorator;
+/**
+ * Sets regex pattern for string validation.
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @SchemaPattern('^[a-z0-9_]+$')
+ *   username: string;
+ * }
+ * ```
+ */
+declare function SchemaPattern(pattern: string): PropertyDecorator;
+/**
+ * Sets minimum value (inclusive).
+ *
+ * @example
+ * ```typescript
+ * class Product {
+ *   @SchemaMin(0)
+ *   price: number;
+ * }
+ * ```
+ */
+declare function SchemaMin(value: number): PropertyDecorator;
+/**
+ * Sets maximum value (inclusive).
+ *
+ * @example
+ * ```typescript
+ * class Rating {
+ *   @SchemaMax(5)
+ *   score: number;
+ * }
+ * ```
+ */
+declare function SchemaMax(value: number): PropertyDecorator;
+/**
+ * Sets minimum value (exclusive).
+ *
+ * @example
+ * ```typescript
+ * class Discount {
+ *   @ExclusiveMin(0)  // must be > 0
+ *   percentage: number;
+ * }
+ * ```
+ */
+declare function ExclusiveMin(value: number): PropertyDecorator;
+/**
+ * Sets maximum value (exclusive).
+ *
+ * @example
+ * ```typescript
+ * class Probability {
+ *   @ExclusiveMax(1)  // must be < 1
+ *   value: number;
+ * }
+ * ```
+ */
+declare function ExclusiveMax(value: number): PropertyDecorator;
+/**
+ * Value must be a multiple of this number.
+ *
+ * @example
+ * ```typescript
+ * class Currency {
+ *   @MultipleOf(0.01)
+ *   amount: number;
+ * }
+ * ```
+ */
+declare function MultipleOf(value: number): PropertyDecorator;
+/**
+ * Sets minimum array length.
+ *
+ * @example
+ * ```typescript
+ * class Order {
+ *   @SchemaMinItems(1)
+ *   items: OrderItem[];
+ * }
+ * ```
+ */
+declare function SchemaMinItems(count: number): PropertyDecorator;
+/**
+ * Sets maximum array length.
+ *
+ * @example
+ * ```typescript
+ * class Article {
+ *   @SchemaMaxItems(10)
+ *   tags: string[];
+ * }
+ * ```
+ */
+declare function SchemaMaxItems(count: number): PropertyDecorator;
+/**
+ * Requires all array items to be unique.
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @SchemaUniqueItems()
+ *   roles: string[];
+ * }
+ * ```
+ */
+declare function SchemaUniqueItems(): PropertyDecorator;
+/**
+ * Sets allowed enum values.
+ *
+ * @example
+ * ```typescript
+ * class User {
+ *   @SchemaEnum(['admin', 'user', 'guest'])
+ *   role: string;
+ * }
+ * ```
+ *
+ * With TypeScript enum:
+ * ```typescript
+ * enum Status { Active = 'active', Inactive = 'inactive' }
+ *
+ * class User {
+ *   @SchemaEnum(Object.values(Status))
+ *   status: Status;
+ * }
+ * ```
+ */
+declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
 
-export { ApiSynovaError, AuthSynovaError, type ISynovaConfig, type ISynovaExecuteOptions, type ISynovaExecuteResponse, 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, NetworkSynovaError, NotFoundSynovaError, RateLimitSynovaError, ServerSynovaError, SynovaCloudSdk, SynovaError, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, type TSynovaUsageType, TimeoutSynovaError };
+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 };