@synova-cloud/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,564 @@
+type TSynovaMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+type TSynovaResponseType = 'message' | 'tool_calls' | 'image' | 'error';
+type TSynovaModelType = 'text' | 'image';
+interface ISynovaLogger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (messageOrError: string | Error, ...args: unknown[]) => void;
+}
+type TSynovaRetryStrategy = 'exponential' | 'linear';
+interface ISynovaRetryConfig {
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Retry strategy: 'exponential' or 'linear' (default: 'exponential') */
+    strategy?: TSynovaRetryStrategy;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+}
+interface ISynovaConfig {
+    /** Base URL for API (default: https://api.synova.cloud) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: ISynovaRetryConfig;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom logger (default: console) */
+    logger?: ISynovaLogger;
+}
+interface ISynovaPromptVariable {
+    name: string;
+    type: string;
+    description?: string;
+    defaultValue?: string;
+}
+interface ISynovaPrompt {
+    promptId: string;
+    name: string;
+    version: string;
+    messages: ISynovaMessage[];
+    variables: ISynovaPromptVariable[];
+    tags: string[];
+    createdAt: string;
+}
+interface ISynovaGetPromptOptions {
+    /** Tag to retrieve (e.g., 'latest', 'production') */
+    tag?: string;
+    /** Version to retrieve (e.g., '1.0.0') */
+    version?: string;
+}
+interface ISynovaToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+interface ISynovaToolResult {
+    /** ID of the tool call this result responds to */
+    toolCallId: string;
+    /** Result content (typically JSON stringified) */
+    content: string;
+}
+interface ISynovaMessage {
+    role: TSynovaMessageRole;
+    /** Message content (required for user/assistant, optional for tool) */
+    content?: string;
+    /** Structured object (for assistant messages with responseSchema) */
+    object?: unknown;
+    /** Tool call ID (for tool messages) */
+    toolCallId?: string;
+    /** Tool calls requested by assistant (when role='assistant') */
+    toolCalls?: ISynovaToolCall[];
+    /** Tool execution results (when role='tool') */
+    toolResults?: ISynovaToolResult[];
+    /** File attachments (images, PDFs, text files) */
+    files?: ISynovaFileAttachment[];
+}
+interface ISynovaExecuteOptions {
+    /** LLM provider (e.g., 'openai', 'anthropic', 'google', 'azure_openai', 'deepseek') */
+    provider: string;
+    /** LLM model to use (e.g., 'gpt-4o', 'claude-sonnet-4-20250514') */
+    model: string;
+    /** Variables to substitute in prompt template */
+    variables?: Record<string, unknown>;
+    /** Previous messages for multi-turn conversation */
+    messages?: ISynovaMessage[];
+    /** Version tag (e.g., 'latest', 'production', 'staging') */
+    tag?: string;
+    /** Specific version number (e.g., '1.2.0') - takes precedence over tag */
+    version?: string;
+    /** Custom metadata for tracking/filtering in analytics */
+    metadata?: Record<string, string>;
+    /** Model parameters (temperature, maxTokens, topP, topK, etc.) */
+    parameters?: Record<string, unknown>;
+    /** JSON Schema for structured output */
+    responseSchema?: Record<string, unknown>;
+}
+interface ISynovaUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+interface ISynovaExecutionError {
+    code: string;
+    message: string;
+    provider?: string;
+    retryable: boolean;
+    retryAfterMs?: number;
+    details?: unknown;
+}
+interface ISynovaFileThumbnails {
+    /** Small thumbnail URL (120px width) */
+    small?: string;
+    /** Medium thumbnail URL (240px width) */
+    medium?: string;
+    /** Large thumbnail URL (480px width) */
+    large?: string;
+}
+interface ISynovaFileAttachment {
+    /** Reference to uploaded file by ID */
+    fileId?: string;
+    /** File URL */
+    url?: string;
+    /** MIME type (e.g., 'image/png', 'application/pdf') */
+    mimeType?: string;
+    /** Thumbnail URLs for images */
+    thumbnails?: ISynovaFileThumbnails;
+}
+interface ISynovaExecuteResponse {
+    type: TSynovaResponseType;
+    /** Text content (when type='message') */
+    content?: string;
+    /** Structured output object (when responseSchema provided) */
+    object?: unknown;
+    /** Tool calls requested by LLM (when type='tool_calls') */
+    toolCalls?: ISynovaToolCall[];
+    /** Generated files/images (when type='image') */
+    files?: ISynovaFileAttachment[];
+    /** Error details (when type='error') */
+    error?: ISynovaExecutionError;
+    /** Token usage statistics */
+    usage?: ISynovaUsage;
+}
+interface ISynovaModelCapabilities {
+    text_generation?: boolean;
+    function_calling?: boolean;
+    vision?: boolean;
+    json_mode?: boolean;
+    streaming?: boolean;
+    reasoning?: boolean;
+    extended_thinking?: boolean;
+    text_to_image?: boolean;
+    image_to_image?: boolean;
+}
+interface ISynovaModelLimits {
+    context_window?: number;
+    max_output_tokens?: number;
+}
+interface ISynovaModelPricing {
+    effective_from: string;
+    input?: number;
+    output?: number;
+    per_image?: number;
+}
+interface ISynovaModel {
+    id: string;
+    provider: string;
+    display_name: string;
+    type: TSynovaModelType;
+    capabilities: ISynovaModelCapabilities;
+    limits: ISynovaModelLimits;
+    pricing?: ISynovaModelPricing[];
+    deprecated_from?: string;
+}
+interface ISynovaProvider {
+    id: string;
+    display_name: string;
+    models: ISynovaModel[];
+}
+interface ISynovaModelsResponse {
+    providers: ISynovaProvider[];
+}
+interface ISynovaListModelsOptions {
+    /** Filter by model type */
+    type?: TSynovaModelType;
+    /** Filter by capability */
+    capability?: keyof ISynovaModelCapabilities;
+    /** Filter by provider */
+    provider?: string;
+}
+interface ISynovaUploadedFile {
+    /** File ID */
+    id: string;
+    /** URL for file access */
+    url: string;
+    /** Thumbnail URL for preview */
+    thumbnailUrl?: string;
+    /** Original file name */
+    originalName: string;
+    /** MIME type (e.g., 'image/png', 'application/pdf') */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** File category ('image', 'video', 'audio', 'document', 'other') */
+    fileCategory: string;
+    /** Creation date (ISO 8601) */
+    createdAt: string;
+}
+interface ISynovaUploadResponse {
+    /** Uploaded files */
+    data: ISynovaUploadedFile[];
+}
+interface ISynovaUploadOptions {
+    /** Project ID to associate files with */
+    projectId: string;
+}
+interface IApiErrorResponse {
+    code: string;
+    httpCode: number;
+    message: string;
+    requestId: string;
+    timestamp: string;
+}
+
+interface IRetryOptions {
+    maxRetries: number;
+    strategy: TSynovaRetryStrategy;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+}
+interface IHttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    retry: IRetryOptions;
+    debug: boolean;
+    logger: ISynovaLogger;
+}
+interface IRequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | undefined>;
+}
+interface IUploadOptions {
+    path: string;
+    formData: FormData;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: IHttpClientConfig);
+    request<T>(options: IRequestOptions): Promise<T>;
+    upload<T>(options: IUploadOptions): Promise<T>;
+    private makeRequest;
+    private makeUploadRequest;
+    private handleErrorResponse;
+    private buildUrl;
+    private isRetryable;
+    private calculateRetryDelay;
+    private sleep;
+    private log;
+}
+
+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
+     *
+     * @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' });
+     * ```
+     */
+    get(promptId: string, options?: ISynovaGetPromptOptions): Promise<ISynovaPrompt>;
+    /**
+     * Execute a prompt with 'latest' tag
+     *
+     * @param promptId - The prompt ID
+     * @param options - Execution options including provider, model and variables
+     * @returns The execution response
+     *
+     * @example
+     * ```ts
+     * 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
+     *
+     * @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
+     *
+     * @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>;
+}
+
+declare class ModelsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all available models
+     *
+     * @param options - Optional filters
+     * @returns List of providers with their models
+     *
+     * @example
+     * ```ts
+     * // Get all models
+     * const { providers } = await client.models.list();
+     *
+     * // Filter by type
+     * const imageModels = await client.models.list({ type: 'image' });
+     *
+     * // Filter by capability
+     * const functionCallingModels = await client.models.list({
+     *   capability: 'function_calling',
+     * });
+     *
+     * // Filter by provider
+     * const openaiModels = await client.models.list({ provider: 'openai' });
+     * ```
+     */
+    list(options?: ISynovaListModelsOptions): Promise<ISynovaModelsResponse>;
+    /**
+     * Get models for a specific provider
+     *
+     * @param provider - Provider ID (e.g., 'openai', 'anthropic')
+     * @returns List of models for the provider
+     *
+     * @example
+     * ```ts
+     * const { models } = await client.models.getByProvider('openai');
+     * ```
+     */
+    getByProvider(provider: string): Promise<ISynovaModel[]>;
+    /**
+     * Get a specific model
+     *
+     * @param provider - Provider ID
+     * @param model - Model ID
+     * @returns Model details
+     *
+     * @example
+     * ```ts
+     * const model = await client.models.get('openai', 'gpt-4o');
+     * console.log(model.capabilities);
+     * console.log(model.limits);
+     * ```
+     */
+    get(provider: string, model: string): Promise<ISynovaModel>;
+}
+
+declare class FilesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Upload files for use in prompt execution
+     *
+     * @param files - Array of File or Blob objects to upload
+     * @param options - Upload options including projectId
+     * @returns Upload response with file metadata
+     *
+     * @example
+     * ```ts
+     * // Upload files
+     * const result = await client.files.upload(
+     *   [file1, file2],
+     *   { projectId: 'prj_abc123' }
+     * );
+     *
+     * console.log('Uploaded files:', result.data);
+     *
+     * // Use uploaded file in prompt execution
+     * const response = await client.prompts.execute('prm_abc123', {
+     *   provider: 'openai',
+     *   model: 'gpt-4o',
+     *   messages: [
+     *     {
+     *       role: 'user',
+     *       content: 'Describe this image',
+     *       files: [{ fileId: result.data[0].id }],
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    upload(files: (File | Blob)[], options: ISynovaUploadOptions): Promise<ISynovaUploadResponse>;
+}
+
+/**
+ * Synova Cloud SDK client
+ *
+ * @example
+ * ```ts
+ * import { SynovaCloudSdk } from '@synova-cloud/sdk';
+ *
+ * const client = new SynovaCloudSdk('your-api-key');
+ *
+ * // Get a prompt
+ * const prompt = await client.prompts.get('prm_abc123');
+ *
+ * // Execute a prompt
+ * const result = await client.prompts.execute('prm_abc123', {
+ *   provider: 'openai',
+ *   model: 'gpt-4o',
+ *   variables: { topic: 'TypeScript' },
+ * });
+ *
+ * // List available models
+ * const { providers } = await client.models.list();
+ *
+ * // Get models for a specific provider
+ * const openaiModels = await client.models.getByProvider('openai');
+ *
+ * // With custom retry config
+ * const clientWithRetry = new SynovaCloudSdk('your-api-key', {
+ *   retry: {
+ *     maxRetries: 5,
+ *     strategy: 'linear',
+ *     initialDelayMs: 500,
+ *   },
+ * });
+ * ```
+ */
+declare class SynovaCloudSdk {
+    readonly prompts: PromptsResource;
+    readonly models: ModelsResource;
+    readonly files: FilesResource;
+    private readonly http;
+    /**
+     * Create a new Synova Cloud SDK client
+     *
+     * @param apiKey - Your Synova API key
+     * @param config - Optional configuration
+     */
+    constructor(apiKey: string, config?: ISynovaConfig);
+}
+
+/**
+ * Base error class for all Synova SDK errors
+ */
+declare class SynovaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when API returns an error response
+ */
+declare class ApiSynovaError extends SynovaError {
+    readonly code: string;
+    readonly httpCode: number;
+    readonly requestId: string;
+    readonly timestamp: string;
+    constructor(response: IApiErrorResponse);
+}
+/**
+ * Error thrown when authentication fails
+ */
+declare class AuthSynovaError extends SynovaError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when resource is not found
+ */
+declare class NotFoundSynovaError extends SynovaError {
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string);
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+declare class RateLimitSynovaError extends SynovaError {
+    readonly retryAfterMs?: number;
+    constructor(message?: string, retryAfterMs?: number);
+}
+/**
+ * Error thrown when request times out
+ */
+declare class TimeoutSynovaError extends SynovaError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Error thrown when network request fails
+ */
+declare class NetworkSynovaError extends SynovaError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when server returns 5xx error
+ */
+declare class ServerSynovaError extends SynovaError {
+    readonly httpCode: number;
+    readonly retryable: boolean;
+    constructor(httpCode: number, message?: string);
+}
+
+export { ApiSynovaError, AuthSynovaError, type ISynovaConfig, type ISynovaExecuteOptions, type ISynovaExecuteResponse, type ISynovaExecutionError, 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 ISynovaRetryConfig, type ISynovaToolCall, type ISynovaToolResult, type ISynovaUploadOptions, type ISynovaUploadResponse, type ISynovaUploadedFile, type ISynovaUsage, NetworkSynovaError, NotFoundSynovaError, RateLimitSynovaError, ServerSynovaError, SynovaCloudSdk, SynovaError, type TSynovaMessageRole, type TSynovaModelType, type TSynovaResponseType, type TSynovaRetryStrategy, TimeoutSynovaError };