@synova-cloud/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Synova Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,475 @@
+# Synova Cloud SDK for Node.js
+
+Official Node.js SDK for the [Synova Cloud](https://synova.cloud) API.
+
+## Installation
+
+```bash
+npm install @synova-cloud/sdk
+# or
+yarn add @synova-cloud/sdk
+# or
+pnpm add @synova-cloud/sdk
+```
+
+## Quick Start
+
+```typescript
+import { SynovaCloudSdk } from '@synova-cloud/sdk';
+
+const client = new SynovaCloudSdk('your-api-key');
+
+// Execute a prompt
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  variables: { name: 'World' },
+});
+
+console.log(response.content);
+```
+
+## Configuration
+
+```typescript
+import { SynovaCloudSdk } from '@synova-cloud/sdk';
+
+const client = new SynovaCloudSdk('your-api-key', {
+  baseUrl: 'https://api.synova.cloud', // Custom API URL
+  timeout: 30000, // Request timeout in ms (default: 30000)
+  debug: true, // Enable debug logging
+  retry: {
+    maxRetries: 3, // Max retry attempts (default: 3)
+    strategy: 'exponential', // 'exponential' or 'linear' (default: 'exponential')
+    initialDelayMs: 1000, // Initial retry delay (default: 1000)
+    maxDelayMs: 30000, // Max retry delay (default: 30000)
+    backoffMultiplier: 2, // Multiplier for exponential backoff (default: 2)
+  },
+});
+```
+
+## API Reference
+
+### Prompts
+
+#### Get Prompt
+
+Retrieve a prompt template by ID.
+
+```typescript
+// Get latest version (default)
+const prompt = await client.prompts.get('prm_abc123');
+
+// Get by tag
+const prompt = await client.prompts.get('prm_abc123', { tag: 'production' });
+
+// Get specific version
+const prompt = await client.prompts.get('prm_abc123', { version: '1.2.0' });
+```
+
+#### Execute Prompt
+
+Execute a prompt with an LLM provider.
+
+```typescript
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',      // Required: 'openai', 'anthropic', 'google', etc.
+  model: 'gpt-4o',         // Required: model ID
+  variables: {             // Optional: template variables
+    userMessage: 'Hello!',
+  },
+});
+
+console.log(response.content);  // LLM response text
+console.log(response.usage);    // { inputTokens, outputTokens, totalTokens }
+```
+
+#### Execute with Tag or Version
+
+```typescript
+// Execute specific tag
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-20250514',
+  tag: 'production',
+  variables: { topic: 'AI' },
+});
+
+// Execute specific version
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  version: '1.2.0',
+  variables: { topic: 'AI' },
+});
+```
+
+#### With Model Parameters
+
+```typescript
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  variables: { topic: 'TypeScript' },
+  parameters: {
+    temperature: 0.7,
+    maxTokens: 1000,
+    topP: 0.9,
+  },
+});
+```
+
+#### With Metadata (Analytics)
+
+```typescript
+const response = await client.prompts.execute('prm_abc123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  variables: { query: 'Hello' },
+  metadata: {
+    userId: 'user_123',
+    sessionId: 'sess_456',
+    environment: 'production',
+  },
+});
+```
+
+#### With Conversation History
+
+```typescript
+const response = await client.prompts.execute('prm_chat456', {
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-20250514',
+  variables: { topic: 'TypeScript' },
+  messages: [
+    { role: 'user', content: 'What is TypeScript?' },
+    { role: 'assistant', content: 'TypeScript is a typed superset of JavaScript...' },
+    { role: 'user', content: 'How do I use generics?' },
+  ],
+});
+```
+
+#### With Structured Output (JSON Schema)
+
+```typescript
+const response = await client.prompts.execute('prm_extract789', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  variables: { text: 'John Doe, age 30, from New York' },
+  responseSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      age: { type: 'number' },
+      city: { type: 'string' },
+    },
+    required: ['name', 'age', 'city'],
+  },
+});
+
+// Access parsed object directly
+console.log(response.object); // { name: 'John Doe', age: 30, city: 'New York' }
+```
+
+#### Image Generation
+
+```typescript
+const response = await client.prompts.execute('prm_image123', {
+  provider: 'openai',
+  model: 'dall-e-3',
+  variables: { description: 'A sunset over mountains' },
+});
+
+if (response.type === 'image') {
+  for (const file of response.files) {
+    console.log('Generated image:', file.url);
+    console.log('MIME type:', file.mimeType);
+  }
+}
+```
+
+#### With Tool Calls
+
+```typescript
+const response = await client.prompts.execute('prm_assistant012', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  variables: { query: 'What is the weather in Tokyo?' },
+});
+
+if (response.type === 'tool_calls') {
+  for (const toolCall of response.toolCalls) {
+    console.log(`Tool: ${toolCall.name}`);
+    console.log(`Arguments: ${JSON.stringify(toolCall.arguments)}`);
+
+    // Execute your tool
+    const result = await executeMyTool(toolCall.name, toolCall.arguments);
+
+    // Continue conversation with tool results
+    const finalResponse = await client.prompts.execute('prm_assistant012', {
+      provider: 'openai',
+      model: 'gpt-4o',
+      messages: [
+        { role: 'user', content: 'What is the weather in Tokyo?' },
+        { role: 'assistant', toolCalls: [toolCall] },
+        { role: 'tool', toolResults: [{ toolCallId: toolCall.id, content: JSON.stringify(result) }] },
+      ],
+    });
+
+    console.log(finalResponse.content);
+  }
+}
+```
+
+### Models
+
+#### List All Models
+
+```typescript
+const { providers } = await client.models.list();
+
+for (const provider of providers) {
+  console.log(`${provider.displayName}:`);
+  for (const model of provider.models) {
+    console.log(`  - ${model.displayName} (${model.id})`);
+  }
+}
+```
+
+#### Filter Models
+
+```typescript
+// Filter by type
+const textModels = await client.models.list({ type: 'text' });
+const imageModels = await client.models.list({ type: 'image' });
+
+// Filter by capability
+const visionModels = await client.models.list({ capability: 'vision' });
+
+// Filter by provider
+const openaiModels = await client.models.list({ provider: 'openai' });
+```
+
+#### Get Models by Provider
+
+```typescript
+const models = await client.models.getByProvider('anthropic');
+
+for (const model of models) {
+  console.log(`${model.displayName}: context=${model.limits.contextWindow}`);
+}
+```
+
+#### Get Specific Model
+
+```typescript
+const model = await client.models.get('openai', 'gpt-4o');
+
+console.log('Capabilities:', model.capabilities);
+console.log('Context window:', model.limits.contextWindow);
+console.log('Pricing:', model.pricing);
+```
+
+### Files
+
+#### Upload Files
+
+Upload files for use in prompt execution (e.g., images for vision models).
+
+```typescript
+const result = await client.files.upload(
+  [file1, file2], // File[] or Blob[]
+  { projectId: 'prj_abc123' }
+);
+
+for (const file of result.data) {
+  console.log(`Uploaded: ${file.originalName}`);
+  console.log(`  ID: ${file.id}`);
+  console.log(`  URL: ${file.url}`);
+  console.log(`  Size: ${file.size} bytes`);
+}
+```
+
+#### Use Uploaded Files in Messages
+
+```typescript
+// Upload an image
+const uploadResult = await client.files.upload([imageFile], { projectId: 'prj_abc123' });
+const fileId = uploadResult.data[0].id;
+
+// Use in prompt execution with vision model
+const response = await client.prompts.execute('prm_vision123', {
+  provider: 'openai',
+  model: 'gpt-4o',
+  messages: [
+    {
+      role: 'user',
+      content: 'What is in this image?',
+      files: [{ fileId }],
+    },
+  ],
+});
+
+console.log(response.content);
+```
+
+## Error Handling
+
+The SDK provides typed errors for different failure scenarios:
+
+```typescript
+import {
+  SynovaCloudSdk,
+  SynovaError,
+  AuthSynovaError,
+  NotFoundSynovaError,
+  RateLimitSynovaError,
+  TimeoutSynovaError,
+  NetworkSynovaError,
+  ServerSynovaError,
+  ApiSynovaError,
+} from '@synova-cloud/sdk';
+
+try {
+  const response = await client.prompts.execute('prm_abc123', {
+    provider: 'openai',
+    model: 'gpt-4o',
+    variables: { name: 'World' },
+  });
+} catch (error) {
+  if (error instanceof AuthSynovaError) {
+    console.error('Invalid API key');
+  } else if (error instanceof NotFoundSynovaError) {
+    console.error(`Resource not found: ${error.resourceType} ${error.resourceId}`);
+  } else if (error instanceof RateLimitSynovaError) {
+    console.error(`Rate limited. Retry after: ${error.retryAfterMs}ms`);
+  } else if (error instanceof TimeoutSynovaError) {
+    console.error(`Request timed out after ${error.timeoutMs}ms`);
+  } else if (error instanceof NetworkSynovaError) {
+    console.error(`Network error: ${error.message}`);
+  } else if (error instanceof ServerSynovaError) {
+    console.error(`Server error ${error.httpCode}: ${error.message}`);
+  } else if (error instanceof ApiSynovaError) {
+    console.error(`API error [${error.code}]: ${error.message}`);
+  } else if (error instanceof SynovaError) {
+    console.error(`Synova error: ${error.message}`);
+  }
+}
+```
+
+## Retry Behavior
+
+The SDK automatically retries requests on:
+- Rate limit errors (429) - uses `Retry-After` header if available
+- Server errors (5xx)
+- Network errors
+- Timeout errors
+
+Non-retryable errors (fail immediately):
+- Authentication errors (401)
+- Not found errors (404)
+- Client errors (4xx)
+
+### Retry Strategies
+
+**Exponential Backoff** (default):
+```
+delay = initialDelayMs * backoffMultiplier^(attempt-1)
+```
+Example with defaults: 1000ms, 2000ms, 4000ms...
+
+**Linear**:
+```
+delay = initialDelayMs * attempt
+```
+Example with defaults: 1000ms, 2000ms, 3000ms...
+
+Both strategies add ±10% jitter to prevent thundering herd.
+
+## Custom Logger
+
+You can provide a custom logger that implements the `ISynovaLogger` interface:
+
+```typescript
+import { SynovaCloudSdk, ISynovaLogger } from '@synova-cloud/sdk';
+
+const customLogger: ISynovaLogger = {
+  debug: (message, ...args) => myLogger.debug(message, ...args),
+  info: (message, ...args) => myLogger.info(message, ...args),
+  warn: (message, ...args) => myLogger.warn(message, ...args),
+  error: (messageOrError, ...args) => {
+    if (messageOrError instanceof Error) {
+      myLogger.error(messageOrError.message, messageOrError, ...args);
+    } else {
+      myLogger.error(messageOrError, ...args);
+    }
+  },
+};
+
+const client = new SynovaCloudSdk('your-api-key', {
+  debug: true,
+  logger: customLogger,
+});
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import type {
+  // Config
+  ISynovaConfig,
+  ISynovaRetryConfig,
+  TSynovaRetryStrategy,
+  ISynovaLogger,
+  // Prompts
+  ISynovaPrompt,
+  ISynovaPromptVariable,
+  ISynovaGetPromptOptions,
+  // Execution
+  ISynovaExecuteOptions,
+  ISynovaExecuteResponse,
+  ISynovaUsage,
+  ISynovaExecutionError,
+  // Messages
+  ISynovaMessage,
+  ISynovaToolCall,
+  ISynovaToolResult,
+  TSynovaMessageRole,
+  TSynovaResponseType,
+  // Files
+  ISynovaFileAttachment,
+  ISynovaFileThumbnails,
+  ISynovaUploadedFile,
+  ISynovaUploadResponse,
+  ISynovaUploadOptions,
+  // Models
+  ISynovaModel,
+  ISynovaModelCapabilities,
+  ISynovaModelLimits,
+  ISynovaModelPricing,
+  ISynovaProvider,
+  ISynovaModelsResponse,
+  ISynovaListModelsOptions,
+  TSynovaModelType,
+} from '@synova-cloud/sdk';
+```
+
+## CommonJS
+
+The SDK supports both ESM and CommonJS:
+
+```javascript
+const { SynovaCloudSdk } = require('@synova-cloud/sdk');
+
+const client = new SynovaCloudSdk('your-api-key');
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+
+## License
+
+MIT