@aptos-labs/ts-sdk 1.29.0 → 1.30.0

package/src/api/staking.ts

@@ -16,17 +16,54 @@ import { waitForIndexerOnVersion } from "./utils";
  * A class to query all `Staking` related queries on Aptos.
  */
 export class Staking {
+  /**
+   * Creates an instance of the Aptos client with the specified configuration.
+   * This allows you to interact with the Aptos blockchain using the provided settings.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   * @param config.network - The network to connect to (e.g., TESTNET, MAINNET).
+   * @param config.nodeUrl - The URL of the Aptos node to connect to.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a configuration for the Aptos client
+   *     const config = new AptosConfig({ network: Network.TESTNET }); // Specify your network
+   *
+   *     // Initialize the Aptos client with the configuration
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(readonly config: AptosConfig) {}
 
   /**
-   * Queries current number of delegators in a pool.  Throws an error if the pool is not found.
+   * Queries the current number of delegators in a specified pool. Throws an error if the pool is not found.
+   *
+   * @param args - The parameters for the query.
+   * @param args.poolAddress - The address of the pool to query.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   * @returns The number of delegators for the given pool.
    *
    * @example
-   * const delegators = await aptos.getNumberOfDelegators({poolAddress:"0x123"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @param args.poolAddress Pool address
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @returns The number of delegators for the given pool
+   * async function runExample() {
+   *   // Get the number of delegators for a specific pool
+   *   const delegators = await aptos.getNumberOfDelegators({ poolAddress: "0x1" }); // replace with a real pool address
+   *   console.log(`Number of delegators: ${delegators}`);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getNumberOfDelegators(args: {
     poolAddress: AccountAddressInput;
@@ -41,13 +78,27 @@ export class Staking {
   }
 
   /**
-   * Queries current number of delegators in a pool.  Throws an error if the pool is not found.
+   * Retrieves the current number of delegators across all pools.
+   *
+   * @param args Optional parameters for the query.
+   * @param args.minimumLedgerVersion Optional ledger version to sync up to before querying.
+   * @param args.options Optional ordering options for the response.
+   * @returns GetNumberOfDelegatorsForAllPoolsResponse response type containing the number of delegators per pool.
    *
    * @example
-   * const delegators = await aptos.getNumberOfDelegatorsForAllPools()
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
    *
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @returns GetNumberOfDelegatorsForAllPoolsResponse response type
+   * async function runExample() {
+   *   // Retrieve the number of delegators for all pools
+   *   const delegators = await aptos.getNumberOfDelegatorsForAllPools();
+   *   console.log(delegators);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getNumberOfDelegatorsForAllPools(args?: {
     minimumLedgerVersion?: AnyNumber;
@@ -62,15 +113,33 @@ export class Staking {
   }
 
   /**
-   * Queries delegated staking activities
+   * Queries delegated staking activities for a specific delegator and pool.
+   *
+   * @param args - The arguments for querying delegated staking activities.
+   * @param args.delegatorAddress - The address of the delegator.
+   * @param args.poolAddress - The address of the staking pool.
+   * @param args.minimumLedgerVersion - Optional ledger version to sync up to before querying.
+   * @returns The response containing delegated staking activities.
    *
    * @example
-   * const delegators = await aptos.getDelegatedStakingActivities({delegatorAddress:"0x123",poolAddress:"0x456"})
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Get delegated staking activities for a specific delegator and pool
+   *   const activities = await aptos.getDelegatedStakingActivities({
+   *     delegatorAddress: "0x1", // replace with a real delegator address
+   *     poolAddress: "0x2", // replace with a real pool address
+   *     minimumLedgerVersion: 1, // specify your own if needed
+   *   });
    *
-   * @param args.delegatorAddress Delegator address
-   * @param args.poolAddress Pool address
-   * @param args.minimumLedgerVersion Optional ledger version to sync up to, before querying
-   * @returns GetDelegatedStakingActivitiesResponse response type
+   *   console.log(activities);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getDelegatedStakingActivities(args: {
     delegatorAddress: AccountAddressInput;

package/src/api/table.ts

@@ -15,56 +15,113 @@ import { AptosConfig } from "./aptosConfig";
 import { waitForIndexerOnVersion } from "./utils";
 
 /**
- * A class to query all `Table` Aptos related queries
+ * A class to query all `Table` Aptos related queries.
  */
 export class Table {
   readonly config: AptosConfig;
 
+  /**
+   * Initializes a new instance of the Aptos client with the specified configuration.
+   * This allows you to interact with the Aptos blockchain using the provided settings.
+   *
+   * @param config - The configuration settings for the Aptos client.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * async function runExample() {
+   *     // Create a new Aptos client with testnet configuration
+   *     const config = new AptosConfig({ network: Network.TESTNET });
+   *     const aptos = new Aptos(config);
+   *
+   *     console.log("Aptos client initialized:", aptos);
+   * }
+   * runExample().catch(console.error);
+   * ```
+   */
   constructor(config: AptosConfig) {
     this.config = config;
   }
 
   /**
-   * Queries for a table item for a table identified by the handle and the key for the item.
-   * Key and value types need to be passed in to help with key serialization and value deserialization.
-   *
-   * Note, this query calls the fullnode server
-   *
-   * @example https://api.devnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::coin::CoinInfo%3C0x1::aptos_coin::AptosCoin%3E
-   * const tableItem = await aptos.getTableItem({
-   *  handle: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca",
-   *  data: {
-   *   key_type: "address", // Move type of table key
-   *   value_type: "u128", // Move type of table value
-   *   key: "0x619dc29a0aac8fa146714058e8dd6d2d0f3bdf5f6331907bf91f3acd81e6935" // Value of table key
-   *  },
-   * })
-   *
-   * @param args.handle A pointer to where that table is stored
-   * @param args.data Object that describes table item
-   * @param args.options.ledgerVersion The ledger version to query, if not provided it will get the latest version
-   *
-   * @returns Table item value rendered in JSON
+   * Queries for a specific item in a table identified by the handle and the key for the item.
+   * This function allows you to retrieve structured data from a table in the Aptos blockchain.
+   *
+   * @param args.handle A pointer to where that table is stored.
+   * @param args.data Object that describes the table item, including key and value types.
+   * @param args.data.key_type The Move type of the table key.
+   * @param args.data.value_type The Move type of the table value.
+   * @param args.data.key The value of the table key.
+   * @param args.options.ledgerVersion The ledger version to query; if not provided, it will get the latest version.
+   *
+   * @returns Table item value rendered in JSON.
+   *
+   * @example
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Retrieve a table item from the Aptos blockchain
+   *   const tableItem = await aptos.getTableItem({
+   *     handle: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca",
+   *     data: {
+   *       key_type: "address", // Move type of table key
+   *       value_type: "u128", // Move type of table value
+   *       key: "0x619dc29a0aac8fa146714058e8dd6d2d0f3bdf5f6331907bf91f3acd81e6935" // Value of table key
+   *     },
+   *   });
+   *
+   *   console.log(tableItem);
+   * }
+   * runExample().catch(console.error);
+   * ```
    */
   async getTableItem<T>(args: { handle: string; data: TableItemRequest; options?: LedgerVersionArg }): Promise<T> {
     return getTableItem<T>({ aptosConfig: this.config, ...args });
   }
 
   /**
-   * Queries for a table items data.
+   * Queries for table items data with optional filtering and pagination.
+   * This function allows you to retrieve specific data from a table based on provided criteria.
    *
-   * Optional `options.where` param can be passed to filter the response.
+   * @param args - The arguments for querying table items data.
+   * @param args.minimumLedgerVersion - Optional minimum ledger version to wait for before querying.
+   * @param args.options - Optional parameters for pagination and filtering.
+   * @param args.options.where - Conditions to filter the response.
+   * @param args.options.offset - The number of items to skip before starting to collect the result set.
+   * @param args.options.limit - The maximum number of items to return.
+   * @param args.options.orderBy - The criteria to order the results.
    *
-   * Note, this query calls the indexer server
+   * Note: This query calls the indexer server.
    *
    * @example
-   * const data = await aptos.getTableItemsData({
-   *  options: { where: {
-   *      table_handle: { _eq: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca" },
-   *      transaction_version: { _eq: "0" }
-   *    }
-   *  },
-   * });
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Retrieve table items data with specific filtering options
+   *   const data = await aptos.getTableItemsData({
+   *     minimumLedgerVersion: 1, // specify your own minimum ledger version if needed
+   *     options: {
+   *       where: {
+   *         table_handle: { _eq: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca" },
+   *         transaction_version: { _eq: "0" }
+   *       },
+   *       limit: 10, // specify your own limit if needed
+   *     },
+   *   });
+   *
+   *   console.log(data);
+   * }
+   * runExample().catch(console.error);
+   * ```
    *
    * @returns GetTableItemsDataResponse
    */
@@ -81,16 +138,39 @@ export class Table {
   }
 
   /**
-   * Queries for a table items metadata.
+   * Queries for the metadata of table items, allowing for filtering and pagination.
    *
-   * Optional `options.where` param can be passed to filter the response.
+   * @param args - The parameters for the query.
+   * @param args.minimumLedgerVersion - Optional minimum ledger version to wait for before querying.
+   * @param args.options - Optional parameters for pagination and filtering.
+   * @param args.options.where - Conditions to filter the response.
+   * @param args.options.offset - The offset for pagination.
+   * @param args.options.limit - The maximum number of items to return.
+   * @param args.options.orderBy - The order in which to return the items.
    *
-   * Note, this query calls the indexer server
+   * Note that this query calls the indexer server.
    *
    * @example
-   * const data = await aptos.getTableItemsMetadata({
-   *  options: { where: { handle: { _eq: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca" } } },
-   * });
+   * ```typescript
+   * import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
+   *
+   * const config = new AptosConfig({ network: Network.TESTNET });
+   * const aptos = new Aptos(config);
+   *
+   * async function runExample() {
+   *   // Fetching table items metadata with a filter condition
+   *   const data = await aptos.getTableItemsMetadata({
+   *     minimumLedgerVersion: 1, // specify your own minimum ledger version if needed
+   *     options: {
+   *       where: { handle: { _eq: "0x1b854694ae746cdbd8d44186ca4929b2b337df21d1c74633be19b2710552fdca" } },
+   *       limit: 10, // specify your own limit if needed
+   *     },
+   *   });
+   *
+   *   console.log(data);
+   * }
+   * runExample().catch(console.error);
+   * ```
    *
    * @returns GetTableItemsMetadataResponse
    */