@qwickapps/server 1.3.0 → 1.3.1

package/src/plugins/cache-plugin.test.ts

@@ -79,10 +79,13 @@ describe('Cache Plugin', () => {
     addMenuItem: vi.fn(),
     addPage: vi.fn(),
     addWidget: vi.fn(),
+    addConfigComponent: vi.fn(),
     getRoutes: vi.fn().mockReturnValue([]),
     getMenuItems: vi.fn().mockReturnValue([]),
     getPages: vi.fn().mockReturnValue([]),
     getWidgets: vi.fn().mockReturnValue([]),
+    getConfigComponents: vi.fn().mockReturnValue([]),
+    getPluginContributions: vi.fn().mockReturnValue({ routes: [], menuItems: [], pages: [], widgets: [], config: undefined }),
     getConfig: vi.fn().mockReturnValue({}),
     setConfig: vi.fn().mockResolvedValue(undefined),
     subscribe: vi.fn().mockReturnValue(() => {}),

package/src/plugins/index.ts

@@ -28,6 +28,8 @@ export type { CachePluginConfig, CacheInstance } from './cache-plugin.js';
 // Auth plugin
 export {
   createAuthPlugin,
+  createAuthPluginFromEnv,
+  getAuthStatus,
   isAuthenticated,
   getAuthenticatedUser,
   getAccessToken,
@@ -37,6 +39,7 @@ export {
   auth0Adapter,
   basicAdapter,
   supabaseAdapter,
+  supertokensAdapter,
   isAuthenticatedRequest,
 } from './auth/index.js';
 export type {
@@ -47,6 +50,10 @@ export type {
   Auth0AdapterConfig,
   SupabaseAdapterConfig,
   BasicAdapterConfig,
+  SupertokensAdapterConfig,
+  AuthPluginState,
+  AuthEnvPluginOptions,
+  AuthConfigStatus,
 } from './auth/index.js';
 
 // Users plugin
@@ -130,3 +137,22 @@ export type {
   CachedEntitlements,
   EntitlementStats,
 } from './entitlements/index.js';
+
+// Preferences plugin (depends on Users)
+export {
+  createPreferencesPlugin,
+  getPreferencesStore,
+  getPreferences,
+  updatePreferences,
+  deletePreferences,
+  getDefaultPreferences,
+  postgresPreferencesStore,
+  deepMerge,
+} from './preferences/index.js';
+export type {
+  PreferencesPluginConfig,
+  PreferencesStore,
+  UserPreferences,
+  PostgresPreferencesStoreConfig,
+  PreferencesApiConfig,
+} from './preferences/index.js';

package/src/plugins/postgres-plugin.test.ts

@@ -56,10 +56,13 @@ describe('PostgreSQL Plugin', () => {
     addMenuItem: vi.fn(),
     addPage: vi.fn(),
     addWidget: vi.fn(),
+    addConfigComponent: vi.fn(),
     getRoutes: vi.fn().mockReturnValue([]),
     getMenuItems: vi.fn().mockReturnValue([]),
     getPages: vi.fn().mockReturnValue([]),
     getWidgets: vi.fn().mockReturnValue([]),
+    getConfigComponents: vi.fn().mockReturnValue([]),
+    getPluginContributions: vi.fn().mockReturnValue({ routes: [], menuItems: [], pages: [], widgets: [], config: undefined }),
     getConfig: vi.fn().mockReturnValue({}),
     setConfig: vi.fn().mockResolvedValue(undefined),
     subscribe: vi.fn().mockReturnValue(() => {}),

package/src/plugins/preferences/__tests__/deep-merge.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Deep Merge Utility Tests
+ *
+ * Unit tests for the deep merge function used by the preferences plugin.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { deepMerge } from '../stores/postgres-store.js';
+
+describe('deepMerge', () => {
+  describe('basic merging', () => {
+    it('should merge flat objects', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1, b: 2 });
+    });
+
+    it('should not mutate original objects', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+      deepMerge(target, source);
+      expect(target).toEqual({ a: 1 });
+      expect(source).toEqual({ b: 2 });
+    });
+
+    it('should return a new object', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+      const result = deepMerge(target, source);
+      expect(result).not.toBe(target);
+      expect(result).not.toBe(source);
+    });
+  });
+
+  describe('nested object merging', () => {
+    it('should merge nested objects recursively', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: { y: 2 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 1, y: 2 } });
+    });
+
+    it('should handle deeply nested objects', () => {
+      const target = { a: { b: { c: { x: 1 } } } };
+      const source = { a: { b: { c: { y: 2 } } } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { b: { c: { x: 1, y: 2 } } } });
+    });
+
+    it('should merge multiple nested keys', () => {
+      const target = {
+        theme: 'light',
+        notifications: { email: true, push: true },
+      };
+      const source = {
+        notifications: { email: false },
+      };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({
+        theme: 'light',
+        notifications: { email: false, push: true },
+      });
+    });
+  });
+
+  describe('value overwriting', () => {
+    it('should let source override target for same keys', () => {
+      const target = { a: 1 };
+      const source = { a: 2 };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 2 });
+    });
+
+    it('should let source override target for nested keys', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: { x: 2 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 2 } });
+    });
+  });
+
+  describe('array handling', () => {
+    it('should replace arrays (not merge)', () => {
+      const target = { a: [1, 2] };
+      const source = { a: [3, 4, 5] };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: [3, 4, 5] });
+    });
+
+    it('should replace array with empty array', () => {
+      const target = { a: [1, 2, 3] };
+      const source = { a: [] };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: [] });
+    });
+
+    it('should replace non-array with array', () => {
+      const target = { a: 'string' };
+      const source = { a: [1, 2] };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: [1, 2] });
+    });
+
+    it('should replace array with non-array', () => {
+      const target = { a: [1, 2] };
+      const source = { a: 'string' };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 'string' });
+    });
+  });
+
+  describe('special values', () => {
+    it('should handle null values in source', () => {
+      const target = { a: 1 };
+      const source = { a: null };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: null });
+    });
+
+    it('should skip undefined values in source', () => {
+      const target = { a: 1 };
+      const source = { a: undefined };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should handle null in target', () => {
+      const target = { a: null };
+      const source = { a: { x: 1 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 1 } });
+    });
+
+    it('should replace object with null', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: null };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: null });
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty target', () => {
+      const target = {};
+      const source = { a: 1 };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should handle empty source', () => {
+      const target = { a: 1 };
+      const source = {};
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 1 });
+    });
+
+    it('should handle both empty', () => {
+      const target = {};
+      const source = {};
+      const result = deepMerge(target, source);
+      expect(result).toEqual({});
+    });
+
+    it('should handle primitive values becoming objects', () => {
+      const target = { a: 'string' };
+      const source = { a: { x: 1 } };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: { x: 1 } });
+    });
+
+    it('should handle objects becoming primitive values', () => {
+      const target = { a: { x: 1 } };
+      const source = { a: 'string' };
+      const result = deepMerge(target, source);
+      expect(result).toEqual({ a: 'string' });
+    });
+  });
+
+  describe('real-world preference scenarios', () => {
+    it('should merge default preferences with user preferences', () => {
+      const defaults = {
+        theme: 'system',
+        notifications: {
+          email: true,
+          push: true,
+          sms: false,
+        },
+        trading: {
+          defaultSymbol: 'SPY',
+          chartInterval: '5min',
+        },
+      };
+
+      const userPrefs = {
+        theme: 'dark',
+        notifications: {
+          email: false,
+        },
+      };
+
+      const result = deepMerge(defaults, userPrefs);
+      expect(result).toEqual({
+        theme: 'dark',
+        notifications: {
+          email: false,
+          push: true,
+          sms: false,
+        },
+        trading: {
+          defaultSymbol: 'SPY',
+          chartInterval: '5min',
+        },
+      });
+    });
+
+    it('should handle partial updates to preferences', () => {
+      const existing = {
+        theme: 'dark',
+        notifications: {
+          email: false,
+          push: true,
+        },
+      };
+
+      const update = {
+        notifications: {
+          push: false,
+        },
+      };
+
+      const result = deepMerge(existing, update);
+      expect(result).toEqual({
+        theme: 'dark',
+        notifications: {
+          email: false,
+          push: false,
+        },
+      });
+    });
+  });
+});

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';