payload-socket-plugin 1.1.3 → 1.1.5

package/README.md

@@ -108,26 +108,18 @@ await initSocketIO(server);
 
 ```typescript
 // client.ts
-import { io, Socket } from "socket.io-client";
-import type {
-  ServerToClientEvents,
-  ClientToServerEvents,
-} from "payload-socket-plugin";
+import { io } from "socket.io-client";
 
-// Create a typed socket for full TypeScript support
-const socket: Socket<ServerToClientEvents, ClientToServerEvents> = io(
-  "http://localhost:3000",
-  {
-    auth: {
-      token: "your-jwt-token", // Get from Payload login
-    },
-  }
-);
+const socket = io("http://localhost:3000", {
+  auth: {
+    token: "your-jwt-token", // Get from Payload login
+  },
+});
 
-// Subscribe to collection events (fully typed!)
+// Subscribe to collection events
 socket.emit("join-collection", "posts");
 
-// Listen for events (event parameter is fully typed!)
+// Listen for events
 socket.on("payload:event", (event) => {
   console.log("Event received:", event);
   // {
@@ -365,105 +357,35 @@ This is handled automatically via the `"browser"` field in `package.json`, so yo
 
 ## Environment Variables
 
+The plugin does not read environment variables directly. You can use environment variables in your configuration:
+
 ```bash
-# Required for Redis multi-instance support
+# Example: Redis URL for multi-instance support
 REDIS_URL=redis://localhost:6379
 
 # Optional: Payload configuration
 PAYLOAD_SECRET=your-secret-key
 ```
 
-## TypeScript Types
+Then pass them in your plugin configuration:
 
-The plugin provides full TypeScript support with typed Socket.IO events following [Socket.IO v4 TypeScript best practices](https://socket.io/docs/v4/typescript/).
+```typescript
+socketPlugin({
+  redis: {
+    url: process.env.REDIS_URL,
+  },
+});
+```
 
-### Available Types
+## TypeScript Types
 
 ```typescript
 import type {
-  // Event interfaces for Socket.IO
-  ServerToClientEvents,
-  ClientToServerEvents,
-  InterServerEvents,
-  SocketData,
-
-  // Plugin types
   CollectionAuthorizationHandler,
   RealtimeEventPayload,
   AuthenticatedSocket,
   EventType,
-  RealtimeEventsPluginOptions,
-} from "payload-socket-plugin";
-```
-
-### Typed Socket.IO Client
-
-Use the event interfaces for full type safety on the client side:
-
-```typescript
-import { io, Socket } from "socket.io-client";
-import type {
-  ServerToClientEvents,
-  ClientToServerEvents,
 } from "payload-socket-plugin";
-
-// Create a typed socket client
-const socket: Socket<ServerToClientEvents, ClientToServerEvents> = io(
-  "http://localhost:3000",
-  {
-    auth: {
-      token: "your-jwt-token",
-    },
-  }
-);
-
-// Now you get full autocomplete and type checking!
-socket.emit("subscribe", ["posts", "users"]); // ✅ Type-safe
-socket.emit("join-collection", "posts"); // ✅ Type-safe
-
-socket.on("payload:event", (event) => {
-  // event is typed as RealtimeEventPayload
-  console.log(event.collection, event.type, event.doc);
-});
-
-socket.on("payload:event:all", (event) => {
-  // event is typed as RealtimeEventPayload
-  console.log("Global event:", event);
-});
-```
-
-### Event Interfaces
-
-**ServerToClientEvents** - Events the server emits to clients:
-
-```typescript
-interface ServerToClientEvents {
-  "payload:event": (event: RealtimeEventPayload) => void;
-  "payload:event:all": (event: RealtimeEventPayload) => void;
-}
-```
-
-**ClientToServerEvents** - Events clients can send to the server:
-
-```typescript
-interface ClientToServerEvents {
-  subscribe: (collections: string | string[]) => void;
-  unsubscribe: (collections: string | string[]) => void;
-  "join-collection": (collection: string) => void;
-}
-```
-
-**SocketData** - Data stored on each socket:
-
-```typescript
-interface SocketData {
-  user?: {
-    id: string | number;
-    email?: string;
-    collection?: string;
-    role?: string;
-  };
-}
 ```
 
 ## Troubleshooting
@@ -496,10 +418,11 @@ interface SocketData {
 
 **Solutions**:
 
-- Verify `REDIS_URL` environment variable is set correctly
+- Verify `redis.url` is set correctly in plugin options
 - Check Redis server is running and accessible
 - Ensure both server instances use the same Redis URL
 - Check Redis logs for connection errors
+- Make sure you're passing the Redis URL in the plugin configuration, not relying on environment variables
 
 ### TypeScript Errors
 
@@ -511,6 +434,43 @@ interface SocketData {
 - 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

package/dist/socketManager.d.ts

@@ -1,6 +1,6 @@
 import { Server as SocketIOServer } from "socket.io";
 import { Server as HTTPServer } from "http";
-import { RealtimeEventsPluginOptions, RealtimeEventPayload, ServerToClientEvents, ClientToServerEvents, InterServerEvents, SocketData } from "./types";
+import { RealtimeEventsPluginOptions, RealtimeEventPayload } from "./types";
 /**
  * Socket.IO Manager for handling real-time events with Redis adapter
  * Supports multiple Payload instances for production environments
@@ -14,7 +14,7 @@ export declare class SocketIOManager {
     /**
      * Initialize Socket.IO server with Redis adapter
      */
-    init(server: HTTPServer): Promise<SocketIOServer<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>>;
+    init(server: HTTPServer): Promise<SocketIOServer>;
     /**
      * Setup Redis adapter for multi-instance synchronization
      */
@@ -39,7 +39,7 @@ export declare class SocketIOManager {
     /**
      * Get Socket.IO server instance
      */
-    getIO(): SocketIOServer<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData> | null;
+    getIO(): SocketIOServer | null;
     /**
      * Cleanup and close connections
      */

package/dist/socketManager.js

@@ -25,7 +25,7 @@ class SocketIOManager {
      */
     async init(server) {
         const { redis, socketIO = {} } = this.options;
-        // Create Socket.IO server with typed events
+        // Create Socket.IO server
         this.io = new socket_io_1.Server(server, {
             path: socketIO.path || "/socket.io",
             cors: socketIO.cors || {
@@ -42,15 +42,16 @@ class SocketIOManager {
         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;
+        const redisUrl = this.options.redis?.url;
         if (!redisUrl) {
-            payload_1.default.logger.warn("REDIS_URL not configured. Skipping Redis adapter setup.");
+            payload_1.default.logger.warn("Redis URL not configured. Skipping Redis adapter setup. Set redis.url in plugin options.");
             return;
         }
         try {
@@ -67,6 +68,7 @@ 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");
         }
         catch (error) {
             payload_1.default.logger.error("Failed to setup Redis adapter:", error);
@@ -98,15 +100,17 @@ class SocketIOManager {
                     if (!userDoc) {
                         return next(new Error("User not found"));
                     }
-                    // Attach user info to socket.data
-                    socket.data.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 = socket.data.user;
+                    socket.user = userInfo;
                     next();
                 }
                 catch (jwtError) {
@@ -124,6 +128,7 @@ 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}`);
             // Allow clients to subscribe to specific collections
             socket.on("subscribe", (collections) => {
                 const collectionList = Array.isArray(collections)
@@ -131,6 +136,7 @@ class SocketIOManager {
                     : [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
@@ -140,20 +146,21 @@ class SocketIOManager {
                     : [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 (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}`);
             });
             // Handle disconnection
             socket.on("disconnect", () => {
-                // Cleanup happens automatically
+                payload_1.default.logger.info(`Client disconnected: ${socket.id}, User: ${socket.user?.email || socket.user?.id}`);
             });
             if (this.options.onSocketConnection) {
                 try {
-                    // Cast to AuthenticatedSocket for backward compatibility
                     await this.options.onSocketConnection(socket, this.io, payload_1.default);
                 }
                 catch (error) {
@@ -167,6 +174,7 @@ class SocketIOManager {
      */
     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;
@@ -185,7 +193,9 @@ class SocketIOManager {
             if (collectionHandler) {
                 const sockets = await this.io.in(room).fetchSockets();
                 for (const socket of sockets) {
-                    const user = socket.data.user || socket.user;
+                    const authSocket = socket;
+                    // 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) {
@@ -222,6 +232,7 @@ class SocketIOManager {
         if (this.subClient) {
             await this.subClient.quit();
         }
+        payload_1.default.logger.info("Socket.IO server closed");
     }
 }
 exports.SocketIOManager = SocketIOManager;

package/dist/types.d.ts

@@ -24,48 +24,10 @@ export interface RealtimeEventPayload {
     /** Timestamp of the event */
     timestamp: string;
 }
-/**
- * Events that the server can emit to clients
- */
-export interface ServerToClientEvents {
-    /** Real-time event for a specific collection */
-    "payload:event": (event: RealtimeEventPayload) => void;
-    /** Real-time event broadcast to all listeners */
-    "payload:event:all": (event: RealtimeEventPayload) => void;
-}
-/**
- * Events that clients can send to the server
- */
-export interface ClientToServerEvents {
-    /** Subscribe to one or more collections */
-    subscribe: (collections: string | string[]) => void;
-    /** Unsubscribe from one or more collections */
-    unsubscribe: (collections: string | string[]) => void;
-    /** Join a collection room (alias for subscribe) */
-    "join-collection": (collection: string) => void;
-}
-/**
- * Events for inter-server communication (when using Redis adapter)
- */
-export interface InterServerEvents {
-    ping: () => void;
-}
-/**
- * Data stored on each socket instance
- */
-export interface SocketData {
-    user?: {
-        id: string | number;
-        email?: string;
-        collection?: string;
-        role?: string;
-    };
-}
 /**
  * Socket.IO server instance with authentication
- * @deprecated Use Socket<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData> instead
  */
-export interface AuthenticatedSocket extends Socket<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData> {
+export interface AuthenticatedSocket extends Socket {
     user?: {
         id: string | number;
         email?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-socket-plugin",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Real-time Socket.IO plugin for Payload CMS with Redis support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",