@amaster.ai/client 1.1.0-beta.7 → 1.1.0-beta.71

package/types/index.d.ts

@@ -1,44 +1,40 @@
 /**
- * ============================================================================
- * @amaster.ai/client - Unified API Client
- * ============================================================================
- * 
- * A Supabase-inspired unified client for the Amaster platform.
- * 
+ *  * A Supabase-inspired unified client for the Amaster platform.
+ *
  * ## Features
  * - Single client instance for all services (auth, entity, bpm, workflow)
  * - Automatic token management and refresh
  * - Auto-attach authentication to all requests
  * - Centralized error handling
- * 
+ *
  * ## Quick Start
  * ```typescript
  * import { createClient } from '@amaster.ai/client';
- * 
+ *
  * const client = createClient({
  *   baseURL: 'https://api.amaster.ai',
  *   onUnauthorized: () => window.location.href = '/login'
  * });
- * 
+ *
  * // Login
  * await client.auth.login({ email, password });
- * 
+ *
  * // All subsequent requests automatically include auth token
  * await client.entity.list('default', 'users');
  * await client.bpm.startProcess('approval', {});
  * ```
- * 
+ *
  * ## Module Documentation
  * For detailed API documentation, see individual module type definitions:
  * - **Authentication**: {@link ./auth/index.d.ts} (split into user, password-auth, code-auth, oauth, permissions, profile)
  * - **Entity Operations**: {@link ./entity.d.ts}
  * - **BPM (Business Process)**: {@link ./bpm.d.ts}
  * - **Workflow Execution**: {@link ./workflow.d.ts}
- * 
+ *
  * ## AI-Friendly Type Structure
  * This package provides modular type definitions optimized for AI tools and large language models.
  * Types are split into focused modules that can be loaded on-demand:
- * 
+ *
  * **Authentication Types** (70-88% token savings):
  * - `@amaster.ai/client/auth/user` - User types (100 lines)
  * - `@amaster.ai/client/auth/password-auth` - Login/register (200 lines)
@@ -46,507 +42,293 @@
  * - `@amaster.ai/client/auth/oauth` - OAuth providers (120 lines)
  * - `@amaster.ai/client/auth/permissions` - Permission helpers (80 lines)
  * - `@amaster.ai/client/auth/profile` - Profile management (100 lines)
- * 
- * @packageDocumentation
- */
+ * */
 
-import type { AuthClientAPI } from './auth/index';
-import type { EntityClientAPI } from './entity';
-import type { BpmClientAPI } from './bpm';
-import type { WorkflowClientAPI } from './workflow';
-import type { ASRClient } from './asr';
-import type { CopilotA2UIClient } from './copilot';
-import type { FunctionClient } from './function';
-import type { TTSClient } from './tts';
+import type { AuthClientAPI } from "./auth/index";
+import type { EntityClientAPI } from "./entity";
+import type { BpmClientAPI } from "./bpm";
+import type { WorkflowClientAPI } from "./workflow";
+import type { ASRClientConfig, ASRClient, ASRHttpClientConfig, ASRHttpClient } from "./asr";
+import type { CopilotClientAPI } from "./copilot";
+import type { FunctionClientAPI } from "./function";
+import type { TTSClientAPI } from "./tts";
+import type { S3ClientAPI } from "./s3";
+import type { HttpClient } from "./http";
 
 /**
  * Configuration options for creating an Amaster client
- * 
- * @example
- * Basic configuration:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai'
- * });
- * ```
- * 
- * @example
- * With authentication callbacks:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   onUnauthorized: () => {
- *     console.log('User is not authenticated');
- *     window.location.href = '/login';
- *   },
- *   onTokenExpired: () => {
- *     console.log('Token expired, refreshing...');
- *   }
- * });
- * ```
- * 
- * @example
- * With custom headers:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   headers: {
- *     'X-Tenant-ID': 'tenant-123',
- *     'X-App-Version': '1.0.0'
- *   }
- * });
- * ```
+ *
  */
 export interface AmasterClientOptions {
   /**
    * Base URL for the Amaster API
-   * 
-   * @example 'https://api.amaster.ai'
-   * @example 'https://my-app.amaster.ai'
+   *
    */
   baseURL: string;
 
   /**
    * Optional custom headers to include in ALL requests
-   * 
+   *
    * These headers will be merged with authentication headers.
    * Useful for tenant IDs, API keys, or application metadata.
-   * 
-   * @example
-   * ```typescript
-   * {
-   *   'X-Tenant-ID': 'tenant-123',
-   *   'X-App-Version': '1.0.0',
-   *   'X-Custom-Header': 'custom-value'
-   * }
-   * ```
+   *
    */
   headers?: Record<string, string>;
 
   /**
    * Callback triggered when a 401 Unauthorized response is received
-   * 
+   *
    * Use this to redirect to login page or show authentication modal.
    * This callback is invoked BEFORE the request promise rejects.
-   * 
-   * @example
-   * Redirect to login page:
-   * ```typescript
-   * onUnauthorized: () => {
-   *   window.location.href = '/login';
-   * }
-   * ```
-   * 
-   * @example
-   * Show modal:
-   * ```typescript
-   * onUnauthorized: () => {
-   *   showLoginModal();
-   * }
-   * ```
+   *
    */
   onUnauthorized?: () => void;
 
   /**
    * Callback triggered when the access token expires
-   * 
+   *
    * Note: Token refresh is handled automatically by the client.
    * This callback is for additional actions like logging or analytics.
-   * 
-   * @example
-   * ```typescript
-   * onTokenExpired: () => {
-   *   console.log('Token expired, auto-refreshing...');
-   *   analytics.track('token_expired');
-   * }
-   * ```
+   *
    */
   onTokenExpired?: () => void;
 
   /**
    * Enable automatic token refresh (default: true)
-   * 
+   *
    * When enabled, tokens are automatically refreshed before expiry.
-   * 
+   *
    * @default true
    */
   autoRefresh?: boolean;
 
   /**
    * Token refresh threshold in seconds (default: 300)
-   * 
+   *
    * Tokens will be refreshed this many seconds before expiry.
    * For example, if set to 300 (5 minutes), a token expiring at
    * 10:00:00 will be refreshed at 9:55:00.
-   * 
+   *
    * @default 300
    */
   refreshThreshold?: number;
+
+  /**
+   * Auto-handle OAuth callback on page load (default: true)
+   *
+   * Automatically detects and processes `#access_token` in URL hash,
+   * then clears the hash for security. Set to `false` to manually
+   * call `client.auth.handleOAuthCallback()`.
+   *
+   * @default true
+   */
+  autoHandleOAuthCallback?: boolean;
 }
 
 /**
  * Unified Amaster Client interface
- * 
+ *
  * This is the main client object returned by `createClient()`.
  * It provides access to all Amaster services through a unified interface.
- * 
+ *
  * ## Core Modules
  * - {@link auth} - Authentication and user management
  * - {@link entity} - CRUD operations for entities
  * - {@link bpm} - Business process management
  * - {@link workflow} - Workflow execution
- * 
+ *
  * ## Token Management
  * - {@link isAuthenticated} - Check if user is authenticated
  * - {@link getAccessToken} - Get current access token
  * - {@link setAccessToken} - Set access token manually
  * - {@link clearAuth} - Clear all authentication state
- * 
- * @example
- * Complete authentication flow:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // 1. Login
- * await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password123'
- * });
- * 
- * // 2. Check authentication
- * if (client.isAuthenticated()) {
- *   console.log('User is logged in');
- * }
- * 
- * // 3. Get current token
- * const token = client.getAccessToken();
- * 
- * // 4. Use any service (token automatically attached)
- * const users = await client.entity.list('default', 'users');
- * 
- * // 5. Logout
- * await client.auth.logout();
- * ```
+ *
  */
 export interface AmasterClient {
   /**
    * Authentication module
-   * 
+   *
    * Provides methods for user authentication, registration, and management.
-   * 
+   *
    * For detailed documentation, see {@link ./auth.d.ts}
-   * 
-   * @example
-   * Login:
-   * ```typescript
-   * await client.auth.login({
-   *   email: 'user@example.com',
-   *   password: 'password123'
-   * });
-   * ```
-   * 
-   * @example
-   * Register:
-   * ```typescript
-   * await client.auth.register({
-   *   username: 'johndoe',
-   *   email: 'john@example.com',
-   *   password: 'Password@123'
-   * });
-   * ```
-   * 
-   * @example
-   * Get current user:
-   * ```typescript
-   * const result = await client.auth.getMe();
-   * console.log(result.data); // User object
-   * ```
+   *
    */
   auth: AuthClientAPI;
 
   /**
    * Entity CRUD operations module
-   * 
+   *
    * Provides methods for creating, reading, updating, and deleting entities.
-   * 
+   *
    * For detailed documentation, see {@link ./entity.d.ts}
-   * 
-   * @example
-   * List entities:
-   * ```typescript
-   * const result = await client.entity.list('default', 'users', {
-   *   page: 1,
-   *   perPage: 20,
-   *   orderBy: 'createdAt',
-   *   orderDir: 'desc'
-   * });
-   * ```
-   * 
-   * @example
-   * Create entity:
-   * ```typescript
-   * await client.entity.create('default', 'users', {
-   *   name: 'John Doe',
-   *   email: 'john@example.com'
-   * });
-   * ```
+   *
    */
   entity: EntityClientAPI;
 
   /**
    * Business Process Management (BPM) module
-   * 
+   *
    * Provides methods for managing BPMN processes and tasks.
-   * 
+   *
    * For detailed documentation, see {@link ./bpm.d.ts}
-   * 
-   * @example
-   * Start a process:
-   * ```typescript
-   * const result = await client.bpm.startProcess('approval', {
-   *   amount: { value: 1000, type: 'Long' },
-   *   requester: { value: 'user-123', type: 'String' }
-   * });
-   * ```
-   * 
-   * @example
-   * Get tasks:
-   * ```typescript
-   * const tasks = await client.bpm.getTasks({
-   *   assignee: 'user-123',
-   *   processDefinitionKey: 'approval'
-   * });
-   * ```
+   *
    */
   bpm: BpmClientAPI;
 
   /**
    * Workflow execution module
-   * 
+   *
    * Provides methods for executing Dify-style workflows.
-   * 
+   *
    * For detailed documentation, see {@link ./workflow.d.ts}
-   * 
-   * @example
-   * Run a workflow:
-   * ```typescript
-   * const result = await client.workflow.run('data-analysis', {
-   *   input_data: 'sample data',
-   *   options: { format: 'json' }
-   * });
-   * console.log(result.data.outputs);
-   * ```
+   *
    */
   workflow: WorkflowClientAPI;
 
   /**
    * ASR (Automatic Speech Recognition) module
-   * 
+   *
    * Provides methods for real-time speech-to-text conversion via WebSocket.
-   * 
+   *
    * For detailed documentation, see {@link ./asr.d.ts}
    */
-  asr: ASRClient;
+  asr: (config: ASRClientConfig) => ASRClient;
+
+  /**
+   * ASR HTTP module
+   *
+   * Provides methods for speech-to-text conversion via HTTP API.
+   *
+   * For detailed documentation, see
+   */
+  asrHttp: (config: ASRHttpClientConfig) => ASRHttpClient;
 
   /**
    * Copilot AI Assistant module
-   * 
-   * Provides methods for interactive AI conversations with A2UI streaming.
-   * 
+   *
+   * Provides methods for interactive AI conversations with a2a streaming.
+   *
    * For detailed documentation, see {@link ./copilot.d.ts}
-   * 
-   * @example
-   * Chat with AI:
-   * ```typescript
-   * const stream = client.copilot.chat([
-   *   { role: 'user', content: 'Hello' }
-   * ]);
-   * 
-   * for await (const messages of stream) {
-   *   // Process A2UI messages
-   * }
-   * ```
+   *
    */
-  copilot: CopilotA2UIClient;
+  copilot: CopilotClientAPI;
 
   /**
    * Serverless Function module
-   * 
+   *
    * Provides methods for invoking serverless functions.
-   * 
+   *
    * For detailed documentation, see {@link ./function.d.ts}
    */
-  function: FunctionClient;
+  function: FunctionClientAPI;
 
   /**
    * TTS (Text-to-Speech) module
-   * 
+   *
    * Provides methods for real-time text-to-speech conversion via WebSocket.
-   * 
+   *
    * For detailed documentation, see {@link ./tts.d.ts}
    */
-  tts: TTSClient;
+  tts: TTSClientAPI;
 
   /**
-   * Check if the user is currently authenticated
-   * 
-   * @returns `true` if a valid access token exists, `false` otherwise
-   * 
-   * @example
+   * S3 Storage module
+   *
+   * Provides methods for file upload, download, and management.
+   *
+   * For detailed documentation, see {@link ./s3.d.ts}
+   */
+  s3: S3ClientAPI;
+
+  /**
+   * HTTP client instance used for all requests
+   *
+   * This is the underlying HTTP client that handles all API requests.
+   * It automatically includes authentication headers and base URL.
+   * You can use this client to make custom requests to the Amaster API
+   * or your own backend while still benefiting from automatic token management.
+     * For example:
    * ```typescript
-   * if (client.isAuthenticated()) {
-   *   console.log('User is logged in');
-   * } else {
-   *   console.log('Please log in');
-   * }
+   * const response = await client.http.request({
+   *   url: '/api/custom-endpoint',
+   *   method: 'POST',
+   *   data: { key: 'value' }
+   * });
+   * console.log(response.data);
    * ```
+     * Note: The `http` client is an instance of the same HTTP client used internally by the Amaster client.
+   * It automatically includes the base URL and authentication headers configured in `createClient()`.
+   */
+  http: HttpClient;
+
+  /**
+   * Check if the user is currently authenticated
+   *
+   * @returns `true` if a valid access token exists, `false` otherwise
+   *
    */
   isAuthenticated(): boolean;
 
   /**
    * Get the current access token
-   * 
+   *
    * @returns The access token string, or `null` if not authenticated
-   * 
-   * @example
-   * ```typescript
-   * const token = client.getAccessToken();
-   * if (token) {
-   *   console.log('Token:', token);
-   * }
-   * ```
-   * 
-   * @example
-   * Store token for later use:
-   * ```typescript
-   * const token = client.getAccessToken();
-   * if (token) {
-   *   localStorage.setItem('backup_token', token);
-   * }
-   * ```
+   *
    */
   getAccessToken(): string | null;
 
   /**
    * Manually set the access token
-   * 
+   *
    * Useful when you have a token from another source (e.g., SSO, OAuth).
    * After setting the token, all requests will use it automatically.
-   * 
+   *
    * @param token - The JWT access token to set
-   * 
-   * @example
-   * Set token from OAuth:
-   * ```typescript
-   * const ssoToken = await getSSOToken();
-   * client.setAccessToken(ssoToken);
-   * 
-   * // Now all requests will use this token
-   * await client.entity.list('default', 'users');
-   * ```
-   * 
-   * @example
-   * Restore token from storage:
-   * ```typescript
-   * const savedToken = localStorage.getItem('auth_token');
-   * if (savedToken) {
-   *   client.setAccessToken(savedToken);
-   * }
-   * ```
+   *
    */
   setAccessToken(token: string): void;
 
   /**
    * Clear all authentication state
-   * 
+   *
    * This removes:
    * - Access token
    * - User information
    * - Auto-refresh timers
-   * 
+   *
    * After calling this, `isAuthenticated()` will return `false`
    * and all requests will be unauthenticated.
-   * 
-   * @example
-   * ```typescript
-   * client.clearAuth();
-   * console.log(client.isAuthenticated()); // false
-   * console.log(client.getAccessToken());  // null
-   * ```
-   * 
-   * @example
-   * Logout without API call:
-   * ```typescript
-   * // If you want to clear local state without calling logout API
-   * client.clearAuth();
-   * window.location.href = '/login';
-   * ```
+   *
    */
   clearAuth(): void;
 }
 
 /**
  * Factory function to create a unified Amaster client
- * 
+ *
  * This is the main entry point for using the Amaster client library.
  * It returns a client instance that provides access to all Amaster services.
- * 
+ *
  * @param options - Configuration options for the client
  * @returns A configured Amaster client instance
- * 
- * @example
- * Basic usage:
- * ```typescript
- * import { createClient } from '@amaster.ai/client';
- * 
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai'
- * });
- * 
- * await client.auth.login({ email, password });
- * ```
- * 
- * @example
- * With callbacks:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   onUnauthorized: () => {
- *     console.log('Session expired');
- *     window.location.href = '/login';
- *   },
- *   onTokenExpired: () => {
- *     console.log('Token expired, refreshing...');
- *   }
- * });
- * ```
- * 
- * @example
- * With custom headers:
- * ```typescript
- * const client = createClient({
- *   baseURL: 'https://api.amaster.ai',
- *   headers: {
- *     'X-Tenant-ID': 'tenant-123',
- *     'X-App-Version': '1.0.0'
- *   }
- * });
- * ```
+ *
  */
 export declare function createClient(options: AmasterClientOptions): AmasterClient;
 
 // Re-export shared common types
-export type { ClientResult } from './common';
+export type { ClientResult } from "./common";
 
 // Re-export main client interfaces
-export type { AuthClientAPI } from './auth';
-export type { EntityClientAPI } from './entity';
-export type { BpmClientAPI } from './bpm';
-export type { WorkflowClientAPI } from './workflow';
-export type { ASRClient } from './asr';
-export type { CopilotA2UIClient } from './copilot';
-export type { FunctionClient } from './function';
-export type { TTSClient } from './tts';
+export type { AuthClientAPI } from "./auth";
+export type { EntityClientAPI } from "./entity";
+export type { BpmClientAPI } from "./bpm";
+export type { WorkflowClientAPI } from "./workflow";
+export type { ASRClient, ASRClientConfig, ASRHttpClient, ASRHttpClientConfig, Recorder, RecorderOptions } from "./asr";
+export type { CopilotClientAPI } from "./copilot";
+export type { FunctionClientAPI } from "./function";
+export type { TTSClientAPI } from "./tts";
+export type { S3ClientAPI } from "./s3";
+export type { HttpClient } from "./http";
 
 // For detailed types, import directly from submodules:
 // import type { LoginParams, User } from '@amaster.ai/client/auth'