@amaster.ai/auth-client 1.0.0-beta.6 → 1.0.0-beta.73

package/README.md

@@ -8,7 +8,8 @@ Authentication SDK for Amaster Platform - Complete client-side authentication so
 - 🔄 **Automatic Token Refresh**: JWT token auto-refresh before expiration
 - 📦 **Token Storage**: localStorage or sessionStorage with SSR support
 - 🎯 **Permission System**: Role-based and permission-based access control
-- 🔗 **OAuth Integration**: Google, GitHub, WeChat, and custom OAuth providers
+- 👤 **Anonymous Access**: Automatic support for anonymous users with configurable permissions
+- 🔗 **OAuth Integration**: Google, GitHub, WeChat OAuth, WeChat Mini Program, and custom OAuth providers
 - 📡 **Event System**: Listen to login, logout, and token events
 - 💾 **Session Management**: View and revoke active sessions
 - 🔒 **Type-Safe**: Full TypeScript support
@@ -58,29 +59,56 @@ if (result.data) {
 const user = await authClient.getMe();
 
 // Check permissions
-if (authClient.hasPermission("user.read")) {
+if (authClient.hasPermission("user", "read")) {
   // Show user list
 }
 ```
 
 ## Configuration
 
+### Zero Configuration (Recommended)
+
+The SDK works out of the box with **zero configuration**:
+
+```typescript
+const authClient = createAuthClient();
+
+// Storage auto-detects environment:
+// - Browser → localStorage
+// - WeChat Mini Program → wx.setStorageSync
+// - SSR/Node.js → no-op (no persistence)
+```
+
+### Optional Configuration
+
 ```typescript
 interface AuthClientOptions {
   baseURL?: string; // API base URL, defaults to window.location.origin
-  storage?: "localStorage" | "sessionStorage"; // Token storage type, defaults to localStorage
+  headers?: Record<string, string>; // Custom headers for all requests
   onTokenExpired?: () => void; // Token expiration callback
   onUnauthorized?: () => void; // Unauthorized (401) callback
+  autoHandleOAuthCallback?: boolean; // Auto-handle OAuth callback hash on init, default true
+  autoRedirectAfterLogin?: boolean; // Auto-consume ?redirect=... after any successful login, default true
 }
 ```
 
+**Example:**
+
+```typescript
+const authClient = createAuthClient({
+  baseURL: "https://api.example.com",
+  onTokenExpired: () => (window.location.href = "/login"),
+  onUnauthorized: () => alert("Session expired"),
+});
+```
+
 **Built-in Features (Zero Config):**
 
-- ✅ **Auto Token Refresh**: Refreshes 5 minutes before expiry
-- ✅ **Auto Permission Sync**: Syncs on page load and every token refresh
-- ✅ **Lightweight Data**: Only permission names cached, not full objects
-- ✅ **On-Demand DataScope**: Loads only when needed
-- ✅ **SSR Compatible**: Works in both browser and server environments
+- ✅ Auto environment detection (browser, WeChat Mini Program, SSR)
+- ✅ Auto token refresh (5 minutes before expiry)
+- ✅ Auto permission sync
+- ✅ Auto anonymous support
+- ✅ Smart storage (localStorage, wx.storage, no-op for SSR)
 
 ## Authentication
 
@@ -154,15 +182,21 @@ const redirectUrl = sessionStorage.getItem("oauth_redirect") || "/";
 window.location.href = redirectUrl;
 ```
 
+If the callback page URL already carries `?redirect=...` such as
+`/login?redirect=%2Fapi%2Foauth%2Fauthorize...`, the SDK will reuse that
+redirect target automatically after a successful OAuth callback. Both
+`#access_token=...` and `#accessToken=...` callback hash formats are supported.
+
+By default, the same `?redirect=...` handling is also applied to password login,
+verification-code login, registration auto-login, and mini-program login. Set
+`autoRedirectAfterLogin: false` to disable this behavior and fully control
+navigation in the application layer.
+
 **Popup window:**
 
 ```typescript
 // Main page
-const popup = window.open(
-  "/api/auth/oauth/google",
-  "oauth-login",
-  "width=600,height=700"
-);
+const popup = window.open("/api/auth/oauth/google", "oauth-login", "width=600,height=700");
 
 window.addEventListener("message", (event) => {
   if (event.data.type === "oauth-success") {
@@ -178,6 +212,177 @@ if (window.opener) {
 }
 ```
 
+### WeChat Mini Program Login
+
+The SDK automatically detects WeChat Mini Program environment and uses `wx.storage`:
+
+```typescript
+import { createAuthClient } from "@amaster.ai/auth-client";
+
+// Zero configuration - auto-detects WeChat environment
+const authClient = createAuthClient({
+  baseURL: "https://api.yourdomain.com",
+});
+
+// Login with WeChat code
+wx.login({
+  success: async (res) => {
+    if (res.code) {
+      const result = await authClient.loginWithMiniProgram(res.code);
+
+      if (result.data) {
+        console.log("Logged in:", result.data.user);
+        // Token automatically saved to wx.storage
+        wx.switchTab({ url: "/pages/index/index" });
+      } else if (result.error) {
+        wx.showToast({
+          title: result.error.message || "Login failed",
+          icon: "none",
+        });
+      }
+    }
+  },
+  fail: (err) => {
+    console.error("wx.login failed:", err);
+  },
+});
+```
+
+**Get user phone number (optional):**
+
+```xml
+<!-- WXML -->
+<button
+  open-type="getPhoneNumber"
+  bindgetphonenumber="onGetPhoneNumber"
+>
+  Get Phone Number
+</button>
+```
+
+```typescript
+// JS
+async onGetPhoneNumber(e) {
+  const { code } = e.detail;
+
+  if (code) {
+    const result = await authClient.getMiniProgramPhoneNumber(code);
+
+    if (result.data) {
+      console.log("Phone number:", result.data.phone);
+      console.log("Verified:", result.data.phoneVerified);
+
+      // Update UI with phone number
+      this.setData({
+        phone: result.data.phone
+      });
+    } else if (result.error) {
+      wx.showToast({
+        title: result.error.message || 'Failed to get phone number',
+        icon: 'none'
+      });
+    }
+  } else {
+    // User denied authorization
+    console.log("User cancelled phone number authorization");
+  }
+}
+```
+
+**Complete Mini Program example:**
+
+```typescript
+// pages/login/login.js
+import { createAuthClient } from "@amaster.ai/auth-client";
+
+const authClient = createAuthClient({
+  baseURL: "https://api.yourdomain.com",
+});
+
+Page({
+  data: {
+    userInfo: null,
+    hasPhone: false,
+  },
+
+  // Auto-login on page load
+  onLoad() {
+    this.handleLogin();
+  },
+
+  // WeChat Mini Program login
+  async handleLogin() {
+    wx.showLoading({ title: "Logging in..." });
+
+    wx.login({
+      success: async (res) => {
+        if (res.code) {
+          const result = await authClient.loginWithMiniProgram(res.code);
+
+          wx.hideLoading();
+
+          if (result.data) {
+            this.setData({
+              userInfo: result.data.user,
+            });
+
+            // Navigate to home
+            wx.switchTab({ url: "/pages/index/index" });
+          } else {
+            wx.showToast({
+              title: "Login failed",
+              icon: "none",
+            });
+          }
+        }
+      },
+      fail: () => {
+        wx.hideLoading();
+        wx.showToast({
+          title: "Login failed",
+          icon: "none",
+        });
+      },
+    });
+  },
+
+  // Get phone number with user authorization
+  async onGetPhoneNumber(e) {
+    const { code } = e.detail;
+
+    if (!code) {
+      wx.showToast({
+        title: "Authorization cancelled",
+        icon: "none",
+      });
+      return;
+    }
+
+    wx.showLoading({ title: "Getting phone..." });
+
+    const result = await authClient.getMiniProgramPhoneNumber(code);
+
+    wx.hideLoading();
+
+    if (result.data) {
+      this.setData({
+        hasPhone: true,
+      });
+
+      wx.showToast({
+        title: "Phone number obtained",
+        icon: "success",
+      });
+    } else {
+      wx.showToast({
+        title: result.error?.message || "Failed to get phone",
+        icon: "none",
+      });
+    }
+  },
+});
+```
+
 ### Logout
 
 ```typescript
@@ -215,67 +420,50 @@ await authClient.changePassword({
 
 ## Permission Checks
 
-### Local Permission Checks (Fast)
+### Anonymous Access Support
 
-Permissions are cached locally as string arrays for fast UI checks:
+The SDK automatically supports anonymous users with **zero configuration**:
 
 ```typescript
-// Check single role
-if (authClient.hasRole("admin")) {
-  // Admin only
-}
+// Create client
+const authClient = createAuthClient();
 
-// Check single permission
-if (authClient.hasPermission("user.read")) {
-  // Can read users
+// Permission checks work for both authenticated and anonymous users
+if (authClient.hasPermission("article", "read")) {
+  showArticleList();
 }
 
-// Check any permission
-if (authClient.hasAnyPermission(["user.read", "user.manage"])) {
-  // Has at least one permission
+// Check if user is anonymous
+if (authClient.isAnonymous()) {
+  showLoginPrompt();
 }
 
-// Check all permissions
-if (authClient.hasAllPermissions(["user.read", "user.write"])) {
-  // Has all permissions
-}
+// After login, permissions automatically update
+await authClient.login({ ... });
 ```
 
-### On-Demand Data Scope Loading
+### Local Permission Checks (Fast)
 
-Data scopes are loaded only when needed to reduce data transfer:
+Permissions are cached locally for fast UI checks:
 
 ```typescript
-// Get data scope for a specific permission
-const result = await authClient.getPermissionScope("user.read");
-if (result.data) {
-  const { dataScope } = result.data;
-  
-  if (dataScope.scopeType === "department") {
-    // Filter users by department
-    const users = await api.getUsers({
-      departmentId: dataScope.scopeFilter.departmentId
-    });
-  } else if (dataScope.scopeType === "all") {
-    // Show all users
-    const users = await api.getUsers();
-  }
+// Check role
+if (authClient.hasRole("admin")) {
+  showAdminPanel();
 }
-```
 
-**Optimized Data Structure:**
+if (authClient.isAnonymous()) {
+  showLoginPrompt();
+}
 
-```typescript
-// User object (lightweight)
-{
-  uid: "xxx",
-  email: "user@example.com",
-  roles: ["admin", "user"],  // Only role codes
-  permissions: ["user.read", "user.write", "order.read"],  // Only permission names
-  // NO dataScopes - loaded on demand
+// Check permission
+if (authClient.hasPermission("user", "read")) {
+  showUserList();
 }
 ```
 
+````
+
 ## OAuth Bindings
 
 ### Get Bindings
@@ -416,48 +604,32 @@ if (result.error) {
 
 ### Token Management
 
-- SDK automatically manages Access Token and Refresh Token
-- Access Token is stored in localStorage/sessionStorage
-- Refresh Token is managed by backend via HttpOnly Cookie
-- Token is automatically refreshed 5 minutes before expiration (configurable)
-
-### Permission Sync
-
-- **On Page Load**: User info and permissions automatically sync from backend
-- **On Token Refresh**: Permissions re-sync every 5 minutes when token refreshes
-- **Manual Sync**: Call `await authClient.getMe()` to force sync anytime
-
-**Behavior:**
-- Permissions always stay fresh without any configuration
-- Page refresh loads latest permissions from backend
-- Background sync happens automatically every 5 minutes
+- Tokens are automatically managed by the SDK
+- Access Token refreshes 5 minutes before expiration
+- No manual token handling required
 
 ### Permission Checks
 
-- **Frontend permission checks are for UI control only** (show/hide buttons, menus)
-- **Backend must verify permissions again** - frontend checks are NOT security measures
-- Use permission checks to improve UX, not as security enforcement
+- Use permission checks for UI control (show/hide buttons, menus)
+- Frontend checks are NOT security measures
+- Backend must always verify permissions
 
 ### SSR Support
 
-The SDK detects SSR environments and uses a no-op storage adapter:
+The SDK works in both browser and SSR environments:
 
 ```typescript
-// Safe in both browser and SSR
 const authClient = createAuthClient();
 ```
 
 ## TypeScript
 
-Full TypeScript support with comprehensive type definitions:
+Full TypeScript support:
 
 ```typescript
 import type {
   User,
   LoginResponse,
-  Permission,
-  Role,
-  DataScope,
   Session,
   OAuthBinding,
 } from "@amaster.ai/auth-client";
@@ -470,3 +642,4 @@ MIT
 ## Contributing
 
 Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+````

package/dist/auth.d.cts

@@ -14,7 +14,7 @@
  * ============================================================================
  */
 import { HttpClient, ClientResult } from '@amaster.ai/http-client';
-import { s as User, k as RegisterParams, f as LoginResponse, L as LoginParams, d as CodeLoginParams, S as SendCodeParams, r as SuccessResponse, b as CaptchaResponse, h as OAuthProvider, R as RefreshTokenResponse } from './types-Bgi_Lwkp.cjs';
+import { q as User, i as RegisterParams, e as LoginResponse, L as LoginParams, c as CodeLoginParams, S as SendCodeParams, p as SuccessResponse, b as CaptchaResponse, g as OAuthProvider, M as MiniProgramPhoneResponse, R as RefreshTokenResponse } from './types-DGF9cpAg.cjs';
 
 /**
  * Authentication Module
@@ -30,11 +30,16 @@ import { s as User, k as RegisterParams, f as LoginResponse, L as LoginParams, d
  * - Logout and token refresh
  */
 
+declare const browserNavigation: {
+    replace(url: string): void;
+};
 interface AuthModuleDeps {
     http: HttpClient;
     onLoginSuccess: (user: User, accessToken: string) => void;
+    autoRedirectAfterLogin: boolean;
     storage: {
         getItem: (key: string) => string | null;
+        setItem: (key: string, value: string) => void;
     };
     clearAuth: () => void;
 }
@@ -59,8 +64,14 @@ declare function createAuthModule(deps: AuthModuleDeps): {
      * @category Authentication
      * @example
      * ```typescript
+     * // Auto-detect loginType from username
+     * await auth.login({
+     *   username: "john_doe",
+     *   password: "Password@123",
+     * });
+     *
+     * // Auto-detect loginType from email
      * await auth.login({
-     *   loginType: "email",
      *   email: "user@example.com",
      *   password: "Password@123",
      * });
@@ -73,11 +84,17 @@ declare function createAuthModule(deps: AuthModuleDeps): {
      * @category Authentication
      * @example
      * ```typescript
+     * // Auto-detect loginType from email
      * await auth.loginWithCode({
-     *   loginType: "email",
      *   email: "user@example.com",
      *   code: "123456",
      * });
+     *
+     * // Auto-detect loginType from phone
+     * await auth.loginWithCode({
+     *   phone: "13800138000",
+     *   code: "123456",
+     * });
      * ```
      */
     loginWithCode(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
@@ -116,6 +133,51 @@ declare function createAuthModule(deps: AuthModuleDeps): {
      * @category Authentication
      */
     handleOAuthCallback(): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Login with WeChat Mini Program code
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * // In WeChat Mini Program
+     * wx.login({
+     *   success: async (res) => {
+     *     if (res.code) {
+     *       const result = await auth.loginWithMiniProgram(res.code);
+     *       if (result.data) {
+     *         console.log("Logged in:", result.data.user);
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    loginWithMiniProgram(code: string): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Get WeChat Mini Program user phone number
+     * Requires user authorization via getPhoneNumber button
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * // WXML
+     * <button open-type="getPhoneNumber" bindgetphonenumber="onGetPhoneNumber">
+     *   Get Phone Number
+     * </button>
+     *
+     * // JS
+     * async onGetPhoneNumber(e) {
+     *   const { code } = e.detail;
+     *   if (code) {
+     *     const result = await auth.getMiniProgramPhoneNumber(code);
+     *     if (result.data) {
+     *       console.log("Phone:", result.data.phone);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    getMiniProgramPhoneNumber(code: string): Promise<ClientResult<MiniProgramPhoneResponse>>;
     /**
      * Logout current user
      *
@@ -135,4 +197,4 @@ declare function createAuthModule(deps: AuthModuleDeps): {
 };
 type AuthModule = ReturnType<typeof createAuthModule>;
 
-export { type AuthModule, type AuthModuleDeps, createAuthModule };
+export { type AuthModule, type AuthModuleDeps, browserNavigation, createAuthModule };

package/dist/auth.d.ts

@@ -14,7 +14,7 @@
  * ============================================================================
  */
 import { HttpClient, ClientResult } from '@amaster.ai/http-client';
-import { s as User, k as RegisterParams, f as LoginResponse, L as LoginParams, d as CodeLoginParams, S as SendCodeParams, r as SuccessResponse, b as CaptchaResponse, h as OAuthProvider, R as RefreshTokenResponse } from './types-Bgi_Lwkp.js';
+import { q as User, i as RegisterParams, e as LoginResponse, L as LoginParams, c as CodeLoginParams, S as SendCodeParams, p as SuccessResponse, b as CaptchaResponse, g as OAuthProvider, M as MiniProgramPhoneResponse, R as RefreshTokenResponse } from './types-DGF9cpAg.js';
 
 /**
  * Authentication Module
@@ -30,11 +30,16 @@ import { s as User, k as RegisterParams, f as LoginResponse, L as LoginParams, d
  * - Logout and token refresh
  */
 
+declare const browserNavigation: {
+    replace(url: string): void;
+};
 interface AuthModuleDeps {
     http: HttpClient;
     onLoginSuccess: (user: User, accessToken: string) => void;
+    autoRedirectAfterLogin: boolean;
     storage: {
         getItem: (key: string) => string | null;
+        setItem: (key: string, value: string) => void;
     };
     clearAuth: () => void;
 }
@@ -59,8 +64,14 @@ declare function createAuthModule(deps: AuthModuleDeps): {
      * @category Authentication
      * @example
      * ```typescript
+     * // Auto-detect loginType from username
+     * await auth.login({
+     *   username: "john_doe",
+     *   password: "Password@123",
+     * });
+     *
+     * // Auto-detect loginType from email
      * await auth.login({
-     *   loginType: "email",
      *   email: "user@example.com",
      *   password: "Password@123",
      * });
@@ -73,11 +84,17 @@ declare function createAuthModule(deps: AuthModuleDeps): {
      * @category Authentication
      * @example
      * ```typescript
+     * // Auto-detect loginType from email
      * await auth.loginWithCode({
-     *   loginType: "email",
      *   email: "user@example.com",
      *   code: "123456",
      * });
+     *
+     * // Auto-detect loginType from phone
+     * await auth.loginWithCode({
+     *   phone: "13800138000",
+     *   code: "123456",
+     * });
      * ```
      */
     loginWithCode(params: CodeLoginParams): Promise<ClientResult<LoginResponse>>;
@@ -116,6 +133,51 @@ declare function createAuthModule(deps: AuthModuleDeps): {
      * @category Authentication
      */
     handleOAuthCallback(): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Login with WeChat Mini Program code
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * // In WeChat Mini Program
+     * wx.login({
+     *   success: async (res) => {
+     *     if (res.code) {
+     *       const result = await auth.loginWithMiniProgram(res.code);
+     *       if (result.data) {
+     *         console.log("Logged in:", result.data.user);
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    loginWithMiniProgram(code: string): Promise<ClientResult<LoginResponse>>;
+    /**
+     * Get WeChat Mini Program user phone number
+     * Requires user authorization via getPhoneNumber button
+     *
+     * @category Authentication
+     * @example
+     * ```typescript
+     * // WXML
+     * <button open-type="getPhoneNumber" bindgetphonenumber="onGetPhoneNumber">
+     *   Get Phone Number
+     * </button>
+     *
+     * // JS
+     * async onGetPhoneNumber(e) {
+     *   const { code } = e.detail;
+     *   if (code) {
+     *     const result = await auth.getMiniProgramPhoneNumber(code);
+     *     if (result.data) {
+     *       console.log("Phone:", result.data.phone);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    getMiniProgramPhoneNumber(code: string): Promise<ClientResult<MiniProgramPhoneResponse>>;
     /**
      * Logout current user
      *
@@ -135,4 +197,4 @@ declare function createAuthModule(deps: AuthModuleDeps): {
 };
 type AuthModule = ReturnType<typeof createAuthModule>;
 
-export { type AuthModule, type AuthModuleDeps, createAuthModule };
+export { type AuthModule, type AuthModuleDeps, browserNavigation, createAuthModule };