hackchat-engine 1.1.8 → 1.1.11

package/Client.js

@@ -186,7 +186,8 @@ class Client extends EventEmitter {
 
           const success = this.ws.connect(gw);
           if (!success) {
-            return reject(new Error('Connection failed to start (Socket likely not IDLE)'));
+            reject(new Error('Connection failed to start (Socket likely not IDLE)'));
+            return;
           }
 
           this.ws.connection.once('error', reject);
@@ -405,6 +406,42 @@ class Client extends EventEmitter {
       signedTransaction,
     });
   }
+
+  /**
+    * Send `updateMessage` operation to the server
+    * @param {string} customId The customId of the target message
+    * @param {string} text The text to apply
+    * @param {string} [mode='overwrite'] The update mode:
+    *   'overwrite', 'append', 'prepend', or 'complete'
+    */
+  updateMessage(customId, text, mode = 'overwrite') {
+    this.ws.send({
+      cmd: OPCodes.UPDATE_MESSAGE,
+      channel: this.channel, // @todo Multichannel
+      customId,
+      text,
+      mode,
+    });
+  }
+
+  /**
+    * Request the public wallet address of a specific user
+    * @param {number|string} target The userid (number) or nickname (string) of the user
+    */
+  getWallet(target) {
+    const payload = {
+      cmd: OPCodes.GET_WALLET,
+      channel: this.channel, // @todo Multichannel
+    };
+
+    if (typeof target === 'number') {
+      payload.userid = target;
+    } else {
+      payload.nick = target;
+    }
+
+    this.ws.send(payload);
+  }
 }
 
 export default Client;

package/README.md

@@ -1,60 +1,181 @@
 # hackchat-engine
 
-A NodeJS and browser friendly JavaScript library used to interact with a hackchat server.
+A modern, NodeJS and browser-friendly ES6 WebSocket library for interacting with [hack.chat](https://hack.chat) servers. This engine provides an object-oriented interface, automatic keep-alives, and structured event handling.
 
-# Installation
+## Installation
 
-## Prerequisites
+### Prerequisites
 
-- [node.js 14.15](https://nodejs.org/en/download/package-manager/) or higher
-- [npm 6](https://nodejs.org/en/download/package-manager/) or higher
+* **Node.js 14+** (This package uses ES Modules)
+* **NPM 6+**
 
-## Install
+### Install
 
-`npm i hackchat-engine`
+```bash
+npm install hackchat-engine
 
-# Usage
+```
+
+---
 
-## Minimum Usage
+## Quick Start
+
+This library uses **ES Modules**. You must use `import` syntax.
 
 ```javascript
-  const { Client } = require('hackchat-engine');
-  const hcClient = new Client();
+import { Client } from 'hackchat-engine';
 
-  const testName = 'testBot';
-  const testPass = 'testBot';
-  const testChannel = 'programming';
+const botName = 'MyBot';
+const botPass = 'secretPassword';
+const channel = 'programming';
 
-  hcClient.on('connected', () => console.log('Connected!'));
+// Initialize the client
+const client = new Client({
+  debug: true
+});
 
-  hcClient.on('session', (payload) => {
-    console.log(payload);
-    hcClient.join(testName, testPass, testChannel);
-  });
+// Triggered when the WebSocket connects to the gateway
+client.on('connected', () => {
+  console.log('Connected to server!');
+  client.ws.send({ cmd: 'getchannels' });
+  client.join(botName, botPass, channel);
+});
 
-  hcClient.on('channelJoined', (payload) => {
-    console.log(payload);
-    hcClient.say(testChannel, 'Bep boop i r bot');
-  });
+// Triggered when the server assigns a session ID
+client.on('session', (session) => {
+  console.log(`Session ID: ${session.sessionID}`);
+});
 
-  hcClient.on('message', (payload) => {
-    console.log(payload);
-    hcClient.say(testChannel, 'No u');
-  });
-```
+// Triggered when the client successfully joins the channel
+client.on('channelJoined', (data) => {
+  console.log(`Joined channel: ${data.channel}`);
+  client.say(channel, 'Hello world! I am a bot.');
+});
 
-## Advanced Usage
+// Triggered on every new message
+client.on('message', (message) => {
+  // Ignore our own messages
+  if (message.user.isMine) return;
 
-** Need to update this, still **
+  console.log(`[${message.channel}] ${message.user.name}: ${message.content}`);
+
+  if (message.content === '!ping') {
+    // Helper method to reply directly to the channel
+    message.reply('Pong!');
+  }
+});
+
+```
 
-### Changing the connection
+---
 
-By default, this engine will connect to 'wss://hack.chat/chat-ws'. To change this, add a `ws.gateway` property to the `options` object, for example:
+## Configuration
+
+You can pass an options object to the `Client` constructor to customize the connection.
 
 ```javascript
-const hcClient = new Client({
+const client = new Client({
+  // Connection details
   ws: {
-    gateway: 'ws://1.1.1.1:6060/',
-  }
+    gateway: 'wss://hack.chat/chat-ws', // Default
+    // gateway: 'ws://127.0.0.1:6060/' // For local development
+  },
+  
+  // Set to true to see internal logs and raw packets
+  debug: false, 
+
+  // If true, identifies as a bot to the server (default: true)
+  isBot: true, 
+});
+
+```
+
+---
+
+## Events
+
+The client extends `EventEmitter`. You can listen for the following events:
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `connected` | `Client` | Socket connection established. |
+| `session` | `SessionStruct` | Server has assigned a session ID. |
+| `channelJoined` | `Object` | Client has successfully joined a channel and received the user list. |
+| `message` | `MessageStruct` | A new message was received. |
+| `userJoined` | `UserStruct` | A user joined the channel. |
+| `userLeft` | `UserStruct` | A user left the channel. |
+| `userUpdate` | `UserStruct` | A user changed their flair, color, or status. |
+| `whisper` | `WhisperStruct` | Received a private whisper. |
+| `invite` | `InviteStruct` | Received an invitation to another channel. |
+| `emote` | `EmoteStruct` | A user sent a `/me` emote. |
+| `warning` | `WarningStruct` | Server sent a warning (e.g., rate limit). |
+| `gotCaptcha` | `CaptchaStruct` | Server requires a captcha solution. |
+| `hackAttempt` | `HackAttemptStruct` | A user attempted a disallowed action (admin alerts). |
+| `updateMessage` | `UpdateMessageStruct` | A previously sent message was edited or deleted. |
+
+---
+
+## Key Methods
+
+### Core
+
+* **`client.join(nick, password, channel)`**: Authenticate and join a specific channel.
+* **`client.say(channel, text)`**: Send a message to a channel.
+* **`client.changeColor(hex)`**: Change your nickname color (e.g., `CCCCCC`).
+* **`client.changeUsername(newNick)`**: Request a nickname change.
+
+### Moderation
+
+* **`client.kick(channel, user)`**: Kick a user (requires permissions).
+* **`client.ban(channel, user)`**: Ban a user (requires permissions).
+* **`client.enableCaptcha(channel)`**: Turn on captcha for the channel.
+* **`client.lockChannel(channel)`**: Lock the channel (admin only).
+
+### Interactions
+
+The `MessageStruct` (passed in the `message` event) has helper methods:
+
+* **`message.reply(text)`**: Automatically replies to the channel the message originated from.
+
+### Message Manipulation
+
+* **`client.updateMessage(customId, text, mode)`**: Edit a message you previously sent.
+* `mode`: `'overwrite'`, `'append'`, `'prepend'`, or `'complete'` (delete).
+
+
+
+---
+
+## Advanced Usage
+
+### Handling Custom Commands
+
+If the server implements custom opcodes that are not natively handled by the engine, you can register a listener for them:
+
+```javascript
+client.onCommand('customEvent', (payload) => {
+  console.log('Received custom packet:', payload);
 });
+
 ```
+
+### Accessing Users
+
+Users are stored in an extended Map for easy access.
+
+```javascript
+// Get a user by ID
+const user = client.users.get(12345);
+
+// Find a user by name
+const user = client.users.find(u => u.username === 'Admin');
+
+if (user) {
+  console.log(`${user.username} is currently ${user.isOnline ? 'Online' : 'Offline'}`);
+}
+
+```
+
+## License
+
+MIT

package/events/EventsManager.js

@@ -14,6 +14,8 @@ import PublicChannels from './PublicChannels.js';
 import HackAttempt from './HackAttempt.js';
 import SignMessage from './SignMessage.js';
 import SignTransaction from './SignTransaction.js';
+import UpdateMessage from './UpdateMessage.js';
+import WalletInfo from './WalletInfo.js';
 
 /**
   * This class routes incoming event data to it's proper handler
@@ -42,6 +44,8 @@ class EventsManager {
     this.HackAttempt = new HackAttempt(this.client);
     this.SignMessage = new SignMessage(this.client);
     this.SignTransaction = new SignTransaction(this.client);
+    this.UpdateMessage = new UpdateMessage(this.client);
+    this.WalletInfo = new WalletInfo(this.client);
   }
 }
 

package/events/HackAttempt.js

@@ -5,7 +5,7 @@ import HackAttemptStruct from '../structures/HackAttemptStruct.js';
   * This class handles an incoming `hackattempt` event from the server
   * @private
   */
-class PublicChannels extends AbstractEvent {
+class HackAttempt extends AbstractEvent {
   /**
     * Event handler function
     * @param {object} data Incoming event data
@@ -21,4 +21,4 @@ class PublicChannels extends AbstractEvent {
   }
 }
 
-export default PublicChannels;
+export default HackAttempt;

package/events/UpdateMessage.js

@@ -0,0 +1,24 @@
+import AbstractEvent from './AbstractEvent.js';
+import UpdateMessageStruct from '../structures/UpdateMessageStruct.js';
+
+/**
+  * This class handles an incoming `updateMessage` event from the server
+  * @private
+  */
+class UpdateMessage extends AbstractEvent {
+  /**
+    * Event handler function
+    * @param {object} data Incoming event data
+    * @returns {object}
+    */
+  handle(data) {
+    const { client } = this;
+    const update = new UpdateMessageStruct(client, data);
+
+    return {
+      update,
+    };
+  }
+}
+
+export default UpdateMessage;

package/events/WalletInfo.js

@@ -0,0 +1,24 @@
+import AbstractEvent from './AbstractEvent.js';
+import WalletInfoStruct from '../structures/WalletInfoStruct.js';
+
+/**
+  * This class handles an incoming `walletInfo` event from the server
+  * @private
+  */
+class WalletInfo extends AbstractEvent {
+  /**
+    * Event handler function
+    * @param {object} data Incoming event data
+    * @returns {object}
+    */
+  handle(data) {
+    const { client } = this;
+    const info = new WalletInfoStruct(client, data);
+
+    return {
+      info,
+    };
+  }
+}
+
+export default WalletInfo;

package/package.json

@@ -59,5 +59,5 @@
     "lintfix": "eslint --fix --ignore-path .gitignore .",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "version": "1.1.8"
+  "version": "1.1.11"
 }

package/structures/HackAttemptStruct.js

@@ -58,7 +58,7 @@ class HackAttemptStruct {
     this.lib = data.lib;
 
     /**
-      * The timestamp the publicchannels was sent at
+      * The timestamp the hackattempt was sent at
       * @type {number}
       */
     this.timestamp = new Date();

package/structures/UpdateMessageStruct.js

@@ -0,0 +1,64 @@
+/**
+  * This class handles parsing of the data of an `updateMessage` event
+  */
+class UpdateMessageStruct {
+  /**
+    * @param {Client} client Main client reference
+    * @param {object} data Incoming event data
+    */
+  constructor(client, data) {
+    /**
+      * Add client reference
+      * @type {Client}
+      * @readonly
+      */
+    Object.defineProperty(this, 'client', { value: client });
+
+    if (data) this.setup(data);
+  }
+
+  /**
+    * Fill in this structure with provided data
+    * @param {object} data Incoming event data
+    * @returns {void}
+    */
+  setup(data) {
+    /**
+      * The channel the message resides in
+      * @type {string}
+      */
+    this.channel = data.channel;
+
+    /**
+      * The customId of the target message
+      * @type {string}
+      */
+    this.customId = data.customId;
+
+    /**
+      * The update mode (overwrite, append, prepend, complete)
+      * @type {string}
+      */
+    this.mode = data.mode;
+
+    /**
+      * The new text content (or text to append/prepend)
+      * @type {string}
+      */
+    this.text = data.text;
+
+    /**
+      * The user who initiated the update
+      * @type {User}
+      */
+    this.user = this.client.users.get(data.userid);
+
+    /**
+      * The timestamp of the update
+      * @type {Date}
+      */
+    this.timestamp = new Date();
+  }
+}
+
+export default UpdateMessageStruct;

package/structures/WalletInfoStruct.js

@@ -0,0 +1,58 @@
+/**
+  * This class handles parsing of the data of a `walletInfo` event
+  */
+class WalletInfoStruct {
+  /**
+    * @param {Client} client Main client reference
+    * @param {object} data Incoming event data
+    */
+  constructor(client, data) {
+    /**
+      * Add client reference
+      * @type {Client}
+      * @readonly
+      */
+    Object.defineProperty(this, 'client', { value: client });
+
+    if (data) this.setup(data);
+  }
+
+  /**
+    * Fill in this structure with provided data
+    * @param {object} data Incoming event data
+    * @returns {void}
+    */
+  setup(data) {
+    /**
+      * The channel where the request originated
+      * @type {string}
+      */
+    this.channel = data.channel;
+
+    /**
+      * The user ID of the target user
+      * @type {number}
+      */
+    this.userid = data.userid;
+
+    /**
+      * The nickname of the target user
+      * @type {string}
+      */
+    this.nick = data.nick;
+
+    /**
+      * The public wallet address of the user
+      * @type {string}
+      */
+    this.address = data.address;
+
+    /**
+      * The user object associated with this wallet info
+      * @type {User|undefined}
+      */
+    this.user = this.client.users.get(data.userid);
+  }
+}
+
+export default WalletInfoStruct;

package/util/Constants.js

@@ -76,6 +76,8 @@ export const OPCodes = {
   REQUEST_SIW: 'siw',
   SIGN_SIW: 'signsiw',
   CONFIRM_TX: 'confirmtx',
+  UPDATE_MESSAGE: 'updateMessage',
+  GET_WALLET: 'getwallet',
 };
 
 /**
@@ -107,6 +109,7 @@ export const Events = {
   HACK_ATTEMPT: 'hackAttempt',
   SIGN_MESSAGE: 'signMessage',
   SIGN_TRANSACTION: 'signTransaction',
+  WALLET_INFO: 'walletInfo',
 };
 
 /**
@@ -130,4 +133,6 @@ export const WSEvents = {
   HACK_ATTEMPT: 'hackAttempt',
   SIGN_MESSAGE: 'signMessage',
   SIGN_TRANSACTION: 'signTransaction',
+  UPDATE_MESSAGE: 'updateMessage',
+  WALLET_INFO: 'walletInfo',
 };

package/websocket/SocketHandler.js

@@ -194,7 +194,7 @@ class SocketHandler extends EventEmitter {
       this.client.setTimeout(() => {
         this.connect(gateway, 0, force);
       },
-        after);
+      after);
 
       return false;
     }

package/websocket/packets/PacketRouter.js

@@ -21,6 +21,8 @@ import PubChannelsHandler from './handlers/PubChannelsHandler.js';
 import HackAttemptHandler from './handlers/HackAttemptHandler.js';
 import SignMessageHandler from './handlers/SignMessageHandler.js';
 import SignTransactionHandler from './handlers/SignTransactionHandler.js';
+import UpdateMessageHandler from './handlers/UpdateMessageHandler.js';
+import WalletInfoHandler from './handlers/WalletInfoHandler.js';
 
 const BeforeReadyWhitelist = [
   WSEvents.SESSION,
@@ -77,6 +79,8 @@ class PacketRouter {
     this.registerEvent(WSEvents.HACK_ATTEMPT, HackAttemptHandler);
     this.registerEvent(WSEvents.SIGN_MESSAGE, SignMessageHandler);
     this.registerEvent(WSEvents.SIGN_TRANSACTION, SignTransactionHandler);
+    this.registerEvent(WSEvents.UPDATE_MESSAGE, UpdateMessageHandler);
+    this.registerEvent(WSEvents.WALLET_INFO, WalletInfoHandler);
   }
 
   /**

package/websocket/packets/handlers/UpdateMessageHandler.js

@@ -0,0 +1,30 @@
+import AbstractHandler from './AbstractHandler.js';
+import { Events } from '../../../util/Constants.js';
+
+/**
+  * Handles an updateMessage packet received from the server
+  * @private
+  */
+class UpdateMessageHandler extends AbstractHandler {
+  /**
+    * Parses incoming packet data and emits related events
+    * @param {object} packet Incoming packet data
+    * @returns {void}
+    */
+  handle(packet) {
+    const { client } = this.packetRouter;
+    const response = client.events.UpdateMessage.handle(packet);
+
+    /**
+      * Emitted when a message update is received
+      * @event Client#updateMessage
+      * @param {UpdateMessageStruct} update The update details
+      */
+    client.emit(Events.UPDATE_MESSAGE, response.update);
+
+    // Emit debug info
+    client.emit(Events.DEBUG, `[${Events.UPDATE_MESSAGE}]: ${packet}`);
+  }
+}
+
+export default UpdateMessageHandler;

package/websocket/packets/handlers/WalletInfoHandler.js

@@ -0,0 +1,30 @@
+import AbstractHandler from './AbstractHandler.js';
+import { Events } from '../../../util/Constants.js';
+
+/**
+  * Handles a walletInfo packet received from the server
+  * @private
+  */
+class WalletInfoHandler extends AbstractHandler {
+  /**
+    * Parses incoming packet data and emits related events
+    * @param {object} packet Incoming packet data
+    * @returns {void}
+    */
+  handle(packet) {
+    const { client } = this.packetRouter;
+    const response = client.events.WalletInfo.handle(packet);
+
+    /**
+      * Emitted when wallet information is received
+      * @event Client#walletInfo
+      * @param {WalletInfoStruct} info The wallet information
+      */
+    client.emit(Events.WALLET_INFO, response.info);
+
+    // Emit debug info
+    client.emit(Events.DEBUG, `[${Events.WALLET_INFO}]: ${packet}`);
+  }
+}
+
+export default WalletInfoHandler;