@blazium/ton-connect-mobile 1.2.1 → 1.2.3

package/README.md

@@ -9,8 +9,8 @@ Production-ready TON Connect Mobile SDK for React Native and Expo. Implements th
 - ✅ **Full `@tonconnect/ui-react` Compatibility** - Drop-in replacement
 - ✅ **React Native & Expo Support** - Works with both Expo and React Native CLI
 - ✅ **Android & iOS Support** - Full deep linking support
-- ✅ **Multiple Wallet Support** - Tonkeeper, Tonhub, MyTonWallet, Telegram Wallet
-- ✅ **Beautiful Wallet Selection Modal** - Built-in wallet picker UI
+- ✅ **Multiple Wallet Support** - Tonkeeper (including Web), Tonhub, MyTonWallet, Telegram Wallet
+- ✅ **Beautiful Wallet Selection Modal** - Grid layout matching @tonconnect/ui-react design
 - ✅ **Transaction Signing** - Send transactions with wallet approval
 - ✅ **Data Signing** - Sign arbitrary data for authentication
 - ✅ **Transaction Builder Utilities** - Helper functions for building transactions
@@ -18,6 +18,10 @@ Production-ready TON Connect Mobile SDK for React Native and Expo. Implements th
 - ✅ **Enhanced Error Messages** - Clear error messages with recovery suggestions
 - ✅ **Wallet Availability Checking** - Check if wallets are available
 - ✅ **Session Persistence** - Maintains connection across app restarts
+- ✅ **Network Switching** - Switch between mainnet and testnet dynamically
+- ✅ **Event Emitters** - Listen to connect, disconnect, transaction, and error events
+- ✅ **Wallet Balance Checking** - Get wallet balance via TON Center API
+- ✅ **Transaction Status Tracking** - Track transaction status with polling
 - ✅ **TypeScript** - Full type safety
 - ✅ **Production Ready** - Battle-tested implementation
 
@@ -135,18 +139,50 @@ Pre-built button component for connecting/disconnecting wallets.
 
 #### `useTonConnectUI()`
 
-Access the TonConnectUI instance with all methods.
+Access the TonConnectUI instance with all methods and features.
 
 ```typescript
 const tonConnectUI = useTonConnectUI();
 
-// Methods:
+// Connection methods:
 await tonConnectUI.connectWallet();
 await tonConnectUI.disconnect();
+await tonConnectUI.restoreConnection(); // Restore from stored session
+
+// Transaction methods:
 await tonConnectUI.sendTransaction({ ... });
 await tonConnectUI.signData({ data: '...', version: '1.0' });
+
+// Modal methods:
 await tonConnectUI.openModal();
 tonConnectUI.closeModal();
+
+// Wallet customization:
+tonConnectUI.setWalletList([...]); // Customize available wallets
+
+// Network management:
+const network = tonConnectUI.getNetwork(); // Get current network
+tonConnectUI.setNetwork('testnet'); // Switch to testnet
+
+// Balance checking:
+const balance = await tonConnectUI.getBalance(); // Get connected wallet balance
+const balance2 = await tonConnectUI.getBalance(address); // Get specific address balance
+
+// Transaction status:
+const status = await tonConnectUI.getTransactionStatusByHash(txHash, address);
+
+// Event listeners:
+const unsubscribe = tonConnectUI.on('connect', (wallet) => {
+  console.log('Connected:', wallet);
+});
+tonConnectUI.on('disconnect', () => console.log('Disconnected'));
+tonConnectUI.on('transaction', (tx) => console.log('Transaction:', tx));
+tonConnectUI.on('error', (error) => console.error('Error:', error));
+
+// State access:
+tonConnectUI.wallet; // Current wallet state
+tonConnectUI.modalState.open; // Modal open state
+tonConnectUI.uiVersion; // UI kit version
 ```
 
 #### `useTonWallet()`
@@ -204,10 +240,12 @@ new TonConnectMobile(config: TonConnectMobileConfig)
 - `manifestUrl` (required): URL to your TonConnect manifest file
 - `scheme` (required): Your app's deep link scheme
 - `storageKeyPrefix` (optional): Prefix for storage keys (default: `'tonconnect_'`)
-- `connectionTimeout` (optional): Connection timeout in ms (default: `30000`)
-- `transactionTimeout` (optional): Transaction timeout in ms (default: `300000`)
+- `connectionTimeout` (optional): Connection timeout in ms (default: `300000` = 5 minutes)
+- `transactionTimeout` (optional): Transaction timeout in ms (default: `300000` = 5 minutes)
 - `skipCanOpenURLCheck` (optional): Skip canOpenURL check (default: `true` for Android compatibility)
 - `preferredWallet` (optional): Default wallet name
+- `network` (optional): Network to use - `'mainnet'` or `'testnet'` (default: `'mainnet'`)
+- `tonApiEndpoint` (optional): Custom TON API endpoint (default: auto-selected based on network)
 
 #### Methods
 
@@ -286,20 +324,124 @@ const unsubscribe = ton.onStatusChange((status) => {
 });
 ```
 
-## Platform Support
+##### `getNetwork(): Network`
+
+Get current network (mainnet or testnet).
+
+```typescript
+const network = ton.getNetwork(); // 'mainnet' or 'testnet'
+```
+
+##### `setNetwork(network: Network): void`
+
+Switch between mainnet and testnet.
+
+```typescript
+ton.setNetwork('testnet'); // Switch to testnet
+// Note: Warning is logged if switching while wallet is connected
+```
+
+##### `getBalance(address?: string): Promise<BalanceResponse>`
+
+Get wallet balance from TON Center API.
+
+```typescript
+// Get balance of connected wallet
+const balance = await ton.getBalance();
+
+// Get balance of specific address
+const balance = await ton.getBalance('EQD0vdSA_NedR9uvbgN9EikRX-suesDxGeFg69XQMavfLqIo');
+
+// Response:
+// {
+//   balance: "1000000000", // in nanotons
+//   balanceTon: "1.0", // formatted TON
+//   network: "mainnet"
+// }
+```
+
+##### `getTransactionStatusByHash(txHash: string, address: string): Promise<TransactionStatusResponse>`
+
+Get transaction status by hash (recommended method).
+
+```typescript
+const status = await ton.getTransactionStatusByHash(txHash, address);
+
+// Response:
+// {
+//   status: "confirmed" | "pending" | "failed" | "unknown",
+//   hash?: string,
+//   blockNumber?: number,
+//   error?: string
+// }
+```
+
+##### `getTransactionStatus(boc: string, maxAttempts?: number, intervalMs?: number): Promise<TransactionStatusResponse>`
+
+Get transaction status from BOC (requires BOC parsing library).
+
+```typescript
+// Note: This method requires BOC parsing. Use getTransactionStatusByHash() instead.
+const status = await ton.getTransactionStatus(boc, 10, 2000);
+```
+
+##### `on<T>(event: TonConnectEventType, listener: TonConnectEventListener<T>): () => void`
+
+Add event listener.
+
+```typescript
+// Listen to connection events
+const unsubscribe = ton.on('connect', (wallet) => {
+  console.log('Connected to:', wallet.name);
+});
+
+// Listen to transaction events
+ton.on('transaction', (tx) => {
+  console.log('Transaction sent:', tx.boc);
+});
+
+// Listen to errors
+ton.on('error', (error) => {
+  console.error('SDK error:', error);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+##### `off<T>(event: TonConnectEventType, listener: TonConnectEventListener<T>): void`
+
+Remove event listener.
+
+```typescript
+ton.off('connect', listener);
+```
+
+##### `removeAllListeners(event?: TonConnectEventType): void`
 
-**⚠️ Important**: TON Connect deep links (`tonconnect://`) only work on **mobile devices** (Android/iOS). They do not work in web browsers.
+Remove all listeners for an event, or all events.
+
+```typescript
+ton.removeAllListeners('connect'); // Remove all connect listeners
+ton.removeAllListeners(); // Remove all listeners
+```
+
+## Platform Support
 
 - ✅ **Android**: Full support via Expo or React Native CLI
 - ✅ **iOS**: Full support via Expo or React Native CLI  
-- ⚠️ **Web**: Deep links are not supported. The SDK will throw a clear error message if you try to use it in a web browser.
+- ✅ **Web**: Universal links supported (opens wallet in new tab/window)
 
-**Why?** The `tonconnect://` protocol is a custom URI scheme that requires a mobile app handler. Web browsers cannot handle these custom protocols.
+**Web Platform Notes:**
+- On web, wallets with universal links (like Tonkeeper Web, MyTonWallet) can be opened in a new browser tab
+- The SDK automatically detects web platform and shows all available wallets
+- Wallet availability is checked based on universal link support
+- Deep links (`tonconnect://`) are not supported in web browsers, but universal links work perfectly
 
-**Testing**: To test wallet connections, use:
+**Testing**: 
 - Android device or emulator
 - iOS device or simulator
-- Not web browsers
+- Web browsers (for wallets with web support like Tonkeeper Web)
 
 ## Configuration
 
@@ -368,10 +510,12 @@ The manifest URL must be accessible via HTTPS.
 
 ## Supported Wallets
 
-- **Tonkeeper** - Full support
-- **Tonhub** - Full support
-- **MyTonWallet** - Full support
-- **Wallet in Telegram** - Full support
+- **Tonkeeper** - Full support (iOS, Android, Web)
+- **MyTonWallet** - Full support (iOS, Android, Web)
+- **Tonhub** - Full support (iOS, Android)
+- **Wallet in Telegram** - Full support (iOS, Android)
+
+**Note**: Wallet icons are automatically loaded from official sources. If an icon fails to load, a placeholder with the wallet's initial is shown.
 
 ## Migration from @tonconnect/ui-react
 
@@ -453,10 +597,133 @@ MIT
 For issues and questions:
 - GitHub Issues: [https://github.com/blaziumdev/ton-connect-mobile/issues](https://github.com/blaziumdev/ton-connect-mobile/issues)
 
-## New Features in v1.2.0
+## New Features in v1.2.3
+
+### 🌐 Network Switching
+Switch between mainnet and testnet dynamically:
+
+```typescript
+// Initialize with network
+const ton = new TonConnectMobile({
+  network: 'testnet', // or 'mainnet' (default)
+  // ... other config
+});
+
+// Or switch at runtime
+ton.setNetwork('testnet');
+tonConnectUI.setNetwork('testnet');
+
+// Get current network
+const network = ton.getNetwork(); // 'mainnet' or 'testnet'
+```
+
+**Features:**
+- Chain ID automatically updates (-239 for mainnet, -3 for testnet)
+- TON API endpoint automatically switches based on network
+- Warning logged if switching network while wallet is connected
+- React components automatically update chain ID
+
+### 📡 Event Emitters
+Listen to SDK events for reactive programming:
+
+```typescript
+// Add event listeners
+tonConnectUI.on('connect', (wallet) => {
+  console.log('Connected to:', wallet.name);
+});
+
+tonConnectUI.on('disconnect', () => {
+  console.log('Disconnected');
+});
+
+tonConnectUI.on('transaction', (tx) => {
+  console.log('Transaction sent:', tx.boc);
+});
+
+tonConnectUI.on('error', (error) => {
+  console.error('SDK error:', error);
+});
+
+// Remove listener
+const unsubscribe = tonConnectUI.on('connect', listener);
+unsubscribe(); // or
+tonConnectUI.off('connect', listener);
+```
+
+**Available Events:**
+- `connect` - Fired when wallet connects
+- `disconnect` - Fired when wallet disconnects
+- `transaction` - Fired when transaction is sent
+- `error` - Fired when an error occurs
+- `statusChange` - Fired when connection status changes
+
+### 💰 Wallet Balance Checking
+Get wallet balance from TON Center API:
+
+```typescript
+// Get balance of connected wallet
+const balance = await tonConnectUI.getBalance();
+
+// Get balance of specific address
+const balance = await tonConnectUI.getBalance('EQD0vdSA_NedR9uvbgN9EikRX-suesDxGeFg69XQMavfLqIo');
+
+// Response:
+// {
+//   balance: "1000000000", // in nanotons
+//   balanceTon: "1.0", // formatted TON
+//   network: "mainnet"
+// }
+```
+
+**Features:**
+- Automatically uses correct API endpoint based on network
+- Returns balance in both nanotons and formatted TON
+- Validates address format before API call
+- Handles API errors gracefully
+
+### 📊 Transaction Status Tracking
+Track transaction status after sending:
+
+```typescript
+// Using transaction hash (recommended)
+const status = await tonConnectUI.getTransactionStatusByHash(txHash, address);
+
+// Response:
+// {
+//   status: "confirmed" | "pending" | "failed" | "unknown",
+//   hash: "transaction_hash",
+//   blockNumber: 12345,
+//   error?: "error message"
+// }
+
+// Using BOC (requires BOC parsing library)
+const status = await tonConnectUI.getTransactionStatus(boc, maxAttempts, intervalMs);
+```
+
+**Features:**
+- Polling mechanism with configurable attempts and intervals
+- Network-specific API endpoint selection
+- Returns detailed status information
+- Handles API errors gracefully
+
+### 🎯 Complete TonConnectUI API
+All features from `@tonconnect/ui-react` are now available:
+
+```typescript
+const tonConnectUI = useTonConnectUI();
+
+// Restore connection from stored session
+await tonConnectUI.restoreConnection();
+
+// Customize available wallets
+tonConnectUI.setWalletList([
+  { name: 'Tonkeeper', universalLink: '...', platforms: ['ios', 'android', 'web'] },
+  { name: 'MyTonWallet', universalLink: '...', platforms: ['ios', 'android', 'web'] },
+]);
+```
 
 ### 🎨 Wallet Selection Modal
-Beautiful, built-in wallet selection modal that automatically appears when you call `openModal()`:
+Beautiful, built-in wallet selection modal with grid layout matching @tonconnect/ui-react design. Automatically appears when you call `openModal()`:
 
 ```typescript
 import { WalletSelectionModal } from '@blazium/ton-connect-mobile/react';
@@ -469,6 +736,14 @@ import { WalletSelectionModal } from '@blazium/ton-connect-mobile/react';
 />
 ```
 
+**Features:**
+- Grid layout (4 columns) matching @tonconnect/ui-react design
+- Real wallet icons loaded from official sources
+- Availability status for each wallet
+- Automatic wallet filtering by platform
+- Smooth animations and loading states
+- Custom wallet list support via `setWalletList()`
+
 ### 🛠️ Transaction Builder Utilities
 Helper functions for building transactions easily:
 
@@ -533,6 +808,12 @@ if (isAvailable) {
 }
 ```
 
+**Platform Detection:**
+- On web: Checks if wallet has universal link support (can open in new tab)
+- On mobile: Checks if wallet supports the current platform (iOS/Android)
+- Uses adapter type for reliable platform detection
+- All wallets with universal links are considered available on web
+
 ### 💬 Enhanced Error Messages
 All errors now include helpful recovery suggestions:
 
@@ -549,6 +830,23 @@ try {
 
 ## Changelog
 
+### v1.2.3
+- ✅ **NEW**: Network switching - Switch between mainnet and testnet dynamically
+- ✅ **NEW**: Event emitters - Listen to connect, disconnect, transaction, and error events
+- ✅ **NEW**: Wallet balance checking - Get wallet balance via TON Center API integration
+- ✅ **NEW**: Transaction status tracking - Track transaction status with polling mechanism
+- ✅ **NEW**: Complete TonConnectUI API implementation - all features from @tonconnect/ui-react
+- ✅ **NEW**: `restoreConnection()` method - restore connection from stored session
+- ✅ **NEW**: `setWalletList()` method - customize available wallets in modal
+- ✅ **NEW**: Wallet selection modal with grid layout matching @tonconnect/ui-react design
+- ✅ **NEW**: Real wallet icons loaded from official sources
+- ✅ **NEW**: Improved web platform support (Tonkeeper Web, MyTonWallet Web)
+- ✅ **IMPROVED**: Wallet availability detection using adapter type (more reliable)
+- ✅ **IMPROVED**: All wallets shown on web platform (with availability status)
+- ✅ **IMPROVED**: Chain ID automatically updates when network changes
+- ✅ **FIXED**: Tonkeeper now correctly shows as available on web
+- ✅ **FIXED**: All Turkish comments translated to English
+
 ### v1.2.0
 - ✅ **NEW**: Beautiful wallet selection modal component
 - ✅ **NEW**: Transaction builder utilities (`buildTransferTransaction`, `tonToNano`, etc.)

package/dist/core/wallets.js

@@ -17,6 +17,7 @@ exports.SUPPORTED_WALLETS = [
         appName: 'Tonkeeper',
         universalLink: 'https://app.tonkeeper.com/ton-connect',
         deepLink: 'tonkeeper://',
+        iconUrl: 'https://tonkeeper.com/assets/tonconnect-icon.png',
         platforms: ['ios', 'android', 'web'], // CRITICAL FIX: Tonkeeper Web is supported
         preferredReturnStrategy: 'post_redirect', // CRITICAL FIX: 'back' strategy may not send callback properly, use 'post_redirect'
         requiresReturnScheme: true, // CRITICAL FIX: Mobile apps need returnScheme for proper callback handling
@@ -26,6 +27,7 @@ exports.SUPPORTED_WALLETS = [
         appName: 'MyTonWallet',
         universalLink: 'https://connect.mytonwallet.org',
         deepLink: 'mytonwallet://',
+        iconUrl: 'https://static.mytonwallet.io/icon-256.png',
         platforms: ['ios', 'android', 'web'],
         preferredReturnStrategy: 'post_redirect',
         requiresReturnScheme: true, // MyTonWallet requires explicit returnScheme
@@ -35,6 +37,7 @@ exports.SUPPORTED_WALLETS = [
         appName: 'Wallet',
         universalLink: 'https://wallet.tonapi.io/ton-connect',
         deepLink: 'tg://',
+        iconUrl: 'https://wallet.tonapi.io/icon.png',
         platforms: ['ios', 'android'],
         preferredReturnStrategy: 'post_redirect',
         requiresReturnScheme: true, // Telegram Wallet requires explicit returnScheme
@@ -44,6 +47,7 @@ exports.SUPPORTED_WALLETS = [
         appName: 'Tonhub',
         universalLink: 'https://tonhub.com/ton-connect',
         deepLink: 'tonhub://',
+        iconUrl: 'https://tonhub.com/tonconnect_logo.png',
         platforms: ['ios', 'android'],
         preferredReturnStrategy: 'post_redirect',
         requiresReturnScheme: true, // Tonhub requires explicit returnScheme for proper callback

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * TON Connect Mobile SDK
  * Production-ready implementation for React Native and Expo
  */
-import { TonConnectMobileConfig, ConnectionStatus, WalletInfo, SendTransactionRequest, StatusChangeCallback } from './types';
+import { TonConnectMobileConfig, ConnectionStatus, WalletInfo, SendTransactionRequest, StatusChangeCallback, Network, TonConnectEventType, TonConnectEventListener, TransactionStatusResponse, BalanceResponse } from './types';
 import { type WalletDefinition } from './core/wallets';
 /**
  * Custom error classes
@@ -34,6 +34,7 @@ export declare class TonConnectMobile {
     private adapter;
     private config;
     private statusChangeCallbacks;
+    private eventListeners;
     private currentStatus;
     private urlUnsubscribe;
     private currentWallet;
@@ -119,6 +120,22 @@ export declare class TonConnectMobile {
      * Notify all status change callbacks
      */
     private notifyStatusChange;
+    /**
+     * Emit event to all listeners
+     */
+    private emit;
+    /**
+     * Add event listener
+     */
+    on<T = any>(event: TonConnectEventType, listener: TonConnectEventListener<T>): () => void;
+    /**
+     * Remove event listener
+     */
+    off<T = any>(event: TonConnectEventType, listener: TonConnectEventListener<T>): void;
+    /**
+     * Remove all listeners for an event
+     */
+    removeAllListeners(event?: TonConnectEventType): void;
     /**
      * Validate session ID format
      */
@@ -139,6 +156,26 @@ export declare class TonConnectMobile {
      * Cleanup resources
      */
     destroy(): void;
+    /**
+     * Get current network
+     */
+    getNetwork(): Network;
+    /**
+     * Set network (mainnet/testnet)
+     */
+    setNetwork(network: Network): void;
+    /**
+     * Get wallet balance
+     */
+    getBalance(address?: string): Promise<BalanceResponse>;
+    /**
+     * Get transaction status
+     */
+    getTransactionStatus(boc: string, maxAttempts?: number, intervalMs?: number): Promise<TransactionStatusResponse>;
+    /**
+     * Get transaction status by hash (more reliable than BOC)
+     */
+    getTransactionStatusByHash(txHash: string, address: string): Promise<TransactionStatusResponse>;
 }
 export * from './types';
 export type { WalletDefinition } from './core/wallets';