@airgap/icp 0.13.11-beta.1 → 0.13.11-beta.2

package/v1/utils/actor.d.ts

@@ -0,0 +1,246 @@
+import { RequestId } from './auth';
+import { CreateCertificateOptions } from './certificate';
+import { Agent, HttpAgent, QueryResponseRejected, SubmitResponse } from './http';
+import { Principal } from './principal';
+import * as IDL from './idl';
+import { PollStrategyFactory } from './polling';
+import { AgentError } from './errors';
+export interface GlobalInternetComputer {
+    ic: {
+        agent: Agent;
+        HttpAgent: typeof HttpAgent;
+        IDL: typeof IDL;
+        /**
+         * Simple advertisement of features in whoever is managing this `globalThis.ic`.
+         * Use Case
+         * * Scripts that know they need an ic feature can detect using this and, if not present
+         *   (e.g. old bootstrap version), they can dynamically include their own and continue
+         *   operating (e.g. polyfill).
+         *   This is useful when adding features to bootstrap. You can still deploy your canister to
+         *   an ic with old bootstrap, then just dynamically reload your own new-version bootstrap if
+         *   needed.
+         */
+        features?: {
+            /** This is falsy if authn isn't supported at all */
+            authentication?: boolean;
+        };
+        /**
+         * The Actor for the canister being used for the frontend. Normally should correspond to the
+         * canister represented by the canister id in the URL.
+         *
+         * It does not have any functions configured.
+         *
+         * If a canister ID could not be found, no actor were created and this is undefined.
+         */
+        canister: ActorSubclass | undefined;
+    };
+}
+export declare function getDefaultAgent(): Agent;
+/**
+ * This file is generated from the candid for asset management.
+ */
+export declare type canister_id = Principal;
+export interface canister_settings {
+    controllers: [] | [Array<Principal>];
+    freezing_threshold: [] | [bigint];
+    memory_allocation: [] | [bigint];
+    compute_allocation: [] | [bigint];
+}
+export interface definite_canister_settings {
+    controllers: Array<Principal>;
+    freezing_threshold: bigint;
+    memory_allocation: bigint;
+    compute_allocation: bigint;
+}
+export declare type user_id = Principal;
+export declare type wasm_module = Array<number>;
+export default interface _SERVICE {
+    canister_status: (arg_0: {
+        canister_id: canister_id;
+    }) => Promise<{
+        status: {
+            stopped: null;
+        } | {
+            stopping: null;
+        } | {
+            running: null;
+        };
+        memory_size: bigint;
+        cycles: bigint;
+        settings: definite_canister_settings;
+        module_hash: [] | [Array<number>];
+    }>;
+    create_canister: (arg_0: {
+        settings: [] | [canister_settings];
+    }) => Promise<{
+        canister_id: canister_id;
+    }>;
+    delete_canister: (arg_0: {
+        canister_id: canister_id;
+    }) => Promise<undefined>;
+    deposit_cycles: (arg_0: {
+        canister_id: canister_id;
+    }) => Promise<undefined>;
+    install_code: (arg_0: {
+        arg: Array<number>;
+        wasm_module: wasm_module;
+        mode: {
+            reinstall: null;
+        } | {
+            upgrade: null;
+        } | {
+            install: null;
+        };
+        canister_id: canister_id;
+    }) => Promise<undefined>;
+    provisional_create_canister_with_cycles: (arg_0: {
+        settings: [] | [canister_settings];
+        amount: [] | [bigint];
+    }) => Promise<{
+        canister_id: canister_id;
+    }>;
+    provisional_top_up_canister: (arg_0: {
+        canister_id: canister_id;
+        amount: bigint;
+    }) => Promise<undefined>;
+    raw_rand: () => Promise<Array<number>>;
+    start_canister: (arg_0: {
+        canister_id: canister_id;
+    }) => Promise<undefined>;
+    stop_canister: (arg_0: {
+        canister_id: canister_id;
+    }) => Promise<undefined>;
+    uninstall_code: (arg_0: {
+        canister_id: canister_id;
+    }) => Promise<undefined>;
+    update_settings: (arg_0: {
+        canister_id: Principal;
+        settings: canister_settings;
+    }) => Promise<undefined>;
+}
+export declare type ManagementCanisterRecord = _SERVICE;
+export declare function getManagementCanister(config: CallConfig): ActorSubclass<ManagementCanisterRecord>;
+export declare class ActorCallError extends AgentError {
+    readonly canisterId: Principal;
+    readonly methodName: string;
+    readonly type: 'query' | 'update';
+    readonly props: Record<string, string>;
+    constructor(canisterId: Principal, methodName: string, type: 'query' | 'update', props: Record<string, string>);
+}
+export declare class QueryCallRejectedError extends ActorCallError {
+    readonly result: QueryResponseRejected;
+    constructor(canisterId: Principal, methodName: string, result: QueryResponseRejected);
+}
+export declare class UpdateCallRejectedError extends ActorCallError {
+    readonly requestId: RequestId;
+    readonly response: SubmitResponse['response'];
+    constructor(canisterId: Principal, methodName: string, requestId: RequestId, response: SubmitResponse['response']);
+}
+/**
+ * Configuration to make calls to the Replica.
+ */
+export interface CallConfig {
+    /**
+     * An agent to use in this call, otherwise the actor or call will try to discover the
+     * agent to use.
+     */
+    agent?: Agent;
+    /**
+     * A polling strategy factory that dictates how much and often we should poll the
+     * read_state endpoint to get the result of an update call.
+     */
+    pollingStrategyFactory?: PollStrategyFactory;
+    /**
+     * The canister ID of this Actor.
+     */
+    canisterId?: string | Principal;
+    /**
+     * The effective canister ID. This should almost always be ignored.
+     */
+    effectiveCanisterId?: Principal;
+}
+/**
+ * Configuration that can be passed to customize the Actor behaviour.
+ */
+export interface ActorConfig extends CallConfig {
+    /**
+     * The Canister ID of this Actor. This is required for an Actor.
+     */
+    canisterId: string | Principal;
+    /**
+     * An override function for update calls' CallConfig. This will be called on every calls.
+     */
+    callTransform?(methodName: string, args: unknown[], callConfig: CallConfig): Partial<CallConfig> | void;
+    /**
+     * An override function for query calls' CallConfig. This will be called on every query.
+     */
+    queryTransform?(methodName: string, args: unknown[], callConfig: CallConfig): Partial<CallConfig> | void;
+    /**
+     * Polyfill for BLS Certificate verification in case wasm is not supported
+     */
+    blsVerify?: CreateCertificateOptions['blsVerify'];
+}
+/**
+ * A subclass of an actor. Actor class itself is meant to be a based class.
+ */
+export declare type ActorSubclass<T = Record<string, ActorMethod>> = Actor & T;
+/**
+ * An actor method type, defined for each methods of the actor service.
+ */
+export interface ActorMethod<Args extends unknown[] = unknown[], Ret extends unknown = unknown> {
+    (...args: Args): Promise<Ret>;
+    withOptions(options: CallConfig): (...args: Args) => Promise<Ret>;
+}
+/**
+ * The mode used when installing a canister.
+ */
+export declare enum CanisterInstallMode {
+    Install = "install",
+    Reinstall = "reinstall",
+    Upgrade = "upgrade"
+}
+/**
+ * Internal metadata for actors. It's an enhanced version of ActorConfig with
+ * some fields marked as required (as they are defaulted) and canisterId as
+ * a Principal type.
+ */
+interface ActorMetadata {
+    service: IDL.ServiceClass;
+    agent?: Agent;
+    config: ActorConfig;
+}
+declare const metadataSymbol: unique symbol;
+/**
+ * An actor base class. An actor is an object containing only functions that will
+ * return a promise. These functions are derived from the IDL definition.
+ */
+export declare class Actor {
+    /**
+     * Get the Agent class this Actor would call, or undefined if the Actor would use
+     * the default agent (global.ic.agent).
+     * @param actor The actor to get the agent of.
+     */
+    static agentOf(actor: Actor): Agent | undefined;
+    /**
+     * Get the interface of an actor, in the form of an instance of a Service.
+     * @param actor The actor to get the interface of.
+     */
+    static interfaceOf(actor: Actor): IDL.ServiceClass;
+    static canisterIdOf(actor: Actor): Principal;
+    static install(fields: {
+        module: ArrayBuffer;
+        mode?: CanisterInstallMode;
+        arg?: ArrayBuffer;
+    }, config: ActorConfig): Promise<void>;
+    static createCanister(config?: CallConfig): Promise<Principal>;
+    static createAndInstallCanister(interfaceFactory: IDL.InterfaceFactory, fields: {
+        module: ArrayBuffer;
+        arg?: ArrayBuffer;
+    }, config?: CallConfig): Promise<ActorSubclass>;
+    static createActorClass(interfaceFactory: IDL.InterfaceFactory): ActorConstructor;
+    static createActor<T = Record<string, ActorMethod>>(interfaceFactory: IDL.InterfaceFactory, configuration: ActorConfig): ActorSubclass<T>;
+    private [metadataSymbol];
+    protected constructor(metadata: ActorMetadata);
+}
+export declare type ActorConstructor = new (config: ActorConfig) => ActorSubclass;
+export {};