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

package/types/app-client.d.ts

@@ -284,18 +284,43 @@ export declare class AppClient {
     private _paramsMethods;
     private _createTransactionsMethods;
     private _sendMethods;
+    /**
+     * 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: AppClientParams);
     /**
      * Clone this app client with different params
      *
      * @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: CloneAppClientParams): 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 fromCreatorAndName(params: ResolveAppClientByCreatorAndName): Promise<AppClient>;
     /**
@@ -304,6 +329,13 @@ export declare 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 fromNetwork(params: ResolveAppClientByNetwork): Promise<AppClient>;
     /**
@@ -311,6 +343,10 @@ export declare 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: Arc56Contract | AppSpec | string): Arc56Contract;
     /** The ID of the app instance this client is linked to. */
@@ -339,7 +375,11 @@ export declare class AppClient {
      * ```
      */
     get params(): {
-        /** 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: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -378,7 +418,11 @@ export declare class AppClient {
             populateAppCallResources?: boolean | undefined;
             coverAppCallInnerTransactionFees?: boolean | undefined;
         };
-        /** 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: (params: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -485,7 +529,11 @@ export declare class AppClient {
                 clearStateProgram: string | Uint8Array;
             }> | AppMethodCall<import("./composer").AppMethodCallParams> | undefined)[] | undefined;
         }>;
-        /** 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: (params: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -506,7 +554,11 @@ export declare class AppClient {
             method: string;
             args?: (algosdk.ABIValue | AppMethodCallTransactionArgument | ABIStruct | undefined)[] | undefined;
         }) => Promise<AppCallMethodCall>;
-        /** 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: (params: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -527,7 +579,10 @@ export declare class AppClient {
             method: string;
             args?: (algosdk.ABIValue | AppMethodCallTransactionArgument | ABIStruct | undefined)[] | undefined;
         }) => Promise<AppDeleteMethodCall>;
-        /** 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: (params: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -548,7 +603,10 @@ export declare class AppClient {
             method: string;
             args?: (algosdk.ABIValue | AppMethodCallTransactionArgument | ABIStruct | undefined)[] | undefined;
         }) => Promise<AppCallMethodCall>;
-        /** 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: (params: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -710,7 +768,10 @@ export declare class AppClient {
     };
     /** Create transactions for the current app */
     get createTransaction(): {
-        /** 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: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -732,6 +793,8 @@ export declare class AppClient {
         }) => Promise<algosdk.Transaction>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -759,6 +822,8 @@ export declare class AppClient {
         }>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -786,6 +851,8 @@ export declare class AppClient {
         }>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -813,6 +880,8 @@ export declare class AppClient {
         }>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -840,6 +909,8 @@ export declare class AppClient {
         }>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -985,7 +1056,10 @@ export declare class AppClient {
     };
     /** Send transactions to the current app */
     get send(): {
-        /** 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: {
             maxFee?: AlgoAmount | undefined;
             note?: string | Uint8Array | undefined;
@@ -1015,6 +1089,8 @@ export declare class AppClient {
         }>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -1049,6 +1125,8 @@ export declare 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: {
             maxFee?: AlgoAmount | undefined;
@@ -1081,6 +1159,8 @@ export declare class AppClient {
         }, "return"> & AppReturn<algosdk.ABIValue | ABIStruct | undefined>>;
         /**
          * 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: {
             maxFee?: AlgoAmount | undefined;
@@ -1113,6 +1193,8 @@ export declare class AppClient {
         }, "return"> & AppReturn<algosdk.ABIValue | ABIStruct | undefined>>;
         /**
          * 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: {
             maxFee?: AlgoAmount | undefined;
@@ -1145,6 +1227,8 @@ export declare class AppClient {
         }, "return"> & AppReturn<algosdk.ABIValue | ABIStruct | undefined>>;
         /**
          * 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: (params: {
             maxFee?: AlgoAmount | undefined;
@@ -1455,6 +1539,10 @@ export declare 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) })
+     * ```
      */
     fundAppAccount(params: FundAppParams): Promise<{
         groupId: string;
@@ -1468,23 +1556,39 @@ export declare class AppClient {
     /**
      * Returns raw global state for the current app.
      * @returns The global state
+     * @example
+     * ```typescript
+     * const globalState = await appClient.getGlobalState()
+     * ```
      */
     getGlobalState(): Promise<AppState>;
     /**
      * 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')
+     * ```
      */
     getLocalState(address: Address | string): Promise<AppState>;
     /**
      * Returns the names of all current boxes for the current app.
      * @returns The names of the boxes
+     * @example
+     * ```typescript
+     * const boxNames = await appClient.getBoxNames()
+     * ```
      */
     getBoxNames(): Promise<BoxName[]>;
     /**
      * 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')
+     * ```
      */
     getBoxValue(name: BoxIdentifier): Promise<Uint8Array>;
     /**
@@ -1492,6 +1596,10 @@ export declare 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))
+     * ```
      */
     getBoxValueFromABIType(name: BoxIdentifier, type: ABIType): Promise<ABIValue>;
     /**
@@ -1499,6 +1607,10 @@ export declare 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()
+     * ```
      */
     getBoxValues(filter?: (name: BoxName) => boolean): Promise<{
         name: BoxName;
@@ -1510,6 +1622,10 @@ export declare 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))
+     * ```
      */
     getBoxValuesFromABIType(type: ABIType, filter?: (name: BoxName) => boolean): Promise<{
         name: BoxName;
@@ -1559,6 +1675,8 @@ export declare 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)
      */
     compile(compilation?: AppClientCompilationParams): Promise<AppClientCompilationResult>;
     /**
@@ -1586,7 +1704,9 @@ export declare 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 compile(appSpec: Arc56Contract, appManager: AppManager, compilation?: AppClientCompilationParams): Promise<AppClientCompilationResult>;
     /**