@amaster.ai/client 1.1.0-beta.4 → 1.1.0-beta.41

package/types/tts.d.ts

@@ -1,31 +1,12 @@
 /**
- * ============================================================================
- * 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 */
@@ -63,75 +44,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 +68,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 +76,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 +84,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,

package/types/auth/permissions.d.ts

@@ -1,254 +0,0 @@
-/**
- * ============================================================================
- * Permission Checking - Type Definitions & Helpers
- * ============================================================================
- * 
- * Permission and role checking utilities:
- * - Type-safe permission checking
- * - Role validation
- * - Permission helpers
- * 
- * @module auth/permissions
- */
-
-import type { User } from './user';
-
-/**
- * Permission check result
- */
-export interface PermissionCheckResult {
-  /** Whether the permission check passed */
-  granted: boolean;
-  
-  /** Optional reason if denied */
-  reason?: string;
-}
-
-/**
- * Permission checking helpers
- * 
- * @example
- * Check single permission:
- * ```typescript
- * import { hasPermission } from '@amaster.ai/client/auth/permissions';
- * 
- * const user = await client.auth.getMe().then(r => r.data);
- * 
- * if (hasPermission(user, 'user:delete')) {
- *   showDeleteButton();
- * }
- * ```
- * 
- * @example
- * Check role:
- * ```typescript
- * import { hasRole } from '@amaster.ai/client/auth/permissions';
- * 
- * if (hasRole(user, 'admin')) {
- *   showAdminPanel();
- * }
- * ```
- * 
- * @example
- * Check any of multiple permissions:
- * ```typescript
- * import { hasAnyPermission } from '@amaster.ai/client/auth/permissions';
- * 
- * if (hasAnyPermission(user, ['user:read', 'user:write', 'user:delete'])) {
- *   showUserManagement();
- * }
- * ```
- */
-export namespace PermissionHelpers {
-  /**
-   * Check if user has a specific permission
-   * 
-   * @param user - User object with permissions
-   * @param permission - Permission to check (format: "resource:action")
-   * @returns True if user has the permission
-   * 
-   * @example
-   * ```typescript
-   * const canDelete = hasPermission(user, 'user:delete');
-   * const canRead = hasPermission(user, 'order:read');
-   * ```
-   */
-  export function hasPermission(user: User | null | undefined, permission: string): boolean;
-
-  /**
-   * Check if user has a specific role
-   * 
-   * @param user - User object with roles
-   * @param role - Role code to check
-   * @returns True if user has the role
-   * 
-   * @example
-   * ```typescript
-   * const isAdmin = hasRole(user, 'admin');
-   * const isManager = hasRole(user, 'manager');
-   * ```
-   */
-  export function hasRole(user: User | null | undefined, role: string): boolean;
-
-  /**
-   * Check if user has ANY of the specified permissions
-   * 
-   * @param user - User object with permissions
-   * @param permissions - Array of permissions to check
-   * @returns True if user has at least one permission
-   * 
-   * @example
-   * ```typescript
-   * // User can access if they have ANY of these permissions
-   * const canAccessUsers = hasAnyPermission(user, [
-   *   'user:read',
-   *   'user:write',
-   *   'user:delete'
-   * ]);
-   * ```
-   */
-  export function hasAnyPermission(user: User | null | undefined, permissions: string[]): boolean;
-
-  /**
-   * Check if user has ALL of the specified permissions
-   * 
-   * @param user - User object with permissions
-   * @param permissions - Array of permissions to check
-   * @returns True if user has all permissions
-   * 
-   * @example
-   * ```typescript
-   * // User needs ALL of these permissions
-   * const canManageUsers = hasAllPermissions(user, [
-   *   'user:read',
-   *   'user:write',
-   *   'user:delete'
-   * ]);
-   * ```
-   */
-  export function hasAllPermissions(user: User | null | undefined, permissions: string[]): boolean;
-
-  /**
-   * Check if user has ANY of the specified roles
-   * 
-   * @param user - User object with roles
-   * @param roles - Array of role codes to check
-   * @returns True if user has at least one role
-   * 
-   * @example
-   * ```typescript
-   * const isStaff = hasAnyRole(user, ['admin', 'moderator', 'support']);
-   * ```
-   */
-  export function hasAnyRole(user: User | null | undefined, roles: string[]): boolean;
-
-  /**
-   * Check if user has ALL of the specified roles
-   * 
-   * @param user - User object with roles
-   * @param roles - Array of role codes to check
-   * @returns True if user has all roles
-   * 
-   * @example
-   * ```typescript
-   * const isSuperAdmin = hasAllRoles(user, ['admin', 'superuser']);
-   * ```
-   */
-  export function hasAllRoles(user: User | null | undefined, roles: string[]): boolean;
-}
-
-/**
- * Re-export helpers as individual functions for convenience
- * 
- * @example
- * ```typescript
- * import { hasPermission, hasRole } from '@amaster.ai/client/auth/permissions';
- * 
- * const canDelete = hasPermission(user, 'user:delete');
- * const isAdmin = hasRole(user, 'admin');
- * ```
- */
-
-/**
- * Check if user has a specific permission
- * 
- * @param user - User object with permissions
- * @param permission - Permission to check (format: "resource:action")
- * @returns True if user has the permission
- * 
- * @example
- * ```typescript
- * const canDelete = hasPermission(user, 'user:delete');
- * ```
- */
-export declare function hasPermission(user: User | null | undefined, permission: string): boolean;
-
-/**
- * Check if user has a specific role
- * 
- * @param user - User object with roles
- * @param role - Role code to check
- * @returns True if user has the role
- * 
- * @example
- * ```typescript
- * const isAdmin = hasRole(user, 'admin');
- * ```
- */
-export declare function hasRole(user: User | null | undefined, role: string): boolean;
-
-/**
- * Check if user has ANY of the specified permissions
- * 
- * @param user - User object with permissions
- * @param permissions - Array of permissions to check
- * @returns True if user has at least one permission
- * 
- * @example
- * ```typescript
- * const canAccessUsers = hasAnyPermission(user, ['user:read', 'user:write']);
- * ```
- */
-export declare function hasAnyPermission(user: User | null | undefined, permissions: string[]): boolean;
-
-/**
- * Check if user has ALL of the specified permissions
- * 
- * @param user - User object with permissions
- * @param permissions - Array of permissions to check
- * @returns True if user has all permissions
- * 
- * @example
- * ```typescript
- * const canManageUsers = hasAllPermissions(user, ['user:read', 'user:write', 'user:delete']);
- * ```
- */
-export declare function hasAllPermissions(user: User | null | undefined, permissions: string[]): boolean;
-
-/**
- * Check if user has ANY of the specified roles
- * 
- * @param user - User object with roles
- * @param roles - Array of role codes to check
- * @returns True if user has at least one role
- * 
- * @example
- * ```typescript
- * const isStaff = hasAnyRole(user, ['admin', 'moderator']);
- * ```
- */
-export declare function hasAnyRole(user: User | null | undefined, roles: string[]): boolean;
-
-/**
- * Check if user has ALL of the specified roles
- * 
- * @param user - User object with roles
- * @param roles - Array of role codes to check
- * @returns True if user has all roles
- * 
- * @example
- * ```typescript
- * const isSuperAdmin = hasAllRoles(user, ['admin', 'superuser']);
- * ```
- */
-export declare function hasAllRoles(user: User | null | undefined, roles: string[]): boolean;