@algorandfoundation/algokit-utils 10.0.0-alpha.9 → 10.0.0-beta.1

package/client-manager.d.ts

@@ -0,0 +1,475 @@
+import { Expand } from "./packages/common/src/expand.js";
+import { AlgodClient } from "./packages/algod_client/src/client.js";
+import { IndexerClient } from "./packages/indexer_client/src/client.js";
+import { KmdClient } from "./packages/kmd_client/src/client.js";
+import { AlgoClientConfig, AlgoConfig, NetworkDetails } from "./network-client.js";
+import { AlgorandClient } from "./algorand-client.js";
+import { AppClient, AppClientParams, ResolveAppClientByCreatorAndName } from "./app-client.js";
+import { AppFactory, AppFactoryParams } from "./app-factory.js";
+import { TestNetDispenserApiClient, TestNetDispenserApiClientParams } from "./dispenser-client.js";
+
+//#region src/client-manager.d.ts
+/** Clients from algosdk that interact with the official Algorand APIs */
+interface AlgoSdkClients {
+  /** Algod client, see https://dev.algorand.co/reference/rest-apis/algod/ */
+  algod: AlgodClient;
+  /** Optional indexer client, see https://dev.algorand.co/reference/rest-apis/indexer */
+  indexer?: IndexerClient;
+  /** Optional KMD client, see https://dev.algorand.co/reference/rest-apis/kmd/ */
+  kmd?: KmdClient;
+}
+/** Params to get an app factory from `ClientManager`. */
+type ClientAppFactoryParams = Expand<Omit<AppFactoryParams, 'algorand'>>;
+/** Params to get an app client by creator address and name from `ClientManager`. */
+type ClientResolveAppClientByCreatorAndNameParams = Expand<Omit<ResolveAppClientByCreatorAndName, 'algorand'>>;
+/** Params to get an app client by ID from `ClientManager`. */
+type ClientAppClientParams = Expand<Omit<AppClientParams, 'algorand'>>;
+/** Params to get an app client by network from `ClientManager`. */
+type ClientAppClientByNetworkParams = Expand<Omit<AppClientParams, 'algorand' | 'appId'>>;
+/** Params to get a typed app client by creator address and name from `ClientManager`. */
+type ClientTypedAppClientByCreatorAndNameParams = Expand<Omit<ResolveAppClientByCreatorAndName, 'algorand' | 'appSpec'>>;
+/** Params to get a typed app client by ID from `ClientManager`. */
+type ClientTypedAppClientParams = Expand<Omit<AppClientParams, 'algorand' | 'appSpec'>>;
+/** Params to get a typed app client by network from `ClientManager`. */
+type ClientTypedAppClientByNetworkParams = Expand<Omit<AppClientParams, 'algorand' | 'appSpec' | 'appId'>>;
+/** Params to get a typed app factory from `ClientManager`. */
+type ClientTypedAppFactoryParams = Expand<Omit<AppFactoryParams, 'algorand' | 'appSpec'>>;
+/** Exposes access to various API clients. */
+declare class ClientManager {
+  private _algod;
+  private _indexer?;
+  private _kmd?;
+  private _algorand?;
+  /**
+   * algosdk clients or config for interacting with the official Algorand APIs.
+   * @param clientsOrConfig The clients or config to use
+   * @example Algod client only
+   * ```typescript
+   * const clientManager = new ClientManager({ algod: algodClient })
+   * ```
+   * @example All clients
+   * ```typescript
+   * const clientManager = new ClientManager({ algod: algodClient, indexer: indexerClient, kmd: kmdClient })
+   * ```
+   * @example Algod config only
+   * ```typescript
+   * const clientManager = new ClientManager({ algodConfig })
+   * ```
+   * @example All client configs
+   * ```typescript
+   * const clientManager = new ClientManager({ algodConfig, indexerConfig, kmdConfig })
+   * ```
+   */
+  constructor(clientsOrConfig: AlgoConfig | AlgoSdkClients, algorandClient?: AlgorandClient);
+  /**
+   * Returns an Algod API client.
+   * @returns The Algod client
+   */
+  get algod(): AlgodClient;
+  /**
+   * Returns an 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(): IndexerClient;
+  /**
+   * Returns an Indexer API client or `undefined` if it's not been provided.
+   * @returns The Indexer client or `undefined`
+   */
+  get indexerIfPresent(): IndexerClient | undefined;
+  /**
+   * Returns a 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(): KmdClient;
+  private _getNetworkPromise;
+  /**
+   * Get details about the current network.
+   * @example Getting genesis ID
+   * ```typescript
+   * const network = await networkClient.network()
+   * const genesisId = network.genesisId
+   * ```
+   * @returns The current network details
+   */
+  network(): Promise<NetworkDetails>;
+  /**
+   * 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): genesisId is "devnet-v1" | "sandnet-v1" | "dockernet-v1";
+  /**
+   * 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>;
+  /**
+   * Returns a TestNet Dispenser API client.
+   *
+   * Refer to [docs](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md) on guidance to obtain an access token.
+   *
+   * @param params An object containing parameters for the TestNetDispenserApiClient class.
+   * @example
+   * const client = clientManager.getTestNetDispenser(
+   *     {
+   *       authToken: 'your_auth_token',
+   *       requestTimeout: 15,
+   *     }
+   * )
+   *
+   * @returns An instance of the TestNetDispenserApiClient class.
+   */
+  getTestNetDispenser(params: TestNetDispenserApiClientParams): TestNetDispenserApiClient;
+  /**
+   * Returns a TestNet Dispenser API client, loading the auth token from `process.env.ALGOKIT_DISPENSER_ACCESS_TOKEN`.
+   *
+   * Refer to [docs](https://github.com/algorandfoundation/algokit/blob/main/docs/testnet_api.md) on guidance to obtain an access token.
+   *
+   * @param params An object containing parameters for the TestNetDispenserApiClient class.
+   * @example
+   * const client = clientManager.getTestNetDispenserFromEnvironment(
+   *     {
+   *       requestTimeout: 15,
+   *     }
+   * )
+   *
+   * @returns An instance of the TestNetDispenserApiClient class.
+   */
+  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 = clientManager.getAppFactory({
+   *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\/}',
+   * })
+   * ```
+   * @example Advanced example
+   * ```typescript
+   * const factory = clientManager.getAppFactory({
+   *   appSpec: parsedAppSpec_AppSpec_or_Arc56Contract,
+   *   defaultSender: "SENDERADDRESS",
+   *   appName: "OverriddenAppName",
+   *   version: "2.0.0",
+   *   updatable: true,
+   *   deletable: false,
+   *   deployTimeParams: { ONE: 1, TWO: 'value' }
+   * })
+   * ```
+   * @returns The `AppFactory` instance
+   */
+  getAppFactory(params: ClientAppFactoryParams): AppFactory;
+  /**
+   * Returns a new `AppClient` client for managing calls and state for an ARC-32/ARC-56 app.
+   * This method resolves the app ID by looking up the 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
+   * @example Basic
+   * ```typescript
+   * 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` instance
+   */
+  getAppClientByCreatorAndName(params: ClientResolveAppClientByCreatorAndNameParams): Promise<AppClient>;
+  /**
+   * Returns a new `AppClient` client for managing calls and state for an ARC-32/ARC-56 app.
+   * @param params The parameters to create the app client
+   * @example Basic
+   * ```typescript
+   * const appClient = clientManager.getAppClientById({
+   *   appSpec: '{/* ARC-56 or ARC-32 compatible JSON *\}',
+   *   appId: 12345n,
+   * })
+   * ```
+   * @returns The `AppClient` instance
+   */
+  getAppClientById(params: ClientAppClientParams): AppClient;
+  /**
+   * Returns a new `AppClient` client for managing calls and state for an ARC-56 app.
+   * This method resolves the app ID for the current network based on
+   * pre-determined network-specific app IDs specified in the ARC-56 app spec.
+   *
+   * 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
+   * @example Basic
+   * ```typescript
+   * 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` instance
+   */
+  getAppClientByNetwork(params: ClientAppClientByNetworkParams): Promise<AppClient>;
+  /**
+   * Returns a new typed client, resolving the app by creator address and name.
+   * @param typedClient The typed client type to use
+   * @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 = clientManager.getTypedAppClientByCreatorAndName(MyContractClient, {
+   *   creatorAddress: "CREATORADDRESS",
+   *   defaultSender: alice,
+   * })
+   * ```
+   * @example Specify name
+   * ```typescript
+   * const appClient = clientManager.getTypedAppClientByCreatorAndName(MyContractClient, {
+   *   creatorAddress: "CREATORADDRESS",
+   *   name: "contract-name",
+   *   defaultSender: alice,
+   * })
+   * ```
+   * @returns The typed client instance
+   */
+  getTypedAppClientByCreatorAndName<TClient extends TypedAppClient<InstanceType<TClient>>>(typedClient: TClient, params: ClientTypedAppClientByCreatorAndNameParams): Promise<InstanceType<TClient>>;
+  /**
+   * Returns a new typed client, resolving the app by app ID.
+   * @param typedClient The typed client type to use
+   * @param params The params to resolve the app by ID
+   * @example
+   * ```typescript
+   * const appClient = clientManager.getTypedAppClientById(MyContractClient, {
+   *   appId: 12345n,
+   *   defaultSender: alice,
+   * })
+   * ```
+   * @returns The typed client instance
+   */
+  getTypedAppClientById<TClient extends TypedAppClient<InstanceType<TClient>>>(typedClient: TClient, params: ClientTypedAppClientParams): InstanceType<TClient>;
+  /**
+   * Returns a new typed client, resolves the app ID for the current network based on
+   * pre-determined network-specific app IDs specified in the ARC-56 app spec.
+   *
+   * If no IDs are in the app spec or the network isn't recognised, an error is thrown.
+   * @param typedClient The typed client type to use
+   * @param params The params to resolve the app by network
+   * @example
+   * ```typescript
+   * const appClient = clientManager.getTypedAppClientByNetwork(MyContractClient, {
+   *   defaultSender: alice,
+   * })
+   * ```
+   * @returns The typed client instance
+   */
+  getTypedAppClientByNetwork<TClient extends TypedAppClient<InstanceType<TClient>>>(typedClient: TClient, params?: ClientTypedAppClientByNetworkParams): Promise<InstanceType<TClient>>;
+  /**
+   * Returns a new typed app factory.
+   * @param typedFactory The typed factory type to use
+   * @param params The params to resolve the factory by
+   * @example
+   * ```typescript
+   * const appFactory = clientManager.getTypedAppFactory(MyContractClient, {
+   *   sender: alice,
+   * })
+   * ```
+   * @returns The typed client instance
+   */
+  getTypedAppFactory<TClient>(typedFactory: TypedAppFactory<TClient>, params?: ClientTypedAppFactoryParams): TClient;
+  /**
+   * Retrieve client configurations from environment variables when defined or get defaults (expects to be called from a Node.js environment)
+   *
+   * If both `process.env.INDEXER_SERVER` and `process.env.ALGOD_SERVER` is defined it will use both along with optional `process.env.ALGOD_PORT`, `process.env.ALGOD_TOKEN`, `process.env.INDEXER_PORT` and `process.env.INDEXER_TOKEN`.
+   *
+   * If only `process.env.ALGOD_SERVER` is defined it will use this along with optional `process.env.ALGOD_PORT` and `process.env.ALGOD_TOKEN` and leave indexer as `undefined`.
+   *
+   * If only `process.env.INDEXER_SERVER` is defined it will use the default (LocalNet) configuration for both algod and indexer.
+   *
+   * It will return a KMD configuration that uses `process.env.KMD_PORT` (or port 4002) if `process.env.ALGOD_SERVER` is defined,
+   * otherwise it will use the default LocalNet config unless it detects testnet or mainnet.
+   * @example
+   * ```typescript
+   * const config = ClientManager.getConfigFromEnvironmentOrLocalNet()
+   * ```
+   * @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)
+   *
+   * 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'))
+   *  await algod.healthCheck().do()
+   * ```
+   * @example AlgoNode (mainnet)
+   * ```typescript
+   *  const algod = ClientManager.getAlgodClient(ClientManager.getAlgoNodeConfig('mainnet', 'algod'))
+   *  await algod.healthCheck().do()
+   * ```
+   * @example Custom (e.g. default LocalNet)
+   * ```typescript
+   *  const algod = ClientManager.getAlgodClient({server: 'http://localhost', port: '4001', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
+   *  await algod.healthCheck().do()
+   * ```
+   */
+  static getAlgodClient(config: AlgoClientConfig): AlgodClient;
+  /**
+   * 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
+   *  const algod = ClientManager.getAlgodClientFromEnvironment()
+   *  await algod.healthCheck().do()
+   *  ```
+   */
+  static getAlgodClientFromEnvironment(): AlgodClient;
+  /**
+   * 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'))
+   *  await indexer.makeHealthCheck().do()
+   * ```
+   * @example AlgoNode (mainnet)
+   * ```typescript
+   *  const indexer = ClientManager.getIndexerClient(ClientManager.getAlgoNodeConfig('mainnet', 'indexer'))
+   *  await indexer.makeHealthCheck().do()
+   * ```
+   * @example Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)
+   * ```typescript
+   *  const indexer = ClientManager.getIndexerClient({server: 'http://localhost', port: '8980', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
+   *  await indexer.makeHealthCheck().do()
+   * ```
+   */
+  static getIndexerClient(config: AlgoClientConfig): IndexerClient;
+  /**
+   * 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
+   *  // Uses process.env.INDEXER_SERVER, process.env.INDEXER_PORT and process.env.INDEXER_TOKEN
+   *  const indexer = ClientManager.getIndexerClientFromEnvironment()
+   *  await indexer.makeHealthCheck().do()
+   *  ```
+   */
+  static getIndexerClientFromEnvironment(): IndexerClient;
+  /**
+   * Returns a KMD SDK client.
+   *
+   * 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'})
+   * ```
+   */
+  static getKmdClient(config: AlgoClientConfig): KmdClient;
+  /**
+   * 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
+   *  const kmd = ClientManager.getKmdClientFromEnvironment()
+   *  ```
+   */
+  static getKmdClientFromEnvironment(): KmdClient;
+}
+/**
+ * Interface to identify a typed client that can be used to interact with an application.
+ */
+interface TypedAppClient<TClient> {
+  new (params: Omit<AppClientParams, 'appSpec'>): TClient;
+  fromNetwork(params: Omit<AppClientParams, 'appId' | 'appSpec'>): Promise<TClient>;
+  fromCreatorAndName(params: Omit<ResolveAppClientByCreatorAndName, 'appSpec'>): Promise<TClient>;
+}
+/**
+ * Interface to identify a typed factory that can be used to create and deploy an application.
+ */
+interface TypedAppFactory<TClient> {
+  new (params: Omit<AppFactoryParams, 'appSpec'>): TClient;
+}
+//#endregion
+export { AlgoSdkClients, ClientAppClientByNetworkParams, ClientAppClientParams, ClientAppFactoryParams, ClientManager, ClientResolveAppClientByCreatorAndNameParams, ClientTypedAppClientByCreatorAndNameParams, ClientTypedAppClientByNetworkParams, ClientTypedAppClientParams, ClientTypedAppFactoryParams, TypedAppClient, TypedAppFactory };
+//# sourceMappingURL=client-manager.d.ts.map