@dfinity/agent/lib/esm/agent/http/index.d.ts

JavaScript and TypeScript library to interact with the Internet Computer

import { type JsonObject } from '@dfinity/candid';
import { Principal } from '@dfinity/principal';
import { type Identity } from '../../auth.ts';
import { type Agent, type ApiQueryResponse, type QueryFields, type ReadStateOptions, type ReadStateResponse, type SubmitResponse } from '../api.ts';
import { Expiry } from './transforms.ts';
import { type HttpAgentRequest, type HttpAgentRequestTransformFn, type Nonce } from './types.ts';
import { type SubnetStatus } from '../../canisterStatus/index.ts';
import { ObservableLog } from '../../observable.ts';
import { type BackoffStrategyFactory } from '../../polling/backoff.ts';
export * from './transforms.ts';
export { type Nonce, makeNonce } from './types.ts';
export declare enum RequestStatusResponseStatus {
    Received = "received",
    Processing = "processing",
    Replied = "replied",
    Rejected = "rejected",
    Unknown = "unknown",
    Done = "done"
}
export declare const IC_ROOT_KEY: string;
export declare const MANAGEMENT_CANISTER_ID = "aaaaa-aa";
export interface HttpAgentOptions {
    fetch?: typeof fetch;
    fetchOptions?: Record<string, unknown>;
    callOptions?: Record<string, unknown>;
    host?: string;
    identity?: Identity | Promise<Identity>;
    /**
     * The maximum time a request can be delayed before being rejected.
     * @default 5 minutes
     */
    ingressExpiryInMinutes?: number;
    credentials?: {
        name: string;
        password?: string;
    };
    /**
     * Adds a unique {@link Nonce} with each query.
     * Enabling will prevent queries from being answered with a cached response.
     * @example
     * const agent = new HttpAgent({ useQueryNonces: true });
     * agent.addTransform(makeNonceTransform(makeNonce);
     * @default false
     */
    useQueryNonces?: boolean;
    /**
     * Number of times to retry requests before throwing an error
     * @default 3
     */
    retryTimes?: number;
    /**
     * The strategy to use for backoff when retrying requests
     */
    backoffStrategy?: BackoffStrategyFactory;
    /**
     * Whether the agent should verify signatures signed by node keys on query responses. Increases security, but adds overhead and must make a separate request to cache the node keys for the canister's subnet.
     * @default true
     */
    verifyQuerySignatures?: boolean;
    /**
     * Whether to log to the console. Defaults to false.
     */
    logToConsole?: boolean;
    /**
     * Alternate root key to use for verifying certificates. If not provided, the default IC root key will be used.
     */
    rootKey?: Uint8Array;
    /**
     * Whether or not the root key should be automatically fetched during construction. Defaults to false.
     */
    shouldFetchRootKey?: boolean;
    /**
     * Whether or not to sync the time with the network during construction. Defaults to false.
     */
    shouldSyncTime?: boolean;
}
interface V1HttpAgentInterface {
    _identity: Promise<Identity> | null;
    readonly _fetch: typeof fetch;
    readonly _fetchOptions?: Record<string, unknown>;
    readonly _callOptions?: Record<string, unknown>;
    readonly _host: URL;
    readonly _credentials: string | undefined;
    readonly _retryTimes: number;
    _isAgent: true;
}
/**
 * A HTTP agent allows users to interact with a client of the internet computer
using the available methods. It exposes an API that closely follows the
public view of the internet computer, and is not intended to be exposed
directly to the majority of users due to its low-level interface.
 * There is a pipeline to apply transformations to the request before sending
it to the client. This is to decouple signature, nonce generation and
other computations so that this class can stay as simple as possible while
allowing extensions.
 */
export declare class HttpAgent implements Agent {
    #private;
    rootKey: Uint8Array | null;
    readonly host: URL;
    readonly _isAgent = true;
    config: HttpAgentOptions;
    log: ObservableLog;
    /**
     * @param options - Options for the HttpAgent
     * @deprecated Use `HttpAgent.create` or `HttpAgent.createSync` instead
     */
    constructor(options?: HttpAgentOptions);
    static createSync(options?: HttpAgentOptions): HttpAgent;
    static create(options?: HttpAgentOptions): Promise<HttpAgent>;
    static from(agent: Pick<HttpAgent, 'config'> | V1HttpAgentInterface): Promise<HttpAgent>;
    isLocal(): boolean;
    addTransform(type: 'update' | 'query', fn: HttpAgentRequestTransformFn, priority?: number): void;
    getPrincipal(): Promise<Principal>;
    /**
     * Makes a call to a canister method.
     * @param canisterId - The ID of the canister to call. Can be a Principal or a string.
     * @param options - Options for the call.
     * @param options.methodName - The name of the method to call.
     * @param options.arg - The argument to pass to the method, as a Uint8Array.
     * @param options.effectiveCanisterId - (Optional) The effective canister ID, if different from the target canister ID.
     * @param options.callSync - (Optional) Whether to use synchronous call mode. Defaults to true.
     * @param options.nonce - (Optional) A unique nonce for the request. If provided, it will override any nonce set by transforms.
     * @param identity - (Optional) The identity to use for the call. If not provided, the agent's current identity will be used.
     * @returns A promise that resolves to the response of the call, including the request ID and response details.
     */
    call(canisterId: Principal | string, options: {
        methodName: string;
        arg: Uint8Array;
        effectiveCanisterId?: Principal | string;
        callSync?: boolean;
        nonce?: Uint8Array | Nonce;
    }, identity?: Identity | Promise<Identity>): Promise<SubmitResponse>;
    query(canisterId: Principal | string, fields: QueryFields, identity?: Identity | Promise<Identity>): Promise<ApiQueryResponse>;
    createReadStateRequest(fields: ReadStateOptions, identity?: Identity | Promise<Identity>): Promise<any>;
    readState(canisterId: Principal | string, fields: ReadStateOptions, _identity?: Identity | Promise<Identity>, request?: any): Promise<ReadStateResponse>;
    parseTimeFromResponse(response: {
        certificate: Uint8Array;
    }): number;
    /**
     * Allows agent to sync its time with the network. Can be called during intialization or mid-lifecycle if the device's clock has drifted away from the network time. This is necessary to set the Expiry for a request
     * @param {Principal} canisterIdOverride - Pass a canister ID if you need to sync the time with a particular subnet. Uses the ICP ledger canister by default.
     */
    syncTime(canisterIdOverride?: Principal): Promise<void>;
    status(): Promise<JsonObject>;
    fetchRootKey(): Promise<Uint8Array>;
    invalidateIdentity(): void;
    replaceIdentity(identity: Identity): void;
    fetchSubnetKeys(canisterId: Principal | string): Promise<SubnetStatus | undefined>;
    protected _transform(request: HttpAgentRequest): Promise<HttpAgentRequest>;
    /**
     * Returns the time difference in milliseconds between the IC network clock and the client's clock,
     * after the clock has been synced.
     *
     * If the time has not been synced, returns `0`.
     */
    getTimeDiffMsecs(): number;
    /**
     * Returns `true` if the time has been synced at least once with the IC network, `false` otherwise.
     */
    hasSyncedTime(): boolean;
}
/**
 * Calculates the ingress expiry time based on the maximum allowed expiry in minutes and the time difference in milliseconds.
 * The expiry is rounded down according to the {@link Expiry.fromDeltaInMilliseconds} method.
 * @param maxIngressExpiryInMinutes - The maximum ingress expiry time in minutes.
 * @param timeDiffMsecs - The time difference in milliseconds to adjust the expiry.
 * @returns The calculated ingress expiry as an Expiry object.
 */
export declare function calculateIngressExpiry(maxIngressExpiryInMinutes: number, timeDiffMsecs: number): Expiry;
//# sourceMappingURL=index.d.ts.map