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

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;
 }

package/types/auth/oauth.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * OAuth & Social Login - Type Definitions
- * ============================================================================
- * 
- * OAuth and social authentication including:
+ *  * OAuth and social authentication including:
  * - GitHub OAuth
  * - Google OAuth
  * - WeChat OAuth (Web & Mini Program)
@@ -30,30 +26,7 @@ export type OAuthProvider =
 
 /**
  * OAuth login parameters
- * 
- * @example
- * GitHub OAuth:
- * ```typescript
- * // 1. Get OAuth URL
- * const url = await client.auth.getOAuthUrl({
- *   provider: 'github',
- *   redirectUri: 'https://app.example.com/auth/callback'
- * });
- * 
- * // 2. Redirect user to OAuth provider
- * window.location.href = url.data.authUrl;
- * 
- * // 3. Handle callback
- * // User is redirected back with code in URL params
- * const params = new URLSearchParams(window.location.search);
- * const code = params.get('code');
- * 
- * // 4. Complete OAuth login
- * const result = await client.auth.oauthLogin({
- *   provider: 'github',
- *   code: code!
- * });
- * ```
+ *
  */
 export interface OAuthLoginParams {
   /** OAuth provider */
@@ -101,23 +74,7 @@ export interface OAuthUrlResponse {
 
 /**
  * WeChat Mini Program login parameters
- * 
- * @example
- * ```typescript
- * // 1. Get code from WeChat API
- * wx.login({
- *   success: async (res) => {
- *     // 2. Login with code
- *     const result = await client.auth.wechatMiniProgramLogin({
- *       code: res.code
- *     });
- *     
- *     if (result.data) {
- *       console.log('Logged in:', result.data.user);
- *     }
- *   }
- * });
- * ```
+ *
  */
 export interface WeChatMiniProgramLoginParams {
   /** WeChat login code */
@@ -158,30 +115,7 @@ export interface OAuthAPI {
    * 
    * @param params - OAuth provider and redirect URI
    * @returns Authorization URL and state
-   * 
-   * @example
-   * GitHub OAuth flow:
-   * ```typescript
-   * const result = await client.auth.getOAuthUrl({
-   *   provider: 'github',
-   *   redirectUri: 'https://app.example.com/auth/callback'
-   * });
-   * 
-   * if (result.data) {
-   *   // Redirect user to GitHub login
-   *   window.location.href = result.data.authUrl;
-   * }
-   * ```
-   * 
-   * @example
-   * Google OAuth with custom scopes:
-   * ```typescript
-   * const result = await client.auth.getOAuthUrl({
-   *   provider: 'google',
-   *   redirectUri: 'https://app.example.com/auth/callback',
-   *   scopes: ['email', 'profile', 'https://www.googleapis.com/auth/calendar']
-   * });
-   * ```
+   *
    */
   getOAuthUrl(params: GetOAuthUrlParams): Promise<ClientResult<OAuthUrlResponse>>;
 
@@ -192,42 +126,7 @@ export interface OAuthAPI {
    * 
    * @param params - OAuth provider and authorization code
    * @returns User info and access token
-   * 
-   * @example
-   * Complete GitHub OAuth:
-   * ```typescript
-   * // After user is redirected back from GitHub
-   * const params = new URLSearchParams(window.location.search);
-   * const code = params.get('code');
-   * 
-   * const result = await client.auth.oauthLogin({
-   *   provider: 'github',
-   *   code: code!,
-   *   redirectUri: 'https://app.example.com/auth/callback'
-   * });
-   * 
-   * if (result.data) {
-   *   console.log('Logged in as:', result.data.user.displayName);
-   *   // Token is now automatically attached to all requests
-   * }
-   * ```
-   * 
-   * @example
-   * With error handling:
-   * ```typescript
-   * const result = await client.auth.oauthLogin({
-   *   provider: 'google',
-   *   code: authCode
-   * });
-   * 
-   * if (result.error) {
-   *   if (result.status === 400) {
-   *     console.error('Invalid or expired authorization code');
-   *   } else {
-   *     console.error('OAuth login failed:', result.error.message);
-   *   }
-   * }
-   * ```
+   *
    */
   oauthLogin(params: OAuthLoginParams): Promise<ClientResult<LoginResponse>>;
 
@@ -238,43 +137,7 @@ export interface OAuthAPI {
    * 
    * @param params - WeChat login code
    * @returns User info and access token
-   * 
-   * @example
-   * ```typescript
-   * // In WeChat Mini Program
-   * wx.login({
-   *   success: async (res) => {
-   *     const result = await client.auth.wechatMiniProgramLogin({
-   *       code: res.code
-   *     });
-   *     
-   *     if (result.data) {
-   *       wx.setStorageSync('token', result.data.accessToken);
-   *       wx.showToast({ title: 'Login successful!' });
-   *     }
-   *   }
-   * });
-   * ```
-   * 
-   * @example
-   * With user info:
-   * ```typescript
-   * wx.login({
-   *   success: async (loginRes) => {
-   *     wx.getUserInfo({
-   *       success: async (userRes) => {
-   *         await client.auth.wechatMiniProgramLogin({
-   *           code: loginRes.code,
-   *           userInfo: {
-   *             encryptedData: userRes.encryptedData,
-   *             iv: userRes.iv
-   *           }
-   *         });
-   *       }
-   *     });
-   *   }
-   * });
-   * ```
+   *
    */
   wechatMiniProgramLogin(params: WeChatMiniProgramLoginParams): Promise<ClientResult<LoginResponse>>;
 }

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

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * Password Authentication - Type Definitions
- * ============================================================================
- * 
- * Password-based authentication including:
+ *  * Password-based authentication including:
  * - Email/username/phone + password login
  * - User registration
  * - Password change
@@ -20,45 +16,7 @@ import type { User } from './user';
  * User registration parameters
  * 
  * At least one identifier (username, email, or phone) must be provided.
- * 
- * @example
- * Register with email:
- * ```typescript
- * await client.auth.register({
- *   email: 'user@example.com',
- *   password: 'Password@123',
- *   displayName: 'John Doe'
- * });
- * ```
- * 
- * @example
- * Register with username and email:
- * ```typescript
- * await client.auth.register({
- *   username: 'johndoe',
- *   email: 'john@example.com',
- *   password: 'Password@123',
- *   displayName: 'John Doe'
- * });
- * ```
- * 
- * @example
- * Register with captcha verification:
- * ```typescript
- * // 1. Get captcha
- * const captcha = await client.auth.getCaptcha();
- * 
- * // 2. Show captcha.data.captchaImage to user
- * const userInput = prompt('Enter captcha:');
- * 
- * // 3. Register with captcha
- * await client.auth.register({
- *   username: 'johndoe',
- *   email: 'john@example.com',
- *   password: 'Password@123',
- *   captcha: `${captcha.data.captchaId}:${userInput}`
- * });
- * ```
+ *
  */
 export interface RegisterParams {
   /** Username (optional, but one of username/email/phone required) */
@@ -82,7 +40,6 @@ export interface RegisterParams {
   /** 
    * Captcha verification (optional)
    * Format: "captchaId:userInput"
-   * @example "abc-123:XY7K"
    */
   captcha?: string;
 }
@@ -97,34 +54,7 @@ export type LoginType = 'username' | 'email' | 'phone';
  * 
  * The `loginType` field is optional - it will be auto-detected based on
  * which identifier field (username/email/phone) you provide.
- * 
- * @example
- * Login with email (auto-detect):
- * ```typescript
- * await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'Password@123'
- * });
- * ```
- * 
- * @example
- * Login with username (explicit type):
- * ```typescript
- * await client.auth.login({
- *   loginType: 'username',
- *   username: 'johndoe',
- *   password: 'Password@123'
- * });
- * ```
- * 
- * @example
- * Login with phone:
- * ```typescript
- * await client.auth.login({
- *   phone: '+86-13800138000',
- *   password: 'Password@123'
- * });
- * ```
+ *
  */
 export interface LoginParams {
   /** Login method (optional, auto-detected if not provided) */
@@ -145,18 +75,7 @@ export interface LoginParams {
 
 /**
  * Change password parameters
- * 
- * @example
- * ```typescript
- * const result = await client.auth.changePassword({
- *   oldPassword: 'OldPassword@123',
- *   newPassword: 'NewPassword@456'
- * });
- * 
- * if (result.data?.success) {
- *   console.log('Password changed successfully');
- * }
- * ```
+ *
  */
 export interface ChangePasswordParams {
   /** Current password (for verification) */
@@ -173,23 +92,7 @@ export interface ChangePasswordParams {
 
 /**
  * Login/Registration response with user info and access token
- * 
- * @example
- * ```typescript
- * const result = await client.auth.login({
- *   email: 'user@example.com',
- *   password: 'password123'
- * });
- * 
- * if (result.data) {
- *   const { user, accessToken } = result.data;
- *   console.log(`Welcome ${user.displayName}!`);
- *   console.log(`Token: ${accessToken}`);
- *   
- *   // All subsequent requests now include this token automatically
- *   await client.entity.list('default', 'users');
- * }
- * ```
+ *
  */
 export interface LoginResponse {
   /** User information */
@@ -222,6 +125,8 @@ export interface SuccessResponse {
  * Password Authentication API
  * 
  * Methods for password-based authentication and account management.
+ * 
+ * @since 1.0.0
  */
 export interface PasswordAuthAPI {
   /**
@@ -234,30 +139,25 @@ export interface PasswordAuthAPI {
    * @returns User info and access token (if auto-login enabled)
    * 
    * @example
-   * Basic registration:
-   * ```typescript
+   * // Register with email
    * const result = await client.auth.register({
    *   email: 'user@example.com',
-   *   password: 'Password@123',
+   *   password: 'SecurePass123',
    *   displayName: 'John Doe'
    * });
    * 
-   * if (result.data) {
-   *   console.log('Registration successful!');
-   *   console.log('User:', result.data.user);
+   * if (result.success) {
+   *   console.log('User registered:', result.data.user.uid);
    * }
-   * ```
    * 
    * @example
-   * Registration with username:
-   * ```typescript
-   * await client.auth.register({
+   * // Register with username
+   * const result = await client.auth.register({
    *   username: 'johndoe',
-   *   email: 'john@example.com',
-   *   password: 'Password@123',
-   *   displayName: 'John Doe'
+   *   password: 'SecurePass123'
    * });
-   * ```
+   * 
+   * @since 1.0.0
    */
   register(params: RegisterParams): Promise<ClientResult<LoginResponse>>;
 
@@ -271,30 +171,33 @@ export interface PasswordAuthAPI {
    * @returns User info and access token
    * 
    * @example
-   * Login with email:
-   * ```typescript
+   * // Login with email
    * const result = await client.auth.login({
    *   email: 'user@example.com',
-   *   password: 'Password@123'
+   *   password: 'myPassword123'
    * });
    * 
-   * if (result.data) {
-   *   console.log('Welcome', result.data.user.displayName);
-   *   // Token is now automatically attached to all requests
+   * if (result.success) {
+   *   console.log('Welcome,', result.data.user.displayName);
    * } else {
-   *   console.error('Login failed:', result.error?.message);
+   *   console.error('Login failed:', result.error.message);
    * }
-   * ```
    * 
    * @example
-   * Login with username:
-   * ```typescript
-   * await client.auth.login({
-   *   loginType: 'username',
+   * // Login with username
+   * const result = await client.auth.login({
    *   username: 'johndoe',
-   *   password: 'Password@123'
+   *   password: 'myPassword123'
+   * });
+   * 
+   * @example
+   * // Login with phone
+   * const result = await client.auth.login({
+   *   phone: '+1234567890',
+   *   password: 'myPassword123'
    * });
-   * ```
+   * 
+   * @since 1.0.0
    */
   login(params: LoginParams): Promise<ClientResult<LoginResponse>>;
 
@@ -308,18 +211,16 @@ export interface PasswordAuthAPI {
    * @returns Success status
    * 
    * @example
-   * ```typescript
    * const result = await client.auth.changePassword({
-   *   oldPassword: 'OldPassword@123',
-   *   newPassword: 'NewPassword@456'
+   *   oldPassword: 'currentPass123',
+   *   newPassword: 'newSecurePass456'
    * });
    * 
-   * if (result.data?.success) {
+   * if (result.success) {
    *   console.log('Password changed successfully');
-   * } else {
-   *   console.error('Failed:', result.error?.message);
    * }
-   * ```
+   * 
+   * @since 1.0.0
    */
   changePassword(params: ChangePasswordParams): Promise<ClientResult<SuccessResponse>>;
 }