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

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

package/types/auth/profile.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * User Profile Management - Type Definitions
- * ============================================================================
- * 
- * User profile operations including:
+ *  * User profile operations including:
  * - Get current user information
  * - Update profile fields
  * - Avatar management
@@ -20,36 +16,7 @@ import type { User } from './user';
  * Update user profile parameters
  * 
  * All fields are optional - only update what you want to change.
- * 
- * @example
- * Update display name:
- * ```typescript
- * await client.auth.updateProfile({
- *   displayName: 'Jane Doe'
- * });
- * ```
- * 
- * @example
- * Update multiple fields:
- * ```typescript
- * await client.auth.updateProfile({
- *   displayName: 'John Smith',
- *   avatarUrl: 'https://cdn.example.com/avatar.jpg',
- *   phone: '+86-13900139000'
- * });
- * ```
- * 
- * @example
- * Update email (may require verification):
- * ```typescript
- * const result = await client.auth.updateProfile({
- *   email: 'newemail@example.com'
- * });
- * 
- * if (result.data && !result.data.emailVerified) {
- *   console.log('Verification email sent to new address');
- * }
- * ```
+ *
  */
 export interface UpdateProfileParams {
   /** New display name */
@@ -79,41 +46,7 @@ export interface ProfileAPI {
    * Retrieves the profile of the currently authenticated user.
    * 
    * @returns Current user info with roles and permissions
-   * 
-   * @example
-   * Basic usage:
-   * ```typescript
-   * const result = await client.auth.getMe();
-   * if (result.data) {
-   *   console.log('Current user:', result.data.displayName);
-   *   console.log('Email:', result.data.email);
-   *   console.log('Roles:', result.data.roles);
-   *   console.log('Permissions:', result.data.permissions);
-   * }
-   * ```
-   * 
-   * @example
-   * Check permissions:
-   * ```typescript
-   * const result = await client.auth.getMe();
-   * if (result.data?.permissions.includes('user:delete')) {
-   *   showDeleteButton();
-   * }
-   * 
-   * if (result.data?.roles.includes('admin')) {
-   *   showAdminPanel();
-   * }
-   * ```
-   * 
-   * @example
-   * Display verification status:
-   * ```typescript
-   * const user = (await client.auth.getMe()).data;
-   * if (user) {
-   *   console.log(`Email ${user.email}${user.emailVerified ? ' ✓' : ' (unverified)'}`);
-   *   console.log(`Phone ${user.phone}${user.phoneVerified ? ' ✓' : ' (unverified)'}`);
-   * }
-   * ```
+   *
    */
   getMe(): Promise<ClientResult<User>>;
 
@@ -125,39 +58,7 @@ export interface ProfileAPI {
    * 
    * @param params - Fields to update
    * @returns Updated user info
-   * 
-   * @example
-   * Update display name:
-   * ```typescript
-   * const result = await client.auth.updateProfile({
-   *   displayName: 'Jane Smith'
-   * });
-   * 
-   * if (result.data) {
-   *   console.log('Profile updated:', result.data.displayName);
-   * }
-   * ```
-   * 
-   * @example
-   * Update avatar:
-   * ```typescript
-   * // After uploading avatar to CDN
-   * const avatarUrl = 'https://cdn.example.com/avatars/user-123.jpg';
-   * 
-   * await client.auth.updateProfile({
-   *   avatarUrl: avatarUrl
-   * });
-   * ```
-   * 
-   * @example
-   * Update multiple fields:
-   * ```typescript
-   * await client.auth.updateProfile({
-   *   displayName: 'John Doe',
-   *   avatarUrl: 'https://cdn.example.com/avatar.jpg',
-   *   phone: '+86-13900139000'
-   * });
-   * ```
+   *
    */
   updateProfile(params: UpdateProfileParams): Promise<ClientResult<User>>;
 }

package/types/auth/user.d.ts

@@ -1,9 +1,5 @@
 /**
- * ============================================================================
- * User Types - Base User Information
- * ============================================================================
- * 
- * Core user data structures including:
+ *  * Core user data structures including:
  * - User profile information
  * - Role and permission types
  * - User status enums
@@ -17,30 +13,7 @@
  * Roles and permissions are returned as simple string arrays for efficient client-side use:
  * - `roles`: ["admin", "user", "manager"]
  * - `permissions`: ["user:read", "user:write", "order:read"]
- * 
- * @example
- * Check user permissions:
- * ```typescript
- * const result = await client.auth.getMe();
- * const user = result.data;
- * 
- * if (user.roles.includes('admin')) {
- *   console.log('User is an admin');
- * }
- * 
- * if (user.permissions.includes('user:delete')) {
- *   showDeleteButton();
- * }
- * ```
- * 
- * @example
- * Display user info:
- * ```typescript
- * const user = result.data;
- * console.log(`Name: ${user.displayName}`);
- * console.log(`Email: ${user.email}${user.emailVerified ? ' ✓' : ''}`);
- * console.log(`Roles: ${user.roles.join(', ')}`);
- * ```
+ *
  */
 export interface User {
   /** Unique user identifier */
@@ -82,16 +55,13 @@ export interface User {
    * Includes system roles and custom roles:
    * - System roles: "anonymous" (unauthenticated), "member" (default), "admin"
    * - Custom roles: defined in app.settings.yml
-   * 
-   * @example ["admin", "user", "manager"]
-   * @example ["anonymous"] // For unauthenticated users
+   *
    */
   roles: string[];
   
   /** 
    * Permission names granted to user
    * Format: "resource:action"
-   * @example ["user:read", "user:write", "order:read", "order:delete"]
    */
   permissions: string[];