GridClient types and docstrings

.gitignore

@@ -3,6 +3,7 @@ dist/
 yarn-error.log
 packages/grid_client/docs/tests/
 packages/grid_client/docs/api/
+packages/grid_client/tests/test-reports/
 
 packages/stats/public/build/
 packages/playground/dist/

packages/grid_client/scripts/add_node_to_network.ts

@@ -1,16 +1,16 @@
-import { NetworkAddNodeModel } from "../src";
+import { GridClient, NetworkAddNodeModel } from "../src";
 import { getClient } from "./client_loader";
 import { log } from "./utils";
 
-async function addNode(client, node) {
+async function addNode(client: GridClient, node: NetworkAddNodeModel) {
   const res = await client.networks.addNode(node);
   log("================= Adding node =================");
   log(res);
   log("================= Adding node =================");
 }
 
 async function main() {
-  const grid3 = await getClient();
+  const grid3: GridClient = await getClient("vm/vmu0sir");
   const node: NetworkAddNodeModel = {
     name: "wedtest",
     ipRange: "10.249.0.0/16",
@@ -19,7 +19,6 @@ async function main() {
   };
   // if the network is not created, it will create one and add this node to it.
   await addNode(grid3, node);
-
   await grid3.disconnect();
 }
 main();

packages/grid_client/scripts/calculator.ts

@@ -1,51 +1,51 @@
-import { CalculatorModel, CUModel, SUModel } from "../src";
+import { CalculatorModel, CUModel, GridClient, SUModel } from "../src";
 import { getClient } from "./client_loader";
 import { log } from "./utils";
 
-async function calculateCU(client, CUModel) {
+async function calculateCU(client: GridClient, CUModel: CUModel) {
   const res = await client.calculator.calCU(CUModel);
   log("================= Calculating CU =================");
   log(res);
   log("================= Calculating CU =================");
 }
 
-async function calculateSU(client, SUModel) {
+async function calculateSU(client: GridClient, SUModel: SUModel) {
   const res = await client.calculator.calSU(SUModel);
   log("================= Calculating SU =================");
   log(res);
   log("================= Calculating SU =================");
 }
 
-async function getTFTPrice(client) {
+async function getTFTPrice(client: GridClient) {
   const res = await client.calculator.tftPrice();
   log("================= TFT Price =================");
   log(res);
   log("================= TFT Price =================");
 }
 
-async function getPricingPolicy(client) {
+async function getPricingPolicy(client: GridClient) {
   const res = await client.calculator.getPrices();
   log("================= Pricing Policy =================");
   log(res);
   log("================= Pricing Policy =================");
 }
 
-async function calculateDeployment(client, CalculatorModel) {
+async function calculateDeployment(client: GridClient, CalculatorModel: CalculatorModel) {
   const res = await client.calculator.calculate(CalculatorModel);
   log("================= Deployment Cost =================");
   log(res);
   log("================= Deployment Cost =================");
 }
 
-async function calculateDeploymentWithCurrentBalance(client, CalculatorModel) {
+async function calculateDeploymentWithCurrentBalance(client: GridClient, CalculatorModel: CalculatorModel) {
   const res = await client.calculator.calculateWithMyBalance(CalculatorModel);
   log("================= Deployment Cost with current balance =================");
   log(res);
   log("================= Deployment Cost with current balance =================");
 }
 
 async function main() {
-  const grid3 = await getClient();
+  const grid3: GridClient = await getClient();
   const CalculatorModel: CalculatorModel = {
     cru: 16,
     mru: 8, // GB

packages/grid_client/scripts/checkNodeAlive.ts

@@ -1,9 +1,9 @@
-import { PingNodeOptionsModel } from "../src";
+import { GridClient, PingNodeOptionsModel } from "../src";
 import { getClient } from "./client_loader";
 import { log } from "./utils";
 
-async function pingNode(client, nodeId) {
-  const res = await client.zos.pingNode(nodeId);
+async function pingNode(client: GridClient, node: PingNodeOptionsModel) {
+  const res = await client.zos.pingNode(node);
   log("================= Ping result =================");
   log(res);
   log("================= Ping result =================");

packages/grid_client/scripts/client_loader.ts

@@ -2,27 +2,51 @@ import fs from "fs";
 import path from "path";
 import { env } from "process";
 
-import { GridClient } from "../src";
+import { ClientOptions, GridClient, NetworkEnv } from "../src";
 
-const network = env.NETWORK;
+const network = env.NETWORK as NetworkEnv;
 const mnemonic = env.MNEMONIC;
 const storeSecret = env.STORE_SECRET;
 const ssh_key = env.SSH_KEY;
-let config;
 
-if (network === undefined || mnemonic === undefined || ssh_key === undefined) {
-  console.log("Credentials not all found in env variables. Loading all credentials from default config.json...");
-  config = JSON.parse(fs.readFileSync(path.join(__dirname, "./config.json"), "utf-8"));
-} else {
-  console.log("Credentials loaded from env variables...");
-  config = {
-    network: network,
-    mnemonic: mnemonic,
-    storeSecret: storeSecret,
-    ssh_key: ssh_key,
-  };
+let config: { ssh_key: string } & ClientOptions;
+setConfig();
+
+/**
+ * Loads configuration either from environment variables or from a config.json file.
+ * If environment variables are not fully set, it falls back to loading from the config.json file.
+ */
+function setConfig() {
+  if (network === undefined || mnemonic === undefined || ssh_key === undefined) {
+    console.log("Credentials not all found in env variables. Loading all credentials from default config.json...");
+    config = JSON.parse(fs.readFileSync(path.join(__dirname, "./config.json"), "utf-8"));
+  } else {
+    console.log("Credentials loaded from env variables...");
+    config = {
+      network: network,
+      mnemonic: mnemonic,
+      storeSecret: storeSecret,
+      ssh_key: ssh_key,
+    };
+  }
 }
 
+/**
+ * Function to instantiate and connect a GridClient with a specified project name.
+ *
+ * The project name is important to list your deployments.
+ * @example
+ *
+ * const deploymentName = 'testVM'
+ * const projectName = 'vm/' + deploymentName
+ * const gc = await getClient(projectName)
+ * await gc.machines.deploy({...});
+ * // When you deploy using this project name, you'll only be able to list your deployments using this same project name.
+ * await gc.machines.getObj(deploymentName);
+ *
+ * @param projectName - Optional project name to use with the GridClient instance.
+ * @returns {Promise<GridClient>} - A promise that resolves to a connected GridClient instance.
+ */
 async function getClient(projectName = ""): Promise<GridClient> {
   const gridClient = new GridClient({
     network: config.network,
@@ -34,6 +58,11 @@ async function getClient(projectName = ""): Promise<GridClient> {
   return gridClient;
 }
 
+/**
+ * Function to instantiate and connect a new GridClient using the existing mnemonic as the store secret.
+ *
+ * @returns {Promise<GridClient>} - A promise that resolves to a connected GridClient instance.
+ */
 async function getNewClient(): Promise<GridClient> {
   const gridClient = new GridClient({
     network: config.network,

packages/grid_client/scripts/create_account.ts

@@ -6,7 +6,7 @@ import { NetworkEnv } from "../src/config";
 import config from "./config.json";
 import { log } from "./utils";
 
-async function createAccount(client, relay) {
+async function createAccount(client: GridClient, relay: string) {
   const res = await client.tfchain.createAccount(relay, true);
   log("================= Creating account =================");
   log(res);

packages/grid_client/src/client.ts

@@ -23,6 +23,7 @@ class GridClient {
   config: GridClientConfig;
   rmbClient: RMBClient;
   tfclient: TFClient;
+  /**The `MachinesModule` class provides methods to interact with machine operations.*/
   machines: modules.machines;
   k8s: modules.k8s;
   zdbs: modules.zdbs;
@@ -36,22 +37,36 @@ class GridClient {
   capacity: modules.capacity;
   twinId: number;
   nodes: modules.nodes;
+  /**The `Algorand` class provides methods to interact with algorand operations.*/
   algorand: modules.algorand;
+  /**The `TFChain` class provides methods to interact with tfchain operations.*/
   tfchain: modules.tfchain;
+  /**The `Stellar` class provides methods to interact with stellar operations.*/
   stellar: modules.stellar;
+  /**The `Blockchain` class representing a Blockchain interface that manages accounts across different blockchain types such as Algorand, Stellar, and TFChain.*/
   blockchain: modules.blockchain;
+  /**The `Calculator` class for performing various calculations related to pricing and resources.*/
   calculator: modules.calculator;
   currency: modules.currency;
   utility: modules.utility;
   farmerbot: modules.farmerbot;
   farms: modules.farms;
+  /**The `NetworkModule` class provides methods to interact with network operations.*/
   networks: modules.networks;
   dao: modules.dao;
   bridge: modules.bridge;
   modules: string[] = [];
 
   readonly _mnemonic: string;
 
+  /**
+   * The `GridClient` class is a main entry point for interacting with the Grid.
+   * It provides methods to connect to the `chain`, manage node resources, and interact with various modules.
+   *
+   * Initializes a new instance of the `GridClient` class.
+   *
+   * @param {ClientOptions} clientOptions - The client options for configuring the Grid client.
+   */
   constructor(public clientOptions: ClientOptions) {
     if (!clientOptions.storeSecret && validateMnemonic(clientOptions.mnemonic)) {
       this._mnemonic = clientOptions.mnemonic;
@@ -85,6 +100,17 @@ class GridClient {
       throw new GridClientError(`Unknown NETWORK selected! Acceptable networks are [dev | qa | test | main ]`);
     }
   }
+
+  /**
+   * Connects to the Grid based on the network, could be [`devnet`, `qanet`, `testnet`, `mainnet`].
+   *
+   * This method sets up the necessary clients for interacting with the Grid,
+   * establishes connections, and performs key migrations if required.
+   *
+   * @returns {Promise<void>} A promise that resolves when the connection is established.
+   *
+   * @throws {TwinNotExistError} If the twin for the provided mnemonic does not exist on the network.
+   */
   async connect(): Promise<void> {
     const urls = this.getDefaultUrls(this.clientOptions.network);
 
@@ -119,6 +145,11 @@ class GridClient {
     await migrateKeysEncryption.apply(this, [GridClient]);
   }
 
+  /**
+   * Internal method to initialize the client configuration and modules.
+   *
+   * This method is called internally to set up the configuration and instantiate the modules.
+   */
   _connect(): void {
     const urls = this.getDefaultUrls(this.clientOptions.network);
     const storePath = PATH.join(appPath, this.clientOptions.network, String(this.twinId));
@@ -151,6 +182,15 @@ class GridClient {
     }
   }
 
+  /**
+   * Tests the connection URLs to ensure they are reachable.
+   *
+   * @param {Record<string, string>} urls - The URLs to test.
+   *
+   * @returns {Promise<void>} A promise that resolves when the URLs are successfully tested.
+   *
+   * @throws {Error} If any of the URLs fail to connect.
+   */
   async testConnectionUrls(urls: Record<string, string>): Promise<void> {
     try {
       await send("get", urlJoin(urls.rmbProxy, "version"), "", {});
@@ -170,6 +210,14 @@ class GridClient {
     }
   }
 
+  /**
+    * Gets the configured URLs (or the default URLs if not provided) for the specified network environment.  
+
+   *
+   * @param {NetworkEnv} network - The network environment.
+   *
+   * @returns {Record<string, string>} The default URLs for the network environment.
+   */
   getDefaultUrls(network: NetworkEnv): Record<string, string> {
     const base = network === NetworkEnv.main ? "grid.tf" : `${network}.grid.tf`;
     const { proxyURL, relayURL, substrateURL, graphqlURL, activationURL } = this.clientOptions;
@@ -184,18 +232,33 @@ class GridClient {
     return urls;
   }
 
+  /**
+   * Disconnects from the Grid clients.
+   *
+   * This method disconnects the RMB and TF clients, terminating the connection to the Grid network.
+   *
+   * @returns {Promise<void>} A promise that resolves when the disconnection is complete.
+   */
   async disconnect(): Promise<void> {
     if (this.rmbClient) await this.rmbClient.disconnect();
     if (this.tfclient) await this.tfclient.disconnect();
   }
 
-  async invoke(message, args) {
+  /**
+   * Invokes a method on a specified module with the provided arguments.
+   *
+   * This method allows dynamic invocation of module methods by specifying the module and method names.
+   *
+   * @param {string} message - The message specifying the module and method.
+   * @param {string} args - The args of the module.
+   */
+  async invoke(message: string, args: any) {
     const namespaces = message.split(".");
     if (namespaces.length > 2) {
       throw new ValidationError(`Message must include 2 parts only not ${namespaces.length}.`);
     }
 
-    const method = namespaces.pop();
+    const method = namespaces.pop() as string;
 
     const module_name = namespaces[0];
     if (!this.modules.includes(module_name)) {

packages/grid_client/src/clients/tf-grid/balances.ts

@@ -1,8 +1,23 @@
-import { Balance, Balances, BalanceTransferOptions, Client, QueryBalancesGetOptions } from "@threefold/tfchain_client";
+import {
+  Balance,
+  Balances,
+  BalanceTransferOptions,
+  Client,
+  ExtrinsicResult,
+  QueryBalancesGetOptions,
+} from "@threefold/tfchain_client";
 import { GridClientError } from "@threefold/types";
 import { Decimal } from "decimal.js";
 
 class TFBalances extends Balances {
+  /**
+   * Get the balance for a specific address.
+   *
+   * This method retrieves the balance for a specific address in TFT.
+   *
+   * @param {QueryBalancesGetOptions} options - The options for getting the balance, including the address.
+   * @returns {Promise<Balance>} A promise that resolves with the balance object containing free, reserved, and frozen amounts.
+   */
   async get(options: QueryBalancesGetOptions): Promise<Balance> {
     const balances = await super.get(options);
     for (const b of Object.keys(balances)) {
@@ -12,13 +27,26 @@ class TFBalances extends Balances {
     return balances;
   }
 
-  async transfer(options: BalanceTransferOptions) {
+  /**
+   * Prepare a Transfer extrinsic for a specified amount of TFT (`ThreeFold Tokens`) to a given address.
+   *
+   * @param {BalanceTransferOptions} options - The transfer options, including the destination address and the amount to transfer.
+   * @returns {Promise<ExtrinsicResult<number>>} A promise that resolves once the transfer extrinsic is created.
+   */
+  async transfer(options: BalanceTransferOptions): Promise<ExtrinsicResult<number>> {
     const decimalAmount = new Decimal(options.amount);
     const decimalAmountInTFT = decimalAmount.mul(10 ** 7).toNumber();
     return await super.transfer({ address: options.address, amount: decimalAmountInTFT });
   }
 
-  async getMoreFunds() {
+  /**
+   * Fund the wallet with `100TFT` on `Dev | QA` nets for the current user.
+   *
+   * This method fetches additional funds for the current user from the TFChain.
+   *
+   * @returns {Promise<number>} A promise that resolves once the funds are successfully retrieved.
+   */
+  async getMoreFunds(): Promise<number> {
     if (!this.client.url.includes("qa") && !this.client.url.includes("dev")) {
       throw new GridClientError("Unable to get more TFTs.");
     }