refactor: Improve code readability and documentation in assets.servic…

…e.ts, router.service.ts, swap.service.ts, tonapi.service.ts, and convert.ts

src/services/assets/assets.service.ts

@@ -2,12 +2,18 @@ import { Services } from '../../core/services';
 import { Asset, PaginatedAssets } from '../../types/assets';
 
 export class Assets extends Services {
-    public async getExactAsset(asset: string): Promise<Asset | null> {
+    /**
+     * Retrieves an exact asset from the server.
+     *
+     * @param {string} asset - The token address you want.
+     * @returns {Promise<Asset | null>} A promise that resolves to the token if found, or null if not found.
+     */
+    public async getExactAsset(token_address: string): Promise<Asset | null> {
         const assets = await this.client.request.send<Asset[]>({
             url: '/swap-process/data/assets/find/exactSearch',
             method: 'POST',
             data: {
-                assets: [asset],
+                assets: [token_address],
             },
         });
         if (assets.length > 0) {
@@ -18,7 +24,10 @@ export class Assets extends Services {
     }
 
     /**
-     * getAssets
+     * Retrieves a list of assets from the server based on the provided asset addresses.
+     *
+     * @param {string[]} assetsAddress - An array of asset addresses to fetch.
+     * @returns {Promise<Asset[]>} A promise that resolves to an array of assets.
      */
     public async getAssets(assetsAddress: string[]) {
         const listOfAssets = await this.client.request.send<{ list: Asset[] }>({
@@ -32,7 +41,12 @@ export class Assets extends Services {
     }
 
     /**
-     * getPaginatedAssets
+     * Retrieves a paginated list of assets from the server.
+     *
+     * @param {number} [page=1] page  - The page number to retrieve. Defaults to 1.
+     * @param {boolean} [warning=false] warning - A boolean indicating whether to include warnings. Defaults to false.
+     * @param {string} [phrase=''] phrase - An optional search phrase to filter the assets.
+     * @returns {Promise<PaginatedAssets>} A promise that resolves to a paginated list of assets.
      */
     public async getPaginatedAssets(page = 1, warning = false, phrase?: string) {
         const listOfAssets = await this.client.request.send<PaginatedAssets>({
@@ -45,7 +59,13 @@ export class Assets extends Services {
     }
 
     /**
-     * getPairs
+     * Retrieves a paginated list of asset pairs from the server.
+     *
+     * @param {string} assetAddress - The address of the asset to fetch pairs for.
+     * @param {number} [page=1] - The page number to retrieve. Defaults to 1.
+     * @param {boolean} [warning=false] - A boolean indicating whether to include warnings. Defaults to false.
+     * @param {string} [searchPhrase=''] - An optional search phrase to filter the asset pairs.
+     * @returns {Promise<PaginatedAssets>} A promise that resolves to a paginated list of asset pairs.
      */
     public async getPairs(
         assetAddress: string,

src/services/router/router.service.ts

@@ -2,14 +2,26 @@ import { Services } from '../../core/services';
 import { BestRoute, Dex } from '../../types/router';
 
 export class Router extends Services {
+    /**
+     * Finds the best route for a given input and output asset address, pay amount, and optional slippage and DEX.
+     *
+     * @param {string} inputAssetAddress - The address of the input asset.
+     * @param {string} outputAssetAddress - The address of the output asset.
+     * @param {bigint} payAmount - The amount to be paid.
+     * @param {number} [slippage] - Optional slippage percentage.
+     * @param {Dex} [forceDex] - Optional DEX to force the route through.
+     * @returns {Promise<BestRoute>} A promise that resolves to the best route.
+     *
+     * @todo Add validation for address and slippage.
+     * @todo If the user doesn't input an address, get the address by asset service.
+     */
     public async findBestRoute(
         inputAssetAddress: string,
         outputAssetAddress: string,
         payAmount: bigint,
         slippage?: number,
         forceDex?: Dex,
     ) {
-        // TODO Validation on address, slippage
         // TODO if User doesn't input address get address by asset service
 
         const body = {

src/services/swap/swap.service.ts

@@ -4,7 +4,12 @@ import { SwapResponse } from '../../types/swap';
 
 export class Swap extends Services {
     /**
-     * swap
+     * Creates a swap request using the provided user wallet address and best route.
+     *
+     * @param {string} userWalletAddress - The address of the user's wallet.
+     * @param {BestRoute} bestRoute - The best route from router.
+     * @param {string} [app_id] - Optional application ID to include in the request headers.
+     * @returns {Promise<SwapResponse>} A promise that resolves to the swap response.
      */
     public async createSwap(userWalletAddress: string, bestRoute: BestRoute, app_id?: string) {
         return await this.client.request.send<SwapResponse>({

src/services/tonapi/tonapi.service.ts

@@ -11,6 +11,13 @@ import {
 import { TransactionEvent } from '../../types/transaction-event';
 
 export class TonApi extends Services {
+    /**
+     * Fetches the jetton data for a given wallet address and jetton address.
+     *
+     * @param {string} walletAddr - The wallet address to fetch the jetton data for.
+     * @param {string} jettonAddress - The jetton address to fetch the data from.
+     * @returns {Promise<Balance>} A promise that resolves to the balance data.
+     */
     public async getJettonData(walletAddr: string, jettonAddress: string) {
         const data = await this.client.request.send<Balance>({
             baseURL: 'https://tonapi.io/v2',
@@ -21,6 +28,13 @@ export class TonApi extends Services {
         return data;
     }
 
+    /**
+     * Retrieves a custom payload for a specific wallet and jetton address.
+     *
+     * @param {string} walletAddr - The address of the wallet.
+     * @param {string} jettonAddress - The address of the jetton.
+     * @returns {Promise<CustomPayload>} A promise that resolves to the custom payload.
+     */
     public async getCustomPayload(walletAddr: string, jettonAddress: string) {
         const data = await this.client.request.send<CustomPayload>({
             baseURL: 'https://tonapi.io/v2',
@@ -32,7 +46,12 @@ export class TonApi extends Services {
     }
 
     /**
-     * getWalletAssets
+     * Retrieves wallet assets for a given wallet address, including balances and rates for jettons.
+     *
+     * @param {string} walletAddress - The address of the wallet to retrieve assets for.
+     * @param {string[]} [currencies=['usd']] - An array of currency codes to retrieve rates for.
+     * @param {boolean} [custom_payload=true] - Whether to include custom payload in the request.
+     * @returns {Promise<Map<string, Balance>>} A promise that resolves to a map of balances keyed by jetton addresses.
      */
     public async getWalletAssets(
         walletAddress: string,
@@ -87,7 +106,10 @@ export class TonApi extends Services {
     }
 
     /**
-     * getAssetsRates
+     * Fetches the rates of specified assets from the TON API.
+     *
+     * @param {string[]} assetsAddresses - An array of asset addresses to fetch rates for.
+     * @returns {Promise<Map<string, Prices>>} A promise that resolves to a map where the keys are user-friendly asset addresses and the values are their corresponding prices.
      */
     public async getAssetsRates(assetsAddresses: string[]) {
         const addresses = assetsAddresses.join(',');
@@ -110,6 +132,15 @@ export class TonApi extends Services {
     /**
      * waitForTransactionResult
      */
+    /**
+     * Waits for a transaction result by periodically checking the transaction status.
+     *
+     * @param {string} hash - The hash of the transaction to wait for.
+     * @param {number} [period_ms=3000] - The period in milliseconds to wait between checks.
+     * @param {number} [maxRetry=30] - The maximum number of retries before giving up.
+     * @returns {Promise<TransactionEvent>} - A promise that resolves with the transaction result when complete.
+     * @throws {Error} - Throws an error if the maximum number of retries is reached.
+     */
     public async waitForTransactionResult(
         hash: string,
         period_ms: number = 3000,
@@ -140,8 +171,10 @@ export class TonApi extends Services {
     }
 
     /**
-     * getTransactionEvent
+     * Fetches a transaction event from the TON API using the provided hash.
      *
+     * @param {string} hash - The hash of the transaction event to retrieve.
+     * @returns {Promise<TransactionEvent>} A promise that resolves to the transaction event.
      */
     public async getTransactionEvent(hash: string) {
         const event = await this.client.request.send<TransactionEvent>({
@@ -152,7 +185,11 @@ export class TonApi extends Services {
     }
 
     /**
-     * allTransactionComplete
+     * Checks if all transactions in the given event are complete.
+     *
+     * @param {TransactionEvent} event - The transaction event to check.
+     * @returns {boolean} - Returns `true` if all transactions are complete and successful, otherwise `false`.
+     * @throws {Error} - Throws an error if any transaction action has a status other than 'ok'.
      */
     public allTransactionComplete(event: TransactionEvent) {
         if (event.in_progress) return false;

src/utils/convert.ts

@@ -1,3 +1,11 @@
+/**
+ * Converts a given number, string, or bigint to a bigint with the specified number of decimals.
+ *
+ * @param {number | string | bigint} src - The source value to convert. It can be a number, string, or bigint.
+ * @param {number} [decimals=9] - The number of decimal places to consider for the conversion. Defaults to 9.
+ * @returns {bigint} - The converted value as a bigint.
+ * @throws {Error} - Throws an error if the input number is not finite, if the input string is invalid, or if the input number does not have enough precision.
+ */
 export function toNano(src: number | string | bigint, decimals: number = 9): bigint {
     if (typeof src === 'bigint') {
         return src * 10n ** BigInt(decimals);
@@ -59,6 +67,13 @@ export function toNano(src: number | string | bigint, decimals: number = 9): big
     }
 }
 
+/**
+ * Converts a value from nano units to a string representation with the specified number of decimals.
+ *
+ * @param {bigint | number | string} src - The source value in nano units. It can be a bigint, number, or string.
+ * @param {number} [decimals=9] - The number of decimal places to include in the output string. Defaults to 9.
+ * @returns {string} The converted value as a string with the specified number of decimals.
+ */
 export function fromNano(src: bigint | number | string, decimals: number = 9) {
     let v = BigInt(src);
     let neg = false;