@eleven-am/pondsocket 0.1.65 → 0.1.67

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,203 @@ 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";
 
-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';
+}
+
+function isTextProfane(text) {
+    // Implement your profanity check logic here
+    // Return true if the text is profane, false otherwise
+    return false;
+}
+
+function getMessagesFromDatabase(channelId) {
+    // Implement your logic to retrieve messages from the database
+    // Return an array of messages
+    return [];
+}
+
+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 = getRoleFromToken(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);
+    }
+});
+
+// Create a channel, providing a callback that is called when a user attempts to join the channel
+const profanityChannel = endpoint.createChannel('/channel/:id', async (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;
+    const { id } = req.event.params;
+
+    // maybe retrieve the channel from a database
+    const messages = await getMessagesFromDatabase(id);
+
+    // 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(),
+            })
+            // and send the user the channel history
+            .sendToUsers('history', { messages }, [req.user.id]);
+
+        // Alternatively, you can also send messages to the user, NOTE that the user would be automatically subscribed to the channel.
+        // res.send('history', { messages }, { username, profanityCount: 0 })
+        //   .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 (isTextProfane(text)) {
+        // Reject the message if it contains profanity
+        res.reject('Profanity is not allowed', 400, {
+            profanityCount:  req.user.assigns.profanityCount + 1
+        });
+
+        // note that profanityCount is updated so req.user.assigns.profanityCount will be updated
+        if (req.user.assigns.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.channel;
+});
+
+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 +366,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 +402,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 +458,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 +492,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/channel/channel.js

@@ -21,9 +21,9 @@ var __rest = (this && this.__rest) || function (s, e) {
         }
     return t;
 };
-var _ChannelEngine_instances, _ChannelEngine_receiver, _ChannelEngine_presenceEngine, _ChannelEngine_users, _ChannelEngine_parentEngine, _ChannelEngine_subscribe, _ChannelEngine_getUsersFromRecipients, _Client_engine;
+var _ChannelEngine_instances, _ChannelEngine_receiver, _ChannelEngine_presenceEngine, _ChannelEngine_users, _ChannelEngine_parentEngine, _ChannelEngine_subscribe, _ChannelEngine_getUsersFromRecipients, _Channel_engine;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = exports.ChannelEngine = void 0;
+exports.Channel = exports.ChannelEngine = void 0;
 const eventRequest_1 = require("./eventRequest");
 const eventResponse_1 = require("./eventResponse");
 const enums_1 = require("../enums");
@@ -257,37 +257,37 @@ _ChannelEngine_receiver = new WeakMap(), _ChannelEngine_presenceEngine = new Wea
     }
     return users;
 };
-class Client {
+class Channel {
     constructor(engine) {
-        _Client_engine.set(this, void 0);
-        __classPrivateFieldSet(this, _Client_engine, engine, "f");
+        _Channel_engine.set(this, void 0);
+        __classPrivateFieldSet(this, _Channel_engine, engine, "f");
     }
     getAssigns() {
-        return __classPrivateFieldGet(this, _Client_engine, "f").getAssigns();
+        return __classPrivateFieldGet(this, _Channel_engine, "f").getAssigns();
     }
     getUserData(userId) {
-        return __classPrivateFieldGet(this, _Client_engine, "f").getUserData(userId);
+        return __classPrivateFieldGet(this, _Channel_engine, "f").getUserData(userId);
     }
     broadcastMessage(event, payload) {
-        __classPrivateFieldGet(this, _Client_engine, "f").sendMessage(enums_1.SystemSender.CHANNEL, enums_1.ChannelReceiver.ALL_USERS, enums_1.ServerActions.BROADCAST, event, payload);
+        __classPrivateFieldGet(this, _Channel_engine, "f").sendMessage(enums_1.SystemSender.CHANNEL, enums_1.ChannelReceiver.ALL_USERS, enums_1.ServerActions.BROADCAST, event, payload);
     }
     sendToUser(userId, event, payload) {
-        __classPrivateFieldGet(this, _Client_engine, "f").sendMessage(enums_1.SystemSender.CHANNEL, [userId], enums_1.ServerActions.BROADCAST, event, payload);
+        __classPrivateFieldGet(this, _Channel_engine, "f").sendMessage(enums_1.SystemSender.CHANNEL, [userId], enums_1.ServerActions.BROADCAST, event, payload);
     }
     banUser(userId, reason) {
-        __classPrivateFieldGet(this, _Client_engine, "f").kickUser(userId, reason !== null && reason !== void 0 ? reason : 'You have been banned from the channel');
+        __classPrivateFieldGet(this, _Channel_engine, "f").kickUser(userId, reason !== null && reason !== void 0 ? reason : 'You have been banned from the channel');
     }
     trackPresence(userId, presence) {
-        __classPrivateFieldGet(this, _Client_engine, "f").trackPresence(userId, presence);
+        __classPrivateFieldGet(this, _Channel_engine, "f").trackPresence(userId, presence);
     }
     removePresence(userId) {
         var _a;
-        (_a = __classPrivateFieldGet(this, _Client_engine, "f").presenceEngine) === null || _a === void 0 ? void 0 : _a.removePresence(userId);
+        (_a = __classPrivateFieldGet(this, _Channel_engine, "f").presenceEngine) === null || _a === void 0 ? void 0 : _a.removePresence(userId);
     }
     updatePresence(userId, presence) {
         var _a;
-        (_a = __classPrivateFieldGet(this, _Client_engine, "f").presenceEngine) === null || _a === void 0 ? void 0 : _a.updatePresence(userId, presence);
+        (_a = __classPrivateFieldGet(this, _Channel_engine, "f").presenceEngine) === null || _a === void 0 ? void 0 : _a.updatePresence(userId, presence);
     }
 }
-exports.Client = Client;
-_Client_engine = new WeakMap();
+exports.Channel = Channel;
+_Channel_engine = new WeakMap();

package/channel/eventRequest.js

@@ -18,8 +18,8 @@ class EventRequest extends abstractRequest_1.AbstractRequest {
         }
         return assigns;
     }
-    get client() {
-        return new channel_1.Client(this._engine);
+    get channel() {
+        return new channel_1.Channel(this._engine);
     }
 }
 exports.EventRequest = EventRequest;

package/lobby/joinRequest.js

@@ -35,8 +35,8 @@ class JoinRequest extends abstractRequest_1.AbstractRequest {
             presence: {},
         };
     }
-    get client() {
-        return new channel_1.Client(this._engine);
+    get channel() {
+        return new channel_1.Channel(this._engine);
     }
 }
 exports.JoinRequest = JoinRequest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleven-am/pondsocket",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "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;
@@ -107,7 +111,7 @@ declare abstract class PondResponse {
 declare class EventRequest<Path extends string> extends AbstractRequest<Path> {
     user: UserData;
 
-    client: Client;
+    channel: Channel;
 }
 
 declare class EventResponse extends PondResponse {
@@ -189,7 +193,7 @@ declare class EventResponse extends PondResponse {
     closeChannel (reason: string): void;
 }
 
-export declare class Channel {
+export declare class ClientChannel {
     channelState: ChannelState;
 
     /**
@@ -315,7 +319,7 @@ declare class Endpoint {
     closeConnection (clientIds: string | string[]): void;
 }
 
-export declare class Client {
+export declare class Channel {
     /**
      * @desc Gets the current assign data for the channel.
      */
@@ -375,7 +379,7 @@ declare class JoinRequest<Path extends string> extends AbstractRequest<Path> {
 
     user: UserData;
 
-    client: Client;
+    channel: Channel;
 }
 
 declare class JoinResponse extends PondResponse {
@@ -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 {
 
     /**
@@ -559,7 +571,7 @@ declare class PondClient {
      * @param name - The name of the channel.
      * @param params - The params to send to the server.
      */
-    createChannel (name: string, params?: JoinParams): Channel;
+    createChannel (name: string, params?: JoinParams): ClientChannel;
 
     /**
      * @desc Subscribes to the connection state.
@@ -569,4 +581,3 @@ declare class PondClient {
 }
 
 declare const pondSocket: (app: Express) => PondSocketExpressApp;
-