payload-socket-plugin 1.0.0 → 1.1.1

package/README.md

@@ -18,7 +18,7 @@ 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
+- **Payload CMS**: ^2.0.0 || ^3.0.0
 - **Redis** (optional): Required for multi-instance deployments
 
 ## Installation
@@ -61,15 +61,17 @@ export default buildConfig({
         },
         path: "/socket.io",
       },
-      includeCollections: ["projects", "posts"],
+      includeCollections: ["posts", "users"],
       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;
+          return (
+            event.doc.status === "published" || user.id === event.doc.author
+          );
+        },
+        users: async (user, event) => {
+          // Only allow user to receive their own events
+          return user.id === event.id;
         },
       },
     }),
@@ -115,16 +117,16 @@ const socket = io("http://localhost:3000", {
 });
 
 // Subscribe to collection events
-socket.emit("join-collection", "projects");
+socket.emit("join-collection", "posts");
 
 // Listen for events
 socket.on("payload:event", (event) => {
   console.log("Event received:", event);
   // {
   //   type: 'update',
-  //   collection: 'projects',
+  //   collection: 'posts',
   //   id: '123',
-  //   doc: { ... },
+  //   doc: { title: 'My Post', status: 'published', ... },
   //   user: { id: '456', email: 'user@example.com' },
   //   timestamp: '2024-01-01T00:00:00.000Z'
   // }
@@ -144,6 +146,7 @@ socket.on("payload:event", (event) => {
 | `authorize`          | `object`   | -       | Per-collection authorization handlers                   |
 | `shouldEmit`         | `function` | -       | Filter function to determine if event should be emitted |
 | `transformEvent`     | `function` | -       | Transform events before emitting                        |
+| `onSocketConnection` | `function` | -       | Custom event handlers for each socket connection        |
 
 ## Authorization
 
@@ -152,28 +155,25 @@ Authorization handlers determine which users can receive events for specific doc
 ```typescript
 import type { CollectionAuthorizationHandler } from "payload-socket-plugin";
 
-const authorizeProject: CollectionAuthorizationHandler = async (
-  user,
-  event
-) => {
+const authorizePost: 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",
+  // Check if post is published or user is the author
+  const post = await payload.findByID({
+    collection: "posts",
     id: event.id as string,
   });
 
-  return user.id === project.user;
+  return post.status === "published" || user.id === post.author;
 };
 
 // Use in plugin config
 socketPlugin({
   authorize: {
-    projects: authorizeProject,
+    posts: authorizePost,
   },
 });
 ```
@@ -184,13 +184,13 @@ socketPlugin({
 
 ```typescript
 // Subscribe to a single collection
-socket.emit("join-collection", "projects");
+socket.emit("join-collection", "posts");
 
 // Subscribe to multiple collections
-socket.emit("subscribe", ["projects", "posts"]);
+socket.emit("subscribe", ["posts", "users", "media"]);
 
 // Unsubscribe
-socket.emit("unsubscribe", ["projects"]);
+socket.emit("unsubscribe", ["posts"]);
 ```
 
 ### Listening for Events
@@ -198,8 +198,8 @@ socket.emit("unsubscribe", ["projects"]);
 ```typescript
 // Listen to specific collection events
 socket.on("payload:event", (event) => {
-  if (event.collection === "projects" && event.type === "update") {
-    // Handle project update
+  if (event.collection === "posts" && event.type === "update") {
+    // Handle post update
   }
 });
 
@@ -211,6 +211,80 @@ socket.on("payload:event:all", (event) => {
 
 ## Advanced Usage
 
+### Custom Socket Event Handlers
+
+You can register your own custom event handlers that will be attached to each authenticated socket.
+
+**Simple inline handlers:**
+
+```typescript
+socketPlugin({
+  onSocketConnection: (socket, io, payload) => {
+    // Custom event handler
+    socket.on("send-message", async (data) => {
+      const { roomId, message } = data;
+
+      // Broadcast to room
+      io.to(`room:${roomId}`).emit("new-message", {
+        user: socket.user,
+        message,
+        timestamp: new Date().toISOString(),
+      });
+    });
+
+    // Custom room management
+    socket.on("join-custom-room", (roomId) => {
+      socket.join(`room:${roomId}`);
+      socket.emit("joined-room", { roomId });
+    });
+
+    // Access Payload CMS from your handlers
+    socket.on("get-user-data", async () => {
+      const user = await payload.findByID({
+        collection: "users",
+        id: socket.user!.id as string,
+      });
+      socket.emit("user-data", user);
+    });
+  },
+});
+```
+
+**Organized in separate files (recommended):**
+
+```typescript
+// Import from examples directory
+import { projectHandlers } from "./examples/projectHandlers";
+import { chatHandlers } from "./examples/chatHandlers";
+import { notificationHandlers } from "./examples/notificationHandlers";
+
+// Or import all at once
+import {
+  projectHandlers,
+  chatHandlers,
+  notificationHandlers,
+} from "./examples";
+
+socketPlugin({
+  onSocketConnection: (socket, io, payload) => {
+    // Use one or more pre-built handlers
+    projectHandlers(socket, io, payload);
+    chatHandlers(socket, io, payload);
+    notificationHandlers(socket, io, payload);
+  },
+});
+```
+
+**See the [examples directory](./examples) for complete implementations** including:
+
+| Handler                   | Features                                                             |
+| ------------------------- | -------------------------------------------------------------------- |
+| **Project Collaboration** | Join/leave rooms, permission checking, presence tracking, kick users |
+| **Chat/Messaging**        | Send messages, typing indicators, read receipts                      |
+| **Notifications**         | User notifications, broadcast announcements (admin only)             |
+
+Each example includes full client-side and server-side code with error handling and best practices.
+
 ### Custom Event Filtering
 
 ```typescript
@@ -271,6 +345,16 @@ socketPlugin({
 4. Authorization handlers determine which users receive the event
 5. Redis adapter ensures events sync across multiple server instances
 
+## Browser Compatibility
+
+This plugin includes automatic browser-safe mocking for the Payload admin panel. When bundled for the browser (e.g., in the Payload admin UI), the plugin automatically uses a mock implementation that:
+
+- Returns the config unchanged (no Socket.IO server initialization)
+- Provides no-op functions for `initSocketIO()` and `SocketIOManager` methods
+- Prevents server-side dependencies (Socket.IO, Redis) from being bundled in the browser
+
+This is handled automatically via the `"browser"` field in `package.json`, so you don't need to configure anything special. The Socket.IO server only runs on the server side.
+
 ## Environment Variables
 
 ```bash
@@ -353,7 +437,6 @@ import type {
 
 ## 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

package/dist/browser.d.ts

@@ -0,0 +1,24 @@
+import type { Config } from "payload/config";
+/**
+ * Browser-safe mock for the Socket.IO plugin
+ * This file is used when bundling for the browser (e.g., Payload admin panel)
+ * The actual Socket.IO server only runs on the server side
+ */
+export declare const socketPlugin: () => (config: Config) => Config;
+/**
+ * Browser-safe mock for initSocketIO
+ * Does nothing in browser environment
+ */
+export declare const initSocketIO: () => Promise<void>;
+/**
+ * Browser-safe mock for SocketIOManager
+ * Returns a mock class that does nothing in browser environment
+ */
+export declare class SocketIOManager {
+    constructor();
+    init(): Promise<null>;
+    emitEvent(): Promise<void>;
+    getIO(): null;
+    close(): Promise<void>;
+}
+export * from "./types";

package/dist/browser.js

@@ -0,0 +1,61 @@
+"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.SocketIOManager = exports.initSocketIO = exports.socketPlugin = void 0;
+/**
+ * Browser-safe mock for the Socket.IO plugin
+ * This file is used when bundling for the browser (e.g., Payload admin panel)
+ * The actual Socket.IO server only runs on the server side
+ */
+const socketPlugin = () => (config) => {
+    // Return config unchanged - Socket.IO server is server-side only
+    return config;
+};
+exports.socketPlugin = socketPlugin;
+/**
+ * Browser-safe mock for initSocketIO
+ * Does nothing in browser environment
+ */
+const initSocketIO = async () => {
+    // No-op in browser
+    console.warn("initSocketIO called in browser environment - this is a no-op");
+};
+exports.initSocketIO = initSocketIO;
+/**
+ * Browser-safe mock for SocketIOManager
+ * Returns a mock class that does nothing in browser environment
+ */
+class SocketIOManager {
+    constructor() {
+        // No-op in browser
+    }
+    async init() {
+        console.warn("SocketIOManager.init called in browser environment - this is a no-op");
+        return null;
+    }
+    async emitEvent() {
+        // No-op in browser
+    }
+    getIO() {
+        return null;
+    }
+    async close() {
+        // No-op in browser
+    }
+}
+exports.SocketIOManager = SocketIOManager;
+// Export types (these are safe for browser)
+__exportStar(require("./types"), exports);

package/dist/socketManager.js

@@ -123,7 +123,7 @@ class SocketIOManager {
      * Setup connection event handlers
      */
     setupConnectionHandlers() {
-        this.io.on("connection", (socket) => {
+        this.io.on("connection", async (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) => {
@@ -135,7 +135,7 @@ class SocketIOManager {
                     payload_1.default.logger.info(`Client ${socket.id} subscribed to collection: ${collection}`);
                 });
             });
-            // // Allow clients to unsubscribe from collections
+            // Allow clients to unsubscribe from collections
             socket.on("unsubscribe", (collections) => {
                 const collectionList = Array.isArray(collections)
                     ? collections
@@ -145,169 +145,24 @@ class SocketIOManager {
                     payload_1.default.logger.info(`Client ${socket.id} unsubscribed from collection: ${collection}`);
                 });
             });
-            // Allow clients to join collection rooms to receive update events
+            // Allow clients to join collection rooms (alias for subscribe)
             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);
+            // Handle disconnection
+            socket.on("disconnect", () => {
+                payload_1.default.logger.info(`Client disconnected: ${socket.id}, User: ${socket.user?.email || 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
+            if (this.options.onSocketConnection) {
                 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",
-                        });
-                    }
+                    await this.options.onSocketConnection(socket, this.io, payload_1.default);
                 }
                 catch (error) {
-                    payload_1.default.logger.error("Error kicking user:", error);
-                    socket.emit("kick-error", {
-                        message: "Failed to kick user",
-                    });
+                    payload_1.default.logger.error(`Error in custom socket connection handler: ${error}`);
                 }
-            });
-            // 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`);
-                    }
-                }
-            });
+            }
         });
     }
     /**

package/dist/types.d.ts

@@ -110,4 +110,23 @@ export interface RealtimeEventsPluginOptions {
      * Custom event transformer
      */
     transformEvent?: (event: RealtimeEventPayload) => RealtimeEventPayload;
+    /**
+     * Custom socket event handlers
+     * Register your own event handlers that will be attached to each authenticated socket
+     *
+     * @example
+     * ```ts
+     * onSocketConnection: (socket, io, payload) => {
+     *   socket.on('custom-event', (data) => {
+     *     // Handle custom event
+     *     socket.emit('custom-response', { success: true });
+     *   });
+     *
+     *   socket.on('join-room', (roomId) => {
+     *     socket.join(`custom:${roomId}`);
+     *   });
+     * }
+     * ```
+     */
+    onSocketConnection?: (socket: AuthenticatedSocket, io: any, payload: any) => void | Promise<void>;
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "payload-socket-plugin",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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",
+  "browser": "dist/browser.js",
   "files": [
     "dist",
     "README.md"
@@ -30,9 +30,6 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "peerDependencies": {
-    "payload": "^2.0.0"
-  },
   "dependencies": {
     "@socket.io/redis-adapter": "^8.0.0",
     "ioredis": "^5.3.0",
@@ -42,7 +39,6 @@
   "devDependencies": {
     "@types/jsonwebtoken": "^9.0.0",
     "@types/node": "^20.0.0",
-    "payload": "^2.0.0",
     "typescript": "^5.0.0"
   },
   "repository": {

package/dist/mock.d.ts

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-"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;