@tonconnect/sdk - npm Package Compare versions

Comparing version 3.0.2 to 3.0.3-beta.0

lib/types/index.d.ts

@@ -22,2 +22,7 @@ export declare interface Account {
 /**
+ * Requested authentication type: 'ton_addr' or 'ton_proof'.
+ */
+export declare type AuthType = ConnectItem['name'];
+
+/**
  * Thrown when request to the wallet contains errors.
@@ -30,2 +35,20 @@ */
 
+/**
+ * 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 {
@@ -36,2 +59,12 @@ MAINNET = "-239",
 
+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 {
@@ -49,2 +82,121 @@ UNKNOWN_ERROR = 0,
 
+/**
+ * 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> = {
@@ -58,2 +210,69 @@ name: 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 {
@@ -86,4 +305,30 @@ /**
 
+/**
+ * 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;
@@ -237,2 +482,15 @@
 
+/**
+ * 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 = {
@@ -292,2 +550,6 @@ name: 'SendTransaction';
 
+export declare interface TonAddressItem {
+    name: 'ton_addr';
+}
+
 declare class TonConnect implements ITonConnect {
@@ -309,2 +571,7 @@ private static readonly walletsList;
     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;
@@ -432,2 +699,6 @@ private readonly dappSettings;
     /**
+     * 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}
@@ -449,2 +720,7 @@ * @default https://raw.githubusercontent.com/ton-connect/wallets-list/main/wallets.json
 
+export declare interface TonProofItem {
+    name: 'ton_proof';
+    payload: string;
+}
+
 export declare type TonProofItemReply = TonProofItemReplySuccess | TonProofItemReplyError;
@@ -475,2 +751,81 @@
 /**
+ * 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.
@@ -477,0 +832,0 @@ */

package.json

 {
   "name": "@tonconnect/sdk",
-  "version": "3.0.2",
+  "version": "3.0.3-beta.0",
   "scripts": {
@@ -5,0 +5,0 @@ "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",

README.md

@@ -360,2 +360,50 @@ # TON Connect SDK
 
+# Tracking
+
+## Track events
+
+Tracker for TonConnect user actions, such as transaction signing, connection, etc.
+
+List of events:
+* `connection-started`: when a user starts connecting a wallet.
+* `connection-completed`: when a user successfully connected a wallet.
+* `connection-error`: when a user cancels a connection or there is an error during the connection process.
+* `connection-restoring-started`: when the dApp starts restoring a connection.
+* `connection-restoring-completed`: when the dApp successfully restores a connection.
+* `connection-restoring-error`: when the dApp fails to restore a connection.
+* `disconnection`: when a user starts disconnecting a wallet.
+* `transaction-sent-for-signature`: when a user sends a transaction for signature.
+* `transaction-signed`: when a user successfully signs a transaction.
+* `transaction-signing-failed`: when a user cancels transaction signing or there is an error during the signing process.
+
+If you want to track user actions, you can subscribe to the window events with prefix `ton-connect-`:
+
+```typescript
+window.addEventListener('ton-connect-transaction-sent-for-signature', (event) => {
+    console.log('Transaction init', event.detail);
+});
+```
+
+## Use custom event dispatcher
+
+You can use your custom event dispatcher to track user actions. To do this, you need to pass the `eventDispatcher` to the TonConnect constructor:
+
+```typescript
+import {TonConnect, EventDispatcher, SdkActionEvent} from '@tonconnect/sdk';
+
+class CustomEventDispatcher implements EventDispatcher<SdkActionEvent> {
+    public async dispatchEvent(
+      eventName: string, 
+      eventDetails: SdkActionEvent
+    ): Promise<void> {
+        console.log(`Event: ${eventName}, details:`, eventDetails);
+    }
+}
+
+const eventDispatcher = new CustomEventDispatcher();
+
+const connector = new TonConnect({ eventDispatcher });
+```
+
+
 # Troubleshooting
@@ -362,0 +410,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

949521

increased by10.27%

Lines of code

6896

increased by17.34%

Number of lines in readme file

432

increased by12.5%

Worsened metrics

Number of low quality alerts

1

increased byInfinity%

No dependency changes