@algorandfoundation/algokit-utils 8.2.0-beta.1 → 8.2.0-beta.3

package/types/app-client.mjs

@@ -94,6 +94,18 @@ function getConstantBlockOffset(program) {
 /** ARC-56/ARC-32 application client that allows you to manage calls and
  * state for a specific deployed instance of an app (with a known app ID). */
 class AppClient {
+    /**
+     * Create a new app client.
+     * @param params The parameters to create the app client
+     * @returns The `AppClient` instance
+     * @example
+     * ```typescript
+     * const appClient = new AppClient({
+     *   appId: 12345678n,
+     *   appSpec: appSpec,
+     *   algorand: AlgorandClient.mainNet(),
+     * })
+     */
     constructor(params) {
         this._appId = params.appId;
         this._appAddress = algosdk.getApplicationAddress(this._appId);
@@ -128,6 +140,10 @@ class AppClient {
      *
      * @param params The params to use for the the cloned app client. Omit a param to keep the original value. Set a param to override the original value. Setting to undefined will clear the original value.
      * @returns A new app client with the altered params
+     * @example
+     * ```typescript
+     * const appClient2 = appClient.clone({ defaultSender: 'NEW_SENDER_ADDRESS' })
+     * ```
      */
     clone(params) {
         return new AppClient({
@@ -146,6 +162,15 @@ class AppClient {
      * Returns a new `AppClient` client, resolving the app by creator address and name
      * using AlgoKit app deployment semantics (i.e. looking for the app creation transaction note).
      * @param params The parameters to create the app client
+     * @returns The `AppClient` instance
+     * @example
+     * ```typescript
+     * const appClient = await AppClient.fromCreatorAndName({
+     *   creatorAddress: 'CREATOR_ADDRESS',
+     *   name: 'APP_NAME',
+     *   appSpec: appSpec,
+     *   algorand: AlgorandClient.mainNet(),
+     * })
      */
     static async fromCreatorAndName(params) {
         const appSpec = AppClient.normaliseAppSpec(params.appSpec);
@@ -166,6 +191,13 @@ class AppClient {
      *
      * If no IDs are in the app spec or the network isn't recognised, an error is thrown.
      * @param params The parameters to create the app client
+     * @returns The `AppClient` instance
+     * @example
+     * ```typescript
+     * const appClient = await AppClient.fromNetwork({
+     *   appSpec: appSpec,
+     *   algorand: AlgorandClient.mainNet(),
+     * })
      */
     static async fromNetwork(params) {
         const network = await params.algorand.client.network();
@@ -190,6 +222,10 @@ class AppClient {
      * normalises it into a parsed ARC-56 contract object.
      * @param spec The spec to normalise
      * @returns The normalised ARC-56 contract object
+     * @example
+     * ```typescript
+     * const arc56AppSpec = AppClient.normaliseAppSpec(appSpec)
+     * ```
      */
     static normaliseAppSpec(spec) {
         const parsedSpec = typeof spec === 'string' ? JSON.parse(spec) : spec;
@@ -266,6 +302,10 @@ class AppClient {
      * An alias for `appClient.send.fundAppAccount(params)`.
      * @param params The parameters for the funding transaction
      * @returns The result of the funding
+     * @example
+     * ```typescript
+     * await appClient.fundAppAccount({ amount: algo(1) })
+     * ```
      */
     async fundAppAccount(params) {
         return this.send.fundAppAccount(params);
@@ -273,6 +313,10 @@ class AppClient {
     /**
      * Returns raw global state for the current app.
      * @returns The global state
+     * @example
+     * ```typescript
+     * const globalState = await appClient.getGlobalState()
+     * ```
      */
     async getGlobalState() {
         return await this._algorand.app.getGlobalState(this.appId);
@@ -281,6 +325,10 @@ class AppClient {
      * Returns raw local state for the given account address.
      * @param address The address of the account to get the local state for
      * @returns The local state
+     * @example
+     * ```typescript
+     * const localState = await appClient.getLocalState('ACCOUNT_ADDRESS')
+     * ```
      */
     async getLocalState(address) {
         return await this._algorand.app.getLocalState(this.appId, address);
@@ -288,6 +336,10 @@ class AppClient {
     /**
      * Returns the names of all current boxes for the current app.
      * @returns The names of the boxes
+     * @example
+     * ```typescript
+     * const boxNames = await appClient.getBoxNames()
+     * ```
      */
     async getBoxNames() {
         return await this._algorand.app.getBoxNames(this.appId);
@@ -296,6 +348,10 @@ class AppClient {
      * Returns the value of the given box for the current app.
      * @param name The identifier of the box to return
      * @returns The current box value as a byte array
+     * @example
+     * ```typescript
+     * const boxValue = await appClient.getBoxValue('boxName')
+     * ```
      */
     async getBoxValue(name) {
         return await this._algorand.app.getBoxValue(this.appId, name);
@@ -305,6 +361,10 @@ class AppClient {
      * @param name The identifier of the box to return
      * @param type
      * @returns The current box value as a byte array
+     * @example
+     * ```typescript
+     * const boxValue = await appClient.getBoxValueFromABIType('boxName', new ABIUintType(32))
+     * ```
      */
     async getBoxValueFromABIType(name, type) {
         return await this._algorand.app.getBoxValueFromABIType({
@@ -318,6 +378,10 @@ class AppClient {
      * Note: This will issue multiple HTTP requests (one per box) and it's not an atomic operation so values may be out of sync.
      * @param filter Optional filter to filter which boxes' values are returned
      * @returns The (name, value) pair of the boxes with values as raw byte arrays
+     * @example
+     * ```typescript
+     * const boxValues = await appClient.getBoxValues()
+     * ```
      */
     async getBoxValues(filter) {
         const names = (await this.getBoxNames()).filter(filter ?? ((_) => true));
@@ -330,6 +394,10 @@ class AppClient {
      * @param type The ABI type to decode the values with
      * @param filter Optional filter to filter which boxes' values are returned
      * @returns The (name, value) pair of the boxes with values as the ABI Value
+     * @example
+     * ```typescript
+     * const boxValues = await appClient.getBoxValuesFromABIType(new ABIUintType(32))
+     * ```
      */
     async getBoxValuesFromABIType(type, filter) {
         const names = (await this.getBoxNames()).filter(filter ?? ((_) => true));
@@ -414,6 +482,8 @@ class AppClient {
      * If no TEAL templates provided it will use any byte code provided in the app spec.
      *
      * Will store any generated source maps for later use in debugging.
+     * @param compilation Any compilation parameters to use
+     * @returns The compiled code and any compilation results (including source maps)
      */
     async compile(compilation) {
         const result = await AppClient.compile(this._appSpec, this._algorand.app, compilation);
@@ -489,7 +559,9 @@ class AppClient {
      *
      * Will store any generated source maps for later use in debugging.
      * @param appSpec The app spec for the app
+     * @param appManager The app manager to use for compilation
      * @param compilation Any compilation parameters to use
+     * @returns The compiled code and any compilation results (including source maps)
      */
     static async compile(appSpec, appManager, compilation) {
         const { deployTimeParams, updatable, deletable } = compilation ?? {};
@@ -537,6 +609,9 @@ class AppClient {
         const m = getArc56Method(methodNameOrSignature, this._appSpec);
         return await Promise.all(args?.map(async (a, i) => {
             const arg = m.args[i];
+            if (!arg) {
+                throw new Error(`Unexpected arg at position ${i}. ${m.name} only expects ${m.args.length} args`);
+            }
             if (a !== undefined) {
                 // If a struct then convert to tuple for the underlying call
                 return arg.struct && typeof a === 'object' && !Array.isArray(a)
@@ -678,7 +753,11 @@ class AppClient {
     }
     getMethodCallParamsMethods() {
         return {
-            /** Return params for a payment transaction to fund the app account */
+            /**
+             * Return params for a payment transaction to fund the app account
+             * @param params The parameters for the fund app accont payment transaction
+             * @returns The parameters which can be used to create a fund app account payment transaction
+             */
             fundAppAccount: (params) => {
                 return {
                     ...params,
@@ -687,26 +766,44 @@ class AppClient {
                     receiver: this.appAddress,
                 };
             },
-            /** Return params for an update ABI call, including deploy-time TEAL template replacements and compilation if provided */
+            /**
+             * Return params for an update ABI call, including deploy-time TEAL template replacements and compilation if provided
+             * @param params The parameters for the update ABI method call
+             * @returns The parameters which can be used to create an update ABI method call
+             */
             update: async (params) => {
                 return (await this.getABIParams({
                     ...params,
                     ...(await this.compile(params)),
                 }, OnApplicationComplete.UpdateApplicationOC));
             },
-            /** Return params for an opt-in ABI call */
+            /**
+             * Return params for an opt-in ABI call
+             * @param params The parameters for the opt-in ABI method call
+             * @returns The parameters which can be used to create an opt-in ABI method call
+             */
             optIn: async (params) => {
                 return (await this.getABIParams(params, OnApplicationComplete.OptInOC));
             },
-            /** Return params for an delete ABI call */
+            /**
+             * Return params for an delete ABI call
+             * @param params The parameters for the delete ABI method call
+             * @returns The parameters which can be used to create a delete ABI method call
+             */
             delete: async (params) => {
                 return (await this.getABIParams(params, OnApplicationComplete.DeleteApplicationOC));
             },
-            /** Return params for an close out ABI call */
+            /** Return params for an close out ABI call
+             * @param params The parameters for the close out ABI method call
+             * @returns The parameters which can be used to create a close out ABI method call
+             */
             closeOut: async (params) => {
                 return (await this.getABIParams(params, OnApplicationComplete.CloseOutOC));
             },
-            /** Return params for an ABI call */
+            /** Return params for an ABI call
+             * @param params The parameters for the ABI method call
+             * @returns The parameters which can be used to create an ABI method call
+             */
             call: async (params) => {
                 return (await this.getABIParams(params, params.onComplete ?? OnApplicationComplete.NoOpOC));
             },
@@ -714,12 +811,17 @@ class AppClient {
     }
     getMethodCallSendMethods() {
         return {
-            /** Sign and send transactions for a payment transaction to fund the app account */
+            /** Sign and send transactions for a payment transaction to fund the app account
+             * @param params The parameters for the fund app account payment transaction
+             * @returns The result of send the fund app account payment transaction
+             */
             fundAppAccount: (params) => {
                 return this._algorand.send.payment(this.params.fundAppAccount(params));
             },
             /**
              * Sign and send transactions for an update ABI call, including deploy-time TEAL template replacements and compilation if provided
+             * @param params The parameters for the update ABI method call
+             * @returns The result of sending the update ABI method call
              */
             update: async (params) => {
                 const compiled = await this.compile(params);
@@ -730,24 +832,32 @@ class AppClient {
             },
             /**
              * Sign and send transactions for an opt-in ABI call
+             * @param params The parameters for the opt-in ABI method call
+             * @returns The result of sending the opt-in ABI method call
              */
             optIn: (params) => {
                 return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.optIn(params)), getArc56Method(params.method, this._appSpec)));
             },
             /**
              * Sign and send transactions for a delete ABI call
+             * @param params The parameters for the delete ABI method call
+             * @returns The result of sending the delete ABI method call
              */
             delete: (params) => {
                 return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appDeleteMethodCall(await this.params.delete(params)), getArc56Method(params.method, this._appSpec)));
             },
             /**
              * Sign and send transactions for a close out ABI call
+             * @param params The parameters for the close out ABI method call
+             * @returns The result of sending the close out ABI method call
              */
             closeOut: (params) => {
                 return this.handleCallErrors(async () => this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.closeOut(params)), getArc56Method(params.method, this._appSpec)));
             },
             /**
              * Sign and send transactions for a call (defaults to no-op)
+             * @param params The parameters for the ABI method call
+             * @returns The result of sending the ABI method call
              */
             call: async (params) => {
                 // Read-only call - do it via simulate
@@ -798,36 +908,49 @@ class AppClient {
     }
     getMethodCallCreateTransactionMethods() {
         return {
-            /** Return transaction for a payment transaction to fund the app account */
+            /** Return transaction for a payment transaction to fund the app account
+             * @param params The parameters for the fund app account payment transaction
+             * @returns A transaction which can be used to fund the app account
+             */
             fundAppAccount: (params) => {
                 return this._algorand.createTransaction.payment(this.params.fundAppAccount(params));
             },
             /**
              * Return transactions for an update ABI call, including deploy-time TEAL template replacements and compilation if provided
+             * @param params The parameters for the update ABI method call
+             * @returns The transactions which can be used to create an update ABI method call
              */
             update: async (params) => {
                 return this._algorand.createTransaction.appUpdateMethodCall(await this.params.update(params));
             },
             /**
              * Return transactions for an opt-in ABI call
+             * @param params The parameters for the opt-in ABI method call
+             * @returns The transactions which can be used to create an opt-in ABI method call
              */
             optIn: async (params) => {
                 return this._algorand.createTransaction.appCallMethodCall(await this.params.optIn(params));
             },
             /**
              * Return transactions for a delete ABI call
+             * @param params The parameters for the delete ABI method call
+             * @returns The transactions which can be used to create a delete ABI method call
              */
             delete: async (params) => {
                 return this._algorand.createTransaction.appDeleteMethodCall(await this.params.delete(params));
             },
             /**
              * Return transactions for a close out ABI call
+             * @param params The parameters for the close out ABI method call
+             * @returns The transactions which can be used to create a close out ABI method call
              */
             closeOut: async (params) => {
                 return this._algorand.createTransaction.appCallMethodCall(await this.params.closeOut(params));
             },
             /**
              * Return transactions for an ABI call (defaults to no-op)
+             * @param params The parameters for the ABI method call
+             * @returns The transactions which can be used to create an ABI method call
              */
             call: async (params) => {
                 return this._algorand.createTransaction.appCallMethodCall(await this.params.call(params));