@amaster.ai/client 1.0.0-alpha.1

package/types/auth/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Authentication module - provides user authentication and management capabilities.
+ * 
+ * This module exports all auth-related types for convenient importing:
+ * 
+ * @example
+ * // Import specific types
+ * import type { LoginParams, User, OAuthProvider } from '@amaster.ai/client/auth';
+ * 
+ * @example
+ * // 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 for convenient importing
+export * from './user';
+export * from './password-auth';
+export * from './code-auth';
+export * from './oauth';
+export * from './profile';
+
+// Import for unified API
+import type { PasswordAuthAPI } from './password-auth';
+import type { CodeAuthAPI } from './code-auth';
+import type { OAuthAPI } from './oauth';
+import type { ProfileAPI } from './profile';
+
+// ==================== Token Management ====================
+
+/**
+ * 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;
+}
+
+// ==================== Unified Authentication API ====================
+
+/**
+ * Complete Authentication Client API
+ * 
+ * Combines all authentication capabilities into a single interface.
+ * All methods return a `ClientResult<T>` for consistent error handling.
+ *
+ */
+export interface AuthClientAPI 
+  extends PasswordAuthAPI,
+          CodeAuthAPI,
+          OAuthAPI,
+          ProfileAPI {
+  
+  /**
+   * Logout current user
+   * 
+   * Invalidates the current session and clears local authentication state.
+   * All subsequent requests will be unauthenticated until login again.
+   * 
+   * @returns Success status
+   *
+   */
+  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
+   *
+   */
+  refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
+
+  // ==================== Permission Checks ====================
+  
+  /**
+   * Check if current user has a specific role (local check, fast)
+   * 
+   * Works for both authenticated and anonymous users.
+   * Checks against locally cached user roles.
+   * 
+   * @param roleCode - Role code to check (e.g., "admin", "user", "anonymous")
+   * @returns True if user has the role
+   *
+   */
+  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

@@ -0,0 +1,143 @@
+/**
+ *  * OAuth and social authentication including:
+ * - GitHub OAuth
+ * - Google OAuth
+ * - WeChat OAuth (Web & Mini Program)
+ * - Generic OAuth flow
+ * 
+ * @module auth/oauth
+ */
+
+import type { ClientResult } from '../common';
+import type { LoginResponse } from './password-auth';
+
+// ==================== OAuth Providers ====================
+
+/**
+ * Supported OAuth providers
+ */
+export type OAuthProvider = 
+  | 'github'
+  | 'google'
+  | 'wechat'
+  | 'wechat-miniprogram'
+  | 'gitlab'
+  | 'microsoft';
+
+/**
+ * OAuth login parameters
+ *
+ */
+export interface OAuthLoginParams {
+  /** OAuth provider */
+  provider: OAuthProvider;
+  
+  /** Authorization code from OAuth callback */
+  code: string;
+  
+  /** Redirect URI used in the OAuth flow */
+  redirectUri?: string;
+  
+  /** State parameter for CSRF protection */
+  state?: string;
+}
+
+/**
+ * Get OAuth URL parameters
+ */
+export interface GetOAuthUrlParams {
+  /** OAuth provider */
+  provider: OAuthProvider;
+  
+  /** Redirect URI after OAuth */
+  redirectUri: string;
+  
+  /** State parameter for CSRF protection */
+  state?: string;
+  
+  /** Additional scopes (provider-specific) */
+  scopes?: string[];
+}
+
+/**
+ * OAuth URL response
+ */
+export interface OAuthUrlResponse {
+  /** Authorization URL to redirect user to */
+  authUrl: string;
+  
+  /** State parameter for verification */
+  state: string;
+}
+
+// ==================== WeChat Specific ====================
+
+/**
+ * WeChat Mini Program login parameters
+ *
+ */
+export interface WeChatMiniProgramLoginParams {
+  /** WeChat login code */
+  code: string;
+  
+  /** User info from WeChat (optional) */
+  userInfo?: {
+    /** Encrypted user data */
+    encryptedData: string;
+    /** IV for decryption */
+    iv: string;
+  };
+}
+
+/**
+ * WeChat web OAuth parameters
+ */
+export interface WeChatWebLoginParams {
+  /** Authorization code from WeChat OAuth */
+  code: string;
+  
+  /** State parameter */
+  state?: string;
+}
+
+// ==================== API ====================
+
+/**
+ * OAuth & Social Login API
+ * 
+ * Methods for OAuth-based authentication.
+ */
+export interface OAuthAPI {
+  /**
+   * Get OAuth authorization URL
+   * 
+   * Generates the URL to redirect users to for OAuth authentication.
+   * 
+   * @param params - OAuth provider and redirect URI
+   * @returns Authorization URL and state
+   *
+   */
+  getOAuthUrl(params: GetOAuthUrlParams): Promise<ClientResult<OAuthUrlResponse>>;
+
+  /**
+   * Complete OAuth login
+   * 
+   * Exchanges the OAuth authorization code for access token and user info.
+   * 
+   * @param params - OAuth provider and authorization code
+   * @returns User info and access token
+   *
+   */
+  oauthLogin(params: OAuthLoginParams): Promise<ClientResult<LoginResponse>>;
+
+  /**
+   * WeChat Mini Program login
+   * 
+   * Authenticates user in WeChat Mini Program environment.
+   * 
+   * @param params - WeChat login code
+   * @returns User info and access token
+   *
+   */
+  wechatMiniProgramLogin(params: WeChatMiniProgramLoginParams): Promise<ClientResult<LoginResponse>>;
+}

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

@@ -0,0 +1,226 @@
+/**
+ *  * Password-based authentication including:
+ * - Email/username/phone + password login
+ * - User registration
+ * - Password change
+ * 
+ * @module auth/password-auth
+ */
+
+import type { ClientResult } from '../common';
+import type { User } from './user';
+
+// ==================== Parameters ====================
+
+/**
+ * User registration parameters
+ * 
+ * At least one identifier (username, email, or phone) must be provided.
+ *
+ */
+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"
+   */
+  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.
+ *
+ */
+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;
+}
+
+/**
+ * Change password parameters
+ *
+ */
+export interface ChangePasswordParams {
+  /** Current password (for verification) */
+  oldPassword: string;
+  
+  /** 
+   * New password (8-128 characters)
+   * Must contain: uppercase, lowercase, number
+   */
+  newPassword: string;
+}
+
+// ==================== Responses ====================
+
+/**
+ * Login/Registration response with user info and access token
+ *
+ */
+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;
+}
+
+/**
+ * Generic success response
+ */
+export interface SuccessResponse {
+  /** Whether operation was successful */
+  success: boolean;
+  
+  /** Optional message */
+  message?: string;
+}
+
+// ==================== API ====================
+
+/**
+ * Password Authentication API
+ * 
+ * Methods for password-based authentication and account management.
+ * 
+ * @since 1.0.0
+ */
+export interface PasswordAuthAPI {
+  /**
+   * 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
+   * // Register with email
+   * const result = await client.auth.register({
+   *   email: 'user@example.com',
+   *   password: 'SecurePass123',
+   *   displayName: 'John Doe'
+   * });
+   * 
+   * if (result.success) {
+   *   console.log('User registered:', result.data.user.uid);
+   * }
+   * 
+   * @example
+   * // Register with username
+   * const result = await client.auth.register({
+   *   username: 'johndoe',
+   *   password: 'SecurePass123'
+   * });
+   * 
+   * @since 1.0.0
+   */
+  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
+   * const result = await client.auth.login({
+   *   email: 'user@example.com',
+   *   password: 'myPassword123'
+   * });
+   * 
+   * if (result.success) {
+   *   console.log('Welcome,', result.data.user.displayName);
+   * } else {
+   *   console.error('Login failed:', result.error.message);
+   * }
+   * 
+   * @example
+   * // Login with username
+   * const result = await client.auth.login({
+   *   username: 'johndoe',
+   *   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>>;
+
+  /**
+   * 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
+   * const result = await client.auth.changePassword({
+   *   oldPassword: 'currentPass123',
+   *   newPassword: 'newSecurePass456'
+   * });
+   * 
+   * if (result.success) {
+   *   console.log('Password changed successfully');
+   * }
+   * 
+   * @since 1.0.0
+   */
+  changePassword(params: ChangePasswordParams): Promise<ClientResult<SuccessResponse>>;
+}

package/types/auth/profile.d.ts

@@ -0,0 +1,64 @@
+/**
+ *  * User profile operations including:
+ * - Get current user information
+ * - Update profile fields
+ * - Avatar management
+ * 
+ * @module auth/profile
+ */
+
+import type { ClientResult } from '../common';
+import type { User } from './user';
+
+// ==================== Parameters ====================
+
+/**
+ * Update user profile parameters
+ * 
+ * All fields are optional - only update what you want to change.
+ *
+ */
+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;
+}
+
+// ==================== API ====================
+
+/**
+ * User Profile Management API
+ * 
+ * Methods for managing user profile information.
+ */
+export interface ProfileAPI {
+  /**
+   * Get current user information
+   * 
+   * Retrieves the profile of the currently authenticated user.
+   * 
+   * @returns Current user info with roles and permissions
+   *
+   */
+  getMe(): Promise<ClientResult<User>>;
+
+  /**
+   * Update user profile
+   * 
+   * Updates one or more fields of the current user's profile.
+   * Only the fields provided will be updated.
+   * 
+   * @param params - Fields to update
+   * @returns Updated user info
+   *
+   */
+  updateProfile(params: UpdateProfileParams): Promise<ClientResult<User>>;
+}

package/types/auth/user.d.ts

@@ -0,0 +1,73 @@
+/**
+ *  * Core user data structures including:
+ * - User profile information
+ * - Role and permission types
+ * - User status enums
+ * 
+ * @module auth/user
+ */
+
+/**
+ * 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"]
+ *
+ */
+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
+   * 
+   * 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"
+   */
+  permissions: string[];
+  
+  /** Account creation timestamp (ISO 8601) */
+  createdAt: string;
+  
+  /** Last update timestamp (ISO 8601) */
+  updatedAt: string;
+}