@qwickapps/server 1.2.0 → 1.3.1

package/src/plugins/users/users-plugin.ts

@@ -0,0 +1,418 @@
+/**
+ * Users Plugin
+ *
+ * User identity management plugin for @qwickapps/server.
+ * Provides CRUD operations, search, and user lookup functionality.
+ *
+ * Note: Ban management is handled by the separate Bans Plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type {
+  UsersPluginConfig,
+  UserStore,
+  User,
+  CreateUserInput,
+  UpdateUserInput,
+  UserSearchParams,
+  UserInfo,
+  UserSyncInput,
+} from './types.js';
+// Import helpers from other plugins for buildUserInfo
+// Note: These imports are used dynamically based on registry.hasPlugin() checks
+import { getEntitlements } from '../entitlements/entitlements-plugin.js';
+import { getPreferences } from '../preferences/preferences-plugin.js';
+import { getActiveBan } from '../bans/bans-plugin.js';
+
+// Store instance for helper access
+let currentStore: UserStore | null = null;
+let currentRegistry: PluginRegistry | null = null;
+
+/**
+ * Create the Users plugin
+ */
+export function createUsersPlugin(config: UsersPluginConfig): Plugin {
+  const debug = config.debug || false;
+  // Routes are mounted under /api by the control panel, so don't include /api in prefix
+  const apiPrefix = config.api?.prefix || '/users';
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[UsersPlugin] ${message}`, data || '');
+    }
+  }
+
+  return {
+    id: 'users',
+    name: 'Users',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      log('Starting users plugin');
+
+      // Initialize the store (creates tables if needed)
+      await config.store.initialize();
+      log('Users plugin migrations complete');
+
+      // Store references for helper access
+      currentStore = config.store;
+      currentRegistry = registry;
+
+      // Register health check
+      registry.registerHealthCheck({
+        name: 'users-store',
+        type: 'custom',
+        check: async () => {
+          try {
+            // Simple health check - try to search with limit 1
+            await config.store.search({ limit: 1 });
+            return { healthy: true };
+          } catch {
+            return { healthy: false };
+          }
+        },
+      });
+
+      // Add API routes if enabled
+      if (config.api?.crud !== false) {
+        // List/Search users
+        registry.addRoute({
+          method: 'get',
+          path: apiPrefix,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const params: UserSearchParams = {
+                query: req.query.q as string,
+                provider: req.query.provider as string,
+                page: parseInt(req.query.page as string) || 1,
+                limit: Math.min(parseInt(req.query.limit as string) || 20, 100),
+                sortBy: (req.query.sortBy as UserSearchParams['sortBy']) || 'created_at',
+                sortOrder: (req.query.sortOrder as UserSearchParams['sortOrder']) || 'desc',
+              };
+
+              const result = await config.store.search(params);
+              res.json(result);
+            } catch (error) {
+              console.error('[UsersPlugin] Search error:', error);
+              res.status(500).json({ error: 'Failed to search users' });
+            }
+          },
+        });
+
+        // Get user by ID
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/:id`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const user = await config.store.getById(req.params.id);
+              if (!user) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+              res.json(user);
+            } catch (error) {
+              console.error('[UsersPlugin] Get user error:', error);
+              res.status(500).json({ error: 'Failed to get user' });
+            }
+          },
+        });
+
+        // Create user
+        registry.addRoute({
+          method: 'post',
+          path: apiPrefix,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input: CreateUserInput = {
+                email: req.body.email,
+                name: req.body.name,
+                external_id: req.body.external_id,
+                provider: req.body.provider,
+                picture: req.body.picture,
+                metadata: req.body.metadata,
+              };
+
+              if (!input.email) {
+                return res.status(400).json({ error: 'Email is required' });
+              }
+
+              // Check if user already exists
+              const existing = await config.store.getByEmail(input.email);
+              if (existing) {
+                return res.status(409).json({ error: 'User with this email already exists' });
+              }
+
+              const user = await config.store.create(input);
+              res.status(201).json(user);
+            } catch (error) {
+              console.error('[UsersPlugin] Create user error:', error);
+              res.status(500).json({ error: 'Failed to create user' });
+            }
+          },
+        });
+
+        // Update user
+        registry.addRoute({
+          method: 'put',
+          path: `${apiPrefix}/:id`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input: UpdateUserInput = {
+                name: req.body.name,
+                picture: req.body.picture,
+                metadata: req.body.metadata,
+              };
+
+              const user = await config.store.update(req.params.id, input);
+              if (!user) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+              res.json(user);
+            } catch (error) {
+              console.error('[UsersPlugin] Update user error:', error);
+              res.status(500).json({ error: 'Failed to update user' });
+            }
+          },
+        });
+
+        // Delete user
+        registry.addRoute({
+          method: 'delete',
+          path: `${apiPrefix}/:id`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const deleted = await config.store.delete(req.params.id);
+              if (!deleted) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+              res.status(204).send();
+            } catch (error) {
+              console.error('[UsersPlugin] Delete user error:', error);
+              res.status(500).json({ error: 'Failed to delete user' });
+            }
+          },
+        });
+
+        // GET /users/:id/info - Get comprehensive user info
+        registry.addRoute({
+          method: 'get',
+          path: `${apiPrefix}/:id/info`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const user = await config.store.getById(req.params.id);
+              if (!user) {
+                return res.status(404).json({ error: 'User not found' });
+              }
+
+              const info = await buildUserInfo(user, registry);
+              res.json(info);
+            } catch (error) {
+              console.error('[UsersPlugin] Get user info error:', error);
+              res.status(500).json({ error: 'Failed to get user info' });
+            }
+          },
+        });
+
+        // POST /users/sync - Find or create user, return comprehensive info
+        registry.addRoute({
+          method: 'post',
+          path: `${apiPrefix}/sync`,
+          pluginId: 'users',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const input = req.body as UserSyncInput;
+
+              // Normalize and validate email
+              const email = input.email?.trim().toLowerCase();
+              const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+              if (!email || !emailRegex.test(email)) {
+                return res.status(400).json({ error: 'Valid email is required' });
+              }
+
+              // Validate required fields
+              if (!input.external_id) {
+                return res.status(400).json({ error: 'external_id is required' });
+              }
+              if (!input.provider) {
+                return res.status(400).json({ error: 'provider is required' });
+              }
+
+              // Find or create user
+              const user = await findOrCreateUser({
+                email: email,
+                external_id: input.external_id,
+                provider: input.provider,
+                name: input.name?.trim(),
+                picture: input.picture?.trim(),
+              });
+
+              const info = await buildUserInfo(user, registry);
+              res.json(info);
+            } catch (error) {
+              console.error('[UsersPlugin] User sync error:', error);
+              res.status(500).json({ error: 'Failed to sync user' });
+            }
+          },
+        });
+      }
+
+      log('Users plugin started');
+    },
+
+    async onStop(): Promise<void> {
+      log('Stopping users plugin');
+      await config.store.shutdown();
+      currentStore = null;
+      currentRegistry = null;
+      log('Users plugin stopped');
+    },
+  };
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Get the current user store instance
+ */
+export function getUserStore(): UserStore | null {
+  return currentStore;
+}
+
+/**
+ * Get a user by ID
+ */
+export async function getUserById(id: string): Promise<User | null> {
+  if (!currentStore) {
+    throw new Error('Users plugin not initialized');
+  }
+  return currentStore.getById(id);
+}
+
+/**
+ * Get a user by email
+ */
+export async function getUserByEmail(email: string): Promise<User | null> {
+  if (!currentStore) {
+    throw new Error('Users plugin not initialized');
+  }
+  return currentStore.getByEmail(email);
+}
+
+/**
+ * Find or create a user from auth provider data
+ */
+export async function findOrCreateUser(data: {
+  email: string;
+  name?: string;
+  external_id: string;
+  provider: string;
+  picture?: string;
+}): Promise<User> {
+  if (!currentStore) {
+    throw new Error('Users plugin not initialized');
+  }
+
+  // Try to find by external ID first
+  let user = await currentStore.getByExternalId(data.external_id, data.provider);
+  if (user) {
+    await currentStore.updateLastLogin(user.id);
+    return user;
+  }
+
+  // Try to find by email
+  user = await currentStore.getByEmail(data.email);
+  if (user) {
+    // Note: external_id cannot be updated after user creation for security reasons
+    await currentStore.updateLastLogin(user.id);
+    return user;
+  }
+
+  // Create new user
+  user = await currentStore.create({
+    email: data.email,
+    name: data.name,
+    external_id: data.external_id,
+    provider: data.provider,
+    picture: data.picture,
+  });
+
+  return user;
+}
+
+/**
+ * Build comprehensive user info by aggregating data from all loaded plugins.
+ * This helper fetches data from entitlements, preferences, and bans plugins
+ * in parallel (if they are loaded) and returns a unified UserInfo object.
+ */
+export async function buildUserInfo(user: User, registry: PluginRegistry): Promise<UserInfo> {
+  const info: UserInfo = { user };
+
+  // Fetch data from other plugins in parallel
+  const promises: Promise<void>[] = [];
+
+  if (registry.hasPlugin('entitlements')) {
+    promises.push(
+      getEntitlements(user.email)
+        .then((result) => {
+          info.entitlements = result.entitlements;
+        })
+        .catch((error) => {
+          console.error('[UsersPlugin] Failed to fetch entitlements:', error);
+          // Continue without entitlements - don't fail the whole request
+        })
+    );
+  }
+
+  if (registry.hasPlugin('preferences')) {
+    promises.push(
+      getPreferences(user.id)
+        .then((prefs) => {
+          info.preferences = prefs;
+        })
+        .catch((error) => {
+          console.error('[UsersPlugin] Failed to fetch preferences:', error);
+          // Continue without preferences - don't fail the whole request
+        })
+    );
+  }
+
+  if (registry.hasPlugin('bans')) {
+    promises.push(
+      getActiveBan(user.id)
+        .then((ban) => {
+          // Transform Ban to UserInfo.ban shape (only include relevant fields)
+          info.ban = ban
+            ? {
+                id: ban.id,
+                reason: ban.reason,
+                banned_at: ban.banned_at,
+                expires_at: ban.expires_at,
+              }
+            : null;
+        })
+        .catch((error) => {
+          console.error('[UsersPlugin] Failed to fetch ban status:', error);
+          // Continue without ban info - don't fail the whole request
+        })
+    );
+  }
+
+  // Future: roles plugin
+  // if (registry.hasPlugin('roles')) {
+  //   promises.push(getUserRoles(user.id).then(roles => info.roles = roles));
+  // }
+
+  await Promise.all(promises);
+  return info;
+}

package/ui/src/App.tsx

@@ -1,21 +1,66 @@
+import { useState, useEffect } from 'react';
 import { BrowserRouter, Routes, Route } from 'react-router-dom';
 import { QwickApp, ProductLogo, Text } from '@qwickapps/react-framework';
 import { Link, Box } from '@mui/material';
 import { defaultConfig } from './config/AppConfig';
+import { DashboardWidgetProvider } from './dashboard';
 import { DashboardPage } from './pages/DashboardPage';
-import { HealthPage } from './pages/HealthPage';
 import { LogsPage } from './pages/LogsPage';
-import { ConfigPage } from './pages/ConfigPage';
-import { DiagnosticsPage } from './pages/DiagnosticsPage';
+import { SystemPage } from './pages/SystemPage';
+import { PluginsPage } from './pages/PluginsPage';
+import { UsersPage } from './pages/UsersPage';
+import { EntitlementsPage } from './pages/EntitlementsPage';
+import { PluginPage } from './pages/PluginPage';
 import { NotFoundPage } from './pages/NotFoundPage';
+import { api, type MenuContribution } from './api/controlPanelApi';
+
+// Navigation item type
+interface NavigationItem {
+  id: string;
+  label: string;
+  route: string;
+  icon: string;
+}
+
+// Core navigation items always shown
+const coreNavigationItems: NavigationItem[] = [
+  { id: 'dashboard', label: 'Dashboard', route: '/', icon: 'dashboard' },
+  { id: 'plugins', label: 'Plugins', route: '/plugins', icon: 'extension' },
+  { id: 'logs', label: 'Logs', route: '/logs', icon: 'article' },
+  { id: 'system', label: 'System', route: '/system', icon: 'settings' },
+];
+
+// Built-in optional navigation items - shown if corresponding plugin is registered
+const builtInPluginNavItems: Record<string, NavigationItem> = {
+  users: { id: 'users', label: 'Users', route: '/users', icon: 'people' },
+};
+
+// Routes that have dedicated page components
+const dedicatedRoutes = new Set(['/', '/plugins', '/logs', '/system', '/users', '/entitlements']);
 
 // Package version - injected at build time or fallback
 const SERVER_VERSION = '1.0.0';
 
-// Default logo - consumers can customize
-const logo = <ProductLogo name="Control Panel" />;
+// Declare global type for injected base path
+declare global {
+  interface Window {
+    __APP_BASE_PATH__?: string;
+  }
+}
+
+/**
+ * Get the base path for the application.
+ *
+ * The server injects window.__APP_BASE_PATH__ at runtime based on
+ * either the configured mountPath or X-Forwarded-Prefix header.
+ * This is a simple, robust approach - no complex detection needed.
+ */
+const basePath = window.__APP_BASE_PATH__ ?? '';
+
+// Configure API with the detected base path
+api.setBaseUrl(basePath);
 
-// Default footer content with QwickApps Server branding
+// Footer content with QwickApps Server branding
 const footerContent = (
   <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'center', gap: 0.5, py: 2 }}>
     <Text variant="caption" customColor="var(--theme-text-secondary)">
@@ -34,32 +79,144 @@ const footerContent = (
 );
 
 export function App() {
+  const [navigationItems, setNavigationItems] = useState<NavigationItem[]>(coreNavigationItems);
+  const [registeredPlugins, setRegisteredPlugins] = useState<Set<string>>(new Set());
+  const [pluginMenuItems, setPluginMenuItems] = useState<MenuContribution[]>([]);
+  const [logoName, setLogoName] = useState<string>('Control Panel');
+  const [logoIconUrl, setLogoIconUrl] = useState<string | undefined>();
+  const [isLoading, setIsLoading] = useState(true);
+
+  // Fetch product info and UI contributions on mount
+  useEffect(() => {
+    const loadData = async () => {
+      try {
+        // Fetch both in parallel
+        const [infoResult, contributionsResult] = await Promise.allSettled([
+          api.getInfo(),
+          api.getUiContributions(),
+        ]);
+
+        // Update logo name and icon URL if info fetch succeeded
+        if (infoResult.status === 'fulfilled') {
+          setLogoName(infoResult.value.logoName);
+          setLogoIconUrl(infoResult.value.logoIconUrl);
+        } else {
+          console.warn('Failed to fetch product info:', infoResult.reason);
+        }
+
+        // Update navigation from UI contributions
+        if (contributionsResult.status === 'fulfilled') {
+          const { plugins, menuItems } = contributionsResult.value;
+          const pluginIds = new Set(plugins.map((p) => p.id));
+          setRegisteredPlugins(pluginIds);
+          setPluginMenuItems(menuItems);
+
+          // Build navigation: core items + built-in plugin items + dynamic menu items
+          const dynamicNav = [...coreNavigationItems];
+
+          // Add built-in plugin nav items (like Users)
+          for (const [pluginId, navItem] of Object.entries(builtInPluginNavItems)) {
+            if (pluginIds.has(pluginId)) {
+              dynamicNav.push(navItem);
+            }
+          }
+
+          // Add plugin-contributed menu items (sorted by order)
+          const sortedMenuItems = [...menuItems].sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+          for (const menuItem of sortedMenuItems) {
+            // Skip if we already have a nav item for this route
+            if (dynamicNav.some(nav => nav.route === menuItem.route)) {
+              continue;
+            }
+            dynamicNav.push({
+              id: menuItem.id,
+              label: menuItem.label,
+              route: menuItem.route,
+              icon: menuItem.icon || 'extension',
+            });
+          }
+
+          setNavigationItems(dynamicNav);
+        } else {
+          console.warn('Failed to fetch UI contributions:', contributionsResult.reason);
+        }
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    loadData();
+  }, []);
+
+  // Dynamic logo based on logoName and logoIconUrl from API
+  // When logoIconUrl is provided, use it as a custom icon instead of the default QwickIcon
+  const logoIcon = logoIconUrl ? (
+    <img
+      src={logoIconUrl}
+      alt={logoName}
+      style={{ width: 32, height: 32, objectFit: 'contain' }}
+    />
+  ) : undefined;
+  const logo = <ProductLogo icon={logoIcon} name={logoName} />;
+
+  // Show loading state until plugins are loaded
+  // This ensures QwickApp receives the correct navigation on first render
+  if (isLoading) {
+    return (
+      <Box
+        sx={{
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          minHeight: '100vh',
+          bgcolor: 'var(--theme-background, #1a1a2e)',
+        }}
+      />
+    );
+  }
+
   return (
-    <BrowserRouter>
-      <QwickApp
-        config={defaultConfig}
-        logo={logo}
-        footerContent={footerContent}
-        enableScaffolding={true}
-        navigationItems={[
-          { id: 'dashboard', label: 'Dashboard', route: '/', icon: 'dashboard' },
-          { id: 'health', label: 'Health', route: '/health', icon: 'favorite' },
-          { id: 'logs', label: 'Logs', route: '/logs', icon: 'article' },
-          { id: 'config', label: 'Config', route: '/config', icon: 'settings' },
-          { id: 'diagnostics', label: 'Diagnostics', route: '/diagnostics', icon: 'bug_report' },
-        ]}
-        showThemeSwitcher={true}
-        showPaletteSwitcher={true}
-      >
-        <Routes>
-          <Route path="/" element={<DashboardPage />} />
-          <Route path="/health" element={<HealthPage />} />
-          <Route path="/logs" element={<LogsPage />} />
-          <Route path="/config" element={<ConfigPage />} />
-          <Route path="/diagnostics" element={<DiagnosticsPage />} />
-          <Route path="*" element={<NotFoundPage />} />
-        </Routes>
-      </QwickApp>
+    <BrowserRouter basename={basePath || undefined}>
+      <DashboardWidgetProvider>
+        <QwickApp
+          config={defaultConfig}
+          logo={logo}
+          footerContent={footerContent}
+          enableScaffolding={true}
+          navigationItems={navigationItems}
+          showThemeSwitcher={true}
+          showPaletteSwitcher={true}
+        >
+          <Routes>
+            {/* Core routes */}
+            <Route path="/" element={<DashboardPage />} />
+            <Route path="/plugins" element={<PluginsPage />} />
+            <Route path="/logs" element={<LogsPage />} />
+            <Route path="/system" element={<SystemPage />} />
+
+            {/* Built-in plugin routes */}
+            {registeredPlugins.has('users') && (
+              <Route path="/users" element={<UsersPage />} />
+            )}
+            {registeredPlugins.has('entitlements') && (
+              <Route path="/entitlements" element={<EntitlementsPage />} />
+            )}
+
+            {/* Dynamic plugin routes - render generic PluginPage for non-dedicated routes */}
+            {pluginMenuItems
+              .filter(item => !dedicatedRoutes.has(item.route))
+              .map(item => (
+                <Route
+                  key={item.id}
+                  path={item.route}
+                  element={<PluginPage pluginId={item.pluginId} title={item.label} route={item.route} />}
+                />
+              ))}
+
+            <Route path="*" element={<NotFoundPage />} />
+          </Routes>
+        </QwickApp>
+      </DashboardWidgetProvider>
     </BrowserRouter>
   );
 }