@synova-cloud/sdk 1.9.1 → 2.0.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 /**
  * JSON Schema primitive types
  */
-type TJsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+type TJsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
 /**
  * JSON Schema string formats
  * @see https://json-schema.org/understanding-json-schema/reference/string#built-in-formats
@@ -38,41 +38,117 @@ interface IJsonSchema {
     oneOf?: IJsonSchema[];
     not?: IJsonSchema;
 }
+
+/**
+ * Interface for schema adapters that convert various schema libraries to JSON Schema
+ */
+interface ISchemaAdapter<TSchema = unknown> {
+    /**
+     * Check if this adapter can handle the given schema
+     */
+    canHandle(schema: unknown): schema is TSchema;
+    /**
+     * Convert the schema to JSON Schema format
+     */
+    toJsonSchema(schema: TSchema): IJsonSchema;
+}
+
 /**
- * Metadata keys used by schema decorators
+ * Schema type identifier
  */
-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";
-    readonly ADDITIONAL_PROPERTIES: "synova:schema:additionalProperties";
-};
+type TSchemaType = 'zod' | 'yup' | 'joi' | 'json-schema' | 'unknown';
 /**
- * Options for schema generation
+ * Zod-like schema interface
  */
-interface IGenerateSchemaOptions {
-    /** Allow additional properties on objects (default: false) */
-    additionalProperties?: boolean;
+interface IZodLike {
+    _def: {
+        typeName: string;
+    };
+    safeParse: unknown;
 }
 /**
- * Constructor type for classes
+ * Yup-like schema interface
  */
-type TClassConstructor<T = unknown> = new (...args: any[]) => T;
+interface IYupLike {
+    __isYupSchema__: true;
+}
+/**
+ * Joi-like schema interface
+ */
+interface IJoiLike {
+    describe: () => unknown;
+}
+/**
+ * Supported schema input types.
+ * Provides better type hints while maintaining flexibility.
+ */
+type TSchemaInput = IJsonSchema | IZodLike | IYupLike | IJoiLike | unknown;
+/**
+ * Schema resolver that converts various schema libraries to JSON Schema.
+ * Supports Zod, Yup, Joi, and raw JSON Schema.
+ */
+declare class SchemaResolver {
+    private static adapters;
+    /**
+     * Register a custom adapter.
+     *
+     * @param adapter - The adapter to register
+     * @param position - Where to insert: 'first' adds at the beginning,
+     *                   'last' adds before JsonSchemaAdapter (fallback)
+     *
+     * @example
+     * ```typescript
+     * SchemaResolver.registerAdapter(new MyCustomAdapter(), 'first');
+     * ```
+     */
+    static registerAdapter(adapter: ISchemaAdapter, position?: 'first' | 'last'): void;
+    /**
+     * Reset adapters to default configuration.
+     * Removes all custom adapters.
+     */
+    static resetAdapters(): void;
+    /**
+     * Resolve a schema input to JSON Schema format.
+     *
+     * @param schema - Schema from Zod, Yup, Joi, or raw JSON Schema
+     * @returns JSON Schema representation
+     * @throws Error if schema type is not supported
+     *
+     * @example
+     * ```typescript
+     * // Zod
+     * const zodSchema = z.object({ title: z.string() });
+     * const jsonSchema = SchemaResolver.resolve(zodSchema);
+     *
+     * // Yup
+     * const yupSchema = yup.object({ title: yup.string().required() });
+     * const jsonSchema = SchemaResolver.resolve(yupSchema);
+     *
+     * // Joi
+     * const joiSchema = Joi.object({ title: Joi.string() });
+     * const jsonSchema = SchemaResolver.resolve(joiSchema);
+     *
+     * // Raw JSON Schema (passthrough)
+     * const rawSchema = { type: 'object', properties: { title: { type: 'string' } } };
+     * const jsonSchema = SchemaResolver.resolve(rawSchema);
+     * ```
+     */
+    static resolve(schema: TSchemaInput): IJsonSchema;
+    /**
+     * Check if a schema is supported.
+     *
+     * @param schema - Schema to check
+     * @returns true if the schema is supported
+     */
+    static isSupported(schema: unknown): boolean;
+    /**
+     * Get the type of a schema.
+     *
+     * @param schema - Schema to identify
+     * @returns Schema type identifier
+     */
+    static getSchemaType(schema: unknown): TSchemaType;
+}
 
 type TSynovaMessageRole = 'system' | 'user' | 'assistant' | 'tool';
 type TSynovaResponseType = 'message' | 'tool_calls' | 'image' | 'audio' | 'error';
@@ -177,8 +253,8 @@ interface ISynovaExecuteOptions {
     metadata?: Record<string, string>;
     /** Model parameters (temperature, maxTokens, topP, topK, etc.) */
     parameters?: Record<string, unknown>;
-    /** JSON Schema for structured output */
-    responseSchema?: IJsonSchema;
+    /** Schema for structured output (Zod, Yup, Joi, or raw JSON Schema) */
+    responseSchema?: TSchemaInput;
     /** Session ID for trace grouping (enables multi-call trace view in observability) */
     sessionId?: string;
 }
@@ -473,15 +549,6 @@ 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);
@@ -490,26 +557,36 @@ declare class PromptsResource {
      */
     get(promptId: string, options?: ISynovaGetPromptOptions): Promise<ISynovaPrompt>;
     /**
-     * Execute a prompt with typed response
+     * Execute a prompt with typed response using responseSchema
      *
      * @example
      * ```ts
-     * // With responseClass - returns typed object
-     * const topic = await client.prompts.execute('prm_abc123', {
+     * // With Zod schema
+     * const schema = z.object({ title: z.string() });
+     * const result = await client.prompts.execute<z.infer<typeof schema>>('prm_abc123', {
      *   provider: 'openai',
      *   model: 'gpt-4o',
-     *   responseClass: TopicDto,
+     *   responseSchema: schema,
+     * });
+     * console.log(result.title); // Typed as string
+     *
+     * // With raw JSON Schema
+     * const result = await client.prompts.execute<{ title: string }>('prm_abc123', {
+     *   provider: 'openai',
+     *   model: 'gpt-4o',
+     *   responseSchema: { type: 'object', properties: { title: { type: 'string' } } },
      * });
-     * console.log(topic.title); // Typed as string
      * ```
      */
-    execute<T>(promptId: string, options: ISynovaExecuteTypedOptions<T>): Promise<T>;
+    execute<T>(promptId: string, options: ISynovaExecuteOptions & {
+        responseSchema: NonNullable<ISynovaExecuteOptions['responseSchema']>;
+    }): Promise<T>;
     /**
      * Execute a prompt
      *
      * @example
      * ```ts
-     * // Without responseClass - returns ISynovaExecuteResponse
+     * // Without responseSchema - returns ISynovaExecuteResponse
      * const result = await client.prompts.execute('prm_abc123', {
      *   provider: 'openai',
      *   model: 'gpt-4o',
@@ -523,7 +600,9 @@ declare class PromptsResource {
     /**
      * Execute a prompt by tag with typed response
      */
-    executeByTag<T>(promptId: string, tag: string, options: ISynovaExecuteTypedOptions<T>): Promise<T>;
+    executeByTag<T>(promptId: string, tag: string, options: ISynovaExecuteOptions & {
+        responseSchema: NonNullable<ISynovaExecuteOptions['responseSchema']>;
+    }): Promise<T>;
     /**
      * Execute a prompt by tag
      */
@@ -531,24 +610,13 @@ declare class PromptsResource {
     /**
      * Execute a prompt by version with typed response
      */
-    executeByVersion<T>(promptId: string, version: string, options: ISynovaExecuteTypedOptions<T>): Promise<T>;
+    executeByVersion<T>(promptId: string, version: string, options: ISynovaExecuteOptions & {
+        responseSchema: NonNullable<ISynovaExecuteOptions['responseSchema']>;
+    }): Promise<T>;
     /**
      * Execute a prompt by version
      */
     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 {
@@ -889,325 +957,75 @@ declare class ExecutionSynovaError extends SynovaError {
     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);
- * ```
+ * Passthrough adapter for raw JSON Schema objects.
+ * Transforms `nullable: true` to `type: ["...", "null"]` recursively.
  */
-declare class ClassSchema {
+declare class JsonSchemaAdapter implements ISchemaAdapter<IJsonSchema> {
+    private static readonly VALID_JSON_SCHEMA_TYPES;
+    canHandle(schema: unknown): schema is IJsonSchema;
+    toJsonSchema(schema: IJsonSchema): IJsonSchema;
     /**
-     * Generate JSON Schema from a class
+     * Recursively transform `nullable: true` to `type: ["...", "null"]`
      */
-    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;
+    private transformNullable;
 }
 
 /**
- * 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;
- * }
- * ```
+ * Zod schema type definition
  */
-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;
+interface IZodSchema {
+    _def: {
+        typeName: string;
+    };
+    safeParse: (data: unknown) => {
+        success: boolean;
+    };
+}
 /**
- * Value must be a multiple of this number.
- *
- * @example
- * ```typescript
- * class Currency {
- *   @MultipleOf(0.01)
- *   amount: number;
- * }
- * ```
+ * Adapter for Zod schemas.
+ * Uses zod-to-json-schema for conversion.
  */
-declare function MultipleOf(value: number): PropertyDecorator;
+declare class ZodAdapter implements ISchemaAdapter<IZodSchema> {
+    canHandle(schema: unknown): schema is IZodSchema;
+    toJsonSchema(schema: IZodSchema): IJsonSchema;
+}
+
 /**
- * Sets minimum array length.
- *
- * @example
- * ```typescript
- * class Order {
- *   @SchemaMinItems(1)
- *   items: OrderItem[];
- * }
- * ```
+ * Yup schema type definition
  */
-declare function SchemaMinItems(count: number): PropertyDecorator;
+interface IYupSchema {
+    __isYupSchema__: boolean;
+}
 /**
- * Sets maximum array length.
+ * Adapter for Yup schemas.
+ * Uses @sodaru/yup-to-json-schema for conversion.
  *
- * @example
- * ```typescript
- * class Article {
- *   @SchemaMaxItems(10)
- *   tags: string[];
- * }
- * ```
+ * @see https://github.com/jquense/yup/blob/master/src/schema.ts
  */
-declare function SchemaMaxItems(count: number): PropertyDecorator;
+declare class YupAdapter implements ISchemaAdapter<IYupSchema> {
+    canHandle(schema: unknown): schema is IYupSchema;
+    toJsonSchema(schema: IYupSchema): IJsonSchema;
+}
+
 /**
- * Requires all array items to be unique.
- *
- * @example
- * ```typescript
- * class User {
- *   @SchemaUniqueItems()
- *   roles: string[];
- * }
- * ```
+ * Joi schema type definition
  */
-declare function SchemaUniqueItems(): PropertyDecorator;
+interface IJoiSchema {
+    describe: () => {
+        type: string;
+    };
+}
 /**
- * Sets allowed enum values.
+ * Adapter for Joi schemas.
+ * Uses joi-to-json for conversion.
  *
- * @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;
- * }
- * ```
+ * @see https://joi.dev/api/#isschemaschema-options
  */
-declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
+declare class JoiAdapter implements ISchemaAdapter<IJoiSchema> {
+    canHandle(schema: unknown): schema is IJoiSchema;
+    toJsonSchema(schema: IJoiSchema): IJsonSchema;
+}
 
-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 };
+export { ApiSynovaError, AuthSynovaError, ExecutionSynovaError, type IJsonSchema, type ISchemaAdapter, type ISynovaConfig, type ISynovaCreateSpanOptions, type ISynovaEndSpanOptions, 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 ISynovaSpan, type ISynovaSpanData, type ISynovaToolCall, type ISynovaToolResult, type ISynovaUploadOptions, type ISynovaUploadResponse, type ISynovaUploadedFile, type ISynovaWrapOptions, type ISynovaWrapToolOptions, JoiAdapter, JsonSchemaAdapter, NetworkSynovaError, NotFoundSynovaError, RateLimitSynovaError, SchemaResolver, ServerSynovaError, SynovaCloudSdk, SynovaError, type TJsonSchemaFormat, type TJsonSchemaType, type TSchemaInput, type TSchemaType, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, type TSynovaSpanLevel, type TSynovaSpanStatus, type TSynovaSpanType, type TSynovaUsageType, TimeoutSynovaError, YupAdapter, ZodAdapter };