@qwickapps/server 1.5.2 → 1.6.1

package/src/plugins/usage/UsageManagementPage.tsx

@@ -0,0 +1,93 @@
+/**
+ * UsageManagementPage - Full management interface for usage tracking
+ */
+
+import React, { useState, useEffect } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, Column } from '@qwickapps/react-framework';
+
+export interface UsageManagementPageProps {
+  /** API endpoint prefix (default: '/api/usage') */
+  apiPrefix?: string;
+}
+
+interface UsageEvent {
+  id: string;
+  userId: string;
+  userEmail: string;
+  eventType: string;
+  featureName: string;
+  timestamp: string;
+  metadata?: Record<string, unknown>;
+}
+
+export function UsageManagementPage({ apiPrefix = '/api/usage' }: UsageManagementPageProps) {
+  const [activeTab, setActiveTab] = useState<'recent' | 'features' | 'users' | 'config'>('recent');
+  const [events, setEvents] = useState<UsageEvent[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (activeTab === 'recent') {
+      fetch(`${apiPrefix}/events?limit=100`)
+        .then((res) => res.json())
+        .then((data) => {
+          setEvents(data.events || []);
+          setLoading(false);
+        })
+        .catch(() => setLoading(false));
+    }
+  }, [activeTab, apiPrefix]);
+
+  const columns: Column<UsageEvent>[] = [
+    { key: 'timestamp', label: 'Time', sortable: true },
+    { key: 'userEmail', label: 'User', sortable: true },
+    { key: 'eventType', label: 'Event Type', sortable: true },
+    { key: 'featureName', label: 'Feature', sortable: true },
+    {
+      key: 'metadata',
+      label: 'Details',
+      render: (val) => (
+        <code className="text-xs bg-gray-100 dark:bg-gray-800 px-2 py-1 rounded">
+          {val ? JSON.stringify(val).substring(0, 50) + '...' : '-'}
+        </code>
+      ),
+    },
+  ];
+
+  const tabs = [
+    { id: 'recent', label: 'Recent Events' },
+    { id: 'features', label: 'By Feature' },
+    { id: 'users', label: 'By User' },
+    { id: 'config', label: 'Configuration' },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="Usage Tracking"
+      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">
+              Usage tracking configuration and data retention policies.
+            </p>
+          </div>
+        </div>
+      ) : activeTab === 'recent' ? (
+        <DataTable
+          columns={columns}
+          data={events}
+          loading={loading}
+          emptyMessage="No usage events found"
+        />
+      ) : (
+        <div className="p-8 text-center text-gray-500 dark:text-gray-400">
+          {activeTab === 'features' ? 'Feature usage analytics' : 'User usage analytics'}
+        </div>
+      )}
+    </PluginManagementPage>
+  );
+}

package/src/plugins/usage/UsageStatusWidget.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * UsageStatusWidget 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 { UsageStatusWidget } from './UsageStatusWidget';
+
+describe('UsageStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<UsageStatusWidget apiPrefix="/api/usage" />);
+
+    expect(screen.getByText(/Usage Tracking Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalEvents: 10000,
+      activeUsers: 500,
+      eventsToday: 1200,
+      topFeature: 'Login',
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<UsageStatusWidget apiPrefix="/api/usage" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Usage Tracking')).toBeInTheDocument();
+      expect(screen.getByText(/Total Events: 10000/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Users: 500/)).toBeInTheDocument();
+      expect(screen.getByText(/Events Today: 1200/)).toBeInTheDocument();
+      expect(screen.getByText(/Top Feature: Login/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/usage/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Usage service error')
+    );
+
+    render(<UsageStatusWidget apiPrefix="/api/usage" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Usage service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalEvents: 5000,
+      activeUsers: 250,
+      eventsToday: 600,
+      topFeature: 'Search',
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<UsageStatusWidget apiPrefix="/custom/usage" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/usage/stats');
+    });
+  });
+
+  it('displays all usage metrics correctly', async () => {
+    const mockStats = {
+      totalEvents: 50000,
+      activeUsers: 2000,
+      eventsToday: 5000,
+      topFeature: 'Dashboard',
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<UsageStatusWidget apiPrefix="/api/usage" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total Events: 50000/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Users: 2000/)).toBeInTheDocument();
+      expect(screen.getByText(/Events Today: 5000/)).toBeInTheDocument();
+      expect(screen.getByText(/Top Feature: Dashboard/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/usage/UsageStatusWidget.tsx

@@ -0,0 +1,52 @@
+/**
+ * UsageStatusWidget - Dashboard widget for usage tracking overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface UsageStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/usage') */
+  apiPrefix?: string;
+}
+
+export function UsageStatusWidget({ apiPrefix = '/api/usage' }: UsageStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalEvents: number;
+    activeUsers: number;
+    eventsToday: number;
+    topFeature: string;
+    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="Usage Tracking"
+      stats={[
+        { label: 'Total Events', value: stats?.totalEvents ?? 0 },
+        { label: 'Active Users', value: stats?.activeUsers ?? 0 },
+        { label: 'Events Today', value: stats?.eventsToday ?? 0 },
+        { label: 'Top Feature', value: stats?.topFeature ?? 'N/A' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/usage"
+    />
+  );
+}

package/src/plugins/usage/index.ts

@@ -37,3 +37,9 @@ export type {
 
 // Stores
 export { postgresUsageStore } from './stores/index.js';
+
+// UI Components
+export { UsageStatusWidget } from './UsageStatusWidget.js';
+export type { UsageStatusWidgetProps } from './UsageStatusWidget.js';
+export { UsageManagementPage } from './UsageManagementPage.js';
+export type { UsageManagementPageProps } from './UsageManagementPage.js';

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

@@ -48,7 +48,7 @@ function getTomorrowMidnight(): Date {
  */
 export function createUsagePlugin(config: UsagePluginConfig): Plugin {
   const debug = config.debug || false;
-  const apiPrefix = config.api?.prefix || '/usage';
+  const apiPrefix = config.api?.prefix || '/'; // Framework adds /usage prefix automatically
 
   function log(message: string, data?: Record<string, unknown>) {
     if (debug) {

package/src/plugins/users/API_ROUTES.md

@@ -0,0 +1,311 @@
+# Users Plugin API Routes
+
+This document describes the API routes needed to support the UsersStatusWidget and UsersManagementPage UI components.
+
+## Routes to Implement
+
+The users plugin should expose these API routes for the UI components.
+
+### 1. GET /api/users/stats
+
+Returns user statistics for the status widget.
+
+**Response:**
+```typescript
+{
+  totalUsers: number;
+  activeUsers: number;
+  invitedUsers: number;
+  suspendedUsers: number;
+  recentSignups: number;  // Last 7 days
+  health: 'healthy' | 'warning' | 'error';
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/users/stats', async (req, res) => {
+  const stats = await usersPlugin.getStats();
+  res.json(stats);
+});
+```
+
+### 2. GET /api/users
+
+Returns paginated list of users with optional filtering.
+
+**Query Parameters:**
+- `limit` - Max users to return (default: 100, max: 1000)
+- `offset` - Pagination offset (default: 0)
+- `q` - Search query (searches email and name)
+- `status` - Filter by status ('invited', 'active', 'suspended')
+- `provider` - Filter by auth provider
+
+**Response:**
+```typescript
+{
+  users: Array<{
+    id: string;
+    email: string;
+    name?: string;
+    provider?: string;
+    status: 'invited' | 'active' | 'suspended';
+    created_at: string;
+    last_login_at?: string;
+    picture?: string;
+  }>;
+  total: number;
+  limit: number;
+  offset: number;
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/users', async (req, res) => {
+  const { limit = 100, offset = 0, q, status, provider } = req.query;
+
+  const users = await usersPlugin.listUsers({
+    limit: Math.min(parseInt(limit as string), 1000),
+    offset: parseInt(offset as string),
+    search: q as string,
+    status: status as UserStatus,
+    provider: provider as string,
+  });
+
+  res.json(users);
+});
+```
+
+### 3. GET /api/users/:id
+
+Returns detailed information for a specific user.
+
+**Response:**
+```typescript
+{
+  id: string;
+  email: string;
+  name?: string;
+  provider?: string;
+  status: 'invited' | 'active' | 'suspended';
+  created_at: string;
+  updated_at: string;
+  last_login_at?: string;
+  picture?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/users/:id', async (req, res) => {
+  const user = await usersPlugin.getUser(req.params.id);
+
+  if (!user) {
+    return res.status(404).json({ error: 'User not found' });
+  }
+
+  res.json(user);
+});
+```
+
+### 4. POST /api/users
+
+Creates a new user (invite).
+
+**Request Body:**
+```typescript
+{
+  email: string;
+  name?: string;
+  status?: 'invited' | 'active';
+  metadata?: Record<string, unknown>;
+}
+```
+
+**Response:**
+```typescript
+{
+  id: string;
+  email: string;
+  name?: string;
+  status: 'invited' | 'active';
+  created_at: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.post('/api/users', async (req, res) => {
+  const { email, name, status = 'invited', metadata } = req.body;
+
+  if (!email) {
+    return res.status(400).json({ error: 'Email is required' });
+  }
+
+  const user = await usersPlugin.createUser({
+    email,
+    name,
+    status,
+    metadata,
+  });
+
+  res.status(201).json(user);
+});
+```
+
+### 5. PATCH /api/users/:id
+
+Updates user information or status.
+
+**Request Body:**
+```typescript
+{
+  name?: string;
+  status?: 'invited' | 'active' | 'suspended';
+  metadata?: Record<string, unknown>;
+}
+```
+
+**Response:**
+```typescript
+{
+  id: string;
+  email: string;
+  name?: string;
+  status: 'invited' | 'active' | 'suspended';
+  updated_at: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.patch('/api/users/:id', async (req, res) => {
+  const { name, status, metadata } = req.body;
+
+  const user = await usersPlugin.updateUser(req.params.id, {
+    name,
+    status,
+    metadata,
+  });
+
+  if (!user) {
+    return res.status(404).json({ error: 'User not found' });
+  }
+
+  res.json(user);
+});
+```
+
+### 6. DELETE /api/users/:id
+
+Deletes a user account.
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  message: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.delete('/api/users/:id', async (req, res) => {
+  const deleted = await usersPlugin.deleteUser(req.params.id);
+
+  if (!deleted) {
+    return res.status(404).json({ error: 'User not found' });
+  }
+
+  res.json({ success: true, message: 'User deleted' });
+});
+```
+
+## Integration with Plugin
+
+These routes should be registered in the users plugin's `onGatewayReady` hook:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Stats endpoint
+  app.get('/api/users/stats', async (req, res) => {
+    const stats = await this.getStats();
+    res.json(stats);
+  });
+
+  // List users
+  app.get('/api/users', async (req, res) => {
+    // Implementation
+  });
+
+  // Get user
+  app.get('/api/users/:id', async (req, res) => {
+    // Implementation
+  });
+
+  // Create user
+  app.post('/api/users', async (req, res) => {
+    // Implementation
+  });
+
+  // Update user
+  app.patch('/api/users/:id', async (req, res) => {
+    // Implementation
+  });
+
+  // Delete user
+  app.delete('/api/users/:id', async (req, res) => {
+    // Implementation
+  });
+}
+```
+
+## Widget Registration
+
+The plugin should also register its UI components:
+
+```typescript
+async onGatewayReady(app: Express): Promise<void> {
+  // Register API routes (see above)
+
+  // Register control panel UI
+  registry.registerWidget({
+    id: 'users-status',
+    title: 'User Management',
+    component: 'UsersStatusWidget',
+    props: { apiPrefix: '/api/users' },
+    order: 20,
+  });
+
+  registry.registerPage({
+    path: '/cpanel/plugins/users',
+    title: 'User Management',
+    component: 'UsersManagementPage',
+    props: { apiPrefix: '/api/users' },
+  });
+}
+```
+
+## Security Considerations
+
+1. **Authentication**: All user management endpoints require authentication
+2. **Authorization**: Only admin users should access user management
+3. **Rate Limiting**: Apply rate limits to prevent abuse
+4. **Input Validation**: Validate all email addresses and user data
+5. **Audit Logging**: Log all user management actions
+6. **PII Protection**: Handle user data according to privacy regulations
+7. **Deletion**: Implement soft delete or hard delete based on requirements
+
+## Performance Considerations
+
+1. **Pagination**: Always paginate user lists to avoid loading large datasets
+2. **Indexing**: Index frequently queried fields (email, status, created_at)
+3. **Caching**: Cache user statistics for the status widget
+4. **Search**: Use database full-text search for better performance
+5. **Bulk Operations**: Implement bulk suspend/activate for efficiency
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/users/UsersManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * UsersManagementPage 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 { UsersManagementPage } from './UsersManagementPage';
+
+describe('UsersManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<UsersManagementPage apiPrefix="/api/users" />);
+
+    expect(screen.getByText('User Management')).toBeInTheDocument();
+  });
+
+  it('fetches users and stats on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<UsersManagementPage apiPrefix="/api/users" />);
+
+    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(<UsersManagementPage apiPrefix="/custom/users" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+});