@algorandfoundation/algokit-utils 10.0.0-beta.3 → 10.0.0-beta.4

package/app-client.mjs

@@ -1,9 +1,9 @@
 import { getAddress, getApplicationAddress, getOptionalAddress } from "./packages/common/src/address.mjs";
 import { ProgramSourceMap } from "./packages/common/src/sourcemap.mjs";
-import { OnApplicationComplete } from "./packages/transact/src/transactions/app-call.mjs";
+import "./packages/transact/src/transactions/app-call.mjs";
 import { Config } from "./config.mjs";
 import { asJson, binaryStartsWith } from "./util.mjs";
-import { EventType } from "./lifecycle-events.mjs";
+import "./lifecycle-events.mjs";
 import { argTypeIsTransaction, getABIDecodedValue, getABIEncodedValue, getABIMethod } from "./packages/abi/src/abi-method.mjs";
 import { getBoxABIStorageKey, getBoxABIStorageKeys, getBoxABIStorageMap, getGlobalABIStorageKeys, getGlobalABIStorageMaps, getLocalABIStorageKeys, getLocalABIStorageMaps } from "./packages/abi/src/arc56-contract.mjs";
 import { arc32ToArc56 } from "./app-spec.mjs";
@@ -99,14 +99,17 @@ var AppClient = class AppClient {
 		this._boxStateMethods = this.getBoxMethods();
 		this._paramsMethods = {
 			...this.getMethodCallParamsMethods(),
+			/** Get parameters to define bare (raw) transactions to the current app */
 			bare: this.getBareParamsMethods()
 		};
 		this._createTransactionsMethods = {
 			...this.getMethodCallCreateTransactionMethods(),
+			/** Get transactions for bare (raw) calls to the current app */
 			bare: this.getBareCreateTransactionMethods()
 		};
 		this._sendMethods = {
 			...this.getMethodCallSendMethods(),
+			/** Send bare (raw) transactions to the current app */
 			bare: this.getBareSendMethods()
 		};
 	}
@@ -250,8 +253,18 @@ var AppClient = class AppClient {
 	/** Get state (local, global, box) from the current app */
 	get state() {
 		return {
+			/**
+			* Methods to access local state for the current app
+			* @param address The address of the account to get the local state for
+			*/
 			local: this._localStateMethods,
+			/**
+			* Methods to access global state for the current app
+			*/
 			global: this._globalStateMethods,
+			/**
+			* Methods to access box storage for the current app
+			*/
 			box: this._boxStateMethods
 		};
 	}
@@ -532,7 +545,7 @@ var AppClient = class AppClient {
 		});
 		const clearTemplate = Buffer.from(appSpec.source.clear, "base64").toString("utf-8");
 		const compiledClear = await appManager.compileTealTemplate(clearTemplate, deployTimeParams);
-		if (Config.debug) await Config.events.emitAsync(EventType.AppCompiled, { sources: [{
+		if (Config.debug) await Config.events.emitAsync("AppCompiled", { sources: [{
 			compiledTeal: compiledApproval,
 			appName: appSpec.name,
 			fileName: "approval"
@@ -604,46 +617,58 @@ var AppClient = class AppClient {
 	}
 	getBareParamsMethods() {
 		return {
+			/** Return params for an update call, including deploy-time TEAL template replacements and compilation if provided */
 			update: async (params) => {
 				return this.getBareParams({
 					...params,
 					...await this.compile(params)
-				}, OnApplicationComplete.UpdateApplication);
+				}, 4);
 			},
+			/** Return params for an opt-in call */
 			optIn: (params) => {
-				return this.getBareParams(params, OnApplicationComplete.OptIn);
+				return this.getBareParams(params, 1);
 			},
+			/** Return params for a delete call */
 			delete: (params) => {
-				return this.getBareParams(params, OnApplicationComplete.DeleteApplication);
+				return this.getBareParams(params, 5);
 			},
+			/** Return params for a clear state call */
 			clearState: (params) => {
-				return this.getBareParams(params, OnApplicationComplete.ClearState);
+				return this.getBareParams(params, 3);
 			},
+			/** Return params for a close out call */
 			closeOut: (params) => {
-				return this.getBareParams(params, OnApplicationComplete.CloseOut);
+				return this.getBareParams(params, 2);
 			},
+			/** Return params for a call (defaults to no-op) */
 			call: (params) => {
-				return this.getBareParams(params, params?.onComplete ?? OnApplicationComplete.NoOp);
+				return this.getBareParams(params, params?.onComplete ?? 0);
 			}
 		};
 	}
 	getBareCreateTransactionMethods() {
 		return {
+			/** Returns a transaction for an update call, including deploy-time TEAL template replacements and compilation if provided */
 			update: async (params) => {
 				return this._algorand.createTransaction.appUpdate(await this.params.bare.update(params));
 			},
+			/** Returns a transaction for an opt-in call */
 			optIn: (params) => {
 				return this._algorand.createTransaction.appCall(this.params.bare.optIn(params));
 			},
+			/** Returns a transaction for a delete call */
 			delete: (params) => {
 				return this._algorand.createTransaction.appDelete(this.params.bare.delete(params));
 			},
+			/** Returns a transaction for a clear state call */
 			clearState: (params) => {
 				return this._algorand.createTransaction.appCall(this.params.bare.clearState(params));
 			},
+			/** Returns a transaction for a close out call */
 			closeOut: (params) => {
 				return this._algorand.createTransaction.appCall(this.params.bare.closeOut(params));
 			},
+			/** Returns a transaction for a call (defaults to no-op) */
 			call: (params) => {
 				return this._algorand.createTransaction.appCall(this.params.bare.call(params));
 			}
@@ -651,6 +676,7 @@ var AppClient = class AppClient {
 	}
 	getBareSendMethods() {
 		return {
+			/** Signs and sends an update call, including deploy-time TEAL template replacements and compilation if provided */
 			update: async (params) => {
 				const compiled = await this.compile(params);
 				return {
@@ -658,18 +684,23 @@ var AppClient = class AppClient {
 					...compiled
 				};
 			},
+			/** Signs and sends an opt-in call */
 			optIn: (params) => {
 				return this._algorand.send.appCall(this.params.bare.optIn(params));
 			},
+			/** Signs and sends a delete call */
 			delete: (params) => {
 				return this._algorand.send.appDelete(this.params.bare.delete(params));
 			},
+			/** Signs and sends a clear state call */
 			clearState: (params) => {
 				return this._algorand.send.appCall(this.params.bare.clearState(params));
 			},
+			/** Signs and sends a close out call */
 			closeOut: (params) => {
 				return this._algorand.send.appCall(this.params.bare.closeOut(params));
 			},
+			/** Signs and sends a call (defaults to no-op) */
 			call: (params) => {
 				return this._algorand.send.appCall(this.params.bare.call(params));
 			}
@@ -677,6 +708,11 @@ var AppClient = class AppClient {
 	}
 	getMethodCallParamsMethods() {
 		return {
+			/**
+			* 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,
@@ -685,31 +721,63 @@ var AppClient = class AppClient {
 					receiver: this.appAddress
 				};
 			},
+			/**
+			* 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.UpdateApplication);
+				}, 4);
 			},
+			/**
+			* 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.OptIn);
+				return await this.getABIParams(params, 1);
 			},
+			/**
+			* 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.DeleteApplication);
+				return await this.getABIParams(params, 5);
 			},
+			/** 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.CloseOut);
+				return await this.getABIParams(params, 2);
 			},
+			/** 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.NoOp);
+				return await this.getABIParams(params, params.onComplete ?? 0);
 			}
 		};
 	}
 	getMethodCallSendMethods() {
 		return {
+			/** 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);
 				return {
@@ -717,17 +785,37 @@ var AppClient = class AppClient {
 					...compiled
 				};
 			},
+			/**
+			* 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: async (params) => {
 				return this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.optIn(params)));
 			},
+			/**
+			* 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: async (params) => {
 				return this.processMethodCallReturn(this._algorand.send.appDeleteMethodCall(await this.params.delete(params)));
 			},
+			/**
+			* 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: async (params) => {
 				return this.processMethodCallReturn(this._algorand.send.appCallMethodCall(await this.params.closeOut(params)));
 			},
+			/**
+			* 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) => {
-				if ((params.onComplete === OnApplicationComplete.NoOp || !params.onComplete) && getABIMethod(params.method, this._appSpec).readonly) {
+				if ((params.onComplete === 0 || !params.onComplete) && getABIMethod(params.method, this._appSpec).readonly) {
 					const readonlyParams = { ...params };
 					if (params.coverAppCallInnerTransactionFees && params.maxFee) {
 						readonlyParams.staticFee = params.maxFee;
@@ -757,21 +845,50 @@ var AppClient = class AppClient {
 	}
 	getMethodCallCreateTransactionMethods() {
 		return {
+			/** 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));
 			}
@@ -839,14 +956,29 @@ var AppClient = class AppClient {
 	getBoxMethods() {
 		const that = this;
 		const stateMethods = {
+			/**
+			* Returns all single-key state values in a record keyed by the key name and the value a decoded ABI value.
+			*/
 			getAll: async () => {
 				return Object.fromEntries(await Promise.all(Object.keys(that._appSpec.state.keys.box).map(async (key) => [key, await stateMethods.getValue(key)])));
 			},
+			/**
+			* Returns a single state value for the current app with the value a decoded ABI value.
+			* @param name The name of the state value to retrieve the value for
+			* @returns
+			*/
 			getValue: async (name) => {
 				const metadata = getBoxABIStorageKey(that._appSpec, name);
 				const value = await that.getBoxValue(Buffer.from(metadata.key, "base64"));
 				return getABIDecodedValue(metadata.valueType, value);
 			},
+			/**
+			*
+			* @param mapName The name of the map to read from
+			* @param key The key within the map (without any map prefix) as either a Buffer with the bytes or a value
+			*  that will be converted to bytes by encoding it using the specified ABI key type
+			*  in the ARC-56 spec
+			*/
 			getMapValue: async (mapName, key) => {
 				const metadata = getBoxABIStorageMap(that._appSpec, mapName);
 				const prefix = Buffer.from(metadata.prefix ?? "", "base64");
@@ -855,6 +987,10 @@ var AppClient = class AppClient {
 				const value = await that.getBoxValue(Buffer.from(base64Key, "base64"));
 				return getABIDecodedValue(metadata.valueType, value);
 			},
+			/**
+			* Returns all map values for the given map from box storage.
+			* @param mapName The name of the map to read from
+			*/
 			getMap: async (mapName) => {
 				const metadata = getBoxABIStorageMap(that._appSpec, mapName);
 				const prefix = Buffer.from(metadata.prefix ?? "", "base64");
@@ -868,10 +1004,19 @@ var AppClient = class AppClient {
 	}
 	getStateMethods(stateGetter, keyGetter, mapGetter) {
 		const stateMethods = {
+			/**
+			* Returns all single-key state values in a record keyed by the key name and the value a decoded ABI value.
+			*/
 			getAll: async () => {
 				const appState = await stateGetter();
 				return Object.fromEntries(await Promise.all(Object.keys(keyGetter()).map(async (key) => [key, await stateMethods.getValue(key, appState)])));
 			},
+			/**
+			* Returns a single state value for the current app with the value a decoded ABI value.
+			* @param name The name of the state value to retrieve the value for
+			* @param appState Optional cached value of the current state
+			* @returns
+			*/
 			getValue: async (name, appState) => {
 				const state = Object.values(appState ?? await stateGetter());
 				const metadata = keyGetter()[name];
@@ -880,6 +1025,14 @@ var AppClient = class AppClient {
 				if (value && "valueRaw" in value) return getABIDecodedValue(metadata.valueType, value.valueRaw);
 				return value?.value;
 			},
+			/**
+			* Returns a single value from the given map for the current app with the value a decoded ABI value.
+			* @param mapName The name of the map to read from
+			* @param key The key within the map (without any map prefix) as either a Buffer with the bytes or a value
+			*  that will be converted to bytes by encoding it using the specified ABI key type
+			*  in the ARC-56 spec
+			* @param appState Optional cached value of the current state
+			*/
 			getMapValue: async (mapName, key, appState) => {
 				const state = Object.values(appState ?? await stateGetter());
 				const metadata = mapGetter()[mapName];
@@ -890,6 +1043,11 @@ var AppClient = class AppClient {
 				if (value && "valueRaw" in value) return getABIDecodedValue(metadata.valueType, value.valueRaw);
 				return value?.value;
 			},
+			/**
+			* Returns all map values for the given map.
+			* @param mapName The name of the map to read from
+			* @returns A map of all key-value pairs in the map as a `Record<string, ABIValue>`
+			*/
 			getMap: async (mapName) => {
 				const state = Object.values(await stateGetter());
 				const metadata = mapGetter()[mapName];