@qwickapps/server 1.1.9 → 1.3.0

package/ui/src/App.tsx

@@ -1,21 +1,64 @@
+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 { 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: '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(['/', '/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 +77,143 @@ 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="/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>
   );
 }

package/ui/src/api/controlPanelApi.ts

@@ -20,12 +20,13 @@ export interface HealthResponse {
 
 export interface InfoResponse {
   product: string;
+  logoName: string;
+  logoIconUrl?: string;
   version: string;
   uptime: number;
   links: Array<{ label: string; url: string; external?: boolean }>;
   branding?: {
     primaryColor?: string;
-    logo?: string;
   };
 }
 
@@ -33,6 +34,8 @@ export interface DiagnosticsResponse {
   timestamp: string;
   product: string;
   version?: string;
+  /** @qwickapps/server framework version */
+  frameworkVersion?: string;
   uptime: number;
   health: Record<string, HealthCheck>;
   system: {
@@ -75,6 +78,131 @@ export interface LogSource {
   available: boolean;
 }
 
+// ==================
+// Users API Types
+// ==================
+export interface User {
+  id: string;
+  email: string;
+  name?: string;
+  created_at?: string;
+  updated_at?: string;
+  last_login?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UsersResponse {
+  users: User[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+// ==================
+// Bans API Types
+// ==================
+export interface Ban {
+  id: string;
+  user_id?: string;
+  email: string;
+  reason: string;
+  banned_at: string;
+  banned_by: string;
+  expires_at?: string;
+}
+
+export interface BansResponse {
+  bans: Ban[];
+  total: number;
+}
+
+// ==================
+// Entitlements API Types
+// ==================
+export interface EntitlementDefinition {
+  id: string;
+  name: string;
+  category?: string;
+  description?: string;
+}
+
+export interface EntitlementResult {
+  identifier: string;
+  entitlements: string[];
+  source: string;
+  cached?: boolean;
+  cachedAt?: string;
+  expiresAt?: string;
+}
+
+// ==================
+// Entitlements Status
+// ==================
+export interface EntitlementSourceInfo {
+  name: string;
+  description?: string;
+  readonly: boolean;
+  primary: boolean;
+}
+
+export interface EntitlementsStatus {
+  readonly: boolean;
+  writeEnabled: boolean;
+  cacheEnabled: boolean;
+  cacheTtl: number;
+  sources: EntitlementSourceInfo[];
+}
+
+// ==================
+// Plugin Feature Detection
+// ==================
+export interface PluginFeatures {
+  users: boolean;
+  bans: boolean;
+  entitlements: boolean;
+  entitlementsReadonly?: boolean;
+}
+
+// ==================
+// UI Contributions Types
+// ==================
+
+export interface MenuContribution {
+  id: string;
+  label: string;
+  icon?: string;
+  route: string;
+  order?: number;
+  pluginId: string;
+  parent?: string;
+}
+
+export interface PageContribution {
+  id: string;
+  route: string;
+  title: string;
+  pluginId: string;
+}
+
+export interface WidgetContribution {
+  id: string;
+  title: string;
+  /** Component name to render (matched by frontend widget registry) */
+  component: string;
+  /** Priority for ordering (lower = first, default: 100) */
+  priority?: number;
+  /** Whether this widget is shown by default */
+  showByDefault?: boolean;
+  pluginId: string;
+}
+
+export interface UiContributionsResponse {
+  menuItems: MenuContribution[];
+  pages: PageContribution[];
+  widgets: WidgetContribution[];
+  plugins: Array<{ id: string; name: string; version?: string; status: string }>;
+}
+
 class ControlPanelApi {
   private baseUrl: string;
 
@@ -82,6 +210,207 @@ class ControlPanelApi {
     this.baseUrl = baseUrl;
   }
 
+  /**
+   * Set the base URL for API requests.
+   * Call this when the control panel is mounted at a custom path.
+   */
+  setBaseUrl(baseUrl: string): void {
+    this.baseUrl = baseUrl;
+  }
+
+  // ==================
+  // Plugin Feature Detection
+  // ==================
+
+  /**
+   * Detect which user management plugins are available by probing their endpoints
+   */
+  async detectFeatures(): Promise<PluginFeatures> {
+    const [users, bans, entitlements] = await Promise.all([
+      this.checkEndpoint('/api/users'),
+      this.checkEndpoint('/api/bans'),
+      this.checkEndpoint('/api/entitlements/available'),
+    ]);
+
+    // If entitlements is available, get readonly status
+    let entitlementsReadonly = true;
+    if (entitlements) {
+      try {
+        const status = await this.getEntitlementsStatus();
+        entitlementsReadonly = status.readonly;
+      } catch {
+        // Default to readonly if we can't get status
+      }
+    }
+
+    return { users, bans, entitlements, entitlementsReadonly };
+  }
+
+  private async checkEndpoint(path: string): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, { method: 'HEAD' });
+      // 200, 401, 403 mean the endpoint exists (might need auth)
+      // 404 means it doesn't exist
+      return response.status !== 404;
+    } catch {
+      return false;
+    }
+  }
+
+  // ==================
+  // Users API
+  // ==================
+
+  async getUsers(options: {
+    limit?: number;
+    page?: number;
+    search?: string;
+  } = {}): Promise<UsersResponse> {
+    const params = new URLSearchParams();
+    if (options.limit) params.set('limit', options.limit.toString());
+    if (options.page) params.set('page', options.page.toString());
+    if (options.search) params.set('search', options.search);
+
+    const response = await fetch(`${this.baseUrl}/api/users?${params}`);
+    if (!response.ok) {
+      throw new Error(`Users request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getUserById(id: string): Promise<User> {
+    const response = await fetch(`${this.baseUrl}/api/users/${id}`);
+    if (!response.ok) {
+      throw new Error(`User request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  // ==================
+  // Bans API
+  // ==================
+
+  async getBans(): Promise<BansResponse> {
+    const response = await fetch(`${this.baseUrl}/api/bans`);
+    if (!response.ok) {
+      throw new Error(`Bans request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async banUser(email: string, reason: string, expiresAt?: string): Promise<void> {
+    const response = await fetch(`${this.baseUrl}/api/bans`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, reason, expiresAt }),
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `Ban request failed: ${response.statusText}`);
+    }
+  }
+
+  async unbanUser(email: string): Promise<void> {
+    const response = await fetch(`${this.baseUrl}/api/bans/${encodeURIComponent(email)}`, {
+      method: 'DELETE',
+    });
+    if (!response.ok) {
+      throw new Error(`Unban request failed: ${response.statusText}`);
+    }
+  }
+
+  async checkBan(email: string): Promise<{ banned: boolean; ban?: Ban }> {
+    const response = await fetch(`${this.baseUrl}/api/bans/check/${encodeURIComponent(email)}`);
+    if (!response.ok) {
+      throw new Error(`Ban check failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  // ==================
+  // Entitlements API
+  // ==================
+
+  async getEntitlements(email: string): Promise<EntitlementResult> {
+    const response = await fetch(`${this.baseUrl}/api/entitlements/${encodeURIComponent(email)}`);
+    if (!response.ok) {
+      throw new Error(`Entitlements request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async refreshEntitlements(email: string): Promise<EntitlementResult> {
+    const response = await fetch(`${this.baseUrl}/api/entitlements/${encodeURIComponent(email)}/refresh`, {
+      method: 'POST',
+    });
+    if (!response.ok) {
+      throw new Error(`Entitlements refresh failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async checkEntitlement(email: string, entitlement: string): Promise<{ has: boolean }> {
+    const response = await fetch(
+      `${this.baseUrl}/api/entitlements/${encodeURIComponent(email)}/check/${encodeURIComponent(entitlement)}`
+    );
+    if (!response.ok) {
+      throw new Error(`Entitlement check failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getAvailableEntitlements(): Promise<EntitlementDefinition[]> {
+    const response = await fetch(`${this.baseUrl}/api/entitlements/available`);
+    if (!response.ok) {
+      throw new Error(`Available entitlements request failed: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.entitlements;
+  }
+
+  async grantEntitlement(email: string, entitlement: string): Promise<void> {
+    const response = await fetch(`${this.baseUrl}/api/entitlements/${encodeURIComponent(email)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ entitlement }),
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `Grant entitlement failed: ${response.statusText}`);
+    }
+  }
+
+  async revokeEntitlement(email: string, entitlement: string): Promise<void> {
+    const response = await fetch(
+      `${this.baseUrl}/api/entitlements/${encodeURIComponent(email)}/${encodeURIComponent(entitlement)}`,
+      { method: 'DELETE' }
+    );
+    if (!response.ok) {
+      throw new Error(`Revoke entitlement failed: ${response.statusText}`);
+    }
+  }
+
+  async invalidateEntitlementCache(email: string): Promise<void> {
+    const response = await fetch(`${this.baseUrl}/api/entitlements/cache/${encodeURIComponent(email)}`, {
+      method: 'DELETE',
+    });
+    if (!response.ok) {
+      throw new Error(`Cache invalidation failed: ${response.statusText}`);
+    }
+  }
+
+  async getEntitlementsStatus(): Promise<EntitlementsStatus> {
+    const response = await fetch(`${this.baseUrl}/api/entitlements/status`);
+    if (!response.ok) {
+      throw new Error(`Entitlements status request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  // ==================
+  // Health API
+  // ==================
+
   async getHealth(): Promise<HealthResponse> {
     const response = await fetch(`${this.baseUrl}/api/health`);
     if (!response.ok) {
@@ -143,6 +472,30 @@ class ControlPanelApi {
     const data = await response.json();
     return data.sources;
   }
+
+  // ==================
+  // Plugins API
+  // ==================
+
+  async getPlugins(): Promise<{ plugins: Array<{ id: string; name: string; version?: string }> }> {
+    const response = await fetch(`${this.baseUrl}/api/plugins`);
+    if (!response.ok) {
+      throw new Error(`Plugins request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  // ==================
+  // UI Contributions API
+  // ==================
+
+  async getUiContributions(): Promise<UiContributionsResponse> {
+    const response = await fetch(`${this.baseUrl}/api/ui-contributions`);
+    if (!response.ok) {
+      throw new Error(`UI contributions request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
 }
 
 export const api = new ControlPanelApi();