@tonconnect/ui 2.0.0-beta.1 → 2.0.0-beta.10

package/lib/index.d.ts

@@ -131,6 +131,7 @@ interface ActionConfiguration {
      */
     twaReturnUrl?: `${string}://${string}`;
     /**
+     * @deprecated Shouldn't be used anymore, SDK will automatically detect return strategy for TWA-TWA connections.
      * Specifies whether the method should redirect user to the connected wallet
      * @default 'ios'
      */
@@ -160,6 +161,11 @@ interface TonConnectUiOptions {
      * Configuration for action-period (e.g. sendTransaction) UI elements: modals and notifications and wallet behaviour (return strategy).
      */
     actionsConfiguration?: ActionConfiguration;
+    /**
+     * Specifies whether the Android back button should be used to close modals and notifications on Android devices.
+     * @default true
+     */
+    enableAndroidBackHandler?: boolean;
 }
 
 declare type TonConnectUiCreateOptions = TonConnectUiOptionsWithConnector | TonConnectUiOptionsWithManifest;
@@ -189,7 +195,7 @@ interface TonConnectUiCreateOptionsBase extends TonConnectUiOptions {
     widgetRootId?: string;
 }
 
-declare type WalletOpenMethod = 'qrcode' | 'universal-link';
+declare type WalletOpenMethod = 'qrcode' | 'universal-link' | 'custom-deeplink';
 declare type WalletInfoWithOpenMethod = WalletInfoInjectable | WalletInfoRemoteWithOpenMethod | (WalletInfoInjectable & WalletInfoRemoteWithOpenMethod);
 declare type WalletInfoRemoteWithOpenMethod = WalletInfoRemote & {
     openMethod?: WalletOpenMethod;
@@ -205,16 +211,81 @@ declare type LoadableReady<T> = {
     value: T;
 };
 
+interface WalletsModal {
+    /**
+     * Open the modal.
+     */
+    open: () => void;
+    /**
+     * Close the modal.
+     */
+    close: () => void;
+    /**
+     * Subscribe to the modal window status changes.
+     */
+    onStateChange: (callback: (state: WalletsModalState) => void) => () => void;
+    /**
+     * Current modal window state.
+     */
+    state: WalletsModalState;
+}
+/**
+ * Opened modal window state.
+ */
+declare type WalletModalOpened = {
+    /**
+     * Modal window status.
+     */
+    status: 'opened';
+    /**
+     * Always `null` for opened modal window.
+     */
+    closeReason: null;
+};
+/**
+ * Closed modal window state.
+ */
+declare type WalletModalClosed = {
+    /**
+     * Modal window status.
+     */
+    status: 'closed';
+    /**
+     * Close reason, if the modal window was closed.
+     */
+    closeReason: WalletsModalCloseReason | null;
+};
+/**
+ * Modal window state.
+ */
+declare type WalletsModalState = WalletModalOpened | WalletModalClosed;
+/**
+ * Modal window close reason.
+ */
+declare type WalletsModalCloseReason = 'action-cancelled' | 'wallet-selected';
+
 declare class TonConnectUI {
     static getWallets(): Promise<WalletInfo[]>;
     private readonly walletInfoStorage;
     private readonly preferredWalletStorage;
-    readonly connector: ITonConnect;
     private walletInfo;
     private systemThemeChangeUnsubscribe;
     private actionsConfiguration?;
     private readonly walletsList;
     private connectRequestParametersCallback?;
+    /**
+     * TonConnect instance.
+     */
+    readonly connector: ITonConnect;
+    /**
+     * Manages the modal window state.
+     */
+    readonly modal: WalletsModal;
+    /**
+     * Manages the transaction modal window state.
+     * TODO: make it public when interface will be ready for external usage.
+     */
+    private readonly transactionModal;
     /**
      * Promise that resolves after end of th connection restoring process (promise will fire after `onStatusChange`, so you can get actual information about wallet and session after when promise resolved).
      * Resolved value `true`/`false` indicates if the session was restored successfully.
@@ -255,7 +326,26 @@ declare class TonConnectUI {
      */
     onStatusChange(callback: (wallet: ConnectedWallet | null) => void, errorsHandler?: (err: TonConnectError) => void): ReturnType<ITonConnect['onStatusChange']>;
     /**
+     * Opens the modal window, returns a promise that resolves after the modal window is opened.
+     */
+    openModal(): Promise<void>;
+    /**
+     * Closes the modal window.
+     */
+    closeModal(): void;
+    /**
+     * Subscribe to the modal window state changes, returns a function which has to be called to unsubscribe.
+     */
+    onModalStateChange(onChange: (state: WalletsModalState) => void): () => void;
+    /**
+     * Returns current modal window state.
+     */
+    get modalState(): WalletsModalState;
+    /**
+     * @deprecated Use `tonConnectUI.openModal()` instead. Will be removed in the next major version.
      * Opens the modal window and handles a wallet connection.
+     * @return Connected wallet.
+     * @throws TonConnectUIError if connection was aborted.
      */
     connectWallet(): Promise<ConnectedWallet>;
     /**
@@ -268,6 +358,48 @@ declare class TonConnectUI {
      * @param options modal and notifications behaviour settings. Default is show only 'before' modal and all notifications.
      */
     sendTransaction(tx: SendTransactionRequest, options?: ActionConfiguration): Promise<SendTransactionResponse>;
+    /**
+     * TODO: remove in the next major version.
+     * Initiates a connection with an embedded wallet, awaits its completion, and returns the connected wallet information.
+     * @param embeddedWallet - Information about the embedded wallet to connect to.
+     * @throws Error if the connection process fails.
+     * @internal
+     */
+    private connectEmbeddedWallet;
+    /**
+     * TODO: remove in the next major version.
+     * Initiates the connection process for an external wallet by opening the wallet modal
+     * and returns the connected wallet information upon successful connection.
+     * @throws Error if the user cancels the connection process or if the connection process fails.
+     * @internal
+     */
+    private connectExternalWallet;
+    /**
+     * TODO: remove in the next major version.
+     * Waits for a wallet connection based on provided options, returning connected wallet information.
+     * @param options - Configuration for connection statuses and errors handling.
+     * @options.ignoreErrors - If true, ignores errors during waiting, waiting continues until a valid wallet connects. Default is false.
+     * @options.abortSignal - Optional AbortSignal for external cancellation. Throws TonConnectUIError if aborted.
+     * @throws TonConnectUIError if waiting is aborted or no valid wallet connection is received and ignoreErrors is false.
+     * @internal
+     */
+    private waitForWalletConnection;
+    /**
+     * Waits for a transaction to be sent based on provided options, returning the transaction response.
+     * @param options - Configuration for transaction statuses and errors handling.
+     * @options.transaction - Transaction to send.
+     * @options.ignoreErrors - If true, ignores errors during waiting, waiting continues until a valid transaction is sent. Default is false.
+     * @options.abortSignal - Optional AbortSignal for external cancellation. Throws TonConnectUIError if aborted.
+     * @param onRequestSent (optional) will be called after the transaction is sent to the wallet.
+     * @throws TonConnectUIError if waiting is aborted or no valid transaction response is received and ignoreErrors is false.
+     * @internal
+     */
+    private waitForSendTransaction;
+    /**
+     * Subscribe to the transaction modal window state changes, returns a function which has to be called to unsubscribe.
+     * @internal
+     */
+    private onTransactionModalStateChange;
     private subscribeToWalletChange;
     private setPreferredWalletAppName;
     private getSelectedWalletInfo;
@@ -283,4 +415,4 @@ declare class TonConnectUIError extends TonConnectError {
     constructor(...args: ConstructorParameters<typeof Error>);
 }
 
-export { ActionConfiguration, BorderRadius, Color, ColorsSet, ConnectedWallet, Loadable, LoadableLoading, LoadableReady, Locales, PartialColorsSet, ReturnStrategy, THEME, Theme, TonConnectUI, TonConnectUIError, TonConnectUiCreateOptions, TonConnectUiCreateOptionsBase, TonConnectUiOptions, TonConnectUiOptionsWithConnector, TonConnectUiOptionsWithManifest, UIPreferences, UIWallet, WalletInfoRemoteWithOpenMethod, WalletInfoWithOpenMethod, WalletOpenMethod, WalletsListConfiguration };
+export { ActionConfiguration, BorderRadius, Color, ColorsSet, ConnectedWallet, Loadable, LoadableLoading, LoadableReady, Locales, PartialColorsSet, ReturnStrategy, THEME, Theme, TonConnectUI, TonConnectUIError, TonConnectUiCreateOptions, TonConnectUiCreateOptionsBase, TonConnectUiOptions, TonConnectUiOptionsWithConnector, TonConnectUiOptionsWithManifest, UIPreferences, UIWallet, WalletInfoRemoteWithOpenMethod, WalletInfoWithOpenMethod, WalletModalClosed, WalletModalOpened, WalletOpenMethod, WalletsListConfiguration, WalletsModal, WalletsModalCloseReason, WalletsModalState };