@tonconnect/sdk 3.0.2 → 3.0.3-beta.1

package/lib/types/index.d.ts

@@ -18,6 +18,13 @@ export declare interface Account {
     publicKey?: string;
 }
 
+export declare type AddTonConnectPrefix<T extends string> = `ton-connect-${T}` | `ton-connect-ui-${T}`;
+
+/**
+ * Requested authentication type: 'ton_addr' or 'ton_proof'.
+ */
+export declare type AuthType = ConnectItem['name'];
+
 /**
  * Thrown when request to the wallet contains errors.
  */
@@ -26,11 +33,53 @@ 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 extends {
+    type: string;
+}> 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<P extends AddTonConnectPrefix<T['type']>>(eventName: P, eventDetails: T & {
+        type: RemoveTonConnectPrefix<P>;
+    }): Promise<void>;
+    /**
+     * Adds an event listener to the browser window.
+     * @param eventName - The name of the event to listen for.
+     * @param listener - The listener to add.
+     * @param options - The options for the listener.
+     * @returns A function that removes the listener.
+     */
+    addEventListener<P extends AddTonConnectPrefix<T['type']>>(eventName: P, listener: (event: CustomEvent<T & {
+        type: RemoveTonConnectPrefix<P>;
+    }>) => void, options?: AddEventListenerOptions): 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 +92,157 @@ 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';
+    /**
+     * Connection success flag.
+     */
+    is_success: true;
+} & 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';
+    /**
+     * Connection success flag.
+     */
+    is_success: false;
+    /**
+     * Reason for the error.
+     */
+    error_message: string;
+    /**
+     * Error code.
+     */
+    error_code: CONNECT_EVENT_ERROR_CODES | null;
+    /**
+     * Custom data for the connection.
+     */
+    custom_data: Version;
+};
+
+/**
+ * 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;
+    } & Version;
+};
+
+/**
+ * Connection restoring completed event when successfully restored a connection.
+ */
+export declare type ConnectionRestoringCompletedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-restoring-completed';
+    /**
+     * Connection success flag.
+     */
+    is_success: true;
+} & 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';
+    /**
+     * Connection success flag.
+     */
+    is_success: false;
+    /**
+     * Reason for the error.
+     */
+    error_message: string;
+    /**
+     * Custom data for the connection.
+     */
+    custom_data: Version;
+};
+
+/**
+ * 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';
+    /**
+     * Custom data for the connection.
+     */
+    custom_data: Version;
+};
+
+/**
+ * Initial connection event when a user initiates a connection.
+ */
+export declare type ConnectionStartedEvent = {
+    /**
+     * Event type.
+     */
+    type: 'connection-started';
+    /**
+     * Custom data for the connection.
+     */
+    custom_data: Version;
+};
+
+export declare type ConnectItem = TonAddressItem | TonProofItem;
+
 export declare type ConnectItemReplyError<T> = {
     name: T;
     error: {
@@ -51,6 +251,98 @@ export declare type ConnectItemReplyError<T> = {
     };
 };
 
+/**
+ * Create a connection completed event.
+ * @param version
+ * @param wallet
+ */
+export declare function createConnectionCompletedEvent(version: Version, wallet: Wallet | null): ConnectionCompletedEvent;
+
+/**
+ * Create a connection error event.
+ * @param version
+ * @param error_message
+ * @param errorCode
+ */
+export declare function createConnectionErrorEvent(version: Version, error_message: string, errorCode: CONNECT_EVENT_ERROR_CODES | void): ConnectionErrorEvent;
+
+/**
+ * Create a connection restoring completed event.
+ * @param version
+ * @param wallet
+ */
+export declare function createConnectionRestoringCompletedEvent(version: Version, wallet: Wallet | null): ConnectionRestoringCompletedEvent;
+
+/**
+ * Create a connection restoring error event.
+ * @param version
+ * @param errorMessage
+ */
+export declare function createConnectionRestoringErrorEvent(version: Version, errorMessage: string): ConnectionRestoringErrorEvent;
+
+/**
+ * Create a connection restoring started event.
+ */
+export declare function createConnectionRestoringStartedEvent(version: Version): ConnectionRestoringStartedEvent;
+
+/**
+ * Create a connection init event.
+ */
+export declare function createConnectionStartedEvent(version: Version): ConnectionStartedEvent;
+
+/**
+ * Create a disconnect event.
+ * @param version
+ * @param wallet
+ * @param scope
+ * @returns
+ */
+export declare function createDisconnectionEvent(version: Version, wallet: Wallet | null, scope: 'dapp' | 'wallet'): DisconnectionEvent;
+
+/**
+ * Create a request version event.
+ */
+export declare function createRequestVersionEvent(): RequestVersionEvent;
+
+/**
+ * Create a response version event.
+ * @param version
+ */
+export declare function createResponseVersionEvent(version: string): ResponseVersionEvent;
+
+/**
+ * Create a transaction init event.
+ * @param version
+ * @param wallet
+ * @param transaction
+ */
+export declare function createTransactionSentForSignatureEvent(version: Version, wallet: Wallet | null, transaction: SendTransactionRequest): TransactionSentForSignatureEvent;
+
+/**
+ * Create a transaction signed event.
+ * @param version
+ * @param wallet
+ * @param transaction
+ * @param signedTransaction
+ */
+export declare function createTransactionSignedEvent(version: Version, wallet: Wallet | null, transaction: SendTransactionRequest, signedTransaction: SendTransactionResponse): TransactionSignedEvent;
+
+/**
+ * Create a transaction error event.
+ * @param version
+ * @param wallet
+ * @param transaction
+ * @param errorMessage
+ * @param errorCode
+ */
+export declare function createTransactionSigningFailedEvent(version: Version, wallet: Wallet | null, transaction: SendTransactionRequest, errorMessage: string, errorCode: SEND_TRANSACTION_ERROR_CODES | void): TransactionSigningFailedEvent;
+
+/**
+ * Create a version info.
+ * @param version
+ */
+export declare function createVersionInfo(version: Version): Version;
+
 export declare interface DappMetadata {
     /**
      * Dapp name. Might be simple, will not be used as identifier.
@@ -78,8 +370,48 @@ 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 extends {
+    type: string;
+}> {
+    /**
+     * 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<P extends AddTonConnectPrefix<T['type']>>(eventName: P, eventDetails: T & {
+        type: RemoveTonConnectPrefix<P>;
+    }): Promise<void>;
+    /**
+     * Adds an event listener.
+     * @param eventName - The name of the event to listen for.
+     * @param listener - The listener to add.
+     * @param options - The options for the listener.
+     * @returns A function that removes the listener.
+     */
+    addEventListener<P extends AddTonConnectPrefix<T['type']>>(eventName: P, listener: (event: CustomEvent<T & {
+        type: RemoveTonConnectPrefix<P>;
+    }>) => void, options?: AddEventListenerOptions): Promise<() => void>;
+}
+
 export declare type Feature = SendTransactionFeatureDeprecated | SendTransactionFeature | SignDataFeature;
 
 /**
@@ -228,6 +560,48 @@ export declare class ParseHexError extends TonConnectError {
     constructor(...args: ConstructorParameters<typeof TonConnectError>);
 }
 
+/**
+ * Removes the `ton-connect-` and `ton-connect-ui-` prefixes from the given string.
+ */
+export declare type RemoveTonConnectPrefix<T> = T extends `ton-connect-ui-${infer Rest}` ? Rest : T extends `ton-connect-${infer Rest}` ? Rest : T;
+
+/**
+ * Request TON Connect UI version.
+ */
+export declare type RequestVersionEvent = {
+    /**
+     * Event type.
+     */
+    type: 'request-version';
+};
+
+/**
+ * Response TON Connect UI version.
+ */
+export declare type ResponseVersionEvent = {
+    /**
+     * Event type.
+     */
+    type: 'response-version';
+    /**
+     * TON Connect UI version.
+     */
+    version: string;
+};
+
+/**
+ * User action events.
+ */
+export declare type SdkActionEvent = VersionEvent | 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 +656,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 +676,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 +802,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 +823,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 +852,93 @@ 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';
+    /**
+     * Connection success flag.
+     */
+    is_success: true;
+    /**
+     * 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';
+    /**
+     * Connection success flag.
+     */
+    is_success: false;
+    /**
+     * 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.
  */
@@ -483,6 +962,25 @@ export declare class UserRejectsError extends TonConnectError {
     constructor(...args: ConstructorParameters<typeof TonConnectError>);
 }
 
+/**
+ * Version of the TON Connect SDK and TON Connect UI.
+ */
+export declare type Version = {
+    /**
+     * TON Connect SDK version.
+     */
+    ton_connect_sdk_lib: string | null;
+    /**
+     * TON Connect UI version.
+     */
+    ton_connect_ui_lib: string | null;
+};
+
+/**
+ * Version events.
+ */
+export declare type VersionEvent = RequestVersionEvent | ResponseVersionEvent;
+
 export declare interface Wallet {
     /**
      * Information about user's wallet's device.
@@ -657,6 +1155,11 @@ export declare class WalletsListManager {
     private isCorrectWalletConfigDTO;
 }
 
+/**
+ * Parameters without version field.
+ */
+export declare type WithoutVersion<T> = T extends [Version, ...infer Rest] ? [...Rest] : never;
+
 /**
  * Thrown when passed address is in incorrect format.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonconnect/sdk",
-  "version": "3.0.2",
+  "version": "3.0.3-beta.1",
   "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"
@@ -56,6 +56,7 @@
     "webpack-cli": "^5.0.0",
     "rollup": "^3.18.0",
     "@rollup/plugin-typescript": "^11.0.0",
+    "@rollup/plugin-replace": "5.0.5",
     "vite": "^4.2.1",
     "vite-tsconfig-paths": "^4.0.5",
     "vitest": "^0.29.2",