A JavaScript frontend library for interacting with ICP Backend Canisters and Identity Providers.
NOTE: This is a Beta version
To create a Client instance you must call the static method create
and later you must call the init
method:
const client = Client.create({});
await client.init();
Most implementations use Identity Providers to call canisters with autenticated identities, so its necesary to declare which Identity Providers you want to use:
const client = Client.create({
providers: [
new InternetIdentity({
providerUrl: process.env.NEXT_PUBLIC_INTERNET_IDENTITY_URL!,
}),
],
});
See following example to start an authentication process:
const provider = client.getProvider("internet-identity");
provider.connect();
Then, you can get all the authenticated identities:
const identities = client.getIdentities();
Ares Client supports two kind of Canisters:
- Candid Canisters: Traditional Canisters that you can build according the Internet Computer Protocol
- Http Canisters: Canisters Build according the HTTP Gateway Protocol, this is an Experimental feature.
To use candid canisters you can follow the example below:
import { _SERVICE, idlFactory } from "path_to_canister_declarations/test.did.js";
export const candidTest: Canister = {
idlFactory,
configuration: {
canisterId: "TEST_CANDID_CANISTER_ID",
},
};
const client = Client.create({
agentConfig: {
host: "IC_HOST_URL",
},
...
candidCanisters: {
candidTest
}
});
const candidActor = client.getCandidActor("candidTest");
To use http canisters you can follow the example below:
export const httpTest: Canister = {
baseUrl: "API_REST_URL"
};
const client = Client.create({
...
restCanisters: {
httpTest
}
});
const candidActor = client.getRestActor("httpTest");
You can use both canisters (candid and http) at the same time:
const client = Client.create({
agentConfig: {
host: "IC_HOST_URL",
},
...
candidCanisters: {
candidTest
},
restCanisters: {
httpTest
}
});
Ares defines some prebuild Identity Providers, but if you like to implement your own, you neet to create a class that implements the IdentityProvider
interface:
export class MyCustomIdentityProvider implements IdentityProvider {}
For a complete implementation you can see how the InternetIdentity
provider is built.
You can define custom storage (where identities and some configurations will be stored), for that, yo need to create a class that implements the ClientStorageInterface
:
class MyCustomStorage implements ClientStorageInterface {}