@covalenthq/client-sdk 0.2.9 → 0.5.0

package/README.md

@@ -1,12 +1,13 @@
-# covalent-api-sdk-ts
+# Covalent SDK for TypeScript
 
-The Covalent API SDK supported for TypeScript.
+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.
 
-The Covalent SDK supports all chains across Mainnets and Testnets. List of supported Networks can be found on our [Supported Networks page](https://www.covalenthq.com/docs/networks/)
 
 > **Name Resolution**
 >
-> The Covalent SDK supports address resolution natively allowing an ENS, RNS, Lens Handle or Unstoppable Domains address to be passed in directly for all our endpoints.
+> 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`)
 
 ## Getting started
 
@@ -18,14 +19,14 @@ or
 yarn add @covalenthq/client-sdk
 ```
 
-After installing the app, you can then import and use the SDK:
+After installing, you can import and use the SDK with:
 
 ```ts
-import { Client } from "@covalenthq/client-sdk";
+import { CovalentClient } from "@covalenthq/client-sdk";
 
 const ApiServices = async () => {
-    const client = new Client("YOUR_API_KEY"); // Replace with your Covalent API key.
-    const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS"); // Example call, refer to API Docs for required paramaters or click into the method `getTokenBalancesForWalletAddress` to see the accepted parameter arguments
+    const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
+    const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS"); // Example call
     if (!resp.error) {
         console.log(resp.data);
     } else {
@@ -33,55 +34,71 @@ const ApiServices = async () => {
     }
 }
 ```
-Query Parameters for any API endpoint is handled using `typed objects`. To pass in query parameters, developers can define an object that follows the type listed in the `tsdocs` and follow the `tsdocs` for autocomplete suggestions for the supported parameters. Supported parameters can be passed in as any order. For example: a developer wants to set the `quoteCurrency` parameter to `CAD` and `nft` to `true`.
+
+> **Getting an API Key**
+>
+> 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**:
+
+> If you have been using: 
+>
+> `import { Client } from "@covalenthq/client-sdk";`
+>
+> Please change to:
+>
+> `import { CovalentClient } from "@covalenthq/client-sdk";`
+
+### Typed Objects
+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});
 ```
 
-All of our types are also available for import! For example:
+You can import all the listed types. For example:
 ```ts
-import { Client, BalancesResponse,  BalanceItem } from "@covalenthq/client-sdk";
+import { CovalentClient, BalancesResponse,  BalanceItem } from "@covalenthq/client-sdk";
 const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS", {quoteCurrency: "CAD", nft: true});
 const data: BalancesResponse = resp.data; // `resp.data` in this case is of type `BalancesResponse`
 const items: BalanceItem[] = resp.data.items; // `resp.data.items` is of type `BalanceItem[]`
 ```
 
-> **Creating a unique Covalent API Key**
->
-> To create your own API key, **[sign up for an Covalent account here](https://www.covalenthq.com/platform/auth/register/)** and use the key created under the [API Keys](https://www.covalenthq.com/platform/apikey/) tab.
-
-
 ## How to use the Covalent SDK
 
-The Covalent SDK provides comprehensive support for all Class A, Class B, and Pricing endpoints grouped under various Services, offering a wide range of functionalities and capabilities:
+The Covalent SDK provides comprehensive support for all Class A, Class B, and Pricing endpoints that are grouped under the following *Service* namespaces:
 
-- `SecurityService`: Access to the Covalent's getApprovals endpoint
-- `BalanceService`: Access to the Covalent's balances endpoints
-- `BaseServices`: Access to the Covalent's log events, chain, and block endpoints
-- `NftService`: Access to the Covalent's NFT endpoints
-- `PricingService`: Access to the Covalent's get historical token prices endpoint
-- `TransactionService`: Access to the Covalent's transactions endpoints
-- `XykService`: Access to the Covalent's Xy=k endpoints
+- [`SecurityService`](#securityservice): Access to the token approvals endpoints
+- [`BalanceService`](#balanceservice): Access to the balances endpoints
+- [`BaseService`](#baseservice): Access to the address activity, log events, chain status, and block retrieval endpoints
+- [`NftService`](#nftservice): Access to the  NFT endpoints
+- [`PricingService`](#pricingservice): Access to the historical token prices endpoint
+- [`TransactionService`](#transactionservice): Access to the transactions endpoints
+- [`XykService`](#xykservice): Access to the XY=K suite of endpoints
 
 ### SecurityService
 
-The `SecurityService` class contains the getApprovals() endpoint, refer to the [getApprovals endpoint on our API docs](https://www.covalenthq.com/docs/api/security/get-token-approvals-for-address/).
+The `SecurityService` class refers to the [token approvals API endpoints](https://www.covalenthq.com/docs/api/security/get-token-approvals-for-address/):
 
-- `getApprovals()`: Get a list of approvals across all token contracts categorized by spenders for a wallet’s assets.
+- `getApprovals()`: Get a list of approvals across all ERC20 token contracts categorized by spenders for a wallet’s assets.
+- `getNftApprovals()`: Get a list of approvals across all NFT contracts categorized by spenders for a wallet’s assets.
 
 ### BalanceService
 
-The `BalanceService` class contains the balances endpoints. Listed below are the supported endpoints, also refer to our api docs under the Balances section in our class A endpoints.
+The `BalanceService` class refers to the [balances API endpoints](https://www.covalenthq.com/docs/api/balances/get-token-balances-for-address/):
 
 - `getTokenBalancesForWalletAddress()`: Fetch the native, fungible (ERC20), and non-fungible (ERC721 & ERC1155) tokens held by an address. Response includes spot prices and other metadata.
 - `getHistoricalTokenBalancesForWalletAddress()`: Fetch the historical native, fungible (ERC20), and non-fungible (ERC721 & ERC1155) tokens held by an address at a given block height or date. Response includes daily prices and other metadata.
 - `getHistoricalPortfolioForWalletAddress()`: Render a daily portfolio balance for an address broken down by the token. The timeframe is user-configurable, defaults to 30 days.
-- `getErc20TransfersForWalletAddress()`: Render the transfer-in and transfer-out of a token along with historical prices from an address.
+- `getErc20TransfersForWalletAddress()`: Render the transfer-in and transfer-out of a token along with historical prices from an address. (Paginated)
+- `getErc20TransfersForWalletAddressByPage()`: Render the transfer-in and transfer-out of a token along with historical prices from an address. (By page)
 - `getTokenHoldersV2ForTokenAddress()`: 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.
+- `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.
 
-### BaseServices
+### BaseService
 
-The `BaseServices` class contains the log events, chain, and block endpoints. Listed below are the supported endpoints, also refer to our api docs under the Base section in our class A endpoints.
+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/):
 
 - `getBlock()`: Fetch and render a single block for a block explorer.
 - `getLogs()`: Get all the event logs of the latest block, or for a range of blocks. Includes sender contract metadata as well as decoded logs.
@@ -95,7 +112,7 @@ The `BaseServices` class contains the log events, chain, and block endpoints. Li
 
 ### NftService
 
-The `NftService` class contains the NFT endpoints. Listed below are the supported endpoints, also refer to our api docs under the NFT section in our class A endpoints.
+The `NftService` class refers to the [NFT API endpoints](https://www.covalenthq.com/docs/api/nft/get-nfts-for-address/):
 
 - `getChainCollections()`: Used to fetch the list of NFT collections with downloaded and cached off chain data like token metadata and asset files.
 - `getNftsForAddress()`: Used to render the NFTs (including ERC721 and ERC1155) held by an address.
@@ -107,17 +124,19 @@ The `NftService` class contains the NFT endpoints. Listed below are the supporte
 - `getCollectionTraitsSummary()`: Used to calculate rarity scores for a collection based on its traits.
 - `checkOwnershipInNft()`: Used to verify ownership of NFTs (including ERC-721 and ERC-1155) within a collection.
 - `checkOwnershipInNftForSpecificTokenId()`: Used to verify ownership of a specific token (ERC-721 or ERC-1155) within a collection.
-- `getNftExternalMetadataForContract()`: Get a single NFT with metadata by token ID from a collection. Useful for building NFT card displays.
+- `getNftMarketSaleCount()`: Used to build a time-series chart of the sales count of an NFT collection.
+- `getNftMarketVolume()`: Used to build a time-series chart of the transaction volume of an NFT collection.
+- `getNftMarketFloorPrice()`: Used to render a price floor chart for an NFT collection.
 
 ### PricingService
 
-The `PricingService` class contains the getTokenPrices() endpoint. Refer to the [getTokenPrices endpoint on our API docs](https://www.covalenthq.com/docs/api/pricing/get-historical-token-prices/).
+The `PricingService` class refers to the [historical token prices API endpoint](https://www.covalenthq.com/docs/api/pricing/get-historical-token-prices/):
 
 - `getTokenPrices()`: Get historic prices of a token between date ranges. Supports native tokens.
 
 ### TransactionService
 
-The `TransactionService` class contains the transactions endpoint. Listed below are the supported endpoints, also refer to our api docs under the Transactions section in our class A endpoints.
+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.
 - `getTransaction()`: Fetch and render a single transaction including its decoded log events. Additionally return semantically decoded information for DEX trades, lending and NFT sales.
@@ -126,13 +145,14 @@ The `TransactionService` class contains the transactions endpoint. Listed below
 
 ### XykService
 
-The `XykService` class contains the Xy=k endpoints. Listed below are the supported endpoints, also refer to our api docs under the XY=K section in our class B endpoints.
+The `XykService` refers to the [Xy=k API endpoints](https://www.covalenthq.com/docs/api/xyk/get-xyk-pools/):
 
 - `getPools()`: Get all the pools of a particular DEX. Supports most common DEXs (Uniswap, SushiSwap, etc), and returns detailed trading data (volume, liquidity, swap counts, fees, LP token prices).
 - `getPoolByAddress()`: Get the 7 day and 30 day time-series data (volume, liquidity, price) of a particular liquidity pool in a DEX. Useful for building time-series charts on DEX trading activity.
 - `getPoolsForTokenAddress()`: Get all pools and the supported DEX for a token. Useful for building a table of top pairs across all supported DEXes that the token is trading on.
+- `getPoolsForWalletAddress()`: Get all pools and supported DEX for a wallet. Useful for building a personal DEX UI showcasing pairs and supported DEXes associated to the wallet.
 - `getAddressExchangeBalances()`: Return balance of a wallet/contract address on a specific DEX.
-- `getNetworkExchangeTokens()`: Get the balance of a wallet address in a DEX. Useful for finding out user balances locked up in DEX pools.
+- `getNetworkExchangeTokens()`: Retrieve all network exchange tokens for a specific DEX. Useful for building a top tokens table by total liquidity within a particular DEX.
 - `getSupportedDEXes()`: Get all the supported DEXs available for the xy=k endpoints, along with the swap fees and factory addresses.
 - `getDexForPoolAddress()`: Get the supported DEX given a pool address, along with the swap fees, DEX's logo url, and factory addresses. Useful to identifying the specific DEX to which a pair address is associated.
 - `getSingleNetworkExchangeToken()`: Get historical daily swap count for a single network exchange token.
@@ -142,9 +162,9 @@ The `XykService` class contains the Xy=k endpoints. Listed below are the support
 - `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
+## How pagination works
 
-#### Endpoints supporting pagination
+The following endpoints support pagination:
 
 - `getErc20TransfersForWalletAddress()`
 - `getTokenHoldersV2ForTokenAddress()`
@@ -155,25 +175,76 @@ The `XykService` class contains the Xy=k endpoints. Listed below are the support
 - `getTokenIdsForContractWithMetadata()`
 - `getAllTransactionsForAddress()`
 
-The listed endpoints above are currently the only endpoints that support pagination which return 100 results per page. To get the next page, it uses a `link url` or the `page-number` provided in the endpoint response. Here's an example of how to paginate through all recent transactions on the ethereum blockchain for the demo's ENS address:
+Using the Covalent API, paginated supported endpoints return only 100 items, such as transactions or log events, per page. However, the Covalent SDK leverages generators to *seamlessly fetch all items without the user having to deal with pagination*. 
+
+For example, the following fetches ALL transactions for `demo.eth` on Ethereum:
 ```ts
-import { Client } from "@covalenthq/client-sdk";
+import { CovalentClient } from "@covalenthq/client-sdk";
 
 const ApiServices = async () => {
-    const client = new Client("YOUR_API_KEY"); // Replace with your Covalent API key.
-    for await (const tx of client.TransactionService.getAllTransactionsForAddress("eth-mainnet", "demo.eth")) {
-        console.log("tx", tx);
+    const client = new CovalentClient("YOUR_API_KEY"); // Replace with your Covalent API key.
+    try {
+        for await (const tx of client.TransactionService.getAllTransactionsForAddress("eth-mainnet", "demo.eth")) {
+            console.log("tx", tx);
+        }
+    } catch (error) {
+        console.log(error.message);
     }
 }
 ```
-The paginated endpoints exclusively returns their response items without the response wrapper, enabling developers to access the list seamlessly, ensuring efficient and straightforward item retrieval.
+
+### Concurrency Mechanism
+
+Developers have the flexibility to specify the desired number of concurrent API calls they wish to execute using the `threadCount` settings parameter, with a default value of `3`. For example:
+
+```ts
+import { CovalentClient, CovalentClientSettings } from "@covalenthq/client-sdk";
+
+const settings: CovalentClientSettings = {
+    threadCount: 5
+}
+
+const ApiServices = async () => {
+    const client = new CovalentClient("YOUR_API_KEY", settings); // Replace with your Covalent API key and add set debugger
+    const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
+    if (!resp.error) {
+        console.log(resp.data);
+    } else {
+        console.log(resp.error_message);
+    }
+}
+```
+
+### Debugger Mode
+
+Developers have the option to enable a debugger mode that provides response times, the URLs of called endpoints, and the HTTP statuses of those endpoints. This feature helps users identify which endpoints may have encountered failures. The default is `debug = false` if no input is provided.
+
+```ts
+import { CovalentClient, CovalentClientSettings } from "@covalenthq/client-sdk";
+
+const settings: CovalentClientSettings = {
+    debug: true
+}
+
+const ApiServices = async () => {
+    const client = new CovalentClient("YOUR_API_KEY", settings); // Replace with your Covalent API key and add set debugger
+    const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS");
+    if (!resp.error) {
+        console.log(resp.data);
+    } else {
+        console.log(resp.error_message);
+    }
+}
+```
+
+![example result image](https://www.datocms-assets.com/86369/1697154621-sdk-debugger-output.png)
 
 ### Retry Mechanism
 
-Each endpoint is equipped with an exponential backoff algorithm that exponentially extends the wait time between retries, making up to a `maximum of 5` retry attempts only.
+Each endpoint is equipped with an exponential backoff algorithm that exponentially extends the wait time between retries, up to a `maximum of 5` retry attempts.
 
 ### Error Handling
-The paginated endpoints will throw an error message in this format: `An error occurred {error_code}: {error_message}`, when an error occurs. The developer would need to make sure to catch those errors if any. This endpoint does not follow our default response format unlike our other endpoints, shown below.
+The paginated endpoints throw an error message in this format: `An error occurred {error_code}: {error_message}`. The developer will need to `catch` these errors. Note - these endpoints do not follow the default response format which is:
 ```ts
 ❴ 
     "data": ...,

package/dist/cjs/index.d.ts

@@ -0,0 +1,9 @@
+export { CovalentClient, Client, Chain, Quote, Chains, Quotes, CovalentClientSettings } from "./services/CovalentClient";
+export * from "./util/types/BalanceServiceTypes";
+export * from "./util/types/BaseServiceTypes";
+export * from "./util/types/NftServiceTypes";
+export * from "./util/types/PricingServiceTypes";
+export * from "./util/types/SecurityServiceTypes";
+export * from "./util/types/XykServiceTypes";
+export * from "./util/types/GenericTypes";
+export * from "./util/types/TransactionServiceTypes";