payload-socket-plugin 1.1.2 → 1.1.3

package/README.md

@@ -108,18 +108,26 @@ await initSocketIO(server);
 
 ```typescript
 // client.ts
-import { io } from "socket.io-client";
+import { io, Socket } from "socket.io-client";
+import type {
+  ServerToClientEvents,
+  ClientToServerEvents,
+} from "payload-socket-plugin";
 
-const socket = io("http://localhost:3000", {
-  auth: {
-    token: "your-jwt-token", // Get from Payload login
-  },
-});
+// 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
+    },
+  }
+);
 
-// Subscribe to collection events
+// Subscribe to collection events (fully typed!)
 socket.emit("join-collection", "posts");
 
-// Listen for events
+// Listen for events (event parameter is fully typed!)
 socket.on("payload:event", (event) => {
   console.log("Event received:", event);
   // {
@@ -367,15 +375,97 @@ PAYLOAD_SECRET=your-secret-key
 
 ## TypeScript Types
 
+The plugin provides full TypeScript support with typed Socket.IO events following [Socket.IO v4 TypeScript best practices](https://socket.io/docs/v4/typescript/).
+
+### Available 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
 
 ### Connection Issues

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 } from "./types";
+import { RealtimeEventsPluginOptions, RealtimeEventPayload, ServerToClientEvents, ClientToServerEvents, InterServerEvents, SocketData } 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>;
+    init(server: HTTPServer): Promise<SocketIOServer<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData>>;
     /**
      * Setup Redis adapter for multi-instance synchronization
      */
@@ -39,7 +39,7 @@ export declare class SocketIOManager {
     /**
      * Get Socket.IO server instance
      */
-    getIO(): SocketIOServer | null;
+    getIO(): SocketIOServer<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData> | 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
+        // Create Socket.IO server with typed events
         this.io = new socket_io_1.Server(server, {
             path: socketIO.path || "/socket.io",
             cors: socketIO.cors || {
@@ -42,7 +42,6 @@ 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;
     }
     /**
@@ -68,7 +67,6 @@ 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);
@@ -100,13 +98,15 @@ class SocketIOManager {
                     if (!userDoc) {
                         return next(new Error("User not found"));
                     }
-                    // Attach user info
-                    socket.user = {
+                    // Attach user info to socket.data
+                    socket.data.user = {
                         id: userDoc.id,
                         email: userDoc.email,
                         collection: decoded.collection || "users",
                         role: userDoc.role,
                     };
+                    // Also attach to socket.user for backward compatibility
+                    socket.user = socket.data.user;
                     next();
                 }
                 catch (jwtError) {
@@ -124,7 +124,6 @@ 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)
@@ -132,7 +131,6 @@ 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
@@ -142,21 +140,20 @@ 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", () => {
-                payload_1.default.logger.info(`Client disconnected: ${socket.id}, User: ${socket.user?.email || socket.user?.id}`);
+                // Cleanup happens automatically
             });
             if (this.options.onSocketConnection) {
                 try {
+                    // Cast to AuthenticatedSocket for backward compatibility
                     await this.options.onSocketConnection(socket, this.io, payload_1.default);
                 }
                 catch (error) {
@@ -170,7 +167,6 @@ 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;
@@ -189,9 +185,9 @@ class SocketIOManager {
             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);
+                    const user = socket.data.user || socket.user;
+                    if (user) {
+                        const isAuthorized = await collectionHandler(user, finalEvent);
                         if (isAuthorized) {
                             socket.emit("payload:event", finalEvent);
                         }
@@ -226,7 +222,6 @@ 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,10 +24,48 @@ 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 {
+export interface AuthenticatedSocket extends Socket<ClientToServerEvents, ServerToClientEvents, InterServerEvents, SocketData> {
     user?: {
         id: string | number;
         email?: string;

package/package.json

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