ClientManager
Defined in: client.ts:40
ClientManager is a central class for managing the Internet Computer (IC) agent and authentication state.
It initializes the agent (connecting to local or mainnet), handles authentication via AuthClient, and integrates with TanStack Query’s QueryClient for state management.
Example
Section titled “Example”import { ClientManager } from "@ic-reactor/core";import { QueryClient } from "@tanstack/react-query";
const queryClient = new QueryClient();const clientManager = new ClientManager({ queryClient, withLocalEnv: true, // Use local replica});
await clientManager.initialize();Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ClientManager(
parameters):ClientManager
Defined in: client.ts:71
Creates a new instance of ClientManager.
Parameters
Section titled “Parameters”parameters
Section titled “parameters”Configuration options for the agent and network environment.
Returns
Section titled “Returns”ClientManager
Properties
Section titled “Properties”queryClient
Section titled “queryClient”queryClient:
QueryClient
Defined in: client.ts:51
The TanStack QueryClient used for managing cached canister data and invalidating queries on identity changes.
agentState
Section titled “agentState”agentState:
AgentState
Defined in: client.ts:55
Current state of the HttpAgent, including initialization status, network, and error information.
authState
Section titled “authState”authState:
AuthState
Defined in: client.ts:59
Current authentication state, including the active identity, authentication progress, and errors.
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get agent():
HttpAgent
Defined in: client.ts:385
The underlying HttpAgent managed by this class.
Returns
Section titled “Returns”HttpAgent
agentHost
Section titled “agentHost”Get Signature
Section titled “Get Signature”get agentHost():
URL|undefined
Defined in: client.ts:392
The host URL of the current IC agent.
Returns
Section titled “Returns”URL | undefined
agentHostName
Section titled “agentHostName”Get Signature
Section titled “Get Signature”get agentHostName():
string
Defined in: client.ts:399
The hostname of the current IC agent.
Returns
Section titled “Returns”string
isLocal
Section titled “isLocal”Get Signature
Section titled “Get Signature”get isLocal():
boolean
Defined in: client.ts:406
Returns true if the agent is connecting to a local environment.
Returns
Section titled “Returns”boolean
network
Section titled “network”Get Signature
Section titled “Get Signature”get network():
"local"|"remote"|"ic"
Defined in: client.ts:413
Returns the current network type (‘ic’ or ‘local’).
Returns
Section titled “Returns”"local" | "remote" | "ic"
Methods
Section titled “Methods”initialize()
Section titled “initialize()”initialize():
Promise<ClientManager>
Defined in: client.ts:172
Orchestrates the complete initialization of the ClientManager. This method awaits the agent’s core initialization (e.g., fetching root keys) and triggers the authentication (session restoration) in the background.
Returns
Section titled “Returns”Promise<ClientManager>
A promise that resolves to the ClientManager instance when core initialization is complete.
initializeAgent()
Section titled “initializeAgent()”initializeAgent():
Promise<void>
Defined in: client.ts:184
Specifically initializes the HttpAgent. On local networks, this includes fetching the root key for certificate verification.
Returns
Section titled “Returns”Promise<void>
A promise that resolves when the agent is fully initialized.
authenticate()
Section titled “authenticate()”authenticate():
Promise<Identity|undefined>
Defined in: client.ts:236
Attempts to initialize the authentication client and restore a previous session.
If an AuthClient is already initialized (passed in constructor or previously created),
it uses that instance. Otherwise, it dynamically imports the @icp-sdk/auth module
and creates a new AuthClient.
If the module is missing and no client is provided, it fails gracefully by marking authentication as unavailable.
Returns
Section titled “Returns”Promise<Identity | undefined>
A promise that resolves to the restored Identity, or undefined if auth fails or is unavailable.
login()
Section titled “login()”login(
loginOptions?):Promise<void>
Defined in: client.ts:303
Triggers the login flow using the Internet Identity provider.
Parameters
Section titled “Parameters”loginOptions?
Section titled “loginOptions?”AuthClientLoginOptions
Options for the login flow, including identity provider and callbacks.
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”An error if the authentication module is not installed.
logout()
Section titled “logout()”logout():
Promise<void>
Defined in: client.ts:363
Logs out the user and reverts the agent to an anonymous identity.
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”An error if the authentication module is not installed.
getUserPrincipal()
Section titled “getUserPrincipal()”getUserPrincipal():
Promise<Principal>
Defined in: client.ts:421
Returns the current user’s Principal identity.
Returns
Section titled “Returns”Promise<Principal>
registerCanisterId()
Section titled “registerCanisterId()”registerCanisterId(
canisterId,name?):void
Defined in: client.ts:429
Registers a canister ID that this agent will interact with. This is used for informational purposes and network detection.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string
string
Returns
Section titled “Returns”void
connectedCanisterIds()
Section titled “connectedCanisterIds()”connectedCanisterIds():
string[]
Defined in: client.ts:449
Returns a list of all canister IDs registered with this agent.
Returns
Section titled “Returns”string[]
getSubnetIdFromCanister()
Section titled “getSubnetIdFromCanister()”getSubnetIdFromCanister(
canisterId):Promise<Principal>
Defined in: client.ts:456
Get the subnet ID for a canister.
Parameters
Section titled “Parameters”canisterId
Section titled “canisterId”string
Returns
Section titled “Returns”Promise<Principal>
syncTimeWithSubnet()
Section titled “syncTimeWithSubnet()”syncTimeWithSubnet(
subnetId):Promise<void>
Defined in: client.ts:463
Sync time with a specific subnet.
Parameters
Section titled “Parameters”subnetId
Section titled “subnetId”Principal
Returns
Section titled “Returns”Promise<void>
subscribe()
Section titled “subscribe()”subscribe(
callback): () =>void
Defined in: client.ts:483
Subscribes to identity changes (e.g., after login/logout).
Parameters
Section titled “Parameters”callback
Section titled “callback”(identity) => void
Function called with the new identity.
Returns
Section titled “Returns”An unsubscribe function.
():
void
Returns
Section titled “Returns”void
subscribeAgentState()
Section titled “subscribeAgentState()”subscribeAgentState(
callback): () =>void
Defined in: client.ts:497
Subscribes to changes in the agent’s initialization state.
Parameters
Section titled “Parameters”callback
Section titled “callback”(state) => void
Function called with the updated agent state.
Returns
Section titled “Returns”An unsubscribe function.
():
void
Returns
Section titled “Returns”void
subscribeAuthState()
Section titled “subscribeAuthState()”subscribeAuthState(
callback): () =>void
Defined in: client.ts:511
Subscribes to changes in the authentication state.
Parameters
Section titled “Parameters”callback
Section titled “callback”(state) => void
Function called with the updated authentication state.
Returns
Section titled “Returns”An unsubscribe function.
():
void
Returns
Section titled “Returns”void
updateAgent()
Section titled “updateAgent()”updateAgent(
identity):void
Defined in: client.ts:524
Replaces the current agent’s identity and invalidates TanStack queries.
Parameters
Section titled “Parameters”identity
Section titled “identity”Identity
The new identity to use.
Returns
Section titled “Returns”void