@eleven-am/pondsocket 0.1.65 → 0.1.66

package/README.md

@@ -33,7 +33,7 @@ Within each endpoint, sockets interact through channels. Channels provide an org
 
 ```javascript
 const channel = endpoint.createChannel('/channel/:id', (req, res) => {
-    // Handle channel-specific events and actions
+    // Handle the join request, which is sent when a user attempts to join the channel
 });
 ```
 
@@ -74,9 +74,179 @@ This node client allows you to turn another server into a client, enabling easy
 - **Broadcasting**: PondSocket enables broadcasting messages to all users or specific groups within a channel, facilitating real-time updates.
 - **Typed and Well-documented**: The codebase is thoroughly documented and typed, providing a seamless development experience with improved IDE suggestions.
 
-## License
+## Examples
+
+### Client-side Example with Authentication
+
+To connect to the PondSocket server and send messages while associating a username with the client connection, follow the steps below:
+
+```javascript
+import PondClient from "@eleven-am/pondsocket/client";
+
+// Your server URL
+const serverUrl = 'ws://your-server-url/api/socket';
+
+// Your authenticated user's username (replace with actual username)
+const authToken = 'your-auth-token';
+
+// Your username (replace with actual username)
+const username = 'user123';
+
+// Create a new PondClient instance
+const socket = new PondClient(serverUrl, { token: authToken });
+
+// Connect to the server
+socket.connect();
+
+// Add event listeners to handle various scenarios
+socket.onConnectionChange((connected) => {
+    if (connected) {
+        console.log('Connected to the server.');
+    } else {
+        console.log('Disconnected from the server.');
+    }
+});
+
+// Create a channel and join it
+const channel = socket.createChannel('/channel/123', { username });
+channel.join();
+
+// Send a message to the server
+const message = "Hello, PondSocket!";
+channel.broadcast('message', { text: message });
+
+// Handle received messages
+channel.onMessage((event, message) => {
+    console.log(`Received message from server: ${message.text}`);
+});
+```
+
+The client will now connect to the server, and the server will receive the necessary headers automatically, including any authentication tokens or cookies, as required by the browser.
+
+### Server-side Example with Authentication and check for profanity before broadcasting
+
+To create a PondSocket server that accepts authenticated connections and checks for profanity before broadcasting messages, follow the steps below:
+
+```javascript
+import PondSocket from "@eleven-am/pondsocket";
+import Filter from "bad-words";
 
-PondSocket is released under the MIT License. Please refer to the `LICENSE` file for detailed licensing information.
+// Helper functions for token validation
+function isValidToken(token) {
+    // Implement your token validation logic here
+    // Return true if the token is valid, false otherwise
+    return true;
+}
+
+function getRoleFromToken(token) {
+    // Implement the logic to extract the user's role from the token
+    // Return the user's role
+    return 'user';
+}
+
+// Create a PondChannel with profanity check
+const profanityFilter = new Filter();
+
+const pond = new PondSocket();
+
+// Create an endpoint for handling socket connections
+const endpoint = pond.createEndpoint('/api/socket', (req, res) => {
+    // Depending if the user already has cookies set, they can be accessed from the request headers or the request address
+    const token = req.query.token; // If the token is passed as a query parameter
+
+    // Perform token validation here
+    if (isValidToken(token)) {
+        // Extract the authenticated user's username
+        const role = getUsernameFromToken(token);
+
+        // Handle socket connection and authentication for valid users
+        res.accept({ role }); // Assign the user's role to the socket
+    } else {
+        // Reject the connection for invalid users or without a token
+        res.reject('Invalid token', 401);
+    }
+});
+
+const profanityChannel = endpoint.createChannel('/channel/:id', (req, res) => {
+    // When joining the channel, any joinParams passed from the client will be available in the request payload
+    // Also any previous assigns on the socket will be available in the request payload as well
+    const { role } = req.user.assigns;
+    const { username } = req.joinParams;
+    
+    // Check if the user has the required role to join the channel
+    if (role === 'admin') {
+        // Accept the join request
+        res.accept({ username, profanityCount: 0 })
+        // optionally you can track the presence of the user in the channel
+            .trackPresence({
+                username,
+                role,
+                status: 'online',
+                onlineSince: Date.now(),
+            });
+    } else {
+        // Reject the join request
+        res.reject('You do not have the required role to join this channel', 403);
+    }
+});
+
+// Attach message event listener to the profanityChannel
+profanityChannel.onEvent('message', (req, res) => {
+    const { text } = req.event.payload;
+
+    // Check for profanity
+    if (profanityFilter.isProfane(text)) {
+        const profanityCount = req.user.assigns.profanityCount + 1
+        // Reject the message if it contains profanity
+        res.reject('Profanity is not allowed', 400, {
+            profanityCount,
+        });
+        
+        if (profanityCount >= 3) {
+            // Kick the user from the channel if they have used profanity more than 3 times
+            res.evictUser('You have been kicked from the channel for using profanity');
+        } else {
+            // you can broadcast a message to all users or In the channel that profanity is not allowed
+            res.broadcast('profanity-warning', { message: 'Profanity is not allowed' })
+                // or you can send a message to the user that profanity is not allowed
+                .send('profanity-warning', { message: `You have used profanity ${profanityCount} times. You will be kicked from the channel if you use profanity more than 3 times.` });
+        }
+    } else {
+        // Accept the message to allow broadcasting to other clients in the channel
+        res.accept();
+    }
+    
+    // for more complete access to the channel, you can use the client object
+    // const channel = req.client;
+});
+
+profanityChannel.onEvent('presence/:presence', (req, res) => {
+    const { presence } = req.event.params;
+    const { username } = req.user.assigns;
+    
+    // Handle presence events
+    res.updatePresence({
+        username,
+        role,
+        onlineSince: Date.now(),
+        status: presence,
+    });
+});
+
+profanityChannel.onLeave((req, res) => {
+    const { username } = req.user.assigns;
+    
+    // When a user leaves the channel, PondSocket will automatically remove the user from the presence list and inform other users in the channel
+    
+    // perform a cleanup operation here
+});
+
+
+// Start the server
+pond.listen(3000, () => {
+    console.log('PondSocket server listening on port 3000');
+});
+```
 
 ## API Documentation
 
@@ -172,6 +342,8 @@ The `PondChannel` class represents a Generic channel in the PondSocket server. I
 
 - `broadcast(event: string, payload: PondMessage, channelName?: string): void`: Broadcasts a message to all users in the channel with the specified event and payload. Optionally, a specific channel name can be provided to broadcast the message only to users in that channel.
 
+- `onLeave(handler: (event: LeaveEvent) => void | Promise<void>): void`: Handles a leave event for the channel with the provided handler function when a user leaves the channel.
+
 ### EventRequest
 
 The `EventRequest` class represents the request object when an event is received from a client.
@@ -206,9 +378,7 @@ The `EventResponse` class represents the response object for handling events fro
 
 - `broadcastFromUser(event: string, payload: PondMessage): EventResponse`: Sends a message to all clients in the channel except the sender with the specified event and payload.
 
-- `sendToUsers(event: string, payload: PondMessage, userIds: string[]): EventResponse`: Sends
-
-a message to a specific set of clients identified by the provided userIds with the specified event and payload.
+- `sendToUsers(event: string, payload: PondMessage, userIds: string[]): EventResponse`: Sends a message to a specific set of clients identified by the provided userIds with the specified event and payload.
 
 - `trackPresence(presence: PondPresence, userId?: string): EventResponse`: Tracks a user's presence in the channel.
 
@@ -264,7 +434,7 @@ The `PondClient` class represents a client that connects to the PondSocket serve
 
 ### Channel
 
-The `Channel` class represents a channel in the PondSocket server.
+The `Channel` class represents a channel in the PondClient.
 
 **Methods:**
 
@@ -298,6 +468,10 @@ The `Channel` class represents a channel in the PondSocket server.
 
 - `onConnectionChange(callback: (connected: boolean) => void): Unsubscribe`: Monitors the connection state of the channel and calls the provided callback when the connection state changes.
 
+## License
+
+PondSocket is released under the GPL-3.0 License. Please refer to the `LICENSE` file for detailed licensing information.
+
 ## Conclusion
 
 PondSocket is a powerful and versatile solution for building real-time applications that require efficient bidirectional communication between server and client components. Its minimalist design and comprehensive feature set make it an excellent choice for WebSocket-based projects, providing developers with a straightforward and reliable tool for building real-time communication systems. With the Node.js client, it also allows for easy communication between multiple server instances, expanding its capabilities even further.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleven-am/pondsocket",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "description": "PondSocket is a fast simple socket server",
   "keywords": [
     "socket",

package/types.d.ts

@@ -1,9 +1,11 @@
-import { Express } from 'express';
 import { Server as HTTPServer, IncomingHttpHeaders } from 'http';
+
+import type { Express } from 'express';
 import { WebSocketServer } from 'ws';
 
 type Unsubscribe = () => void;
 
+export type default_t<T = any> = Record<string, T>;
 type IsParam<Path> = Path extends `:${infer Param}` ? Param : never;
 
 type FilteredParams<Path> = Path extends `${infer First}/${infer Second}`
@@ -21,12 +23,7 @@ type EventParams<Path> = {
     params: Params<Path>;
 }
 
-type Primitives = number | string | boolean | null | undefined;
-
-type PondObject = {
-    [key: string]: Primitives | PondObject | PondObject[];
-}
-
+type PondObject = default_t;
 type PondPresence = PondObject;
 type PondMessage = PondObject;
 type PondAssigns = PondObject;
@@ -56,6 +53,13 @@ type IncomingConnection<Path> = EventParams<Path> & {
     address: string;
 }
 
+interface LeaveEvent {
+    userId: string;
+    assigns: PondAssigns;
+}
+
+type LeaveCallback = (event: LeaveEvent) => void;
+
 interface UserData {
     assigns: PondAssigns;
     presence: PondPresence;
@@ -479,6 +483,12 @@ export declare class PondChannel {
      *});
      */
     broadcast (event: string, payload: PondMessage, channelName?: string): void;
+
+    /**
+     * @desc Handles the leave event for a user, can occur when a user disconnects or leaves a channel, use this to clean up any resources
+     * @param callback - The callback to execute when a user leaves
+     */
+    public onLeave (callback: LeaveCallback): void;
 }
 
 declare class PondSocket {
@@ -515,6 +525,8 @@ declare class PondSocket {
     createEndpoint<Path extends string> (path: PondPath<Path>, handler: (request: IncomingConnection<Path>, response: ConnectionResponse) => void | Promise<void>): Endpoint;
 }
 
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
 interface PondSocketExpressApp extends Express {
 
     /**