payload-socket-plugin 1.0.0 → 1.1.0

package/README.md

@@ -144,6 +144,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
 
@@ -211,6 +212,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

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,6 +1,6 @@
 {
   "name": "payload-socket-plugin",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Real-time Socket.IO plugin for Payload CMS with Redis support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",