@qwickapps/server 1.2.0 → 1.3.1

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,192 @@ 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 }>;
+}
+
+// ==================
+// Plugin Detail Types
+// ==================
+
+export interface ConfigContribution {
+  id: string;
+  component: string;
+  title?: string;
+  pluginId: string;
+}
+
+export interface PluginContributions {
+  routes: Array<{ method: string; path: string }>;
+  menuItems: MenuContribution[];
+  pages: PageContribution[];
+  widgets: WidgetContribution[];
+  config?: ConfigContribution;
+}
+
+export interface PluginInfo {
+  id: string;
+  name: string;
+  version?: string;
+  status: 'starting' | 'active' | 'stopped' | 'error';
+  error?: string;
+  contributionCounts: {
+    routes: number;
+    menuItems: number;
+    pages: number;
+    widgets: number;
+    hasConfig: boolean;
+  };
+}
+
+export interface PluginsResponse {
+  plugins: PluginInfo[];
+}
+
+export interface PluginDetailResponse {
+  id: string;
+  name: string;
+  version?: string;
+  status: 'starting' | 'active' | 'stopped' | 'error';
+  error?: string;
+  contributions: PluginContributions;
+}
+
+// ==================
+// Auth Config Types
+// ==================
+
+export type AuthPluginState = 'disabled' | 'enabled' | 'error';
+
+export interface AuthConfigStatus {
+  state: AuthPluginState;
+  adapter: string | null;
+  error?: string;
+  missingVars?: string[];
+  config?: Record<string, string>;
+}
+
 class ControlPanelApi {
   private baseUrl: string;
 
@@ -82,6 +271,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 +533,68 @@ class ControlPanelApi {
     const data = await response.json();
     return data.sources;
   }
+
+  // ==================
+  // Plugins API
+  // ==================
+
+  async getPlugins(): Promise<PluginsResponse> {
+    const response = await fetch(`${this.baseUrl}/api/plugins`);
+    if (!response.ok) {
+      throw new Error(`Plugins request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getPluginDetail(id: string): Promise<PluginDetailResponse> {
+    const response = await fetch(`${this.baseUrl}/api/plugins/${encodeURIComponent(id)}`);
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new Error(`Plugin not found: ${id}`);
+      }
+      throw new Error(`Plugin detail 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();
+  }
+
+  // ==================
+  // Auth Config API
+  // ==================
+
+  async getAuthConfigStatus(): Promise<AuthConfigStatus> {
+    const response = await fetch(`${this.baseUrl}/api/auth/config/status`);
+    if (!response.ok) {
+      // Return disabled state if endpoint not available
+      if (response.status === 404) {
+        return { state: 'disabled', adapter: null };
+      }
+      throw new Error(`Auth config status request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getAuthConfig(): Promise<AuthConfigStatus> {
+    const response = await fetch(`${this.baseUrl}/api/auth/config`);
+    if (!response.ok) {
+      if (response.status === 404) {
+        return { state: 'disabled', adapter: null };
+      }
+      throw new Error(`Auth config request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
 }
 
 export const api = new ControlPanelApi();

package/ui/src/components/ControlPanelApp.tsx

@@ -0,0 +1,212 @@
+/**
+ * ControlPanelApp Component
+ *
+ * A wrapper around QwickApp that provides control panel functionality.
+ * Injects base control panel routes (Dashboard, Health, Logs, System)
+ * and allows consumers to add custom routes.
+ *
+ * Usage:
+ * ```tsx
+ * import { ControlPanelApp } from '@qwickapps/server/ui';
+ *
+ * function App() {
+ *   return (
+ *     <ControlPanelApp
+ *       productName="My Service"
+ *       logo={<MyLogo />}
+ *       customDashboard={<MyDashboard />}
+ *     >
+ *       <Route path="/users" element={<UsersPage />} />
+ *       <Route path="/settings" element={<SettingsPage />} />
+ *     </ControlPanelApp>
+ *   );
+ * }
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { ReactNode, useState, useEffect } from 'react';
+import { Routes, Route } from 'react-router-dom';
+import { Box, Link } from '@mui/material';
+import { QwickApp, ProductLogo, Text, type MenuItem } from '@qwickapps/react-framework';
+import { defaultConfig } from '../config/AppConfig';
+
+// Base pages
+import { DashboardPage } from '../pages/DashboardPage';
+import { LogsPage } from '../pages/LogsPage';
+import { SystemPage } from '../pages/SystemPage';
+import { AuthPage } from '../pages/AuthPage';
+import { NotFoundPage } from '../pages/NotFoundPage';
+
+// Dashboard widget system
+import {
+  DashboardWidgetProvider,
+  WidgetComponentRegistryProvider,
+  getBuiltInWidgetComponents,
+  type DashboardWidget,
+  type WidgetComponent,
+} from '../dashboard';
+
+// API
+import { api } from '../api/controlPanelApi';
+
+export interface ControlPanelAppProps {
+  /** Product name displayed in the header */
+  productName?: string;
+
+  /** Custom logo component */
+  logo?: ReactNode;
+
+  /** Custom footer content (replaces default) */
+  footerContent?: ReactNode;
+
+  /** Initial dashboard widgets to register (legacy context-based system) */
+  dashboardWidgets?: DashboardWidget[];
+
+  /**
+   * Widget components to register for the plugin-based widget system.
+   * These map component names (from server WidgetContribution) to React components.
+   * Built-in widgets (ServiceHealthWidget, etc.) are registered automatically.
+   */
+  widgetComponents?: WidgetComponent[];
+
+  /** Additional navigation items to add to the base control panel nav */
+  navigationItems?: MenuItem[];
+
+  /** Whether to show the base control panel navigation (Dashboard, Health, etc.) */
+  showBaseNavigation?: boolean;
+
+  /** Base navigation item IDs to hide (e.g., ['health'] to hide the Health page) */
+  hideBaseNavItems?: string[];
+
+  /** Whether to show theme switcher in settings */
+  showThemeSwitcher?: boolean;
+
+  /** Whether to show palette switcher in settings */
+  showPaletteSwitcher?: boolean;
+
+  /** Base path for the control panel (e.g., '/cpanel') */
+  basePath?: string;
+
+  /** Custom routes to add (as Route elements) */
+  children?: ReactNode;
+}
+
+/**
+ * Default footer with QwickApps Server branding
+ */
+function DefaultFooter({ version }: { version: string }) {
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'center', gap: 0.5, py: 2 }}>
+      <Text variant="caption" customColor="var(--theme-text-secondary)">
+        Built with{' '}
+        <Link
+          href="https://qwickapps.com/products/qwickapps-server"
+          target="_blank"
+          rel="noopener noreferrer"
+          sx={{ color: 'primary.main' }}
+        >
+          QwickApps Server
+        </Link>
+        {version && ` v${version}`}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * Base navigation items for control panel
+ * Routes are relative to BrowserRouter's basename (handled by NavigationProvider in QwickApp)
+ */
+function getBaseNavigationItems(): MenuItem[] {
+  return [
+    { id: 'dashboard', label: 'Dashboard', route: '/', icon: 'dashboard' },
+    { id: 'logs', label: 'Logs', route: '/logs', icon: 'article' },
+    { id: 'auth', label: 'Auth', route: '/auth', icon: 'lock' },
+    { id: 'system', label: 'System', route: '/system', icon: 'settings' },
+  ];
+}
+
+export function ControlPanelApp({
+  productName = 'Control Panel',
+  logo,
+  footerContent,
+  dashboardWidgets = [],
+  widgetComponents = [],
+  navigationItems = [],
+  showBaseNavigation = true,
+  hideBaseNavItems = [],
+  showThemeSwitcher = true,
+  showPaletteSwitcher = true,
+  basePath = '',
+  children,
+}: ControlPanelAppProps) {
+  const [version, setVersion] = useState<string>('');
+
+  // Combine built-in widget components with custom ones
+  const allWidgetComponents = [...getBuiltInWidgetComponents(), ...widgetComponents];
+
+  // Configure API base URL based on basePath - do this synchronously before any renders
+  // If basePath is '/cpanel', API is at '/cpanel/api'
+  // If basePath is '' or '/', API is at '/api'
+  const apiBasePath = basePath && basePath !== '/' ? basePath : '';
+  api.setBaseUrl(apiBasePath);
+
+  // Fetch version from API
+  useEffect(() => {
+    api.getInfo()
+      .then((info) => setVersion(info.version || ''))
+      .catch(() => {});
+  }, [apiBasePath]); // Re-fetch when apiBasePath changes
+
+  // Build navigation: base items (filtered by hideBaseNavItems) + custom items
+  // Navigation routes are relative to BrowserRouter's basename
+  const filteredBaseItems = showBaseNavigation
+    ? getBaseNavigationItems().filter(item => !hideBaseNavItems.includes(item.id))
+    : [];
+  const allNavigationItems: MenuItem[] = [
+    ...filteredBaseItems,
+    ...navigationItems,
+  ];
+
+  // Default logo if not provided
+  const effectiveLogo = logo || <ProductLogo name={productName} />;
+
+  // Default footer if not provided
+  const effectiveFooter = footerContent || <DefaultFooter version={version} />;
+
+  return (
+    <WidgetComponentRegistryProvider initialComponents={allWidgetComponents}>
+      <DashboardWidgetProvider initialWidgets={dashboardWidgets}>
+        <QwickApp
+          config={defaultConfig}
+          logo={effectiveLogo}
+          footerContent={effectiveFooter}
+          enableScaffolding={true}
+          navigationItems={allNavigationItems}
+          showThemeSwitcher={showThemeSwitcher}
+          showPaletteSwitcher={showPaletteSwitcher}
+        >
+          <Routes>
+            {/* Base control panel routes (filtered by hideBaseNavItems) */}
+            {showBaseNavigation && (
+              <>
+                {!hideBaseNavItems.includes('dashboard') && <Route path="/" element={<DashboardPage />} />}
+                {!hideBaseNavItems.includes('logs') && <Route path="/logs" element={<LogsPage />} />}
+                {!hideBaseNavItems.includes('auth') && <Route path="/auth" element={<AuthPage />} />}
+                {!hideBaseNavItems.includes('system') && <Route path="/system" element={<SystemPage />} />}
+              </>
+            )}
+
+            {/* Custom routes from consumer */}
+            {children}
+
+            {/* Catch-all for 404 */}
+            <Route path="*" element={<NotFoundPage />} />
+          </Routes>
+        </QwickApp>
+      </DashboardWidgetProvider>
+    </WidgetComponentRegistryProvider>
+  );
+}