@qwickapps/server 1.3.1 → 1.5.0

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

@@ -0,0 +1,182 @@
+/**
+ * Notifications Manager
+ *
+ * Core service that manages PostgreSQL LISTEN/NOTIFY and SSE client connections.
+ * Provides realtime event routing from database to connected clients.
+ *
+ * Architecture:
+ * - Single dedicated PostgreSQL connection for LISTEN (not from pool)
+ * - In-memory Map of SSE clients
+ * - Event routing based on device_id/user_id filters
+ * - Automatic reconnection with exponential backoff
+ * - Heartbeat system for connection health
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Response } from 'express';
+import type { NotificationsStats, ConnectionHealth, NotificationsManagerInterface, NotificationsPluginConfig } from './types.js';
+import type { Logger } from '../../core/types.js';
+/**
+ * NotificationsManager - Singleton service for realtime notifications
+ */
+export declare class NotificationsManager implements NotificationsManagerInterface {
+    private client;
+    private clients;
+    private channels;
+    private connectionString;
+    private logger;
+    private heartbeatInterval;
+    private heartbeatIncludeStatus;
+    private reconnectMaxAttempts;
+    private reconnectBaseDelay;
+    private reconnectMaxDelay;
+    private initialized;
+    private isReconnecting;
+    private isShuttingDown;
+    private reconnectAttempts;
+    private reconnectTimer?;
+    private heartbeatTimer?;
+    private stats;
+    private maxClients;
+    private lastEventReceivedAt;
+    constructor(connectionString: string, channels: string[], config: NotificationsPluginConfig, logger: Logger);
+    /**
+     * Helper to safely truncate IDs for logging
+     */
+    private truncateId;
+    /**
+     * Initialize the manager - connect to PostgreSQL and start LISTEN
+     */
+    initialize(): Promise<void>;
+    /**
+     * Connect to PostgreSQL and set up LISTEN
+     */
+    private connect;
+    /**
+     * Handle PostgreSQL connection error
+     */
+    private handleConnectionError;
+    /**
+     * Handle incoming notification from PostgreSQL
+     */
+    private handleNotification;
+    /**
+     * Route event to matching SSE clients
+     */
+    private routeEvent;
+    /**
+     * Filter clients based on device_id or user_id
+     */
+    private filterClients;
+    /**
+     * Send SSE event to a client
+     */
+    private sendEvent;
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    private scheduleReconnect;
+    /**
+     * Clean up existing PostgreSQL connection
+     */
+    private cleanupConnection;
+    /**
+     * Sanitize channel name to prevent SQL injection
+     */
+    private sanitizeChannelName;
+    /**
+     * Register a new SSE client
+     * @returns true if registered, false if at capacity
+     */
+    registerClient(id: string, deviceId: string | undefined, userId: string | undefined, response: Response): boolean;
+    /**
+     * Unregister a client
+     */
+    private unregisterClient;
+    /**
+     * 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 connected clients
+     */
+    broadcastToAll(eventType: string, payload: unknown): number;
+    /**
+     * Start heartbeat system
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat system
+     */
+    private stopHeartbeat;
+    /**
+     * Get list of connected clients
+     */
+    getClients(): Array<{
+        id: string;
+        deviceId?: string;
+        userId?: string;
+        connectedAt: string;
+        durationMs: number;
+    }>;
+    /**
+     * Disconnect a specific client by ID
+     * @param clientId - The client ID to disconnect
+     * @param disconnectedBy - Optional info about who initiated the disconnect (for audit logging)
+     * @returns true if client was found and disconnected, false otherwise
+     */
+    disconnectClient(clientId: string, disconnectedBy?: {
+        userId?: string;
+        email?: string;
+        ip?: string;
+    }): boolean;
+    /**
+     * Get current statistics
+     */
+    getStats(): NotificationsStats;
+    /**
+     * Get connection health status
+     */
+    getConnectionHealth(): ConnectionHealth;
+    /**
+     * Force reconnection - useful for recovery
+     */
+    forceReconnect(): Promise<void>;
+    /**
+     * Shutdown the manager
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Set the notifications manager singleton
+ */
+export declare function setNotificationsManager(manager: NotificationsManager | null): void;
+/**
+ * Get the notifications manager singleton
+ * @throws Error if manager is not initialized
+ */
+export declare function getNotificationsManager(): NotificationsManager;
+/**
+ * Check if notifications manager is available
+ */
+export declare function hasNotificationsManager(): boolean;
+/**
+ * Broadcast event to a specific device
+ * @returns Number of clients the event was sent to
+ */
+export declare function broadcastToDevice(deviceId: string, eventType: string, payload: unknown): number;
+/**
+ * Broadcast event to all devices for a user
+ * @returns Number of clients the event was sent to
+ */
+export declare function broadcastToUser(userId: string, eventType: string, payload: unknown): number;
+/**
+ * Broadcast event to all connected clients
+ * @returns Number of clients the event was sent to
+ */
+export declare function broadcastToAll(eventType: string, payload: unknown): number;
+//# sourceMappingURL=notifications-manager.d.ts.map

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

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