@amaster.ai/client 1.1.0-beta.0

package/types/auth.d.ts

@@ -0,0 +1,674 @@
+/**
+ * ============================================================================
+ * Authentication Module - Type Definitions
+ * ============================================================================
+ * 
+ * This module provides comprehensive authentication capabilities including:
+ * - Password-based login (username/email/phone)
+ * - User registration
+ * - Verification code login
+ * - OAuth/Social login
+ * - Token management and refresh
+ * - User profile management
+ * - Permission and role management
+ * 
+ * @module auth
+ */
+
+import type { ClientResult } from './common';
+
+// ==================== User & Roles ====================
+
+/**
+ * User information with optimized roles and permissions
+ * 
+ * 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();
+ * }
+ * ```
+ */
+export interface User {
+  /** Unique user identifier */
+  uid: string;
+  /** Username (null if not set) */
+  username: string | null;
+  /** Email address (null if not set) */
+  email: string | null;
+  /** Phone number (null if not set) */
+  phone: string | null;
+  /** Display name shown in UI */
+  displayName: string | null;
+  /** Avatar image URL */
+  avatarUrl: string | null;
+  /** Whether account is active */
+  isActive: boolean;
+  /** Whether email is verified */
+  emailVerified: boolean;
+  /** Whether phone is verified */
+  phoneVerified: boolean;
+  /** Email verification timestamp (ISO 8601) */
+  emailVerifiedAt: string | null;
+  /** Phone verification timestamp (ISO 8601) */
+  phoneVerifiedAt: string | null;
+  /** 
+   * Role codes assigned to user 
+   * @example ["admin", "user", "manager"]
+   */
+  roles: string[];
+  /** 
+   * Permission names granted to user
+   * Format: "resource:action"
+   * @example ["user:read", "user:write", "order:read", "order:delete"]
+   */
+  permissions: string[];
+  /** Account creation timestamp (ISO 8601) */
+  createdAt: string;
+  /** Last update timestamp (ISO 8601) */
+  updatedAt: string;
+}
+
+// ==================== Authentication Parameters ====================
+
+/**
+ * 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 captcha:
+ * ```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) */
+  username?: string;
+  /** Email address (optional, but one of username/email/phone required) */
+  email?: string;
+  /** Phone number (optional, but one of username/email/phone required) */
+  phone?: string;
+  /** 
+   * Password (required, 8-128 characters)
+   * Must contain at least: uppercase, lowercase, number
+   */
+  password: string;
+  /** Display name for UI */
+  displayName?: string;
+  /** 
+   * Captcha verification (optional)
+   * Format: "captchaId:userInput"
+   * @example "abc-123:XY7K"
+   */
+  captcha?: string;
+}
+
+/**
+ * Login method type
+ */
+export type LoginType = 'username' | 'email' | 'phone';
+
+/**
+ * Login parameters for password-based authentication
+ * 
+ * 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) */
+  loginType?: LoginType;
+  /** Username (required if loginType='username') */
+  username?: string;
+  /** Email (required if loginType='email') */
+  email?: string;
+  /** Phone (required if loginType='phone') */
+  phone?: string;
+  /** Password (always required) */
+  password: string;
+}
+
+/**
+ * Verification code login type
+ */
+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
+ * const code = '123456';
+ * 
+ * // 3. Login with code
+ * await client.auth.codeLogin({
+ *   email: 'user@example.com',
+ *   code: code
+ * });
+ * ```
+ */
+export interface CodeLoginParams {
+  /** Login method (optional, auto-detected) */
+  loginType?: CodeLoginType;
+  /** Email (required if using email code) */
+  email?: string;
+  /** Phone (required if using phone code) */
+  phone?: string;
+  /** Verification code received via email/SMS */
+  code: string;
+}
+
+/**
+ * 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'
+ * });
+ * ```
+ */
+export interface UpdateProfileParams {
+  /** New display name */
+  displayName?: string;
+  /** New avatar URL */
+  avatarUrl?: string;
+  /** New email (may require verification) */
+  email?: string;
+  /** New phone (may require verification) */
+  phone?: string;
+}
+
+/**
+ * Change password parameters
+ * 
+ * @example
+ * ```typescript
+ * await client.auth.changePassword({
+ *   oldPassword: 'OldPassword@123',
+ *   newPassword: 'NewPassword@456'
+ * });
+ * ```
+ */
+export interface ChangePasswordParams {
+  /** Current password (for verification) */
+  oldPassword: string;
+  /** 
+   * New password (8-128 characters)
+   * Must contain: uppercase, lowercase, number
+   */
+  newPassword: string;
+}
+
+// ==================== Authentication Responses ====================
+
+/**
+ * Login 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 */
+  user: User;
+  /** JWT access token */
+  accessToken: string;
+  /** Refresh token (if configured) */
+  refreshToken?: string;
+  /** Token expiration time in seconds */
+  expiresIn?: number;
+}
+
+/**
+ * Token refresh response
+ */
+export interface RefreshTokenResponse {
+  /** New access token */
+  accessToken: string;
+  /** Token expiration time in seconds */
+  expiresIn?: number;
+}
+
+/**
+ * Generic success response
+ */
+export interface SuccessResponse {
+  /** Whether operation was successful */
+  success: boolean;
+  /** Optional message */
+  message?: string;
+}
+
+// ==================== Authentication API ====================
+
+/**
+ * Authentication Client API
+ * 
+ * Provides methods for user authentication and account management.
+ * 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 {
+  // ==================== Core Authentication ====================
+
+  /**
+   * Register a new user account
+   * 
+   * Creates a new user account with the provided credentials.
+   * Depending on backend configuration, may auto-login after registration.
+   * 
+   * @param params - Registration parameters
+   * @returns User info and access token (if auto-login enabled)
+   * 
+   * @example
+   * Basic registration:
+   * ```typescript
+   * const result = await client.auth.register({
+   *   email: 'user@example.com',
+   *   password: 'Password@123',
+   *   displayName: 'John Doe'
+   * });
+   * 
+   * if (result.data) {
+   *   console.log('Registration successful!');
+   *   console.log('User:', result.data.user);
+   * }
+   * ```
+   * 
+   * @example
+   * Registration with username:
+   * ```typescript
+   * await client.auth.register({
+   *   username: 'johndoe',
+   *   email: 'john@example.com',
+   *   password: 'Password@123',
+   *   displayName: 'John Doe'
+   * });
+   * ```
+   */
+  register(params: RegisterParams): Promise<ClientResult<LoginResponse>>;
+
+  /**
+   * Login with password
+   * 
+   * Authenticates a user with username/email/phone and password.
+   * On success, access token is automatically stored and attached to all subsequent requests.
+   * 
+   * @param params - Login credentials
+   * @returns User info and access token
+   * 
+   * @example
+   * Login with email:
+   * ```typescript
+   * const result = await client.auth.login({
+   *   email: 'user@example.com',
+   *   password: 'Password@123'
+   * });
+   * 
+   * if (result.data) {
+   *   console.log('Welcome', result.data.user.displayName);
+   *   // Token is now automatically attached to all requests
+   * } else {
+   *   console.error('Login failed:', result.error?.message);
+   * }
+   * ```
+   * 
+   * @example
+   * Login with username:
+   * ```typescript
+   * await client.auth.login({
+   *   loginType: 'username',
+   *   username: 'johndoe',
+   *   password: 'Password@123'
+   * });
+   * ```
+   */
+  login(params: LoginParams): Promise<ClientResult<LoginResponse>>;
+
+  /**
+   * Login with verification code
+   * 
+   * Authenticates using a verification code sent to email or phone.
+   * 
+   * @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!');
+   * }
+   * ```
+   */
+  codeLogin(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
+
+  /**
+   * Logout current user
+   * 
+   * Invalidates the current session and clears local authentication state.
+   * 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>>;
+
+  /**
+   * Refresh access token
+   * 
+   * Obtains a new access token using the refresh token.
+   * Note: Token refresh is handled automatically by the client.
+   * This method is exposed for manual refresh scenarios.
+   * 
+   * @returns New access token
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.auth.refreshToken();
+   * if (result.data) {
+   *   console.log('Token refreshed:', result.data.accessToken);
+   * }
+   * ```
+   */
+  refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
+
+  // ==================== User Profile Management ====================
+
+  /**
+   * Get current user information
+   * 
+   * Retrieves the profile of the currently authenticated user.
+   * 
+   * @returns Current user info
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.auth.getMe();
+   * if (result.data) {
+   *   console.log('Current user:', result.data.displayName);
+   *   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')) {
+   *   // Show delete button
+   * }
+   * ```
+   */
+  getMe(): Promise<ClientResult<User>>;
+
+  /**
+   * Update user profile
+   * 
+   * Updates one or more fields of the current user's profile.
+   * 
+   * @param params - Fields to update
+   * @returns Updated user info
+   * 
+   * @example
+   * Update display name:
+   * ```typescript
+   * await client.auth.updateProfile({
+   *   displayName: 'Jane Smith'
+   * });
+   * ```
+   * 
+   * @example
+   * Update multiple fields:
+   * ```typescript
+   * await client.auth.updateProfile({
+   *   displayName: 'John Doe',
+   *   avatarUrl: 'https://cdn.example.com/avatar.jpg'
+   * });
+   * ```
+   */
+  updateProfile(params: UpdateProfileParams): Promise<ClientResult<User>>;
+
+  /**
+   * Change password
+   * 
+   * Changes the password for the current user.
+   * Requires the old password for verification.
+   * 
+   * @param params - Old and new passwords
+   * @returns Success status
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.auth.changePassword({
+   *   oldPassword: 'OldPassword@123',
+   *   newPassword: 'NewPassword@456'
+   * });
+   * 
+   * if (result.data?.success) {
+   *   console.log('Password changed successfully');
+   * } else {
+   *   console.error('Failed:', result.error?.message);
+   * }
+   * ```
+   */
+  changePassword(params: ChangePasswordParams): Promise<ClientResult<SuccessResponse>>;
+
+  // ==================== Verification & Security ====================
+
+  /**
+   * Send verification code
+   * 
+   * Sends a verification code to the specified email or phone.
+   * Used for code login or account verification.
+   * 
+   * @param params - Email or phone to send code to
+   * @returns Success status
+   * 
+   * @example
+   * Send email verification code:
+   * ```typescript
+   * await client.auth.sendCode({
+   *   type: 'email',
+   *   email: 'user@example.com'
+   * });
+   * console.log('Code sent to email');
+   * ```
+   * 
+   * @example
+   * Send SMS verification code:
+   * ```typescript
+   * await client.auth.sendCode({
+   *   type: 'phone',
+   *   phone: '+86-13800138000'
+   * });
+   * ```
+   */
+  sendCode(params: {
+    type: 'email' | 'phone';
+    email?: string;
+    phone?: string;
+  }): Promise<ClientResult<SuccessResponse>>;
+
+  /**
+   * Get captcha image
+   * 
+   * Retrieves a captcha challenge for verification.
+   * 
+   * @returns Captcha ID and image (base64)
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.auth.getCaptcha();
+   * if (result.data) {
+   *   // Display image to user
+   *   const img = document.createElement('img');
+   *   img.src = result.data.captchaImage;
+   *   
+   *   // Save captchaId for later verification
+   *   const captchaId = result.data.captchaId;
+   * }
+   * ```
+   */
+  getCaptcha(): Promise<ClientResult<{
+    captchaId: string;
+    captchaImage: string; // base64 encoded image
+  }>>;
+}