@qwickapps/server 1.6.0 → 1.6.1

package/src/plugins/entitlements/EntitlementsManagementPage.tsx

@@ -0,0 +1,113 @@
+/**
+ * EntitlementsManagementPage - Full management interface for entitlements
+ */
+
+import React, { useState, useEffect } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, Column } from '@qwickapps/react-framework';
+
+export interface EntitlementsManagementPageProps {
+  /** API endpoint prefix (default: '/api/entitlements') */
+  apiPrefix?: string;
+}
+
+interface Entitlement {
+  id: string;
+  userId: string;
+  userEmail: string;
+  featureName: string;
+  status: 'active' | 'expired' | 'revoked';
+  grantedAt: string;
+  expiresAt?: string;
+  grantedBy?: string;
+}
+
+export function EntitlementsManagementPage({ apiPrefix = '/api/entitlements' }: EntitlementsManagementPageProps) {
+  const [activeTab, setActiveTab] = useState<'all' | 'active' | 'expired' | 'config'>('all');
+  const [entitlements, setEntitlements] = useState<Entitlement[]>([]);
+  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) => {
+        setEntitlements(data.entitlements || []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, [activeTab, apiPrefix]);
+
+  const columns: Column<Entitlement>[] = [
+    { key: 'userEmail', label: 'User', sortable: true },
+    { key: 'featureName', label: 'Feature', sortable: true },
+    {
+      key: 'status',
+      label: 'Status',
+      sortable: true,
+      render: (val) => (
+        <span
+          className={`px-2 py-1 rounded text-xs font-medium ${
+            val === 'active'
+              ? 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-100'
+              : val === 'expired'
+              ? 'bg-gray-100 dark:bg-gray-700 text-gray-800 dark:text-gray-300'
+              : 'bg-red-100 dark:bg-red-900 text-red-800 dark:text-red-100'
+          }`}
+        >
+          {String(val)}
+        </span>
+      ),
+    },
+    { key: 'grantedAt', label: 'Granted', sortable: true },
+    { key: 'expiresAt', label: 'Expires', sortable: true },
+    { key: 'grantedBy', label: 'Granted By' },
+  ];
+
+  const tabs = [
+    { id: 'all', label: 'All Entitlements' },
+    { id: 'active', label: 'Active' },
+    { id: 'expired', label: 'Expired' },
+    { id: 'config', label: 'Configuration' },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="Entitlements 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">
+              Feature definitions and entitlement rules configuration.
+            </p>
+          </div>
+        </div>
+      ) : (
+        <DataTable
+          columns={columns}
+          data={entitlements}
+          loading={loading}
+          emptyMessage="No entitlements found"
+          bulkActions={[
+            {
+              label: 'Grant Entitlement',
+              onClick: (rows) => console.log('Grant to:', rows),
+              variant: 'primary',
+            },
+            {
+              label: 'Revoke Selected',
+              onClick: (rows) => console.log('Revoke:', rows),
+              variant: 'danger',
+            },
+          ]}
+        />
+      )}
+    </PluginManagementPage>
+  );
+}

package/src/plugins/entitlements/EntitlementsStatusWidget.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * EntitlementsStatusWidget 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 { EntitlementsStatusWidget } from './EntitlementsStatusWidget';
+
+describe('EntitlementsStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<EntitlementsStatusWidget apiPrefix="/api/entitlements" />);
+
+    expect(screen.getByText(/Entitlements Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalEntitlements: 250,
+      activeEntitlements: 200,
+      expiredEntitlements: 50,
+      recentGrants: 30,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<EntitlementsStatusWidget apiPrefix="/api/entitlements" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Entitlements')).toBeInTheDocument();
+      expect(screen.getByText(/Total Entitlements: 250/)).toBeInTheDocument();
+      expect(screen.getByText(/Active: 200/)).toBeInTheDocument();
+      expect(screen.getByText(/Expired: 50/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Grants: 30/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/entitlements/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Entitlements service error')
+    );
+
+    render(<EntitlementsStatusWidget apiPrefix="/api/entitlements" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Entitlements service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalEntitlements: 100,
+      activeEntitlements: 80,
+      expiredEntitlements: 20,
+      recentGrants: 15,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<EntitlementsStatusWidget apiPrefix="/custom/entitlements" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/entitlements/stats');
+    });
+  });
+
+  it('displays all entitlement metrics correctly', async () => {
+    const mockStats = {
+      totalEntitlements: 500,
+      activeEntitlements: 400,
+      expiredEntitlements: 100,
+      recentGrants: 60,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<EntitlementsStatusWidget apiPrefix="/api/entitlements" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total Entitlements: 500/)).toBeInTheDocument();
+      expect(screen.getByText(/Active: 400/)).toBeInTheDocument();
+      expect(screen.getByText(/Expired: 100/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Grants: 60/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/entitlements/EntitlementsStatusWidget.tsx

@@ -0,0 +1,52 @@
+/**
+ * EntitlementsStatusWidget - Dashboard widget for entitlements overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface EntitlementsStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/entitlements') */
+  apiPrefix?: string;
+}
+
+export function EntitlementsStatusWidget({ apiPrefix = '/api/entitlements' }: EntitlementsStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalEntitlements: number;
+    activeEntitlements: number;
+    expiredEntitlements: number;
+    recentGrants: 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="Entitlements"
+      stats={[
+        { label: 'Total Entitlements', value: stats?.totalEntitlements ?? 0 },
+        { label: 'Active', value: stats?.activeEntitlements ?? 0 },
+        { label: 'Expired', value: stats?.expiredEntitlements ?? 0 },
+        { label: 'Recent Grants', value: stats?.recentGrants ?? 0, suffix: '/7d' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/entitlements"
+    />
+  );
+}

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

@@ -40,7 +40,7 @@ let cacheVersion = 1;
 export function createEntitlementsPlugin(config: EntitlementsPluginConfig): 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 || '/entitlements';
+  const apiPrefix = config.api?.prefix || ''; // Framework adds /entitlements prefix automatically (empty string to avoid double slash)
   const apiEnabled = config.api?.enabled !== false;
   const enableWriteApi = config.api?.enableWrite !== false;
 

package/src/plugins/entitlements/index.ts

@@ -49,3 +49,9 @@ export type {
   CachedEntitlements,
   EntitlementStats,
 } from './types.js';
+
+// UI Components
+export { EntitlementsStatusWidget } from './EntitlementsStatusWidget.js';
+export type { EntitlementsStatusWidgetProps } from './EntitlementsStatusWidget.js';
+export { EntitlementsManagementPage } from './EntitlementsManagementPage.js';
+export type { EntitlementsManagementPageProps } from './EntitlementsManagementPage.js';

package/src/plugins/health/API_ROUTES.md

@@ -0,0 +1,283 @@
+# Health Check Plugin API Routes
+
+This document describes the API routes needed to support the HealthStatusWidget and HealthManagementPage UI components.
+
+## Routes to Add
+
+All routes should be registered in the `onGatewayReady` hook of the health plugin.
+
+### 1. GET /api/plugins/health/summary
+
+Returns aggregated health status across all registered health checks.
+
+**Response:**
+```typescript
+{
+  overall: 'healthy' | 'degraded' | 'unhealthy';
+  totalChecks: number;
+  healthyChecks: number;
+  unhealthyChecks: number;
+  degradedChecks: number;
+  checks: Array<{
+    name: string;
+    type: string;           // "http", "tcp", "custom"
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    latency?: number;       // Response time in ms
+    message?: string;
+    lastChecked: string;    // ISO 8601 timestamp
+    details?: Record<string, unknown>;
+  }>;
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/health/summary', async (req, res) => {
+  const healthManager = registry.getHealthManager();
+  const results = await healthManager.checkAll();
+
+  const checks = results.map((result) => ({
+    name: result.name,
+    type: result.type,
+    status: result.status,
+    latency: result.latency,
+    message: result.message,
+    lastChecked: result.lastChecked.toISOString(),
+    details: result.details,
+  }));
+
+  const healthyCount = checks.filter((c) => c.status === 'healthy').length;
+  const degradedCount = checks.filter((c) => c.status === 'degraded').length;
+  const unhealthyCount = checks.filter((c) => c.status === 'unhealthy').length;
+
+  const overall =
+    unhealthyCount > 0 ? 'unhealthy' :
+    degradedCount > 0 ? 'degraded' : 'healthy';
+
+  res.json({
+    overall,
+    totalChecks: checks.length,
+    healthyChecks: healthyCount,
+    unhealthyChecks: unhealthyCount,
+    degradedChecks: degradedCount,
+    checks,
+  });
+});
+```
+
+### 2. GET /api/plugins/health/checks/:name
+
+Returns detailed status for a specific health check.
+
+**Response:**
+```typescript
+{
+  name: string;
+  type: string;
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  latency?: number;
+  message?: string;
+  lastChecked: string;
+  details?: Record<string, unknown>;
+  history?: Array<{
+    timestamp: string;
+    status: string;
+    latency?: number;
+  }>;
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/health/checks/:name', async (req, res) => {
+  const healthManager = registry.getHealthManager();
+  const checkName = req.params.name;
+
+  const result = await healthManager.check(checkName);
+
+  if (!result) {
+    return res.status(404).json({ error: 'Health check not found' });
+  }
+
+  res.json({
+    name: result.name,
+    type: result.type,
+    status: result.status,
+    latency: result.latency,
+    message: result.message,
+    lastChecked: result.lastChecked.toISOString(),
+    details: result.details,
+    // TODO: Implement history tracking
+    history: [],
+  });
+});
+```
+
+### 3. POST /api/plugins/health/checks/:name/run
+
+Triggers an immediate health check for a specific check (useful for testing).
+
+**Response:**
+```typescript
+{
+  name: string;
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  latency?: number;
+  message?: string;
+  timestamp: string;
+}
+```
+
+**Implementation:**
+```typescript
+app.post('/api/plugins/health/checks/:name/run', async (req, res) => {
+  const healthManager = registry.getHealthManager();
+  const checkName = req.params.name;
+
+  try {
+    const result = await healthManager.runCheck(checkName);
+
+    res.json({
+      name: result.name,
+      status: result.status,
+      latency: result.latency,
+      message: result.message,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+```
+
+### 4. GET /api/plugins/health/aggregate
+
+Returns aggregate health across all services (standard health endpoint format).
+
+**Response:**
+```typescript
+{
+  status: 'pass' | 'warn' | 'fail';
+  version: string;
+  releaseId: string;
+  checks: {
+    [name: string]: [{
+      status: 'pass' | 'warn' | 'fail';
+      time: string;
+      output?: string;
+    }]
+  };
+}
+```
+
+**Implementation:**
+```typescript
+app.get('/api/plugins/health/aggregate', async (req, res) => {
+  const healthManager = registry.getHealthManager();
+  const results = await healthManager.checkAll();
+
+  const checks: Record<string, any[]> = {};
+
+  for (const result of results) {
+    checks[result.name] = [{
+      status:
+        result.status === 'healthy' ? 'pass' :
+        result.status === 'degraded' ? 'warn' : 'fail',
+      time: result.lastChecked.toISOString(),
+      output: result.message,
+    }];
+  }
+
+  const hasFailed = results.some((r) => r.status === 'unhealthy');
+  const hasDegraded = results.some((r) => r.status === 'degraded');
+
+  res.json({
+    status: hasFailed ? 'fail' : hasDegraded ? 'warn' : 'pass',
+    version: '1.0.0',
+    releaseId: process.env.RELEASE_ID || 'unknown',
+    checks,
+  });
+});
+```
+
+## Health Status Mapping
+
+The plugin should map health check results to standardized statuses:
+
+| Internal Status | API Status | Description |
+|----------------|------------|-------------|
+| `healthy: true` | `healthy` | Service operating normally |
+| `healthy: false` | `unhealthy` | Service is down or failing |
+| `latency > threshold` | `degraded` | Service is slow but functional |
+
+**Degraded Thresholds:**
+- HTTP checks: latency > 1000ms
+- TCP checks: latency > 500ms
+- Custom checks: up to implementation
+
+## 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/health/summary', ...);
+  app.get('/api/plugins/health/checks/:name', ...);
+  app.post('/api/plugins/health/checks/:name/run', ...);
+  app.get('/api/plugins/health/aggregate', ...);
+}
+```
+
+## 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: 'health-status',
+    title: 'Service Health',
+    component: 'HealthStatusWidget',
+    props: { apiPrefix: '/api/plugins/health' },
+    order: 5,
+  });
+
+  registry.registerPage({
+    path: '/cpanel/plugins/health',
+    title: 'Service Health',
+    component: 'HealthManagementPage',
+    props: { apiPrefix: '/api/plugins/health' },
+  });
+}
+```
+
+## Health Check History (Future Enhancement)
+
+To implement health check history:
+
+1. Store last N check results in memory or database
+2. Track status changes and timestamps
+3. Calculate uptime percentage
+4. Detect patterns (flapping, gradual degradation)
+
+Example structure:
+```typescript
+interface HealthCheckHistory {
+  checkName: string;
+  results: Array<{
+    timestamp: Date;
+    status: string;
+    latency?: number;
+  }>;
+  uptime: number;          // Percentage
+  mtbf: number;            // Mean time between failures (seconds)
+}
+```
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/health/HealthManagementPage.test.tsx

@@ -0,0 +1,57 @@
+/**
+ * HealthManagementPage 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 { HealthManagementPage } from './HealthManagementPage';
+
+describe('HealthManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<HealthManagementPage apiPrefix="/api/health" />);
+
+    expect(screen.getByText('Health Checks Management')).toBeInTheDocument();
+  });
+
+  it('fetches health checks on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<HealthManagementPage apiPrefix="/api/health" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/api/health/checks');
+    });
+  });
+
+  it('renders all tabs', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<HealthManagementPage apiPrefix="/api/health" />);
+
+    expect(screen.getByRole('tab', { name: /All Checks/i })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /Unhealthy/i })).toBeInTheDocument();
+  });
+});