exguard-client 1.0.0

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,609 @@
+# ExGuard Client Implementation Guide
+
+Complete step-by-step guide to implement @empowerx/exguard-client in your React application.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Project Setup](#project-setup)
+- [Configuration](#configuration)
+- [Basic Usage](#basic-usage)
+- [Advanced Features](#advanced-features)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+Before installing ExGuard client, ensure you have:
+
+1. **Node.js** >= 18.0.0
+2. **React** >= 18.0.0 or >= 19.0.0
+3. **TypeScript** (recommended for type safety)
+4. **ExGuard Backend API** running and accessible
+
+### Required Peer Dependencies
+
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0",
+  "react-router": "^7.0.0",
+  "axios": "^1.0.0",
+  "socket.io-client": "^4.0.0"
+}
+```
+
+## Installation
+
+### Step 1: Install the Package
+
+Using pnpm (recommended):
+```bash
+pnpm add @empowerx/exguard-client
+```
+
+Using npm:
+```bash
+npm install @empowerx/exguard-client
+```
+
+Using yarn:
+```bash
+yarn add @empowerx/exguard-client
+```
+
+### Step 2: Install Peer Dependencies
+
+If not already installed:
+
+```bash
+# Using pnpm
+pnpm add react react-dom react-router axios socket.io-client
+
+# Using npm
+npm install react react-dom react-router axios socket.io-client
+```
+
+## Project Setup
+
+### Option 1: Using the Setup Script (Recommended)
+
+The package includes a setup script that creates a clean module structure in your project:
+
+```bash
+npx exguard-setup
+# or
+pnpm exguard-setup
+```
+
+This creates:
+```
+src/features/exguard/
+├── index.ts              # Re-exports from @empowerx/exguard-client
+├── README.md            # Module-specific documentation
+└── config/
+    └── exguard.config.ts # Optional configuration file
+```
+
+**Benefits:**
+- Clean separation between package and application code
+- Easy to customize or extend ExGuard functionality
+- Consistent import paths across your application
+- Type-safe re-exports
+
+### Option 2: Direct Package Imports
+
+You can also import directly from the package without the setup script:
+
+```tsx
+import { PermissionGuard, useUserAccess } from '@empowerx/exguard-client';
+```
+
+## Configuration
+
+### Step 1: Configure ExGuard API URL
+
+In your application entry point (`main.tsx` or `App.tsx`):
+
+```tsx
+// src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ExGuardRealtimeProvider, setExGuardConfig } from '@/features/exguard';
+import App from './App';
+
+// Configure ExGuard API URL
+setExGuardConfig({
+  apiUrl: import.meta.env.VITE_GUARD_APP_URL as string,
+});
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ExGuardRealtimeProvider>
+      <App />
+    </ExGuardRealtimeProvider>
+  </StrictMode>
+);
+```
+
+### Step 2: Environment Variables
+
+Create or update your `.env` file:
+
+**For Vite:**
+```env
+VITE_GUARD_APP_URL=https://your-exguard-api.com
+```
+
+**For Next.js:**
+```env
+NEXT_PUBLIC_GUARD_APP_URL=https://your-exguard-api.com
+```
+
+**For Create React App:**
+```env
+REACT_APP_GUARD_APP_URL=https://your-exguard-api.com
+```
+
+### Step 3: Wrap Your Application
+
+Ensure your app is wrapped with `ExGuardRealtimeProvider`:
+
+```tsx
+// src/App.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { RouterProvider } from 'react-router';
+import { ExGuardRealtimeProvider, setExGuardConfig } from '@/features/exguard';
+import router from './router';
+
+const queryClient = new QueryClient();
+
+// Configure before rendering
+setExGuardConfig({
+  apiUrl: import.meta.env.VITE_GUARD_APP_URL as string,
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ExGuardRealtimeProvider>
+        <RouterProvider router={router} />
+      </ExGuardRealtimeProvider>
+    </QueryClientProvider>
+  );
+}
+
+export default App;
+```
+
+## Basic Usage
+
+### 1. Route Protection with PermissionGuard
+
+Protect entire routes or components based on module access:
+
+```tsx
+// src/features/profiles/pages/ProfilesPage.tsx
+import { PermissionGuard } from '@/features/exguard';
+import { ProfilesList } from '../components/ProfilesList';
+
+export function ProfilesPage() {
+  return (
+    <PermissionGuard
+      module="EXID"
+      fallbackPath="/unauthorized"
+    >
+      <ProfilesList />
+    </PermissionGuard>
+  );
+}
+```
+
+### 2. Permission-Based Feature Access
+
+Protect specific features or actions:
+
+```tsx
+// src/features/profiles/pages/ProfileDetailPage.tsx
+import { PermissionGuard } from '@/features/exguard';
+
+export function ProfileDetailPage() {
+  return (
+    <div>
+      <h1>Profile Details</h1>
+      
+      {/* Only users with profile:update permission can see this */}
+      <PermissionGuard
+        module="EXID"
+        permission="profile:update"
+        requirePermission={true}
+      >
+        <button>Edit Profile</button>
+      </PermissionGuard>
+      
+      {/* Only users with profile:delete permission can see this */}
+      <PermissionGuard
+        module="EXID"
+        permission="profile:delete"
+        requirePermission={true}
+      >
+        <button>Delete Profile</button>
+      </PermissionGuard>
+    </div>
+  );
+}
+```
+
+### 3. Using useUserAccess Hook
+
+Access user permissions programmatically:
+
+```tsx
+// src/features/profiles/components/ProfileActions.tsx
+import { useUserAccess } from '@/features/exguard';
+
+export function ProfileActions({ profileId }: { profileId: string }) {
+  const { hasModuleAccess, hasPermission, isLoading } = useUserAccess();
+
+  if (isLoading) {
+    return <div>Loading permissions...</div>;
+  }
+
+  // Check module access
+  if (!hasModuleAccess('EXID')) {
+    return <div>Access denied to EXID module</div>;
+  }
+
+  return (
+    <div className="flex gap-2">
+      {/* Show edit button only if user has permission */}
+      {hasPermission('EXID', 'profile:update') && (
+        <button onClick={() => handleEdit(profileId)}>
+          Edit
+        </button>
+      )}
+      
+      {/* Show delete button only if user has permission */}
+      {hasPermission('EXID', 'profile:delete') && (
+        <button onClick={() => handleDelete(profileId)}>
+          Delete
+        </button>
+      )}
+      
+      {/* View is always available if user has module access */}
+      <button onClick={() => handleView(profileId)}>
+        View
+      </button>
+    </div>
+  );
+}
+```
+
+### 4. API Functions
+
+Verify tokens and get user access data:
+
+```tsx
+// src/features/auth/hooks/useAuth.ts
+import { verifyToken, getUserAccess } from '@/features/exguard';
+
+export function useAuth() {
+  const checkAuthentication = async () => {
+    try {
+      const result = await verifyToken();
+      
+      if (!result.isValid) {
+        // Token is invalid, redirect to login
+        window.location.href = '/login';
+        return;
+      }
+      
+      // Get user's access data
+      const userAccess = await getUserAccess();
+      console.log('User modules:', userAccess.modules);
+      console.log('User roles:', userAccess.roles);
+      
+      return userAccess;
+    } catch (error) {
+      console.error('Authentication failed:', error);
+      throw error;
+    }
+  };
+
+  return { checkAuthentication };
+}
+```
+
+## Advanced Features
+
+### 1. Realtime RBAC Updates
+
+Listen to real-time permission changes:
+
+```tsx
+// src/features/admin/pages/UsersPage.tsx
+import { useEffect, useState } from 'react';
+import { 
+  useExGuardRealtime, 
+  useExGuardRealtimeSubscription,
+  EXGUARD_RBAC_EVENTS 
+} from '@/features/exguard';
+
+export function UsersPage() {
+  const [users, setUsers] = useState([]);
+  const { isConnected } = useExGuardRealtime();
+
+  // Subscribe to user RBAC updates
+  useExGuardRealtimeSubscription(
+    EXGUARD_RBAC_EVENTS.USER_ROLES_UPDATED,
+    (payload) => {
+      console.log('User roles updated:', payload);
+      // Refresh user list or update specific user
+      refreshUsers();
+    }
+  );
+
+  // Subscribe to permission changes
+  useExGuardRealtimeSubscription(
+    EXGUARD_RBAC_EVENTS.RBAC_PERMISSIONS_UPDATED,
+    (payload) => {
+      console.log('Permissions updated:', payload);
+      // Refresh current user's access data
+      window.location.reload(); // or use a more elegant refresh
+    }
+  );
+
+  return (
+    <div>
+      <div>WebSocket: {isConnected ? '✅ Connected' : '❌ Disconnected'}</div>
+      {/* User list */}
+    </div>
+  );
+}
+```
+
+### 2. Custom RBAC Refresh Logic
+
+Register callbacks for when RBAC data needs to be refreshed:
+
+```tsx
+// src/providers/AppProvider.tsx
+import { useEffect } from 'react';
+import { useExGuardRealtime, getUserAccess } from '@/features/exguard';
+import { useQueryClient } from '@tanstack/react-query';
+
+export function AppProvider({ children }) {
+  const { registerRbacRefreshCallback } = useExGuardRealtime();
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    // Register callback to refresh user data when RBAC changes
+    const unregister = registerRbacRefreshCallback(async () => {
+      console.log('RBAC data changed, refreshing...');
+      
+      // Refetch user access data
+      const newAccess = await getUserAccess();
+      
+      // Update React Query cache
+      queryClient.setQueryData(['userAccess'], newAccess);
+      
+      // Invalidate related queries
+      queryClient.invalidateQueries({ queryKey: ['permissions'] });
+      queryClient.invalidateQueries({ queryKey: ['modules'] });
+    });
+
+    return unregister; // Cleanup on unmount
+  }, [registerRbacRefreshCallback, queryClient]);
+
+  return <>{children}</>;
+}
+```
+
+### 3. Token Management
+
+Access and manage authentication tokens:
+
+```tsx
+// src/utils/auth.ts
+import { EXGUARD_STORAGE_KEYS } from '@/features/exguard';
+
+export function getAccessToken(): string | null {
+  return localStorage.getItem(EXGUARD_STORAGE_KEYS.ACCESS_TOKEN);
+}
+
+export function getIdToken(): string | null {
+  return localStorage.getItem(EXGUARD_STORAGE_KEYS.ID_TOKEN);
+}
+
+export function clearTokens(): void {
+  localStorage.removeItem(EXGUARD_STORAGE_KEYS.ACCESS_TOKEN);
+  localStorage.removeItem(EXGUARD_STORAGE_KEYS.ID_TOKEN);
+  localStorage.removeItem(EXGUARD_STORAGE_KEYS.REFRESH_TOKEN);
+}
+
+// Use in axios interceptor
+import axios from 'axios';
+
+axios.interceptors.request.use((config) => {
+  const token = getAccessToken();
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+```
+
+## Best Practices
+
+### 1. Import Pattern
+
+**✅ DO:** Use the generated exguard module for imports
+```tsx
+import { PermissionGuard, useUserAccess } from '@/features/exguard';
+```
+
+**❌ DON'T:** Mix package and module imports
+```tsx
+// Avoid this - choose one pattern
+import { PermissionGuard } from '@empowerx/exguard-client';
+import { useUserAccess } from '@/features/exguard';
+```
+
+### 2. Permission Guard Placement
+
+**✅ DO:** Place PermissionGuard at route level
+```tsx
+<Route 
+  path="/profiles" 
+  element={
+    <PermissionGuard module="EXID">
+      <ProfilesPage />
+    </PermissionGuard>
+  } 
+/>
+```
+
+**✅ DO:** Use for feature-level protection
+```tsx
+<PermissionGuard module="EXID" permission="profile:delete">
+  <DeleteButton />
+</PermissionGuard>
+```
+
+### 3. Error Handling
+
+Always handle permission errors gracefully:
+
+```tsx
+import { useUserAccess } from '@/features/exguard';
+
+export function MyComponent() {
+  const { hasModuleAccess, error, isLoading } = useUserAccess();
+
+  if (isLoading) {
+    return <LoadingSpinner />;
+  }
+
+  if (error) {
+    return <ErrorMessage message="Failed to load permissions" />;
+  }
+
+  if (!hasModuleAccess('EXID')) {
+    return <AccessDenied />;
+  }
+
+  return <ProtectedContent />;
+}
+```
+
+### 4. Performance
+
+Use `enabled` option to control when to fetch permissions:
+
+```tsx
+const { hasModuleAccess } = useUserAccess({
+  enabled: isAuthenticated, // Only fetch when authenticated
+  refetchInterval: 60000,   // Refetch every minute
+});
+```
+
+### 5. TypeScript Usage
+
+Leverage full type safety:
+
+```tsx
+import type { 
+  UserAccessData, 
+  ModulePermissions,
+  RealtimeEventPayload 
+} from '@/features/exguard';
+
+interface MyComponentProps {
+  userAccess: UserAccessData;
+  onPermissionChange: (payload: RealtimeEventPayload) => void;
+}
+```
+
+## Troubleshooting
+
+### Issue: "Cannot find module '@/features/exguard'"
+
+**Solution:** Ensure you've run the setup script and your tsconfig paths are configured:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### Issue: WebSocket not connecting
+
+**Solution:** Check that:
+1. ExGuard API URL is correct
+2. User is authenticated (has valid tokens)
+3. CORS is properly configured on the backend
+4. ExGuardRealtimeProvider is wrapping your app
+
+```tsx
+// Debug connection
+const { isConnected } = useExGuardRealtime();
+console.log('WebSocket connected:', isConnected);
+```
+
+### Issue: Permissions not updating in real-time
+
+**Solution:** Ensure you're listening to the correct events:
+
+```tsx
+import { EXGUARD_RBAC_EVENTS } from '@/features/exguard';
+
+// Listen to general RBAC updates
+useExGuardRealtimeSubscription(
+  EXGUARD_RBAC_EVENTS.RBAC_PERMISSIONS_UPDATED,
+  (payload) => {
+    // Refresh user access data
+    window.location.reload();
+  }
+);
+```
+
+### Issue: TypeScript errors after installation
+
+**Solution:** Rebuild the package and clear TypeScript cache:
+
+```bash
+cd packages/exguard-client
+pnpm build
+
+# In your app
+rm -rf node_modules/.cache
+pnpm install
+```
+
+### Issue: Module not found errors for old imports
+
+**Solution:** Old realtime provider files need to be deleted. Remove:
+- `src/app/providers/realtime-*.ts*`
+- `src/shared/hooks/use-realtime.ts`
+- `src/shared/lib/realtime*.ts`
+
+Then update all imports to use `@/features/exguard`.
+
+## Support
+
+For additional help:
+
+1. Check the [README.md](./README.md) for API reference
+2. Review example implementations in the test applications
+3. Contact the EmpowerX development team
+
+## License
+
+MIT