Merge main into release

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## Proposed Changes
+
+-
+-
+-

.github/workflows/issue_labelled.yml

@@ -1,4 +1,4 @@
-name: Create Zendesk ticket when an issue is labelled with makerx 
+name: Create Zendesk ticket when an issue is labelled with makerx
 on:
   issues:
     types: [labeled]

.prettierignore

@@ -10,3 +10,7 @@ coverage
 **/generated/types.ts
 # don't format ide files
 .idea
+# don't format auto generated code docs
+docs/code
+# don't format test contract artifacts
+tests/example-contracts/**/*.json

.vscode/settings.json

@@ -6,10 +6,6 @@
     "source.organizeImports": true
   },
   "jest.jestCommandLine": "npm run test --",
-  "jest.autoRun": {
-    "watch": false,
-    "onSave": "test-file",
-    "onStartup": ["all-tests"]
-  },
+  "jest.autoRun": {},
   "dotenv.enableAutocloaking": false
 }

docs/capabilities/dispenser-client.md

@@ -0,0 +1,57 @@
+# TestNet Dispenser Client
+
+The TestNet Dispenser Client is a utility for interacting with the AlgoKit TestNet Dispenser API. It provides methods to fund an account, register a refund for a transaction, and get the current limit for an account.
+
+## Creating a Dispenser Client
+
+To create a Dispenser Client, you need to provide an authorization token. This can be done in two ways:
+
+1. Pass the token directly to the client constructor as `authToken`.
+2. Set the token as an environment variable `ALGOKIT_DISPENSER_ACCESS_TOKEN` (see [docs](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md#error-handling) on how to obtain the token).
+
+If both methods are used, the constructor argument takes precedence.
+
+```ts
+import * as algokit from '@algorandfoundation/algokit-utils'
+
+// Using constructor argument
+const client = algokit.getTestNetDispenserApiClient({ authToken: 'your_auth_token' })
+
+// Using environment variable
+process.env['ALGOKIT_DISPENSER_ACCESS_TOKEN'] = 'your_auth_token'
+const client = algokit.getTestNetDispenserApiClient()
+```
+
+## Funding an Account
+
+To fund an account with Algos from the dispenser API, use the `fund` method. This method requires the receiver's address, the amount to be funded, and the asset ID.
+
+```ts
+const response = await client.fund('receiver_address', 1000)
+```
+
+The `fund` method returns a `DispenserFundResponse` object, which contains the transaction ID (`txId`) and the amount funded.
+
+## Registering a Refund
+
+To register a refund for a transaction with the dispenser API, use the `refund` method. This method requires the transaction ID of the refund transaction.
+
+```ts
+await client.refund('transaction_id')
+```
+
+> Keep in mind, to perform a refund you need to perform a payment transaction yourself first by sending funds back to TestNet Dispenser, then you can invoke this refund endpoint and pass the txn_id of your refund txn. You can obtain dispenser address by inspecting the sender field of any issued fund transaction initiated via [fund](#funding-an-account).
+
+## Getting Current Limit
+
+To get the current limit for an account with Algos from the dispenser API, use the `getLimit` method. This method requires the account address.
+
+```ts
+const response = await client.getLimit()
+```
+
+The `limit` method returns a `DispenserLimitResponse` object, which contains the current limit amount.
+
+## Error Handling
+
+If an error occurs while making a request to the dispenser API, an exception will be raised with a message indicating the type of error. Refer to [Error Handling docs](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md#error-handling) for details on how you can handle each individual error `code`.

docs/capabilities/transfer.md

@@ -17,18 +17,17 @@ The key function to facilitate Algo transfers is `algokit.transferAlgos(transfer
 
 ## `ensureFunded`
 
-The ability to automatically fund an account to have a minimum amount of disposable ALGOs to spend is incredibly useful for automation and deployment scripts. The function to facilitate this is `algokit.ensureFunded(funding, algod, kmd?)`, which returns a [`SendTransactionResult`](./transaction.md#sendtransactionresult) (or undefined if it didn't need to send a transaction) and takes a [`EnsureFundedParams`](../code/interfaces/types_transfer.EnsureFundedParams.md):
+The `ensureFunded` function automatically funds an account to maintain a minimum amount of disposable ALGOs. This is particularly useful for automation and deployment scripts. The function is defined as `algokit.ensureFunded(funding, algod, kmd?)` and returns a [`EnsureFundedReturnType`](../code/interfaces/types_transfer.EnsureFundedReturnType.md) if a transaction was needed, or `undefined` if no transaction was required. The function takes a [`EnsureFundedParams`](../code/interfaces/types_transfer.EnsureFundedParams.md) object as an argument:
 
 - All properties in [`SendTransactionParams`](./transaction.md#sendtransactionparams)
 - `accountToFund: SendTransactionFrom | string` - The account that is to be funded
-- `fundingSource?: SendTransactionFrom` - The account that is the source of funds, if not specified then it will use the [dispenser](./account.md#dispenser)
-- `minSpendingBalance: AlgoAmount` - The minimum balance of ALGOs that the account should have available to spend (i.e. on top of minimum balance requirement)
-- `minFundingIncrement?: AlgoAmount` - When issuing a funding amount, the minimum amount to transfer (avoids many small transfers if this gets called often on an active account)
-- `amount: AlgoAmount` - The [amount](./amount.md) of ALGOs to send
+- `fundingSource?: SendTransactionFrom | TestNetDispenserApiClient` - The account that is the source of funds or a dispenser API client. If not specified, it will use the [dispenser](./account.md#dispenser)
+- `minSpendingBalance: AlgoAmount` - The minimum balance of ALGOs that the account should have available to spend (i.e., on top of the minimum balance requirement)
+- `minFundingIncrement?: AlgoAmount` - When issuing a funding amount, the minimum amount to transfer. This avoids many small transfers if this function gets called often on an active account
 - `transactionParams?: SuggestedParams` - The optional [transaction parameters](./transaction.md#transaction-params)
 - `note?: TransactionNote` - The [transaction note](./transaction.md#transaction-notes)
 
-The function calls Algod to find the current balance and minimum balance requirement, gets the difference between those two numbers and checks to see if it's more than the `minSpendingBalance` and if so then it will send the difference, or the `minFundingIncrement` if that is specified.
+The function calls Algod to find the current balance and minimum balance requirement, calculates the difference between those two numbers, and checks to see if it's more than the `minSpendingBalance`. If so, it will send the difference, or the `minFundingIncrement` if that is specified. If the `fundingSource` is an instance of `TestNetDispenserApiClient`, the function will use the dispenser API to fund the account. Refer to [algokit-cli documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/dispenser.md#ci-access-token) for details on obtaining an access token for AlgoKit TestNet Dispenser API.
 
 ## `transferAsset`
 
@@ -48,3 +47,5 @@ The key function to facilitate asset transfers is `transferAsset(transfer, algod
 If you want to programmtically send funds then you will often need a "dispenser" account that has a store of ALGOs that can be sent and a private key available for that dispenser account.
 
 There is a standard AlgoKit Utils function to get access to a [dispenser account](./account.md#accounts): [`algokit.getDispenserAccount(algod, kmd?)`](../code/modules/index.md#getdispenseraccount). When running against [LocalNet](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/localnet.md), the dispenser account can be automatically determined using the [Kmd API](https://developer.algorand.org/docs/rest-apis/kmd). When running against other networks like TestNet or MainNet the mnemonic (and optionally sender address if it's been rekeyed) of the dispenser account can be provided via environment variables (`process.env.DISPENSER_MNEMONIC` and optionally `process.env.DISPENSER_SENDER` if rekeyed).
+
+> Please note that this does not refer to the [AlgoKit TestNet Dispenser API](./dispenser-client.md) which is a separate abstraction that can be used to fund accounts on TestNet via dedicated API service.

docs/code/README.md

@@ -17,6 +17,8 @@
 - [types/app-client.spec](modules/types_app_client_spec.md)
 - [types/app-spec](modules/types_app_spec.md)
 - [types/config](modules/types_config.md)
+- [types/dispenser-client](modules/types_dispenser_client.md)
+- [types/dispenser-client.spec](modules/types_dispenser_client_spec.md)
 - [types/indexer](modules/types_indexer.md)
 - [types/logging](modules/types_logging.md)
 - [types/logic-error](modules/types_logic_error.md)

docs/code/classes/types_dispenser_client.TestNetDispenserApiClient.md

@@ -0,0 +1,221 @@
+[@algorandfoundation/algokit-utils](../README.md) / [types/dispenser-client](../modules/types_dispenser_client.md) / TestNetDispenserApiClient
+
+# Class: TestNetDispenserApiClient
+
+[types/dispenser-client](../modules/types_dispenser_client.md).TestNetDispenserApiClient
+
+`TestNetDispenserApiClient` is a class that provides methods to interact with the [Algorand TestNet Dispenser API](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md).
+It allows you to fund an address with Algos, refund a transaction, and get the funding limit for the Algo asset.
+
+The class requires an authentication token and a request timeout to be initialized. The authentication token can be provided
+either directly as a parameter or through an `ALGOKIT_DISPENSER_ACCESS_TOKEN` environment variable. If neither is provided, an error is thrown.
+
+The request timeout can be provided as a parameter. If not provided, a default value is used.
+
+**`Method`**
+
+fund - Sends a funding request to the dispenser API to fund the specified address with the given amount of Algo.
+
+**`Method`**
+
+refund - Sends a refund request to the dispenser API for the specified refundTxnId.
+
+**`Method`**
+
+limit - Sends a request to the dispenser API to get the funding limit for the Algo asset.
+
+**`Example`**
+
+```typescript
+const client = new TestNetDispenserApiClient({ authToken: 'your_auth_token', requestTimeout: 30 });
+const fundResponse = await client.fund('your_address', 100);
+const limitResponse = await client.getLimit();
+await client.refund('your_transaction_id');
+```
+
+**`Throws`**
+
+If neither the environment variable 'ALGOKIT_DISPENSER_ACCESS_TOKEN' nor the authToken parameter were provided.
+
+## Table of contents
+
+### Constructors
+
+- [constructor](types_dispenser_client.TestNetDispenserApiClient.md#constructor)
+
+### Properties
+
+- [\_authToken](types_dispenser_client.TestNetDispenserApiClient.md#_authtoken)
+- [\_requestTimeout](types_dispenser_client.TestNetDispenserApiClient.md#_requesttimeout)
+
+### Accessors
+
+- [authToken](types_dispenser_client.TestNetDispenserApiClient.md#authtoken)
+- [requestTimeout](types_dispenser_client.TestNetDispenserApiClient.md#requesttimeout)
+
+### Methods
+
+- [fund](types_dispenser_client.TestNetDispenserApiClient.md#fund)
+- [getLimit](types_dispenser_client.TestNetDispenserApiClient.md#getlimit)
+- [processDispenserRequest](types_dispenser_client.TestNetDispenserApiClient.md#processdispenserrequest)
+- [refund](types_dispenser_client.TestNetDispenserApiClient.md#refund)
+
+## Constructors
+
+### constructor
+
+• **new TestNetDispenserApiClient**(`params`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `params` | ``null`` \| [`TestNetDispenserApiClientParams`](../interfaces/types_dispenser_client.TestNetDispenserApiClientParams.md) |
+
+#### Defined in
+
+[src/types/dispenser-client.ts:63](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L63)
+
+## Properties
+
+### \_authToken
+
+• `Private` **\_authToken**: `string`
+
+#### Defined in
+
+[src/types/dispenser-client.ts:60](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L60)
+
+___
+
+### \_requestTimeout
+
+• `Private` **\_requestTimeout**: `number`
+
+#### Defined in
+
+[src/types/dispenser-client.ts:61](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L61)
+
+## Accessors
+
+### authToken
+
+• `get` **authToken**(): `string`
+
+The authentication token used for API requests.
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[src/types/dispenser-client.ts:79](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L79)
+
+___
+
+### requestTimeout
+
+• `get` **requestTimeout**(): `number`
+
+The timeout for API requests, in seconds.
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[src/types/dispenser-client.ts:83](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L83)
+
+## Methods
+
+### fund
+
+▸ **fund**(`address`, `amount`): `Promise`<[`DispenserFundResponse`](../interfaces/types_dispenser_client.DispenserFundResponse.md)\>
+
+Sends a funding request to the dispenser API to fund the specified address with the given amount of Algo.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `address` | `string` | The address to fund. |
+| `amount` | `number` | The amount of Algo to fund. |
+
+#### Returns
+
+`Promise`<[`DispenserFundResponse`](../interfaces/types_dispenser_client.DispenserFundResponse.md)\>
+
+DispenserFundResponse: An object containing the transaction ID and funded amount.
+
+#### Defined in
+
+[src/types/dispenser-client.ts:144](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L144)
+
+___
+
+### getLimit
+
+▸ **getLimit**(): `Promise`<[`DispenserLimitResponse`](../interfaces/types_dispenser_client.DispenserLimitResponse.md)\>
+
+Sends a request to the dispenser API to get the funding limit for the Algo asset.
+
+#### Returns
+
+`Promise`<[`DispenserLimitResponse`](../interfaces/types_dispenser_client.DispenserLimitResponse.md)\>
+
+DispenserLimitResponse: An object containing the funding limit amount.
+
+#### Defined in
+
+[src/types/dispenser-client.ts:170](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L170)
+
+___
+
+### processDispenserRequest
+
+▸ `Private` **processDispenserRequest**(`authToken`, `urlSuffix`, `body?`, `method?`): `Promise`<`Response`\>
+
+Processes a dispenser API request.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `authToken` | `string` | `undefined` | The authentication token. |
+| `urlSuffix` | `string` | `undefined` | The URL suffix for the API request. |
+| `body` | ``null`` \| `Record`<`string`, `string` \| `number`\> | `null` | The request body. |
+| `method` | `string` | `'POST'` | The HTTP method. |
+
+#### Returns
+
+`Promise`<`Response`\>
+
+The API response.
+
+#### Defined in
+
+[src/types/dispenser-client.ts:97](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L97)
+
+___
+
+### refund
+
+▸ **refund**(`refundTxnId`): `Promise`<`void`\>
+
+Sends a refund request to the dispenser API for the specified refundTxnId.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `refundTxnId` | `string` | The transaction ID to refund. |
+
+#### Returns
+
+`Promise`<`void`\>
+
+#### Defined in
+
+[src/types/dispenser-client.ts:161](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L161)

docs/code/interfaces/types_dispenser_client.DispenserFundResponse.md

@@ -0,0 +1,32 @@
+[@algorandfoundation/algokit-utils](../README.md) / [types/dispenser-client](../modules/types_dispenser_client.md) / DispenserFundResponse
+
+# Interface: DispenserFundResponse
+
+[types/dispenser-client](../modules/types_dispenser_client.md).DispenserFundResponse
+
+## Table of contents
+
+### Properties
+
+- [amount](types_dispenser_client.DispenserFundResponse.md#amount)
+- [txId](types_dispenser_client.DispenserFundResponse.md#txid)
+
+## Properties
+
+### amount
+
+• **amount**: `number`
+
+#### Defined in
+
+[src/types/dispenser-client.ts:21](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L21)
+
+___
+
+### txId
+
+• **txId**: `string`
+
+#### Defined in
+
+[src/types/dispenser-client.ts:20](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/dispenser-client.ts#L20)