payload-socket-plugin 1.1.4 → 2.0.0

package/README.md

@@ -6,6 +6,9 @@
 
 Real-time event broadcasting plugin for Payload CMS using Socket.IO with Redis support for multi-instance deployments.
 
+> **Version 2.0.0+** supports Payload CMS v3.72.0+
+> For Payload v2, use [v1.x](https://github.com/beewhoo/payload-socket-plugin/tree/v1.1.5)
+
 ## Features
 
 - ✅ **Real-time Events**: Broadcast collection changes (create, update, delete) to connected clients
@@ -18,17 +21,21 @@ Real-time event broadcasting plugin for Payload CMS using Socket.IO with Redis s
 ## Prerequisites
 
 - **Node.js**: >= 20.0.0
-- **Payload CMS**: ^2.0.0 || ^3.0.0
+- **Payload CMS**: ^3.72.0 (for v2.x of this plugin)
 - **Redis** (optional): Required for multi-instance deployments
 
 ## Installation
 
+### For Payload v3 (Current)
+
+```bash
+npm install payload-socket-plugin@^2.0.0
+```
+
+### For Payload v2 (Legacy)
+
 ```bash
-npm install payload-socket-plugin
-# or
-yarn add payload-socket-plugin
-# or
-pnpm add payload-socket-plugin
+npm install payload-socket-plugin@^1.0.0
 ```
 
 ### Install Socket.IO Client (for frontend)
@@ -37,13 +44,13 @@ pnpm add payload-socket-plugin
 npm install socket.io-client
 ```
 
-## Quick Start
+## Quick Start (Payload v3)
 
 ### 1. Configure the Plugin
 
 ```typescript
 // payload.config.ts
-import { buildConfig } from "payload/config";
+import { buildConfig } from "payload";
 import { socketPlugin } from "payload-socket-plugin";
 
 export default buildConfig({
@@ -79,29 +86,42 @@ export default buildConfig({
 });
 ```
 
-### 2. Initialize Socket.IO Server
+### 2. Initialize Socket.IO Server (Next.js Custom Server)
 
 ```typescript
 // server.ts
 import express from "express";
-import payload from "payload";
+import { createServer } from "http";
+import next from "next";
+import { getPayload } from "payload";
 import { initSocketIO } from "payload-socket-plugin";
+import config from "@payload-config";
 
-const app = express();
+const port = parseInt(process.env.PORT || "3000", 10);
+const dev = process.env.NODE_ENV !== "production";
+const app = next({ dev });
+const handle = app.getRequestHandler();
 
-// Initialize Payload
-await payload.init({
-  secret: process.env.PAYLOAD_SECRET,
-  express: app,
-});
+app.prepare().then(async () => {
+  const server = express();
 
-// Start HTTP server
-const server = app.listen(3000, () => {
-  console.log("Server running on port 3000");
-});
+  // Let Next.js handle all routes
+  server.all("*", (req, res) => handle(req, res));
 
-// Initialize Socket.IO
-await initSocketIO(server);
+  // Create HTTP server
+  const httpServer = createServer(server);
+
+  // Get Payload instance
+  const payload = await getPayload({ config });
+
+  // Initialize Socket.IO with the payload instance
+  await initSocketIO(httpServer, payload);
+
+  // Start server
+  httpServer.listen(port, () => {
+    console.log(`Server listening on port ${port}`);
+  });
+});
 ```
 
 ### 3. Connect from Client
@@ -434,6 +454,43 @@ import type {
 - Check that your `tsconfig.json` includes the plugin's types
 - Verify Payload CMS version compatibility (>= 2.0.0)
 
+## Multi-Instance Deployments with Redis
+
+When using Redis adapter for multi-instance deployments, user data is automatically synchronized across all server instances:
+
+- **`socket.data.user`**: Automatically synchronized across servers via Redis adapter
+- **`socket.user`**: Only available on the local server where the socket connected (backward compatibility)
+
+### Accessing User Data in Custom Handlers
+
+```typescript
+socketPlugin({
+  onSocketConnection: (socket, io, payload) => {
+    socket.on("get-active-users", async (roomName) => {
+      const sockets = await io.in(roomName).fetchSockets();
+
+      const users = sockets.map((s) => {
+        // Use socket.data.user for Redis compatibility (works across all servers)
+        // Fallback to socket.user for local connections
+        const user = s.data.user || (s as any).user;
+        return {
+          id: user?.id,
+          email: user?.email,
+        };
+      });
+
+      socket.emit("active-users", users);
+    });
+  },
+});
+```
+
+**Important**: When using `io.in(room).fetchSockets()` with Redis adapter:
+
+- Remote sockets (from other servers) will have `socket.data.user` populated
+- Local sockets will have both `socket.data.user` and `socket.user` populated
+- Always check `socket.data.user` first for Redis compatibility
+
 ## Performance Considerations
 
 - **Redis**: Highly recommended for production multi-instance deployments
@@ -454,6 +511,99 @@ import type {
 - No built-in event replay or history mechanism
 - Redis is required for multi-instance deployments
 
+## Migration Guide
+
+### Migrating from v1.x (Payload v2) to v2.x (Payload v3)
+
+Version 2.0.0 introduces breaking changes to support Payload CMS v3:
+
+#### 1. Update Dependencies
+
+```bash
+npm install payload@^3.72.0 payload-socket-plugin@^2.0.0
+```
+
+#### 2. Update Import Paths
+
+```typescript
+// ❌ Old (v1.x)
+import { buildConfig } from "payload/config";
+
+// ✅ New (v2.x)
+import { buildConfig } from "payload";
+```
+
+#### 3. Update Server Initialization
+
+The `initSocketIO` function now requires the Payload instance as a parameter:
+
+```typescript
+// ❌ Old (v1.x)
+import payload from "payload";
+import { initSocketIO } from "payload-socket-plugin";
+
+await payload.init({ secret, express: app });
+const server = app.listen(3000);
+await initSocketIO(server);
+```
+
+```typescript
+// ✅ New (v2.x)
+import { getPayload } from "payload";
+import { initSocketIO } from "payload-socket-plugin";
+import config from "@payload-config";
+
+const payload = await getPayload({ config });
+const httpServer = createServer(app);
+await initSocketIO(httpServer, payload);
+```
+
+#### 4. Update Next.js Integration
+
+Payload v3 uses Next.js by default. Update your server setup:
+
+```typescript
+// server.ts (Payload v3 with Next.js)
+import express from "express";
+import { createServer } from "http";
+import next from "next";
+import { getPayload } from "payload";
+import { initSocketIO } from "payload-socket-plugin";
+import config from "@payload-config";
+
+const app = next({ dev: process.env.NODE_ENV !== "production" });
+const handle = app.getRequestHandler();
+
+app.prepare().then(async () => {
+  const server = express();
+  server.all("*", (req, res) => handle(req, res));
+
+  const httpServer = createServer(server);
+  const payload = await getPayload({ config });
+
+  await initSocketIO(httpServer, payload);
+
+  httpServer.listen(3000);
+});
+```
+
+#### 5. Environment Variables
+
+Make sure to set `SOCKET_ENABLED=true` in your `.env` file if you're using the `enabled` option:
+
+```bash
+# .env
+SOCKET_ENABLED=true
+REDIS_URL=redis://localhost:6379
+```
+
+#### Breaking Changes Summary
+
+- **Minimum Payload version**: Now requires Payload v3.72.0+
+- **`initSocketIO` signature**: Now requires `(httpServer, payloadInstance)` instead of just `(httpServer)`
+- **Import paths**: Changed from `payload/config` to `payload`
+- **Payload initialization**: Use `getPayload({ config })` instead of `payload.init()`
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history.

package/dist/index.js

@@ -53,6 +53,7 @@ const socketManager_1 = require("./socketManager");
  */
 const socketPlugin = (pluginOptions = {}) => {
     return (incomingConfig) => {
+        var _a;
         // Default options
         const options = {
             enabled: true,
@@ -79,12 +80,13 @@ const socketPlugin = (pluginOptions = {}) => {
          * Create event payload from hook arguments
          */
         const createEventPayload = (type, collection, args) => {
+            var _a, _b;
             return {
                 type,
                 collection,
-                id: args.doc?.id || args.id,
+                id: ((_a = args.doc) === null || _a === void 0 ? void 0 : _a.id) || args.id,
                 doc: type === "delete" ? undefined : args.doc,
-                user: args.req?.user
+                user: ((_b = args.req) === null || _b === void 0 ? void 0 : _b.user)
                     ? {
                         id: args.req.user.id,
                         email: args.req.user.email,
@@ -97,7 +99,8 @@ const socketPlugin = (pluginOptions = {}) => {
         /**
          * Add hooks to collections
          */
-        const collectionsWithHooks = incomingConfig.collections?.map((collection) => {
+        const collectionsWithHooks = ((_a = incomingConfig.collections) === null || _a === void 0 ? void 0 : _a.map((collection) => {
+            var _a, _b;
             // Skip if events should not be emitted for this collection
             if (!shouldEmitForCollection(collection.slug)) {
                 return collection;
@@ -108,7 +111,7 @@ const socketPlugin = (pluginOptions = {}) => {
                     ...collection.hooks,
                     // After change hook - only emit for updates
                     afterChange: [
-                        ...(collection.hooks?.afterChange || []),
+                        ...(((_a = collection.hooks) === null || _a === void 0 ? void 0 : _a.afterChange) || []),
                         async (args) => {
                             try {
                                 // Only emit events for updates, not creates
@@ -125,7 +128,7 @@ const socketPlugin = (pluginOptions = {}) => {
                     ],
                     // After delete hook
                     afterDelete: [
-                        ...(collection.hooks?.afterDelete || []),
+                        ...(((_b = collection.hooks) === null || _b === void 0 ? void 0 : _b.afterDelete) || []),
                         async (args) => {
                             try {
                                 const event = createEventPayload("delete", collection.slug, args);
@@ -138,7 +141,7 @@ const socketPlugin = (pluginOptions = {}) => {
                     ],
                 },
             };
-        }) || [];
+        })) || [];
         /**
          * Add onInit hook to initialize Socket.IO server
          */
@@ -147,13 +150,10 @@ const socketPlugin = (pluginOptions = {}) => {
             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;
-            }
+            // Store the socket manager for later initialization
+            // The HTTP server will be initialized in server.ts using initSocketIO()
+            // This works for both standard Payload server and custom Express servers
+            payload.__socketManager = socketManager;
         };
         return {
             ...incomingConfig,

package/dist/initSocketIO.d.ts

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

package/dist/initSocketIO.js

@@ -1,10 +1,6 @@
 "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
@@ -12,29 +8,34 @@ const payload_1 = __importDefault(require("payload"));
  * @example
  * ```ts
  * import { initSocketIO } from 'payload-socket-plugin';
+ * import { getPayload } from 'payload';
+ * import config from '@payload-config';
+ *
+ * const payload = await getPayload({ config });
  *
  * const server = app.listen(PORT, () => {
  *   console.log(`Server is running on port ${PORT}`);
  * });
  *
  * // Initialize Socket.IO
- * await initSocketIO(server);
+ * await initSocketIO(server, payload);
  * ```
  */
-async function initSocketIO(httpServer) {
+async function initSocketIO(httpServer, payloadInstance) {
     try {
         // Get the socket manager from payload instance
-        const socketManager = payload_1.default.__socketManager;
+        const socketManager = payloadInstance
+            .__socketManager;
         if (!socketManager) {
-            payload_1.default.logger.warn("Socket.IO manager not found. Make sure socketPlugin is configured.");
+            payloadInstance.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");
+        await socketManager.init(httpServer, payloadInstance);
+        payloadInstance.logger.info("Socket.IO initialized successfully");
     }
     catch (error) {
-        payload_1.default.logger.error("Failed to initialize Socket.IO:", error);
+        payloadInstance.logger.error("Failed to initialize Socket.IO:", error);
         throw error;
     }
 }

package/dist/socketManager.d.ts

@@ -1,6 +1,7 @@
 import { Server as SocketIOServer } from "socket.io";
 import { Server as HTTPServer } from "http";
 import { RealtimeEventsPluginOptions, RealtimeEventPayload } from "./types";
+import type { Payload } from "payload";
 /**
  * Socket.IO Manager for handling real-time events with Redis adapter
  * Supports multiple Payload instances for production environments
@@ -10,11 +11,12 @@ export declare class SocketIOManager {
     private pubClient;
     private subClient;
     private options;
+    private payload;
     constructor(options: RealtimeEventsPluginOptions);
     /**
      * Initialize Socket.IO server with Redis adapter
      */
-    init(server: HTTPServer): Promise<SocketIOServer>;
+    init(server: HTTPServer, payloadInstance: Payload): Promise<SocketIOServer>;
     /**
      * Setup Redis adapter for multi-instance synchronization
      */

package/dist/socketManager.js

@@ -8,7 +8,6 @@ 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
@@ -18,12 +17,14 @@ class SocketIOManager {
         this.io = null;
         this.pubClient = null;
         this.subClient = null;
+        this.payload = null;
         this.options = options;
     }
     /**
      * Initialize Socket.IO server with Redis adapter
      */
-    async init(server) {
+    async init(server, payloadInstance) {
+        this.payload = payloadInstance;
         const { redis, socketIO = {} } = this.options;
         // Create Socket.IO server
         this.io = new socket_io_1.Server(server, {
@@ -42,16 +43,17 @@ class SocketIOManager {
         this.setupAuthentication();
         // Setup connection handlers
         this.setupConnectionHandlers();
-        payload_1.default.logger.info("Socket.IO server initialized with real-time events plugin");
+        this.payload.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 = this.options.redis?.url;
+        var _a;
+        const redisUrl = (_a = this.options.redis) === null || _a === void 0 ? void 0 : _a.url;
         if (!redisUrl) {
-            payload_1.default.logger.warn("Redis URL not configured. Skipping Redis adapter setup. Set redis.url in plugin options.");
+            this.payload.logger.warn("Redis URL not configured. Skipping Redis adapter setup. Set redis.url in plugin options.");
             return;
         }
         try {
@@ -68,10 +70,10 @@ class SocketIOManager {
                 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");
+            this.payload.logger.info("Redis adapter configured for Socket.IO multi-instance support");
         }
         catch (error) {
-            payload_1.default.logger.error("Failed to setup Redis adapter:", error);
+            this.payload.logger.error("Failed to setup Redis adapter:", error);
             throw error;
         }
     }
@@ -91,22 +93,26 @@ class SocketIOManager {
                     return next(new Error("Authentication token required"));
                 }
                 try {
-                    const decoded = jsonwebtoken_1.default.verify(token, payload_1.default.secret);
+                    const decoded = jsonwebtoken_1.default.verify(token, this.payload.secret);
                     // Fetch full user document from Payload
-                    const userDoc = await payload_1.default.findByID({
+                    const userDoc = await this.payload.findByID({
                         collection: decoded.collection || "users",
                         id: decoded.id,
                     });
                     if (!userDoc) {
                         return next(new Error("User not found"));
                     }
-                    // Attach user info
-                    socket.user = {
+                    const userInfo = {
                         id: userDoc.id,
                         email: userDoc.email,
                         collection: decoded.collection || "users",
                         role: userDoc.role,
                     };
+                    // Store in socket.data for Redis adapter compatibility
+                    // socket.data is automatically synchronized across servers via Redis
+                    socket.data.user = userInfo;
+                    // Also attach to socket.user for backward compatibility
+                    socket.user = userInfo;
                     next();
                 }
                 catch (jwtError) {
@@ -114,7 +120,7 @@ class SocketIOManager {
                 }
             }
             catch (error) {
-                payload_1.default.logger.error("Socket authentication error:", error);
+                this.payload.logger.error("Socket authentication error:", error);
                 next(new Error("Authentication failed"));
             }
         });
@@ -124,7 +130,8 @@ class SocketIOManager {
      */
     setupConnectionHandlers() {
         this.io.on("connection", async (socket) => {
-            payload_1.default.logger.info(`Client connected: ${socket.id}, User: ${socket.user?.email || socket.user?.id}`);
+            var _a, _b;
+            this.payload.logger.info(`Client connected: ${socket.id}, User: ${((_a = socket.user) === null || _a === void 0 ? void 0 : _a.email) || ((_b = socket.user) === null || _b === void 0 ? void 0 : _b.id)}`);
             // Allow clients to subscribe to specific collections
             socket.on("subscribe", (collections) => {
                 const collectionList = Array.isArray(collections)
@@ -132,7 +139,7 @@ class SocketIOManager {
                     : [collections];
                 collectionList.forEach((collection) => {
                     socket.join(`collection:${collection}`);
-                    payload_1.default.logger.info(`Client ${socket.id} subscribed to collection: ${collection}`);
+                    this.payload.logger.info(`Client ${socket.id} subscribed to collection: ${collection}`);
                 });
             });
             // Allow clients to unsubscribe from collections
@@ -142,25 +149,27 @@ class SocketIOManager {
                     : [collections];
                 collectionList.forEach((collection) => {
                     socket.leave(`collection:${collection}`);
-                    payload_1.default.logger.info(`Client ${socket.id} unsubscribed from collection: ${collection}`);
+                    this.payload.logger.info(`Client ${socket.id} unsubscribed from collection: ${collection}`);
                 });
             });
             // Allow clients to join collection rooms (alias for subscribe)
             socket.on("join-collection", (collection) => {
+                var _a;
                 const roomName = `collection:${collection}`;
                 socket.join(roomName);
-                payload_1.default.logger.info(`Client ${socket.id} (${socket.user?.email}) joined collection room: ${roomName}`);
+                this.payload.logger.info(`Client ${socket.id} (${(_a = socket.user) === null || _a === void 0 ? void 0 : _a.email}) joined collection room: ${roomName}`);
             });
             // Handle disconnection
             socket.on("disconnect", () => {
-                payload_1.default.logger.info(`Client disconnected: ${socket.id}, User: ${socket.user?.email || socket.user?.id}`);
+                var _a, _b;
+                this.payload.logger.info(`Client disconnected: ${socket.id}, User: ${((_a = socket.user) === null || _a === void 0 ? void 0 : _a.email) || ((_b = socket.user) === null || _b === void 0 ? void 0 : _b.id)}`);
             });
             if (this.options.onSocketConnection) {
                 try {
-                    await this.options.onSocketConnection(socket, this.io, payload_1.default);
+                    await this.options.onSocketConnection(socket, this.io, this.payload);
                 }
                 catch (error) {
-                    payload_1.default.logger.error(`Error in custom socket connection handler: ${error}`);
+                    this.payload.logger.error(`Error in custom socket connection handler: ${error}`);
                 }
             }
         });
@@ -170,7 +179,7 @@ class SocketIOManager {
      */
     async emitEvent(event) {
         if (!this.io) {
-            payload_1.default.logger.warn("Socket.IO server not initialized, cannot emit event");
+            this.payload.logger.warn("Socket.IO server not initialized, cannot emit event");
             return;
         }
         const { authorize, shouldEmit, transformEvent } = this.options;
@@ -190,8 +199,10 @@ class SocketIOManager {
                 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);
+                    // Use socket.data.user for remote sockets (Redis adapter), fallback to socket.user for local
+                    const user = socket.data.user || authSocket.user;
+                    if (user) {
+                        const isAuthorized = await collectionHandler(user, finalEvent);
                         if (isAuthorized) {
                             socket.emit("payload:event", finalEvent);
                         }
@@ -226,7 +237,9 @@ class SocketIOManager {
         if (this.subClient) {
             await this.subClient.quit();
         }
-        payload_1.default.logger.info("Socket.IO server closed");
+        if (this.payload) {
+            this.payload.logger.info("Socket.IO server closed");
+        }
     }
 }
 exports.SocketIOManager = SocketIOManager;

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "payload-socket-plugin",
-  "version": "1.1.4",
-  "description": "Real-time Socket.IO plugin for Payload CMS with Redis support",
+  "version": "2.0.0",
+  "description": "Real-time Socket.IO plugin for Payload CMS v3 with Redis support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "browser": "dist/browser.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "require": "./dist/browser.js",
+      "types": "./dist/browser.d.ts"
+    }
+  },
   "files": [
     "dist",
     "README.md"
@@ -30,6 +41,9 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "peerDependencies": {
+    "payload": "^3.72.0"
+  },
   "dependencies": {
     "@socket.io/redis-adapter": "^8.0.0",
     "ioredis": "^5.3.0",