@aptos-labs/ts-sdk 1.29.0 → 1.30.0

package/src/cli/move.ts

@@ -4,56 +4,58 @@ import { platform } from "os";
 import { AccountAddress } from "../core";
 import { Network } from "../utils";
 
+/**
+ * Class representing a Move package management utility for the Aptos blockchain.
+ * This class provides methods to initialize directories, compile packages, run tests, publish modules, create objects, upgrade
+ * packages, build transaction payloads, and run scripts.
+ */
 export class Move {
   /**
-   * Function to initialize current directory for Aptos
-   *
-   * Configuration will be pushed into .aptos/config.yaml
-   * @param args.network optional Network type argument to use for default settings, default is local
-   * @param args.profile optional Profile to use from the config file, default is 'default'
-   * This will be used to override associated settings such as the REST URL, the Faucet URL, and the private key arguments.
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
+   * Initialize the current directory for Aptos by configuring the necessary settings.
+   * Configuration will be pushed into .aptos/config.yaml.
    *
+   * @param args - The arguments for initialization.
+   * @param args.network - Optional Network type argument to use for default settings; defaults to local.
+   * @param args.profile - Optional Profile to use from the config file; defaults to 'default'. This will override associated
+   * settings such as the REST URL, the Faucet URL, and the private key arguments.
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
    * @returns stdout
    */
   async init(args: {
     network?: Network;
     profile?: string;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ output: string }> {
-    const { network, profile, extraArguments } = args;
+    const { network, profile, extraArguments, showStdout } = args;
     const cliArgs = ["aptos", "init", `--network=${network ?? "local"}`, `--profile=${profile ?? "default"}`];
 
     if (extraArguments) {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Function to compile a package
-   *
-   * @param args.packageDirectoryPath Path to a move package (the folder with a Move.toml file)
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
-   * @example
-   * {
-   *  alice:0x1234, bob:0x5678
-   * }
+   * Compile a Move package located at the specified directory path.
+   * This function helps in preparing the Move package for deployment or further processing.
    *
+   * @param args - The arguments for compiling the package.
+   * @param args.packageDirectoryPath - Path to a Move package (the folder with a Move.toml file).
+   * @param args.namedAddresses - Named addresses for the move binary. Ex. { alice: 0x1234, bob: 0x5678 }
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
    * @returns stdout
    */
   async compile(args: {
     packageDirectoryPath: string;
     namedAddresses: Record<string, AccountAddress>;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ output: string }> {
-    const { packageDirectoryPath, namedAddresses, extraArguments } = args;
+    const { packageDirectoryPath, namedAddresses, extraArguments, showStdout } = args;
     const cliArgs = ["aptos", "move", "compile", "--package-dir", packageDirectoryPath];
 
     const addressesMap = this.parseNamedAddresses(namedAddresses);
@@ -64,30 +66,26 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Function to run Move unit tests for a package
+   * Run Move unit tests for a specified package.
    *
-   * @param args.packageDirectoryPath Path to a move package (the folder with a Move.toml file)
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @example
-   * {
-   *  alice:0x1234, bob:0x5678
-   * }
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
-   *
-   * @returns stdout
+   * @param args - The arguments for running the tests.
+   * @param args.packageDirectoryPath - The path to a Move package (the folder containing a Move.toml file).
+   * @param args.namedAddresses - Named addresses for the move binary. Ex. { alice: 0x1234, bob: 0x5678 }
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
+   * @returns The stdout output from running the tests.
    */
   async test(args: {
     packageDirectoryPath: string;
     namedAddresses: Record<string, AccountAddress>;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ output: string }> {
-    const { packageDirectoryPath, namedAddresses, extraArguments } = args;
+    const { packageDirectoryPath, namedAddresses, extraArguments, showStdout } = args;
     const cliArgs = ["aptos", "move", "test", "--package-dir", packageDirectoryPath];
 
     const addressesMap = this.parseNamedAddresses(namedAddresses);
@@ -98,23 +96,18 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Function to publish the modules to the publisher account on the Aptos blockchain
-   *
-   * @param args.packageDirectoryPath Path to a move package (the folder with a Move.toml file)
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @example
-   * {
-   *  alice:0x1234, bob:0x5678
-   * }
-   * @param args.profile optional Profile to use from the config file.
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
+   * Publishes the modules to the publisher account on the Aptos blockchain.
    *
+   * @param args - The arguments for publishing the modules.
+   * @param args.packageDirectoryPath - The path to a move package (the folder with a Move.toml file).
+   * @param args.namedAddresses - Named addresses for the move binary. Ex. { alice: 0x1234, bob: 0x5678 }
+   * @param args.profile - Optional profile to use from the config file.
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
    * @returns stdout
    */
   async publish(args: {
@@ -122,8 +115,9 @@ export class Move {
     namedAddresses: Record<string, AccountAddress>;
     profile?: string;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ output: string }> {
-    const { packageDirectoryPath, namedAddresses, profile, extraArguments } = args;
+    const { packageDirectoryPath, namedAddresses, profile, extraArguments, showStdout } = args;
     const cliArgs = [
       "aptos",
       "move",
@@ -141,34 +135,28 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Function to create a new object and publish the Move package to it on the Aptos blockchain
+   * Create a new object and publish the Move package to it on the Aptos blockchain.
    *
-   * @param args.packageDirectoryPath Path to a move package (the folder with a Move.toml file)
-   * @param args.addressName Address name for the Move package
-   * @example
-   * MoonCoin, please find the actual address name in Move.toml
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @example
-   * {
-   *  alice:0x1234, bob:0x5678
-   * }
-   * @param args.profile optional Profile to use from the config file.
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
+   * @param args - The arguments for creating the object and publishing the package.
+   * @param args.packageDirectoryPath - Path to a Move package (the folder with a Move.toml file).
+   * @param args.addressName - Address name for the Move package.
+   * @param args.namedAddresses - Named addresses for the Move binary.
+   * @param args.profile - Optional profile to use from the config file.
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
+   * @returns The object address.
    *
-   * A complete example in cli
+   * A complete example in CLI:
    * aptos move create-object-and-publish-package \
    * --package-dir path_to_directory_that_has_move.toml \
    * --address-name launchpad_addr \
-   * --named-addresses "launchpad_addr=0x123,initial_creator_addr=0x456"\
+   * --named-addresses "launchpad_addr=0x123,initial_creator_addr=0x456" \
    * --profile my_profile \
    * --assume-yes
-   * @returns object address
    */
   async createObjectAndPublishPackage(args: {
     packageDirectoryPath: string;
@@ -176,8 +164,9 @@ export class Move {
     namedAddresses: Record<string, AccountAddress>;
     profile?: string;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ objectAddress: string }> {
-    const { packageDirectoryPath, addressName, namedAddresses, profile, extraArguments } = args;
+    const { packageDirectoryPath, addressName, namedAddresses, profile, extraArguments, showStdout } = args;
     const cliArgs = [
       "aptos",
       "move",
@@ -197,28 +186,21 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    const result = await this.runCommand(cliArgs);
+    const result = await this.runCommand(cliArgs, showStdout);
     return { objectAddress: this.extractAddressFromOutput(result.output) };
   }
 
   /**
-   * Function to upgrade a Move package previously published to an object on the Aptos blockchain
-   * Caller must be the object owner to call this function
-   *
-   * @param args.packageDirectoryPath Path to a move package (the folder with a Move.toml file)
-   * @param args.objectAddress Address of the object that the Move package published to
-   * @example
-   * 0x1000
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @example
-   * {
-   *  alice:0x1234, bob:0x5678
-   * }
-   * @param args.profile optional Profile to use from the config file.
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
+   * Upgrade a Move package previously published to an object on the Aptos blockchain.
+   * The caller must be the object owner to execute this function.
    *
+   * @param args - The arguments for upgrading the object package.
+   * @param args.packageDirectoryPath - Path to a Move package (the folder with a Move.toml file).
+   * @param args.objectAddress - Address of the object that the Move package published to. Ex. 0x1000
+   * @param args.namedAddresses - Named addresses for the move binary. Ex. { alice: 0x1234, bob: 0x5678 }
+   * @param args.profile - Optional profile to use from the config file.
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
    * @returns stdout
    */
   async upgradeObjectPackage(args: {
@@ -227,8 +209,9 @@ export class Move {
     namedAddresses: Record<string, AccountAddress>;
     profile?: string;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ output: string }> {
-    const { packageDirectoryPath, objectAddress, namedAddresses, profile, extraArguments } = args;
+    const { packageDirectoryPath, objectAddress, namedAddresses, profile, extraArguments, showStdout } = args;
     const cliArgs = [
       "aptos",
       "move",
@@ -248,23 +231,18 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Build a publication transaction payload and store it in a JSON output file
-   *
-   * @param args.packageDirectoryPath Path to a move package (the folder with a Move.toml file)
-   * @param args.outputFile Output file to write publication transaction to
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @example
-   * {
-   *  alice:0x1234, bob:0x5678
-   * }
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
+   * Build a publication transaction payload and store it in a JSON output file.
    *
+   * @param args - The arguments for building the publishing payload.
+   * @param args.packageDirectoryPath - Path to a move package (the folder with a Move.toml file).
+   * @param args.outputFile - Output file to write the publication transaction to.
+   * @param args.namedAddresses - Named addresses for the move binary. Ex. { alice: 0x1234, bob: 0x5678 }
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]   *
    * @returns stdout
    */
   async buildPublishPayload(args: {
@@ -272,8 +250,9 @@ export class Move {
     outputFile: string;
     namedAddresses: Record<string, AccountAddress>;
     extraArguments?: Array<string>;
-  }) {
-    const { outputFile, packageDirectoryPath, namedAddresses, extraArguments } = args;
+    showStdout?: boolean;
+  }): Promise<{ output: string }> {
+    const { outputFile, packageDirectoryPath, namedAddresses, extraArguments, showStdout } = args;
     const cliArgs = [
       "aptos",
       "move",
@@ -292,29 +271,29 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Function to run a Move script, please run compile before running this
+   * Runs a Move script using the provided compiled script path and optional parameters. Ensure that the script is compiled
+   * before executing this function.
    *
-   * @param args.compiledScriptPath Path to a compiled Move script bytecode file
-   * @param args.namedAddresses  Named addresses for the move binary
-   * @example
-   * build/my_package/bytecode_scripts/my_move_script.mv
-   * @param args.profile optional Profile to use from the config file.
-   * @param args.extraArguments (optional) Any extra arguments to include in the form of an array of strings
-   * @example
-   * ["--assume-yes","--gas-unit-price=10"]
+   * @param args - The arguments for running the script.
+   * @param args.compiledScriptPath - Path to a compiled Move script bytecode file.
+   * Ex. "build/my_package/bytecode_scripts/my_move_script.mv"
+   * @param args.profile - Optional profile to use from the config file.
+   * @param args.extraArguments - Optional extra arguments to include in the form of an array of strings.
+   * Ex. ["--assume-yes","--gas-unit-price=10"]
    *
-   * @returns stdout
+   * @returns The standard output from running the script.
    */
   async runScript(args: {
     compiledScriptPath: string;
     profile?: string;
     extraArguments?: Array<string>;
+    showStdout?: boolean;
   }): Promise<{ output: string }> {
-    const { compiledScriptPath, profile, extraArguments } = args;
+    const { compiledScriptPath, profile, extraArguments, showStdout } = args;
     const cliArgs = [
       "aptos",
       "move",
@@ -328,17 +307,18 @@ export class Move {
       cliArgs.push(...extraArguments);
     }
 
-    return this.runCommand(cliArgs);
+    return this.runCommand(cliArgs, showStdout);
   }
 
   /**
-   * Run a move command
+   * Run a command with the specified arguments and return the output.
    *
-   * @param args
-   * @returns stdout
+   * @param args - An array of strings representing the command-line arguments to be passed to the command.
+   * @param showStdout - Show the standard output generated by the command.
+   * @returns The standard output generated by the command.
    */
   // eslint-disable-next-line class-methods-use-this
-  private async runCommand(args: Array<string>): Promise<{ output: string }> {
+  private async runCommand(args: Array<string>, showStdout: boolean = true): Promise<{ output: string }> {
     return new Promise((resolve, reject) => {
       const currentPlatform = platform();
       let childProcess;
@@ -355,9 +335,11 @@ export class Move {
         stdout += data.toString();
       });
 
-      childProcess.stdout.pipe(process.stdout);
-      childProcess.stderr.pipe(process.stderr);
-      process.stdin.pipe(childProcess.stdin);
+      if (showStdout) {
+        childProcess.stdout.pipe(process.stdout);
+        childProcess.stderr.pipe(process.stderr);
+        process.stdin.pipe(childProcess.stdin);
+      }
 
       childProcess.on("close", (code) => {
         if (code === 0) {
@@ -370,14 +352,11 @@ export class Move {
   }
 
   /**
-   * Convert named addresses from a Map into an array seperated by a comma
-   *
-   * @example
-   * input: {'alice' => '0x123', 'bob' => '0x456'}
-   * output: "alice=0x123,bob=0x456"
+   * Convert named addresses from a Map into an array separated by a comma.
    *
-   * @param namedAddresses
-   * @returns An array of names addresses seperated by a comma
+   * @param namedAddresses - A Map where the key is a string representing the name and the value is an AccountAddress.
+   * Ex. {'alice' => '0x123', 'bob' => '0x456'}
+   * @returns An array of named addresses formatted as strings separated by a comma. Ex. "alice=0x123,bob=0x456"
    */
   // eslint-disable-next-line class-methods-use-this
   private prepareNamedAddresses(namedAddresses: Map<string, AccountAddress>): Array<string> {
@@ -400,10 +379,13 @@ export class Move {
   }
 
   /**
-   * Parse named addresses from a Record type into a Map
+   * Parse named addresses from a Record type into a Map.
+   *
+   * This function transforms a collection of named addresses into a more accessible format by mapping each name to its
+   * corresponding address.
    *
-   * @param namedAddresses
-   * @returns Map<name,address>
+   * @param namedAddresses - A record containing named addresses where the key is the name and the value is the AccountAddress.
+   * @returns A Map where each key is a name and each value is the corresponding address.
    */
   // eslint-disable-next-line class-methods-use-this
   private parseNamedAddresses(namedAddresses: Record<string, AccountAddress>): Map<string, AccountAddress> {
@@ -418,10 +400,11 @@ export class Move {
   }
 
   /**
-   * Extract object address from the output
+   * Extracts the object address from the provided output string.
    *
-   * @param output
-   * @returns object address
+   * @param output - The output string containing the object address.
+   * @returns The extracted object address.
+   * @throws Error if the object address cannot be extracted from the output.
    */
   // eslint-disable-next-line class-methods-use-this
   private extractAddressFromOutput(output: string): string {

package/src/client/core.ts

@@ -8,8 +8,22 @@ import { AnyNumber, AptosRequest, Client, ClientRequest, ClientResponse, MimeTyp
 import { AptosApiType } from "../utils";
 
 /**
- * Given a url and method, sends the request with axios and
- * returns the response.
+ * Sends a request using the specified options and returns the response.
+ *
+ * @param options - The options for the request.
+ * @param options.url - The URL to send the request to.
+ * @param options.method - The HTTP method to use for the request.
+ * @param options.body - The body of the request.
+ * @param options.contentType - The content type of the request.
+ * @param options.params - The query parameters to include in the request.
+ * @param options.overrides - Additional overrides for the request.
+ * @param options.overrides.HEADERS - Custom headers to include in the request.
+ * @param options.overrides.AUTH_TOKEN - The authorization token for the request.
+ * @param options.overrides.API_KEY - The API key for the request.
+ * @param options.originMethod - The origin method for the request.
+ * @param client - The client used to make the request.
+ *
+ * @returns The response from the request.
  */
 export async function request<Req, Res>(options: ClientRequest<Req>, client: Client): Promise<ClientResponse<Res>> {
   const { url, method, body, contentType, params, overrides, originMethod } = options;
@@ -42,11 +56,12 @@ export async function request<Req, Res>(options: ClientRequest<Req>, client: Cli
 }
 
 /**
- * The main function to use when doing an API request.
+ * The main function to use when making an API request, returning the response or throwing an AptosApiError on failure.
  *
- * @param aptosRequestOpts AptosRequest
- * @param aptosConfig The config information for the SDK client instance
- * @returns the response or AptosApiError
+ * @param aptosRequestOpts - Options for the Aptos request, including the URL and path.
+ * @param aptosConfig - The configuration information for the SDK client instance.
+ * @param apiType - The type of API being accessed, which determines how the response is handled.
+ * @returns The response from the API request or throws an AptosApiError if the request fails.
  */
 export async function aptosRequest<Req extends {}, Res extends {}>(
   aptosRequestOpts: AptosRequest,
@@ -59,7 +74,7 @@ export async function aptosRequest<Req extends {}, Res extends {}>(
 
   const aptosResponse: AptosResponse<Req, Res> = {
     status: clientResponse.status,
-    statusText: clientResponse.statusText!,
+    statusText: clientResponse.statusText ?? "No status text provided",
     data: clientResponse.data,
     headers: clientResponse.headers,
     config: clientResponse.config,
@@ -67,7 +82,7 @@ export async function aptosRequest<Req extends {}, Res extends {}>(
     url: fullUrl,
   };
 
-  // Handle case for `Unauthorized` error (i.e API_KEY error)
+  // Handle case for `Unauthorized` error (i.e. API_KEY error)
   if (aptosResponse.status === 401) {
     throw new AptosApiError({ apiType, aptosRequest: aptosRequestOpts, aptosResponse });
   }

package/src/client/get.ts

@@ -4,6 +4,9 @@ import { AptosResponse } from "./types";
 import { AnyNumber, ClientConfig, MimeType } from "../types";
 import { AptosApiType } from "../utils/const";
 
+/**
+ * Options for making a GET request, including configuration for the API client.
+ */
 export type GetRequestOptions = {
   /**
    * The config for the API client
@@ -39,13 +42,24 @@ export type GetRequestOptions = {
   overrides?: ClientConfig;
 };
 
+/**
+ * Options for making a request to the Aptos API, excluding the "type" field.
+ */
 export type GetAptosRequestOptions = Omit<GetRequestOptions, "type">;
 
 /**
- * Main function to do a Get request
+ * Executes a GET request to retrieve data based on the provided options.
  *
- * @param options GetRequestOptions
- * @returns
+ * @param options - The options for the GET request.
+ * @param options.aptosConfig - The configuration object for Aptos requests.
+ * @param options.overrides - Optional overrides for the request configuration.
+ * @param options.params - Query parameters to include in the request.
+ * @param options.contentType - The content type of the request.
+ * @param options.acceptType - The accepted response type.
+ * @param options.path - The specific path for the request.
+ * @param options.originMethod - The original method of the request.
+ * @param options.type - The type of request being made.
+ * @returns The response from the GET request.
  */
 export async function get<Req extends {}, Res extends {}>(
   options: GetRequestOptions,
@@ -72,6 +86,18 @@ export async function get<Req extends {}, Res extends {}>(
   );
 }
 
+/**
+ * Retrieves data from the Aptos full node using the provided options.
+ *
+ * @param options - The options for the request to the Aptos full node.
+ * @param options.aptosConfig - Configuration settings specific to the Aptos client and full node.
+ * @param options.aptosConfig.clientConfig - The client configuration settings.
+ * @param options.aptosConfig.fullnodeConfig - The full node configuration settings.
+ * @param options.overrides - Additional overrides for the request.
+ * @param options.type - The type of API request being made.
+ *
+ * @returns A promise that resolves with the response from the Aptos full node.
+ */
 export async function getAptosFullNode<Req extends {}, Res extends {}>(
   options: GetAptosRequestOptions,
 ): Promise<AptosResponse<Req, Res>> {
@@ -90,10 +116,12 @@ export async function getAptosFullNode<Req extends {}, Res extends {}>(
 }
 
 /**
- * Makes a get request to the pepper service
+ * Makes a GET request to the Aptos Pepper service to retrieve data.
  *
- * @param options GetAptosRequestOptions
- * @returns AptosResponse
+ * @param options - The options for the request.
+ * @param options.param1 - Description of param1.
+ * @param options.param2 - Description of param2.
+ * @returns AptosResponse - The response from the Aptos Pepper service.
  */
 export async function getAptosPepperService<Req extends {}, Res extends {}>(
   options: GetAptosRequestOptions,