payload-socket-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bibek Thapa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,381 @@
+# Payload Socket Plugin
+
+[![npm version](https://badge.fury.io/js/payload-socket-plugin.svg)](https://www.npmjs.com/package/payload-socket-plugin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/payload-socket-plugin.svg)](https://nodejs.org)
+
+Real-time event broadcasting plugin for Payload CMS using Socket.IO with Redis support for multi-instance deployments.
+
+## Features
+
+- ✅ **Real-time Events**: Broadcast collection changes (create, update, delete) to connected clients
+- ✅ **Redis Support**: Multi-instance synchronization using Redis adapter
+- ✅ **Per-Collection Authorization**: Fine-grained control over who receives events
+- ✅ **JWT Authentication**: Secure WebSocket connections using Payload's JWT tokens
+- ✅ **TypeScript**: Full type safety with TypeScript definitions
+- ✅ **Flexible Configuration**: Customize CORS, paths, and event handling
+
+## Prerequisites
+
+- **Node.js**: >= 20.0.0
+- **Payload CMS**: >= 2.0.0
+- **Redis** (optional): Required for multi-instance deployments
+
+## Installation
+
+```bash
+npm install payload-socket-plugin
+# or
+yarn add payload-socket-plugin
+# or
+pnpm add payload-socket-plugin
+```
+
+### Install Socket.IO Client (for frontend)
+
+```bash
+npm install socket.io-client
+```
+
+## Quick Start
+
+### 1. Configure the Plugin
+
+```typescript
+// payload.config.ts
+import { buildConfig } from "payload/config";
+import { socketPlugin } from "payload-socket-plugin";
+
+export default buildConfig({
+  // ... other config
+  plugins: [
+    socketPlugin({
+      enabled: true,
+      redis: {
+        url: process.env.REDIS_URL,
+      },
+      socketIO: {
+        cors: {
+          origin: ["http://localhost:3000"],
+          credentials: true,
+        },
+        path: "/socket.io",
+      },
+      includeCollections: ["projects", "posts"],
+      authorize: {
+        projects: async (user, event) => {
+          // Only allow project owner to receive events
+          return user.id === event.doc.user;
+        },
+        posts: async (user, event) => {
+          // Allow everyone to receive public post events
+          return event.doc.isPublic || user.id === event.doc.user;
+        },
+      },
+    }),
+  ],
+});
+```
+
+### 2. Initialize Socket.IO Server
+
+```typescript
+// server.ts
+import express from "express";
+import payload from "payload";
+import { initSocketIO } from "payload-socket-plugin";
+
+const app = express();
+
+// Initialize Payload
+await payload.init({
+  secret: process.env.PAYLOAD_SECRET,
+  express: app,
+});
+
+// Start HTTP server
+const server = app.listen(3000, () => {
+  console.log("Server running on port 3000");
+});
+
+// Initialize Socket.IO
+await initSocketIO(server);
+```
+
+### 3. Connect from Client
+
+```typescript
+// client.ts
+import { io } from "socket.io-client";
+
+const socket = io("http://localhost:3000", {
+  auth: {
+    token: "your-jwt-token", // Get from Payload login
+  },
+});
+
+// Subscribe to collection events
+socket.emit("join-collection", "projects");
+
+// Listen for events
+socket.on("payload:event", (event) => {
+  console.log("Event received:", event);
+  // {
+  //   type: 'update',
+  //   collection: 'projects',
+  //   id: '123',
+  //   doc: { ... },
+  //   user: { id: '456', email: 'user@example.com' },
+  //   timestamp: '2024-01-01T00:00:00.000Z'
+  // }
+});
+```
+
+## Configuration Options
+
+### `RealtimeEventsPluginOptions`
+
+| Option               | Type       | Default | Description                                             |
+| -------------------- | ---------- | ------- | ------------------------------------------------------- |
+| `enabled`            | `boolean`  | `true`  | Enable/disable the plugin                               |
+| `includeCollections` | `string[]` | `[]`    | Collections to enable real-time events for              |
+| `redis`              | `object`   | -       | Redis configuration for multi-instance support          |
+| `socketIO`           | `object`   | -       | Socket.IO server options (CORS, path, etc.)             |
+| `authorize`          | `object`   | -       | Per-collection authorization handlers                   |
+| `shouldEmit`         | `function` | -       | Filter function to determine if event should be emitted |
+| `transformEvent`     | `function` | -       | Transform events before emitting                        |
+
+## Authorization
+
+Authorization handlers determine which users can receive events for specific documents.
+
+```typescript
+import type { CollectionAuthorizationHandler } from "payload-socket-plugin";
+
+const authorizeProject: CollectionAuthorizationHandler = async (
+  user,
+  event
+) => {
+  // Admin can see all events
+  if (user.role === "admin") {
+    return true;
+  }
+
+  // Check if user owns the project
+  const project = await payload.findByID({
+    collection: "projects",
+    id: event.id as string,
+  });
+
+  return user.id === project.user;
+};
+
+// Use in plugin config
+socketPlugin({
+  authorize: {
+    projects: authorizeProject,
+  },
+});
+```
+
+## Client Events
+
+### Subscribing to Collections
+
+```typescript
+// Subscribe to a single collection
+socket.emit("join-collection", "projects");
+
+// Subscribe to multiple collections
+socket.emit("subscribe", ["projects", "posts"]);
+
+// Unsubscribe
+socket.emit("unsubscribe", ["projects"]);
+```
+
+### Listening for Events
+
+```typescript
+// Listen to specific collection events
+socket.on("payload:event", (event) => {
+  if (event.collection === "projects" && event.type === "update") {
+    // Handle project update
+  }
+});
+
+// Listen to all events
+socket.on("payload:event:all", (event) => {
+  console.log("Any event:", event);
+});
+```
+
+## Advanced Usage
+
+### Custom Event Filtering
+
+```typescript
+socketPlugin({
+  shouldEmit: (event) => {
+    // Only emit events for published documents
+    return event.doc?.status === "published";
+  },
+});
+```
+
+### Event Transformation
+
+```typescript
+socketPlugin({
+  transformEvent: (event) => {
+    // Remove sensitive data before emitting
+    const { doc, ...rest } = event;
+    return {
+      ...rest,
+      doc: {
+        id: doc.id,
+        title: doc.title,
+        // Omit sensitive fields
+      },
+    };
+  },
+});
+```
+
+## How It Works
+
+```
+┌─────────────┐         ┌──────────────┐         ┌─────────────┐
+│   Client    │◄───────►│  Socket.IO   │◄───────►│   Payload   │
+│ (Browser)   │  WebSocket │   Server     │  Hooks  │    CMS      │
+└─────────────┘         └──────────────┘         └─────────────┘
+                              │
+                              ▼
+                        ┌──────────────┐
+                        │    Redis     │
+                        │   Adapter    │
+                        └──────────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    ▼                   ▼
+              ┌──────────┐        ┌──────────┐
+              │ Instance │        │ Instance │
+              │    1     │        │    2     │
+              └──────────┘        └──────────┘
+```
+
+**Flow:**
+
+1. Plugin hooks into Payload's `afterChange` and `afterDelete` lifecycle events
+2. When a document changes, the plugin creates an event payload
+3. Event is broadcast via Socket.IO to all connected clients
+4. Authorization handlers determine which users receive the event
+5. Redis adapter ensures events sync across multiple server instances
+
+## Environment Variables
+
+```bash
+# Required for Redis multi-instance support
+REDIS_URL=redis://localhost:6379
+
+# Optional: Payload configuration
+PAYLOAD_SECRET=your-secret-key
+```
+
+## TypeScript Types
+
+```typescript
+import type {
+  CollectionAuthorizationHandler,
+  RealtimeEventPayload,
+  AuthenticatedSocket,
+  EventType,
+} from "payload-socket-plugin";
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem**: Client can't connect to Socket.IO server
+
+**Solutions**:
+
+- Verify CORS settings in `socketIO.cors` configuration
+- Check that `initSocketIO()` is called after starting the HTTP server
+- Ensure the Socket.IO path matches between server and client (default: `/socket.io`)
+- Verify JWT token is valid and not expired
+
+### Events Not Received
+
+**Problem**: Connected but not receiving events
+
+**Solutions**:
+
+- Check that you've subscribed to the collection: `socket.emit('join-collection', 'collectionName')`
+- Verify the collection is in `includeCollections` array
+- Check authorization handler - it may be blocking events for your user
+- Ensure the event type (create/update/delete) is being triggered
+
+### Redis Connection Issues
+
+**Problem**: Redis adapter not working in multi-instance setup
+
+**Solutions**:
+
+- Verify `REDIS_URL` environment variable is set correctly
+- Check Redis server is running and accessible
+- Ensure both server instances use the same Redis URL
+- Check Redis logs for connection errors
+
+### TypeScript Errors
+
+**Problem**: Type errors when using the plugin
+
+**Solutions**:
+
+- Ensure `payload-socket-plugin` types are installed
+- Check that your `tsconfig.json` includes the plugin's types
+- Verify Payload CMS version compatibility (>= 2.0.0)
+
+## Performance Considerations
+
+- **Redis**: Highly recommended for production multi-instance deployments
+- **Authorization**: Keep authorization handlers lightweight - they run on every event
+- **Event Filtering**: Use `shouldEmit` to reduce unnecessary events
+- **Event Transformation**: Use `transformEvent` to minimize payload size
+
+## Security Considerations
+
+- **JWT Authentication**: All connections require valid Payload JWT tokens
+- **Authorization Handlers**: Always implement proper authorization to prevent data leaks
+- **CORS**: Configure CORS carefully to only allow trusted origins
+- **Event Data**: Be cautious about sensitive data in events - use `transformEvent` to sanitize
+
+## Known Limitations
+
+- Only supports Payload CMS v2.x (v3.x support coming soon)
+- Authorization handlers are called for each connected user on every event
+- No built-in event replay or history mechanism
+- Redis is required for multi-instance deployments
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+## License
+
+MIT © [Bibek Thapa](https://github.com/beewhoo)
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Support
+
+For issues and questions, please [open a GitHub issue](https://github.com/beewhoo/payload-socket-plugin/issues).

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Plugin } from "payload/config";
+import { RealtimeEventsPluginOptions } from "./types";
+/**
+ * Payload CMS Plugin for Real-time Events
+ *
+ * This plugin enables real-time event broadcasting for collection changes
+ * using Socket.IO with Redis adapter for multi-instance support.
+ *
+ * @example
+ * ```ts
+ * import { socketPlugin } from 'payload-socket-plugin';
+ *
+ * export default buildConfig({
+ *   plugins: [
+ *     socketPlugin({
+ *       enabled: true,
+ *       redis: {
+ *         url: process.env.REDIS_URL,
+ *       },
+ *       socketIO: {
+ *         cors: {
+ *           origin: ['http://localhost:3000'],
+ *           credentials: true,
+ *         },
+ *       },
+ *       includeCollections: ['projects', 'actors'],
+ *       authorize: {
+ *         projects: async (user, event) => {
+ *           // Your authorization logic
+ *           return user.id === event.doc.user;
+ *         }
+ *       }
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare const socketPlugin: (pluginOptions?: RealtimeEventsPluginOptions) => Plugin;
+export * from "./types";
+export { SocketIOManager } from "./socketManager";
+export { initSocketIO } from "./initSocketIO";

package/dist/index.js

@@ -0,0 +1,171 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initSocketIO = exports.SocketIOManager = exports.socketPlugin = void 0;
+const socketManager_1 = require("./socketManager");
+/**
+ * Payload CMS Plugin for Real-time Events
+ *
+ * This plugin enables real-time event broadcasting for collection changes
+ * using Socket.IO with Redis adapter for multi-instance support.
+ *
+ * @example
+ * ```ts
+ * import { socketPlugin } from 'payload-socket-plugin';
+ *
+ * export default buildConfig({
+ *   plugins: [
+ *     socketPlugin({
+ *       enabled: true,
+ *       redis: {
+ *         url: process.env.REDIS_URL,
+ *       },
+ *       socketIO: {
+ *         cors: {
+ *           origin: ['http://localhost:3000'],
+ *           credentials: true,
+ *         },
+ *       },
+ *       includeCollections: ['projects', 'actors'],
+ *       authorize: {
+ *         projects: async (user, event) => {
+ *           // Your authorization logic
+ *           return user.id === event.doc.user;
+ *         }
+ *       }
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+const socketPlugin = (pluginOptions = {}) => {
+    return (incomingConfig) => {
+        // Default options
+        const options = {
+            enabled: true,
+            includeCollections: [],
+            ...pluginOptions,
+        };
+        // If plugin is disabled, return config unchanged
+        if (options.enabled === false) {
+            return incomingConfig;
+        }
+        const socketManager = new socketManager_1.SocketIOManager(options);
+        /**
+         * Helper function to check if events should be emitted for a collection
+         */
+        const shouldEmitForCollection = (collectionSlug) => {
+            // Only emit for collections explicitly included
+            if (options.includeCollections && options.includeCollections.length > 0) {
+                return options.includeCollections.includes(collectionSlug);
+            }
+            // If no collections specified, don't emit for any
+            return false;
+        };
+        /**
+         * Create event payload from hook arguments
+         */
+        const createEventPayload = (type, collection, args) => {
+            return {
+                type,
+                collection,
+                id: args.doc?.id || args.id,
+                doc: type === "delete" ? undefined : args.doc,
+                user: args.req?.user
+                    ? {
+                        id: args.req.user.id,
+                        email: args.req.user.email,
+                        collection: args.req.user.collection,
+                    }
+                    : undefined,
+                timestamp: new Date().toISOString(),
+            };
+        };
+        /**
+         * Add hooks to collections
+         */
+        const collectionsWithHooks = incomingConfig.collections?.map((collection) => {
+            // Skip if events should not be emitted for this collection
+            if (!shouldEmitForCollection(collection.slug)) {
+                return collection;
+            }
+            return {
+                ...collection,
+                hooks: {
+                    ...collection.hooks,
+                    // After change hook - only emit for updates
+                    afterChange: [
+                        ...(collection.hooks?.afterChange || []),
+                        async (args) => {
+                            try {
+                                // Only emit events for updates, not creates
+                                if (args.operation !== "update") {
+                                    return;
+                                }
+                                const event = createEventPayload("update", collection.slug, args);
+                                await socketManager.emitEvent(event);
+                            }
+                            catch (error) {
+                                console.error(`Error emitting update event for ${collection.slug}:`, error);
+                            }
+                        },
+                    ],
+                    // After delete hook
+                    afterDelete: [
+                        ...(collection.hooks?.afterDelete || []),
+                        async (args) => {
+                            try {
+                                const event = createEventPayload("delete", collection.slug, args);
+                                await socketManager.emitEvent(event);
+                            }
+                            catch (error) {
+                                console.error(`Error emitting delete event for ${collection.slug}:`, error);
+                            }
+                        },
+                    ],
+                },
+            };
+        }) || [];
+        /**
+         * Add onInit hook to initialize Socket.IO server
+         */
+        const onInit = async (payload) => {
+            // Call original onInit if it exists
+            if (incomingConfig.onInit) {
+                await incomingConfig.onInit(payload);
+            }
+            // Initialize Socket.IO server
+            // The server instance is available after Payload initializes with Express
+            if (payload.express) {
+                // Store the socket manager for later initialization
+                // The HTTP server will be initialized in server.ts using initSocketIO()
+                payload.__socketManager = socketManager;
+            }
+        };
+        return {
+            ...incomingConfig,
+            collections: collectionsWithHooks,
+            onInit,
+        };
+    };
+};
+exports.socketPlugin = socketPlugin;
+// Export types for external use
+__exportStar(require("./types"), exports);
+var socketManager_2 = require("./socketManager");
+Object.defineProperty(exports, "SocketIOManager", { enumerable: true, get: function () { return socketManager_2.SocketIOManager; } });
+var initSocketIO_1 = require("./initSocketIO");
+Object.defineProperty(exports, "initSocketIO", { enumerable: true, get: function () { return initSocketIO_1.initSocketIO; } });

package/dist/initSocketIO.d.ts

@@ -0,0 +1,18 @@
+import { Server as HTTPServer } from "http";
+/**
+ * Initialize Socket.IO server with the HTTP server instance
+ * This should be called after the HTTP server is created
+ *
+ * @example
+ * ```ts
+ * import { initSocketIO } from 'payload-socket-plugin';
+ *
+ * const server = app.listen(PORT, () => {
+ *   console.log(`Server is running on port ${PORT}`);
+ * });
+ *
+ * // Initialize Socket.IO
+ * await initSocketIO(server);
+ * ```
+ */
+export declare function initSocketIO(httpServer: HTTPServer): Promise<void>;

package/dist/initSocketIO.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initSocketIO = initSocketIO;
+const payload_1 = __importDefault(require("payload"));
+/**
+ * Initialize Socket.IO server with the HTTP server instance
+ * This should be called after the HTTP server is created
+ *
+ * @example
+ * ```ts
+ * import { initSocketIO } from 'payload-socket-plugin';
+ *
+ * const server = app.listen(PORT, () => {
+ *   console.log(`Server is running on port ${PORT}`);
+ * });
+ *
+ * // Initialize Socket.IO
+ * await initSocketIO(server);
+ * ```
+ */
+async function initSocketIO(httpServer) {
+    try {
+        // Get the socket manager from payload instance
+        const socketManager = payload_1.default.__socketManager;
+        if (!socketManager) {
+            payload_1.default.logger.warn("Socket.IO manager not found. Make sure socketPlugin is configured.");
+            return;
+        }
+        // Initialize Socket.IO with the HTTP server
+        await socketManager.init(httpServer);
+        payload_1.default.logger.info("Socket.IO initialized successfully");
+    }
+    catch (error) {
+        payload_1.default.logger.error("Failed to initialize Socket.IO:", error);
+        throw error;
+    }
+}

package/dist/mock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mock module for socket plugin
+ * Used by webpack to prevent bundling server-side Socket.IO code in the admin panel
+ *
+ * This is aliased in payload.config.ts webpack configuration:
+ * [socketPluginPath]: socketPluginMockPath
+ */
+import { Config } from "payload/config";
+/**
+ * Mock plugin that does nothing
+ * The real plugin is only used on the server side
+ */
+export declare const socketPlugin: () => (config: Config) => Config;

package/dist/mock.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Mock module for socket plugin
+ * Used by webpack to prevent bundling server-side Socket.IO code in the admin panel
+ *
+ * This is aliased in payload.config.ts webpack configuration:
+ * [socketPluginPath]: socketPluginMockPath
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.socketPlugin = void 0;
+/**
+ * Mock plugin that does nothing
+ * The real plugin is only used on the server side
+ */
+const socketPlugin = () => (config) => {
+    // Return config unchanged - no Socket.IO in admin panel
+    return config;
+};
+exports.socketPlugin = socketPlugin;

package/dist/socketManager.d.ts

@@ -0,0 +1,47 @@
+import { Server as SocketIOServer } from "socket.io";
+import { Server as HTTPServer } from "http";
+import { RealtimeEventsPluginOptions, RealtimeEventPayload } from "./types";
+/**
+ * Socket.IO Manager for handling real-time events with Redis adapter
+ * Supports multiple Payload instances for production environments
+ */
+export declare class SocketIOManager {
+    private io;
+    private pubClient;
+    private subClient;
+    private options;
+    constructor(options: RealtimeEventsPluginOptions);
+    /**
+     * Initialize Socket.IO server with Redis adapter
+     */
+    init(server: HTTPServer): Promise<SocketIOServer>;
+    /**
+     * Setup Redis adapter for multi-instance synchronization
+     */
+    private setupRedisAdapter;
+    /**
+     * Setup authentication middleware for Socket.IO connections
+     */
+    /**
+     * Setup Socket.IO authentication middleware
+     * Verifies JWT tokens sent from clients (e.g., next-app via socket.handshake.auth.token)
+     * Uses Payload CMS JWT verification and fetches user from database
+     */
+    private setupAuthentication;
+    /**
+     * Setup connection event handlers
+     */
+    private setupConnectionHandlers;
+    /**
+     * Emit a real-time event to all connected clients
+     */
+    emitEvent(event: RealtimeEventPayload): Promise<void>;
+    /**
+     * Get Socket.IO server instance
+     */
+    getIO(): SocketIOServer | null;
+    /**
+     * Cleanup and close connections
+     */
+    close(): Promise<void>;
+}

package/dist/socketManager.js

@@ -0,0 +1,377 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketIOManager = void 0;
+const socket_io_1 = require("socket.io");
+const redis_adapter_1 = require("@socket.io/redis-adapter");
+const ioredis_1 = __importDefault(require("ioredis"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const payload_1 = __importDefault(require("payload"));
+/**
+ * Socket.IO Manager for handling real-time events with Redis adapter
+ * Supports multiple Payload instances for production environments
+ */
+class SocketIOManager {
+    constructor(options) {
+        this.io = null;
+        this.pubClient = null;
+        this.subClient = null;
+        this.options = options;
+    }
+    /**
+     * Initialize Socket.IO server with Redis adapter
+     */
+    async init(server) {
+        const { redis, socketIO = {} } = this.options;
+        // Create Socket.IO server
+        this.io = new socket_io_1.Server(server, {
+            path: socketIO.path || "/socket.io",
+            cors: socketIO.cors || {
+                origin: "*",
+                credentials: true,
+            },
+            ...socketIO,
+        });
+        // Setup Redis adapter
+        if (redis) {
+            await this.setupRedisAdapter();
+        }
+        // Setup authentication middleware
+        this.setupAuthentication();
+        // Setup connection handlers
+        this.setupConnectionHandlers();
+        payload_1.default.logger.info("Socket.IO server initialized with real-time events plugin");
+        return this.io;
+    }
+    /**
+     * Setup Redis adapter for multi-instance synchronization
+     */
+    async setupRedisAdapter() {
+        const redisUrl = process.env.REDIS_URL;
+        if (!redisUrl) {
+            payload_1.default.logger.warn("REDIS_URL not configured. Skipping Redis adapter setup.");
+            return;
+        }
+        try {
+            this.pubClient = new ioredis_1.default(redisUrl, {
+                keyPrefix: "socket.io:",
+                retryStrategy: (times) => {
+                    const delay = Math.min(times * 50, 2000);
+                    return delay;
+                },
+            });
+            this.subClient = this.pubClient.duplicate();
+            await Promise.all([
+                new Promise((resolve) => this.pubClient.once("ready", resolve)),
+                new Promise((resolve) => this.subClient.once("ready", resolve)),
+            ]);
+            this.io.adapter((0, redis_adapter_1.createAdapter)(this.pubClient, this.subClient));
+            payload_1.default.logger.info("Redis adapter configured for Socket.IO multi-instance support");
+        }
+        catch (error) {
+            payload_1.default.logger.error("Failed to setup Redis adapter:", error);
+            throw error;
+        }
+    }
+    /**
+     * Setup authentication middleware for Socket.IO connections
+     */
+    /**
+     * Setup Socket.IO authentication middleware
+     * Verifies JWT tokens sent from clients (e.g., next-app via socket.handshake.auth.token)
+     * Uses Payload CMS JWT verification and fetches user from database
+     */
+    setupAuthentication() {
+        this.io.use(async (socket, next) => {
+            try {
+                const token = socket.handshake.auth.token;
+                if (!token) {
+                    return next(new Error("Authentication token required"));
+                }
+                try {
+                    const decoded = jsonwebtoken_1.default.verify(token, payload_1.default.secret);
+                    // Fetch full user document from Payload
+                    const userDoc = await payload_1.default.findByID({
+                        collection: decoded.collection || "users",
+                        id: decoded.id,
+                    });
+                    if (!userDoc) {
+                        return next(new Error("User not found"));
+                    }
+                    // Attach user info
+                    socket.user = {
+                        id: userDoc.id,
+                        email: userDoc.email,
+                        collection: decoded.collection || "users",
+                        role: userDoc.role,
+                    };
+                    next();
+                }
+                catch (jwtError) {
+                    return next(new Error("Invalid authentication token"));
+                }
+            }
+            catch (error) {
+                payload_1.default.logger.error("Socket authentication error:", error);
+                next(new Error("Authentication failed"));
+            }
+        });
+    }
+    /**
+     * Setup connection event handlers
+     */
+    setupConnectionHandlers() {
+        this.io.on("connection", (socket) => {
+            payload_1.default.logger.info(`Client connected: ${socket.id}, User: ${socket.user?.email || socket.user?.id}`);
+            // Allow clients to subscribe to specific collections
+            socket.on("subscribe", (collections) => {
+                const collectionList = Array.isArray(collections)
+                    ? collections
+                    : [collections];
+                collectionList.forEach((collection) => {
+                    socket.join(`collection:${collection}`);
+                    payload_1.default.logger.info(`Client ${socket.id} subscribed to collection: ${collection}`);
+                });
+            });
+            // // Allow clients to unsubscribe from collections
+            socket.on("unsubscribe", (collections) => {
+                const collectionList = Array.isArray(collections)
+                    ? collections
+                    : [collections];
+                collectionList.forEach((collection) => {
+                    socket.leave(`collection:${collection}`);
+                    payload_1.default.logger.info(`Client ${socket.id} unsubscribed from collection: ${collection}`);
+                });
+            });
+            // Allow clients to join collection rooms to receive update events
+            socket.on("join-collection", (collection) => {
+                const roomName = `collection:${collection}`;
+                socket.join(roomName);
+                payload_1.default.logger.info(`Client ${socket.id} (${socket.user?.email}) joined collection room: ${roomName}`);
+            });
+            // Project room handlers for presence tracking
+            socket.on("join-project", async (projectId) => {
+                if (!projectId) {
+                    payload_1.default.logger.warn(`Client ${socket.id} tried to join project without ID`);
+                    return;
+                }
+                // Check if user has permission to join this project
+                try {
+                    const project = await payload_1.default.findByID({
+                        collection: "projects",
+                        id: projectId,
+                        depth: 0,
+                    });
+                    const projectOwnerId = typeof project.user === "string"
+                        ? project.user
+                        : project.user?.id;
+                    const isOwner = socket.user.id === projectOwnerId;
+                    // Check if user has editor invitation
+                    const invitation = await payload_1.default.find({
+                        collection: "projectInvitations",
+                        depth: 0,
+                        where: {
+                            user: { equals: socket.user.id },
+                            status: { equals: "accepted" },
+                            project: { equals: projectId },
+                            role: { equals: "editor" },
+                        },
+                        limit: 1,
+                    });
+                    const hasEditorInvite = invitation.docs.length > 0;
+                    // Only allow owner, users with editor invitation
+                    if (!isOwner && !hasEditorInvite) {
+                        payload_1.default.logger.warn(`Client ${socket.id} (${socket.user?.email}) denied access to project ${projectId} - no editor permission`);
+                        socket.emit("join-project-error", {
+                            message: "You need editor access to join this project room",
+                        });
+                        return;
+                    }
+                }
+                catch (error) {
+                    payload_1.default.logger.error("Error checking project permissions:", error);
+                    socket.emit("join-project-error", {
+                        message: "Failed to verify project permissions",
+                    });
+                    return;
+                }
+                const roomName = `project:${projectId}:room`;
+                await socket.join(roomName);
+                payload_1.default.logger.info(`Client ${socket.id} (${socket.user?.email || socket.user?.id}) joined project: ${projectId}, room: ${roomName}`);
+                // Debug: Log all rooms this socket is in
+                payload_1.default.logger.info(`Socket ${socket.id} is now in rooms: ${Array.from(socket.rooms).join(", ")}`);
+                // Get all sockets in this project room
+                const socketsInRoom = await this.io.in(roomName).fetchSockets();
+                // Build list of active users
+                const activeUsers = socketsInRoom
+                    .map((s) => {
+                    if (s.user) {
+                        return {
+                            id: s.user.id,
+                            email: s.user.email || undefined,
+                        };
+                    }
+                    return null;
+                })
+                    .filter((u) => u !== null);
+                // Remove duplicates (same user, multiple tabs)
+                const uniqueUsers = Array.from(new Map(activeUsers.map((u) => [u.id, u])).values());
+                // Send current active users to the joining client
+                socket.emit("project:active-users", uniqueUsers);
+                // Notify others in the room that a new user joined
+                socket.to(roomName).emit("project:user-joined", {
+                    id: socket.user.id,
+                    email: socket.user.email || undefined,
+                });
+            });
+            socket.on("leave-project", (projectId) => {
+                if (!projectId)
+                    return;
+                const roomName = `project:${projectId}:room`;
+                socket.leave(roomName);
+                payload_1.default.logger.info(`Client ${socket.id} left project: ${projectId}`);
+                // Notify others that user left
+                socket.to(roomName).emit("project:user-left", socket.user.id);
+            });
+            socket.on("kick-user", async (data) => {
+                const { projectId, userId } = data;
+                if (!projectId || !userId) {
+                    payload_1.default.logger.warn(`Client ${socket.id} tried to kick user without projectId or userId`);
+                    return;
+                }
+                // Verify the kicker is the project owner
+                try {
+                    const project = await payload_1.default.findByID({
+                        collection: "projects",
+                        id: projectId,
+                    });
+                    const projectOwnerId = typeof project.user === "string"
+                        ? project.user
+                        : project.user?.id;
+                    if (socket.user.id !== projectOwnerId) {
+                        payload_1.default.logger.warn(`Client ${socket.id} (${socket.user?.email}) tried to kick user but is not the owner`);
+                        socket.emit("kick-error", {
+                            message: "Only the project owner can kick users",
+                        });
+                        return;
+                    }
+                    // Find all sockets for the user to kick
+                    const roomName = `project:${projectId}:room`;
+                    const socketsInRoom = await this.io.in(roomName).fetchSockets();
+                    let kicked = false;
+                    for (const s of socketsInRoom) {
+                        const socketUser = s.user;
+                        if (socketUser && socketUser.id === userId) {
+                            // Emit kick event to the user being kicked
+                            s.emit("kicked-from-project", {
+                                projectId,
+                                message: "You have been removed from this project by the owner",
+                            });
+                            // Remove them from the room
+                            s.leave(roomName);
+                            kicked = true;
+                            payload_1.default.logger.info(`User ${userId} (${socketUser.email}) was kicked from project ${projectId} by ${socket.user?.email}`);
+                        }
+                    }
+                    if (kicked) {
+                        // Notify others that user was kicked
+                        socket.to(roomName).emit("project:user-left", userId);
+                        // Confirm to the kicker
+                        socket.emit("kick-success", { userId });
+                    }
+                    else {
+                        socket.emit("kick-error", {
+                            message: "User not found in project",
+                        });
+                    }
+                }
+                catch (error) {
+                    payload_1.default.logger.error("Error kicking user:", error);
+                    socket.emit("kick-error", {
+                        message: "Failed to kick user",
+                    });
+                }
+            });
+            // Handle disconnection - clean up project presence
+            socket.on("disconnect", async () => {
+                payload_1.default.logger.info(`Client disconnected: ${socket.id}, User: ${socket.user?.email || socket.user?.id}`);
+                // Notify all project rooms that this user left
+                // Socket.IO automatically tracks which rooms the socket was in
+                const rooms = Array.from(socket.rooms);
+                for (const room of rooms) {
+                    // Only process project rooms (skip the socket's own room)
+                    if (room.startsWith("project:") && socket.user) {
+                        socket.to(room).emit("project:user-left", socket.user.id);
+                        payload_1.default.logger.info(`Notified room ${room} that user ${socket.user.id} left`);
+                    }
+                }
+            });
+        });
+    }
+    /**
+     * Emit a real-time event to all connected clients
+     */
+    async emitEvent(event) {
+        if (!this.io) {
+            payload_1.default.logger.warn("Socket.IO server not initialized, cannot emit event");
+            return;
+        }
+        const { authorize, shouldEmit, transformEvent } = this.options;
+        // Check if event should be emitted
+        if (shouldEmit && !shouldEmit(event)) {
+            return;
+        }
+        // Transform event if transformer is provided
+        const finalEvent = transformEvent ? transformEvent(event) : event;
+        // Emit to collection-specific room
+        const room = `collection:${event.collection}`;
+        // If authorization is required, emit to each socket individually
+        if (authorize) {
+            // Get the handler for this collection
+            const collectionHandler = authorize[event.collection];
+            if (collectionHandler) {
+                const sockets = await this.io.in(room).fetchSockets();
+                for (const socket of sockets) {
+                    const authSocket = socket;
+                    if (authSocket.user) {
+                        const isAuthorized = await collectionHandler(authSocket.user, finalEvent);
+                        if (isAuthorized) {
+                            socket.emit("payload:event", finalEvent);
+                        }
+                    }
+                }
+            }
+            // If no handler for this collection, don't emit (deny by default)
+        }
+        else {
+            // No authorization configured - emit to all sockets in the room
+            this.io.to(room).emit("payload:event", finalEvent);
+        }
+        // Also emit to a global room for clients listening to all events
+        this.io.emit("payload:event:all", finalEvent);
+    }
+    /**
+     * Get Socket.IO server instance
+     */
+    getIO() {
+        return this.io;
+    }
+    /**
+     * Cleanup and close connections
+     */
+    async close() {
+        if (this.io) {
+            this.io.close();
+        }
+        if (this.pubClient) {
+            await this.pubClient.quit();
+        }
+        if (this.subClient) {
+            await this.subClient.quit();
+        }
+        payload_1.default.logger.info("Socket.IO server closed");
+    }
+}
+exports.SocketIOManager = SocketIOManager;

package/dist/types.d.ts

@@ -0,0 +1,113 @@
+import { Socket } from "socket.io";
+/**
+ * Event types that can be emitted
+ */
+export type EventType = "create" | "update" | "delete";
+/**
+ * Payload for real-time events
+ */
+export interface RealtimeEventPayload {
+    /** Type of event */
+    type: EventType;
+    /** Collection slug */
+    collection: string;
+    /** Document ID */
+    id: string | number;
+    /** Document data (for create/update events) */
+    doc?: any;
+    /** User who triggered the event */
+    user?: {
+        id: string | number;
+        email?: string;
+        collection?: string;
+    };
+    /** Timestamp of the event */
+    timestamp: string;
+}
+/**
+ * Socket.IO server instance with authentication
+ */
+export interface AuthenticatedSocket extends Socket {
+    user?: {
+        id: string | number;
+        email?: string;
+        collection?: string;
+        role?: string;
+    };
+}
+/**
+ * Authorization handler for a specific collection
+ */
+export type CollectionAuthorizationHandler = (user: any, event: RealtimeEventPayload) => Promise<boolean>;
+/**
+ * Plugin configuration options
+ */
+export interface RealtimeEventsPluginOptions {
+    /**
+     * Enable/disable the plugin
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Collections to include for real-time events
+     * Only these collections will have real-time events enabled
+     * If not provided or empty, no collections will have real-time events
+     */
+    includeCollections?: string[];
+    /**
+     * Redis configuration for multi-instance support
+     * Uses REDIS_URL environment variable
+     */
+    redis?: {
+        /** Redis connection URL - uses process.env.REDIS_URL */
+        url?: string;
+    };
+    /**
+     * Socket.IO server options
+     */
+    socketIO?: {
+        /** CORS configuration */
+        cors?: {
+            origin?: string | string[] | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
+            credentials?: boolean;
+        };
+        /** Path for Socket.IO endpoint */
+        path?: string;
+        /** Additional Socket.IO server options */
+        [key: string]: any;
+    };
+    /**
+     * Custom authentication function
+     * If not provided, uses Payload's built-in JWT authentication
+     */
+    authenticate?: (socket: Socket, payload: any) => Promise<any>;
+    /**
+     * Authorization handlers per collection
+     * Map of collection slug to authorization handler function
+     *
+     * @example
+     * ```ts
+     * authorize: {
+     *   projects: async (user, event) => {
+     *     // Check if user can receive this project event
+     *     return user.id === event.doc.user;
+     *   },
+     *   actors: async (user, event) => {
+     *     // Check if user can receive this actor event
+     *     return user.id === event.doc.user;
+     *   }
+     * }
+     * ```
+     */
+    authorize?: {
+        [collectionSlug: string]: CollectionAuthorizationHandler;
+    };
+    /**
+     * Event filter function to determine if an event should be emitted
+     */
+    shouldEmit?: (event: RealtimeEventPayload) => boolean;
+    /**
+     * Custom event transformer
+     */
+    transformEvent?: (event: RealtimeEventPayload) => RealtimeEventPayload;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "payload-socket-plugin",
+  "version": "1.0.0",
+  "description": "Real-time Socket.IO plugin for Payload CMS with Redis support",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "browser": "dist/mock.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "payload",
+    "payload-plugin",
+    "payload-cms",
+    "socketio",
+    "socket.io",
+    "realtime",
+    "websocket",
+    "redis",
+    "real-time-events"
+  ],
+  "author": "Bibek Thapa",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "payload": "^2.0.0"
+  },
+  "dependencies": {
+    "@socket.io/redis-adapter": "^8.0.0",
+    "ioredis": "^5.3.0",
+    "jsonwebtoken": "^9.0.0",
+    "socket.io": "^4.6.0"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "payload": "^2.0.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:beewhoo/payload-socket-plugin.git"
+  },
+  "homepage": "https://github.com/beewhoo/payload-socket-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/beewhoo/payload-socket-plugin/issues"
+  }
+}