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

package/types/client-manager.d.ts

@@ -60,13 +60,27 @@ export declare class ClientManager {
      * ```
      */
     constructor(clientsOrConfig: AlgoConfig | AlgoSdkClients, algorandClient?: AlgorandClientInterface);
-    /** Returns an algosdk Algod API client. */
+    /**
+     * Returns an algosdk Algod API client.
+     * @returns The Algod client
+     */
     get algod(): algosdk.Algodv2;
-    /** Returns an algosdk Indexer API client or throws an error if it's not been provided. */
+    /**
+     * Returns an algosdk Indexer API client or throws an error if it's not been provided.
+     * @returns The Indexer client
+     * @throws Error if no Indexer client is configured
+     */
     get indexer(): algosdk.Indexer;
-    /** Returns an algosdk Indexer API client or `undefined` if it's not been provided. */
+    /**
+     * Returns an algosdk Indexer API client or `undefined` if it's not been provided.
+     * @returns The Indexer client or `undefined`
+     */
     get indexerIfPresent(): algosdk.Indexer | undefined;
-    /** Returns an algosdk KMD API client or throws an error if it's not been provided. */
+    /**
+     * Returns an algosdk KMD API client or throws an error if it's not been provided.
+     * @returns The KMD client
+     * @throws Error if no KMD client is configured
+     */
     get kmd(): algosdk.Kmd;
     private _getNetworkPromise;
     /**
@@ -83,21 +97,37 @@ export declare class ClientManager {
      * Returns true if the given network genesisId is associated with a LocalNet network.
      * @param genesisId The network genesis ID
      * @returns Whether the given genesis ID is associated with a LocalNet network
+     * @example
+     * ```typescript
+     * const isLocalNet = ClientManager.genesisIdIsLocalNet('testnet-v1.0')
+     * ```
      */
     static genesisIdIsLocalNet(genesisId: string): boolean;
     /**
      * Returns true if the current network is LocalNet.
      * @returns True if the current network is LocalNet.
+     * @example
+     * ```typescript
+     * const isLocalNet = await clientManager.isLocalNet()
+     * ```
      */
     isLocalNet(): Promise<boolean>;
     /**
      * Returns true if the current network is TestNet.
      * @returns True if the current network is TestNet.
+     * @example
+     * ```typescript
+     * const isTestNet = await clientManager.isTestNet()
+     * ```
      */
     isTestNet(): Promise<boolean>;
     /**
      * Returns true if the current network is MainNet.
      * @returns True if the current network is MainNet.
+     * @example
+     * ```typescript
+     * const isMainNet = await clientManager.isMainNet()
+     * ```
      */
     isMainNet(): Promise<boolean>;
     /**
@@ -135,15 +165,16 @@ export declare class ClientManager {
     getTestNetDispenserFromEnvironment(params?: Omit<TestNetDispenserApiClientParams, 'authToken'>): TestNetDispenserApiClient;
     /**
      * Returns a new `AppFactory` client
+     * @param params The parameters to create the app factory
      * @example Basic example
      * ```typescript
-     * const factory = algorand.client.getAppFactory({
+     * const factory = clientManager.getAppFactory({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\/}',
      * })
      * ```
      * @example Advanced example
      * ```typescript
-     * const factory = algorand.client.getAppFactory({
+     * const factory = clientManager.getAppFactory({
      *   appSpec: parsedAppSpec_AppSpec_or_Arc56Contract,
      *   defaultSender: "SENDERADDRESS",
      *   appName: "OverriddenAppName",
@@ -153,6 +184,7 @@ export declare class ClientManager {
      *   deployTimeParams: { ONE: 1, TWO: 'value' }
      * })
      * ```
+     * @returns The `AppFactory` instance
      */
     getAppFactory(params: ClientAppFactoryParams): AppFactory;
     /**
@@ -162,13 +194,13 @@ export declare class ClientManager {
      * @param params The parameters to create the app client
      * @example Basic
      * ```typescript
-     * const appClient = algorand.client.getAppClientByCreatorAndName({
+     * const appClient = clientManager.getAppClientByCreatorAndName({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
      *   // appId resolved by looking for app ID of named app by this creator
      *   creatorAddress: 'CREATORADDRESS',
      * })
      * ```
-     * @returns The `AppClient`
+     * @returns The `AppClient` instance
      */
     getAppClientByCreatorAndName(params: ClientResolveAppClientByCreatorAndNameParams): Promise<AppClient>;
     /**
@@ -176,12 +208,12 @@ export declare class ClientManager {
      * @param params The parameters to create the app client
      * @example Basic
      * ```typescript
-     * const appClient = algorand.client.getAppClientById({
+     * const appClient = clientManager.getAppClientById({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
      *   appId: 12345n,
      * })
      * ```
-     * @returns The `AppClient`
+     * @returns The `AppClient` instance
      */
     getAppClientById(params: ClientAppClientParams): AppClient;
     /**
@@ -193,12 +225,12 @@ export declare class ClientManager {
      * @param params The parameters to create the app client
      * @example Basic
      * ```typescript
-     * const appClient = algorand.client.getAppClientByNetwork({
+     * const appClient = clientManager.getAppClientByNetwork({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
      *   // appId resolved by using ARC-56 spec to find app ID for current network
      * })
      * ```
-     * @returns The `AppClient`
+     * @returns The `AppClient` instance
      */
     getAppClientByNetwork(params: ClientAppClientByNetworkParams): Promise<AppClient>;
     /**
@@ -207,14 +239,14 @@ export declare class ClientManager {
      * @param params The params to resolve the app by creator address and name
      * @example Use name in ARC-32 / ARC-56 app spec
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientByCreatorAndName(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientByCreatorAndName(MyContractClient, {
      *   creatorAddress: "CREATORADDRESS",
      *   defaultSender: alice,
      * })
      * ```
      * @example Specify name
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientByCreatorAndName(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientByCreatorAndName(MyContractClient, {
      *   creatorAddress: "CREATORADDRESS",
      *   name: "contract-name",
      *   defaultSender: alice,
@@ -229,7 +261,7 @@ export declare class ClientManager {
      * @param params The params to resolve the app by ID
      * @example
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientById(MyContractClient, {
      *   appId: 12345n,
      *   defaultSender: alice,
      * })
@@ -246,7 +278,7 @@ export declare class ClientManager {
      * @param params The params to resolve the app by network
      * @example
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientByNetwork(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientByNetwork(MyContractClient, {
      *   defaultSender: alice,
      * })
      * ```
@@ -259,7 +291,7 @@ export declare class ClientManager {
      * @param params The params to resolve the factory by
      * @example
      * ```typescript
-     * const appFactory = algorand.client.getTypedAppFactory(MyContractClient, {
+     * const appFactory = clientManager.getTypedAppFactory(MyContractClient, {
      *   sender: alice,
      * })
      * ```
@@ -284,32 +316,56 @@ export declare class ClientManager {
      * @returns The config for algod, indexer and kmd
      */
     static getConfigFromEnvironmentOrLocalNet(): AlgoConfig;
-    /** Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment)
+    /**
+     * Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment)
      *
      * Expects `process.env.ALGOD_SERVER` to be defined, and you can also specify `process.env.ALGOD_PORT` and `process.env.ALGOD_TOKEN`.
+     * @returns The Algod client configuration
+     * @throws Error if `process.env.ALGOD_SERVER` is not defined
+     * @example
+     * ```typescript
+     * const config = ClientManager.getAlgodConfigFromEnvironment()
+     * ```
      */
     static getAlgodConfigFromEnvironment(): AlgoClientConfig;
     /**
      * Retrieve the indexer configuration from environment variables (expects to be called from a Node.js environment).
      *
      * Expects `process.env.INDEXER_SERVER` to be defined, and you can also specify `process.env.INDEXER_PORT` and `process.env.INDEXER_TOKEN`.
+     * @returns The Indexer client configuration
+     * @throws Error if `process.env.INDEXER_SERVER` is not defined
+     * @example
+     * ```typescript
+     * const config = ClientManager.getIndexerConfigFromEnvironment()
+     * ```
      */
     static getIndexerConfigFromEnvironment(): AlgoClientConfig;
     /** Returns the Algorand configuration to point to the free tier of the AlgoNode service.
      *
      * @param network Which network to connect to - TestNet or MainNet
      * @param config Which algod config to return - Algod or Indexer
+     * @returns The AlgoNode client configuration
+     * @example
+     * ```typescript
+     * const config = ClientManager.getAlgoNodeConfig('testnet', 'algod')
+     * ```
      */
     static getAlgoNodeConfig(network: 'testnet' | 'mainnet', config: 'algod' | 'indexer'): AlgoClientConfig;
     /** Returns the Algorand configuration to point to the default LocalNet.
      *
      * @param configOrPort Which algod config to return - algod, kmd, or indexer OR a port number
+     * @returns The LocalNet client configuration
+     * @example
+     * ```typescript
+     * const config = ClientManager.getDefaultLocalNetConfig('algod')
+     * ```
      */
     static getDefaultLocalNetConfig(configOrPort: 'algod' | 'indexer' | 'kmd' | number): AlgoClientConfig;
     /**
      * Returns an algod SDK client that automatically retries on idempotent calls.
      *
      * @param config The config of the client
+     * @returns The Algod client
      * @example AlgoNode (testnet)
      * ```typescript
      *  const algod = ClientManager.getAlgodClient(ClientManager.getAlgoNodeConfig('testnet', 'algod'))
@@ -330,6 +386,7 @@ export declare class ClientManager {
     /**
      * Returns an algod SDK client that automatically retries on idempotent calls loaded from environment variables (expects to be called from a Node.js environment).
      *
+     * @returns The Algod client
      * @example
      *  ```typescript
      *  // Uses process.env.ALGOD_SERVER, process.env.ALGOD_PORT and process.env.ALGOD_TOKEN
@@ -342,6 +399,7 @@ export declare class ClientManager {
      * Returns an indexer SDK client that automatically retries on idempotent calls
      *
      * @param config The config of the client
+     * @returns The Indexer client
      * @example AlgoNode (testnet)
      * ```typescript
      *  const indexer = ClientManager.getIndexerClient(ClientManager.getAlgoNodeConfig('testnet', 'indexer'))
@@ -362,6 +420,7 @@ export declare class ClientManager {
     /**
      * Returns an indexer SDK client that automatically retries on idempotent calls loaded from environment variables (expects to be called from a Node.js environment).
      *
+     * @returns The Indexer client
      * @example
      *
      *  ```typescript
@@ -377,6 +436,7 @@ export declare class ClientManager {
      * KMD client allows you to export private keys, which is useful to (for instance) get the default account in a LocalNet network.
      *
      * @param config The config for the client
+     * @returns The KMD client
      * @example Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)
      * ```typescript
      *  const kmd = ClientManager.getKmdClient({server: 'http://localhost', port: '4002', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
@@ -386,6 +446,7 @@ export declare class ClientManager {
     /**
      * Returns a KMD SDK client that automatically retries on idempotent calls loaded from environment variables (expects to be called from a Node.js environment).
      *
+     * @returns The KMD client
      * @example
      *  ```typescript
      *  // Uses process.env.ALGOD_SERVER, process.env.KMD_PORT (or if not specified: port 4002) and process.env.ALGOD_TOKEN

package/types/client-manager.js

@@ -44,21 +44,35 @@ class ClientManager {
         this._kmd = _clients.kmd;
         this._algorand = algorandClient;
     }
-    /** Returns an algosdk Algod API client. */
+    /**
+     * Returns an algosdk Algod API client.
+     * @returns The Algod client
+     */
     get algod() {
         return this._algod;
     }
-    /** Returns an algosdk Indexer API client or throws an error if it's not been provided. */
+    /**
+     * Returns an algosdk Indexer API client or throws an error if it's not been provided.
+     * @returns The Indexer client
+     * @throws Error if no Indexer client is configured
+     */
     get indexer() {
         if (!this._indexer)
             throw new Error('Attempt to use Indexer client in AlgoKit instance with no Indexer configured');
         return this._indexer;
     }
-    /** Returns an algosdk Indexer API client or `undefined` if it's not been provided. */
+    /**
+     * Returns an algosdk Indexer API client or `undefined` if it's not been provided.
+     * @returns The Indexer client or `undefined`
+     */
     get indexerIfPresent() {
         return this._indexer;
     }
-    /** Returns an algosdk KMD API client or throws an error if it's not been provided. */
+    /**
+     * Returns an algosdk KMD API client or throws an error if it's not been provided.
+     * @returns The KMD client
+     * @throws Error if no KMD client is configured
+     */
     get kmd() {
         if (!this._kmd)
             throw new Error('Attempt to use Kmd client in AlgoKit instance with no Kmd configured');
@@ -90,6 +104,10 @@ class ClientManager {
      * Returns true if the given network genesisId is associated with a LocalNet network.
      * @param genesisId The network genesis ID
      * @returns Whether the given genesis ID is associated with a LocalNet network
+     * @example
+     * ```typescript
+     * const isLocalNet = ClientManager.genesisIdIsLocalNet('testnet-v1.0')
+     * ```
      */
     static genesisIdIsLocalNet(genesisId) {
         return types_networkClient.genesisIdIsLocalNet(genesisId);
@@ -97,6 +115,10 @@ class ClientManager {
     /**
      * Returns true if the current network is LocalNet.
      * @returns True if the current network is LocalNet.
+     * @example
+     * ```typescript
+     * const isLocalNet = await clientManager.isLocalNet()
+     * ```
      */
     async isLocalNet() {
         return (await this.network()).isLocalNet;
@@ -104,6 +126,10 @@ class ClientManager {
     /**
      * Returns true if the current network is TestNet.
      * @returns True if the current network is TestNet.
+     * @example
+     * ```typescript
+     * const isTestNet = await clientManager.isTestNet()
+     * ```
      */
     async isTestNet() {
         return (await this.network()).isTestNet;
@@ -111,6 +137,10 @@ class ClientManager {
     /**
      * Returns true if the current network is MainNet.
      * @returns True if the current network is MainNet.
+     * @example
+     * ```typescript
+     * const isMainNet = await clientManager.isMainNet()
+     * ```
      */
     async isMainNet() {
         return (await this.network()).isMainNet;
@@ -154,15 +184,16 @@ class ClientManager {
     }
     /**
      * Returns a new `AppFactory` client
+     * @param params The parameters to create the app factory
      * @example Basic example
      * ```typescript
-     * const factory = algorand.client.getAppFactory({
+     * const factory = clientManager.getAppFactory({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\/}',
      * })
      * ```
      * @example Advanced example
      * ```typescript
-     * const factory = algorand.client.getAppFactory({
+     * const factory = clientManager.getAppFactory({
      *   appSpec: parsedAppSpec_AppSpec_or_Arc56Contract,
      *   defaultSender: "SENDERADDRESS",
      *   appName: "OverriddenAppName",
@@ -172,6 +203,7 @@ class ClientManager {
      *   deployTimeParams: { ONE: 1, TWO: 'value' }
      * })
      * ```
+     * @returns The `AppFactory` instance
      */
     getAppFactory(params) {
         if (!this._algorand) {
@@ -186,13 +218,13 @@ class ClientManager {
      * @param params The parameters to create the app client
      * @example Basic
      * ```typescript
-     * const appClient = algorand.client.getAppClientByCreatorAndName({
+     * const appClient = clientManager.getAppClientByCreatorAndName({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
      *   // appId resolved by looking for app ID of named app by this creator
      *   creatorAddress: 'CREATORADDRESS',
      * })
      * ```
-     * @returns The `AppClient`
+     * @returns The `AppClient` instance
      */
     getAppClientByCreatorAndName(params) {
         if (!this._algorand) {
@@ -208,12 +240,12 @@ class ClientManager {
      * @param params The parameters to create the app client
      * @example Basic
      * ```typescript
-     * const appClient = algorand.client.getAppClientById({
+     * const appClient = clientManager.getAppClientById({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
      *   appId: 12345n,
      * })
      * ```
-     * @returns The `AppClient`
+     * @returns The `AppClient` instance
      */
     getAppClientById(params) {
         if (!this._algorand) {
@@ -230,12 +262,12 @@ class ClientManager {
      * @param params The parameters to create the app client
      * @example Basic
      * ```typescript
-     * const appClient = algorand.client.getAppClientByNetwork({
+     * const appClient = clientManager.getAppClientByNetwork({
      *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
      *   // appId resolved by using ARC-56 spec to find app ID for current network
      * })
      * ```
-     * @returns The `AppClient`
+     * @returns The `AppClient` instance
      */
     async getAppClientByNetwork(params) {
         if (!this._algorand) {
@@ -249,14 +281,14 @@ class ClientManager {
      * @param params The params to resolve the app by creator address and name
      * @example Use name in ARC-32 / ARC-56 app spec
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientByCreatorAndName(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientByCreatorAndName(MyContractClient, {
      *   creatorAddress: "CREATORADDRESS",
      *   defaultSender: alice,
      * })
      * ```
      * @example Specify name
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientByCreatorAndName(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientByCreatorAndName(MyContractClient, {
      *   creatorAddress: "CREATORADDRESS",
      *   name: "contract-name",
      *   defaultSender: alice,
@@ -276,7 +308,7 @@ class ClientManager {
      * @param params The params to resolve the app by ID
      * @example
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientById(MyContractClient, {
      *   appId: 12345n,
      *   defaultSender: alice,
      * })
@@ -298,7 +330,7 @@ class ClientManager {
      * @param params The params to resolve the app by network
      * @example
      * ```typescript
-     * const appClient = algorand.client.getTypedAppClientByNetwork(MyContractClient, {
+     * const appClient = clientManager.getTypedAppClientByNetwork(MyContractClient, {
      *   defaultSender: alice,
      * })
      * ```
@@ -316,7 +348,7 @@ class ClientManager {
      * @param params The params to resolve the factory by
      * @example
      * ```typescript
-     * const appFactory = algorand.client.getTypedAppFactory(MyContractClient, {
+     * const appFactory = clientManager.getTypedAppFactory(MyContractClient, {
      *   sender: alice,
      * })
      * ```
@@ -368,9 +400,16 @@ class ClientManager {
             kmdConfig,
         };
     }
-    /** Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment)
+    /**
+     * Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment)
      *
      * Expects `process.env.ALGOD_SERVER` to be defined, and you can also specify `process.env.ALGOD_PORT` and `process.env.ALGOD_TOKEN`.
+     * @returns The Algod client configuration
+     * @throws Error if `process.env.ALGOD_SERVER` is not defined
+     * @example
+     * ```typescript
+     * const config = ClientManager.getAlgodConfigFromEnvironment()
+     * ```
      */
     static getAlgodConfigFromEnvironment() {
         if (!process || !process.env) {
@@ -389,6 +428,12 @@ class ClientManager {
      * Retrieve the indexer configuration from environment variables (expects to be called from a Node.js environment).
      *
      * Expects `process.env.INDEXER_SERVER` to be defined, and you can also specify `process.env.INDEXER_PORT` and `process.env.INDEXER_TOKEN`.
+     * @returns The Indexer client configuration
+     * @throws Error if `process.env.INDEXER_SERVER` is not defined
+     * @example
+     * ```typescript
+     * const config = ClientManager.getIndexerConfigFromEnvironment()
+     * ```
      */
     static getIndexerConfigFromEnvironment() {
         if (!process || !process.env) {
@@ -407,6 +452,11 @@ class ClientManager {
      *
      * @param network Which network to connect to - TestNet or MainNet
      * @param config Which algod config to return - Algod or Indexer
+     * @returns The AlgoNode client configuration
+     * @example
+     * ```typescript
+     * const config = ClientManager.getAlgoNodeConfig('testnet', 'algod')
+     * ```
      */
     static getAlgoNodeConfig(network, config) {
         return {
@@ -417,6 +467,11 @@ class ClientManager {
     /** Returns the Algorand configuration to point to the default LocalNet.
      *
      * @param configOrPort Which algod config to return - algod, kmd, or indexer OR a port number
+     * @returns The LocalNet client configuration
+     * @example
+     * ```typescript
+     * const config = ClientManager.getDefaultLocalNetConfig('algod')
+     * ```
      */
     static getDefaultLocalNetConfig(configOrPort) {
         return {
@@ -429,6 +484,7 @@ class ClientManager {
      * Returns an algod SDK client that automatically retries on idempotent calls.
      *
      * @param config The config of the client
+     * @returns The Algod client
      * @example AlgoNode (testnet)
      * ```typescript
      *  const algod = ClientManager.getAlgodClient(ClientManager.getAlgoNodeConfig('testnet', 'algod'))
@@ -454,6 +510,7 @@ class ClientManager {
     /**
      * Returns an algod SDK client that automatically retries on idempotent calls loaded from environment variables (expects to be called from a Node.js environment).
      *
+     * @returns The Algod client
      * @example
      *  ```typescript
      *  // Uses process.env.ALGOD_SERVER, process.env.ALGOD_PORT and process.env.ALGOD_TOKEN
@@ -468,6 +525,7 @@ class ClientManager {
      * Returns an indexer SDK client that automatically retries on idempotent calls
      *
      * @param config The config of the client
+     * @returns The Indexer client
      * @example AlgoNode (testnet)
      * ```typescript
      *  const indexer = ClientManager.getIndexerClient(ClientManager.getAlgoNodeConfig('testnet', 'indexer'))
@@ -493,6 +551,7 @@ class ClientManager {
     /**
      * Returns an indexer SDK client that automatically retries on idempotent calls loaded from environment variables (expects to be called from a Node.js environment).
      *
+     * @returns The Indexer client
      * @example
      *
      *  ```typescript
@@ -510,6 +569,7 @@ class ClientManager {
      * KMD client allows you to export private keys, which is useful to (for instance) get the default account in a LocalNet network.
      *
      * @param config The config for the client
+     * @returns The KMD client
      * @example Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)
      * ```typescript
      *  const kmd = ClientManager.getKmdClient({server: 'http://localhost', port: '4002', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
@@ -522,6 +582,7 @@ class ClientManager {
     /**
      * Returns a KMD SDK client that automatically retries on idempotent calls loaded from environment variables (expects to be called from a Node.js environment).
      *
+     * @returns The KMD client
      * @example
      *  ```typescript
      *  // Uses process.env.ALGOD_SERVER, process.env.KMD_PORT (or if not specified: port 4002) and process.env.ALGOD_TOKEN