@thru/wallet 0.2.22

package/dist/native.d.ts

@@ -0,0 +1,329 @@
+import { Thru } from '@thru/sdk/client';
+
+declare const AddressType: {
+    readonly THRU: "thru";
+};
+type AddressType = (typeof AddressType)[keyof typeof AddressType];
+interface WalletAccount {
+    accountType: AddressType;
+    address: string;
+    label: string;
+}
+interface AppMetadata {
+    appId: string;
+    appName: string;
+    appUrl: string;
+    imageUrl?: string;
+}
+interface ConnectResult {
+    walletId?: string;
+    accounts: WalletAccount[];
+    selectedAccount?: WalletAccount | null;
+    status?: "pending" | "completed";
+    metadata?: AppMetadata;
+}
+declare const ThruTransactionEncoding: {
+    readonly SIGNING_PAYLOAD_BASE64: "signing_payload_base64";
+    readonly RAW_TRANSACTION_BASE64: "raw_transaction_base64";
+};
+type ThruTransactionEncoding = (typeof ThruTransactionEncoding)[keyof typeof ThruTransactionEncoding];
+interface ThruSigningContext {
+    mode: "managed_fee_payer";
+    selectedAccountPublicKey: string | null;
+    feePayerPublicKey: string;
+    signerPublicKey: string;
+    acceptedInputEncodings: ThruTransactionEncoding[];
+    outputEncoding: typeof ThruTransactionEncoding.RAW_TRANSACTION_BASE64;
+}
+interface ThruTransactionReviewSimulation {
+    before?: string;
+    after?: string;
+}
+interface ThruTransactionReviewAbiReflection {
+    label?: string;
+    kind?: string | null;
+    typeName?: string;
+    value?: unknown;
+    rawHex?: string;
+    source?: string;
+    error?: string;
+}
+interface ThruTransactionReviewPayload {
+    appName?: string;
+    programAddress?: string;
+    abiName?: string;
+    instruction?: string;
+    simulation?: ThruTransactionReviewSimulation;
+    abiReflection?: ThruTransactionReviewAbiReflection;
+}
+interface ThruTransactionIntent {
+    walletAddress?: string;
+    programAddress: string;
+    instructionData: string;
+    readWriteAddresses?: string[];
+    readOnlyAddresses?: string[];
+    review?: ThruTransactionReviewPayload;
+}
+interface SignMessageParams {
+    message: string | Uint8Array;
+    networkId: string;
+}
+interface SignMessageResult {
+    signature: Uint8Array;
+    publicKey: string;
+}
+
+/**
+ * Minimal Thru chain interface exposed to SDK consumers.
+ * The concrete implementation will evolve as the Thru transaction
+ * flow is fleshed out, but maintaining a dedicated contract now
+ * keeps the Surface area aligned with other chain adapters.
+ */
+interface IThruChain {
+    /** Indicates whether the wallet has approved a Thru connection. */
+    readonly connected: boolean;
+    /**
+     * Initiate a Thru connection flow. Resolves with the connected address once
+     * the user has approved the request.
+     */
+    connect(): Promise<{
+        publicKey: string;
+    }>;
+    /** Disconnect the currently connected Thru account. */
+    disconnect(): Promise<void>;
+    /**
+     * Return the current embedded signing contract for Thru transactions.
+     *
+     * The selected account is the managed wallet account shown to the user.
+     * The fee payer / signer can differ when the wallet routes transactions
+     * through an embedded manager profile.
+     */
+    getSigningContext(): Promise<ThruSigningContext>;
+    /**
+     * Sign a wallet-managed transaction intent and return canonical raw
+     * transaction bytes encoded as base64. The wallet owns fee payer choice,
+     * account ordering, headers, nonces, and final wire layout.
+     */
+    signTransaction(transaction: ThruTransactionIntent): Promise<string>;
+}
+
+declare const POST_MESSAGE_REQUEST_TYPES: {
+    readonly CONNECT: "connect";
+    readonly DISCONNECT: "disconnect";
+    readonly SIGN_MESSAGE: "signMessage";
+    readonly SIGN_TRANSACTION: "signTransaction";
+    readonly GET_ACCOUNTS: "getAccounts";
+    readonly GET_CONNECTION_STATE: "getConnectionState";
+    readonly GET_SIGNING_CONTEXT: "getSigningContext";
+    readonly SELECT_ACCOUNT: "selectAccount";
+    readonly MANAGE_ACCOUNTS: "manageAccounts";
+};
+declare const EMBEDDED_PROVIDER_EVENTS: {
+    readonly CONNECT_START: "connect_start";
+    readonly CONNECT: "connect";
+    readonly DISCONNECT: "disconnect";
+    readonly CONNECT_ERROR: "connect_error";
+    readonly ERROR: "error";
+    readonly LOCK: "lock";
+    readonly UI_SHOW: "ui_show";
+    readonly ACCOUNT_CHANGED: "account_changed";
+};
+interface GetConnectionStateResult {
+    isAuthorized: boolean;
+    isConnected: boolean;
+    isUnlocked: boolean;
+    hasPasskey: boolean;
+    hasWalletAccount: boolean;
+    accounts: WalletAccount[];
+    selectedAccount: WalletAccount | null;
+    metadata: AppMetadata | null;
+}
+interface ManageAccountsResult {
+    accounts: WalletAccount[];
+    selectedAccount: WalletAccount | null;
+}
+declare const ErrorCode: {
+    readonly USER_REJECTED: "USER_REJECTED";
+    readonly WALLET_LOCKED: "WALLET_LOCKED";
+    readonly INVALID_PASSWORD: "INVALID_PASSWORD";
+    readonly ALREADY_CONNECTED: "ALREADY_CONNECTED";
+    readonly ACCOUNT_NOT_FOUND: "ACCOUNT_NOT_FOUND";
+    readonly ACCOUNT_CHANGED: "ACCOUNT_CHANGED";
+    readonly INVALID_TRANSACTION: "INVALID_TRANSACTION";
+    readonly TRANSACTION_FAILED: "TRANSACTION_FAILED";
+    readonly INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+type ConnectMetadataInput = Partial<AppMetadata>;
+type ConnectIntent = "default" | "switch-account";
+interface ConnectRequestPayload {
+    metadata?: ConnectMetadataInput;
+    preferredAccountAddress?: string;
+    intent?: ConnectIntent;
+}
+
+interface WebViewRefLike {
+    injectJavaScript: (script: string) => void;
+}
+interface WebViewMessageEventLike {
+    nativeEvent: {
+        data: string;
+    };
+}
+
+type IosWebViewMode = "direct" | "shell-iframe";
+type WalletAvailability = {
+    status: "checking";
+    isAuthorized: false;
+    isConnected: false;
+    isUnlocked: false;
+    hasPasskey: false;
+    hasWalletAccount: false;
+    accounts: WalletAccount[];
+    selectedAccount: null;
+    metadata: null;
+    error: null;
+} | {
+    status: "ready";
+    isAuthorized: boolean;
+    isConnected: boolean;
+    isUnlocked: boolean;
+    hasPasskey: boolean;
+    hasWalletAccount: boolean;
+    accounts: WalletAccount[];
+    selectedAccount: WalletAccount | null;
+    metadata: AppMetadata | null;
+    error: null;
+} | {
+    status: "error";
+    isAuthorized: false;
+    isConnected: false;
+    isUnlocked: false;
+    hasPasskey: false;
+    hasWalletAccount: false;
+    accounts: WalletAccount[];
+    selectedAccount: null;
+    metadata: null;
+    error: Error;
+};
+interface NativeSDKConfig {
+    walletUrl?: string;
+    /** Stamped on every postMessage so wallet's ConnectedAppsStorage can
+        scope per-host. Default: 'thru-mobile://app'. */
+    origin?: string;
+    rpcUrl?: string;
+    addressTypes?: AddressType[];
+    /** iOS-only host mode. Shell iframe is the default; direct is kept
+        as an escape hatch for real-device passkey/WebAuthn comparisons. */
+    iosWebViewMode?: IosWebViewMode;
+    /** Optional host-provided persistent storage (SecureStore,
+        AsyncStorage, localStorage-compatible adapter, etc.). */
+    storage?: NativeSDKStorage;
+    /** Override the legacy connection snapshot key cleared from `storage`. */
+    storageKey?: string;
+    /** Override the key used to remember the app-local selected account. */
+    selectedAccountStorageKey?: string;
+}
+interface SignInOptions {
+    app_id: string;
+    app_display_name: string;
+    app_url?: string;
+    image_url?: string;
+    intent?: ConnectOptions["intent"];
+}
+interface ConnectOptions {
+    metadata?: ConnectMetadataInput;
+    preferredAccountAddress?: string;
+    intent?: ConnectRequestPayload["intent"];
+}
+interface RestoreConnectionOptions {
+    hydrate?: boolean;
+}
+type SDKEvent = "connect" | "disconnect" | "lock" | "error" | "accountChanged" | "availabilityChanged";
+type EventCallback = (...args: any[]) => void;
+interface NativeSDKStorage {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+}
+interface NativeSDKUiHandlers {
+    onShowRequested?: () => void;
+    onHideRequested?: () => void;
+}
+/**
+ * NativeSDK - mobile mirror of `@thru/wallet`'s `BrowserSDK`.
+ * Public surface matches verbatim except `mountInline(HTMLElement)` is
+ * replaced by `attachWebView(WebViewRefLike)` since the host bottom
+ * sheet owns the WebView lifecycle.
+ */
+declare class NativeSDK {
+    private provider;
+    private eventListeners;
+    private initialized;
+    private thruClient;
+    private rpcUrl;
+    private connectInFlight;
+    private lastConnectResult;
+    private walletAvailability;
+    private readonly origin;
+    private readonly storage?;
+    private readonly storageKey;
+    private readonly selectedAccountStorageKey;
+    private readonly iosWebViewMode;
+    constructor(config?: NativeSDKConfig);
+    /** Hand the WebView ref to the underlying provider/bridge. */
+    attachWebView(ref: WebViewRefLike): void;
+    /** Mark a direct top-level WebView wallet document as ready. */
+    markWebViewReady(): void;
+    /** Bind to the WebView's `onMessage` handler. */
+    onMessage: (event: WebViewMessageEventLike) => void;
+    /** Build the URL to load inside the shell <iframe>. */
+    getIframeSrc(): string;
+    /** Wallet origin (e.g. https://wallet.thru.org). */
+    getWalletOrigin(): string;
+    /** Bind host UI lifecycle handlers used by custom WebView hosts. */
+    setUiHandlers(handlers: NativeSDKUiHandlers): void;
+    clearUiHandlers(): void;
+    /** Reject in-flight wallet requests after a user-driven host dismiss. */
+    rejectPendingRequests(message?: string): void;
+    /** iOS WebView host mode. Non-iOS hosts should ignore this value. */
+    getIosWebViewMode(): IosWebViewMode;
+    initialize(): Promise<void>;
+    connect(options?: ConnectOptions): Promise<ConnectResult>;
+    signIn(options: SignInOptions): Promise<ConnectResult>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getWalletAvailability(): WalletAvailability;
+    restoreConnection(options?: RestoreConnectionOptions): Promise<ConnectResult | null>;
+    syncConnectionState(options?: ConnectOptions): Promise<GetConnectionStateResult | null>;
+    refreshWalletAvailability(options?: ConnectOptions): Promise<WalletAvailability>;
+    getAccounts(): WalletAccount[];
+    getSelectedAccount(): WalletAccount | null;
+    selectAccount(publicKey: string): Promise<WalletAccount>;
+    manageAccounts(): Promise<ManageAccountsResult>;
+    get thru(): IThruChain;
+    on(event: SDKEvent, callback: EventCallback): void;
+    off(event: SDKEvent, callback: EventCallback): void;
+    once(event: SDKEvent, callback: EventCallback): void;
+    destroy(): void;
+    /** Lazily-instantiated Thru chain client. */
+    getThru(): Thru;
+    private emit;
+    private setupEventForwarding;
+    private requestConnectionState;
+    private applyConnectionState;
+    private setWalletAvailability;
+    private clearAuthorizedAvailability;
+    private resolveMetadata;
+    private resolveSignInMetadata;
+    private refreshCachedAccounts;
+    private applyPreferredSelectedAccount;
+    private persistSelectedAccountAddress;
+    private clearPersistedConnection;
+    private readSelectedAccountAddress;
+}
+
+export { AddressType, type AppMetadata, type ConnectMetadataInput, type ConnectOptions, type ConnectResult, EMBEDDED_PROVIDER_EVENTS, ErrorCode, type EventCallback, type GetConnectionStateResult, type IThruChain, type IosWebViewMode, type ManageAccountsResult, NativeSDK, type NativeSDKConfig, type NativeSDKStorage, type NativeSDKUiHandlers, POST_MESSAGE_REQUEST_TYPES, type RestoreConnectionOptions, type SDKEvent, type SignInOptions, type SignMessageParams, type SignMessageResult, type ThruSigningContext, ThruTransactionEncoding, type ThruTransactionIntent, type WalletAccount, type WalletAvailability };