ClientManager
Defined in: client.ts:39
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:68
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:50
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:54
Current state of the HttpAgent, including initialization status, network, and error information.
authState
Section titled “authState”authState:
AuthState
Defined in: client.ts:58
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:345
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:352
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:359
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:366
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:373
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:132
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:144
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:196
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:263
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:323
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:381
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:389
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:409
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:416
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:423
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:440
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:454
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:468
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:481
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