@covalenthq/client-sdk 0.9.2 → 0.9.4

package/README.md

@@ -5,6 +5,9 @@
   <a href="https://www.npmjs.com/package/@covalenthq/client-sdk">
     <img src="https://img.shields.io/npm/dm/@covalenthq/client-sdk" alt="npm downloads">
   </a>
+  <a>
+   <img src="https://img.shields.io/badge/node-20.x-green">
+  <a>
 </p>
 
 
@@ -12,12 +15,11 @@
 
 The Covalent SDK is the fastest way to integrate the Covalent Unified API for working with blockchain data. The SDK works with all [supported chains](https://www.covalenthq.com/docs/networks/) including Mainnets and Testnets. 
 
-Note - use `Node v18` and above for best results.
+**Note - Require `Node v18` and above for best results.**
 
-
-> **Name Resolution**
+> **Sign up for an API Key**
 >
-> The Covalent SDK natively supports ENS domains (e.g. `demo.eth`), Lens Handles (e.g. `@demo.lens`) and Unstoppable Domains (e.g. `demo.x`) which automatically resolve to the underlying user address (e.g. `0xfC43f5F9dd45258b3AFf31Bdbe6561D97e8B71de`)
+> To get your own Covalent API key, **[sign up here](https://www.covalenthq.com/platform/auth/register/)** and create your key from the *API Keys* tab.
 
 ## Getting started
 
@@ -29,6 +31,10 @@ or
 yarn add @covalenthq/client-sdk
 ```
 
+## How to use the Covalent SDK
+
+**Video Tutorial**: https://www.youtube.com/watch?v=XSpPJP2w62E&ab_channel=Covalent
+
 After installing, you can import and use the SDK with:
 
 ```ts
@@ -37,47 +43,38 @@ import { CovalentClient, Chains } from "@covalenthq/client-sdk";
 const ApiServices = async () => {
     const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
 
-    // Example call with string literal type
-    const respWithStringLiteral = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
-    if (!respWithStringLiteral.error) {
-        console.log(respWithStringLiteral.data);
-    } else {
-        console.log(respWithStringLiteral.error_message);
-    }
-
-    // Example call with enum
-    const respWithEnum = await client.BalanceService.getTokenBalancesForWalletAddress(Chains.ETH_MAINNET, "WALLET_ADDRESS");
-    if (!respWithEnum.error) {
-        console.log(respWithEnum.data);
+    const balanceResp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
+    if (!balanceResp.error) {
+        console.log(balanceResp.data);
     } else {
-        console.log(respWithEnum.error_message);
+        console.log(balanceResp.error_message);
     }
 }
 ```
-
-> **Getting an API Key**
+> **Name Resolution**
 >
-> To get your own Covalent API key, **[sign up here](https://www.covalenthq.com/platform/auth/register/)** and create your key from the *API Keys* tab.
-
-Note about a **ℹ️ BREAKING CHANGE**:
+> The Covalent SDK natively supports ENS domains (e.g. `demo.eth`), Lens Handles (e.g. `@demo.lens`) and Unstoppable Domains (e.g. `demo.x`) which automatically resolve to the underlying user address (e.g. `0xfC43f5F9dd45258b3AFf31Bdbe6561D97e8B71de`)
 
-> If you have been using: 
->
-> `import { Client } from "@covalenthq/client-sdk";`
->
-> Please change to:
+**ℹ️ BREAKING CHANGE**
+> If you have been importing with `Client`: 
+```ts 
+import { Client } from "@covalenthq/client-sdk";
+```
 >
-> `import { CovalentClient } from "@covalenthq/client-sdk";`
+> Please change to `CovalentClient`:
+```ts
+import { CovalentClient } from "@covalenthq/client-sdk";
+```
 
-### Typed Objects
+### How to apply supported query parameters to endpoints
 Query parameters are handled using `typed objects`. To pass in query parameters, developers can define an object that follows the type listed in the provided `tsdocs` under `src/util/types/`. Additionally, developers can reference the `tsdocs` for autocomplete suggestions for the supported parameters. These supported parameters can be passed in any order. 
 
 For example, the following sets the `quoteCurrency` query parameter to `CAD` and the parameter `nft` to `true` for fetching all the token balances, including NFTs, for a wallet address:
 ```ts
 const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS", {quoteCurrency: "CAD", nft: true});
 ```
-
-You can import all the listed types. For example:
+### Assign Types
+You can import types for each endpoint, found here `src/util/types/`. Here is an example:
 ```ts
 import { CovalentClient, BalancesResponse,  BalanceItem } from "@covalenthq/client-sdk";
 const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS", {quoteCurrency: "CAD", nft: true});
@@ -85,7 +82,30 @@ const data: BalancesResponse = resp.data; // `resp.data` in this case is of type
 const items: BalanceItem[] = resp.data.items; // `resp.data.items` is of type `BalanceItem[]`
 ```
 
-## How to use the Covalent SDK
+### Different ways to input chains in chain fields
+We offer users three options for specifying a chain in the designated field:
+
+1. String literal - directly inputting the chain name, such as `eth-mainnet`, with auto-completion functionality as the user types.
+2. Chain Enum - utilizing the Chain enum `Chains.ETH_MAINNET`, which provides auto-suggestions as the user types in the chain field.
+3. Chain Id - entering the ChainId as a numerical value.
+
+Example with string literal
+```ts
+// Example call with string literal  ("eth-mainnet")
+const respWithStringLiteral = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
+```
+Example with Chain Enum
+```ts
+// Example call with enum  (Chains.ETH_MAINNET)
+const respWithEnum = await client.BalanceService.getTokenBalancesForWalletAddress(Chains.ETH_MAINNET, "WALLET_ADDRESS");
+```
+Example with Chain Id
+```ts
+// Example call with chain Id  (1)
+const respWithChainId = await client.BalanceService.getTokenBalancesForWalletAddress(1, "WALLET_ADDRESS");
+```
+
+## Supported Endpoints
 
 The Covalent SDK provides comprehensive support for all Class A, Class B, and Pricing endpoints that are grouped under the following *Service* namespaces:
 
@@ -117,26 +137,6 @@ 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);
-```
-
-The `prettifyCurrency` function refines the presentation of a monetary value, accepting a numerical amount and a fiat currency code as parameters (with USD as the default currency). It simplifies currency formatting for developers, ensuring visually polished representations of financial information in user interfaces for an enhanced user experience.
-
-```ts
-import { CovalentClient, prettifyCurrency } 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 prettyCurrency = prettifyCurrency(resp.data.items[0].quote_rate);
-```
-
 ### 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/):
@@ -231,7 +231,30 @@ The `XykService` refers to the [Xy=k API endpoints](https://www.covalenthq.com/d
 - `getEcosystemChartData()`: Get a 7d and 30d time-series chart of DEX activity. Includes volume and swap count.
 - `getHealthData()`: Ping the health of xy=k endpoints to get the synced block height per chain.
 
-## How pagination works
+## Additional Helper Functions
+### calculatePrettyBalance
+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);
+```
+### prettifyCurrency
+The `prettifyCurrency` function refines the presentation of a monetary value, accepting a numerical amount and a fiat currency code as parameters (with USD as the default currency). It simplifies currency formatting for developers, ensuring visually polished representations of financial information in user interfaces for an enhanced user experience.
+
+```ts
+import { CovalentClient, prettifyCurrency } 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 prettyCurrency = prettifyCurrency(resp.data.items[0].quote_rate);
+```
+
+## Built-in SDK Features
+### Explaining Pagination Mechanism Within the SDK
 
 The following endpoints support pagination: