@qwickapps/server 1.6.0 → 1.7.0

package/src/plugins/preferences/PreferencesStatusWidget.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * PreferencesStatusWidget 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 { PreferencesStatusWidget } from './PreferencesStatusWidget';
+
+describe('PreferencesStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<PreferencesStatusWidget apiPrefix="/api/preferences" />);
+
+    expect(screen.getByText(/User Preferences Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalPreferences: 500,
+      activeUsers: 150,
+      preferenceSets: 25,
+      recentUpdates: 40,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<PreferencesStatusWidget apiPrefix="/api/preferences" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('User Preferences')).toBeInTheDocument();
+      expect(screen.getByText(/Preference Sets: 25/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Users: 150/)).toBeInTheDocument();
+      expect(screen.getByText(/Total Prefs: 500/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Updates: 40/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/preferences/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Preferences service error')
+    );
+
+    render(<PreferencesStatusWidget apiPrefix="/api/preferences" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Preferences service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalPreferences: 200,
+      activeUsers: 80,
+      preferenceSets: 15,
+      recentUpdates: 20,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<PreferencesStatusWidget apiPrefix="/custom/preferences" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/preferences/stats');
+    });
+  });
+
+  it('displays all preference metrics correctly', async () => {
+    const mockStats = {
+      totalPreferences: 1000,
+      activeUsers: 300,
+      preferenceSets: 50,
+      recentUpdates: 100,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<PreferencesStatusWidget apiPrefix="/api/preferences" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Preference Sets: 50/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Users: 300/)).toBeInTheDocument();
+      expect(screen.getByText(/Total Prefs: 1000/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Updates: 100/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/preferences/PreferencesStatusWidget.tsx

@@ -0,0 +1,52 @@
+/**
+ * PreferencesStatusWidget - Dashboard widget for user preferences overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface PreferencesStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/preferences') */
+  apiPrefix?: string;
+}
+
+export function PreferencesStatusWidget({ apiPrefix = '/api/preferences' }: PreferencesStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalPreferences: number;
+    activeUsers: number;
+    preferenceSets: number;
+    recentUpdates: 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 Preferences"
+      stats={[
+        { label: 'Preference Sets', value: stats?.preferenceSets ?? 0 },
+        { label: 'Active Users', value: stats?.activeUsers ?? 0 },
+        { label: 'Total Prefs', value: stats?.totalPreferences ?? 0 },
+        { label: 'Recent Updates', value: stats?.recentUpdates ?? 0, suffix: '/7d' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/preferences"
+    />
+  );
+}

package/src/plugins/preferences/index.ts

@@ -28,3 +28,9 @@ export type {
 
 // Stores
 export { postgresPreferencesStore, deepMerge } from './stores/index.js';
+
+// UI Components
+export { PreferencesStatusWidget } from './PreferencesStatusWidget.js';
+export type { PreferencesStatusWidgetProps } from './PreferencesStatusWidget.js';
+export { PreferencesManagementPage } from './PreferencesManagementPage.js';
+export type { PreferencesManagementPageProps } from './PreferencesManagementPage.js';

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

@@ -17,10 +17,7 @@ import type {
 } from './types.js';
 import type { AuthenticatedRequest } from '../auth/types.js';
 import { deepMerge } from './stores/postgres-store.js';
-
-// Configuration limits
-const MAX_PREFERENCES_SIZE = 100_000; // 100KB JSON string limit
-const MAX_NESTING_DEPTH = 10;
+import { MAX_PREFERENCES_SIZE, MAX_NESTING_DEPTH } from './types.js';
 
 /**
  * Check if an object exceeds maximum nesting depth
@@ -46,7 +43,7 @@ let pluginDefaults: Record<string, unknown> = {};
 export function createPreferencesPlugin(config: PreferencesPluginConfig): 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 || '/preferences';
+  const apiPrefix = config.api?.prefix || '/'; // Framework adds /preferences prefix automatically
   const apiEnabled = config.api?.enabled !== false;
 
   function log(message: string, data?: Record<string, unknown>) {
@@ -198,6 +195,14 @@ export function createPreferencesPlugin(config: PreferencesPluginConfig): Plugin
         });
       }
 
+      // Register preferences page in UI
+      registry.addPage({
+        pluginId: 'preferences',
+        id: 'preferences:page',
+        route: '/preferences',
+        component: 'PreferencesPage',
+      });
+
       log('Preferences plugin started');
     },
 

package/src/plugins/preferences/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Preferences Plugin Types
+ *
+ * Type definitions for user preferences management.
+ * Supports PostgreSQL with Row-Level Security (RLS) for data isolation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+/**
+ * Configuration limits for preferences
+ */
+export declare const MAX_PREFERENCES_SIZE = 100000;
+export declare const MAX_NESTING_DEPTH = 10;
+/**
+ * User preferences record in the database
+ */
+export interface UserPreferences {
+    /** Primary key - UUID */
+    id: string;
+    /** User ID (foreign key to users table) */
+    user_id: string;
+    /** Preferences as JSON object */
+    preferences: Record<string, unknown>;
+    /** When the preferences were created */
+    created_at: Date;
+    /** When the preferences were last updated */
+    updated_at: Date;
+}
+/**
+ * Preferences store interface - all storage backends must implement this
+ */
+export interface PreferencesStore {
+    /** Store name (e.g., 'postgres', 'memory') */
+    name: string;
+    /**
+     * Initialize the store (create tables, RLS policies, etc.)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get preferences for a user
+     * Returns null if no preferences exist for the user
+     */
+    get(userId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Update preferences for a user (upsert with deep merge)
+     * Returns the merged preferences
+     */
+    update(userId: string, preferences: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Delete preferences for a user
+     * Returns true if preferences were deleted, false if none existed
+     */
+    delete(userId: string): Promise<boolean>;
+    /**
+     * Shutdown the store
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * PostgreSQL preferences store configuration
+ */
+export interface PostgresPreferencesStoreConfig {
+    /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+    pool: unknown | (() => unknown);
+    /** Table name (default: 'user_preferences') */
+    tableName?: string;
+    /** Schema name (default: 'public') */
+    schema?: string;
+    /** Auto-create tables on init (default: true) */
+    autoCreateTables?: boolean;
+    /** Enable RLS (default: true) */
+    enableRLS?: boolean;
+}
+/**
+ * Preferences API configuration
+ */
+export interface PreferencesApiConfig {
+    /** API route prefix (default: '/preferences') */
+    prefix?: string;
+    /** Enable API endpoints (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Preferences plugin configuration
+ */
+export interface PreferencesPluginConfig {
+    /** Preferences storage backend */
+    store: PreferencesStore;
+    /** Default preferences to merge with stored preferences on read */
+    defaults?: Record<string, unknown>;
+    /** API configuration */
+    api?: PreferencesApiConfig;
+    /** Enable debug logging */
+    debug?: boolean;
+}

package/src/plugins/preferences/types.ts

@@ -7,6 +7,12 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
+/**
+ * Configuration limits for preferences
+ */
+export const MAX_PREFERENCES_SIZE = 100_000; // 100KB JSON string limit
+export const MAX_NESTING_DEPTH = 10;
+
 /**
  * User preferences record in the database
  */

package/src/plugins/profiles/API_ROUTES.md

@@ -0,0 +1,27 @@
+# Profiles Plugin API Routes
+
+## Routes
+
+### GET /api/profiles/stats
+Returns profile statistics for the status widget.
+
+**Response:** `{ totalProfiles, completeProfiles, incompleteProfiles, recentUpdates, health }`
+
+### GET /api/profiles
+Returns paginated list of user profiles with optional filtering.
+
+**Query:** `limit, offset, status`
+
+**Response:** `{ profiles: Array<{ id, userId, userEmail, displayName, avatarUrl, completionStatus, updatedAt, createdAt }>, total }`
+
+### GET /api/profiles/:id
+Returns detailed profile information.
+
+### PATCH /api/profiles/:id
+Update profile information.
+
+### DELETE /api/profiles/:id
+Delete a profile.
+
+---
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/profiles/ProfilesManagementPage.test.tsx

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

package/src/plugins/profiles/ProfilesManagementPage.tsx

@@ -0,0 +1,113 @@
+/**
+ * ProfilesManagementPage - Full management interface for user profiles
+ */
+
+import React, { useState, useEffect } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, Column } from '@qwickapps/react-framework';
+
+export interface ProfilesManagementPageProps {
+  /** API endpoint prefix (default: '/api/profiles') */
+  apiPrefix?: string;
+}
+
+interface Profile {
+  id: string;
+  userId: string;
+  userEmail: string;
+  displayName?: string;
+  avatarUrl?: string;
+  completionStatus: 'complete' | 'incomplete';
+  updatedAt: string;
+  createdAt: string;
+}
+
+export function ProfilesManagementPage({ apiPrefix = '/api/profiles' }: ProfilesManagementPageProps) {
+  const [activeTab, setActiveTab] = useState<'all' | 'complete' | 'incomplete' | 'config'>('all');
+  const [profiles, setProfiles] = useState<Profile[]>([]);
+  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) => {
+        setProfiles(data.profiles || []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, [activeTab, apiPrefix]);
+
+  const columns: Column<Profile>[] = [
+    {
+      key: 'avatarUrl',
+      label: '',
+      width: '60px',
+      render: (val) =>
+        val ? (
+          <img
+            src={String(val)}
+            alt="Avatar"
+            className="w-8 h-8 rounded-full"
+          />
+        ) : (
+          <div className="w-8 h-8 rounded-full bg-gray-300 dark:bg-gray-600"></div>
+        ),
+    },
+    { key: 'displayName', label: 'Name', sortable: true },
+    { key: 'userEmail', label: 'Email', sortable: true },
+    {
+      key: 'completionStatus',
+      label: 'Status',
+      sortable: true,
+      render: (val) => (
+        <span
+          className={`px-2 py-1 rounded text-xs font-medium ${
+            val === 'complete'
+              ? 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-100'
+              : 'bg-yellow-100 dark:bg-yellow-900 text-yellow-800 dark:text-yellow-100'
+          }`}
+        >
+          {String(val)}
+        </span>
+      ),
+    },
+    { key: 'updatedAt', label: 'Last Updated', sortable: true },
+    { key: 'createdAt', label: 'Created', sortable: true },
+  ];
+
+  const tabs = [
+    { id: 'all', label: 'All Profiles' },
+    { id: 'complete', label: 'Complete' },
+    { id: 'incomplete', label: 'Incomplete' },
+    { id: 'config', label: 'Configuration' },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="Profiles 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">
+              Profile schema and required fields configuration.
+            </p>
+          </div>
+        </div>
+      ) : (
+        <DataTable
+          columns={columns}
+          data={profiles}
+          loading={loading}
+          emptyMessage="No profiles found"
+        />
+      )}
+    </PluginManagementPage>
+  );
+}

package/src/plugins/profiles/ProfilesStatusWidget.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * ProfilesStatusWidget 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 { ProfilesStatusWidget } from './ProfilesStatusWidget';
+
+describe('ProfilesStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<ProfilesStatusWidget apiPrefix="/api/profiles" />);
+
+    expect(screen.getByText(/User Profiles Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalProfiles: 150,
+      completeProfiles: 120,
+      incompleteProfiles: 30,
+      recentUpdates: 25,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<ProfilesStatusWidget apiPrefix="/api/profiles" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('User Profiles')).toBeInTheDocument();
+      expect(screen.getByText(/Total Profiles: 150/)).toBeInTheDocument();
+      expect(screen.getByText(/Complete: 120/)).toBeInTheDocument();
+      expect(screen.getByText(/Incomplete: 30/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Updates: 25/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/profiles/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Profiles service error')
+    );
+
+    render(<ProfilesStatusWidget apiPrefix="/api/profiles" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Profiles service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalProfiles: 80,
+      completeProfiles: 60,
+      incompleteProfiles: 20,
+      recentUpdates: 10,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<ProfilesStatusWidget apiPrefix="/custom/profiles" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/profiles/stats');
+    });
+  });
+
+  it('displays all profile metrics correctly', async () => {
+    const mockStats = {
+      totalProfiles: 300,
+      completeProfiles: 250,
+      incompleteProfiles: 50,
+      recentUpdates: 45,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<ProfilesStatusWidget apiPrefix="/api/profiles" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total Profiles: 300/)).toBeInTheDocument();
+      expect(screen.getByText(/Complete: 250/)).toBeInTheDocument();
+      expect(screen.getByText(/Incomplete: 50/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Updates: 45/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/profiles/ProfilesStatusWidget.tsx

@@ -0,0 +1,52 @@
+/**
+ * ProfilesStatusWidget - Dashboard widget for user profiles overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface ProfilesStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/profiles') */
+  apiPrefix?: string;
+}
+
+export function ProfilesStatusWidget({ apiPrefix = '/api/profiles' }: ProfilesStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalProfiles: number;
+    completeProfiles: number;
+    incompleteProfiles: number;
+    recentUpdates: 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 Profiles"
+      stats={[
+        { label: 'Total Profiles', value: stats?.totalProfiles ?? 0 },
+        { label: 'Complete', value: stats?.completeProfiles ?? 0 },
+        { label: 'Incomplete', value: stats?.incompleteProfiles ?? 0 },
+        { label: 'Recent Updates', value: stats?.recentUpdates ?? 0, suffix: '/7d' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/profiles"
+    />
+  );
+}

package/src/plugins/profiles/index.ts

@@ -47,3 +47,9 @@ export type {
 
 // Stores
 export { postgresProfileStore } from './stores/index.js';
+
+// UI Components
+export { ProfilesStatusWidget } from './ProfilesStatusWidget.js';
+export type { ProfilesStatusWidgetProps } from './ProfilesStatusWidget.js';
+export { ProfilesManagementPage } from './ProfilesManagementPage.js';
+export type { ProfilesManagementPageProps } from './ProfilesManagementPage.js';