@qwickapps/server 1.4.0 → 1.5.0

package/dist/plugins/notifications/notifications-plugin.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Notifications Plugin
+ *
+ * Provides realtime SSE-based notifications for @qwickapps/server applications.
+ * Uses PostgreSQL LISTEN/NOTIFY for event distribution.
+ *
+ * ## Features
+ * - PostgreSQL LISTEN/NOTIFY integration
+ * - SSE endpoint for client connections
+ * - Device/user-based event filtering
+ * - Automatic reconnection with exponential backoff
+ * - Heartbeat system for connection health
+ * - Statistics and monitoring
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createGateway, createNotificationsPlugin } from '@qwickapps/server';
+ *
+ * const gateway = createGateway({
+ *   productName: 'MyApp',
+ *   controlPanel: {
+ *     plugins: [
+ *       { plugin: createPostgresPlugin({ url: DATABASE_URL }) },
+ *       { plugin: createNotificationsPlugin({
+ *         channels: ['events', 'messages'],
+ *         heartbeat: { interval: 60000 },
+ *       }) },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * ## SSE Endpoint
+ *
+ * ```
+ * GET /notifications/stream?device_id=xxx&user_id=yyy
+ *
+ * Events:
+ *   - connected: Initial connection confirmation
+ *   - heartbeat: Periodic health check
+ *   - {channel}: Events from subscribed channels
+ * ```
+ *
+ * ## Security Note
+ *
+ * This plugin does NOT handle authentication. Authentication should be
+ * configured at the gateway level using the `guard` option or an auth
+ * middleware. The plugin trusts that requests reaching it are authorized.
+ *
+ * Example with gateway guard:
+ * ```typescript
+ * const gateway = createGateway({
+ *   controlPanel: {
+ *     guard: { type: 'basic', username: 'admin', password: 'secret' },
+ *     plugins: [createNotificationsPlugin({ ... })],
+ *   },
+ * });
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Plugin } from '../../core/plugin-registry.js';
+import type { NotificationsPluginConfig } from './types.js';
+/**
+ * Create the Notifications plugin
+ *
+ * @param config Plugin configuration
+ * @returns Plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { createNotificationsPlugin } from '@qwickapps/server';
+ *
+ * const plugin = createNotificationsPlugin({
+ *   channels: ['bot_events', 'chat_messages'],
+ *   heartbeat: { interval: 60000 },
+ *   api: { prefix: '/notifications' },
+ * });
+ * ```
+ */
+export declare function createNotificationsPlugin(config: NotificationsPluginConfig): Plugin;
+//# sourceMappingURL=notifications-plugin.d.ts.map

package/dist/plugins/notifications/notifications-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications-plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/notifications/notifications-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAgC,MAAM,+BAA+B,CAAC;AAC1F,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AA+B5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CA2RnF"}

package/dist/plugins/notifications/notifications-plugin.js

@@ -0,0 +1,337 @@
+/**
+ * Notifications Plugin
+ *
+ * Provides realtime SSE-based notifications for @qwickapps/server applications.
+ * Uses PostgreSQL LISTEN/NOTIFY for event distribution.
+ *
+ * ## Features
+ * - PostgreSQL LISTEN/NOTIFY integration
+ * - SSE endpoint for client connections
+ * - Device/user-based event filtering
+ * - Automatic reconnection with exponential backoff
+ * - Heartbeat system for connection health
+ * - Statistics and monitoring
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createGateway, createNotificationsPlugin } from '@qwickapps/server';
+ *
+ * const gateway = createGateway({
+ *   productName: 'MyApp',
+ *   controlPanel: {
+ *     plugins: [
+ *       { plugin: createPostgresPlugin({ url: DATABASE_URL }) },
+ *       { plugin: createNotificationsPlugin({
+ *         channels: ['events', 'messages'],
+ *         heartbeat: { interval: 60000 },
+ *       }) },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * ## SSE Endpoint
+ *
+ * ```
+ * GET /notifications/stream?device_id=xxx&user_id=yyy
+ *
+ * Events:
+ *   - connected: Initial connection confirmation
+ *   - heartbeat: Periodic health check
+ *   - {channel}: Events from subscribed channels
+ * ```
+ *
+ * ## Security Note
+ *
+ * This plugin does NOT handle authentication. Authentication should be
+ * configured at the gateway level using the `guard` option or an auth
+ * middleware. The plugin trusts that requests reaching it are authorized.
+ *
+ * Example with gateway guard:
+ * ```typescript
+ * const gateway = createGateway({
+ *   controlPanel: {
+ *     guard: { type: 'basic', username: 'admin', password: 'secret' },
+ *     plugins: [createNotificationsPlugin({ ... })],
+ *   },
+ * });
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import { randomUUID } from 'crypto';
+import { NotificationsManager, setNotificationsManager, } from './notifications-manager.js';
+import { getPostgres, hasPostgres } from '../postgres-plugin.js';
+import { getAuthenticatedUser } from '../auth/auth-plugin.js';
+// Validation constants
+const MAX_ID_LENGTH = 128;
+const ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Validate a device_id or user_id parameter
+ */
+function validateId(id, paramName) {
+    if (!id) {
+        return { valid: true }; // undefined is allowed
+    }
+    if (id.length > MAX_ID_LENGTH) {
+        return { valid: false, error: `${paramName} exceeds maximum length of ${MAX_ID_LENGTH} characters` };
+    }
+    if (!ID_PATTERN.test(id)) {
+        return { valid: false, error: `${paramName} contains invalid characters (allowed: alphanumeric, underscore, hyphen)` };
+    }
+    return { valid: true };
+}
+/**
+ * Create the Notifications plugin
+ *
+ * @param config Plugin configuration
+ * @returns Plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { createNotificationsPlugin } from '@qwickapps/server';
+ *
+ * const plugin = createNotificationsPlugin({
+ *   channels: ['bot_events', 'chat_messages'],
+ *   heartbeat: { interval: 60000 },
+ *   api: { prefix: '/notifications' },
+ * });
+ * ```
+ */
+export function createNotificationsPlugin(config) {
+    const apiPrefix = config.api?.prefix || '/notifications';
+    const streamEnabled = config.api?.stream !== false;
+    const statsEnabled = config.api?.stats !== false;
+    let manager = null;
+    return {
+        id: 'notifications',
+        name: 'Notifications',
+        version: '1.0.0',
+        async onStart(_pluginConfig, registry) {
+            const logger = registry.getLogger('notifications');
+            // Check for postgres plugin dependency
+            if (!hasPostgres()) {
+                throw new Error('Notifications plugin requires postgres plugin. ' +
+                    'Please add createPostgresPlugin() before createNotificationsPlugin().');
+            }
+            // Get database connection string from postgres plugin
+            const postgres = getPostgres();
+            const pool = postgres.getPool();
+            // Extract connection string from pool config
+            // Note: pg.Pool stores config internally, we need to reconstruct it
+            const poolConfig = pool.options;
+            let connectionString = poolConfig?.connectionString;
+            if (!connectionString) {
+                // If no connection string, try to get from environment
+                connectionString = process.env.DATABASE_URL;
+            }
+            if (!connectionString) {
+                throw new Error('Could not determine PostgreSQL connection string. ' +
+                    'Ensure DATABASE_URL is set or postgres plugin was configured with a URL.');
+            }
+            logger.debug('Initializing notifications manager', {
+                channels: config.channels,
+                heartbeatInterval: config.heartbeat?.interval,
+            });
+            // Create and initialize manager
+            manager = new NotificationsManager(connectionString, config.channels, config, logger);
+            await manager.initialize();
+            setNotificationsManager(manager);
+            // Register health check
+            registry.registerHealthCheck({
+                name: 'notifications',
+                type: 'custom',
+                check: async () => {
+                    const health = manager?.getConnectionHealth();
+                    return {
+                        healthy: health?.isHealthy ?? false,
+                        details: {
+                            connected: health?.isConnected,
+                            channels: config.channels,
+                            activeClients: manager?.getStats().currentConnections ?? 0,
+                            lastEventAt: health?.lastEventAt?.toISOString(),
+                            isReconnecting: health?.isReconnecting,
+                        },
+                    };
+                },
+            });
+            // Register SSE stream endpoint
+            if (streamEnabled) {
+                registry.addRoute({
+                    method: 'get',
+                    path: `${apiPrefix}/stream`,
+                    pluginId: 'notifications',
+                    handler: (req, res) => {
+                        const deviceId = req.query.device_id;
+                        const userId = req.query.user_id;
+                        // Require at least one filter
+                        if (!deviceId && !userId) {
+                            res.status(400).json({
+                                error: 'Bad Request',
+                                message: 'At least one of device_id or user_id query parameter is required',
+                            });
+                            return;
+                        }
+                        // Validate device_id
+                        const deviceValidation = validateId(deviceId, 'device_id');
+                        if (!deviceValidation.valid) {
+                            res.status(400).json({
+                                error: 'Bad Request',
+                                message: deviceValidation.error,
+                            });
+                            return;
+                        }
+                        // Validate user_id
+                        const userValidation = validateId(userId, 'user_id');
+                        if (!userValidation.valid) {
+                            res.status(400).json({
+                                error: 'Bad Request',
+                                message: userValidation.error,
+                            });
+                            return;
+                        }
+                        // Set SSE headers
+                        res.setHeader('Content-Type', 'text/event-stream');
+                        res.setHeader('Cache-Control', 'no-cache');
+                        res.setHeader('Connection', 'keep-alive');
+                        res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
+                        // Disable compression for SSE
+                        res.setHeader('Content-Encoding', 'identity');
+                        // Flush headers
+                        res.flushHeaders();
+                        // Generate client ID and register
+                        const clientId = randomUUID();
+                        const registered = manager?.registerClient(clientId, deviceId, userId, res);
+                        // Handle capacity limit
+                        if (!registered) {
+                            res.write('event: error\n');
+                            res.write('data: {"error": "Server at capacity, please try again later"}\n\n');
+                            res.end();
+                        }
+                    },
+                });
+                logger.debug(`SSE endpoint registered: GET ${apiPrefix}/stream`);
+            }
+            // Register stats endpoint
+            if (statsEnabled) {
+                registry.addRoute({
+                    method: 'get',
+                    path: `${apiPrefix}/stats`,
+                    pluginId: 'notifications',
+                    handler: (_req, res) => {
+                        if (!manager) {
+                            res.status(503).json({ error: 'Service unavailable' });
+                            return;
+                        }
+                        const stats = manager.getStats();
+                        res.json({
+                            ...stats,
+                            channels: config.channels,
+                            lastEventAt: stats.connectionHealth.lastEventAt?.toISOString(),
+                            lastReconnectionAt: stats.lastReconnectionAt?.toISOString(),
+                        });
+                    },
+                });
+                logger.debug(`Stats endpoint registered: GET ${apiPrefix}/stats`);
+                // Register clients endpoint
+                registry.addRoute({
+                    method: 'get',
+                    path: `${apiPrefix}/clients`,
+                    pluginId: 'notifications',
+                    handler: (_req, res) => {
+                        if (!manager) {
+                            res.status(503).json({ error: 'Service unavailable' });
+                            return;
+                        }
+                        const clients = manager.getClients();
+                        res.json({
+                            clients,
+                            total: clients.length,
+                        });
+                    },
+                });
+                logger.debug(`Clients endpoint registered: GET ${apiPrefix}/clients`);
+                // Register disconnect client endpoint
+                registry.addRoute({
+                    method: 'delete',
+                    path: `${apiPrefix}/clients/:id`,
+                    pluginId: 'notifications',
+                    handler: (req, res) => {
+                        if (!manager) {
+                            res.status(503).json({ error: 'Service unavailable' });
+                            return;
+                        }
+                        const clientId = req.params.id;
+                        if (!clientId) {
+                            res.status(400).json({ error: 'Bad Request', message: 'Client ID is required' });
+                            return;
+                        }
+                        // Get admin user info for audit logging
+                        const adminUser = getAuthenticatedUser(req);
+                        const disconnectedBy = {
+                            userId: adminUser?.id,
+                            email: adminUser?.email,
+                            ip: req.ip || req.socket.remoteAddress,
+                        };
+                        const disconnected = manager.disconnectClient(clientId, disconnectedBy);
+                        if (!disconnected) {
+                            res.status(404).json({ error: 'Not Found', message: 'Client not found' });
+                            return;
+                        }
+                        res.json({ success: true });
+                    },
+                });
+                logger.debug(`Disconnect endpoint registered: DELETE ${apiPrefix}/clients/:id`);
+                // Register force reconnect endpoint
+                registry.addRoute({
+                    method: 'post',
+                    path: `${apiPrefix}/reconnect`,
+                    pluginId: 'notifications',
+                    handler: async (_req, res) => {
+                        if (!manager) {
+                            res.status(503).json({ error: 'Service unavailable' });
+                            return;
+                        }
+                        try {
+                            await manager.forceReconnect();
+                            res.json({ success: true, message: 'Reconnection initiated' });
+                        }
+                        catch (error) {
+                            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+                            res.status(500).json({ error: 'Reconnection failed', message: errorMsg });
+                        }
+                    },
+                });
+                logger.debug(`Reconnect endpoint registered: POST ${apiPrefix}/reconnect`);
+                // Register UI menu item for management page
+                registry.addMenuItem({
+                    pluginId: 'notifications',
+                    id: 'notifications:sidebar',
+                    label: 'Notifications',
+                    icon: 'notifications',
+                    route: '/notifications',
+                    order: 45, // After Rate Limits (40)
+                });
+                // Register dashboard widget
+                registry.addWidget({
+                    id: 'notifications-stats',
+                    title: 'Notifications',
+                    component: 'NotificationsStatsWidget',
+                    priority: 25, // After ServiceHealthWidget (10) and AuthStatusWidget (20)
+                    showByDefault: true,
+                    pluginId: 'notifications',
+                });
+            }
+            logger.info('Notifications plugin started');
+        },
+        async onStop() {
+            if (manager) {
+                await manager.shutdown();
+                setNotificationsManager(null);
+                manager = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=notifications-plugin.js.map

package/dist/plugins/notifications/notifications-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications-plugin.js","sourceRoot":"","sources":["../../../src/plugins/notifications/notifications-plugin.ts"],"names":[],"mappings":"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"}

package/dist/plugins/notifications/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Notifications Plugin Types
+ *
+ * Type definitions for the realtime notifications plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Response } from 'express';
+/**
+ * Configuration for the notifications plugin
+ */
+export interface NotificationsPluginConfig {
+    /**
+     * PostgreSQL channels to LISTEN on.
+     * Each channel maps to a NOTIFY channel in PostgreSQL.
+     * Example: ['bot_events', 'chat_messages']
+     */
+    channels: string[];
+    /**
+     * Heartbeat configuration
+     */
+    heartbeat?: {
+        /** Interval in milliseconds (default: 60000 = 1 minute) */
+        interval?: number;
+        /** Include server status in heartbeat (default: true) */
+        includeStatus?: boolean;
+    };
+    /**
+     * Reconnection configuration for PostgreSQL LISTEN connection
+     */
+    reconnect?: {
+        /** Maximum reconnection attempts before giving up (default: 10) */
+        maxAttempts?: number;
+        /** Base delay in milliseconds for exponential backoff (default: 1000) */
+        baseDelay?: number;
+        /** Maximum delay in milliseconds (default: 60000) */
+        maxDelay?: number;
+    };
+    /**
+     * API endpoint configuration
+     */
+    api?: {
+        /** Route prefix (default: '/notifications') */
+        prefix?: string;
+        /** Enable /stream SSE endpoint (default: true) */
+        stream?: boolean;
+        /** Enable /stats endpoint (default: true) */
+        stats?: boolean;
+    };
+    /**
+     * Enable debug logging (default: false)
+     */
+    debug?: boolean;
+}
+/**
+ * Represents a connected SSE client
+ */
+export interface SSEClient {
+    /** Unique client identifier */
+    id: string;
+    /** Device ID for filtering (optional) */
+    deviceId?: string;
+    /** User ID for filtering (optional) */
+    userId?: string;
+    /** Express response object for SSE */
+    response: Response;
+    /** Connection timestamp */
+    connectedAt: Date;
+}
+/**
+ * PostgreSQL NOTIFY payload structure
+ */
+export interface NotifyPayload {
+    /** Event type (e.g., 'command', 'status') */
+    eventType?: string;
+    /** Target device ID (for routing) */
+    deviceId?: string;
+    /** Target user ID (for routing) */
+    userId?: string;
+    /** Event payload data */
+    payload?: unknown;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+/**
+ * SSE event to send to clients
+ */
+export interface SSEEvent {
+    /** Event type name */
+    eventType: string;
+    /** Event data */
+    payload: unknown;
+}
+/**
+ * Connection health information
+ */
+export interface ConnectionHealth {
+    /** Whether LISTEN connection is established */
+    isConnected: boolean;
+    /** Whether connection is considered healthy */
+    isHealthy: boolean;
+    /** Last time an event was received */
+    lastEventAt: Date | null;
+    /** Time since last event in milliseconds */
+    timeSinceLastEvent: number;
+    /** Number of channels being listened to */
+    channelCount: number;
+    /** Whether reconnection is in progress */
+    isReconnecting: boolean;
+    /** Current reconnection attempt number */
+    reconnectAttempts: number;
+}
+/**
+ * Notifications manager statistics
+ */
+export interface NotificationsStats {
+    /** Total connections since startup */
+    totalConnections: number;
+    /** Currently active connections */
+    currentConnections: number;
+    /** Total events received from PostgreSQL */
+    eventsProcessed: number;
+    /** Total events routed to clients */
+    eventsRouted: number;
+    /** Events that failed JSON parsing */
+    eventsParseFailed: number;
+    /** Events dropped because no clients matched */
+    eventsDroppedNoClients: number;
+    /** Total reconnection attempts */
+    reconnectionAttempts: number;
+    /** Last reconnection timestamp */
+    lastReconnectionAt?: Date;
+    /** Client breakdown by type */
+    clientsByType: {
+        /** Clients with device_id filter */
+        device: number;
+        /** Clients with user_id filter */
+        user: number;
+    };
+    /** Connection health status */
+    connectionHealth: ConnectionHealth;
+}
+/**
+ * NotificationsManager interface for external access
+ */
+export interface NotificationsManagerInterface {
+    /** Register a new SSE client */
+    registerClient(id: string, deviceId: string | undefined, userId: string | undefined, response: Response): void;
+    /** Broadcast event to a specific device */
+    broadcastToDevice(deviceId: string, eventType: string, payload: unknown): number;
+    /** Broadcast event to all devices for a user */
+    broadcastToUser(userId: string, eventType: string, payload: unknown): number;
+    /** Broadcast to all clients (channel-level broadcast) */
+    broadcastToAll(eventType: string, payload: unknown): number;
+    /** Get current statistics */
+    getStats(): NotificationsStats;
+    /** Get connection health */
+    getConnectionHealth(): ConnectionHealth;
+    /** Force reconnection to PostgreSQL */
+    forceReconnect(): Promise<void>;
+    /** Shutdown the manager */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/notifications/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/plugins/notifications/types.ts"],"names":[],"mappings":"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"}

package/dist/plugins/notifications/types.js

@@ -0,0 +1,9 @@
+/**
+ * Notifications Plugin Types
+ *
+ * Type definitions for the realtime notifications plugin.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/plugins/notifications/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/plugins/notifications/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/plugins/parental/__tests__/parental-plugin.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parental Plugin Tests
+ *
+ * Unit tests for the parental controls plugin including:
+ * - Plugin lifecycle
+ * - Guardian settings management
+ * - Profile restrictions
+ * - Activity logging
+ * - PIN verification
+ */
+export {};
+//# sourceMappingURL=parental-plugin.test.d.ts.map

package/dist/plugins/parental/__tests__/parental-plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parental-plugin.test.d.ts","sourceRoot":"","sources":["../../../../src/plugins/parental/__tests__/parental-plugin.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}