@amaster.ai/client 1.1.3 → 1.1.5

package/types/auth/index.d.ts

@@ -1,22 +1,22 @@
 /**
  * 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, 
+ * import type {
+ *   LoginParams,
  *   RegisterParams,
  *   User,
  *   Role,
- *   Permission 
+ *   Permission
  * } from '@amaster.ai/client/auth';
- * 
+ *
  * @module auth
  * @since 1.0.0
  */
@@ -28,138 +28,118 @@ export * from './user';
 export * from './password-auth';
 export * from './code-auth';
 export * from './oauth';
+export * from './permissions';
 export * from './profile';
+export * from './sessions';
 
 // Import for unified API
-import type { PasswordAuthAPI } from './password-auth';
+import type { PasswordAuthAPI, RefreshTokenResponse, SuccessResponse } from './password-auth';
 import type { CodeAuthAPI } from './code-auth';
 import type { OAuthAPI } from './oauth';
+import type { PermissionsAPI } from './permissions';
 import type { ProfileAPI } from './profile';
+import type { SessionsAPI } from './sessions';
 
-// ==================== Token Management ====================
+// ==================== Events ====================
 
 /**
- * Token refresh response
+ * Authentication lifecycle events
  */
-export interface RefreshTokenResponse {
-  /** New access token */
-  accessToken: string;
-  
-  /** Token expiration time in seconds */
-  expiresIn?: number;
-}
+export type AuthEvent =
+  | 'login'
+  | 'logout'
+  | 'tokenExpired'
+  | 'tokenRefreshed'
+  | 'unauthorized';
 
 /**
- * Generic success response
+ * Event callback signature
  */
-export interface SuccessResponse {
-  /** Whether operation was successful */
-  success: boolean;
-  
-  /** Optional message */
-  message?: string;
-}
+export type EventHandler = (...args: any[]) => void;
 
 // ==================== 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 
+export interface AuthClientAPI
   extends PasswordAuthAPI,
           CodeAuthAPI,
           OAuthAPI,
-          ProfileAPI {
-  
+          PermissionsAPI,
+          ProfileAPI,
+          SessionsAPI {
+
   /**
    * Logout current user
-   * 
+   *
    * Invalidates the current session and clears local authentication state.
    * All subsequent requests will be unauthenticated until login again.
-   * 
-   * @returns Success status
    *
+   * @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
    *
+   * @returns New access token
    */
   refreshToken(): Promise<ClientResult<RefreshTokenResponse>>;
 
-  // ==================== Event Handling ====================
-
   /**
    * Subscribe to authentication events
-   * 
+   *
    * Available events:
    * - `login` - Fired after successful login, receives User object
    * - `logout` - Fired after logout
    * - `tokenExpired` - Fired when access token expires
    * - `tokenRefreshed` - Fired after token refresh, receives new token
    * - `unauthorized` - Fired on 401 response
-   * 
+   *
    * @param event - Event name to subscribe to
    * @param handler - Callback function
-   *
    */
-  on(event: "login" | "logout" | "tokenExpired" | "tokenRefreshed" | "unauthorized", handler: (...args: unknown[]) => void): void;
+  on(event: AuthEvent, handler: EventHandler): void;
 
   /**
    * Unsubscribe from authentication events
-   * 
+   *
    * @param event - Event name to unsubscribe from
    * @param handler - The same callback function that was passed to `on()`
-   *
    */
-  off(event: "login" | "logout" | "tokenExpired" | "tokenRefreshed" | "unauthorized", handler: (...args: unknown[]) => void): void;
+  off(event: AuthEvent, handler: EventHandler): void;
 
-  // ==================== 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
+   * Check whether the current client has a stored access token.
    *
+   * @returns True when authenticated, false otherwise
    */
-  hasRole(roleCode: string): boolean;
-  
+  isAuthenticated(): 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
+   * Get the current access token from local storage.
    *
+   * @returns Access token string, or null when not authenticated
    */
-  hasPermission(resource: string, action: string): boolean;
-  
+  getAccessToken(): string | null;
+
   /**
-   * 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
+   * Manually set the current access token.
    *
+   * @param token - JWT access token
+   */
+  setAccessToken(token: string): void;
+
+  /**
+   * Clear all local authentication state, including token and cached user info.
    */
-  isAnonymous(): boolean;
+  clearAuth(): void;
 }

package/types/auth/oauth.d.ts

@@ -1,143 +1,194 @@
 /**
  *  * OAuth and social authentication including:
- * - GitHub OAuth
- * - Google OAuth
- * - WeChat OAuth (Web & Mini Program)
- * - Generic OAuth flow
- * 
+ * - Browser OAuth login
+ * - OAuth callback handling
+ * - Mini Program login
+ * - OAuth account binding management
+ *
  * @module auth/oauth
  */
 
 import type { ClientResult } from '../common';
-import type { LoginResponse } from './password-auth';
+import type { LoginResponse, SuccessResponse } from './password-auth';
 
 // ==================== OAuth Providers ====================
 
 /**
  * Supported OAuth providers
  */
-export type OAuthProvider = 
-  | 'github'
+export type OAuthProvider =
   | 'google'
+  | 'github'
   | 'wechat'
-  | 'wechat-miniprogram'
-  | 'gitlab'
-  | 'microsoft';
+  /** @deprecated Legacy mini-program provider marker kept for compatibility */
+  | 'wechat_mini'
+  | 'platform';
 
 /**
- * OAuth login parameters
- *
+ * OAuth binding information for the current user
  */
-export interface OAuthLoginParams {
+export interface OAuthBinding {
   /** 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;
+
+  /** Provider-specific user ID */
+  providerId: string;
+
+  /** OAuth account email */
+  email: string;
+
+  /** Display name from provider */
+  displayName: string;
+
+  /** Provider avatar URL */
+  avatarUrl: string | null;
+
+  /** Binding creation timestamp */
+  createdAt: string;
 }
 
+// ==================== Mini Program ====================
+
 /**
- * Get OAuth URL parameters
+ * Supported Mini Program platforms
  */
-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[];
-}
+export type MiniProgramPlatform = 'wechat' | 'douyin';
 
 /**
- * OAuth URL response
+ * Unified Mini Program login options
  */
-export interface OAuthUrlResponse {
-  /** Authorization URL to redirect user to */
-  authUrl: string;
-  
-  /** State parameter for verification */
-  state: string;
+export interface MiniLoginParams {
+  /** Optional explicit platform override */
+  platform?: MiniProgramPlatform;
 }
 
-// ==================== WeChat Specific ====================
-
 /**
- * WeChat Mini Program login parameters
- *
+ * Mini Program login parameters
  */
-export interface WeChatMiniProgramLoginParams {
-  /** WeChat login code */
+export interface MiniProgramLoginParams {
+  /** Code from mini-program login API */
   code: string;
-  
-  /** User info from WeChat (optional) */
-  userInfo?: {
-    /** Encrypted user data */
-    encryptedData: string;
-    /** IV for decryption */
-    iv: string;
-  };
+  platform?: MiniProgramPlatform;
 }
 
 /**
- * WeChat web OAuth parameters
+ * Mini Program phone number parameters
  */
-export interface WeChatWebLoginParams {
-  /** Authorization code from WeChat OAuth */
+export interface MiniProgramPhoneParams {
+  /** Code from `getPhoneNumber` button event */
   code: string;
-  
-  /** State parameter */
-  state?: string;
+  platform?: MiniProgramPlatform;
+}
+
+/**
+ * Mini Program phone event-like payload
+ */
+export interface MiniGetPhoneEvent {
+  code?: string;
+  platform?: MiniProgramPlatform;
+  detail?: {
+    code?: string;
+  } | null;
+}
+
+/**
+ * Unified Mini Program phone input
+ */
+export type MiniGetPhoneParams =
+  | string
+  | MiniProgramPhoneParams
+  | MiniGetPhoneEvent;
+
+/**
+ * Mini Program phone number response
+ */
+export interface MiniProgramPhoneResponse {
+  /** Phone number with country code */
+  phone: string;
+
+  /** Whether the phone number is verified by WeChat */
+  phoneVerified: boolean;
 }
 
 // ==================== API ====================
 
 /**
  * OAuth & Social Login API
- * 
- * Methods for OAuth-based authentication.
+ *
+ * Methods for OAuth-based authentication and Mini Program login.
  */
 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
+   * Redirect to OAuth provider for authentication
    *
+   * @param provider - OAuth provider name
+   * @param redirectUrl - Optional post-login redirect target
    */
-  getOAuthUrl(params: GetOAuthUrlParams): Promise<ClientResult<OAuthUrlResponse>>;
+  loginWithOAuth(provider: OAuthProvider, redirectUrl?: string): void;
 
   /**
-   * 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
+   * Handle OAuth callback on the current browser page
    *
+   * Parses the callback hash, stores the access token, and returns the current user.
    */
-  oauthLogin(params: OAuthLoginParams): Promise<ClientResult<LoginResponse>>;
+  handleOAuthCallback(): Promise<ClientResult<LoginResponse>>;
 
   /**
-   * WeChat Mini Program login
-   * 
-   * Authenticates user in WeChat Mini Program environment.
-   * 
-   * @param params - WeChat login code
+   * Login with Mini Program code
+   *
+   * Lower-level API for submitting an already acquired login code.
+   *
+   * @deprecated Prefer `miniLogin()` unless you already have a resolved mini-program login code.
+   *
+   * @param code - Code returned by the current mini-program runtime
    * @returns User info and access token
+   */
+  loginWithMiniProgram(code: string | MiniProgramLoginParams): Promise<ClientResult<LoginResponse>>;
+
+  /**
+   * Unified Mini Program login entry
+   *
+   * Automatically fetches the login code from Taro / wx / tt and submits it to the backend.
+   */
+  miniLogin(params?: MiniLoginParams): Promise<ClientResult<LoginResponse>>;
+
+  /**
+   * Get Mini Program user phone number
+   *
+   * Lower-level API for submitting an already acquired phone code.
+   *
+   * @deprecated Prefer `miniGetPhone(...)` unless you already have a resolved phone authorization code.
+   *
+   * @param code - Code returned by the Mini Program phone-number event
+   * @returns Phone number info
+   */
+  getMiniProgramPhoneNumber(
+    code: string | MiniProgramPhoneParams
+  ): Promise<ClientResult<MiniProgramPhoneResponse>>;
+
+  /**
+   * Unified Mini Program phone binding entry
+   *
+   * Accepts a raw code, `{ code, platform }`, or an event-like object containing `detail.code`.
+   */
+  miniGetPhone(input: MiniGetPhoneParams): Promise<ClientResult<MiniProgramPhoneResponse>>;
+
+  /**
+   * Get OAuth accounts currently bound to the logged-in user
+   */
+  getOAuthBindings(): Promise<ClientResult<OAuthBinding[]>>;
+
+  /**
+   * Redirect to provider binding flow for the current user
+   *
+   * @param provider - OAuth provider name
+   */
+  bindOAuth(provider: OAuthProvider): void;
+
+  /**
+   * Unbind an OAuth account from the current user
    *
+   * @param provider - OAuth provider name
    */
-  wechatMiniProgramLogin(params: WeChatMiniProgramLoginParams): Promise<ClientResult<LoginResponse>>;
+  unbindOAuth(provider: OAuthProvider): Promise<ClientResult<SuccessResponse>>;
 }