@amaster.ai/client 1.1.0-beta.5 → 1.1.0-beta.51

package/types/s3.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 
+ * @module s3
+ */
+
+import type { ClientResult } from './common';
+
+// ==================== Response Types ====================
+
+/**
+ * Upload response data
+ *
+ */
+export interface UploadRes {
+  /** File key in storage */
+  key: string;
+  /** Full access URL */
+  url: string;
+}
+
+/**
+ * File metadata
+ *
+ */
+export interface S3Metadata {
+  contentType?: string;
+  contentLength?: number;
+  lastModified?: string;
+  [key: string]: any;
+}
+
+// ==================== S3 Client API ====================
+
+/**
+ * S3 Storage Client API
+ * 
+ * Provides methods for uploading, downloading, and managing files in object storage.
+ * 
+ * @since 1.0.0
+ */
+export interface S3ClientAPI {
+  /**
+   * Download a file
+   * 
+   * @param filename - The name/key of the file to download
+   * @returns Blob data of the file
+   * 
+   * @example
+   * const result = await client.s3.download('documents/report.pdf');
+   * if (result.success) {
+   *   const blob = result.data;
+   *   const url = URL.createObjectURL(blob);
+   *   window.open(url);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  download(filename: string): Promise<ClientResult<Blob>>;
+
+  /**
+   * Get metadata for a file
+   * 
+   * @param key - The key of the file
+   * @returns File metadata
+   * 
+   * @example
+   * const result = await client.s3.getMetadata('images/photo.jpg');
+   * if (result.success) {
+   *   console.log('Size:', result.data.contentLength);
+   *   console.log('Type:', result.data.contentType);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  getMetadata(key: string): Promise<ClientResult<S3Metadata>>;
+
+  /**
+   * Upload a file
+   * 
+   * @param file - The file to upload (File or Blob)
+   * @returns Upload result containing key and URL
+   * 
+   * @example
+   * const fileInput = document.querySelector('input[type="file"]');
+   * const file = fileInput.files[0];
+   * 
+   * const result = await client.s3.upload(file);
+   * if (result.success) {
+   *   console.log('File uploaded:', result.data.url);
+   *   console.log('File key:', result.data.key);
+   * }
+   * 
+   * @since 1.0.0
+   */
+  upload(file: File | Blob): Promise<ClientResult<UploadRes>>;
+}

package/types/tts.d.ts

@@ -1,35 +1,14 @@
 /**
- * ============================================================================
- * TTS (Text-to-Speech) - Type Definitions
- * ============================================================================
- * 
- * Real-time text-to-speech synthesis using WebSocket connection.
+ *  * Real-time text-to-speech synthesis using WebSocket connection.
  * 
  * @module tts
  */
 
 /**
  * TTS Client Configuration
- * 
- * @example
- * Configure TTS with custom voice:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Reconfigure TTS client
- * client.tts = createTTSClient({
- *   voice: 'Cherry',
- *   audioFormat: 'pcm',
- *   sampleRate: 24000,
- *   autoPlay: true,
- *   onAudioStart: () => console.log('Audio started'),
- *   onAudioEnd: () => console.log('Audio ended')
- * });
- * ```
+ *
  */
 export interface TTSClientConfig {
-  /** WebSocket path override */
-  path?: string;
   
   /** Voice name, default 'Cherry' */
   voice?: string;
@@ -63,75 +42,20 @@ export interface TTSClientConfig {
 }
 
 /**
- * TTS Client API
- * 
- * Real-time text-to-speech synthesis client using WebSocket.
- * 
- * @example
- * Basic usage:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Connect to TTS service
- * await client.tts.connect();
- * 
- * // Synthesize and play speech
- * await client.tts.speak('Hello, welcome to Amaster!');
- * 
- * // Close connection when done
- * client.tts.close();
- * ```
- * 
- * @example
- * With custom voice and callbacks:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * client.tts = createTTSClient({
- *   voice: 'Cherry',
- *   autoPlay: true,
- *   onReady: () => console.log('TTS ready'),
- *   onAudioStart: () => console.log('Playing audio'),
- *   onAudioEnd: () => console.log('Audio finished'),
- *   onError: (error) => console.error('TTS error:', error)
- * });
+ * TTS (Text-to-Speech) Client API
  * 
- * await client.tts.connect();
- * await client.tts.speak('This is a test message');
- * ```
+ * Provides real-time text-to-speech synthesis via WebSocket.
  * 
- * @example
- * Manual audio playback:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * client.tts = createTTSClient({
- *   autoPlay: false,
- *   onAudioChunk: (chunks) => {
- *     console.log(`Received ${chunks.length} audio chunks`);
- *   }
- * });
- * 
- * await client.tts.connect();
- * await client.tts.speak('Hello world');
- * 
- * // Manually play collected audio
- * client.tts.play();
- * ```
+ * @since 1.0.0
  */
-export interface TTSClient {
+export interface TTSClientAPI {
   /**
    * Connect to TTS service
    * 
    * Establishes WebSocket connection to the text-to-speech service.
    * 
    * @returns Promise that resolves when connected
-   * 
-   * @example
-   * ```typescript
-   * await client.tts.connect();
-   * console.log('Connected to TTS service');
-   * ```
+   *
    */
   connect(): Promise<void>;
 
@@ -142,37 +66,7 @@ export interface TTSClient {
    * 
    * @param text - Text to synthesize
    * @returns Promise that resolves when synthesis starts
-   * 
-   * @example
-   * Simple text:
-   * ```typescript
-   * await client.tts.speak('Hello, how can I help you today?');
-   * ```
-   * 
-   * @example
-   * Multiple sentences:
-   * ```typescript
-   * await client.tts.speak(
-   *   'Welcome to our service. ' +
-   *   'We are glad to have you here. ' +
-   *   'Let me know if you need any assistance.'
-   * );
-   * ```
-   * 
-   * @example
-   * Sequential playback:
-   * ```typescript
-   * await client.tts.speak('First message');
-   * // Wait for first message to complete
-   * await new Promise(resolve => {
-   *   const originalOnEnd = client.tts.onAudioEnd;
-   *   client.tts.onAudioEnd = () => {
-   *     resolve(undefined);
-   *     client.tts.onAudioEnd = originalOnEnd;
-   *   };
-   * });
-   * await client.tts.speak('Second message');
-   * ```
+   *
    */
   speak(text: string): Promise<void>;
 
@@ -180,16 +74,7 @@ export interface TTSClient {
    * Play audio from chunks
    * 
    * Manually plays audio chunks when autoPlay is disabled.
-   * 
-   * @example
-   * ```typescript
-   * client.tts = createTTSClient({ autoPlay: false });
-   * await client.tts.connect();
-   * await client.tts.speak('Hello world');
-   * 
-   * // Manually trigger playback
-   * client.tts.play();
-   * ```
+   *
    */
   play(): void;
 
@@ -197,12 +82,7 @@ export interface TTSClient {
    * Close connection
    * 
    * Closes the WebSocket connection and releases resources.
-   * 
-   * @example
-   * ```typescript
-   * // Cleanup when done
-   * client.tts.close();
-   * ```
+   *
    */
   close(): void;
 }

package/types/workflow.d.ts

@@ -1,17 +1,4 @@
 /**
- * ============================================================================
- * Workflow Module - Type Definitions
- * ============================================================================
- * 
- * This module provides workflow execution capabilities using Dify-style
- * workflow engine.
- * 
- * ## Key Features
- * - Execute workflows with inputs
- * - Blocking or streaming execution modes
- * - File upload support
- * - Trace ID for debugging
- * - Auto-inject app_id from URL
  * 
  * @module workflow
  */
@@ -39,15 +26,7 @@ export type WorkflowInputValue =
 
 /**
  * Workflow file attachment
- * 
- * @example
- * ```typescript
- * const file: WorkflowFile = {
- *   name: 'document.pdf',
- *   type: 'application/pdf',
- *   url: 'https://cdn.example.com/document.pdf'
- * };
- * ```
+ *
  */
 export interface WorkflowFile {
   /** File name */
@@ -63,31 +42,7 @@ export interface WorkflowFile {
 /**
  * Workflow execution request parameters
  * 
- * @example
- * Simple execution:
- * ```typescript
- * const request: WorkflowRunRequest = {
- *   inputs: {
- *     query: 'What is the weather?',
- *     location: 'New York'
- *   }
- * };
- * ```
- * 
- * @example
- * With files:
- * ```typescript
- * const request: WorkflowRunRequest = {
- *   inputs: { action: 'analyze' },
- *   files: [{
- *     name: 'data.csv',
- *     type: 'text/csv',
- *     url: 'https://example.com/data.csv'
- *   }],
- *   user: 'user-123',
- *   trace_id: 'trace-abc-456'
- * };
- * ```
+ * @since 1.0.0
  */
 export interface WorkflowRunRequest {
   /** Input variables for the workflow */
@@ -112,22 +67,7 @@ export interface WorkflowRunRequest {
  * Workflow execution response
  * 
  * @template TOutput - The type of workflow outputs
- * 
- * @example
- * ```typescript
- * interface AnalysisOutput {
- *   summary: string;
- *   sentiment: 'positive' | 'negative' | 'neutral';
- *   keywords: string[];
- * }
- * 
- * const result = await client.workflow.run<AnalysisOutput>('text-analysis', {
- *   text: 'This is a great product!'
- * });
- * 
- * console.log(result.data.outputs.summary);
- * console.log(result.data.outputs.sentiment); // 'positive'
- * ```
+ *
  */
 export interface WorkflowRunResponse<TOutput = Record<string, unknown>> {
   /** Task ID */
@@ -136,7 +76,6 @@ export interface WorkflowRunResponse<TOutput = Record<string, unknown>> {
   workflow_run_id: string;
   /** 
    * Execution status
-   * @example 'succeeded', 'failed', 'running'
    */
   status: string;
   /** Workflow output data */
@@ -162,38 +101,7 @@ export interface WorkflowRunResponse<TOutput = Record<string, unknown>> {
  * 
  * Provides methods for executing Dify-style workflows.
  * 
- * @example
- * Complete workflow execution:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // 1. Simple text processing workflow
- * const result = await client.workflow.run('text-summarizer', {
- *   text: 'Long article content here...',
- *   max_words: 100
- * });
- * 
- * if (result.data) {
- *   console.log('Summary:', result.data.outputs.summary);
- *   console.log('Time taken:', result.data.elapsed_time, 'ms');
- *   console.log('Tokens used:', result.data.total_tokens);
- * }
- * 
- * // 2. Data analysis workflow with type safety
- * interface AnalysisOutput {
- *   insights: string[];
- *   score: number;
- *   recommendations: string[];
- * }
- * 
- * const analysis = await client.workflow.run<AnalysisOutput>('data-analyzer', {
- *   dataset: 'sales-2024',
- *   metric: 'revenue'
- * });
- * 
- * console.log('Insights:', analysis.data.outputs.insights);
- * console.log('Score:', analysis.data.outputs.score);
- * ```
+ * @since 1.0.0
  */
 export interface WorkflowClientAPI {
   /**
@@ -208,81 +116,24 @@ export interface WorkflowClientAPI {
    * @returns Workflow execution result
    * 
    * @example
-   * Simple execution with inputs:
-   * ```typescript
-   * const result = await client.workflow.run('greeting', {
-   *   name: 'Alice',
-   *   language: 'en'
+   * // Simple execution
+   * const result = await client.workflow.run('data-processor', {
+   *   source: 'users',
+   *   limit: 100
    * });
    * 
-   * console.log(result.data.outputs.message); // "Hello, Alice!"
-   * ```
-   * 
-   * @example
-   * With full request configuration:
-   * ```typescript
-   * const result = await client.workflow.run('document-processor', {
-   *   inputs: {
-   *     action: 'extract',
-   *     format: 'json'
-   *   },
-   *   files: [{
-   *     name: 'invoice.pdf',
-   *     url: 'https://example.com/invoice.pdf'
-   *   }],
-   *   user: 'user-123',
-   *   trace_id: 'req-abc-456'
-   * });
-   * ```
-   * 
-   * @example
-   * Type-safe outputs:
-   * ```typescript
-   * interface SentimentOutput {
-   *   sentiment: 'positive' | 'negative' | 'neutral';
-   *   confidence: number;
-   *   keywords: string[];
-   * }
-   * 
-   * const result = await client.workflow.run<SentimentOutput>('sentiment-analysis', {
-   *   text: 'I love this product! It works great.'
-   * });
-   * 
-   * if (result.data) {
-   *   // TypeScript knows the structure of outputs
-   *   console.log(result.data.outputs.sentiment);   // Type: 'positive' | 'negative' | 'neutral'
-   *   console.log(result.data.outputs.confidence);  // Type: number
-   *   console.log(result.data.outputs.keywords);    // Type: string[]
+   * if (result.success) {
+   *   console.log('Output:', result.data.outputs);
    * }
-   * ```
    * 
    * @example
-   * Error handling:
-   * ```typescript
-   * const result = await client.workflow.run('risky-workflow', { input: 'test' });
-   * 
-   * if (result.error) {
-   *   console.error('Workflow failed:', result.error.message);
-   * } else if (result.data.error) {
-   *   console.error('Workflow error:', result.data.error);
-   * } else {
-   *   console.log('Success:', result.data.outputs);
-   * }
-   * ```
-   * 
-   * @example
-   * Performance monitoring:
-   * ```typescript
-   * const startTime = Date.now();
-   * const result = await client.workflow.run('heavy-task', { data: largeDataset });
+   * // With type safety
+   * type Output = { processedCount: number; results: string[] };
+   * const result = await client.workflow.run<Output>('batch-processor', {
+   *   batchSize: 50
+   * });
    * 
-   * if (result.data) {
-   *   console.log(`Network time: ${Date.now() - startTime}ms`);
-   *   console.log(`Execution time: ${result.data.elapsed_time}ms`);
-   *   console.log(`Steps: ${result.data.total_steps}`);
-   *   console.log(`Tokens: ${result.data.total_tokens}`);
-   * }
-   * ```
+   * @since 1.0.0
    */
   run<TOutput = Record<string, unknown>>(
     workflowName: string,