@hamak/event-channel-backend 0.5.3

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @hamak/event-channel-backend
+ *
+ * SSE server and Express routes for the event channel.
+ */
+export { EventChannelServer, type EventChannelServerConfig, type ServerEvent } from './server/event-channel-server';
+export { createEventChannelRoutes, type EventChannelRoutesConfig } from './routes/event-channel-routes';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,KAAK,wBAAwB,EAAE,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACpH,OAAO,EAAE,wBAAwB,EAAE,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @hamak/event-channel-backend
+ *
+ * SSE server and Express routes for the event channel.
+ */
+export { EventChannelServer } from './server/event-channel-server';
+export { createEventChannelRoutes } from './routes/event-channel-routes';

package/dist/routes/event-channel-routes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Event Channel Express Routes
+ *
+ * GET  /          - SSE stream endpoint
+ * POST /emit      - Emit a custom event to all clients
+ * POST /dispatch  - Dispatch a remote Redux action to all clients
+ * GET  /status    - Connection statistics
+ */
+import { Router, type Request } from 'express';
+import { EventChannelServer } from '../server/event-channel-server';
+export interface EventChannelRoutesConfig {
+    /** The event channel server instance */
+    server: EventChannelServer;
+    /** Extract a client ID from the request (defaults to IP-based) */
+    getClientId?: (req: Request) => string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+export declare function createEventChannelRoutes(config: EventChannelRoutesConfig): Router;
+//# sourceMappingURL=event-channel-routes.d.ts.map

package/dist/routes/event-channel-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-channel-routes.d.ts","sourceRoot":"","sources":["../../src/routes/event-channel-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAiB,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEpE,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACvC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,CAyFjF"}

package/dist/routes/event-channel-routes.js

@@ -0,0 +1,73 @@
+/**
+ * Event Channel Express Routes
+ *
+ * GET  /          - SSE stream endpoint
+ * POST /emit      - Emit a custom event to all clients
+ * POST /dispatch  - Dispatch a remote Redux action to all clients
+ * GET  /status    - Connection statistics
+ */
+import { Router } from 'express';
+export function createEventChannelRoutes(config) {
+    const { server, debug } = config;
+    const getClientId = config.getClientId ?? ((req) => req.ip ?? 'anonymous');
+    const router = Router();
+    // SSE stream endpoint
+    router.get('/', (req, res) => {
+        const clientId = getClientId(req);
+        // Set SSE headers
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        // Send initial connection event
+        res.write(`data: ${JSON.stringify({ type: 'connected', clientId })}\n\n`);
+        // Register client
+        server.addClient(clientId, res);
+        if (debug) {
+            console.log(`[event-channel] Client connected: ${clientId} (total: ${server.getClientCount()})`);
+        }
+        // Clean up on disconnect
+        req.on('close', () => {
+            server.removeClient(clientId, res);
+            if (debug) {
+                console.log(`[event-channel] Client disconnected: ${clientId} (total: ${server.getClientCount()})`);
+            }
+        });
+    });
+    // Emit a custom event
+    router.post('/emit', (req, res) => {
+        const { type, data, source } = req.body;
+        if (!type) {
+            res.status(400).json({ error: 'Missing required field: type' });
+            return;
+        }
+        server.broadcast(type, data ?? {}, source);
+        if (debug) {
+            console.log(`[event-channel] Event emitted: ${type}`);
+        }
+        res.json({ ok: true, clientCount: server.getClientCount() });
+    });
+    // Dispatch a remote Redux action
+    router.post('/dispatch', (req, res) => {
+        const { actionType, payload, source } = req.body;
+        if (!actionType) {
+            res.status(400).json({ error: 'Missing required field: actionType' });
+            return;
+        }
+        server.dispatchAction(actionType, payload, source);
+        if (debug) {
+            console.log(`[event-channel] Action dispatched: ${actionType}`);
+        }
+        res.json({ ok: true, actionType, clientCount: server.getClientCount() });
+    });
+    // Connection status
+    router.get('/status', (_req, res) => {
+        res.json({
+            connections: server.getClientCount(),
+            uniqueClients: server.getUniqueClientCount(),
+        });
+    });
+    return router;
+}

package/dist/server/event-channel-server.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Event Channel Server
+ *
+ * Manages SSE connections and broadcasts events to connected clients.
+ */
+import type { Response } from 'express';
+export interface EventChannelServerConfig {
+    /** Heartbeat interval in ms. @default 30000 */
+    heartbeatInterval?: number;
+}
+export interface ServerEvent<T = unknown> {
+    id: string;
+    type: string;
+    data: T;
+    timestamp: string;
+    source?: string;
+}
+export declare class EventChannelServer {
+    private clients;
+    private heartbeatTimer;
+    private readonly heartbeatInterval;
+    constructor(config?: EventChannelServerConfig);
+    /** Add a new SSE client connection */
+    addClient(clientId: string, res: Response): void;
+    /** Remove a client connection */
+    removeClient(clientId: string, res: Response): void;
+    /** Broadcast event to all connected clients */
+    broadcast<T>(type: string, data: T, source?: string): void;
+    /** Send event to a specific client */
+    sendToClient<T>(clientId: string, type: string, data: T, source?: string): void;
+    /** Dispatch a remote Redux action to all connected clients */
+    dispatchAction(actionType: string, payload?: unknown, source?: string): void;
+    /** Get total connected client count */
+    getClientCount(): number;
+    /** Get unique client ID count */
+    getUniqueClientCount(): number;
+    /** Destroy and close all connections */
+    destroy(): void;
+    private formatSSE;
+    private startHeartbeat;
+}
+//# sourceMappingURL=event-channel-server.d.ts.map

package/dist/server/event-channel-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-channel-server.d.ts","sourceRoot":"","sources":["../../src/server/event-channel-server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,MAAM,GAAE,wBAA6B;IAKjD,sCAAsC;IACtC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI;IAOhD,iCAAiC;IACjC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI;IAUnD,+CAA+C;IAC/C,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAkB1D,sCAAsC;IACtC,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAmB/E,8DAA8D;IAC9D,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAW5E,uCAAuC;IACvC,cAAc,IAAI,MAAM;IAQxB,iCAAiC;IACjC,oBAAoB,IAAI,MAAM;IAI9B,wCAAwC;IACxC,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,cAAc;CASvB"}

package/dist/server/event-channel-server.js

@@ -0,0 +1,112 @@
+/**
+ * Event Channel Server
+ *
+ * Manages SSE connections and broadcasts events to connected clients.
+ */
+import { randomUUID } from 'crypto';
+export class EventChannelServer {
+    constructor(config = {}) {
+        this.clients = new Map();
+        this.heartbeatTimer = null;
+        this.heartbeatInterval = config.heartbeatInterval ?? 30000;
+        this.startHeartbeat();
+    }
+    /** Add a new SSE client connection */
+    addClient(clientId, res) {
+        if (!this.clients.has(clientId)) {
+            this.clients.set(clientId, new Set());
+        }
+        this.clients.get(clientId).add(res);
+    }
+    /** Remove a client connection */
+    removeClient(clientId, res) {
+        const clientResponses = this.clients.get(clientId);
+        if (clientResponses) {
+            clientResponses.delete(res);
+            if (clientResponses.size === 0) {
+                this.clients.delete(clientId);
+            }
+        }
+    }
+    /** Broadcast event to all connected clients */
+    broadcast(type, data, source) {
+        const event = {
+            id: randomUUID(),
+            type,
+            data,
+            timestamp: new Date().toISOString(),
+            source,
+        };
+        const ssePayload = this.formatSSE(event);
+        for (const responses of this.clients.values()) {
+            for (const res of responses) {
+                res.write(ssePayload);
+            }
+        }
+    }
+    /** Send event to a specific client */
+    sendToClient(clientId, type, data, source) {
+        const responses = this.clients.get(clientId);
+        if (!responses)
+            return;
+        const event = {
+            id: randomUUID(),
+            type,
+            data,
+            timestamp: new Date().toISOString(),
+            source,
+        };
+        const ssePayload = this.formatSSE(event);
+        for (const res of responses) {
+            res.write(ssePayload);
+        }
+    }
+    /** Dispatch a remote Redux action to all connected clients */
+    dispatchAction(actionType, payload, source) {
+        this.broadcast('remote-action', {
+            actionType,
+            payload,
+            meta: {
+                source: source ?? 'server',
+                timestamp: new Date().toISOString(),
+            },
+        }, source);
+    }
+    /** Get total connected client count */
+    getClientCount() {
+        let count = 0;
+        for (const responses of this.clients.values()) {
+            count += responses.size;
+        }
+        return count;
+    }
+    /** Get unique client ID count */
+    getUniqueClientCount() {
+        return this.clients.size;
+    }
+    /** Destroy and close all connections */
+    destroy() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        for (const responses of this.clients.values()) {
+            for (const res of responses) {
+                res.end();
+            }
+        }
+        this.clients.clear();
+    }
+    formatSSE(event) {
+        return `id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+    }
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            for (const responses of this.clients.values()) {
+                for (const res of responses) {
+                    res.write(': heartbeat\n\n');
+                }
+            }
+        }, this.heartbeatInterval);
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hamak/event-channel-backend",
+  "version": "0.5.3",
+  "private": false,
+  "type": "module",
+  "description": "Event channel backend - SSE server and Express routes for remote event dispatch",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amah/app-framework.git",
+    "directory": "packages/event-channel/backend/event-channel-backend"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "express": "^4.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.17",
+    "@types/node": "^20.0.0",
+    "typescript": "~5.4.0",
+    "vitest": "^2.0.0"
+  }
+}