@choiceform/shared-auth 0.1.12 → 0.1.14

package/README.md

@@ -54,19 +54,25 @@ import { adminClient, organizationClient } from "better-auth/client/plugins"
 export const auth = initAuth({
   baseURL: import.meta.env.VITE_AUTH_API_URL || "http://localhost:4320",
   tokenStorageKey: "auth-token",
-  defaultRedirectAfterLogin: "/explore",
-  signInPath: "/sign-in",
+  // 可选：如果你想自定义插件
   plugins: [adminClient(), organizationClient({ teams: { enabled: true } })],
 })
+
+// 注意：导航相关配置已移至组件层面：
+// - 登录成功后的导航：在 SignInPage 组件中通过 onAuthSuccess 回调处理
+// - 未授权时的导航：在 ProtectedRoute 组件中通过 onUnauthorized 回调处理
+// - 登出后的导航：在调用 signOut 时传入 redirectTo 参数
 ```
 
 ### 2. 在应用中使用
 
 ```typescript
 import { AuthSync, ProtectedRoute, useAuthInit } from "@choiceform/shared-auth"
+import { useNavigate } from "react-router"
 import { auth } from "./lib/auth"
 
 function App() {
+  const navigate = useNavigate()
   useAuthInit(auth)
 
   return (
@@ -77,7 +83,10 @@ function App() {
         <Route
           path="/*"
           element={
-            <ProtectedRoute auth={auth} signInPath="/sign-in">
+            <ProtectedRoute 
+              auth={auth} 
+              onUnauthorized={() => navigate("/sign-in", { replace: true })}
+            >
               <YourApp />
             </ProtectedRoute>
           }
@@ -92,17 +101,25 @@ function App() {
 
 ```typescript
 import { SignInPage } from "@choiceform/shared-auth"
+import { useNavigate } from "react-router"
 import { auth } from "./lib/auth"
 
 function LoginPage() {
+  const navigate = useNavigate()
+  
   return (
     <SignInPage
       auth={auth}
-      logo={<YourLogo />}
       title="Your App Title"
       description="Your app description"
       provider="github"
-      redirectAfterLogin="/dashboard"
+      redirectUrl="/dashboard"
+      onAuthSuccess={() => navigate("/dashboard")}
+      githubButton={(isSigningIn) => (
+        <button disabled={isSigningIn}>
+          {isSigningIn ? "Redirecting to GitHub..." : "Sign in with GitHub"}
+        </button>
+      )}
     />
   )
 }
@@ -118,9 +135,9 @@ function LoginPage() {
 
 - `baseURL`: Better Auth API 基础 URL（必需）
 - `tokenStorageKey?`: Token 存储的 localStorage key（默认: `'auth-token'`）
-- `defaultRedirectAfterLogin?`: 登录后默认跳转地址（默认: `'/explore'`）
-- `signInPath?`: 登录页面路径（默认: `'/sign-in'`）
-- `plugins?`: Better Auth 插件列表（默认包含 `adminClient()` 和 `organizationClient()`）
+- `plugins?`: Better Auth 插件列表（默认包含 `organizationClient()`）
+- ~~`defaultRedirectAfterLogin?`~~: (已废弃) 建议在 SignInPage 组件中通过 `redirectUrl` prop 传入
+- ~~`signInPath?`~~: (已废弃) 建议在 ProtectedRoute 组件中通过 `onUnauthorized` 回调处理导航
 
 **返回：** `AuthInstance`
 
@@ -132,11 +149,11 @@ function LoginPage() {
 
 - `baseURL`: Better Auth API 基础 URL（必需）
 - `tokenStorageKey?`: Token 存储的 localStorage key（默认: `'auth-token'`）
-- `defaultRedirectAfterLogin?`: 登录后默认跳转地址（默认: `'/explore'`）
-- `signInPath?`: 登录页面路径（默认: `'/sign-in'`）
 - `plugins?`: Better Auth 插件列表
 - `callbackURLBuilder?`: 自定义回调 URL 构建函数
 - `getSessionEndpoint?`: 获取 session 的端点路径（默认: `'/v1/auth/get-session'`）
+- ~~`defaultRedirectAfterLogin?`~~: (已废弃) 建议在 SignInPage 组件中通过 `redirectUrl` prop 传入
+- ~~`signInPath?`~~: (已废弃) 建议在 ProtectedRoute 组件中通过 `onUnauthorized` 回调处理导航
 
 **返回：** `AuthInstance`
 
@@ -190,9 +207,9 @@ Better Auth 认证状态同步组件。
 
 - `auth`: AuthInstance
 - `children`: React.ReactNode
-- `signInPath?`: 登录页面路径（默认: `'/sign-in'`）
-- `loadingComponent?`: 加载中组件
-- `loadingMessage?`: 加载中消息（默认: `'Checking authentication...'`）
+- `onUnauthorized`: () => void - 当用户未认证时的回调函数（用于导航到登录页）
+- `loadingComponent?`: React.ComponentType<{ message?: string }> - 自定义加载组件
+- `loadingMessage?`: string - 加载中消息（默认: `'Checking authentication...'`）
 
 ### `SignInPage`
 
@@ -201,15 +218,16 @@ Better Auth 认证状态同步组件。
 **Props：**
 
 - `auth`: AuthInstance
-- `className?`: 自定义样式类名
-- `logo?`: Logo 组件
-- `title?`: 标题
-- `description?`: 描述
-- `provider?`: OAuth 提供商（默认: `'github'`）
-- `redirectAfterLogin?`: 登录后跳转地址（默认: `'/explore'`）
-- `signInButtonText?`: 登录按钮文本（默认: `'Sign in with GitHub'`）
-- `signingInButtonText?`: 登录中按钮文本（默认: `'Redirecting to GitHub...'`）
-- `signInButtonIcon?`: 登录按钮图标
+- `className?`: string - 自定义样式类名
+- `title?`: string - 标题
+- `description?`: string - 描述
+- `provider?`: string - OAuth 提供商（默认: `'github'`）
+- `redirectUrl?`: string - OAuth 回调重定向地址（默认: `'/explore'`）
+- `onAuthSuccess?`: () => void - 认证成功后的回调函数（用于导航）
+- `githubButton?`: (isSigningIn: boolean) => React.ReactNode - 自定义 GitHub 登录按钮渲染函数
+- `beforeElement?`: React.ReactNode - 在登录表单之前渲染的元素
+- `afterElement?`: React.ReactNode - 在登录表单之后渲染的元素
+- `footerText?`: React.ReactNode - 页脚文本
 
 ## 工具函数
 
@@ -440,13 +458,17 @@ try {
 
 ### 5. 退出登录
 
-退出登录时使用 `signOut` 方法：
+退出登录时使用 `signOut` 方法，可以选择性地传入重定向地址：
 
 ```typescript
 async function handleSignOut() {
   try {
-    await auth.authActions.signOut()
-    // 用户将被重定向到登录页面
+    // 传入重定向地址，登出后会自动跳转
+    await auth.authActions.signOut("/sign-in")
+    
+    // 或者不传入地址，由调用方手动处理后续导航
+    // await auth.authActions.signOut()
+    // navigate("/sign-in")
   } catch (error) {
     console.error("Sign out failed:", error)
   }

package/dist/components/protected-route.d.ts

@@ -7,7 +7,7 @@ interface ProtectedRouteProps {
         message?: string;
     }>;
     loadingMessage?: string;
-    signInPath?: string;
+    onUnauthorized: () => void;
 }
 /**
  * 路由保护组件

package/dist/components/protected-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-route.d.ts","sourceRoot":"","sources":["../../src/components/protected-route.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,UAAU,mBAAmB;IAC3B,IAAI,EAAE,YAAY,CAAA;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,gBAAgB,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CA8BxD,CAAA;AAED,eAAe,cAAc,CAAA"}
+{"version":3,"file":"protected-route.d.ts","sourceRoot":"","sources":["../../src/components/protected-route.tsx"],"names":[],"mappings":"AACA,OAAO,KAAoB,MAAM,OAAO,CAAA;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,UAAU,mBAAmB;IAC3B,IAAI,EAAE,YAAY,CAAA;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,gBAAgB,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,cAAc,EAAE,MAAM,IAAI,CAAA;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAgCxD,CAAA;AAED,eAAe,cAAc,CAAA"}

package/dist/components/protected-route.js

@@ -1,15 +1,21 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { observer } from "@legendapp/state/react";
-import { Navigate } from "react-router";
+import { useEffect } from "react";
 /**
  * 路由保护组件
  * 等待认证初始化完成，根据认证状态进行路由保护
  */
-export const ProtectedRoute = observer(({ children, auth, signInPath = "/sign-in", loadingComponent, loadingMessage }) => {
+export const ProtectedRoute = observer(({ children, auth, loadingComponent, loadingMessage, onUnauthorized }) => {
     const { authStore, authComputed } = auth;
     // 检查各种状态
     const isInitializing = authComputed.isInitializing.get();
     const isAuthenticated = authStore.isAuthenticated.get();
+    // 当未认证时调用回调
+    useEffect(() => {
+        if (!isInitializing && !isAuthenticated) {
+            onUnauthorized();
+        }
+    }, [isInitializing, isAuthenticated, onUnauthorized]);
     // 检查初始化状态
     if (isInitializing) {
         if (loadingComponent) {
@@ -20,7 +26,7 @@ export const ProtectedRoute = observer(({ children, auth, signInPath = "/sign-in
     }
     // 检查认证状态
     if (!isAuthenticated) {
-        return (_jsx(Navigate, { to: signInPath, replace: true }));
+        return null;
     }
     // 所有检查通过，渲染子组件
     return _jsx(_Fragment, { children: children });

package/dist/components/sign-in-page.d.ts

@@ -8,13 +8,14 @@ interface SignInPageProps {
     description?: string;
     footerText?: React.ReactNode;
     githubButton?: (isSigningIn: boolean) => React.ReactNode;
+    onAuthSuccess?: () => void;
     provider?: string;
-    redirectAfterLogin?: string;
+    redirectUrl?: string;
     title?: string;
 }
 /**
  * 登录页面组件
  */
-export declare function SignInPage({ afterElement, auth, beforeElement, redirectAfterLogin, provider, title, description, githubButton, className, footerText, }: SignInPageProps): import("react/jsx-runtime").JSX.Element;
+export declare function SignInPage({ afterElement, auth, beforeElement, onAuthSuccess, redirectUrl, provider, title, description, githubButton, className, footerText, }: SignInPageProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=sign-in-page.d.ts.map

package/dist/components/sign-in-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sign-in-page.d.ts","sourceRoot":"","sources":["../../src/components/sign-in-page.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA8B,MAAM,OAAO,CAAA;AAElD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,UAAU,eAAe;IACvB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,KAAK,CAAC,SAAS,CAAC;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EACzB,YAAY,EACZ,IAAI,EACJ,aAAa,EACb,kBAA+B,EAC/B,QAAmB,EACnB,KAAK,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,GACX,EAAE,eAAe,2CAgDjB"}
+{"version":3,"file":"sign-in-page.d.ts","sourceRoot":"","sources":["../../src/components/sign-in-page.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA8B,MAAM,OAAO,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,UAAU,eAAe;IACvB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC9B,IAAI,EAAE,YAAY,CAAA;IAClB,aAAa,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,KAAK,CAAC,SAAS,CAAA;IACxD,aAAa,CAAC,EAAE,MAAM,IAAI,CAAA;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EACzB,YAAY,EACZ,IAAI,EACJ,aAAa,EACb,aAAa,EACb,WAA0B,EAC1B,QAAmB,EACnB,KAAK,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,GACX,EAAE,eAAe,2CA+CjB"}

package/dist/components/sign-in-page.js

@@ -2,25 +2,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Slot } from "@choiceform/design-system";
 import { use$ } from "@legendapp/state/react";
 import { useEffect, useState } from "react";
-import { useNavigate } from "react-router";
 /**
  * 登录页面组件
  */
-export function SignInPage({ afterElement, auth, beforeElement, redirectAfterLogin = "/explore", provider = "github", title, description, githubButton, className, footerText, }) {
-    const navigate = useNavigate();
+export function SignInPage({ afterElement, auth, beforeElement, onAuthSuccess, redirectUrl = "/community", provider = "github", title, description, githubButton, className, footerText, }) {
     const { authStore, authActions } = auth;
     const { isAuthenticated, error } = use$(authStore);
     const [isSigningIn, setIsSigningIn] = useState(false);
     useEffect(() => {
-        if (isAuthenticated) {
-            navigate(redirectAfterLogin);
+        if (isAuthenticated && onAuthSuccess) {
+            onAuthSuccess();
         }
-    }, [isAuthenticated, navigate, redirectAfterLogin]);
+    }, [isAuthenticated, onAuthSuccess]);
     const handleSignIn = async () => {
         // 设置本地 loading 状态
         setIsSigningIn(true);
         try {
-            await authActions.signIn(provider, `${window.location.origin}${redirectAfterLogin}`);
+            await authActions.signIn(provider, `${window.location.origin}${redirectUrl}`);
             // OAuth 会重定向，所以这里的代码可能不会执行
             // loading 状态会在页面刷新后重置
         }

package/dist/config.d.ts

@@ -16,8 +16,10 @@ export interface AuthConfig {
      */
     callbackURLBuilder?: (redirectTo: string, baseURL: string) => string;
     /**
-     * OAuth 重定向后的默认跳转地址
-     * @default '/explore'
+     * OAuth 重定向后的默认跳转地址（可选）
+     * 推荐在组件层面通过 props 传入，而不是在配置中设置
+     * @default undefined
+     * @deprecated 建议在 SignInPage 组件中通过 redirectUrl prop 传入
      */
     defaultRedirectAfterLogin?: string;
     /**
@@ -30,10 +32,18 @@ export interface AuthConfig {
      */
     plugins?: BetterAuthPlugin[];
     /**
-     * 登录页面的路由路径
-     * @default '/sign-in'
+     * 登录页面的路由路径（可选）
+     * 推荐在组件层面通过回调传入，而不是在配置中设置
+     * @default undefined
+     * @deprecated 建议在 ProtectedRoute 组件中通过 onUnauthorized 回调处理导航
      */
     signInPath?: string;
+    /**
+     * 跳过错误时的 token 清除（开发环境用）
+     * 启用后，网络错误、解析错误等不会清除 token，避免开发时频繁登出
+     * @default false
+     */
+    skipTokenCleanupOnError?: boolean;
     /**
      * Token 存储的 localStorage key
      * @default 'auth-token'
@@ -43,8 +53,11 @@ export interface AuthConfig {
 /**
  * 默认配置
  */
-export declare const defaultAuthConfig: Required<Omit<AuthConfig, "plugins" | "callbackURLBuilder">> & {
+export declare const defaultAuthConfig: Required<Omit<AuthConfig, "plugins" | "callbackURLBuilder" | "defaultRedirectAfterLogin" | "signInPath" | "skipTokenCleanupOnError">> & {
     callbackURLBuilder: (redirectTo: string, baseURL: string) => string;
+    defaultRedirectAfterLogin: undefined;
     plugins: BetterAuthPlugin[];
+    signInPath: undefined;
+    skipTokenCleanupOnError: false;
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,CACvC,cAAc,4BAA4B,EAAE,WAAW,CACxD,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAEpE;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAElC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAE5B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,oBAAoB,CAAC,CAAC,GAAG;IAC7F,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACnE,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAW5B,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,CACvC,cAAc,4BAA4B,EAAE,WAAW,CACxD,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAEpE;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAElC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAE5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAA;IAEjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CACtC,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,oBAAoB,GAAG,2BAA2B,GAAG,YAAY,GAAG,yBAAyB,CAAC,CAC5H,GAAG;IACF,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACnE,yBAAyB,EAAE,SAAS,CAAA;IACpC,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,UAAU,EAAE,SAAS,CAAA;IACrB,uBAAuB,EAAE,KAAK,CAAA;CAY/B,CAAA"}

package/dist/config.js

@@ -6,9 +6,10 @@ export const defaultAuthConfig = {
     callbackURLBuilder: (redirectTo, baseURL) => {
         return `${baseURL}/v1/auth/redirect?to=${encodeURIComponent(redirectTo)}`;
     },
-    defaultRedirectAfterLogin: "/explore",
+    defaultRedirectAfterLogin: undefined,
     getSessionEndpoint: "/v1/auth/get-session",
     plugins: [],
-    signInPath: "/sign-in",
+    signInPath: undefined,
+    skipTokenCleanupOnError: false,
     tokenStorageKey: "auth-token",
 };

package/dist/core/init-auth-sync.d.ts

@@ -0,0 +1,7 @@
+import type { AuthInstance } from "../core";
+/**
+ * 同步版本的认证初始化
+ * 可以在应用渲染前调用（非 React hook）
+ */
+export declare function initAuthSync(auth: AuthInstance): Promise<void>;
+//# sourceMappingURL=init-auth-sync.d.ts.map

package/dist/core/init-auth-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-auth-sync.d.ts","sourceRoot":"","sources":["../../src/core/init-auth-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BpE"}

package/dist/core/init-auth-sync.js

@@ -0,0 +1,34 @@
+/**
+ * 同步版本的认证初始化
+ * 可以在应用渲染前调用（非 React hook）
+ */
+export async function initAuthSync(auth) {
+    const { authActions, tokenStorage } = auth;
+    // 检查 URL 中的 token
+    const urlParams = new URLSearchParams(window.location.search);
+    let tokenFromUrl = urlParams.get("token");
+    if (tokenFromUrl) {
+        if (decodeURIComponent(tokenFromUrl) === tokenFromUrl) {
+            tokenFromUrl = encodeURIComponent(tokenFromUrl);
+        }
+        // 立即清理 URL 中的 token 参数（避免暴露）
+        urlParams.delete("token");
+        const newUrl = urlParams.toString()
+            ? `${window.location.pathname}?${urlParams.toString()}`
+            : window.location.pathname;
+        window.history.replaceState({}, "", newUrl);
+        // 使用 token 获取 session
+        await authActions.fetchSessionWithToken(tokenFromUrl);
+    }
+    else {
+        // 检查 localStorage 中是否有存储的 token
+        const storedToken = tokenStorage.get();
+        if (storedToken) {
+            await authActions.fetchSessionWithToken(storedToken);
+        }
+        else {
+            // 没有 token，标记为已加载
+            await authActions.initialize(null, true);
+        }
+    }
+}