@tonconnect/sdk 3.0.2-beta.0 → 3.0.3-beta.0

package/lib/types/index.d.ts

@@ -18,6 +18,11 @@ export declare interface Account {
     publicKey?: string;
 }
 
+/**
+ * Requested authentication type: 'ton_addr' or 'ton_proof'.
+ */
+export declare type AuthType = ConnectItem['name'];
+
 /**
  * Thrown when request to the wallet contains errors.
  */
@@ -26,11 +31,39 @@ export declare class BadRequestError extends TonConnectError {
     constructor(...args: ConstructorParameters<typeof TonConnectError>);
 }
 
+/**
+ * A concrete implementation of EventDispatcher that dispatches events to the browser window.
+ */
+export declare class BrowserEventDispatcher<T> implements EventDispatcher<T> {
+    /**
+     * The window object, possibly undefined in a server environment.
+     * @private
+     */
+    private readonly window;
+    /**
+     * Dispatches an event with the given name and details to the browser window.
+     * @param eventName - The name of the event to dispatch.
+     * @param eventDetails - The details of the event to dispatch.
+     * @returns A promise that resolves when the event has been dispatched.
+     */
+    dispatchEvent(eventName: string, eventDetails: T): Promise<void>;
+}
+
 export declare enum CHAIN {
     MAINNET = "-239",
     TESTNET = "-3"
 }
 
+export declare enum CONNECT_EVENT_ERROR_CODES {
+    UNKNOWN_ERROR = 0,
+    BAD_REQUEST_ERROR = 1,
+    MANIFEST_NOT_FOUND_ERROR = 2,
+    MANIFEST_CONTENT_ERROR = 3,
+    UNKNOWN_APP_ERROR = 100,
+    USER_REJECTS_ERROR = 300,
+    METHOD_NOT_SUPPORTED = 400
+}
+
 export declare enum CONNECT_ITEM_ERROR_CODES {
     UNKNOWN_ERROR = 0,
     METHOD_NOT_SUPPORTED = 400
@@ -43,6 +76,125 @@ export declare interface ConnectAdditionalRequest {
     tonProof?: string;
 }
 
+/**
+ * Successful connection event when a user successfully connected a wallet.
+ */
+export declare type ConnectionCompletedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-completed';
+} & ConnectionInfo;
+
+/**
+ * Connection error event when a user cancels a connection or there is an error during the connection process.
+ */
+export declare type ConnectionErrorEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-error';
+    /**
+     * Reason for the error.
+     */
+    error_message: string;
+    /**
+     * Error code.
+     */
+    error_code: CONNECT_EVENT_ERROR_CODES | null;
+};
+
+/**
+ * Connection events.
+ */
+export declare type ConnectionEvent = ConnectionStartedEvent | ConnectionCompletedEvent | ConnectionErrorEvent;
+
+/**
+ * Information about a connected wallet.
+ */
+export declare type ConnectionInfo = {
+    /**
+     * Connected wallet address.
+     */
+    wallet_address: string | null;
+    /**
+     * Wallet type: 'tonkeeper', 'tonhub', etc.
+     */
+    wallet_type: string | null;
+    /**
+     * Wallet version.
+     */
+    wallet_version: string | null;
+    /**
+     * Requested authentication types.
+     */
+    auth_type: AuthType;
+    /**
+     * Custom data for the connection.
+     */
+    custom_data: {
+        /**
+         * Connected chain ID.
+         */
+        chain_id: string | null;
+        /**
+         * Wallet provider.
+         */
+        provider: 'http' | 'injected' | null;
+    };
+};
+
+/**
+ * Connection restoring completed event when successfully restored a connection.
+ */
+export declare type ConnectionRestoringCompletedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-restoring-completed';
+} & ConnectionInfo;
+
+/**
+ * Connection restoring error event when there is an error during the connection restoring process.
+ */
+export declare type ConnectionRestoringErrorEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-restoring-error';
+    /**
+     * Reason for the error.
+     */
+    error_message: string;
+};
+
+/**
+ * Connection restoring events.
+ */
+export declare type ConnectionRestoringEvent = ConnectionRestoringStartedEvent | ConnectionRestoringCompletedEvent | ConnectionRestoringErrorEvent;
+
+/**
+ * Connection restoring started event when initiates a connection restoring process.
+ */
+export declare type ConnectionRestoringStartedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-restoring-started';
+};
+
+/**
+ * Initial connection event when a user initiates a connection.
+ */
+export declare type ConnectionStartedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-started';
+};
+
+export declare type ConnectItem = TonAddressItem | TonProofItem;
+
 export declare type ConnectItemReplyError<T> = {
     name: T;
     error: {
@@ -51,6 +203,73 @@ export declare type ConnectItemReplyError<T> = {
     };
 };
 
+/**
+ * Create a connection completed event.
+ * @param wallet
+ */
+export declare function createConnectionCompletedEvent(wallet: Wallet | null): ConnectionCompletedEvent;
+
+/**
+ * Create a connection error event.
+ * @param error_message
+ * @param errorCode
+ */
+export declare function createConnectionErrorEvent(error_message: string, errorCode: CONNECT_EVENT_ERROR_CODES | void): ConnectionErrorEvent;
+
+/**
+ * Create a connection restoring completed event.
+ * @param wallet
+ */
+export declare function createConnectionRestoringCompletedEvent(wallet: Wallet | null): ConnectionRestoringCompletedEvent;
+
+/**
+ * Create a connection restoring error event.
+ * @param errorMessage
+ */
+export declare function createConnectionRestoringErrorEvent(errorMessage: string): ConnectionRestoringErrorEvent;
+
+/**
+ * Create a connection restoring started event.
+ */
+export declare function createConnectionRestoringStartedEvent(): ConnectionRestoringStartedEvent;
+
+/**
+ * Create a connection init event.
+ */
+export declare function createConnectionStartedEvent(): ConnectionStartedEvent;
+
+/**
+ * Create a disconnect event.
+ * @param wallet
+ * @param scope
+ * @returns
+ */
+export declare function createDisconnectionEvent(wallet: Wallet | null, scope: 'dapp' | 'wallet'): DisconnectionEvent;
+
+/**
+ * Create a transaction init event.
+ * @param wallet
+ * @param transaction
+ */
+export declare function createTransactionSentForSignatureEvent(wallet: Wallet | null, transaction: SendTransactionRequest): TransactionSentForSignatureEvent;
+
+/**
+ * Create a transaction signed event.
+ * @param wallet
+ * @param transaction
+ * @param signedTransaction
+ */
+export declare function createTransactionSignedEvent(wallet: Wallet | null, transaction: SendTransactionRequest, signedTransaction: SendTransactionResponse): TransactionSignedEvent;
+
+/**
+ * Create a transaction error event.
+ * @param wallet
+ * @param transaction
+ * @param errorMessage
+ * @param errorCode
+ */
+export declare function createTransactionSigningFailedEvent(wallet: Wallet | null, transaction: SendTransactionRequest, errorMessage: string, errorCode: SEND_TRANSACTION_ERROR_CODES | void): TransactionSigningFailedEvent;
+
 export declare interface DappMetadata {
     /**
      * Dapp name. Might be simple, will not be used as identifier.
@@ -78,8 +297,34 @@ export declare interface DeviceInfo {
     features: Feature[];
 }
 
+/**
+ * Disconnect event when a user initiates a disconnection.
+ */
+export declare type DisconnectionEvent = {
+    /**
+     * Event type.
+     */
+    type: 'disconnection';
+    /**
+     * Disconnect scope: 'dapp' or 'wallet'.
+     */
+    scope: 'dapp' | 'wallet';
+} & ConnectionInfo;
+
 export declare function encodeTelegramUrlParameters(parameters: string): string;
 
+/**
+ * Interface for an event dispatcher that sends events.
+ */
+export declare interface EventDispatcher<T> {
+    /**
+     * Dispatches an event with the given name and details.
+     * @param eventName - The name of the event to dispatch.
+     * @param eventDetails - The details of the event to dispatch.
+     */
+    dispatchEvent(eventName: string, eventDetails: T): Promise<void>;
+}
+
 export declare type Feature = SendTransactionFeatureDeprecated | SendTransactionFeature | SignDataFeature;
 
 /**
@@ -228,6 +473,19 @@ export declare class ParseHexError extends TonConnectError {
     constructor(...args: ConstructorParameters<typeof TonConnectError>);
 }
 
+/**
+ * User action events.
+ */
+export declare type SdkActionEvent = ConnectionEvent | ConnectionRestoringEvent | DisconnectionEvent | TransactionSigningEvent;
+
+export declare enum SEND_TRANSACTION_ERROR_CODES {
+    UNKNOWN_ERROR = 0,
+    BAD_REQUEST_ERROR = 1,
+    UNKNOWN_APP_ERROR = 100,
+    USER_REJECTS_ERROR = 300,
+    METHOD_NOT_SUPPORTED = 400
+}
+
 export declare type SendTransactionFeature = {
     name: 'SendTransaction';
     maxMessages: number;
@@ -282,6 +540,10 @@ export declare type SignDataFeature = {
     name: 'SignData';
 };
 
+export declare interface TonAddressItem {
+    name: 'ton_addr';
+}
+
 declare class TonConnect implements ITonConnect {
     private static readonly walletsList;
     /**
@@ -298,6 +560,11 @@ declare class TonConnect implements ITonConnect {
      * Returns available wallets list.
      */
     static getWallets(): Promise<WalletInfo[]>;
+    /**
+     * Emits user action event to the EventDispatcher. By default, it uses `window.dispatchEvent` for browser environment.
+     * @private
+     */
+    private readonly tracker;
     private readonly walletsList;
     private readonly dappSettings;
     private readonly bridgeConnectionStorage;
@@ -419,6 +686,10 @@ export declare interface TonConnectOptions {
      * Storage to save protocol data. For browser default is `localStorage`. If you use SDK with nodeJS, you have to specify this field.
      */
     storage?: IStorage;
+    /**
+     * Event dispatcher to track user actions. By default, it uses `window.dispatchEvent` for browser environment.
+     */
+    eventDispatcher?: EventDispatcher<SdkActionEvent>;
     /**
      * Redefine wallets list source URL. Must be a link to a json file with [following structure]{@link https://github.com/ton-connect/wallets-list}
      * @default https://raw.githubusercontent.com/ton-connect/wallets-list/main/wallets.json
@@ -436,6 +707,11 @@ export declare interface TonConnectOptions {
     disableAutoPauseConnection?: boolean;
 }
 
+export declare interface TonProofItem {
+    name: 'ton_proof';
+    payload: string;
+}
+
 export declare type TonProofItemReply = TonProofItemReplySuccess | TonProofItemReplyError;
 
 export declare type TonProofItemReplyError = ConnectItemReplyError<TonProofItemReplySuccess['name']>;
@@ -460,6 +736,85 @@ export declare interface TonProofItemReplySuccess {
  */
 export declare function toUserFriendlyAddress(hexAddress: string, testOnly?: boolean): string;
 
+/**
+ * Transaction information.
+ */
+export declare type TransactionInfo = {
+    /**
+     * Transaction validity time in unix timestamp.
+     */
+    valid_until: string | null;
+    /**
+     * Sender address.
+     */
+    from: string | null;
+    /**
+     * Transaction messages.
+     */
+    messages: TransactionMessage[];
+};
+
+/**
+ * Transaction message.
+ */
+export declare type TransactionMessage = {
+    /**
+     * Recipient address.
+     */
+    address: string | null;
+    /**
+     * Transfer amount.
+     */
+    amount: string | null;
+};
+
+/**
+ * Initial transaction event when a user initiates a transaction.
+ */
+export declare type TransactionSentForSignatureEvent = {
+    /**
+     * Event type.
+     */
+    type: 'transaction-sent-for-signature';
+} & ConnectionInfo & TransactionInfo;
+
+/**
+ * Transaction signed event when a user successfully signed a transaction.
+ */
+export declare type TransactionSignedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'transaction-signed';
+    /**
+     * Signed transaction.
+     */
+    signed_transaction: string;
+} & ConnectionInfo & TransactionInfo;
+
+/**
+ * Transaction events.
+ */
+export declare type TransactionSigningEvent = TransactionSentForSignatureEvent | TransactionSignedEvent | TransactionSigningFailedEvent;
+
+/**
+ * Transaction error event when a user cancels a transaction or there is an error during the transaction process.
+ */
+export declare type TransactionSigningFailedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'transaction-signing-failed';
+    /**
+     * Reason for the error.
+     */
+    error_message: string;
+    /**
+     * Error code.
+     */
+    error_code: SEND_TRANSACTION_ERROR_CODES | null;
+} & ConnectionInfo & TransactionInfo;
+
 /**
  * Thrown when app tries to send rpc request to the injected wallet while not connected.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonconnect/sdk",
-  "version": "3.0.2-beta.0",
+  "version": "3.0.3-beta.0",
   "scripts": {
     "build": "npx rimraf types-dist && npx rimraf lib && npx rollup -c rollup.config.mjs && ttsc --project tsconfig.declarations.json && api-extractor run && npx rimraf types-dist && npx rimraf dist && npx webpack --config webpack.config.js",
     "test": "vitest run"