Merge branch 'main' into nested-method-call

docs/capabilities/debugging.md

@@ -15,7 +15,7 @@ Config.configure({
 })
 ```
 
-## Debugging Utilities
+## Debugging in `node` environment (recommended)
 
 Refer to the [algokit-utils-ts-debug](https://github.com/algorandfoundation/algokit-utils-ts-debug) for more details on how to activate the addon package with `algokit-utils` in your project.
 
@@ -24,3 +24,13 @@ Refer to the [algokit-utils-ts-debug](https://github.com/algorandfoundation/algo
 ### Why are the debug utilities in a separate package?
 
 To keep the `algokit-utils-ts` package lean and isomporphic, the debugging utilities are located in a separate package. This eliminates various error cases with bundlers (e.g. `webpack`, `esbuild`) when building for the browser.
+
+## Debugging in `browser` environment
+
+Note that it's not possible to use `algokit-utils-ts-debug` in browser environments; however, you can still obtain and persist simulation traces from the browser network tab whenever a transaction is being submitted using the algokit-utils-ts package. Make sure to enable the debug mode in the algokit-utils-ts config as described in the [getting started](./docs/code/getting-started.md) guide. To obtain the simulation trace:
+
+1. Open the browser network tab
+2. Submit the transaction
+3. Filter the requests by `simulate`
+4. Copy the 'simulate' request body and store it in a file with a .trace.avm.json extension, then place it under the `debug_traces` folder in your AlgoKit contract project.
+   4.1. (Optional) If you are not using an AlgoKit project structure for your contracts codebase, as long as the trace file is within your VSCode workspace, the extension will present a picker to select the trace file.

docs/code/README.md

@@ -44,6 +44,7 @@
 - [types/expand](modules/types_expand.md)
 - [types/indexer](modules/types_indexer.md)
 - [types/kmd-account-manager](modules/types_kmd_account_manager.md)
+- [types/lifecycle-events](modules/types_lifecycle_events.md)
 - [types/logging](modules/types_logging.md)
 - [types/logic-error](modules/types_logic_error.md)
 - [types/network-client](modules/types_network_client.md)

docs/code/classes/types_async_event_emitter.AsyncEventEmitter.md

@@ -41,7 +41,7 @@
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:18](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L18)
+[src/types/async-event-emitter.ts:7](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L7)
 
 ___
 
@@ -51,7 +51,7 @@ ___
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:17](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L17)
+[src/types/async-event-emitter.ts:6](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L6)
 
 ___
 
@@ -76,7 +76,7 @@ ___
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:66](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L66)
+[src/types/async-event-emitter.ts:55](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L55)
 
 ## Methods
 
@@ -88,22 +88,22 @@ ___
 
 | Name | Type |
 | :------ | :------ |
-| `K` | extends [`EventType`](../enums/types_async_event_emitter.EventType.md) |
+| `K` | extends [`EventType`](../enums/types_lifecycle_events.EventType.md) |
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `eventName` | `K` |
-| `event` | [`EventDataMap`](../modules/types_async_event_emitter.md#eventdatamap)[`K`] |
+| `event` | [`EventDataMap`](../modules/types_lifecycle_events.md#eventdatamap)[`K`] |
 
 #### Returns
 
 `Promise`\<`void`\>
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:20](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L20)
+[src/types/async-event-emitter.ts:9](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L9)
 
 ▸ **emitAsync**(`eventName`, `event`): `Promise`\<`void`\>
 
@@ -120,7 +120,7 @@ ___
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:21](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L21)
+[src/types/async-event-emitter.ts:10](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L10)
 
 ___
 
@@ -132,22 +132,22 @@ ___
 
 | Name | Type |
 | :------ | :------ |
-| `K` | extends [`EventType`](../enums/types_async_event_emitter.EventType.md) |
+| `K` | extends [`EventType`](../enums/types_lifecycle_events.EventType.md) |
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `eventName` | `K` |
-| `listener` | [`AsyncEventListener`](../modules/types_async_event_emitter.md#asynceventlistener)\<[`EventDataMap`](../modules/types_async_event_emitter.md#eventdatamap)[`K`]\> |
+| `listener` | [`AsyncEventListener`](../modules/types_async_event_emitter.md#asynceventlistener)\<[`EventDataMap`](../modules/types_lifecycle_events.md#eventdatamap)[`K`]\> |
 
 #### Returns
 
 [`AsyncEventEmitter`](types_async_event_emitter.AsyncEventEmitter.md)
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:28](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L28)
+[src/types/async-event-emitter.ts:17](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L17)
 
 ▸ **on**\<`T`\>(`eventName`, `listener`): [`AsyncEventEmitter`](types_async_event_emitter.AsyncEventEmitter.md)
 
@@ -170,7 +170,7 @@ ___
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:29](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L29)
+[src/types/async-event-emitter.ts:18](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L18)
 
 ___
 
@@ -182,22 +182,22 @@ ___
 
 | Name | Type |
 | :------ | :------ |
-| `K` | extends [`EventType`](../enums/types_async_event_emitter.EventType.md) |
+| `K` | extends [`EventType`](../enums/types_lifecycle_events.EventType.md) |
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
 | `eventName` | `K` |
-| `listener` | [`AsyncEventListener`](../modules/types_async_event_emitter.md#asynceventlistener)\<[`EventDataMap`](../modules/types_async_event_emitter.md#eventdatamap)[`K`]\> |
+| `listener` | [`AsyncEventListener`](../modules/types_async_event_emitter.md#asynceventlistener)\<[`EventDataMap`](../modules/types_lifecycle_events.md#eventdatamap)[`K`]\> |
 
 #### Returns
 
 [`AsyncEventEmitter`](types_async_event_emitter.AsyncEventEmitter.md)
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:36](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L36)
+[src/types/async-event-emitter.ts:25](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L25)
 
 ▸ **once**\<`T`\>(`eventName`, `listener`): [`AsyncEventEmitter`](types_async_event_emitter.AsyncEventEmitter.md)
 
@@ -220,7 +220,7 @@ ___
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:37](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L37)
+[src/types/async-event-emitter.ts:26](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L26)
 
 ___
 
@@ -241,4 +241,4 @@ ___
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:50](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L50)
+[src/types/async-event-emitter.ts:39](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L39)

docs/code/enums/types_lifecycle_events.EventType.md

@@ -0,0 +1,32 @@
+[@algorandfoundation/algokit-utils](../README.md) / [types/lifecycle-events](../modules/types_lifecycle_events.md) / EventType
+
+# Enumeration: EventType
+
+[types/lifecycle-events](../modules/types_lifecycle_events.md).EventType
+
+## Table of contents
+
+### Enumeration Members
+
+- [AppCompiled](types_lifecycle_events.EventType.md#appcompiled)
+- [TxnGroupSimulated](types_lifecycle_events.EventType.md#txngroupsimulated)
+
+## Enumeration Members
+
+### AppCompiled
+
+• **AppCompiled** = ``"AppCompiled"``
+
+#### Defined in
+
+[src/types/lifecycle-events.ts:5](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/lifecycle-events.ts#L5)
+
+___
+
+### TxnGroupSimulated
+
+• **TxnGroupSimulated** = ``"TxnGroupSimulated"``
+
+#### Defined in
+
+[src/types/lifecycle-events.ts:4](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/lifecycle-events.ts#L4)

docs/code/modules/index.md

@@ -10,6 +10,8 @@
 - [AVMTracesEventData](index.md#avmtraceseventdata)
 - [AlgorandClient](index.md#algorandclient)
 - [DEFAULT\_MAX\_SEARCH\_DEPTH](index.md#default_max_search_depth)
+- [EventDataMap](index.md#eventdatamap)
+- [EventType](index.md#eventtype)
 - [SOURCES\_DIR](index.md#sources_dir)
 - [TEAL\_FILE\_EXT](index.md#teal_file_ext)
 - [TEAL\_SOURCEMAP\_EXT](index.md#teal_sourcemap_ext)
@@ -158,6 +160,18 @@ Re-exports [DEFAULT_MAX_SEARCH_DEPTH](types_debugging.md#default_max_search_dept
 
 ___
 
+### EventDataMap
+
+Re-exports [EventDataMap](types_lifecycle_events.md#eventdatamap)
+
+___
+
+### EventType
+
+Re-exports [EventType](../enums/types_lifecycle_events.EventType.md)
+
+___
+
 ### SOURCES\_DIR
 
 Re-exports [SOURCES_DIR](types_debugging.md#sources_dir)

docs/code/modules/types_async_event_emitter.md

@@ -4,18 +4,13 @@
 
 ## Table of contents
 
-### Enumerations
-
-- [EventType](../enums/types_async_event_emitter.EventType.md)
-
 ### Classes
 
 - [AsyncEventEmitter](../classes/types_async_event_emitter.AsyncEventEmitter.md)
 
 ### Type Aliases
 
 - [AsyncEventListener](types_async_event_emitter.md#asynceventlistener)
-- [EventDataMap](types_async_event_emitter.md#eventdatamap)
 
 ## Type Aliases
 
@@ -46,25 +41,4 @@
 
 #### Defined in
 
-[src/types/async-event-emitter.ts:14](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L14)
-
-___
-
-### EventDataMap
-
-Ƭ **EventDataMap**: `Object`
-
-#### Index signature
-
-▪ [key: `string`]: `unknown`
-
-#### Type declaration
-
-| Name | Type |
-| :------ | :------ |
-| `AppCompiled` | [`TealSourcesDebugEventData`](../interfaces/types_debugging.TealSourcesDebugEventData.md) |
-| `TxnGroupSimulated` | [`AVMTracesEventData`](../interfaces/types_debugging.AVMTracesEventData.md) |
-
-#### Defined in
-
-[src/types/async-event-emitter.ts:8](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L8)
+[src/types/async-event-emitter.ts:3](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/async-event-emitter.ts#L3)

docs/code/modules/types_debugging.md

@@ -70,7 +70,7 @@ ___
 
 ### TEAL\_SOURCEMAP\_EXT
 
-• `Const` **TEAL\_SOURCEMAP\_EXT**: ``".teal.tok.map"``
+• `Const` **TEAL\_SOURCEMAP\_EXT**: ``".teal.map"``
 
 The file extension for TEAL source map files
 

docs/code/modules/types_lifecycle_events.md

@@ -0,0 +1,34 @@
+[@algorandfoundation/algokit-utils](../README.md) / types/lifecycle-events
+
+# Module: types/lifecycle-events
+
+## Table of contents
+
+### Enumerations
+
+- [EventType](../enums/types_lifecycle_events.EventType.md)
+
+### Type Aliases
+
+- [EventDataMap](types_lifecycle_events.md#eventdatamap)
+
+## Type Aliases
+
+### EventDataMap
+
+Ƭ **EventDataMap**: `Object`
+
+#### Index signature
+
+▪ [key: `string`]: `unknown`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `AppCompiled` | [`TealSourcesDebugEventData`](../interfaces/types_debugging.TealSourcesDebugEventData.md) |
+| `TxnGroupSimulated` | [`AVMTracesEventData`](../interfaces/types_debugging.AVMTracesEventData.md) |
+
+#### Defined in
+
+[src/types/lifecycle-events.ts:8](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/types/lifecycle-events.ts#L8)

docs/v7-migration.md

@@ -147,3 +147,33 @@ If you are converting from an older typed client to a new one you will need to m
 - `extraPages` is no longer nested within a `schema` property, instead it's directly on the method call params as `extraProgramPages`
 - `client.compose()` is now `client.newGroup()`
 - `client.compose()....execute()` is now `client.compose()....send()`
+
+### Optional steps
+
+#### AlgoKit VScode AVM debugger extension utils
+
+If you previously used `Config.configure({ debug: true })` for AVM sourcemaps and TEAL traces, you can now debug `puya` compiler-based sourcemaps. This allows stepping through higher-level Algorand Python constructs instead of raw TEAL.
+
+To incorporate this change and resolve frontend bundler issues, `algokit-utils` is now isomorphic. Node-specific dependencies are split into the `algokit-utils-ts-debug` package.
+
+To migrate:
+
+1. Install the new package:
+
+```bash
+npm i @algorandfoundation/algokit-utils-debug
+```
+
+2. Activate the new package:
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+import { registerDebugEventHandlers } from '@algorandfoundation/algokit-utils-debug'
+
+Config.configure({ debug: true })
+registerDebugEventHandlers()
+```
+
+This approach maintains debug functionality while ensuring compatibility with frontend bundlers.
+
+> For more details on debugging puya based contracts, refer [here](https://github.com/algorandfoundation/algokit-avm-vscode-debugger).

package.json

@@ -39,7 +39,7 @@
     "build:0-clean": "rimraf dist coverage",
     "build:1-compile": "rollup -c --configPlugin typescript",
     "build:3-copy-pkg-json": "npx --yes @makerx/ts-toolkit@latest copy-package-json --custom-sections module main type types exports",
-    "build:4-copy-readme": "cpy README.md dist",
+    "build:4-copy-readme": "cpy README.md LICENSE dist",
     "test": "dotenv -e .env -- jest --coverage --passWithNoTests --silent",
     "lint": "eslint ./src/ --ext .ts",
     "lint:fix": "eslint ./src/ --ext .ts --fix",