@qwickapps/server 1.6.0 → 1.7.0

package/src/plugins/bans/BansManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * BansManagementPage Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { BansManagementPage } from './BansManagementPage';
+
+describe('BansManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<BansManagementPage apiPrefix="/api/bans" />);
+
+    expect(screen.getByText('User Bans Management')).toBeInTheDocument();
+  });
+
+  it('fetches bans on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<BansManagementPage apiPrefix="/api/bans" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+
+  it('renders with custom apiPrefix', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<BansManagementPage apiPrefix="/custom/bans" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+});

package/src/plugins/bans/BansManagementPage.tsx

@@ -0,0 +1,129 @@
+/**
+ * BansManagementPage - Full management interface for user bans
+ */
+
+import React, { useState, useEffect } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, Column } from '@qwickapps/react-framework';
+
+export interface BansManagementPageProps {
+  /** API endpoint prefix (default: '/api/bans') */
+  apiPrefix?: string;
+}
+
+interface Ban {
+  id: string;
+  userId: string;
+  userEmail: string;
+  reason: string;
+  type: 'permanent' | 'temporary';
+  status: 'active' | 'expired' | 'lifted';
+  createdAt: string;
+  expiresAt?: string;
+  createdBy?: string;
+}
+
+export function BansManagementPage({ apiPrefix = '/api/bans' }: BansManagementPageProps) {
+  const [activeTab, setActiveTab] = useState<'all' | 'active' | 'expired' | 'config'>('all');
+  const [bans, setBans] = useState<Ban[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const status = activeTab === 'all' ? undefined : activeTab;
+    const url = status ? `${apiPrefix}?status=${status}` : `${apiPrefix}`;
+
+    fetch(url)
+      .then((res) => res.json())
+      .then((data) => {
+        setBans(data.bans || []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, [activeTab, apiPrefix]);
+
+  const columns: Column<Ban>[] = [
+    { key: 'userEmail', label: 'User', sortable: true },
+    { key: 'reason', label: 'Reason', sortable: true },
+    {
+      key: 'type',
+      label: 'Type',
+      sortable: true,
+      render: (val) => (
+        <span
+          className={`px-2 py-1 rounded text-xs font-medium ${
+            val === 'permanent'
+              ? 'bg-red-100 dark:bg-red-900 text-red-800 dark:text-red-100'
+              : 'bg-yellow-100 dark:bg-yellow-900 text-yellow-800 dark:text-yellow-100'
+          }`}
+        >
+          {String(val)}
+        </span>
+      ),
+    },
+    {
+      key: 'status',
+      label: 'Status',
+      sortable: true,
+      render: (val) => (
+        <span
+          className={`px-2 py-1 rounded text-xs font-medium ${
+            val === 'active'
+              ? 'bg-red-100 dark:bg-red-900 text-red-800 dark:text-red-100'
+              : val === 'expired'
+              ? 'bg-gray-100 dark:bg-gray-700 text-gray-800 dark:text-gray-300'
+              : 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-100'
+          }`}
+        >
+          {String(val)}
+        </span>
+      ),
+    },
+    { key: 'createdAt', label: 'Created', sortable: true },
+    { key: 'expiresAt', label: 'Expires', sortable: true },
+    { key: 'createdBy', label: 'Created By' },
+  ];
+
+  const handleLiftBans = (selectedBans: Ban[]) => {
+    console.log('Lift bans:', selectedBans);
+  };
+
+  const tabs = [
+    { id: 'all', label: 'All Bans' },
+    { id: 'active', label: 'Active' },
+    { id: 'expired', label: 'Expired' },
+    { id: 'config', label: 'Configuration' },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="Bans Management"
+      tabs={tabs}
+      activeTab={activeTab}
+      onTabChange={(tab) => setActiveTab(tab as typeof activeTab)}
+    >
+      {activeTab === 'config' ? (
+        <div className="space-y-4">
+          <div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+            <p className="text-sm text-blue-900 dark:text-blue-100">
+              Ban policies and automatic ban rules configuration.
+            </p>
+          </div>
+        </div>
+      ) : (
+        <DataTable
+          columns={columns}
+          data={bans}
+          loading={loading}
+          emptyMessage="No bans found"
+          bulkActions={[
+            {
+              label: 'Lift Selected',
+              onClick: handleLiftBans,
+              variant: 'primary',
+            },
+          ]}
+        />
+      )}
+    </PluginManagementPage>
+  );
+}

package/src/plugins/bans/BansStatusWidget.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * BansStatusWidget Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { BansStatusWidget } from './BansStatusWidget';
+
+describe('BansStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<BansStatusWidget apiPrefix="/api/bans" />);
+
+    expect(screen.getByText(/User Bans Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalBans: 25,
+      activeBans: 15,
+      permanentBans: 8,
+      temporaryBans: 7,
+      recentBans: 5,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<BansStatusWidget apiPrefix="/api/bans" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('User Bans')).toBeInTheDocument();
+      expect(screen.getByText(/Total Bans: 25/)).toBeInTheDocument();
+      expect(screen.getByText(/Active: 15/)).toBeInTheDocument();
+      expect(screen.getByText(/Permanent: 8/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Bans: 5/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/bans/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Bans service error')
+    );
+
+    render(<BansStatusWidget apiPrefix="/api/bans" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Bans service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalBans: 10,
+      activeBans: 5,
+      permanentBans: 3,
+      temporaryBans: 2,
+      recentBans: 1,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<BansStatusWidget apiPrefix="/custom/bans" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/bans/stats');
+    });
+  });
+
+  it('displays all ban metrics correctly', async () => {
+    const mockStats = {
+      totalBans: 50,
+      activeBans: 30,
+      permanentBans: 20,
+      temporaryBans: 10,
+      recentBans: 8,
+      health: 'warning' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<BansStatusWidget apiPrefix="/api/bans" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total Bans: 50/)).toBeInTheDocument();
+      expect(screen.getByText(/Active: 30/)).toBeInTheDocument();
+      expect(screen.getByText(/Permanent: 20/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Bans: 8/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/bans/BansStatusWidget.tsx

@@ -0,0 +1,53 @@
+/**
+ * BansStatusWidget - Dashboard widget for user bans overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface BansStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/bans') */
+  apiPrefix?: string;
+}
+
+export function BansStatusWidget({ apiPrefix = '/api/bans' }: BansStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalBans: number;
+    activeBans: number;
+    permanentBans: number;
+    temporaryBans: number;
+    recentBans: number;
+    health: 'healthy' | 'warning' | 'error';
+  } | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch(`${apiPrefix}/stats`)
+      .then((res) => res.json())
+      .then((data) => {
+        setStats(data);
+        setLoading(false);
+      })
+      .catch((err) => {
+        setError(err.message);
+        setLoading(false);
+      });
+  }, [apiPrefix]);
+
+  return (
+    <PluginStatusWidget
+      title="User Bans"
+      stats={[
+        { label: 'Total Bans', value: stats?.totalBans ?? 0 },
+        { label: 'Active', value: stats?.activeBans ?? 0 },
+        { label: 'Permanent', value: stats?.permanentBans ?? 0 },
+        { label: 'Recent Bans', value: stats?.recentBans ?? 0, suffix: '/7d' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/bans"
+    />
+  );
+}

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

@@ -34,7 +34,7 @@ let pluginConfig: BansPluginConfig | null = null;
 export function createBansPlugin(config: BansPluginConfig): 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 || '/bans';
+  const apiPrefix = config.api?.prefix || '/'; // Framework adds /bans prefix automatically
   const apiEnabled = config.api?.enabled !== false;
 
   function log(message: string, data?: Record<string, unknown>) {

package/src/plugins/bans/index.ts

@@ -29,3 +29,9 @@ export type {
 
 // Stores
 export { postgresBanStore } from './stores/index.js';
+
+// UI Components
+export { BansStatusWidget } from './BansStatusWidget.js';
+export type { BansStatusWidgetProps } from './BansStatusWidget.js';
+export { BansManagementPage } from './BansManagementPage.js';
+export type { BansManagementPageProps } from './BansManagementPage.js';

package/src/plugins/cache/API_ROUTES.md

@@ -0,0 +1,312 @@
+# Redis Cache Plugin API Routes
+
+This document describes the API routes needed to support the CacheStatusWidget and CacheManagementPage UI components.
+
+## Routes to Add
+
+All routes should be registered in the `onGatewayReady` hook of the cache plugin.
+
+### 1. GET /api/plugins/cache/stats
+
+Returns current cache statistics and performance metrics.
+
+**Response:**
+```typescript
+{
+  connected: boolean;
+  keyCount: number;
+  usedMemory: string;      // e.g., "15.2 MB"
+  hitRate: number;         // Percentage (0-100)
+  missRate: number;        // Percentage (0-100)
+  opsPerSec: number;       // Operations per second
+  health: 'healthy' | 'warning' | 'error' | 'disabled';
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/cache/stats', async (req, res) => {
+  try {
+    const instance = getCache(instanceName);
+    const stats = await instance.getStats();
+    const client = instance.getClient();
+
+    // Get hit/miss stats from Redis INFO
+    const info = await client.info('stats');
+    const keyspaceHits = parseInt(info.match(/keyspace_hits:(\d+)/)?.[1] || '0');
+    const keyspaceMisses = parseInt(info.match(/keyspace_misses:(\d+)/)?.[1] || '0');
+    const total = keyspaceHits + keyspaceMisses;
+
+    res.json({
+      connected: stats.connected,
+      keyCount: stats.keyCount,
+      usedMemory: stats.usedMemory || '0 B',
+      hitRate: total > 0 ? (keyspaceHits / total) * 100 : 0,
+      missRate: total > 0 ? (keyspaceMisses / total) * 100 : 0,
+      opsPerSec: 0, // TODO: Calculate from instantaneous_ops_per_sec
+      health: stats.connected ? 'healthy' : 'error',
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+### 2. GET /api/plugins/cache/info
+
+Returns detailed cache information including performance metrics and uptime.
+
+**Response:**
+```typescript
+{
+  connected: boolean;
+  keyCount: number;
+  usedMemory: string;
+  hitRate: number;
+  missRate: number;
+  opsPerSec: number;
+  uptime: number;          // Uptime in seconds
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/cache/info', async (req, res) => {
+  try {
+    const instance = getCache(instanceName);
+    const client = instance.getClient();
+
+    const stats = await instance.getStats();
+    const info = await client.info();
+
+    const keyspaceHits = parseInt(info.match(/keyspace_hits:(\d+)/)?.[1] || '0');
+    const keyspaceMisses = parseInt(info.match(/keyspace_misses:(\d+)/)?.[1] || '0');
+    const total = keyspaceHits + keyspaceMisses;
+    const uptime = parseInt(info.match(/uptime_in_seconds:(\d+)/)?.[1] || '0');
+
+    res.json({
+      connected: stats.connected,
+      keyCount: stats.keyCount,
+      usedMemory: stats.usedMemory || '0 B',
+      hitRate: total > 0 ? (keyspaceHits / total) * 100 : 0,
+      missRate: total > 0 ? (keyspaceMisses / total) * 100 : 0,
+      opsPerSec: parseInt(info.match(/instantaneous_ops_per_sec:(\d+)/)?.[1] || '0'),
+      uptime,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+### 3. GET /api/plugins/cache/keys?pattern=*
+
+Returns list of cached keys matching a pattern with metadata.
+
+**Query Parameters:**
+- `pattern` - Glob pattern to match keys (default: '*')
+
+**Response:**
+```typescript
+Array<{
+  key: string;
+  type: string;           // "string", "list", "set", "zset", "hash"
+  ttl: number;            // TTL in seconds (-1 = no expiry, -2 = key not found)
+  size: number;           // Memory size in bytes
+}>
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/cache/keys', async (req, res) => {
+  try {
+    const instance = getCache(instanceName);
+    const client = instance.getClient();
+    const pattern = (req.query.pattern as string) || '*';
+
+    // Use SCAN instead of KEYS for better performance
+    const keys = await instance.scanKeys(pattern, { count: 100 });
+
+    // Get metadata for each key
+    const keysWithMeta = await Promise.all(
+      keys.slice(0, 100).map(async (key) => {
+        const [type, ttl, memory] = await Promise.all([
+          client.type(key),
+          instance.ttl(key),
+          client.memory('USAGE', key).catch(() => 0),
+        ]);
+
+        return {
+          key,
+          type,
+          ttl,
+          size: memory || 0,
+        };
+      })
+    );
+
+    res.json(keysWithMeta);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+### 4. GET /api/plugins/cache/keys/:key/value
+
+Returns the value for a specific key.
+
+**Response:**
+```typescript
+{
+  key: string;
+  type: string;
+  ttl: number;
+  value: string;          // JSON stringified value
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/cache/keys/:key/value', async (req, res) => {
+  try {
+    const instance = getCache(instanceName);
+    const client = instance.getClient();
+    const key = decodeURIComponent(req.params.key);
+
+    const [type, ttl, value] = await Promise.all([
+      client.type(key),
+      instance.ttl(key),
+      instance.getRaw(key),
+    ]);
+
+    res.json({
+      key,
+      type,
+      ttl,
+      value: value || null,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+### 5. DELETE /api/plugins/cache/keys/:key
+
+Deletes a specific key from cache.
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  message: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.delete('/api/plugins/cache/keys/:key', async (req, res) => {
+  try {
+    const instance = getCache(instanceName);
+    const key = decodeURIComponent(req.params.key);
+
+    const deleted = await instance.delete(key);
+    res.json({
+      success: deleted,
+      message: deleted ? 'Key deleted' : 'Key not found',
+    });
+  } catch (err) {
+    res.status(500).json({ success: false, message: err.message });
+  }
+});
+```
+
+### 6. POST /api/plugins/cache/flush
+
+Flushes all keys with the configured prefix.
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  keysDeleted: number;
+  message: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.post('/api/plugins/cache/flush', async (req, res) => {
+  try {
+    const instance = getCache(instanceName);
+    const keysDeleted = await instance.flush();
+
+    res.json({
+      success: true,
+      keysDeleted,
+      message: `Flushed ${keysDeleted} keys`,
+    });
+  } catch (err) {
+    res.status(500).json({
+      success: false,
+      keysDeleted: 0,
+      message: err.message,
+    });
+  }
+});
+```
+
+## Integration with Plugin
+
+These routes should be registered in the `onGatewayReady` hook:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Register all API routes
+  app.get('/api/plugins/cache/stats', ...);
+  app.get('/api/plugins/cache/info', ...);
+  app.get('/api/plugins/cache/keys', ...);
+  app.get('/api/plugins/cache/keys/:key/value', ...);
+  app.delete('/api/plugins/cache/keys/:key', ...);
+  app.post('/api/plugins/cache/flush', ...);
+}
+```
+
+## Widget Registration
+
+The plugin should also register its status widget and management page:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Register API routes (see above)
+
+  // Register control panel UI
+  registry.registerWidget({
+    id: 'cache-status',
+    title: 'Redis Cache',
+    component: 'CacheStatusWidget',
+    props: { apiPrefix: '/api/plugins/cache' },
+    order: 20,
+  });
+
+  registry.registerPage({
+    path: '/cpanel/plugins/cache',
+    title: 'Redis Cache',
+    component: 'CacheManagementPage',
+    props: { apiPrefix: '/api/plugins/cache' },
+  });
+}
+```
+
+## Performance Considerations
+
+1. **SCAN vs KEYS**: Always use `scanKeys()` instead of `keys()` to avoid blocking Redis on large datasets
+2. **Limit Results**: Limit key listings to 100-1000 items to prevent overwhelming the UI
+3. **Pagination**: Consider implementing cursor-based pagination for large key sets
+4. **Memory Usage**: Use `MEMORY USAGE` command carefully as it can be expensive on large values
+5. **Hit Rate Calculation**: Cache hit/miss stats come from Redis INFO command, which is relatively cheap
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.