@ahoo-wang/fetcher-react 3.5.5 → 3.5.8

package/README.md

@@ -47,20 +47,24 @@ robust data fetching capabilities.
     - [useImmerKeyStorage](#useimmerkeystorage-hook)
   - [Event Hooks](#event-hooks)
     - [useEventSubscription](#useeventsubscription-hook)
+  - [CoSec Security Hooks](#cosec-security-hooks)
+    - [useSecurity](#usesecurity-hook)
+    - [SecurityProvider](#securityprovider)
+    - [useSecurityContext](#usesecuritycontext-hook)
   - [Wow Query Hooks](#wow-query-hooks)
-    - [Basic Query Hooks](#basic-query-hooks)
-      - [useListQuery](#uselistquery-hook)
-      - [usePagedQuery](#usepagedquery-hook)
-      - [useSingleQuery](#usesinglequery-hook)
-      - [useCountQuery](#usecountquery-hook)
-    - [Fetcher Query Hooks](#fetcher-query-hooks)
-      - [useFetcherListQuery](#usefetcherlistquery-hook)
-      - [useFetcherPagedQuery](#usefetcherpagedquery-hook)
-      - [useFetcherSingleQuery](#usefetchersinglequery-hook)
-      - [useFetcherCountQuery](#usefetchercountquery-hook)
-    - [Stream Query Hooks](#stream-query-hooks)
-      - [useListStreamQuery](#useliststreamquery-hook)
-      - [useFetcherListStreamQuery](#usefetcherliststreamquery-hook)
+  - [Basic Query Hooks](#basic-query-hooks)
+    - [useListQuery](#uselistquery-hook)
+    - [usePagedQuery](#usepagedquery-hook)
+    - [useSingleQuery](#usesinglequery-hook)
+    - [useCountQuery](#usecountquery-hook)
+  - [Fetcher Query Hooks](#fetcher-query-hooks)
+    - [useFetcherListQuery](#usefetcherlistquery-hook)
+    - [useFetcherPagedQuery](#usefetcherpagedquery-hook)
+    - [useFetcherSingleQuery](#usefetchersinglequery-hook)
+    - [useFetcherCountQuery](#usefetchercountquery-hook)
+  - [Stream Query Hooks](#stream-query-hooks)
+    - [useListStreamQuery](#useliststreamquery-hook)
+    - [useFetcherListStreamQuery](#usefetcherliststreamquery-hook)
 - [Best Practices](#best-practices)
 - [API Reference](#api-reference)
 - [License](#license)
@@ -711,6 +715,129 @@ Key features:
 - **Error Handling**: Logs warnings for failed subscription attempts
 - **Event Bus Integration**: Works seamlessly with `@ahoo-wang/fetcher-eventbus` TypedEventBus instances
 
+### CoSec Security Hooks
+
+🛡️ **Enterprise Security Integration** - Powerful React hooks for managing authentication state with CoSec tokens, providing seamless integration with enterprise security systems and automatic token lifecycle management.
+
+#### useSecurity Hook
+
+The `useSecurity` hook provides reactive access to authentication state and operations using CoSec tokens. It integrates with TokenStorage to persist tokens and updates state reactively when tokens change.
+
+```typescript jsx
+import { useSecurity } from '@ahoo-wang/fetcher-react/cosec';
+import { tokenStorage } from './tokenStorage';
+import { useNavigate } from 'react-router-dom';
+
+function App() {
+  const navigate = useNavigate();
+
+  const { currentUser, authenticated, signIn, signOut } = useSecurity(tokenStorage, {
+    onSignIn: () => {
+      // Redirect to dashboard after successful login
+      navigate('/dashboard');
+    },
+    onSignOut: () => {
+      // Redirect to login page after logout
+      navigate('/login');
+    }
+  });
+
+  const handleSignIn = async () => {
+    // Direct token
+    await signIn(compositeToken);
+
+    // Or async function
+    await signIn(async () => {
+      const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        body: JSON.stringify({ username, password })
+      });
+      return response.json();
+    });
+  };
+
+  if (!authenticated) {
+    return <button onClick={handleSignIn}>Sign In</button>;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {currentUser.sub}!</p>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+**Key Features:**
+
+- **Reactive Authentication State**: Automatically updates when tokens change
+- **Flexible Sign-in Methods**: Supports both direct tokens and async token providers
+- **Lifecycle Callbacks**: Configurable callbacks for sign-in and sign-out events
+- **Type Safety**: Full TypeScript support with CoSec JWT payload types
+- **Token Persistence**: Integrates with TokenStorage for cross-session persistence
+
+#### SecurityProvider
+
+The `SecurityProvider` component wraps your application to provide authentication context through React context. It internally uses the `useSecurity` hook and makes authentication state available to all child components via the `useSecurityContext` hook.
+
+```tsx
+import { SecurityProvider } from '@ahoo-wang/fetcher-react';
+import { tokenStorage } from './tokenStorage';
+import { useNavigate } from 'react-router-dom';
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <SecurityProvider
+      tokenStorage={tokenStorage}
+      onSignIn={() => navigate('/dashboard')}
+      onSignOut={() => navigate('/login')}
+    >
+      <MyApp />
+    </SecurityProvider>
+  );
+}
+```
+
+**Configuration Options:**
+
+- `tokenStorage`: TokenStorage instance for managing authentication tokens
+- `onSignIn`: Callback function invoked when sign in is successful
+- `onSignOut`: Callback function invoked when sign out occurs
+- `children`: Child components that will have access to security context
+
+#### useSecurityContext Hook
+
+The `useSecurityContext` hook provides access to authentication state and methods within components wrapped by `SecurityProvider`. It offers the same interface as `useSecurity` but through React context.
+
+```tsx
+import { useSecurityContext } from '@ahoo-wang/fetcher-react';
+
+function UserProfile() {
+  const { currentUser, authenticated, signOut } = useSecurityContext();
+
+  if (!authenticated) {
+    return <div>Please sign in</div>;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {currentUser.sub}!</p>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+**Context Benefits:**
+
+- **Prop Drilling Elimination**: Access authentication state without passing props
+- **Component Isolation**: Components can access auth state regardless of component tree depth
+- **Centralized State**: Single source of truth for authentication across the application
+- **Automatic Re-rendering**: Components automatically re-render when authentication state changes
+
 ### Storage Hooks
 
 #### useKeyStorage Hook

package/README.zh-CN.md

@@ -45,20 +45,24 @@
     - [useImmerKeyStorage](#useimmerkeystorage-hook)
   - [事件 Hooks](#事件-hooks)
     - [useEventSubscription](#useeventsubscription-hook)
+  - [CoSec 安全 Hooks](#cosec-安全-hooks)
+    - [useSecurity](#usesecurity-hook)
+    - [SecurityProvider](#securityprovider)
+    - [useSecurityContext](#usesecuritycontext-hook)
   - [Wow 查询 Hooks](#wow-查询-hooks)
-    - [基础查询 Hooks](#基础查询-hooks)
-      - [useListQuery](#uselistquery-hook)
-      - [usePagedQuery](#usepagedquery-hook)
-      - [useSingleQuery](#usesinglequery-hook)
-      - [useCountQuery](#usecountquery-hook)
-    - [获取查询 Hooks](#获取查询-hooks)
-      - [useFetcherListQuery](#usefetcherlistquery-hook)
-      - [useFetcherPagedQuery](#usefetcherpagedquery-hook)
-      - [useFetcherSingleQuery](#usefetchersinglequery-hook)
-      - [useFetcherCountQuery](#usefetchercountquery-hook)
-    - [流查询 Hooks](#流查询-hooks)
-      - [useListStreamQuery](#useliststreamquery-hook)
-      - [useFetcherListStreamQuery](#usefetcherliststreamquery-hook)
+  - [基础查询 Hooks](#基础查询-hooks)
+    - [useListQuery](#uselistquery-hook)
+    - [usePagedQuery](#usepagedquery-hook)
+    - [useSingleQuery](#usesinglequery-hook)
+    - [useCountQuery](#usecountquery-hook)
+  - [获取查询 Hooks](#获取查询-hooks)
+    - [useFetcherListQuery](#usefetcherlistquery-hook)
+    - [useFetcherPagedQuery](#usefetcherpagedquery-hook)
+    - [useFetcherSingleQuery](#usefetchersinglequery-hook)
+    - [useFetcherCountQuery](#usefetchercountquery-hook)
+  - [流查询 Hooks](#流查询-hooks)
+    - [useListStreamQuery](#useliststreamquery-hook)
+    - [useFetcherListStreamQuery](#usefetcherliststreamquery-hook)
 - [最佳实践](#最佳实践)
 - [API 参考](#api-参考)
 - [许可证](#许可证)
@@ -1615,6 +1619,129 @@ function MyComponent() {
 - **错误处理**: 对失败的订阅尝试记录警告
 - **事件总线集成**: 与 `@ahoo-wang/fetcher-eventbus` TypedEventBus 实例无缝配合
 
+### CoSec 安全 Hooks
+
+🛡️ **企业安全集成** - 强大的 React hooks，用于使用 CoSec 令牌管理认证状态，提供与企业安全系统的无缝集成和自动令牌生命周期管理。
+
+#### useSecurity Hook
+
+`useSecurity` hook 使用 CoSec 令牌提供对认证状态和操作的响应式访问。它与 TokenStorage 集成以持久化令牌，并在令牌更改时响应式更新状态。
+
+```typescript jsx
+import { useSecurity } from '@ahoo-wang/fetcher-react/cosec';
+import { tokenStorage } from './tokenStorage';
+import { useNavigate } from 'react-router-dom';
+
+function App() {
+  const navigate = useNavigate();
+
+  const { currentUser, authenticated, signIn, signOut } = useSecurity(tokenStorage, {
+    onSignIn: () => {
+      // 登录成功后重定向到仪表板
+      navigate('/dashboard');
+    },
+    onSignOut: () => {
+      // 登出后重定向到登录页面
+      navigate('/login');
+    }
+  });
+
+  const handleSignIn = async () => {
+    // 直接令牌
+    await signIn(compositeToken);
+
+    // 或异步函数
+    await signIn(async () => {
+      const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        body: JSON.stringify({ username, password })
+      });
+      return response.json();
+    });
+  };
+
+  if (!authenticated) {
+    return <button onClick={handleSignIn}>登录</button>;
+  }
+
+  return (
+    <div>
+      <p>欢迎, {currentUser.sub}!</p>
+      <button onClick={signOut}>登出</button>
+    </div>
+  );
+}
+```
+
+**关键特性:**
+
+- **响应式认证状态**: 当令牌更改时自动更新
+- **灵活的登录方法**: 支持直接令牌和异步令牌提供者
+- **生命周期回调**: 可配置的登录和登出事件回调
+- **类型安全**: 完全支持 TypeScript，具有 CoSec JWT 负载类型
+- **令牌持久化**: 与 TokenStorage 集成以实现跨会话持久化
+
+#### SecurityProvider
+
+`SecurityProvider` 组件包装您的应用程序以通过 React 上下文提供认证上下文。它在内部使用 `useSecurity` hook，并通过 `useSecurityContext` hook 使认证状态可用于所有子组件。
+
+```tsx
+import { SecurityProvider } from '@ahoo-wang/fetcher-react';
+import { tokenStorage } from './tokenStorage';
+import { useNavigate } from 'react-router-dom';
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <SecurityProvider
+      tokenStorage={tokenStorage}
+      onSignIn={() => navigate('/dashboard')}
+      onSignOut={() => navigate('/login')}
+    >
+      <MyApp />
+    </SecurityProvider>
+  );
+}
+```
+
+**配置选项:**
+
+- `tokenStorage`: 用于管理认证令牌的 TokenStorage 实例
+- `onSignIn`: 登录成功时调用的回调函数
+- `onSignOut`: 登出时调用的回调函数
+- `children`: 将有权访问安全上下文的子组件
+
+#### useSecurityContext Hook
+
+`useSecurityContext` hook 在被 `SecurityProvider` 包装的组件中提供对认证状态和方法的访问。它通过 React 上下文提供与 `useSecurity` 相同的接口。
+
+```tsx
+import { useSecurityContext } from '@ahoo-wang/fetcher-react';
+
+function UserProfile() {
+  const { currentUser, authenticated, signOut } = useSecurityContext();
+
+  if (!authenticated) {
+    return <div>请登录</div>;
+  }
+
+  return (
+    <div>
+      <p>欢迎, {currentUser.sub}!</p>
+      <button onClick={signOut}>登出</button>
+    </div>
+  );
+}
+```
+
+**上下文优势:**
+
+- **消除属性钻取**: 无需传递属性即可访问认证状态
+- **组件隔离**: 无论组件树深度如何，组件都可以访问认证状态
+- **集中式状态**: 应用程序中认证的单一真实来源
+- **自动重新渲染**: 当认证状态更改时，组件自动重新渲染
+
 ### 存储 Hooks
 
 #### useKeyStorage

package/dist/cosec/RouteGuard.d.ts

@@ -0,0 +1,49 @@
+import { ReactNode } from 'react';
+/**
+ * Props for the RouteGuard component.
+ */
+export interface RouteGuardProps {
+    /**
+     * The content to render when the user is authenticated.
+     */
+    children: ReactNode;
+    /**
+     * The fallback content to render when the user is not authenticated.
+     * If not provided, nothing will be rendered.
+     */
+    fallback?: ReactNode;
+    /**
+     * Optional redirect function to call when user is not authenticated.
+     * This can be used to programmatically navigate to a login page.
+     */
+    onUnauthorized?: () => void;
+}
+/**
+ * Route guard component that conditionally renders content based on authentication status.
+ *
+ * This component uses the SecurityContext to check if the user is authenticated.
+ * If authenticated, it renders the children. If not authenticated, it renders the fallback
+ * content (if provided) and optionally calls the onUnauthorized callback.
+ *
+ * @param children - The protected content to render when authenticated.
+ * @param fallback - Optional fallback content to render when not authenticated.
+ * @param onUnauthorized - Optional callback to execute when user is not authenticated.
+ * @returns The children if authenticated, fallback if provided, or null otherwise.
+ * @example
+ * ```tsx
+ * import { RouteGuard } from '@ahoo-wang/fetcher-react';
+ *
+ * function ProtectedPage() {
+ *   return (
+ *     <RouteGuard
+ *       fallback={<div>Please log in to access this page.</div>}
+ *       onUnauthorized={() => navigate('/login')}
+ *     >
+ *       <div>Protected content</div>
+ *     </RouteGuard>
+ *   );
+ * }
+ * ```
+ */
+export declare function RouteGuard({ children, fallback, onUnauthorized, }: RouteGuardProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+//# sourceMappingURL=RouteGuard.d.ts.map

package/dist/cosec/RouteGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteGuard.d.ts","sourceRoot":"","sources":["../../src/cosec/RouteGuard.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGlC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,QAAQ,EACR,cAAc,GACf,EAAE,eAAe,2UAcjB"}

package/dist/cosec/SecurityContext.d.ts

@@ -1,55 +1,88 @@
-import { UseSecurityReturn } from './useSecurity';
+import { UseSecurityOptions, UseSecurityReturn } from './useSecurity';
 import { ReactNode } from 'react';
 import { TokenStorage } from '@ahoo-wang/fetcher-cosec';
 /**
- * Type alias for the security context value, which is the same as the return type of useSecurity hook.
- * Provides access to current user information, authentication status, and authentication methods.
+ * Type alias for the security context value, representing the authentication state and methods.
+ * This is equivalent to the return type of the useSecurity hook, providing reactive access to:
+ * - Current authenticated user information (JWT payload)
+ * - Authentication status (boolean flag)
+ * - Sign-in method for authenticating users
+ * - Sign-out method for clearing authentication
+ *
+ * Used internally by the SecurityContext to type the context value.
  */
 export type SecurityContext = UseSecurityReturn;
 /**
  * React context for managing authentication state across the component tree.
- * This context provides a way to share authentication state and methods between components
- * without prop drilling. It should be used with SecurityProvider to wrap the application.
+ * This context enables sharing of authentication state and methods between components
+ * without prop drilling. Components can access authentication data and methods through
+ * the useSecurityContext hook when wrapped by the SecurityProvider.
+ *
+ * The context value is undefined by default, requiring components to be wrapped by
+ * SecurityProvider to access authentication functionality.
  */
 export declare const SecurityContext: import('react').Context<UseSecurityReturn | undefined>;
 /**
- * Props for the SecurityProvider component.
+ * Configuration options for the SecurityProvider component.
+ * Extends UseSecurityOptions to include provider-specific settings like token storage and children.
  */
-export interface SecurityContextOptions {
+export interface SecurityContextOptions extends UseSecurityOptions {
     /**
      * The token storage instance used to manage authentication tokens.
-     * This should be a valid TokenStorage implementation that handles token persistence and retrieval.
+     * This should be a valid TokenStorage implementation that handles token persistence,
+     * retrieval, and lifecycle management across different storage backends (localStorage,
+     * sessionStorage, memory, etc.).
      */
     tokenStorage: TokenStorage;
     /**
      * The child components that will have access to the security context.
+     * These components can use the useSecurityContext hook to access authentication state and methods.
      */
     children: ReactNode;
 }
 /**
  * Provider component that supplies authentication state and methods to its child components.
  * This component wraps the application or a portion of it to provide access to authentication
- * functionality through the useSecurityContext hook.
+ * functionality through the useSecurityContext hook. It internally uses the useSecurity hook
+ * to manage authentication state and makes it available via React context.
  *
  * @param tokenStorage - The token storage instance for managing authentication tokens.
+ *                      This should be a valid TokenStorage implementation that handles
+ *                      token persistence, retrieval, and lifecycle management across different
+ *                      storage backends (localStorage, sessionStorage, memory, etc.).
  * @param children - The child components that will have access to the security context.
+ *                  These components can use the useSecurityContext hook to access authentication
+ *                  state and methods without prop drilling.
+ * @param useSecurityOptions - Optional configuration object containing lifecycle callbacks
+ *                            for sign-in and sign-out events. Extends UseSecurityOptions interface.
+ * @param useSecurityOptions.onSignIn - Callback function invoked when sign in is successful.
+ * @param useSecurityOptions.onSignOut - Callback function invoked when sign out occurs.
  * @returns A React element that provides the security context to its children.
- * @throws {Error} May throw errors if tokenStorage operations fail during initialization.
+ *          The context value includes currentUser, authenticated status, signIn, and signOut methods.
+ * @throws {Error} May throw errors if tokenStorage operations fail during initialization,
+ *                 such as invalid tokens or storage access issues (implementation dependent).
  * @example
  * ```tsx
- * import { SecurityProvider } from '@ahoo-wang/fetcher-react/cosec';
+ * import { SecurityProvider } from '@ahoo-wang/fetcher-react';
  * import { tokenStorage } from './tokenStorage';
+ * import { useNavigate } from 'react-router-dom';
  *
  * function App() {
+ *   const navigate = useNavigate();
+ *
  *   return (
- *     <SecurityProvider tokenStorage={tokenStorage}>
+ *     <SecurityProvider
+ *       tokenStorage={tokenStorage}
+ *       onSignIn={() => navigate('/dashboard')}
+ *       onSignOut={() => navigate('/login')}
+ *     >
  *       <MyApp />
  *     </SecurityProvider>
  *   );
  * }
  * ```
  */
-export declare function SecurityProvider({ tokenStorage, children, }: SecurityContextOptions): import("react/jsx-runtime").JSX.Element;
+export declare function SecurityProvider({ tokenStorage, children, ...useSecurityOptions }: SecurityContextOptions): import("react/jsx-runtime").JSX.Element;
 /**
  * Hook to access the security context within components wrapped by SecurityProvider.
  * This hook provides reactive access to authentication state and methods throughout the component tree.
@@ -58,7 +91,7 @@ export declare function SecurityProvider({ tokenStorage, children, }: SecurityCo
  * @throws {Error} Throws an error if used outside of a SecurityProvider component.
  * @example
  * ```tsx
- * import { useSecurityContext } from '@ahoo-wang/fetcher-react/cosec';
+ * import { useSecurityContext } from '@ahoo-wang/fetcher-react';
  *
  * function UserProfile() {
  *   const { currentUser, authenticated, signOut } = useSecurityContext();

package/dist/cosec/SecurityContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SecurityContext.d.ts","sourceRoot":"","sources":["../../src/cosec/SecurityContext.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAe,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAiB,SAAS,EAAc,MAAM,OAAO,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,eAAe,wDAE3B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,YAAY,EACZ,QAAQ,GACT,EAAE,sBAAsB,2CAOxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD"}
+{"version":3,"file":"SecurityContext.d.ts","sourceRoot":"","sources":["../../src/cosec/SecurityContext.tsx"],"names":[],"mappings":"AAaA,OAAO,EAEL,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAiB,SAAS,EAAc,MAAM,OAAO,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,wDAE3B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE;;;;;OAKG;IACH,YAAY,EAAE,YAAY,CAAC;IAE3B;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,YAAY,EACZ,QAAQ,EACR,GAAG,kBAAkB,EACtB,EAAE,sBAAsB,2CAOxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAQpD"}

package/dist/cosec/index.d.ts

@@ -1,3 +1,4 @@
 export * from './SecurityContext';
 export * from './useSecurity';
+export * from './RouteGuard';
 //# sourceMappingURL=index.d.ts.map

package/dist/cosec/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cosec/index.ts"],"names":[],"mappings":"AAaA,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cosec/index.ts"],"names":[],"mappings":"AAaA,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/cosec/useSecurity.d.ts

@@ -1,11 +1,31 @@
 import { TokenStorage, CompositeToken, CoSecJwtPayload } from '@ahoo-wang/fetcher-cosec';
+/**
+ * Type representing a composite token provider.
+ * Can be either a direct composite token or a function that returns a promise of a composite token.
+ */
+type CompositeTokenProvider = CompositeToken | (() => Promise<CompositeToken>);
 export declare const ANONYMOUS_USER: CoSecJwtPayload;
+/**
+ * Options for configuring the useSecurity hook.
+ */
+export interface UseSecurityOptions {
+    /**
+     * Callback function invoked when sign in is successful.
+     * This is called after the token has been successfully stored.
+     */
+    onSignIn?: () => void;
+    /**
+     * Callback function invoked when sign out occurs.
+     * This is called after the token has been removed.
+     */
+    onSignOut?: () => void;
+}
 /**
  * Return type for the useSecurity hook.
  */
 export interface UseSecurityReturn {
     /**
-     * The current authenticated user's JWT payload, or null if not authenticated.
+     * The current authenticated user's JWT payload, or ANONYMOUS_USER if not authenticated.
      * Contains user information extracted from the access token.
      */
     currentUser: CoSecJwtPayload;
@@ -15,10 +35,12 @@ export interface UseSecurityReturn {
      */
     authenticated: boolean;
     /**
-     * Function to sign in with a composite token.
-     * @param compositeToken - The composite token containing access and refresh tokens.
+     * Function to sign in with a composite token or a function that returns a promise of composite token.
+     * @param compositeTokenProvider - Either a composite token containing access and refresh tokens,
+     *                                or a function that returns a promise resolving to a composite token.
+     * @returns A promise that resolves when the sign-in operation is complete.
      */
-    signIn: (compositeToken: CompositeToken) => void;
+    signIn: (compositeTokenProvider: CompositeTokenProvider) => Promise<void>;
     /**
      * Function to sign out the current user.
      */
@@ -34,6 +56,9 @@ export interface UseSecurityReturn {
  * @param tokenStorage - The token storage instance used to manage authentication tokens.
  *                      This should be a valid TokenStorage implementation that handles
  *                      token persistence and retrieval.
+ * @param options - Optional configuration object containing lifecycle callbacks.
+ * @param options.onSignIn - Callback function invoked when sign in is successful.
+ * @param options.onSignOut - Callback function invoked when sign out occurs.
  * @returns An object containing:
  *          - currentUser: The current authenticated user's JWT payload, or null if not authenticated.
  *          - authenticated: Boolean indicating whether the user is currently authenticated.
@@ -45,12 +70,38 @@ export interface UseSecurityReturn {
  * ```typescript
  * import { useSecurity } from '@ahoo-wang/fetcher-react/cosec';
  * import { tokenStorage } from './tokenStorage';
+ * import { useNavigate } from 'react-router-dom';
  *
  * function App() {
- *   const { currentUser, authenticated, signIn, signOut } = useSecurity(tokenStorage);
+ *   const navigate = useNavigate();
+ *
+ *   const { currentUser, authenticated, signIn, signOut } = useSecurity(tokenStorage, {
+ *     onSignIn: () => {
+ *       // Redirect to dashboard after successful login
+ *       navigate('/dashboard');
+ *     },
+ *     onSignOut: () => {
+ *       // Redirect to login page after logout
+ *       navigate('/login');
+ *     }
+ *   });
+ *
+ *   const handleSignIn = async () => {
+ *     // Direct token
+ *     await signIn(compositeToken);
+ *
+ *     // Or async function
+ *     await signIn(async () => {
+ *       const response = await fetch('/api/auth/login', {
+ *         method: 'POST',
+ *         body: JSON.stringify({ username, password })
+ *       });
+ *       return response.json();
+ *     });
+ *   };
  *
  *   if (!authenticated) {
- *     return <button onClick={() => signIn(compositeToken)}>Sign In</button>;
+ *     return <button onClick={handleSignIn}>Sign In</button>;
  *   }
  *
  *   return (
@@ -62,5 +113,6 @@ export interface UseSecurityReturn {
  * }
  * ```
  */
-export declare function useSecurity(tokenStorage: TokenStorage): UseSecurityReturn;
+export declare function useSecurity(tokenStorage: TokenStorage, options?: UseSecurityOptions): UseSecurityReturn;
+export {};
 //# sourceMappingURL=useSecurity.d.ts.map

package/dist/cosec/useSecurity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSecurity.d.ts","sourceRoot":"","sources":["../../src/cosec/useSecurity.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,eAAO,MAAM,cAAc,EAAE,eAE5B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,eAAe,CAAC;IAE7B;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,MAAM,EAAE,CAAC,cAAc,EAAE,cAAc,KAAK,IAAI,CAAC;IAEjD;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,iBAAiB,CAezE"}
+{"version":3,"file":"useSecurity.d.ts","sourceRoot":"","sources":["../../src/cosec/useSecurity.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAGlC;;;GAGG;AACH,KAAK,sBAAsB,GAAG,cAAc,GAAG,CAAC,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;AAE/E,eAAO,MAAM,cAAc,EAAE,eAK5B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,eAAe,CAAC;IAE7B;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,sBAAsB,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CA0BnB"}