@amaster.ai/client 1.1.0-beta.3 → 1.1.0-beta.31

package/types/asr.d.ts

@@ -1,31 +1,12 @@
 /**
- * ============================================================================
- * ASR (Automatic Speech Recognition) - Type Definitions
- * ============================================================================
- * 
- * Real-time speech recognition using WebSocket connection.
+ *  * Real-time speech recognition using WebSocket connection.
  * 
  * @module asr
  */
 
 /**
  * ASR Client Configuration
- * 
- * @example
- * Configure ASR with custom voice settings:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Reconfigure ASR client
- * client.asr = createASRClient({
- *   audioFormat: 'pcm16',
- *   sampleRate: 16000,
- *   onTranscript: (text, isFinal) => {
- *     console.log(isFinal ? `Final: ${text}` : `Interim: ${text}`);
- *   },
- *   onError: (error) => console.error('ASR Error:', error)
- * });
- * ```
+ *
  */
 export interface ASRClientConfig {
   /** Audio format, default 'pcm16' */
@@ -61,78 +42,20 @@ export interface ASRClientConfig {
 }
 
 /**
- * ASR Client API
- * 
- * Real-time speech recognition client using WebSocket.
- * 
- * @example
- * Basic usage:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // Configure callbacks
- * client.asr = createASRClient({
- *   onTranscript: (text, isFinal) => {
- *     if (isFinal) {
- *       console.log('Final transcript:', text);
- *     } else {
- *       console.log('Interim transcript:', text);
- *     }
- *   }
- * });
- * 
- * // Connect and start recording
- * await client.asr.connect();
- * await client.asr.startRecording();
+ * ASR (Automatic Speech Recognition) Client API
  * 
- * // Stop recording
- * client.asr.stopRecording();
+ * Provides real-time speech-to-text conversion via WebSocket.
  * 
- * // Close connection
- * client.asr.close();
- * ```
- * 
- * @example
- * With error handling:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * client.asr = createASRClient({
- *   onReady: () => console.log('ASR ready'),
- *   onSpeechStart: () => console.log('Speech detected'),
- *   onSpeechEnd: () => console.log('Speech ended'),
- *   onTranscript: (text, isFinal) => {
- *     console.log(isFinal ? `[FINAL] ${text}` : `[INTERIM] ${text}`);
- *   },
- *   onError: (error) => {
- *     console.error('ASR Error:', error.message);
- *   },
- *   onClose: () => {
- *     console.log('ASR connection closed');
- *   }
- * });
- * 
- * try {
- *   await client.asr.connect();
- *   await client.asr.startRecording();
- * } catch (error) {
- *   console.error('Failed to start ASR:', error);
- * }
- * ```
+ * @since 1.0.0
  */
-export interface ASRClient {
+export interface ASRClientAPI {
   /**
    * Connect to ASR service
    * 
    * Establishes WebSocket connection to the speech recognition service.
    * 
    * @returns Promise that resolves when connected
-   * 
-   * @example
-   * ```typescript
-   * await client.asr.connect();
-   * console.log('Connected to ASR service');
-   * ```
+   *
    */
   connect(): Promise<void>;
 
@@ -143,19 +66,7 @@ export interface ASRClient {
    * Requires microphone permission from the user.
    * 
    * @returns Promise that resolves when recording starts
-   * 
-   * @example
-   * ```typescript
-   * // Request microphone permission and start recording
-   * try {
-   *   await client.asr.startRecording();
-   *   console.log('Recording started');
-   * } catch (error) {
-   *   if (error.name === 'NotAllowedError') {
-   *     console.error('Microphone permission denied');
-   *   }
-   * }
-   * ```
+   *
    */
   startRecording(): Promise<void>;
 
@@ -163,16 +74,7 @@ export interface ASRClient {
    * Stop recording
    * 
    * Stops capturing audio from the microphone but keeps the WebSocket connection open.
-   * 
-   * @example
-   * ```typescript
-   * // Stop recording after 10 seconds
-   * await client.asr.startRecording();
-   * setTimeout(() => {
-   *   client.asr.stopRecording();
-   *   console.log('Recording stopped');
-   * }, 10000);
-   * ```
+   *
    */
   stopRecording(): void;
 
@@ -180,13 +82,7 @@ export interface ASRClient {
    * Close connection
    * 
    * Closes the WebSocket connection and releases resources.
-   * 
-   * @example
-   * ```typescript
-   * // Cleanup when done
-   * client.asr.stopRecording();
-   * client.asr.close();
-   * ```
+   *
    */
   close(): void;
 }

package/types/auth/code-auth.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * Verification Code Authentication - Type Definitions
- * ============================================================================
- * 
- * Verification code-based authentication including:
+ *  * Verification code-based authentication including:
  * - Email verification code login
  * - SMS verification code login
  * - Send verification code
@@ -24,46 +20,7 @@ export type CodeLoginType = 'email' | 'phone';
 
 /**
  * Verification code login parameters
- * 
- * @example
- * Email code login:
- * ```typescript
- * // 1. Send verification code
- * await client.auth.sendCode({
- *   type: 'email',
- *   email: 'user@example.com'
- * });
- * 
- * // 2. User receives code via email: "123456"
- * 
- * // 3. Login with code
- * const result = await client.auth.codeLogin({
- *   email: 'user@example.com',
- *   code: '123456'
- * });
- * 
- * if (result.data) {
- *   console.log('Logged in successfully!');
- * }
- * ```
- * 
- * @example
- * Phone code login:
- * ```typescript
- * // 1. Send SMS code
- * await client.auth.sendCode({
- *   type: 'phone',
- *   phone: '+86-13800138000'
- * });
- * 
- * // 2. User receives SMS: "654321"
- * 
- * // 3. Login with code
- * await client.auth.codeLogin({
- *   phone: '+86-13800138000',
- *   code: '654321'
- * });
- * ```
+ *
  */
 export interface CodeLoginParams {
   /** Login method (optional, auto-detected) */
@@ -119,45 +76,7 @@ export interface CodeAuthAPI {
    * 
    * @param params - Email/phone and verification code
    * @returns User info and access token
-   * 
-   * @example
-   * Complete code login flow:
-   * ```typescript
-   * // 1. Send verification code
-   * await client.auth.sendCode({
-   *   type: 'email',
-   *   email: 'user@example.com'
-   * });
-   * 
-   * // 2. User receives code: "123456"
-   * 
-   * // 3. Login with code
-   * const result = await client.auth.codeLogin({
-   *   email: 'user@example.com',
-   *   code: '123456'
-   * });
-   * 
-   * if (result.data) {
-   *   console.log('Logged in successfully!');
-   * }
-   * ```
-   * 
-   * @example
-   * SMS code login with error handling:
-   * ```typescript
-   * const result = await client.auth.codeLogin({
-   *   phone: '+86-13800138000',
-   *   code: userInputCode
-   * });
-   * 
-   * if (result.error) {
-   *   if (result.status === 400) {
-   *     console.error('Invalid or expired code');
-   *   } else {
-   *     console.error('Login failed:', result.error.message);
-   *   }
-   * }
-   * ```
+   *
    */
   codeLogin(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
 
@@ -169,43 +88,7 @@ export interface CodeAuthAPI {
    * 
    * @param params - Email or phone to send code to
    * @returns Success status
-   * 
-   * @example
-   * Send email verification code:
-   * ```typescript
-   * const result = await client.auth.sendCode({
-   *   type: 'email',
-   *   email: 'user@example.com'
-   * });
-   * 
-   * if (result.data?.success) {
-   *   console.log('Code sent to email');
-   *   showCodeInputForm();
-   * }
-   * ```
-   * 
-   * @example
-   * Send SMS verification code:
-   * ```typescript
-   * await client.auth.sendCode({
-   *   type: 'phone',
-   *   phone: '+86-13800138000'
-   * });
-   * console.log('SMS sent');
-   * ```
-   * 
-   * @example
-   * With rate limiting handling:
-   * ```typescript
-   * const result = await client.auth.sendCode({
-   *   type: 'email',
-   *   email: 'user@example.com'
-   * });
-   * 
-   * if (result.status === 429) {
-   *   console.error('Too many requests. Please try again later.');
-   * }
-   * ```
+   *
    */
   sendCode(params: SendCodeParams): Promise<ClientResult<SuccessResponse>>;
 
@@ -216,39 +99,7 @@ export interface CodeAuthAPI {
    * Used during registration or sensitive operations.
    * 
    * @returns Captcha ID and image (base64)
-   * 
-   * @example
-   * Display captcha to user:
-   * ```typescript
-   * const result = await client.auth.getCaptcha();
-   * if (result.data) {
-   *   // Display image to user
-   *   const img = document.createElement('img');
-   *   img.src = result.data.captchaImage;
-   *   document.body.appendChild(img);
-   *   
-   *   // Save captchaId for later verification
-   *   const captchaId = result.data.captchaId;
-   * }
-   * ```
-   * 
-   * @example
-   * Use with registration:
-   * ```typescript
-   * // 1. Get captcha
-   * const captchaResult = await client.auth.getCaptcha();
-   * showCaptchaImage(captchaResult.data.captchaImage);
-   * 
-   * // 2. Get user input
-   * const userInput = await promptUserForCaptcha();
-   * 
-   * // 3. Register with captcha
-   * await client.auth.register({
-   *   email: 'user@example.com',
-   *   password: 'Password@123',
-   *   captcha: `${captchaResult.data.captchaId}:${userInput}`
-   * });
-   * ```
+   *
    */
   getCaptcha(): Promise<ClientResult<CaptchaResponse>>;
 }

package/types/auth/index.d.ts

@@ -1,43 +1,33 @@
 /**
- * ============================================================================
- * Authentication Module - Unified Entry Point
- * ============================================================================
+ * Authentication module - provides user authentication and management capabilities.
  * 
- * This module provides comprehensive authentication capabilities.
- * Import from submodules for better tree-shaking and AI readability:
- * 
- * - `@amaster.ai/client/auth/user` - User types
- * - `@amaster.ai/client/auth/password-auth` - Password login/register
- * - `@amaster.ai/client/auth/code-auth` - Verification code login
- * - `@amaster.ai/client/auth/oauth` - OAuth & social login
- * - `@amaster.ai/client/auth/permissions` - Permission checking helpers
- * - `@amaster.ai/client/auth/profile` - User profile management
+ * This module exports all auth-related types for convenient importing:
  * 
  * @example
- * Import complete API:
- * ```typescript
- * import type { AuthClientAPI } from '@amaster.ai/client/auth';
- * ```
+ * // Import specific types
+ * import type { LoginParams, User, OAuthProvider } from '@amaster.ai/client/auth';
  * 
  * @example
- * Import specific types (recommended for AI):
- * ```typescript
- * import type { LoginParams, User } from '@amaster.ai/client/auth/password-auth';
- * import type { hasPermission } from '@amaster.ai/client/auth/permissions';
- * import type { OAuthProvider } from '@amaster.ai/client/auth/oauth';
- * ```
+ * // Import multiple types
+ * import type { 
+ *   LoginParams, 
+ *   RegisterParams,
+ *   User,
+ *   Role,
+ *   Permission 
+ * } from '@amaster.ai/client/auth';
  * 
  * @module auth
+ * @since 1.0.0
  */
 
 import type { ClientResult } from '../common';
 
-// Re-export all submodule types
+// Re-export all submodule types for convenient importing
 export * from './user';
 export * from './password-auth';
 export * from './code-auth';
 export * from './oauth';
-export * from './permissions';
 export * from './profile';
 
 // Import for unified API
@@ -77,37 +67,7 @@ export interface SuccessResponse {
  * 
  * Combines all authentication capabilities into a single interface.
  * All methods return a `ClientResult<T>` for consistent error handling.
- * 
- * @example
- * Complete authentication flow:
- * ```typescript
- * const client = createClient({ baseURL: 'https://api.amaster.ai' });
- * 
- * // 1. Register new user
- * await client.auth.register({
- *   email: 'user@example.com',
- *   password: 'Password@123',
- *   displayName: 'John Doe'
- * });
- * 
- * // 2. Login (token is automatically stored and attached to all requests)
- * await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'Password@123'
- * });
- * 
- * // 3. Get current user info
- * const userResult = await client.auth.getMe();
- * console.log(userResult.data);
- * 
- * // 4. Update profile
- * await client.auth.updateProfile({
- *   displayName: 'Jane Doe'
- * });
- * 
- * // 5. Logout
- * await client.auth.logout();
- * ```
+ *
  */
 export interface AuthClientAPI 
   extends PasswordAuthAPI,
@@ -122,22 +82,7 @@ export interface AuthClientAPI
    * All subsequent requests will be unauthenticated until login again.
    * 
    * @returns Success status
-   * 
-   * @example
-   * ```typescript
-   * await client.auth.logout();
-   * console.log('Logged out successfully');
-   * 
-   * // Token is cleared, requests are now unauthenticated
-   * console.log(client.isAuthenticated()); // false
-   * ```
-   * 
-   * @example
-   * Logout with redirect:
-   * ```typescript
-   * await client.auth.logout();
-   * window.location.href = '/login';
-   * ```
+   *
    */
   logout(): Promise<ClientResult<SuccessResponse>>;
 
@@ -149,32 +94,45 @@ export interface AuthClientAPI
    * This method is exposed for manual refresh scenarios.
    * 
    * @returns New access token
+   *
+   */
+  refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
+
+  // ==================== Permission Checks ====================
+  
+  /**
+   * Check if current user has a specific role (local check, fast)
    * 
-   * @example
-   * ```typescript
-   * const result = await client.auth.refreshToken();
-   * if (result.data) {
-   *   console.log('Token refreshed:', result.data.accessToken);
-   * }
-   * ```
+   * Works for both authenticated and anonymous users.
+   * Checks against locally cached user roles.
    * 
-   * @example
-   * Manual token refresh on 401:
-   * ```typescript
-   * try {
-   *   const result = await client.entity.list('default', 'users');
-   *   if (result.status === 401) {
-   *     // Try to refresh token
-   *     const refreshResult = await client.auth.refreshToken();
-   *     if (refreshResult.data) {
-   *       // Retry original request
-   *       return await client.entity.list('default', 'users');
-   *     }
-   *   }
-   * } catch (error) {
-   *   // Handle error
-   * }
-   * ```
+   * @param roleCode - Role code to check (e.g., "admin", "user", "anonymous")
+   * @returns True if user has the role
+   *
    */
-  refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
+  hasRole(roleCode: string): boolean;
+  
+  /**
+   * Check if current user has a specific permission (local check, fast)
+   * 
+   * Works for both authenticated and anonymous users.
+   * Checks against locally cached user permissions.
+   * 
+   * @param resource - Resource name (e.g., "user", "order")
+   * @param action - Action name (e.g., "read", "write", "delete")
+   * @returns True if user has the permission
+   *
+   */
+  hasPermission(resource: string, action: string): boolean;
+  
+  /**
+   * Check if current user is anonymous (not authenticated)
+   * 
+   * Convenience method equivalent to `hasRole('anonymous')`.
+   * Returns true if user has the 'anonymous' role.
+   * 
+   * @returns True if user is anonymous
+   *
+   */
+  isAnonymous(): boolean;
 }