@qwickapps/server 1.3.0 → 1.4.0

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

@@ -0,0 +1,350 @@
+/**
+ * Preferences Plugin Tests
+ *
+ * Unit tests for the preferences plugin using mocked dependencies.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  createPreferencesPlugin,
+  getPreferencesStore,
+  getPreferences,
+  updatePreferences,
+  deletePreferences,
+  getDefaultPreferences,
+} from '../preferences-plugin.js';
+import type { PreferencesStore, PreferencesPluginConfig } from '../types.js';
+import type { PluginRegistry } from '../../../core/plugin-registry.js';
+
+describe('Preferences Plugin', () => {
+  // Mock store
+  const createMockStore = (): PreferencesStore => ({
+    name: 'mock',
+    initialize: vi.fn().mockResolvedValue(undefined),
+    get: vi.fn().mockResolvedValue(null),
+    update: vi.fn().mockResolvedValue({}),
+    delete: vi.fn().mockResolvedValue(true),
+    shutdown: vi.fn().mockResolvedValue(undefined),
+  });
+
+  // Mock registry
+  const createMockRegistry = (hasUsers = true): PluginRegistry =>
+    ({
+      hasPlugin: vi.fn().mockImplementation((id: string) => id === 'users' && hasUsers),
+      getPlugin: vi.fn().mockReturnValue(null),
+      listPlugins: vi.fn().mockReturnValue([]),
+      addRoute: vi.fn(),
+      addMenuItem: vi.fn(),
+      addPage: vi.fn(),
+      addWidget: vi.fn(),
+      getRoutes: vi.fn().mockReturnValue([]),
+      getMenuItems: vi.fn().mockReturnValue([]),
+      getPages: vi.fn().mockReturnValue([]),
+      getWidgets: vi.fn().mockReturnValue([]),
+      getConfig: vi.fn().mockReturnValue({}),
+      setConfig: vi.fn().mockResolvedValue(undefined),
+      subscribe: vi.fn().mockReturnValue(() => {}),
+      emit: vi.fn(),
+      registerHealthCheck: vi.fn(),
+      getApp: vi.fn().mockReturnValue({} as any),
+      getRouter: vi.fn().mockReturnValue({} as any),
+      getLogger: vi.fn().mockReturnValue({
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      }),
+    }) as unknown as PluginRegistry;
+
+  let mockStore: PreferencesStore;
+  let mockRegistry: PluginRegistry;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockStore = createMockStore();
+    mockRegistry = createMockRegistry();
+  });
+
+  afterEach(async () => {
+    // Clean up by stopping the plugin if it was started
+    const store = getPreferencesStore();
+    if (store) {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStop();
+    }
+  });
+
+  describe('createPreferencesPlugin', () => {
+    it('should create a plugin with correct id', () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      expect(plugin.id).toBe('preferences');
+    });
+
+    it('should create a plugin with correct name', () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      expect(plugin.name).toBe('Preferences');
+    });
+
+    it('should create a plugin with version', () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      expect(plugin.version).toBe('1.0.0');
+    });
+  });
+
+  describe('onStart', () => {
+    it('should throw error if users plugin is not loaded', async () => {
+      const registryWithoutUsers = createMockRegistry(false);
+      const plugin = createPreferencesPlugin({ store: mockStore });
+
+      await expect(plugin.onStart({}, registryWithoutUsers)).rejects.toThrow(
+        'Preferences plugin requires Users plugin to be loaded first'
+      );
+    });
+
+    it('should initialize store on start', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(mockStore.initialize).toHaveBeenCalled();
+    });
+
+    it('should register health check', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(mockRegistry.registerHealthCheck).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'preferences-store',
+          type: 'custom',
+        })
+      );
+    });
+
+    it('should register API routes by default', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(mockRegistry.addRoute).toHaveBeenCalledTimes(3); // GET, PUT, DELETE
+    });
+
+    it('should register routes with correct paths', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      const calls = (mockRegistry.addRoute as any).mock.calls;
+
+      // Check GET route
+      expect(calls[0][0]).toMatchObject({
+        method: 'get',
+        path: '/preferences',
+        pluginId: 'preferences',
+      });
+
+      // Check PUT route
+      expect(calls[1][0]).toMatchObject({
+        method: 'put',
+        path: '/preferences',
+        pluginId: 'preferences',
+      });
+
+      // Check DELETE route
+      expect(calls[2][0]).toMatchObject({
+        method: 'delete',
+        path: '/preferences',
+        pluginId: 'preferences',
+      });
+    });
+
+    it('should use custom API prefix when provided', async () => {
+      const plugin = createPreferencesPlugin({
+        store: mockStore,
+        api: { prefix: '/user-prefs' },
+      });
+      await plugin.onStart({}, mockRegistry);
+
+      const calls = (mockRegistry.addRoute as any).mock.calls;
+      expect(calls[0][0].path).toBe('/user-prefs');
+    });
+
+    it('should not register routes when API is disabled', async () => {
+      const plugin = createPreferencesPlugin({
+        store: mockStore,
+        api: { enabled: false },
+      });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(mockRegistry.addRoute).not.toHaveBeenCalled();
+    });
+
+    it('should set store reference for helper functions', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+
+      expect(getPreferencesStore()).toBe(mockStore);
+    });
+  });
+
+  describe('onStop', () => {
+    it('should shutdown store', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+      await plugin.onStop();
+
+      expect(mockStore.shutdown).toHaveBeenCalled();
+    });
+
+    it('should clear store reference', async () => {
+      const plugin = createPreferencesPlugin({ store: mockStore });
+      await plugin.onStart({}, mockRegistry);
+      await plugin.onStop();
+
+      expect(getPreferencesStore()).toBeNull();
+    });
+  });
+
+  describe('helper functions', () => {
+    describe('getPreferencesStore', () => {
+      it('should return null when plugin not started', () => {
+        expect(getPreferencesStore()).toBeNull();
+      });
+
+      it('should return store when plugin started', async () => {
+        const plugin = createPreferencesPlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        expect(getPreferencesStore()).toBe(mockStore);
+      });
+    });
+
+    describe('getPreferences', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(getPreferences('user-id')).rejects.toThrow(
+          'Preferences plugin not initialized'
+        );
+      });
+
+      it('should return defaults when no stored preferences', async () => {
+        const defaults = { theme: 'light' };
+        const plugin = createPreferencesPlugin({ store: mockStore, defaults });
+        await plugin.onStart({}, mockRegistry);
+
+        (mockStore.get as any).mockResolvedValue(null);
+
+        const result = await getPreferences('user-id');
+        expect(result).toEqual({ theme: 'light' });
+      });
+
+      it('should merge stored preferences with defaults', async () => {
+        const defaults = { theme: 'light', notifications: { email: true } };
+        const plugin = createPreferencesPlugin({ store: mockStore, defaults });
+        await plugin.onStart({}, mockRegistry);
+
+        (mockStore.get as any).mockResolvedValue({ theme: 'dark' });
+
+        const result = await getPreferences('user-id');
+        expect(result).toEqual({
+          theme: 'dark',
+          notifications: { email: true },
+        });
+      });
+
+      it('should call store.get with userId', async () => {
+        const plugin = createPreferencesPlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        await getPreferences('test-user-id');
+
+        expect(mockStore.get).toHaveBeenCalledWith('test-user-id');
+      });
+    });
+
+    describe('updatePreferences', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(updatePreferences('user-id', {})).rejects.toThrow(
+          'Preferences plugin not initialized'
+        );
+      });
+
+      it('should call store.update with userId and preferences', async () => {
+        const plugin = createPreferencesPlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        const prefs = { theme: 'dark' };
+        (mockStore.update as any).mockResolvedValue(prefs);
+
+        await updatePreferences('test-user-id', prefs);
+
+        expect(mockStore.update).toHaveBeenCalledWith('test-user-id', prefs);
+      });
+
+      it('should merge result with defaults', async () => {
+        const defaults = { notifications: { email: true } };
+        const plugin = createPreferencesPlugin({ store: mockStore, defaults });
+        await plugin.onStart({}, mockRegistry);
+
+        (mockStore.update as any).mockResolvedValue({ theme: 'dark' });
+
+        const result = await updatePreferences('user-id', { theme: 'dark' });
+        expect(result).toEqual({
+          theme: 'dark',
+          notifications: { email: true },
+        });
+      });
+    });
+
+    describe('deletePreferences', () => {
+      it('should throw when plugin not initialized', async () => {
+        await expect(deletePreferences('user-id')).rejects.toThrow(
+          'Preferences plugin not initialized'
+        );
+      });
+
+      it('should call store.delete with userId', async () => {
+        const plugin = createPreferencesPlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        await deletePreferences('test-user-id');
+
+        expect(mockStore.delete).toHaveBeenCalledWith('test-user-id');
+      });
+
+      it('should return store.delete result', async () => {
+        const plugin = createPreferencesPlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        (mockStore.delete as any).mockResolvedValue(true);
+        expect(await deletePreferences('user-id')).toBe(true);
+
+        (mockStore.delete as any).mockResolvedValue(false);
+        expect(await deletePreferences('user-id')).toBe(false);
+      });
+    });
+
+    describe('getDefaultPreferences', () => {
+      it('should return empty object when no defaults configured', async () => {
+        const plugin = createPreferencesPlugin({ store: mockStore });
+        await plugin.onStart({}, mockRegistry);
+
+        expect(getDefaultPreferences()).toEqual({});
+      });
+
+      it('should return configured defaults', async () => {
+        const defaults = { theme: 'light', lang: 'en' };
+        const plugin = createPreferencesPlugin({ store: mockStore, defaults });
+        await plugin.onStart({}, mockRegistry);
+
+        expect(getDefaultPreferences()).toEqual(defaults);
+      });
+
+      it('should return a copy (not reference)', async () => {
+        const defaults = { theme: 'light' };
+        const plugin = createPreferencesPlugin({ store: mockStore, defaults });
+        await plugin.onStart({}, mockRegistry);
+
+        const result = getDefaultPreferences();
+        expect(result).not.toBe(defaults);
+        expect(result).toEqual(defaults);
+      });
+    });
+  });
+});

package/src/plugins/preferences/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Preferences Plugin Index
+ *
+ * User preferences management plugin with PostgreSQL RLS.
+ * Depends on the Users Plugin for user identity.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+// Main plugin
+export {
+  createPreferencesPlugin,
+  getPreferencesStore,
+  getPreferences,
+  updatePreferences,
+  deletePreferences,
+  getDefaultPreferences,
+} from './preferences-plugin.js';
+
+// Types
+export type {
+  PreferencesPluginConfig,
+  PreferencesStore,
+  UserPreferences,
+  PostgresPreferencesStoreConfig,
+  PreferencesApiConfig,
+} from './types.js';
+
+// Stores
+export { postgresPreferencesStore, deepMerge } from './stores/index.js';

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

@@ -0,0 +1,270 @@
+/**
+ * Preferences Plugin
+ *
+ * User preferences management plugin for @qwickapps/server.
+ * Provides per-user preference storage with PostgreSQL RLS for data isolation.
+ *
+ * This plugin depends on the Users Plugin for user identity.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response } from 'express';
+import type { Plugin, PluginConfig, PluginRegistry } from '../../core/plugin-registry.js';
+import type {
+  PreferencesPluginConfig,
+  PreferencesStore,
+} 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;
+
+/**
+ * Check if an object exceeds maximum nesting depth
+ */
+function exceedsMaxDepth(obj: unknown, depth = 0): boolean {
+  if (depth > MAX_NESTING_DEPTH) return true;
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    return Object.values(obj as Record<string, unknown>).some(v => exceedsMaxDepth(v, depth + 1));
+  }
+  if (Array.isArray(obj)) {
+    return obj.some(v => exceedsMaxDepth(v, depth + 1));
+  }
+  return false;
+}
+
+// Store instance for helper access
+let currentStore: PreferencesStore | null = null;
+let pluginDefaults: Record<string, unknown> = {};
+
+/**
+ * Create the Preferences plugin
+ */
+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 apiEnabled = config.api?.enabled !== false;
+
+  function log(message: string, data?: Record<string, unknown>) {
+    if (debug) {
+      console.log(`[PreferencesPlugin] ${message}`, data || '');
+    }
+  }
+
+  return {
+    id: 'preferences',
+    name: 'Preferences',
+    version: '1.0.0',
+
+    async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
+      log('Starting preferences plugin');
+
+      // Check for users plugin dependency
+      if (!registry.hasPlugin('users')) {
+        throw new Error('Preferences plugin requires Users plugin to be loaded first');
+      }
+
+      // Initialize the store (creates tables and RLS policies if needed)
+      await config.store.initialize();
+      log('Preferences plugin migrations complete');
+
+      // Store references for helper access
+      currentStore = config.store;
+      pluginDefaults = config.defaults || {};
+
+      // Register health check
+      registry.registerHealthCheck({
+        name: 'preferences-store',
+        type: 'custom',
+        check: async () => {
+          try {
+            // Simple health check - store is accessible
+            // We can't actually query without a user context due to RLS,
+            // but we can verify the store is initialized
+            return { healthy: currentStore !== null };
+          } catch {
+            return { healthy: false };
+          }
+        },
+      });
+
+      // Add API routes if enabled
+      if (apiEnabled) {
+        // GET /preferences - Get current user's preferences
+        registry.addRoute({
+          method: 'get',
+          path: apiPrefix,
+          pluginId: 'preferences',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const authReq = req as AuthenticatedRequest;
+              const userId = authReq.auth?.user?.id;
+
+              if (!userId) {
+                return res.status(401).json({ error: 'Authentication required' });
+              }
+
+              const stored = await config.store.get(userId);
+
+              // Merge with defaults (defaults as base, stored values override)
+              const preferences = stored
+                ? deepMerge(pluginDefaults, stored)
+                : { ...pluginDefaults };
+
+              res.json({
+                user_id: userId,
+                preferences,
+              });
+            } catch (error) {
+              console.error('[PreferencesPlugin] Get preferences error:', error);
+              res.status(500).json({ error: 'Failed to get preferences' });
+            }
+          },
+        });
+
+        // PUT /preferences - Update current user's preferences
+        registry.addRoute({
+          method: 'put',
+          path: apiPrefix,
+          pluginId: 'preferences',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const authReq = req as AuthenticatedRequest;
+              const userId = authReq.auth?.user?.id;
+
+              if (!userId) {
+                return res.status(401).json({ error: 'Authentication required' });
+              }
+
+              const newPreferences = req.body;
+              if (!newPreferences || typeof newPreferences !== 'object' || Array.isArray(newPreferences)) {
+                return res.status(400).json({ error: 'Request body must be a JSON object' });
+              }
+
+              // Validate payload size
+              const jsonSize = JSON.stringify(newPreferences).length;
+              if (jsonSize > MAX_PREFERENCES_SIZE) {
+                return res.status(413).json({ error: 'Preferences payload too large (max 100KB)' });
+              }
+
+              // Validate nesting depth
+              if (exceedsMaxDepth(newPreferences)) {
+                return res.status(400).json({ error: 'Preferences object too deeply nested (max 10 levels)' });
+              }
+
+              const updated = await config.store.update(userId, newPreferences);
+
+              // Merge with defaults for response
+              const preferences = deepMerge(pluginDefaults, updated);
+
+              res.json({
+                user_id: userId,
+                preferences,
+              });
+            } catch (error) {
+              console.error('[PreferencesPlugin] Update preferences error:', error);
+              res.status(500).json({ error: 'Failed to update preferences' });
+            }
+          },
+        });
+
+        // DELETE /preferences - Reset preferences to defaults
+        registry.addRoute({
+          method: 'delete',
+          path: apiPrefix,
+          pluginId: 'preferences',
+          handler: async (req: Request, res: Response) => {
+            try {
+              const authReq = req as AuthenticatedRequest;
+              const userId = authReq.auth?.user?.id;
+
+              if (!userId) {
+                return res.status(401).json({ error: 'Authentication required' });
+              }
+
+              await config.store.delete(userId);
+
+              // Return 204 No Content (idempotent - success even if no row existed)
+              res.status(204).send();
+            } catch (error) {
+              console.error('[PreferencesPlugin] Delete preferences error:', error);
+              res.status(500).json({ error: 'Failed to delete preferences' });
+            }
+          },
+        });
+      }
+
+      log('Preferences plugin started');
+    },
+
+    async onStop(): Promise<void> {
+      log('Stopping preferences plugin');
+      await config.store.shutdown();
+      currentStore = null;
+      pluginDefaults = {};
+      log('Preferences plugin stopped');
+    },
+  };
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+/**
+ * Get the current preferences store instance
+ */
+export function getPreferencesStore(): PreferencesStore | null {
+  return currentStore;
+}
+
+/**
+ * Get preferences for a user (merged with defaults)
+ */
+export async function getPreferences(userId: string): Promise<Record<string, unknown>> {
+  if (!currentStore) {
+    throw new Error('Preferences plugin not initialized');
+  }
+
+  const stored = await currentStore.get(userId);
+  return stored ? deepMerge(pluginDefaults, stored) : { ...pluginDefaults };
+}
+
+/**
+ * Update preferences for a user
+ * Returns the merged preferences (stored + defaults)
+ */
+export async function updatePreferences(
+  userId: string,
+  preferences: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  if (!currentStore) {
+    throw new Error('Preferences plugin not initialized');
+  }
+
+  const updated = await currentStore.update(userId, preferences);
+  return deepMerge(pluginDefaults, updated);
+}
+
+/**
+ * Delete preferences for a user (reset to defaults)
+ * Returns true if preferences existed and were deleted
+ */
+export async function deletePreferences(userId: string): Promise<boolean> {
+  if (!currentStore) {
+    throw new Error('Preferences plugin not initialized');
+  }
+
+  return currentStore.delete(userId);
+}
+
+/**
+ * Get the configured default preferences
+ */
+export function getDefaultPreferences(): Record<string, unknown> {
+  return { ...pluginDefaults };
+}

package/src/plugins/preferences/stores/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Preferences Stores Index
+ *
+ * Re-exports all available preferences store implementations.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresPreferencesStore, deepMerge } from './postgres-store.js';