@synova-cloud/sdk 1.5.0 → 1.7.0

package/README.md

@@ -119,6 +119,29 @@ const response = await client.prompts.execute('prm_abc123', {
 });
 ```
 
+#### With Your Own API Key
+
+You can pass your own LLM provider API key directly in the request:
+
+```typescript
+// OpenAI, Anthropic, Google, DeepSeek
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  apiKey: 'sk-your-openai-key',
+  variables: { topic: 'TypeScript' },
+});
+
+// Azure OpenAI (requires endpoint)
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'azure_openai',
+  model: 'my-gpt4-deployment',
+  apiKey: 'your-azure-key',
+  azureEndpoint: 'https://my-resource.openai.azure.com',
+  variables: { topic: 'TypeScript' },
+});
+```
+
 #### With Conversation History
 
 ```typescript
@@ -151,6 +174,95 @@ if (response.type === 'image') {
 }
 ```
 
+#### Structured Output (Typed Responses)
+
+Get typed and validated responses from LLMs using JSON Schema.
+
+First, install optional peer dependencies:
+```bash
+npm install class-validator class-transformer
+```
+
+Define a response class with decorators:
+```typescript
+import { IsString, IsArray, IsNumber, Min, Max } from 'class-validator';
+import { Description, Example, ArrayItems } from '@synova-cloud/sdk';
+
+class TopicDto {
+  @IsString()
+  @Description('Article title for SEO')
+  @Example('10 Ways to Improve SQL Performance')
+  title: string;
+
+  @IsString()
+  @Description('Short description')
+  description: string;
+
+  @IsArray()
+  @ArrayItems(String)
+  @Description('SEO keywords')
+  keywords: string[];
+
+  @IsNumber()
+  @Min(1)
+  @Max(10)
+  @Description('Priority from 1 to 10')
+  priority: number;
+}
+```
+
+Execute with `responseClass` to get typed response:
+```typescript
+const topic = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  responseClass: TopicDto,
+});
+
+// topic is typed as TopicDto
+console.log(topic.title);     // string
+console.log(topic.keywords);  // string[]
+console.log(topic.priority);  // number
+```
+
+Works with `executeByTag` and `executeByVersion` too:
+```typescript
+const topic = await client.prompts.executeByTag('prm_abc123', 'production', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  responseClass: TopicDto,
+});
+```
+
+Disable validation if needed:
+```typescript
+const topic = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  responseClass: TopicDto,
+  validate: false, // Skip class-validator validation
+});
+```
+
+**Available Schema Decorators:**
+
+| Decorator | Description |
+|-----------|-------------|
+| `@Description(text)` | Adds description to help LLM |
+| `@Example(...values)` | Adds example values |
+| `@Default(value)` | Sets default value |
+| `@ArrayItems(Type)` | Sets array item type |
+| `@Format(format)` | Sets string format (email, uri, uuid, date-time) |
+| `@Nullable()` | Marks as nullable |
+| `@SchemaMin(n)` | Minimum number value |
+| `@SchemaMax(n)` | Maximum number value |
+| `@SchemaMinLength(n)` | Minimum string length |
+| `@SchemaMaxLength(n)` | Maximum string length |
+| `@SchemaPattern(regex)` | Regex pattern for string |
+| `@SchemaMinItems(n)` | Minimum array length |
+| `@SchemaMaxItems(n)` | Maximum array length |
+| `@SchemaEnum(values)` | Allowed enum values |
+
 ### Models
 
 #### List All Models
@@ -243,116 +355,50 @@ const response = await client.prompts.execute('prm_vision123', {
 console.log(response.content);
 ```
 
-### LLM Provider Keys
-
-Manage API keys for LLM providers (OpenAI, Anthropic, Google, Azure, etc.).
-
-#### List Keys
-
-```typescript
-const { items, total } = await client.llmProviderKeys.list();
-
-for (const key of items) {
-  console.log(`${key.provider}: ${key.maskedKey} (default: ${key.isDefault})`);
-  if (key.label) {
-    console.log(`  Label: ${key.label}`);
-  }
-}
-```
-
-#### Get Key by ID
-
-```typescript
-const key = await client.llmProviderKeys.get('lpk_abc123');
-
-console.log(`Provider: ${key.provider}`);
-console.log(`Default: ${key.isDefault}`);
-console.log(`Label: ${key.label}`);
-```
-
-#### Create Key
-
-```typescript
-// Create OpenAI key
-const key = await client.llmProviderKeys.create({
-  provider: 'openai',
-  apiKey: 'sk-...',
-  label: 'Production Key',
-  defaultModel: 'gpt-4o',
-});
-
-// Create Azure OpenAI key
-const azureKey = await client.llmProviderKeys.create({
-  provider: 'azure_openai',
-  apiKey: 'your-azure-key',
-  azure: {
-    endpoint: 'https://my-resource.openai.azure.com',
-  },
-  label: 'Azure Production',
-});
-```
-
-The first key created for a provider is automatically set as the default.
-
-#### Set Default Key
-
-```typescript
-// Set a different key as the default for its provider
-const key = await client.llmProviderKeys.setDefault('lpk_abc123');
-console.log(`${key.id} is now the default for ${key.provider}`);
-```
-
-#### Delete Key
-
-```typescript
-await client.llmProviderKeys.delete('lpk_abc123');
-```
-
-If you delete the default key and other keys exist for that provider, the next key becomes the new default.
-
-#### Use Specific Key in Execution
-
-```typescript
-// Execute with a specific API key
-const response = await client.prompts.execute('prm_abc123', {
-  provider: 'openai',
-  model: 'gpt-4o',
-  apiKeyId: 'lpk_abc123', // Use this specific key
-  variables: { name: 'World' },
-});
-
-// Or omit apiKeyId to use the default key for the provider
-const response = await client.prompts.execute('prm_abc123', {
-  provider: 'openai',
-  model: 'gpt-4o',
-  variables: { name: 'World' },
-});
-```
-
 ## Error Handling
 
-The SDK provides typed errors for different failure scenarios. All API errors extend `ApiSynovaError` and include full error details:
+The SDK provides typed errors for different failure scenarios:
 
 ```typescript
 import {
   SynovaCloudSdk,
-  SynovaError,
-  ApiSynovaError,
+  ExecutionSynovaError,
+  ValidationSynovaError,
   AuthSynovaError,
   NotFoundSynovaError,
   RateLimitSynovaError,
   ServerSynovaError,
   TimeoutSynovaError,
   NetworkSynovaError,
+  ApiSynovaError,
 } from '@synova-cloud/sdk';
 
 try {
   const response = await client.prompts.execute('prm_abc123', {
     provider: 'openai',
     model: 'gpt-4o',
-    variables: { name: 'World' },
+    responseClass: TopicDto,
   });
 } catch (error) {
+  // LLM execution error (rate limit, invalid key, context too long, etc.)
+  if (error instanceof ExecutionSynovaError) {
+    console.error(`LLM error [${error.code}]: ${error.message}`);
+    console.error(`Provider: ${error.provider}`);
+    console.error(`Retryable: ${error.retryable}`);
+    if (error.retryAfterMs) {
+      console.error(`Retry after: ${error.retryAfterMs}ms`);
+    }
+  }
+
+  // Validation error (response doesn't match class-validator constraints)
+  if (error instanceof ValidationSynovaError) {
+    console.error('Validation failed:');
+    for (const v of error.violations) {
+      console.error(`  ${v.property}: ${Object.values(v.constraints).join(', ')}`);
+    }
+  }
+
+  // API errors
   if (error instanceof AuthSynovaError) {
     console.error('Invalid API key');
   } else if (error instanceof NotFoundSynovaError) {
@@ -366,10 +412,8 @@ try {
   } else if (error instanceof NetworkSynovaError) {
     console.error(`Network error: ${error.message}`);
   } else if (error instanceof ApiSynovaError) {
-    // All API errors have these properties:
     console.error(`API error [${error.code}]: ${error.message}`);
     console.error(`Request ID: ${error.requestId}`);
-    console.error(`Details:`, error.details);
   }
 }
 ```
@@ -476,8 +520,9 @@ import type {
   ISynovaGetPromptOptions,
   // Execution
   ISynovaExecuteOptions,
+  ISynovaExecuteTypedOptions,
   ISynovaExecuteResponse,
-  ISynovaUsage,
+  ISynovaExecutionUsage,
   ISynovaExecutionError,
   // Messages
   ISynovaMessage,
@@ -498,12 +543,13 @@ import type {
   ISynovaModelsResponse,
   ISynovaListModelsOptions,
   TSynovaModelType,
-  // LLM Provider Keys
-  TSynovaLlmProvider,
-  ISynovaAzureConfig,
-  ISynovaLlmProviderKey,
-  ISynovaLlmProviderKeyListResponse,
-  ISynovaCreateLlmProviderKeyOptions,
+  // Schema
+  IJsonSchema,
+  TJsonSchemaType,
+  TJsonSchemaFormat,
+  TClassConstructor,
+  // Errors
+  IValidationViolation,
 } from '@synova-cloud/sdk';
 ```
 
@@ -521,6 +567,15 @@ const client = new SynovaCloudSdk('your-api-key');
 
 - Node.js 18+ (uses native `fetch`)
 
+### Optional Peer Dependencies
+
+For structured output with typed responses:
+```bash
+npm install class-validator class-transformer
+```
+
+These are optional - the SDK works without them, but `responseClass` feature requires them.
+
 ## License
 
 MIT