@ackplus/nest-auth 0.1.51 → 1.1.0

package/ui/README.md

@@ -0,0 +1,288 @@
+# Admin Console UI - Build Guide
+
+Beautiful Tailwind CSS admin dashboard for `@ackplus/nest-auth`
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd packages/nest-auth/src/lib/admin-console/ui
+npm install
+```
+
+### 2. Development Mode (with Hot Reload)
+
+```bash
+npm run dev
+```
+
+This will start the Vite dev server at `http://localhost:5173` with hot module reloading.
+
+### 3. Build for Production
+
+```bash
+npm run build
+```
+
+This will:
+- Compile TypeScript
+- Build React app with Vite
+- Output bundled files to `../static/` folder:
+  - `../static/index.html` (main entry)
+  - `../static/assets/app.js` (bundled JS)
+
+## 📦 Build Output
+
+```plaintext
+packages/nest-auth/src/lib/admin-console/static/
+├── index.html           # Built HTML entry point
+├── styles.css           # Existing CSS (not overwritten)
+└── assets/
+    └── app.js          # Bundled React application
+```
+
+## 🔧 Integration with nest-auth Package
+
+### Option 1: Manual Build
+
+```bash
+# Step 1: Build UI
+cd packages/nest-auth/src/lib/admin-console/ui
+npm install
+npm run build
+
+# Step 2: Build nest-auth package
+cd ../../../..  # back to nest-auth root
+npm run build
+```
+
+### Option 2: Add to nest-auth Build Script
+
+Edit `packages/nest-auth/package.json`:
+
+```json
+{
+  "scripts": {
+    "build:ui": "cd src/lib/admin-console/ui && npm install && npm run build",
+    "prebuild": "npm run build:ui",
+    "build": "tsc && your-existing-build-command"
+  }
+}
+```
+
+Now `npm run build` will automatically build the UI first.
+
+### Option 3: Using Nx (if in Nx workspace)
+
+Add to `packages/nest-auth/project.json`:
+
+```json
+{
+  "targets": {
+    "build-ui": {
+      "executor": "nx:run-commands",
+      "options": {
+        "cwd": "packages/nest-auth/src/lib/admin-console/ui",
+        "commands": [
+          "npm install",
+          "npm run build"
+        ]
+      }
+    },
+    "build": {
+      "dependsOn": ["build-ui"],
+      // ... your existing build config
+    }
+  }
+}
+```
+
+## 🛠️ Development Workflow
+
+### Local Development
+
+```bash
+# Terminal 1: Run UI dev server
+cd packages/nest-auth/src/lib/admin-console/ui
+npm run dev
+
+# Terminal 2: Run your NestJS backend
+cd packages/nest-examples  # or your app
+npm run start:dev
+```
+
+Then:
+- UI dev server: <http://localhost:5173>
+- Backend API: <http://localhost:3000>
+
+### Configuring API Base URL in Dev Mode
+
+When running the dev server in watch mode, you can configure the API base URL using the `VITE_API_BASE_URL` environment variable. Create a `.env` file in the `ui` directory:
+
+```bash
+# .env
+VITE_API_BASE_URL=http://localhost:3000
+```
+
+This sets the origin (protocol + host + port), and the default path `/api/auth/admin` will be appended automatically.
+
+**Priority order:**
+1. Server-injected config (production) - highest priority
+2. `VITE_API_BASE_URL` (origin only) + default path - for dev mode
+3. Current window origin + default path (fallback)
+
+**Note:** After creating or modifying `.env`, restart the dev server for changes to take effect.
+
+For production testing:
+
+```bash
+# Build UI
+cd packages/nest-auth/src/lib/admin-console/ui
+npm run build
+
+# Start backend (serves built UI from static folder)
+cd packages/nest-examples
+npm run start:dev
+
+# Visit: http://localhost:3000/auth/admin
+```
+
+## 📋 Available Scripts
+
+```bash
+npm run dev      # Start dev server with hot reload
+npm run build    # Build for production
+npm run preview  # Preview production build locally
+```
+
+## 🎯 What Gets Built
+
+### Dependencies Bundled
+
+- React & React DOM
+- React Router DOM
+- Lucide React (icons)
+- Recharts (charts)
+- All your components and pages
+
+### Output Size (approximate)
+
+- `app.js`: ~150-200KB (minified + gzipped)
+- `index.html`: ~2KB
+- Total: ~150-202KB
+
+## 🔍 Troubleshooting
+
+### Build Fails
+
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+npm run build
+```
+
+### TypeScript Errors
+
+```bash
+# Check TypeScript configuration
+npx tsc --noEmit
+```
+
+### Port Already in Use
+
+```bash
+# Kill process on port 5173
+lsof -ti:5173 | xargs kill -9
+
+# Or use different port
+npm run dev -- --port 3001
+```
+
+### Build Output Not Working
+
+Make sure the Vite config outputs to the correct location:
+
+```typescript
+// vite.config.ts
+build: {
+  outDir: '../static',  // Must point to static folder
+  emptyOutDir: false,   // Don't delete styles.css
+}
+```
+
+## 🎨 Tech Stack
+
+- **React 18** - UI library
+- **TypeScript 5** - Type safety
+- **Tailwind CSS 3** - Styling
+- **Vite 5** - Build tool (super fast!)
+- **Recharts 2** - Charts & data visualization
+- **Lucide React** - Beautiful icons
+
+## 📁 Project Structure
+
+```plaintext
+ui/
+├── src/
+│   ├── components/     # Reusable components
+│   ├── pages/          # Page components
+│   ├── services/       # API service layer
+│   ├── hooks/          # Custom React hooks
+│   ├── types/          # TypeScript interfaces
+│   ├── App.tsx         # Main app
+│   ├── main.tsx        # Entry point
+│   └── index.css       # Tailwind imports
+├── package.json        # Dependencies & scripts
+├── vite.config.ts      # Vite configuration
+├── tailwind.config.js  # Tailwind theme
+├── tsconfig.json       # TypeScript config
+└── index.html          # HTML template
+```
+
+## ✨ Features
+
+- 📊 Dashboard with statistics & charts
+- 👥 User management
+- 🛡️ Role & permission management
+- 🏢 Multi-tenant support
+- 👨‍💼 Admin management
+- 📚 API documentation
+- 🎨 Beautiful Tailwind UI
+- 📱 Fully responsive
+- ⚡ Lightning fast (Vite)
+
+## 🔗 How It Works
+
+1. **Development**: Vite dev server runs on port 5173
+2. **Build**: Compiles to `../static/` folder
+3. **Production**: NestJS serves files from `static/` folder
+4. **API**: SPA calls backend at `/auth/admin/api/*`
+
+## 📝 Notes
+
+- The `styles.css` in static folder is NOT overwritten by build
+- Build output goes to `../static/` relative to UI folder
+- Hot reload works in dev mode for instant updates
+- TypeScript ensures type safety throughout
+
+## 🆘 Need Help?
+
+Check these files:
+- `vite.config.ts` - Build configuration
+- `tailwind.config.js` - Theme customization
+- `tsconfig.json` - TypeScript settings
+- `src/services/api.ts` - API client setup
+
+---
+
+**Ready to build?** Run these commands:
+
+```bash
+cd packages/nest-auth/src/lib/admin-console/ui
+npm install
+npm run build
+```
+
+That's it! Your beautiful admin console is ready to use! 🎉

package/ui/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="script-src 'self' 'unsafe-inline'"
+    />
+
+    <title>Nest Auth Dashboard</title>
+  </head>
+  <body>
+    <main id="root"></main>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/ui/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "@nest-auth/admin-console-ui",
+    "version": "1.0.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "build:check": "tsc && vite build",
+        "preview": "vite preview"
+    },
+    "dependencies": {
+        "@hookform/resolvers": "^5.2.2",
+        "lucide-react": "^0.294.0",
+        "react": "^18.2.0",
+        "react-dom": "^18.2.0",
+        "react-hook-form": "^7.66.0",
+        "react-router-dom": "^6.20.0",
+        "recharts": "^2.10.0",
+        "swagger-ui-react": "^5.30.1",
+        "yup": "^1.7.1"
+    },
+    "devDependencies": {
+        "@types/react": "^18.2.0",
+        "@types/react-dom": "^18.2.0",
+        "@vitejs/plugin-react": "^4.2.0",
+        "autoprefixer": "^10.4.16",
+        "postcss": "^8.4.32",
+        "tailwindcss": "^3.3.6",
+        "typescript": "^5.3.0",
+        "vite": "^5.0.0",
+        "vite-plugin-singlefile": "^2.3.0"
+    }
+}

package/ui/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+    plugins: {
+        tailwindcss: {},
+        autoprefixer: {},
+    },
+}

package/ui/src/App.tsx

@@ -0,0 +1,245 @@
+import React, { useEffect, useState } from 'react';
+import { HashRouter, Routes, Route, Navigate } from 'react-router-dom';
+import { api } from './services/api';
+import { ConfirmProvider } from './hooks/useConfirm';
+import type { DashboardConfig } from './types';
+import { Layout } from './components/Layout';
+import { LoginPage } from './pages/LoginPage';
+import { DashboardPage } from './pages/DashboardPage';
+import { UsersPage } from './pages/UsersPage';
+import { RolesPage } from './pages/RolesPage';
+import { TenantsPage } from './pages/TenantsPage';
+import { AdminsPage } from './pages/AdminsPage';
+import { PermissionsPage } from './pages/PermissionsPage';
+import { ApiPage } from './pages/ApiPage';
+
+// Protected Route Wrapper
+const ProtectedRoute: React.FC<{
+    children: React.ReactNode;
+    authenticated: boolean | null;
+}> = ({ children, authenticated }) => {
+    // While checking auth, show loading
+    if (authenticated === null) {
+        return (
+            <div className="min-h-screen bg-gray-50 flex items-center justify-center">
+                <div className="text-center">
+                    <div className="animate-spin rounded-full h-16 w-16 border-b-4 border-primary-600 mx-auto mb-4"></div>
+                    <p className="text-gray-600 font-medium">Verifying authentication...</p>
+                </div>
+            </div>
+        );
+    }
+
+    // If not authenticated, redirect to login
+    if (!authenticated) {
+        return <Navigate to="/login" replace />;
+    }
+
+    // If authenticated, render children
+    return <>{children}</>;
+};
+
+export const App: React.FC = () => {
+    const [authenticated, setAuthenticated] = useState<boolean | null>(null);
+    const [config, setConfig] = useState<DashboardConfig | null>(null);
+    const [authChecked, setAuthChecked] = useState(false);
+    const [loginError, setLoginError] = useState<string | null>(null);
+
+    useEffect(() => {
+        checkAuthAndLoadConfig();
+    }, []);
+
+    const checkAuthAndLoadConfig = async () => {
+        try {
+            // First check authentication
+            await api.get('/me');
+            setAuthenticated(true);
+
+            // Then load config
+            const configData = await api.get<DashboardConfig>('/config');
+            setConfig(configData);
+        } catch (err: any) {
+            console.error('Auth check failed:', err);
+            setAuthenticated(false);
+
+            // Still load config for login page
+            try {
+                const configData = await api.get<DashboardConfig>('/config');
+                setConfig(configData);
+            } catch (configErr) {
+                console.error('Failed to load config:', configErr);
+                // Set default config
+                setConfig({
+                    allowAdminManagement: false,
+                });
+            }
+        } finally {
+            setAuthChecked(true);
+        }
+    };
+
+    const handleLogin = async (credentials: any) => {
+        setLoginError(null);
+        try {
+            await api.post('/login', credentials);
+            setAuthenticated(true);
+            // Recheck auth after successful login
+            await checkAuthAndLoadConfig();
+        } catch (err: any) {
+            setAuthenticated(false);
+            setLoginError(err?.message || 'Login failed');
+            throw err;
+        }
+    };
+
+    const handleLogout = async () => {
+        try {
+            await api.post('/logout', {});
+        } catch (err) {
+            console.error('Logout failed:', err);
+        }
+        setAuthenticated(false);
+    };
+
+    // Show loading screen while checking auth or loading config
+    if (!authChecked || config === null) {
+        return (
+            <div className="min-h-screen bg-gradient-to-br from-primary-50 via-blue-50 to-purple-50 flex items-center justify-center">
+                <div className="text-center">
+                    <div className="inline-flex items-center justify-center w-16 h-16 bg-primary-600 rounded-full mb-4 shadow-lg">
+                        <svg className="w-8 h-8 text-white animate-spin" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
+                            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+                        </svg>
+                    </div>
+                    <p className="text-gray-700 font-medium text-lg">Loading Nest Auth Dashboard...</p>
+                    <p className="text-gray-500 text-sm mt-2">Verifying authentication</p>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <ConfirmProvider>
+            <HashRouter>
+                <Routes>
+                    {/* Login Route - Only accessible when NOT authenticated */}
+                    <Route
+                        path="/login"
+                        element={
+                            authenticated ? (
+                                <Navigate to="/dashboard" replace />
+                            ) : (
+                                <LoginPage onLogin={handleLogin} error={loginError} />
+                            )
+                        }
+                    />
+
+                    {/* Protected Routes - Only accessible when authenticated */}
+                    <Route
+                        path="/dashboard"
+                        element={
+                            <ProtectedRoute authenticated={authenticated}>
+                                <Layout config={config} onLogout={handleLogout}>
+                                    <DashboardPage />
+                                </Layout>
+                            </ProtectedRoute>
+                        }
+                    />
+
+                    <Route
+                        path="/users"
+                        element={
+                            <ProtectedRoute authenticated={authenticated}>
+                                <Layout config={config} onLogout={handleLogout}>
+                                    <UsersPage />
+                                </Layout>
+                            </ProtectedRoute>
+                        }
+                    />
+
+                    <Route
+                        path="/roles"
+                        element={
+                            <ProtectedRoute authenticated={authenticated}>
+                                <Layout config={config} onLogout={handleLogout}>
+                                    <RolesPage />
+                                </Layout>
+                            </ProtectedRoute>
+                        }
+                    />
+
+                    <Route
+                        path="/tenants"
+                        element={
+                            <ProtectedRoute authenticated={authenticated}>
+                                <Layout config={config} onLogout={handleLogout}>
+                                    <TenantsPage />
+                                </Layout>
+                            </ProtectedRoute>
+                        }
+                    />
+
+                    <Route
+                        path="/permissions"
+                        element={
+                            <ProtectedRoute authenticated={authenticated}>
+                                <Layout config={config} onLogout={handleLogout}>
+                                    <PermissionsPage />
+                                </Layout>
+                            </ProtectedRoute>
+                        }
+                    />
+
+                    <Route
+                        path="/api"
+                        element={
+                            <ProtectedRoute authenticated={authenticated}>
+                                <Layout config={config} onLogout={handleLogout}>
+                                    <ApiPage />
+                                </Layout>
+                            </ProtectedRoute>
+                        }
+                    />
+
+                    {config.allowAdminManagement && (
+                        <Route
+                            path="/admins"
+                            element={
+                                <ProtectedRoute authenticated={authenticated}>
+                                    <Layout config={config} onLogout={handleLogout}>
+                                        <AdminsPage />
+                                    </Layout>
+                                </ProtectedRoute>
+                            }
+                        />
+                    )}
+
+                    {/* Default redirects */}
+                    <Route
+                        path="/"
+                        element={
+                            authenticated ? (
+                                <Navigate to="/dashboard" replace />
+                            ) : (
+                                <Navigate to="/login" replace />
+                            )
+                        }
+                    />
+
+                    {/* Catch all - redirect based on auth status */}
+                    <Route
+                        path="*"
+                        element={
+                            authenticated ? (
+                                <Navigate to="/dashboard" replace />
+                            ) : (
+                                <Navigate to="/login" replace />
+                            )
+                        }
+                    />
+                </Routes>
+            </HashRouter>
+        </ConfirmProvider>
+    );
+};

package/ui/src/components/AuthGuard.tsx

@@ -0,0 +1,59 @@
+import React, { useEffect, useState } from 'react';
+import { useNavigate, useLocation } from 'react-router-dom';
+import { api, ApiError } from '../services/api';
+
+interface AuthGuardProps {
+    children: React.ReactNode;
+    onAuthChange?: (authenticated: boolean) => void;
+}
+
+export const AuthGuard: React.FC<AuthGuardProps> = ({ children, onAuthChange }) => {
+    const [checking, setChecking] = useState(true);
+    const [authenticated, setAuthenticated] = useState(false);
+    const navigate = useNavigate();
+    const location = useLocation();
+
+    useEffect(() => {
+        checkAuth();
+    }, []);
+
+    const checkAuth = async () => {
+        try {
+            setChecking(true);
+            await api.get('/me');
+            setAuthenticated(true);
+            if (onAuthChange) {
+                onAuthChange(true);
+            }
+        } catch (error) {
+            setAuthenticated(false);
+            if (onAuthChange) {
+                onAuthChange(false);
+            }
+            // Redirect to login, preserving intended destination
+            navigate('/login', {
+                replace: true,
+                state: { from: location.pathname }
+            });
+        } finally {
+            setChecking(false);
+        }
+    };
+
+    if (checking) {
+        return (
+            <div className="min-h-screen bg-gray-50 flex items-center justify-center">
+                <div className="text-center">
+                    <div className="animate-spin rounded-full h-16 w-16 border-b-4 border-primary-600 mx-auto mb-4"></div>
+                    <p className="text-gray-600 font-medium">Verifying authentication...</p>
+                </div>
+            </div>
+        );
+    }
+
+    if (!authenticated) {
+        return null; // Will be redirected by useEffect
+    }
+
+    return <>{children}</>;
+};