@covalenthq/client-sdk 0.6.1 → 0.6.3

package/README.md

@@ -97,6 +97,16 @@ The `BalanceService` class refers to the [balances API endpoints](https://www.co
 - `getTokenHoldersV2ForTokenAddressByPage()`: Get a list of all the token holders for a specified ERC20 or ERC721 token. Returns historic token holders when block-height is set (defaults to latest). Useful for building pie charts of token holders. (Nonpaginated)
 - `getNativeTokenBalance()`: Get the native token balance for an address. This endpoint is required because native tokens are usually not ERC20 tokens and sometimes you want something lightweight.
 
+The `calculatePrettyBalance` function is designed to take up to 4 inputs: the `balance` field obtained from the `tokenBalance` endpoint and the `contract_decimals`. The function also includes two optional fields, `roundOff` and `precision`, to allow developers to round the unscaled balance to a certain decimal precision. The primary purpose of this function is to convert the scaled token balance (the balance parameter) into its unscaled, human-readable form. The scaled balance needs to be divided by 10^(contractDecimals) to remove the scaling factor.
+
+```ts
+import { CovalentClient, calculatePrettyBalance } from "@covalenthq/client-sdk";
+
+const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
+const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
+const prettyBalance = calculatePrettyBalance(resp.data.items[0].balance, resp.data.items[0].contract_decimals);
+```
+
 ### BaseService
 
 The `BaseService` class refers to the [address activity, log events, chain status and block retrieval API endpoints](https://www.covalenthq.com/docs/api/base/get-address-activity/):
@@ -145,11 +155,26 @@ The `PricingService` class refers to the [historical token prices API endpoint](
 The `TransactionService` class refers to the [transactions API endpoints](https://www.covalenthq.com/docs/api/transactions/get-a-transaction/):
 
 - `getAllTransactionsForAddress()`: Fetch and render the most recent transactions involving an address. Frequently seen in wallet applications. (Paginated)
-- `getTransactionsForAddressV3()`: Fetch and render the most recent transactions involving an address. Frequently seen in wallet applications. (Nonpaginated)
+- `getAllTransactionsForAddressByPage()`: Fetch and render the most recent transactions involving an address. Frequently seen in wallet applications. (Nonpaginated)
+- `getTransactionsForAddressV3()`: Fetch and render the most recent transactions involving an address. Frequently seen in wallet applications.
 - `getTransaction()`: Fetch and render a single transaction including its decoded log events. Additionally return semantically decoded information for DEX trades, lending and NFT sales.
 - `getTransactionsForBlock()`: Fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.
 - `getTransactionSummary()`: Fetch the earliest and latest transactions, and the transaction count for a wallet. Calculate the age of the wallet and the time it has been idle and quickly gain insights into their engagement with web3.
 
+The functions `getAllTransactionsForAddressByPage()` and `getTransactionsForAddressV3()` have been enhanced with the introduction of `next()` and `prev()` support functions. These functions facilitate a smoother transition for developers navigating through our links object, which includes `prev` and `next` fields. Instead of requiring developers to manually extract values from these fields and create JavaScript API fetch calls for the URL values, the new `next()` and `prev()` functions provide a streamlined approach, allowing developers to simulate this behavior more efficiently.
+
+```ts
+import { CovalentClient } from "@covalenthq/client-sdk";
+
+const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
+const resp = await client.TransactionService.getAllTransactionsForAddressByPage("eth-mainnet", "WALLET_ADDRESS");
+// assuming resp.data.current_page is 10
+if (resp.data !== null) {
+    const prevPage = await resp.data.prev() // will retrieve page 9
+    console.log(prevPage.data)
+}
+```
+
 ### XykService
 
 The `XykService` refers to the [Xy=k API endpoints](https://www.covalenthq.com/docs/api/xyk/get-xyk-pools/):

package/dist/cjs/index.d.ts

@@ -7,3 +7,4 @@ export * from "./util/types/SecurityServiceTypes";
 export * from "./util/types/XykServiceTypes";
 export * from "./util/types/GenericTypes";
 export * from "./util/types/TransactionServiceTypes";
+export { calculatePrettyBalance } from "./util/CalculatePrettyBalance";

package/dist/cjs/index.js

@@ -2,6 +2,7 @@
 
 var chalk = require('chalk');
 var dateFns = require('date-fns');
+var Big = require('big.js');
 
 const DEFAULT_BACKOFF_MAX_RETRIES = 5;
 const BASE_DELAY_MS = 1000; // Base delay in milliseconds
@@ -658,6 +659,7 @@ class BlockTransactionWithContractTransfers {
         this.gas_quote = data.gas_quote;
         this.pretty_gas_quote = data.pretty_gas_quote;
         this.gas_quote_rate = data.gas_quote_rate;
+        this.explorers = data.explorers && data.explorers !== null ? data.explorers.map((itemData) => new Explorer$1(itemData)) : null;
         this.transfers = data.transfers && data.transfers !== null ? data.transfers.map((itemData) => new TokenTransferItem(itemData)) : null;
     }
 }
@@ -669,6 +671,12 @@ let Pagination$3 = class Pagination {
         this.total_count = data.total_count;
     }
 };
+let Explorer$1 = class Explorer {
+    constructor(data) {
+        this.label = data.label;
+        this.url = data.url;
+    }
+};
 class TokenTransferItem {
     constructor(data) {
         this.block_signed_at = data.block_signed_at && data.block_signed_at !== null ? dateFns.parseISO(data.block_signed_at.toString()) : null;
@@ -3877,6 +3885,7 @@ class Transaction {
         this.pretty_gas_quote = data.pretty_gas_quote;
         this.gas_quote_rate = data.gas_quote_rate;
         this.gas_metadata = data.gas_metadata && data.gas_metadata !== null ? new ContractMetadata(data.gas_metadata) : null;
+        this.explorers = data.explorers && data.explorers !== null ? data.explorers.map((itemData) => new Explorer(itemData)) : null;
         this.dex_details = data.dex_details && data.dex_details !== null ? new DexReport(data.dex_details) : null;
         this.nft_sale_details = data.nft_sale_details && data.nft_sale_details !== null ? new NftSalesReport(data.nft_sale_details) : null;
         this.lending_details = data.lending_details && data.lending_details !== null ? new LendingReport(data.lending_details) : null;
@@ -3894,6 +3903,12 @@ class ContractMetadata {
         this.logo_url = data.logo_url;
     }
 }
+class Explorer {
+    constructor(data) {
+        this.label = data.label;
+        this.url = data.url;
+    }
+}
 class DexReport {
     constructor(data) {
         this.log_offset = data.log_offset;
@@ -4051,6 +4066,154 @@ class Param {
         this.value = data.value;
     }
 }
+class RecentTransactionsResponse {
+    constructor(data, _debug, _apiKey, _threadCount, _urlParams) {
+        this._debug = _debug;
+        this._apiKey = _apiKey;
+        this._threadCount = _threadCount;
+        this._urlParams = _urlParams;
+        this.address = data.address;
+        this.updated_at = data.updated_at && data.updated_at !== null ? dateFns.parseISO(data.updated_at.toString()) : null;
+        this.quote_currency = data.quote_currency;
+        this.chain_id = data.chain_id;
+        this.chain_name = data.chain_name;
+        this.current_page = data.current_page;
+        this.links = data.links && data.links !== null ? new PaginationLinks(data.links) : null;
+        this.items = data.items && data.items !== null ? data.items.map((itemData) => new Transaction(itemData)) : null;
+    }
+    async prev() {
+        let success = false;
+        let data;
+        let response;
+        const backoff = new ExponentialBackoff(this._apiKey, this._debug);
+        const LIMIT = pLimit$1(this._threadCount);
+        while (!success) {
+            try {
+                let startTime;
+                if (this._debug) {
+                    startTime = typeof performance !== 'undefined' ? performance.now() : process.hrtime();
+                }
+                if (this.links.prev === null) {
+                    success = true;
+                    return {
+                        data: null,
+                        error: true,
+                        error_code: 400,
+                        error_message: "Invalid URL: URL link cannot be null"
+                    };
+                }
+                response = await LIMIT(() => fetch(`${this.links.prev}?${this._urlParams}`, {
+                    headers: {
+                        "Authorization": `Bearer ${this._apiKey}`,
+                        "X-Requested-With": userAgent
+                    }
+                }));
+                debugOutput(response.url, response.status, startTime);
+                if (response.status === 429) {
+                    try {
+                        data = await LIMIT(() => backoff.backOff(response.url));
+                    }
+                    catch (error) {
+                        success = true;
+                        return {
+                            data: null,
+                            error: true,
+                            error_code: response.status,
+                            error_message: error.message
+                        };
+                    }
+                }
+                else {
+                    data = await response.json();
+                }
+                const dataClass = new RecentTransactionsResponse(data.data, this._debug, this._apiKey, this._threadCount, this._urlParams);
+                checkAndModifyResponse(dataClass);
+                success = true;
+                return {
+                    data: dataClass,
+                    error: data.error,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+            catch (error) {
+                success = true;
+                return {
+                    data: null,
+                    error: true,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+        }
+    }
+    async next() {
+        let success = false;
+        let data;
+        let response;
+        const backoff = new ExponentialBackoff(this._apiKey, this._debug);
+        const LIMIT = pLimit$1(this._threadCount);
+        while (!success) {
+            try {
+                let startTime;
+                if (this._debug) {
+                    startTime = typeof performance !== 'undefined' ? performance.now() : process.hrtime();
+                }
+                if (this.links.next === null) {
+                    success = true;
+                    return {
+                        data: null,
+                        error: true,
+                        error_code: 400,
+                        error_message: "Invalid URL: URL link cannot be null"
+                    };
+                }
+                response = await LIMIT(() => fetch(`${this.links.next}?${this._urlParams}`, {
+                    headers: {
+                        "Authorization": `Bearer ${this._apiKey}`,
+                        "X-Requested-With": userAgent
+                    }
+                }));
+                debugOutput(response.url, response.status, startTime);
+                if (response.status === 429) {
+                    try {
+                        data = await LIMIT(() => backoff.backOff(response.url));
+                    }
+                    catch (error) {
+                        success = true;
+                        return {
+                            data: null,
+                            error: true,
+                            error_code: response.status,
+                            error_message: error.message
+                        };
+                    }
+                }
+                else {
+                    data = await response.json();
+                }
+                const dataClass = new RecentTransactionsResponse(data.data, this._debug, this._apiKey, this._threadCount, this._urlParams);
+                checkAndModifyResponse(dataClass);
+                success = true;
+                return {
+                    data: dataClass,
+                    error: data.error,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+            catch (error) {
+                success = true;
+                return {
+                    data: null,
+                    error: true,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+        }
+    }
+}
 class PaginationLinks {
     constructor(data) {
         this.prev = data.prev;
@@ -4089,7 +4252,11 @@ class TransactionSummary {
     }
 }
 class TransactionsResponse {
-    constructor(data) {
+    constructor(data, _debug, _apiKey, _threadCount, _urlParams) {
+        this._debug = _debug;
+        this._apiKey = _apiKey;
+        this._threadCount = _threadCount;
+        this._urlParams = _urlParams;
         this.address = data.address;
         this.updated_at = data.updated_at && data.updated_at !== null ? dateFns.parseISO(data.updated_at.toString()) : null;
         this.quote_currency = data.quote_currency;
@@ -4099,6 +4266,138 @@ class TransactionsResponse {
         this.links = data.links && data.links !== null ? new PaginationLinks(data.links) : null;
         this.items = data.items && data.items !== null ? data.items.map((itemData) => new Transaction(itemData)) : null;
     }
+    async prev() {
+        let success = false;
+        let data;
+        let response;
+        const backoff = new ExponentialBackoff(this._apiKey, this._debug);
+        const LIMIT = pLimit$1(this._threadCount);
+        while (!success) {
+            try {
+                let startTime;
+                if (this._debug) {
+                    startTime = typeof performance !== 'undefined' ? performance.now() : process.hrtime();
+                }
+                if (this.links.prev === null) {
+                    success = true;
+                    return {
+                        data: null,
+                        error: true,
+                        error_code: 400,
+                        error_message: "Invalid URL: URL link cannot be null"
+                    };
+                }
+                response = await LIMIT(() => fetch(`${this.links.prev}?${this._urlParams}`, {
+                    headers: {
+                        "Authorization": `Bearer ${this._apiKey}`,
+                        "X-Requested-With": userAgent
+                    }
+                }));
+                debugOutput(response.url, response.status, startTime);
+                if (response.status === 429) {
+                    try {
+                        data = await LIMIT(() => backoff.backOff(response.url));
+                    }
+                    catch (error) {
+                        success = true;
+                        return {
+                            data: null,
+                            error: true,
+                            error_code: response.status,
+                            error_message: error.message
+                        };
+                    }
+                }
+                else {
+                    data = await response.json();
+                }
+                const dataClass = new TransactionsResponse(data.data, this._debug, this._apiKey, this._threadCount, this._urlParams);
+                checkAndModifyResponse(dataClass);
+                success = true;
+                return {
+                    data: dataClass,
+                    error: data.error,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+            catch (error) {
+                success = true;
+                return {
+                    data: null,
+                    error: true,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+        }
+    }
+    async next() {
+        let success = false;
+        let data;
+        let response;
+        const backoff = new ExponentialBackoff(this._apiKey, this._debug);
+        const LIMIT = pLimit$1(this._threadCount);
+        while (!success) {
+            try {
+                let startTime;
+                if (this._debug) {
+                    startTime = typeof performance !== 'undefined' ? performance.now() : process.hrtime();
+                }
+                if (this.links.next === null) {
+                    success = true;
+                    return {
+                        data: null,
+                        error: true,
+                        error_code: 400,
+                        error_message: "Invalid URL: URL link cannot be null"
+                    };
+                }
+                response = await LIMIT(() => fetch(`${this.links.next}?${this._urlParams}`, {
+                    headers: {
+                        "Authorization": `Bearer ${this._apiKey}`,
+                        "X-Requested-With": userAgent
+                    }
+                }));
+                debugOutput(response.url, response.status, startTime);
+                if (response.status === 429) {
+                    try {
+                        data = await LIMIT(() => backoff.backOff(response.url));
+                    }
+                    catch (error) {
+                        success = true;
+                        return {
+                            data: null,
+                            error: true,
+                            error_code: response.status,
+                            error_message: error.message
+                        };
+                    }
+                }
+                else {
+                    data = await response.json();
+                }
+                const dataClass = new TransactionsResponse(data.data, this._debug, this._apiKey, this._threadCount, this._urlParams);
+                checkAndModifyResponse(dataClass);
+                success = true;
+                return {
+                    data: dataClass,
+                    error: data.error,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+            catch (error) {
+                success = true;
+                return {
+                    data: null,
+                    error: true,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+        }
+    }
 }
 /**
  * Transactions APIs
@@ -4299,6 +4598,88 @@ class TransactionService {
             }
         }
     }
+    /**
+     *
+     * Commonly used to fetch and render the most recent transactions involving an address. Frequently seen in wallet applications.
+     *
+     * @param {string} chainName - The chain name eg: `eth-mainnet`.
+     * @param {string} walletAddress - The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically.
+     * @param {GetAllTransactionsForAddressQueryParamOpts} queryParamOpts
+     *   - `quoteCurrency`: The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
+     *   - `noLogs`: Omit log events.
+     *   - `blockSignedAtAsc`: Sort the transactions in ascending chronological order. By default, it's set to `false` and returns transactions in descending chronological order.
+     *   - `withSafe`: Include safe details.
+     *
+     */
+    async getAllTransactionsForAddressByPage(chainName, walletAddress, queryParamOpts) {
+        let success = false;
+        let data;
+        let response;
+        const backoff = new ExponentialBackoff(this.apiKey, this.debug);
+        while (!success) {
+            try {
+                const urlParams = new URLSearchParams();
+                if (queryParamOpts?.quoteCurrency !== undefined) {
+                    urlParams.append("quote-currency", queryParamOpts?.quoteCurrency.toString());
+                }
+                if (queryParamOpts?.noLogs !== undefined) {
+                    urlParams.append("no-logs", queryParamOpts?.noLogs.toString());
+                }
+                if (queryParamOpts?.blockSignedAtAsc !== undefined) {
+                    urlParams.append("block-signed-at-asc", queryParamOpts?.blockSignedAtAsc.toString());
+                }
+                if (queryParamOpts?.withSafe !== undefined) {
+                    urlParams.append("with-safe", queryParamOpts?.withSafe.toString());
+                }
+                let startTime;
+                if (this.debug) {
+                    startTime = typeof performance !== 'undefined' ? performance.now() : process.hrtime();
+                }
+                response = await this.LIMIT(() => fetch(`https://api.covalenthq.com/v1/${chainName}/address/${walletAddress}/transactions_v3/?${urlParams}`, {
+                    headers: {
+                        "Authorization": `Bearer ${this.apiKey}`,
+                        "X-Requested-With": userAgent
+                    }
+                }));
+                debugOutput(response.url, response.status, startTime);
+                if (response.status === 429) {
+                    try {
+                        data = await this.LIMIT(() => backoff.backOff(response.url));
+                    }
+                    catch (error) {
+                        success = true;
+                        return {
+                            data: null,
+                            error: true,
+                            error_code: response.status,
+                            error_message: error.message
+                        };
+                    }
+                }
+                else {
+                    data = await response.json();
+                }
+                const dataClass = new RecentTransactionsResponse(data.data, this.debug, this.apiKey, this.threadCount, urlParams);
+                checkAndModifyResponse(dataClass);
+                success = true;
+                return {
+                    data: dataClass,
+                    error: data.error,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+            catch (error) {
+                success = true;
+                return {
+                    data: null,
+                    error: true,
+                    error_code: data ? data.error_code : response.status,
+                    error_message: data ? data.error_message : response.status === 500 ? "Internal server error" : "401 Authorization Required"
+                };
+            }
+        }
+    }
     /**
      *
      * Commonly used to fetch all transactions including their decoded log events in a block and further flag interesting wallets or transactions.
@@ -4502,7 +4883,7 @@ class TransactionService {
                 else {
                     data = await response.json();
                 }
-                const dataClass = new TransactionsResponse(data.data);
+                const dataClass = new TransactionsResponse(data.data, this.debug, this.apiKey, this.threadCount, urlParams);
                 checkAndModifyResponse(dataClass);
                 success = true;
                 return {
@@ -5867,7 +6248,7 @@ class XykService {
     }
 }
 
-const userAgent = "com.covalenthq.sdk.typescript/0.6.1";
+const userAgent = "com.covalenthq.sdk.typescript/0.6.3";
 /**
  * CovalentClient Class
  */
@@ -5902,6 +6283,28 @@ class Client {
     }
 }
 
+const calculatePrettyBalance = (value, decimals = 18, roundOff = true, precision = 0) => {
+    const bigIntValue = BigInt(value);
+    const bigDecimalValue = new Big(bigIntValue.toString());
+    const _decimals = decimals || 18;
+    const _expoValue = BigInt(Math.pow(10, _decimals));
+    const bigDecimalExpo = new Big(_expoValue.toString());
+    const _calculated = bigDecimalValue.div(bigDecimalExpo);
+    // removes the decimal places, true by default so it adds decimals
+    if (!roundOff) {
+        return _calculated.toString();
+    }
+    let _decimalFixed = precision;
+    if (precision === 0) {
+        _decimalFixed = 2;
+        if (_calculated.lt(100)) {
+            _decimalFixed = 6;
+        }
+    }
+    return _calculated.toFixed(_decimalFixed);
+};
+
 exports.Client = Client;
 exports.CovalentClient = CovalentClient;
+exports.calculatePrettyBalance = calculatePrettyBalance;
 //# sourceMappingURL=index.js.map