ClientManager

Defined in: client.ts:45

ClientManager is a central class for managing the Internet Computer (IC) agent.

It initializes the agent (connecting to local or mainnet) and integrates with TanStack Query’s QueryClient for state management. Use this as a singleton shared by all reactors in an app.

Examples

import { ClientManager } from "@ic-reactor/core";
import { QueryClient } from "@tanstack/query-core";

const queryClient = new QueryClient();
const clientManager = new ClientManager({
  queryClient,
  agentOptions: { host: "http://127.0.0.1:4943" },
});

await clientManager.initialize();

// Reuse the same ClientManager across multiple canisters
const backend = new Reactor<BackendService>({ clientManager, idlFactory: backendIdl, name: "backend" })
const ledger = new Reactor<LedgerService>({ clientManager, idlFactory: ledgerIdl, name: "ledger" })

Constructors

Constructor

new ClientManager(parameters): ClientManager

Defined in: client.ts:70

Creates a new instance of ClientManager.

Parameters

parameters

ClientManagerParameters

Configuration options for the agent and network environment.

Returns

ClientManager

Properties

queryClient

queryClient: QueryClient

Defined in: client.ts:58

The TanStack QueryClient used for managing cached canister data and invalidating queries on identity changes.

---

agentState

agentState: AgentState

Defined in: client.ts:62

Current state of the HttpAgent, including initialization status, network, and error information.

Accessors

agent

Get Signature

get agent(): HttpAgent

Defined in: client.ts:235

The underlying HttpAgent managed by this class.

Returns

HttpAgent

---

agentHost

Get Signature

get agentHost(): URL | undefined

Defined in: client.ts:242

The host URL of the current IC agent.

Returns

URL | undefined

---

agentHostName

Get Signature

get agentHostName(): string

Defined in: client.ts:249

The hostname of the current IC agent.

Returns

string

---

trustsEnvConfig

Get Signature

get trustsEnvConfig(): boolean

Defined in: client.ts:267

Whether the configuration carried by the ic_env cookie may be trusted for this agent’s host.

true when BOTH the agent host and the page origin are unambiguously a local replica, or when the caller passed allowEnvConfig. The page counts because the page is what decides who can write the cookie. Every consumer of that cookie reads this one decision, so the root key, the Internet Identity provider and a reactor’s canister ID cannot disagree about whether the environment is trustworthy.

The deprecated allowEnvRootKey is not enough on its own: it granted the root key alone, and is honoured for the root key alone.

Returns

boolean

---

isLocal

Get Signature

get isLocal(): boolean

Defined in: client.ts:274

Returns true if the agent is connecting to a local environment.

Returns

boolean

---

network

Get Signature

get network(): "local" | "remote" | "ic"

Defined in: client.ts:281

Returns the current network type (‘ic’ or ‘local’).

Returns

"local" | "remote" | "ic"

---

identity

Get Signature

get identity(): Identity | undefined

Defined in: client.ts:293

The identity currently installed on the agent, if one was set explicitly.

Calls capture this at submit time and pass it back on every request they make, so a sign-in or sign-out part-way through cannot re-sign a request that is already in flight.

Returns

Identity | undefined

Methods

initialize()

initialize(): Promise<ClientManager>

Defined in: client.ts:182

Orchestrates the complete initialization of the ClientManager. This method awaits the agent’s core initialization (e.g., fetching root keys) Authentication session restoration is handled by AuthenticationManager.

Returns

Promise<ClientManager>

A promise that resolves to the ClientManager instance when core initialization is complete.

---

initializeAgent()

initializeAgent(): Promise<void>

Defined in: client.ts:193

Specifically initializes the HttpAgent. On local networks, this includes fetching the root key for certificate verification.

Returns

Promise<void>

A promise that resolves when the agent is fully initialized.

---

getUserPrincipal()

getUserPrincipal(): Promise<Principal>

Defined in: client.ts:300

Returns the current user’s Principal identity.

Returns

Promise<Principal>

---

registerCanisterId()

registerCanisterId(canisterId, name?): void

Defined in: client.ts:308

Registers a canister ID that this agent will interact with. This is used for informational purposes and network detection.

Parameters

canisterId

string

name?

string

Returns

void

---

connectedCanisterIds()

connectedCanisterIds(): string[]

Defined in: client.ts:331

Returns a list of all canister IDs registered with this agent.

Returns

string[]

---

getSubnetIdFromCanister()

getSubnetIdFromCanister(canisterId): Promise<Principal>

Defined in: client.ts:338

Get the subnet ID for a canister.

Parameters

canisterId

string

Returns

Promise<Principal>

---

syncTimeWithSubnet()

syncTimeWithSubnet(subnetId): Promise<void>

Defined in: client.ts:345

Sync time with a specific subnet.

Parameters

subnetId

Principal

Returns

Promise<void>

---

subscribe()

subscribe(callback): () => void

Defined in: client.ts:354

Subscribes to identity changes (e.g., after login/logout).

Parameters

callback

(identity) => void

Function called with the new identity.

Returns

An unsubscribe function.

() => void

---

subscribeAgentState()

subscribeAgentState(callback): () => void

Defined in: client.ts:368

Subscribes to changes in the agent’s initialization state.

Parameters

callback

(state) => void

Function called with the updated agent state.

Returns

An unsubscribe function.

() => void

---

updateAgent()

updateAgent(identity): void

Defined in: client.ts:381

Replaces the current agent’s identity and invalidates TanStack queries.

Parameters

identity

Identity

The new identity to use.

Returns

void