@swr-login/react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,250 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SWRLoginConfig, AuthResponse, User, PluginManager, TokenManager, AuthEventEmitter, AuthStateMachine, BroadcastSync } from '@swr-login/core';
+import React from 'react';
+
+interface SWRLoginProviderProps {
+    /** Authentication configuration */
+    config: SWRLoginConfig;
+    children: React.ReactNode;
+}
+/**
+ * SWRLoginProvider initializes the auth system and provides context to all child hooks.
+ *
+ * @example
+ * ```tsx
+ * import { SWRLoginProvider } from '@swr-login/react';
+ * import { JWTAdapter } from '@swr-login/adapter-jwt';
+ * import { PasswordPlugin } from '@swr-login/plugin-password';
+ *
+ * function App() {
+ *   return (
+ *     <SWRLoginProvider
+ *       config={{
+ *         adapter: JWTAdapter(),
+ *         plugins: [PasswordPlugin({ loginUrl: '/api/login' })],
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SWRLoginProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SWRLoginProvider({ config, children }: SWRLoginProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseLoginOptions {
+    /** Plugin name to use for login */
+    pluginName?: string;
+}
+interface UseLoginReturn<TCredentials = unknown> {
+    /**
+     * Trigger login with specified credentials.
+     * If pluginName was not provided in options, it must be passed as first argument.
+     */
+    login: (credentialsOrPluginName: TCredentials | string, credentials?: TCredentials) => Promise<AuthResponse>;
+    /** Whether a login request is in progress */
+    isLoading: boolean;
+    /** Last login error, if any */
+    error: Error | null;
+    /** Reset error state */
+    reset: () => void;
+}
+/**
+ * Hook to trigger login flow via a registered plugin.
+ *
+ * @param pluginName - Optional default plugin name
+ *
+ * @example
+ * ```tsx
+ * // With default plugin
+ * const { login, isLoading, error } = useLogin('password');
+ * await login({ username: 'alice', password: 'secret' });
+ *
+ * // Without default plugin (specify at call time)
+ * const { login } = useLogin();
+ * await login('oauth-google', { redirect: false });
+ * ```
+ */
+declare function useLogin<TCredentials = unknown>(pluginName?: string): UseLoginReturn<TCredentials>;
+
+declare const AUTH_KEY = "__swr_login_user__";
+interface UseUserReturn<T extends User = User> {
+    /** Current authenticated user, or null if not logged in */
+    user: T | null;
+    /** Whether user data is being fetched */
+    isLoading: boolean;
+    /** Whether user is authenticated */
+    isAuthenticated: boolean;
+    /** Error from fetching user data */
+    error: Error | undefined;
+    /**
+     * Manually update cached user data.
+     * Call with `null` to clear, or with a user object to update.
+     */
+    mutate: (data?: T | null) => Promise<void>;
+}
+/**
+ * Hook to access current user data via SWR cache.
+ *
+ * Uses SWR's stale-while-revalidate strategy:
+ * - Immediately returns cached user data
+ * - Revalidates in the background using the configured fetchUser function
+ * - Automatically syncs across all components using this hook
+ *
+ * @example
+ * ```tsx
+ * const { user, isLoading, isAuthenticated } = useUser<MyUser>();
+ *
+ * if (isLoading) return <Spinner />;
+ * if (!isAuthenticated) return <LoginPage />;
+ * return <Dashboard user={user} />;
+ * ```
+ */
+declare function useUser<T extends User = User>(): UseUserReturn<T>;
+
+interface UseLogoutOptions {
+    /** Specific plugin to call logout on */
+    pluginName?: string;
+    /** Whether to broadcast logout to other tabs (default: true) */
+    broadcast?: boolean;
+}
+interface UseLogoutReturn {
+    /** Execute logout */
+    logout: (options?: UseLogoutOptions) => Promise<void>;
+    /** Whether logout is in progress */
+    isLoading: boolean;
+}
+/**
+ * Hook to perform secure logout with cross-tab sync.
+ *
+ * Logout flow:
+ * 1. Call plugin logout (if applicable)
+ * 2. Clear stored tokens
+ * 3. Clear SWR cache (mutate user to null)
+ * 4. Broadcast logout to other tabs
+ * 5. Transition state to 'unauthenticated'
+ *
+ * @example
+ * ```tsx
+ * const { logout, isLoading } = useLogout();
+ *
+ * <button onClick={() => logout()} disabled={isLoading}>
+ *   Sign Out
+ * </button>
+ * ```
+ */
+declare function useLogout(): UseLogoutReturn;
+
+interface SessionInfo {
+    /** Current access token */
+    accessToken: string | null;
+    /** Current refresh token */
+    refreshToken: string | null;
+    /** Token expiration timestamp (ms since epoch) */
+    expiresAt: number | null;
+    /** Whether the access token has expired */
+    isExpired: boolean;
+    /** Whether tokens exist (regardless of expiry) */
+    hasTokens: boolean;
+}
+/**
+ * Hook to access raw session/token information.
+ *
+ * Useful for:
+ * - Adding Authorization headers to custom requests
+ * - Checking token expiry status
+ * - Debugging session state
+ *
+ * @example
+ * ```tsx
+ * const { accessToken, isExpired } = useSession();
+ *
+ * const fetchData = () => fetch('/api/data', {
+ *   headers: { Authorization: `Bearer ${accessToken}` },
+ * });
+ * ```
+ */
+declare function useSession(): SessionInfo;
+
+interface UsePermissionReturn {
+    /** Check if user has a specific permission */
+    hasPermission: (permission: string) => boolean;
+    /** Check if user has a specific role */
+    hasRole: (role: string) => boolean;
+    /** Check if user has all specified permissions */
+    hasAllPermissions: (permissions: string[]) => boolean;
+    /** Check if user has any of the specified permissions */
+    hasAnyPermission: (permissions: string[]) => boolean;
+    /** Check if user has all specified roles */
+    hasAllRoles: (roles: string[]) => boolean;
+    /** Check if user has any of the specified roles */
+    hasAnyRole: (roles: string[]) => boolean;
+}
+/**
+ * Hook for checking user permissions and roles.
+ *
+ * Reads from the `permissions` and `roles` arrays on the User object.
+ *
+ * @example
+ * ```tsx
+ * const { hasPermission, hasRole } = usePermission();
+ *
+ * if (hasPermission('admin:write')) {
+ *   // Show admin controls
+ * }
+ *
+ * if (hasRole('editor')) {
+ *   // Show editor tools
+ * }
+ * ```
+ */
+declare function usePermission(): UsePermissionReturn;
+
+interface AuthGuardProps {
+    children: React.ReactNode;
+    /** Required permissions (checked against user.permissions) */
+    permissions?: string[];
+    /** Required roles (checked against user.roles) */
+    roles?: string[];
+    /** If true, ALL permissions/roles must match. If false, ANY match suffices. (default: false) */
+    requireAll?: boolean;
+    /** Component to render when user is not authenticated or lacks permissions */
+    fallback?: React.ReactNode;
+    /** Component to render while checking auth status */
+    loadingComponent?: React.ReactNode;
+}
+/**
+ * Declarative auth guard component.
+ * Protects child content based on authentication state and permissions/roles.
+ *
+ * @example
+ * ```tsx
+ * <AuthGuard
+ *   permissions={['admin', 'editor']}
+ *   requireAll={false}
+ *   fallback={<Navigate to="/login" />}
+ *   loadingComponent={<Skeleton />}
+ * >
+ *   <AdminPanel />
+ * </AuthGuard>
+ * ```
+ */
+declare function AuthGuard({ children, permissions, roles, requireAll, fallback, loadingComponent, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
+
+/** Internal context value passed through SWRLoginProvider */
+interface AuthContextValue {
+    pluginManager: PluginManager;
+    tokenManager: TokenManager;
+    emitter: AuthEventEmitter;
+    stateMachine: AuthStateMachine;
+    broadcastSync: BroadcastSync | null;
+    config: SWRLoginConfig;
+}
+/**
+ * Internal hook to access auth context.
+ * Must be used within SWRLoginProvider.
+ * @throws Error if used outside of SWRLoginProvider
+ */
+declare function useAuthContext(): AuthContextValue;
+
+export { AUTH_KEY, type AuthContextValue, AuthGuard, type AuthGuardProps, SWRLoginProvider, type SWRLoginProviderProps, type SessionInfo, type UseLoginOptions, type UseLoginReturn, type UseLogoutOptions, type UseLogoutReturn, type UsePermissionReturn, type UseUserReturn, useAuthContext, useLogin, useLogout, usePermission, useSession, useUser };

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { SWRLoginConfig, AuthResponse, User, PluginManager, TokenManager, AuthEventEmitter, AuthStateMachine, BroadcastSync } from '@swr-login/core';
+import React from 'react';
+
+interface SWRLoginProviderProps {
+    /** Authentication configuration */
+    config: SWRLoginConfig;
+    children: React.ReactNode;
+}
+/**
+ * SWRLoginProvider initializes the auth system and provides context to all child hooks.
+ *
+ * @example
+ * ```tsx
+ * import { SWRLoginProvider } from '@swr-login/react';
+ * import { JWTAdapter } from '@swr-login/adapter-jwt';
+ * import { PasswordPlugin } from '@swr-login/plugin-password';
+ *
+ * function App() {
+ *   return (
+ *     <SWRLoginProvider
+ *       config={{
+ *         adapter: JWTAdapter(),
+ *         plugins: [PasswordPlugin({ loginUrl: '/api/login' })],
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SWRLoginProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function SWRLoginProvider({ config, children }: SWRLoginProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseLoginOptions {
+    /** Plugin name to use for login */
+    pluginName?: string;
+}
+interface UseLoginReturn<TCredentials = unknown> {
+    /**
+     * Trigger login with specified credentials.
+     * If pluginName was not provided in options, it must be passed as first argument.
+     */
+    login: (credentialsOrPluginName: TCredentials | string, credentials?: TCredentials) => Promise<AuthResponse>;
+    /** Whether a login request is in progress */
+    isLoading: boolean;
+    /** Last login error, if any */
+    error: Error | null;
+    /** Reset error state */
+    reset: () => void;
+}
+/**
+ * Hook to trigger login flow via a registered plugin.
+ *
+ * @param pluginName - Optional default plugin name
+ *
+ * @example
+ * ```tsx
+ * // With default plugin
+ * const { login, isLoading, error } = useLogin('password');
+ * await login({ username: 'alice', password: 'secret' });
+ *
+ * // Without default plugin (specify at call time)
+ * const { login } = useLogin();
+ * await login('oauth-google', { redirect: false });
+ * ```
+ */
+declare function useLogin<TCredentials = unknown>(pluginName?: string): UseLoginReturn<TCredentials>;
+
+declare const AUTH_KEY = "__swr_login_user__";
+interface UseUserReturn<T extends User = User> {
+    /** Current authenticated user, or null if not logged in */
+    user: T | null;
+    /** Whether user data is being fetched */
+    isLoading: boolean;
+    /** Whether user is authenticated */
+    isAuthenticated: boolean;
+    /** Error from fetching user data */
+    error: Error | undefined;
+    /**
+     * Manually update cached user data.
+     * Call with `null` to clear, or with a user object to update.
+     */
+    mutate: (data?: T | null) => Promise<void>;
+}
+/**
+ * Hook to access current user data via SWR cache.
+ *
+ * Uses SWR's stale-while-revalidate strategy:
+ * - Immediately returns cached user data
+ * - Revalidates in the background using the configured fetchUser function
+ * - Automatically syncs across all components using this hook
+ *
+ * @example
+ * ```tsx
+ * const { user, isLoading, isAuthenticated } = useUser<MyUser>();
+ *
+ * if (isLoading) return <Spinner />;
+ * if (!isAuthenticated) return <LoginPage />;
+ * return <Dashboard user={user} />;
+ * ```
+ */
+declare function useUser<T extends User = User>(): UseUserReturn<T>;
+
+interface UseLogoutOptions {
+    /** Specific plugin to call logout on */
+    pluginName?: string;
+    /** Whether to broadcast logout to other tabs (default: true) */
+    broadcast?: boolean;
+}
+interface UseLogoutReturn {
+    /** Execute logout */
+    logout: (options?: UseLogoutOptions) => Promise<void>;
+    /** Whether logout is in progress */
+    isLoading: boolean;
+}
+/**
+ * Hook to perform secure logout with cross-tab sync.
+ *
+ * Logout flow:
+ * 1. Call plugin logout (if applicable)
+ * 2. Clear stored tokens
+ * 3. Clear SWR cache (mutate user to null)
+ * 4. Broadcast logout to other tabs
+ * 5. Transition state to 'unauthenticated'
+ *
+ * @example
+ * ```tsx
+ * const { logout, isLoading } = useLogout();
+ *
+ * <button onClick={() => logout()} disabled={isLoading}>
+ *   Sign Out
+ * </button>
+ * ```
+ */
+declare function useLogout(): UseLogoutReturn;
+
+interface SessionInfo {
+    /** Current access token */
+    accessToken: string | null;
+    /** Current refresh token */
+    refreshToken: string | null;
+    /** Token expiration timestamp (ms since epoch) */
+    expiresAt: number | null;
+    /** Whether the access token has expired */
+    isExpired: boolean;
+    /** Whether tokens exist (regardless of expiry) */
+    hasTokens: boolean;
+}
+/**
+ * Hook to access raw session/token information.
+ *
+ * Useful for:
+ * - Adding Authorization headers to custom requests
+ * - Checking token expiry status
+ * - Debugging session state
+ *
+ * @example
+ * ```tsx
+ * const { accessToken, isExpired } = useSession();
+ *
+ * const fetchData = () => fetch('/api/data', {
+ *   headers: { Authorization: `Bearer ${accessToken}` },
+ * });
+ * ```
+ */
+declare function useSession(): SessionInfo;
+
+interface UsePermissionReturn {
+    /** Check if user has a specific permission */
+    hasPermission: (permission: string) => boolean;
+    /** Check if user has a specific role */
+    hasRole: (role: string) => boolean;
+    /** Check if user has all specified permissions */
+    hasAllPermissions: (permissions: string[]) => boolean;
+    /** Check if user has any of the specified permissions */
+    hasAnyPermission: (permissions: string[]) => boolean;
+    /** Check if user has all specified roles */
+    hasAllRoles: (roles: string[]) => boolean;
+    /** Check if user has any of the specified roles */
+    hasAnyRole: (roles: string[]) => boolean;
+}
+/**
+ * Hook for checking user permissions and roles.
+ *
+ * Reads from the `permissions` and `roles` arrays on the User object.
+ *
+ * @example
+ * ```tsx
+ * const { hasPermission, hasRole } = usePermission();
+ *
+ * if (hasPermission('admin:write')) {
+ *   // Show admin controls
+ * }
+ *
+ * if (hasRole('editor')) {
+ *   // Show editor tools
+ * }
+ * ```
+ */
+declare function usePermission(): UsePermissionReturn;
+
+interface AuthGuardProps {
+    children: React.ReactNode;
+    /** Required permissions (checked against user.permissions) */
+    permissions?: string[];
+    /** Required roles (checked against user.roles) */
+    roles?: string[];
+    /** If true, ALL permissions/roles must match. If false, ANY match suffices. (default: false) */
+    requireAll?: boolean;
+    /** Component to render when user is not authenticated or lacks permissions */
+    fallback?: React.ReactNode;
+    /** Component to render while checking auth status */
+    loadingComponent?: React.ReactNode;
+}
+/**
+ * Declarative auth guard component.
+ * Protects child content based on authentication state and permissions/roles.
+ *
+ * @example
+ * ```tsx
+ * <AuthGuard
+ *   permissions={['admin', 'editor']}
+ *   requireAll={false}
+ *   fallback={<Navigate to="/login" />}
+ *   loadingComponent={<Skeleton />}
+ * >
+ *   <AdminPanel />
+ * </AuthGuard>
+ * ```
+ */
+declare function AuthGuard({ children, permissions, roles, requireAll, fallback, loadingComponent, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
+
+/** Internal context value passed through SWRLoginProvider */
+interface AuthContextValue {
+    pluginManager: PluginManager;
+    tokenManager: TokenManager;
+    emitter: AuthEventEmitter;
+    stateMachine: AuthStateMachine;
+    broadcastSync: BroadcastSync | null;
+    config: SWRLoginConfig;
+}
+/**
+ * Internal hook to access auth context.
+ * Must be used within SWRLoginProvider.
+ * @throws Error if used outside of SWRLoginProvider
+ */
+declare function useAuthContext(): AuthContextValue;
+
+export { AUTH_KEY, type AuthContextValue, AuthGuard, type AuthGuardProps, SWRLoginProvider, type SWRLoginProviderProps, type SessionInfo, type UseLoginOptions, type UseLoginReturn, type UseLogoutOptions, type UseLogoutReturn, type UsePermissionReturn, type UseUserReturn, useAuthContext, useLogin, useLogout, usePermission, useSession, useUser };