accounts/dist/core/Remote.d.ts

Tempo Accounts SDK

import { type RpcRequest } from 'ox';
import * as Provider from 'ox/Provider';
import * as RpcResponse from 'ox/RpcResponse';
import type { StoreApi } from 'zustand/vanilla';
import type * as Messenger from '../core/Messenger.js';
import type * as CoreProvider from '../core/Provider.js';
import * as Schema from '../core/Schema.js';
import type { OneOf } from '../internal/types.js';
/** A remote JSON-RPC request tracked across the host/remote boundary. */
export type Request<result = unknown> = OneOf<{
    /** JSON-RPC request sent to the remote. */
    request: RpcRequest.RpcRequest;
    /** Request is waiting for a remote response. */
    status: 'pending';
} | {
    /** JSON-RPC request sent to the remote. */
    request: RpcRequest.RpcRequest;
    /** Resolved RPC result. */
    result: result;
    /** Request completed successfully. */
    status: 'success';
} | {
    /** JSON-RPC request sent to the remote. */
    request: RpcRequest.RpcRequest;
    /** RPC error returned by the remote. */
    error: RpcResponse.ErrorObject;
    /** Request completed with an error. */
    status: 'error';
}>;
/** Request queue payload synced from a host adapter instance to the remote app. */
export type Sync = {
    /** Active account for the request source, or `undefined` if none is selected. */
    account: {
        address: string;
    } | undefined;
    /** Chain ID for the request source. */
    chainId: number;
    /** Pending request queue sent to the remote auth app. */
    requests: readonly Request[];
};
/** State managed by the remote (dialog) side. */
export type State = {
    /** Whether the dialog is rendered in an iframe or popup. */
    mode: 'iframe' | 'popup' | undefined;
    /** Trusted host origin from MessageEvent. */
    origin: string | undefined;
    /** Whether the dialog is ready to display content. */
    ready: boolean;
    /** Queued RPC requests received from the host. */
    requests: readonly Request[];
};
/** Remote context — bundles messenger, provider, and remote store. */
export type Remote = {
    /**
     * Messenger for remote communication.
     */
    messenger: Messenger.Bridge;
    /**
     * Provider instance for executing RPC methods.
     */
    provider: CoreProvider.Provider;
    /**
     * Remote context store.
     */
    store: StoreApi<State>;
    /**
     * Hostnames trusted to render the embed in an iframe.
     */
    trustedHosts: readonly string[];
    /**
     * Subscribes to user-facing RPC requests from the parent context.
     *
     * Syncs the host's active chain, updates the remote store, and invokes
     * the callback with the first pending request (or `null` when the queue
     * is cleared, signalling the UI should close).
     *
     * @param cb - Callback receiving the request payload.
     * @returns Unsubscribe function.
     */
    onUserRequest: (cb: (payload: onUserRequest.Payload) => void | Promise<void>) => () => void;
    /**
     * Subscribes to incoming RPC requests from the parent context.
     * Updates the remote store with the received requests and syncs the
     * host's active chain to the remote provider.
     *
     * @param cb - Callback receiving the full queued request list.
     * @returns Unsubscribe function.
     */
    onRequests: (cb: (requests: readonly Request[], event: MessageEvent, extra: {
        account: {
            address: string;
        } | undefined;
    }) => void) => () => void;
    /**
     * Signals readiness to the host and begins accepting requests.
     * Call this after the remote context is fully initialized.
     */
    ready: (options?: ready.Options | undefined) => void;
    /**
     * Reject an RPC request.
     */
    reject: (request: Request['request'], error?: Provider.ProviderRpcError | RpcResponse.BaseError | undefined) => void;
    /** Reject all pending RPC requests. */
    rejectAll: (error?: Provider.ProviderRpcError | RpcResponse.BaseError | undefined) => void;
    /**
     * Respond to an RPC request.
     *
     * When `options.result` is provided, sends it directly.
     * When `options.error` is provided, sends an error response.
     * Otherwise, executes `provider.request(request)` and sends the result.
     */
    respond: (request: Request['request'], options?: respond.Options) => Promise<unknown>;
};
export declare namespace onUserRequest {
    type Payload = {
        /** Active account on the host side. */
        account: {
            address: string;
        } | undefined;
        /** Origin of the host that opened this dialog. */
        origin: string;
        /** The pending request to display, or `null` when the dialog should close. */
        request: Request['request'] | null;
    };
}
export declare namespace ready {
    type Options = Messenger.ReadyOptions & {
        /** Authenticated account addresses. When provided, the wallet responds to SDK sync requests. */
        accounts?: readonly string[] | undefined;
    };
}
export declare namespace respond {
    type Options = {
        /** Return the resolved result without sending the RPC response. */
        defer?: boolean | undefined;
        /** Error to respond with (takes precedence over result). */
        error?: {
            code: number;
            message: string;
        } | undefined;
        /**
         * Called when `provider.request()` throws. Return `true` to suppress the
         * error response to the parent — the dialog stays open and can show a
         * recovery UI. The error is still re-thrown to the caller.
         */
        onError?: ((error: Error) => boolean | void) | undefined;
        /** Explicit result — if omitted, calls `provider.request(request)`. */
        result?: unknown | undefined;
        /** Transform the result before sending. */
        selector?: ((result: any) => unknown) | undefined;
    };
}
/** Creates a remote context for the dialog app. */
export declare function create(options: create.Options): Remote;
export declare namespace create {
    type Options = {
        /** Bridge messenger for cross-frame communication. */
        messenger: Messenger.Bridge;
        /** Provider to execute RPC requests against. */
        provider: CoreProvider.Provider;
        /** Hostnames trusted to render the embed in an iframe. */
        trustedHosts?: readonly string[] | undefined;
    };
}
/** Returns an inert remote context for SSR environments. */
export declare function noop(): Remote;
/**
 * Validates an RPC request from search params.
 *
 * Parses against the `Schema.Request` discriminated union, checks the
 * method matches, and enforces strict parameter schemas (e.g. required
 * `limits`) unless `strict` is false. On failure, rejects all pending
 * requests via the messenger and re-throws so the router can handle the
 * error boundary.
 */
export declare function validateSearch<const method extends Schema.Request['method']>(remote: Remote, search: Record<string, unknown>, parameters: validateSearch.Options<method>): validateSearch.ReturnType<method>;
export declare namespace validateSearch {
    type Options<method extends Schema.Request['method']> = {
        /** Expected RPC method for this route. */
        method: method;
        /** Whether to apply strict parameter policy validation. */
        strict?: boolean | undefined;
    };
    type ReturnType<method extends Schema.Request['method']> = Extract<Schema.Request, {
        method: method;
    }> & {
        id: number;
        jsonrpc: '2.0';
        _decoded: Extract<Schema.Request, {
            method: method;
        }>;
        _returnType: unknown;
    };
}
//# sourceMappingURL=Remote.d.ts.map