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

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
@@ -16,31 +12,8 @@
  * 
  * 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(', ')}`);
- * ```
+ * - `permissions`: ["user.read", "user.write", "order.read"]
+ *
  */
 export interface User {
   /** Unique user identifier */
@@ -77,15 +50,18 @@ export interface User {
   phoneVerifiedAt: string | null;
   
   /** 
-   * Role codes assigned to user 
-   * @example ["admin", "user", "manager"]
+   * Role codes assigned to user
+   * 
+   * Includes system roles and custom roles:
+   * - System roles: "anonymous" (unauthenticated), "member" (default), "admin"
+   * - Custom roles: defined in app.settings.yml
+   *
    */
   roles: string[];
   
   /** 
    * Permission names granted to user
-   * Format: "resource:action"
-   * @example ["user:read", "user:write", "order:read", "order:delete"]
+   * Format: "resource.action"
    */
   permissions: string[];