@covalenthq/client-sdk 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,6 @@
 # covalent-api-sdk-ts
 
-The Covalent API SDK supported for Typescript.
+The Covalent API SDK supported for TypeScript.
 
 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/)
 
@@ -33,6 +33,10 @@ 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`.
+```ts
+const resp = await client.BalanceService.getTokenBalancesForWalletAddress("eth-mainnet", "WALLET_ADDRESS", {quoteCurrency: "CAD", nft: true});
+```
 
 > **Creating a unique Covalent API Key**
 >
@@ -48,7 +52,7 @@ The Covalent SDK provides comprehensive support for all Class A, Class B, and Pr
 - `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 (with pagination)
+- `TransactionService`: Access to the Covalent's transactions endpoints
 - `XykService`: Access to the Covalent's Xy=k endpoints
 
 ### SecurityService
@@ -129,7 +133,18 @@ The `XykService` class contains the Xy=k endpoints. Listed below are the support
 
 ### How pagination works
 
-The Covalent `getAllTransactionsForAddress()` endpoint is currently the only endpoint that supports pagination which return 100 results per page. To get the next page, it uses a link url that is grabbed from the previous call. Here's an example of how to paginate through all recent transactions on the ethereum blockchain for the demo's ENS address:
+#### Endpoints supporting pagination
+
+- `getErc20TransfersForWalletAddress()`
+- `getTokenHoldersV2ForTokenAddress()`
+- `getBlockHeights()`
+- `getLogEventsByAddress()`
+- `getLogEventsByTopicHash()`
+- `getChainCollections()`
+- `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:
 ```ts
 import { Client } from "@covalenthq/client-sdk";
 
@@ -140,14 +155,14 @@ const ApiServices = async () => {
     }
 }
 ```
-This endpoint exclusively returns transaction items without the response wrapper, enabling developers to access the list seamlessly, ensuring efficient and straightforward transaction item retrieval.
+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.
 
 ### 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.
 
 ### Error Handling
-The `getAllTransactionsForAddress()` endpoint 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 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.
 ```ts
 ❴ 
     "data": ...,

package/dist/services/BalanceService.d.ts

@@ -1,4 +1,4 @@
-import { Chains, Quotes } from "./Client";
+import { Chains, Quotes, Response } from "./Client";
 declare class BalancesResponse {
     /** * The requested address. */
     address: string;
@@ -128,23 +128,6 @@ declare class OhlcItem {
     pretty_quote: string;
     constructor(data: OhlcItem);
 }
-declare class Erc20TransfersResponse {
-    /** * The requested address. */
-    address: string;
-    /** * The timestamp when the response was generated. Useful to show data staleness to users. */
-    updated_at: Date;
-    /** * The requested quote currency eg: `USD`. */
-    quote_currency: string;
-    /** * The requested chain ID eg: `1`. */
-    chain_id: number;
-    /** * The requested chain name eg: `eth-mainnet`. */
-    chain_name: string;
-    /** * List of response items. */
-    items: BlockTransactionWithContractTransfers[];
-    /** * Pagination metadata. */
-    pagination: Pagination;
-    constructor(data: Erc20TransfersResponse);
-}
 declare class BlockTransactionWithContractTransfers {
     /** * The block signed timestamp in UTC. */
     block_signed_at: Date;
@@ -179,17 +162,6 @@ declare class BlockTransactionWithContractTransfers {
     transfers: TokenTransferItem[];
     constructor(data: BlockTransactionWithContractTransfers);
 }
-declare class Pagination {
-    /** * True is there is another page. */
-    has_more: boolean;
-    /** * The requested page number. */
-    page_number: number;
-    /** * The requested number of items on the current page. */
-    page_size: number;
-    /** * The total number of items across all pages for this request. */
-    total_count: number;
-    constructor(data: Pagination);
-}
 declare class TokenTransferItem {
     /** * The block signed timestamp in UTC. */
     block_signed_at: Date;
@@ -228,19 +200,6 @@ declare class MethodCallsForTransfers {
     method: string;
     constructor(data: MethodCallsForTransfers);
 }
-declare class TokenHoldersResponse {
-    /** * The timestamp when the response was generated. Useful to show data staleness to users. */
-    updated_at: Date;
-    /** * The requested chain ID eg: `1`. */
-    chain_id: number;
-    /** * The requested chain name eg: `eth-mainnet`. */
-    chain_name: string;
-    /** * List of response items. */
-    items: TokenHolder[];
-    /** * Pagination metadata. */
-    pagination: Pagination;
-    constructor(data: TokenHoldersResponse);
-}
 declare class TokenHolder {
     /** * Use contract decimals to format the token balance for display purposes - divide the balance by `10^{contract_decimals}`. */
     contract_decimals: number;
@@ -316,16 +275,66 @@ declare class HistoricalBalanceItem {
     nft_data: NftData[];
     constructor(data: HistoricalBalanceItem);
 }
+export interface GetTokenBalancesForWalletAddressQueryParamOpts {
+    /** * The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. */
+    quoteCurrency?: Quotes;
+    /** * If `true`, NFTs will be included in the response. */
+    nft?: boolean;
+    /** * If `true`, only NFTs that have been cached will be included in the response. Helpful for faster response times. */
+    noNftFetch?: boolean;
+    /** * If `true`, the suspected spam tokens are removed. Supports `eth-mainnet` and `matic-mainnet`. */
+    noSpam?: boolean;
+    /** * If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs. */
+    noNftAssetMetadata?: boolean;
+}
+export interface GetHistoricalPortfolioForWalletAddressQueryParamOpts {
+    /** * The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. */
+    quoteCurrency?: Quotes;
+    /** * The number of days to return data for. Defaults to 30 days. */
+    days?: number;
+}
+export interface GetErc20TransfersForWalletAddressQueryParamOpts {
+    /** * The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. */
+    quoteCurrency?: Quotes;
+    /** * The requested contract address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically. */
+    contractAddress?: string;
+    /** * The block height to start from, defaults to `0`. */
+    startingBlock?: number;
+    /** * The block height to end at, defaults to current block height. */
+    endingBlock?: number;
+    /** * Number of items per page. Omitting this parameter defaults to 100. */
+    pageSize?: number;
+    /** * 0-indexed page number to begin pagination. */
+    pageNumber?: number;
+}
+export interface GetTokenHoldersV2ForTokenAddressQueryParamOpts {
+    /** * Ending block to define a block range. Omitting this parameter defaults to the latest block height. */
+    blockHeight?: number;
+    /** * Number of items per page. Note: Currently, only values of `100` and `1000` are supported. Omitting this parameter defaults to 100. */
+    pageSize?: number;
+    /** * 0-indexed page number to begin pagination. */
+    pageNumber?: number;
+}
+export interface GetHistoricalTokenBalancesForWalletAddressQueryParamOpts {
+    /** * The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`. */
+    quoteCurrency?: Quotes;
+    /** * If `true`, NFTs will be included in the response. */
+    nft?: boolean;
+    /** * If `true`, only NFTs that have been cached will be included in the response. Helpful for faster response times. */
+    noNftFetch?: boolean;
+    /** * If `true`, the suspected spam tokens are removed. Supports `eth-mainnet` and `matic-mainnet`. */
+    noSpam?: boolean;
+    /** * If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs. */
+    noNftAssetMetadata?: boolean;
+    /** * Ending block to define a block range. Omitting this parameter defaults to the latest block height. */
+    blockHeight?: number;
+    /** * Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date. */
+    date?: number;
+}
 /**
  * Balances APIs
  *
  */
-export declare class Response<T> {
-    data: T;
-    error: boolean;
-    error_code: number;
-    error_message: string;
-}
 export declare class BalanceService {
     private apiKey;
     constructor(apiKey: string);
@@ -333,57 +342,64 @@ export declare class BalanceService {
      *
      * @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 {string} quoteCurrency - The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
-     * @param {boolean} nft - If `true`, NFTs will be included in the response.
-     * @param {boolean} noNftFetch - If `true`, only NFTs that have been cached will be included in the response. Helpful for faster response times.
-     * @param {boolean} noSpam - If `true`, the suspected spam tokens are removed. Supports `eth-mainnet` and `matic-mainnet`.
-     * @param {boolean} noNftAssetMetadata - If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs.
+     * @param {GetTokenBalancesForWalletAddressQueryParamOpts} queryParamOpts
+     *   - `quoteCurrency`: The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
+     *   - `nft`: If `true`, NFTs will be included in the response.
+     *   - `noNftFetch`: If `true`, only NFTs that have been cached will be included in the response. Helpful for faster response times.
+     *   - `noSpam`: If `true`, the suspected spam tokens are removed. Supports `eth-mainnet` and `matic-mainnet`.
+     *   - `noNftAssetMetadata`: If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs.
      *
      */
-    getTokenBalancesForWalletAddress(chainName: Chains, walletAddress: string, quoteCurrency?: Quotes, nft?: boolean, noNftFetch?: boolean, noSpam?: boolean, noNftAssetMetadata?: boolean): Promise<Response<BalancesResponse>>;
+    getTokenBalancesForWalletAddress(chainName: Chains, walletAddress: string, queryParamOpts?: GetTokenBalancesForWalletAddressQueryParamOpts): Promise<Response<BalancesResponse>>;
     /**
      *
      * @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 {string} quoteCurrency - The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
-     * @param {number} days - The number of days to return data for. Defaults to 30 days.
+     * @param {GetHistoricalPortfolioForWalletAddressQueryParamOpts} queryParamOpts
+     *   - `quoteCurrency`: The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
+     *   - `days`: The number of days to return data for. Defaults to 30 days.
      *
      */
-    getHistoricalPortfolioForWalletAddress(chainName: Chains, walletAddress: string, quoteCurrency?: Quotes, days?: number): Promise<Response<PortfolioResponse>>;
+    getHistoricalPortfolioForWalletAddress(chainName: Chains, walletAddress: string, queryParamOpts?: GetHistoricalPortfolioForWalletAddressQueryParamOpts): Promise<Response<PortfolioResponse>>;
     /**
      *
      * @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 {string} quoteCurrency - The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
-     * @param {string} contractAddress - The requested contract address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically.
-     * @param {number} startingBlock - The block height to start from, defaults to `0`.
-     * @param {number} endingBlock - The block height to end at, defaults to current block height.
+     * @param {GetErc20TransfersForWalletAddressQueryParamOpts} queryParamOpts
+     *   - `quoteCurrency`: The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
+     *   - `contractAddress`: The requested contract address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically.
+     *   - `startingBlock`: The block height to start from, defaults to `0`.
+     *   - `endingBlock`: The block height to end at, defaults to current block height.
+     *   - `pageSize`: Number of items per page. Omitting this parameter defaults to 100.
+     *   - `pageNumber`: 0-indexed page number to begin pagination.
      *
      */
-    getErc20TransfersForWalletAddress(chainName: Chains, walletAddress: string, quoteCurrency?: Quotes, contractAddress?: string, startingBlock?: number, endingBlock?: number): Promise<Response<Erc20TransfersResponse>>;
+    getErc20TransfersForWalletAddress(chainName: Chains, walletAddress: string, queryParamOpts?: GetErc20TransfersForWalletAddressQueryParamOpts): AsyncIterable<BlockTransactionWithContractTransfers>;
     /**
      *
      * @param {string} chainName - The chain name eg: `eth-mainnet`.
      * @param {string} tokenAddress - The requested address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically.
-     * @param {number} blockHeight - Ending block to define a block range. Omitting this parameter defaults to the latest block height.
-     * @param {number} pageSize - Number of items per page. Note: Currently, only values of `100` and `1000` are supported. Omitting this parameter defaults to 100.
-     * @param {number} pageNumber - 0-indexed page number to begin pagination.
+     * @param {GetTokenHoldersV2ForTokenAddressQueryParamOpts} queryParamOpts
+     *   - `blockHeight`: Ending block to define a block range. Omitting this parameter defaults to the latest block height.
+     *   - `pageSize`: Number of items per page. Note: Currently, only values of `100` and `1000` are supported. Omitting this parameter defaults to 100.
+     *   - `pageNumber`: 0-indexed page number to begin pagination.
      *
      */
-    getTokenHoldersV2ForTokenAddress(chainName: Chains, tokenAddress: string, blockHeight?: number, pageSize?: number, pageNumber?: number): Promise<Response<TokenHoldersResponse>>;
+    getTokenHoldersV2ForTokenAddress(chainName: Chains, tokenAddress: string, queryParamOpts?: GetTokenHoldersV2ForTokenAddressQueryParamOpts): AsyncIterable<TokenHolder>;
     /**
      *
      * @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 {string} quoteCurrency - The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
-     * @param {boolean} nft - If `true`, NFTs will be included in the response.
-     * @param {boolean} noNftFetch - If `true`, only NFTs that have been cached will be included in the response. Helpful for faster response times.
-     * @param {boolean} noSpam - If `true`, the suspected spam tokens are removed. Supports `eth-mainnet` and `matic-mainnet`.
-     * @param {boolean} noNftAssetMetadata - If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs.
-     * @param {number} blockHeight - Ending block to define a block range. Omitting this parameter defaults to the latest block height.
-     * @param {number} date - Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date.
+     * @param {GetHistoricalTokenBalancesForWalletAddressQueryParamOpts} queryParamOpts
+     *   - `quoteCurrency`: The currency to convert. Supports `USD`, `CAD`, `EUR`, `SGD`, `INR`, `JPY`, `VND`, `CNY`, `KRW`, `RUB`, `TRY`, `NGN`, `ARS`, `AUD`, `CHF`, and `GBP`.
+     *   - `nft`: If `true`, NFTs will be included in the response.
+     *   - `noNftFetch`: If `true`, only NFTs that have been cached will be included in the response. Helpful for faster response times.
+     *   - `noSpam`: If `true`, the suspected spam tokens are removed. Supports `eth-mainnet` and `matic-mainnet`.
+     *   - `noNftAssetMetadata`: If `true`, the response shape is limited to a list of collections and token ids, omitting metadata and asset information. Helpful for faster response times and wallets holding a large number of NFTs.
+     *   - `blockHeight`: Ending block to define a block range. Omitting this parameter defaults to the latest block height.
+     *   - `date`: Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date.
      *
      */
-    getHistoricalTokenBalancesForWalletAddress(chainName: Chains, walletAddress: string, quoteCurrency?: Quotes, nft?: boolean, noNftFetch?: boolean, noSpam?: boolean, noNftAssetMetadata?: boolean, blockHeight?: number, date?: number): Promise<Response<HistoricalBalancesResponse>>;
+    getHistoricalTokenBalancesForWalletAddress(chainName: Chains, walletAddress: string, queryParamOpts?: GetHistoricalTokenBalancesForWalletAddressQueryParamOpts): Promise<Response<HistoricalBalancesResponse>>;
 }
 export {};