Updated API docs

docs/filelist

@@ -0,0 +1,19 @@
+src/defaults.js
+src/clients/hook-clients/registry-client.js
+rc/clients/hook-clients/governor-client.js
+src/clients/hook-clients/heartbeat-client.js
+src/clients/hook-clients/hook-client-factory.js
+src/clients/base-evernode-client.js
+src/clients/tenant-client.js
+src/clients/host-client.js
+src/clients/foundation-client.js
+src/xrpl-api.js
+src/xrpl-common.js
+src/xrpl-account.js
+src/evernode-common.js
+src/state-helpers.js
+src/util-helpers.js
+src/transaction-helper.js
+src/encryption-helper.js
+src/evernode-helpers.js
+src/xfl-helpers.js

docs/init-docs.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const path = require('path');
+
+const updateJSDocUtil = () => {
+    const jsdocUtilDumperPath = path.join(__dirname, '../node_modules/jsdoc/lib/jsdoc/util/dumper.js');
+
+    let utilFileContent = fs.readFileSync(jsdocUtilDumperPath, 'utf8');
+
+    const oldUtilFunction = `exports.dump = function(...args) {
+    const result = [];
+    let walker;
+
+    for (let arg of args) {
+        walker = new ObjectWalker();
+        result.push( JSON.stringify(walker.walk(arg), null, 4) );
+    }
+
+    return result.join('\\n');
+};`;
+
+    const newUtilFunction = `exports.dump = function(...args) {
+    const result = [];
+    let walker;
+
+    for (let arg of args) {
+        walker = new ObjectWalker();
+        result.push( JSON.stringify(walker.walk(arg), (key, value) => typeof value == 'bigint' ? value.toString() : value, 4) );
+    }
+
+    return result.join('\\n');
+};`;
+
+    if (utilFileContent.includes(oldUtilFunction)) {
+        utilFileContent = utilFileContent.replace(oldUtilFunction, newUtilFunction);
+        fs.writeFileSync(jsdocUtilDumperPath, utilFileContent, 'utf8');
+        console.log('JSDoc utility function modified successfully!');
+    } else {
+        console.log('JSDoc obsolete utility function is not found.');
+    }
+};
+
+updateJSDocUtil();

package.json

@@ -11,7 +11,9 @@
     "lint": "./node_modules/.bin/eslint src/**/*.js",
     "build": "npm run lint && ncc build src/index.js -e elliptic -e xrpl -e ripple-address-codec -e ripple-binary-codec -e ripple-keypairs -o dist/ && cp evernode-license.pdf dist/",
     "bundle": "npm run build && ./clean-pkg.sh",
-    "publish": "npm run bundle && cp npm-readme.md dist/README.md && npm publish ./dist"
+    "publish": "npm run bundle && cp npm-readme.md dist/README.md && npm publish ./dist",
+    "docs-init": "node docs/init-docs.js",
+    "docs": "echo '# Evernode JS API Documentation' > docs/evernode-js-api.md && xargs jsdoc2md < docs/filelist >> docs/evernode-js-api.md"
   },
   "dependencies": {
     "elliptic": "6.5.4",
@@ -23,6 +25,7 @@
     "xrpl-accountlib": "3.2.9"
   },
   "devDependencies": {
-    "eslint": "8.3.0"
+    "eslint": "8.3.0",
+    "jsdoc-to-markdown": "9.0.1"
   }
 }

src/clients/base-evernode-client.js

@@ -30,6 +30,19 @@ const REPUTATION_VALUE_PARAM_OFFSET = 20;
 // By reputation address <host_address(20)><token_id(32)><error(1)>
 const HOST_DEREG_FROM_REP_PARAM_SIZE = 53;
 
+/**
+ * Creates an instance of BaseEvernodeClient.
+ * @param {string} xrpAddress - The XRP address associated with the client.
+ * @param {string} xrpSecret - The XRP secret associated with the client.
+ * @param {Array<string>} watchEvents - An array of event names to watch.
+ * @param {boolean} [autoSubscribe=false] - Whether to automatically subscribe to events.
+ * @param {Object} [options={}] - Optional configuration options.
+ * @param {string} [options.governorAddress] - The governor address. Defaults to a predefined value if not provided.
+ * @param {XrplApi} [options.xrplApi] - An instance of XrplApi. If not provided, a new instance will be created.
+ * @param {string} [options.rippledServer] - The URL of the rippled server to use if a new XrplApi instance is created.
+ * @param {Object} [options.config] - Optional configuration settings.
+ * @param {string} [options.messagePrivateKey] - The private key for message encryption, if required.
+ */
 class BaseEvernodeClient {
 
     #watchEvents;
@@ -64,8 +77,8 @@ class BaseEvernodeClient {
 
     /**
      * Listens to the subscribed events. This will listen for the event without detaching the handler until it's 'off'.
-     * @param {string} event Event name.
-     * @param {function(event)} handler Callback function to handle the event.
+     * @param {string} event - The name of the event to listen for.
+     * @param {function} handler - The callback function to handle the event. The function takes the event object as a parameter.
      */
     on(event, handler) {
         this.events.on(event, handler);
@@ -91,7 +104,7 @@ class BaseEvernodeClient {
 
     /**
      * Connects the client to xrpl server and do the config loading and subscriptions. 'subscribe' is called inside this.
-     * @returns boolean value, 'true' if success.
+     * @returns Boolean value `true` if the connection is successful.
      */
     async connect(options = {}) {
         if (this.connected)
@@ -140,7 +153,7 @@ class BaseEvernodeClient {
 
     /**
      * Get the EVR balance in the account.
-     * @returns The available EVR amount as a 'string'.
+     * @returns The available EVR amount as a string.
      */
     async getEVRBalance() {
         const lines = await this.xrplAcc.getTrustLines(EvernodeConstants.EVR, this.config.evrIssuerAddress);
@@ -152,7 +165,7 @@ class BaseEvernodeClient {
 
     /**
      * Get all XRPL hook states in the registry account.
-     * @returns The list of hook states including Evernode configuration and hosts.
+     * @returns The list of hook states, including Evernode configuration and hosts.
      */
     async getHookStates() {
         const regAcc = new XrplAccount(this.governorAddress, null, { xrplApi: this.xrplApi });
@@ -166,7 +179,7 @@ class BaseEvernodeClient {
     /**
      * Get the moment from the given index (timestamp).
      * @param {number} index [Optional] Index (timestamp) to get the moment value.
-     * @returns The moment of the given index (timestamp) as 'number'. Returns current moment if index (timestamp) is not given.
+     * @returns The moment of the given index (timestamp) as a number. Returns the current moment if the timestamp is not provided.
      */
     async getMoment(index = null) {
         const i = index || UtilHelpers.getCurrentUnixTime();
@@ -191,7 +204,7 @@ class BaseEvernodeClient {
 
     /**
      * Get Evernode configuration
-     * @returns An object with all the configuration and their values.
+     * @returns An object containing all the configuration keys and their corresponding values.
      */
     async #getEvernodeConfig() {
         const configStateKeys = {
@@ -257,9 +270,10 @@ class BaseEvernodeClient {
     }
 
     /**
-     * Extracts the transaction info from a given transaction..
-     * @param {object} tx Transaction to be deserialized and extracted.
-     * @returns The event object in the format {name: '', data: {}}. Returns null if not handled. Note: You need to deserialize HookParameters before passing the transaction to this function.
+     * Extracts the transaction info from a given transaction.
+     * Note: You need to deserialize HookParameters before passing the transaction to this function.
+     * @param {object} tx - The transaction object to be deserialized and extracted.
+     * @returns {} The event object in format `{name: string, data: Object}`. Returns `null` if the event is not handled. 
      */
     async extractEvernodeEvent(tx) {
         let eventType;
@@ -1072,6 +1086,7 @@ class BaseEvernodeClient {
      * @param {string} shortName Short name for the proposal candidate.
      * @param {*} options [Optional] transaction options.
      * @returns Proposed candidate id.
+     * @ignore
      */
     async _propose(hashes, shortName, options = {}) {
         const hashesBuf = Buffer.from(hashes, 'hex');
@@ -1122,6 +1137,7 @@ class BaseEvernodeClient {
      * @param {string} candidateId Id of the candidate in hex format.
      * @param {*} options [Optional] transaction options.
      * @returns Transaction result.
+     * @ignore
      */
     async _withdraw(candidateId, options = {}) {
         const candidateIdBuf = Buffer.from(candidateId, 'hex');
@@ -1144,6 +1160,7 @@ class BaseEvernodeClient {
      * @param {string} hostAddress Address of the dud host.
      * @param {*} options [Optional] transaction options.
      * @returns Transaction result.
+     * @ignore
      */
     async _reportDudHost(hostAddress, options = {}) {
         const candidateId = StateHelpers.getDudHostCandidateId(hostAddress);

src/clients/foundation-client.js

@@ -15,8 +15,19 @@ const REPUTATION_PARAM_SIZE = 21;
 
 const FoundationEvents = {}
 
+/**
+ * FoundationClient class to manage and interact with foundation operations.
+ * It extends the BaseEvernodeClient.
+ * @extends BaseEvernodeClient
+ */
 class FoundationClient extends BaseEvernodeClient {
 
+    /**
+     * Creates an instance of FoundationClient.
+     * @param {string} xrpAddress - The XRP address to associate with this client.
+     * @param {string} xrpSecret - The secret (private key) associated with the XRP address.
+     * @param {Object} [options={}] - Additional configuration options for the FoundationClient.
+     */
     constructor(xrpAddress, xrpSecret, options = {}) {
         super(xrpAddress, xrpSecret, Object.values(FoundationEvents), false, options);
     }

src/clients/hook-clients/governor-client.js

@@ -16,6 +16,12 @@ const GovernorEvents = {
     LinkedDudHostCandidateRemoved: EvernodeEvents.LinkedDudHostCandidateRemoved
 }
 
+/**
+ * GovernorClient is responsible for managing governor operations in Evernode.
+ * It interacts with the XRP Ledger using the governor address and listens for specific governor events.
+ * 
+ * @extends BaseEvernodeClient
+ */
 class GovernorClient extends BaseEvernodeClient {
     constructor(options = {}) {
         super((options.governorAddress || Defaults.values.governorAddress), null, Object.values(GovernorEvents), false, options);

src/clients/hook-clients/heartbeat-client.js

@@ -6,6 +6,12 @@ const HeartbeatEvents = {
     FoundationVoted: EvernodeEvents.FoundationVoted
 }
 
+/**
+ * HeartbeatClient is responsible for managing heartbeat operations in Evernode.
+ * It interacts with the XRP Ledger using the heartbeat address and listens for specific heartbeat events.
+ * 
+ * @extends BaseEvernodeClient
+ */
 class HeartbeatClient extends BaseEvernodeClient {
     constructor(options = {}) {
         super(options.heartbeatAddress, null, Object.values(HeartbeatEvents), false, options);

src/clients/hook-clients/hook-client-factory.js

@@ -4,11 +4,17 @@ const { GovernorClient } = require("./governor-client");
 const { HeartbeatClient } = require("./heartbeat-client");
 const { ReputationClient } = require("./reputation-client");
 
+/**
+ * A factory class for creating different types of hook clients based on the provided hook type.
+ * @class
+ */
 class HookClientFactory {
     /**
      * Creates a hook client from given type.
-     * @param {string} hookType Type of the Required Hook. (Supported Hook types 'GOVERNOR', 'REGISTRY' and 'HEARTBEAT')
-     * @returns Instance of requested HookClient type.
+     * @param {string} hookType Type of the Required Hook. (Supported Hook types 'GOVERNOR', 'REGISTRY', 'HEARTBEAT' and 'REPUTATION')
+     * @param {Object} [options={}] - Optional configuration for the hook client.
+     * @returns {Promise<Object|null>} - Returns a promise that resolves to an instance of the requested HookClient type, or `null` if the type is unsupported.
+     * @throws {Error} Will throw an error if there is an issue connecting to the GovernorClient or obtaining the necessary configuration.
      */
     static async create(hookType, options = {}) {
         let governorClient;

src/clients/hook-clients/registry-client.js

@@ -11,15 +11,21 @@ const RegistryEvents = {
     HostReputationUpdated: EvernodeEvents.HostReputationUpdated
 }
 
+/**
+ * RegistryClient is responsible for managing registry operations in Evernode.
+ * It interacts with the XRP Ledger using the registry address and listens for specific registry events.
+ * 
+ * @extends BaseEvernodeClient
+ */
 class RegistryClient extends BaseEvernodeClient {
 
     constructor(options = {}) {
         super(options.registryAddress, null, Object.values(RegistryEvents), false, options);
     }
 
     /**
-     * Gets all the active hosts registered in ledger.
-     * @returns The list of active hosts.
+     * Retrieves all active hosts registered in the ledger.
+     * @returns {Promise<Array>} - A promise that resolves to an array of active hosts.
      */
     async getActiveHostsFromLedger() {
         const hosts = await this.getAllHostsFromLedger();

src/clients/hook-clients/reputation-client.js

@@ -3,6 +3,12 @@ const { BaseEvernodeClient } = require("../base-evernode-client");
 
 const ReputationEvents = {}
 
+/**
+ * ReputationClient is responsible for managing reputation operations in Evernode.
+ * It interacts with the XRP Ledger using the reputation address and listens for specific reputation events.
+ * 
+ * @extends BaseEvernodeClient
+ */
 class ReputationClient extends BaseEvernodeClient {
 
     constructor(options = {}) {

src/clients/host-client.js

@@ -64,8 +64,20 @@ const IPV6_FAMILY = 6;
 const MAX_HOST_LEDGER_OFFSET = 30;
 const TX_RETRY_INTERVAL = 10000;
 
+/**
+ * HostClient class to manage host operations.
+ * It extends the BaseEvernodeClient.
+ * @extends BaseEvernodeClient
+ */
 class HostClient extends BaseEvernodeClient {
 
+    /**
+     * Creates an instance of HostClient.
+     * 
+     * @param {string} xrpAddress - The XRP address to associate with this client.
+     * @param {string} xrpSecret - The secret (private key) associated with the XRP address.
+     * @param {Object} [options={}] - Additional configuration options for the HostClient.
+     */
     constructor(xrpAddress, xrpSecret, options = {}) {
         super(xrpAddress, xrpSecret, Object.values(HostEvents), true, options);
     }

src/clients/tenant-client.js

@@ -17,12 +17,27 @@ const TenantEvents = {
     ExtendError: EvernodeEvents.ExtendError,
 }
 
+/**
+ * TenantClient class to manage tenant operations.
+ * It extends the BaseEvernodeClient.
+ * @extends BaseEvernodeClient
+ */
 class TenantClient extends BaseEvernodeClient {
 
+    /**
+     * Creates an instance of TenantClient.
+     * @param {string} xrpAddress - The XRP address to associate with this client.
+     * @param {string} xrpSecret - The secret (private key) associated with the XRP address.
+     * @param {Object} [options={}] - Additional configuration options for the TenantClient.
+     */
     constructor(xrpAddress, xrpSecret, options = {}) {
         super(xrpAddress, xrpSecret, Object.values(TenantEvents), false, options);
     }
 
+    /**
+     * Prepare the tenant account with account fields and trust lines.
+     * @param {Object} [options={}] - Optional configuration for the account setup.
+     */
     async prepareAccount(options = {}) {
         try {
             if (!await this.xrplAcc.getMessageKey())
@@ -33,6 +48,12 @@ class TenantClient extends BaseEvernodeClient {
         }
     }
 
+    /**
+     * Retrieves and validates a lease host based on the given host address.
+     * @param {string} hostAddress - The XRP Ledger address of the host.
+     * @returns {Promise<Object>} - Returns the host object if valid and active.
+     * @throws Will throw an error if the host is invalid, inactive, or not registered.
+     */
     async getLeaseHost(hostAddress) {
         const host = new XrplAccount(hostAddress, null, { xrplApi: this.xrplApi });
         // Find an owned URI token with matching Evernode host NFT prefix.

src/defaults.js

@@ -31,6 +31,9 @@ const getDefinitions = async () => {
     });
 }
 
+/**
+ * Defaults class is responsible for retrieving and overriding the default Evernode network configurations.
+ */
 class Defaults {
     /**
      * Load defaults from the public definitions json.