@dfinity/agent/lib/esm/actor.d.ts

JavaScript and TypeScript library to interact with the Internet Computer

import { type Agent, type HttpDetailsResponse } from './agent/index.ts';
import { IDL } from '@dfinity/candid';
import { type PollingOptions } from './polling/index.ts';
import { Principal } from '@dfinity/principal';
import { Certificate, type CreateCertificateOptions } from './certificate.ts';
/**
 * 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;
    /**
     * Options for controlling polling behavior.
     */
    pollingOptions?: PollingOptions;
    /**
     * The canister ID of this Actor.
     */
    canisterId?: string | Principal;
    /**
     * The effective canister ID.
     */
    effectiveCanisterId?: Principal;
    /**
     * The nonce to use for this call. This is used to prevent replay attacks.
     */
    nonce?: Uint8Array;
}
/**
 * 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'];
    /**
     * Polling options to use when making update calls. This will override the default DEFAULT_POLLING_OPTIONS.
     */
    pollingOptions?: PollingOptions;
}
/**
 * A subclass of an actor. Actor class itself is meant to be a based class.
 */
export 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 = unknown> {
    (...args: Args): Promise<Ret>;
    withOptions(options: CallConfig): (...args: Args) => Promise<Ret>;
}
/**
 * An actor method type, defined for each methods of the actor service.
 */
export interface ActorMethodWithHttpDetails<Args extends unknown[] = unknown[], Ret = unknown> extends ActorMethod {
    (...args: Args): Promise<{
        httpDetails: HttpDetailsResponse;
        result: Ret;
    }>;
}
/**
 * An actor method type, defined for each methods of the actor service.
 */
export interface ActorMethodExtended<Args extends unknown[] = unknown[], Ret = unknown> extends ActorMethod {
    (...args: Args): Promise<{
        certificate?: Certificate;
        httpDetails?: HttpDetailsResponse;
        result: Ret;
    }>;
}
export type FunctionWithArgsAndReturn<Args extends unknown[] = unknown[], Ret = unknown> = (...args: Args) => Ret;
export type ActorMethodMappedWithHttpDetails<T> = {
    [K in keyof T]: T[K] extends FunctionWithArgsAndReturn<infer Args, infer Ret> ? ActorMethodWithHttpDetails<Args, Ret> : never;
};
export type ActorMethodMappedExtended<T> = {
    [K in keyof T]: T[K] extends FunctionWithArgsAndReturn<infer Args, infer Ret> ? ActorMethodExtended<Args, Ret> : never;
};
/**
 * The mode used when installing a canister.
 */
export type CanisterInstallMode = {
    reinstall: null;
} | {
    upgrade: [] | [
        {
            skip_pre_upgrade: [] | [boolean];
        }
    ];
} | {
    install: null;
};
/**
 * 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;
export interface CreateActorClassOpts {
    httpDetails?: boolean;
    certificate?: boolean;
}
/**
 * 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 createActorClass(interfaceFactory: IDL.InterfaceFactory, options?: CreateActorClassOpts): ActorConstructor;
    static createActor<T = Record<string, ActorMethod>>(interfaceFactory: IDL.InterfaceFactory, configuration: ActorConfig): ActorSubclass<T>;
    /**
     * Returns an actor with methods that return the http response details along with the result
     * @param interfaceFactory - the interface factory for the actor
     * @param configuration - the configuration for the actor
     * @deprecated - use createActor with actorClassOptions instead
     */
    static createActorWithHttpDetails<T = Record<string, ActorMethod>>(interfaceFactory: IDL.InterfaceFactory, configuration: ActorConfig): ActorSubclass<ActorMethodMappedWithHttpDetails<T>>;
    /**
     * Returns an actor with methods that return the http response details along with the result
     * @param interfaceFactory - the interface factory for the actor
     * @param configuration - the configuration for the actor
     * @param actorClassOptions - options for the actor class extended details to return with the result
     */
    static createActorWithExtendedDetails<T = Record<string, ActorMethod>>(interfaceFactory: IDL.InterfaceFactory, configuration: ActorConfig, actorClassOptions?: CreateActorClassOpts): ActorSubclass<ActorMethodMappedExtended<T>>;
    private [metadataSymbol];
    protected constructor(metadata: ActorMetadata);
}
export type ActorConstructor = new (config: ActorConfig) => ActorSubclass;
export declare const ACTOR_METHOD_WITH_HTTP_DETAILS = "http-details";
export declare const ACTOR_METHOD_WITH_CERTIFICATE = "certificate";
export {};
//# sourceMappingURL=actor.d.ts.map