@synova-cloud/sdk 1.9.2 → 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;
+}
+
+/**
+ * Schema type identifier
+ */
+type TSchemaType = 'zod' | 'yup' | 'joi' | 'json-schema' | 'unknown';
+/**
+ * Zod-like schema interface
+ */
+interface IZodLike {
+    _def: {
+        typeName: string;
+    };
+    safeParse: unknown;
+}
 /**
- * Metadata keys used by schema decorators
+ * Yup-like schema interface
  */
-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";
-};
+interface IYupLike {
+    __isYupSchema__: true;
+}
 /**
- * Options for schema generation
+ * Joi-like schema interface
  */
-interface IGenerateSchemaOptions {
-    /** Allow additional properties on objects (default: false) */
-    additionalProperties?: boolean;
+interface IJoiLike {
+    describe: () => unknown;
 }
 /**
- * Constructor type for classes
+ * 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.
  */
-type TClassConstructor<T = unknown> = new (...args: any[]) => T;
+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',
+     *   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',
-     *   responseClass: TopicDto,
+     *   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,349 +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 {
-    /**
-     * Generate JSON Schema from a class
-     */
-    static generate<T>(targetClass: TClassConstructor<T>, options?: IGenerateSchemaOptions): IJsonSchema;
-    /**
-     * Get all properties with their schemas
-     */
-    private static getProperties;
+declare class JsonSchemaAdapter implements ISchemaAdapter<IJsonSchema> {
+    private static readonly VALID_JSON_SCHEMA_TYPES;
+    canHandle(schema: unknown): schema is IJsonSchema;
+    toJsonSchema(schema: IJsonSchema): IJsonSchema;
     /**
-     * Get property names from class-validator metadata
+     * Recursively transform `nullable: true` to `type: ["...", "null"]`
      */
-    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;
- * }
- * ```
- */
-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;
- * }
- * ```
+ * Zod schema type definition
  */
-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;
-/**
- * Sets maximum array length.
- *
- * @example
- * ```typescript
- * class Article {
- *   @SchemaMaxItems(10)
- *   tags: string[];
- * }
- * ```
- */
-declare function SchemaMaxItems(count: number): PropertyDecorator;
+interface IYupSchema {
+    __isYupSchema__: boolean;
+}
 /**
- * Requires all array items to be unique.
+ * Adapter for Yup schemas.
+ * Uses @sodaru/yup-to-json-schema for conversion.
  *
- * @example
- * ```typescript
- * class User {
- *   @SchemaUniqueItems()
- *   roles: string[];
- * }
- * ```
+ * @see https://github.com/jquense/yup/blob/master/src/schema.ts
  */
-declare function SchemaUniqueItems(): PropertyDecorator;
+declare class YupAdapter implements ISchemaAdapter<IYupSchema> {
+    canHandle(schema: unknown): schema is IYupSchema;
+    toJsonSchema(schema: IYupSchema): IJsonSchema;
+}
+
 /**
- * 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;
- * }
- * ```
+ * Joi schema type definition
  */
-declare function SchemaEnum(values: (string | number | boolean | null)[]): PropertyDecorator;
+interface IJoiSchema {
+    describe: () => {
+        type: string;
+    };
+}
 /**
- * Allows additional properties on object.
- * Useful for LLM to add dynamic keys.
- *
- * For arrays, applies to array items instead of the array itself.
- *
- * @param value - `true` for any value type, or a schema to constrain value types
+ * Adapter for Joi schemas.
+ * Uses joi-to-json for conversion.
  *
- * @example
- * ```typescript
- * class Response {
- *   @AdditionalProperties(true) // any value type
- *   metadata: Record<string, unknown>;
- *
- *   @AdditionalProperties({ type: 'string' }) // only string values
- *   labels: Record<string, string>;
- *
- *   @ArrayItems(Object)
- *   @AdditionalProperties(true) // applies to each array item
- *   pipeline: Record<string, unknown>[];
- * }
- * ```
+ * @see https://joi.dev/api/#isschemaschema-options
  */
-declare function AdditionalProperties(value?: boolean | IJsonSchema): PropertyDecorator;
+declare class JoiAdapter implements ISchemaAdapter<IJoiSchema> {
+    canHandle(schema: unknown): schema is IJoiSchema;
+    toJsonSchema(schema: IJoiSchema): IJsonSchema;
+}
 
-export { AdditionalProperties, 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 };