@blazium/ton-connect-mobile 1.1.4 → 1.2.0

package/dist/utils/transactionBuilder.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Transaction Builder Utilities
+ * Helper functions for building TON Connect transaction requests
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tonToNano = tonToNano;
+exports.nanoToTon = nanoToTon;
+exports.buildTransferTransaction = buildTransferTransaction;
+exports.buildMultiTransferTransaction = buildMultiTransferTransaction;
+exports.buildTransactionWithPayload = buildTransactionWithPayload;
+exports.buildTransactionWithStateInit = buildTransactionWithStateInit;
+exports.isValidTonAddress = isValidTonAddress;
+exports.formatTonAddress = formatTonAddress;
+/**
+ * Convert TON amount to nanotons
+ * @param tonAmount - Amount in TON (e.g., 1.5 for 1.5 TON)
+ * @returns Amount in nanotons as string
+ */
+function tonToNano(tonAmount) {
+    const amount = typeof tonAmount === 'string' ? parseFloat(tonAmount) : tonAmount;
+    if (isNaN(amount) || amount < 0) {
+        throw new Error('Invalid TON amount');
+    }
+    const nanotons = Math.floor(amount * 1000000000);
+    return nanotons.toString();
+}
+/**
+ * Convert nanotons to TON
+ * @param nanotons - Amount in nanotons as string
+ * @returns Amount in TON as number
+ */
+function nanoToTon(nanotons) {
+    const nano = BigInt(nanotons);
+    return Number(nano) / 1000000000;
+}
+/**
+ * Build a simple TON transfer transaction
+ * @param to - Recipient address (EQ... format)
+ * @param amount - Amount in TON (will be converted to nanotons)
+ * @param validUntil - Optional expiration timestamp (default: 5 minutes from now)
+ * @returns Transaction request
+ */
+function buildTransferTransaction(to, amount, validUntil) {
+    return {
+        validUntil: validUntil || Date.now() + 5 * 60 * 1000, // 5 minutes default
+        messages: [
+            {
+                address: to,
+                amount: tonToNano(amount),
+            },
+        ],
+    };
+}
+/**
+ * Build a transaction with multiple recipients
+ * @param transfers - Array of {to, amount} transfers
+ * @param validUntil - Optional expiration timestamp (default: 5 minutes from now)
+ * @returns Transaction request
+ */
+function buildMultiTransferTransaction(transfers, validUntil) {
+    return {
+        validUntil: validUntil || Date.now() + 5 * 60 * 1000,
+        messages: transfers.map((transfer) => ({
+            address: transfer.to,
+            amount: tonToNano(transfer.amount),
+        })),
+    };
+}
+/**
+ * Build a transaction with custom payload
+ * @param to - Recipient address
+ * @param amount - Amount in TON
+ * @param payload - Base64 encoded payload
+ * @param validUntil - Optional expiration timestamp
+ * @returns Transaction request
+ */
+function buildTransactionWithPayload(to, amount, payload, validUntil) {
+    return {
+        validUntil: validUntil || Date.now() + 5 * 60 * 1000,
+        messages: [
+            {
+                address: to,
+                amount: tonToNano(amount),
+                payload,
+            },
+        ],
+    };
+}
+/**
+ * Build a transaction with state init (for contract deployment)
+ * @param to - Recipient address
+ * @param amount - Amount in TON
+ * @param stateInit - Base64 encoded state init
+ * @param validUntil - Optional expiration timestamp
+ * @returns Transaction request
+ */
+function buildTransactionWithStateInit(to, amount, stateInit, validUntil) {
+    return {
+        validUntil: validUntil || Date.now() + 5 * 60 * 1000,
+        messages: [
+            {
+                address: to,
+                amount: tonToNano(amount),
+                stateInit,
+            },
+        ],
+    };
+}
+/**
+ * Validate TON address format
+ * @param address - Address to validate
+ * @returns true if address is valid
+ */
+function isValidTonAddress(address) {
+    // TON addresses start with EQ or 0Q and are 48 characters long (base64)
+    return /^(EQ|0Q)[A-Za-z0-9_-]{46}$/.test(address);
+}
+/**
+ * Format TON address for display (with ellipsis)
+ * @param address - Full address
+ * @param startLength - Characters to show at start (default: 6)
+ * @param endLength - Characters to show at end (default: 4)
+ * @returns Formatted address
+ */
+function formatTonAddress(address, startLength = 6, endLength = 4) {
+    if (address.length <= startLength + endLength) {
+        return address;
+    }
+    return `${address.substring(0, startLength)}...${address.substring(address.length - endLength)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blazium/ton-connect-mobile",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Production-ready TON Connect Mobile SDK for React Native and Expo. Implements the real TonConnect protocol for mobile applications using deep links and callbacks.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/wallets.ts

@@ -32,7 +32,7 @@ export const SUPPORTED_WALLETS: WalletDefinition[] = [
     universalLink: 'https://app.tonkeeper.com/ton-connect',
     deepLink: 'tonkeeper://',
     platforms: ['ios', 'android'],
-    preferredReturnStrategy: 'back',
+    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
   },
   {

package/src/index.ts

@@ -40,7 +40,7 @@ import { getWalletByName, getDefaultWallet, SUPPORTED_WALLETS, type WalletDefini
  * Custom error classes
  */
 export class TonConnectError extends Error {
-  constructor(message: string, public code?: string) {
+  constructor(message: string, public code?: string, public recoverySuggestion?: string) {
     super(message);
     this.name = 'TonConnectError';
   }
@@ -48,21 +48,33 @@ export class TonConnectError extends Error {
 
 export class ConnectionTimeoutError extends TonConnectError {
   constructor() {
-    super('Connection request timed out', 'CONNECTION_TIMEOUT');
+    super(
+      'Connection request timed out. The wallet did not respond in time.',
+      'CONNECTION_TIMEOUT',
+      'Please make sure the wallet app is installed and try again. If the issue persists, check your internet connection.'
+    );
     this.name = 'ConnectionTimeoutError';
   }
 }
 
 export class TransactionTimeoutError extends TonConnectError {
   constructor() {
-    super('Transaction request timed out', 'TRANSACTION_TIMEOUT');
+    super(
+      'Transaction request timed out. The wallet did not respond in time.',
+      'TRANSACTION_TIMEOUT',
+      'Please check the wallet app and try again. Make sure you approve or reject the transaction in the wallet.'
+    );
     this.name = 'TransactionTimeoutError';
   }
 }
 
 export class UserRejectedError extends TonConnectError {
-  constructor() {
-    super('User rejected the request', 'USER_REJECTED');
+  constructor(message?: string) {
+    super(
+      message || 'User rejected the request',
+      'USER_REJECTED',
+      'The user cancelled the operation in the wallet app.'
+    );
     this.name = 'UserRejectedError';
   }
 }
@@ -754,6 +766,32 @@ export class TonConnectMobile {
     return this.currentWallet;
   }
 
+  /**
+   * Check if a wallet is available on the current platform
+   * Note: This is a best-effort check and may not be 100% accurate
+   */
+  async isWalletAvailable(walletName?: string): Promise<boolean> {
+    const wallet = walletName ? getWalletByName(walletName) : this.currentWallet;
+    if (!wallet) {
+      return false;
+    }
+
+    // On web, check if wallet supports web platform
+    // eslint-disable-next-line no-undef
+    if (typeof globalThis !== 'undefined' && (globalThis as any).window) {
+      return wallet.platforms.includes('web');
+    }
+
+    // On mobile, we can't reliably check if wallet is installed
+    // Return true if wallet supports the current platform
+    // eslint-disable-next-line no-undef
+    const platform = typeof globalThis !== 'undefined' && (globalThis as any).Platform
+      ? (globalThis as any).Platform.OS === 'ios' ? 'ios' : 'android'
+      : 'android';
+    
+    return wallet.platforms.includes(platform);
+  }
+
   /**
    * Set preferred wallet for connections
    */
@@ -928,3 +966,7 @@ export * from './types';
 export type { WalletDefinition } from './core/wallets';
 export { SUPPORTED_WALLETS, getWalletByName, getDefaultWallet, getWalletsForPlatform } from './core/wallets';
 
+// Export utilities
+export * from './utils/transactionBuilder';
+export * from './utils/retry';
+

package/src/react/TonConnectUIProvider.tsx

@@ -6,6 +6,7 @@
 import React, { createContext, useContext, useState, useEffect, useCallback, ReactNode } from 'react';
 import { TonConnectMobile, ConnectionStatus, WalletInfo, SendTransactionRequest } from '../index';
 import type { TonConnectMobileConfig } from '../types';
+import { WalletSelectionModal } from './WalletSelectionModal';
 
 /**
  * Account information (compatible with @tonconnect/ui-react)
@@ -160,8 +161,10 @@ export function TonConnectUIProvider({
 
   // Open modal
   const openModal = useCallback(async () => {
-    setModalOpen(true);
-  }, []);
+    if (!walletState?.connected) {
+      setModalOpen(true);
+    }
+  }, [walletState?.connected]);
 
   // Close modal
   const closeModal = useCallback(() => {
@@ -240,7 +243,16 @@ export function TonConnectUIProvider({
     sdk,
   };
 
-  return <TonConnectUIContext.Provider value={contextValue}>{children}</TonConnectUIContext.Provider>;
+  return (
+    <TonConnectUIContext.Provider value={contextValue}>
+      {children}
+      {/* Auto-show wallet selection modal when modalOpen is true */}
+      <WalletSelectionModal
+        visible={modalOpen && !walletState?.connected}
+        onClose={closeModal}
+      />
+    </TonConnectUIContext.Provider>
+  );
 }
 
 /**

package/src/react/WalletSelectionModal.tsx

@@ -0,0 +1,292 @@
+/**
+ * WalletSelectionModal component
+ * Provides a beautiful wallet selection UI compatible with @tonconnect/ui-react
+ */
+
+import React from 'react';
+import {
+  Modal,
+  View,
+  Text,
+  TouchableOpacity,
+  ScrollView,
+  StyleSheet,
+  Image,
+  Platform,
+} from 'react-native';
+import { useTonConnectUI, useTonConnectSDK } from './index';
+import type { WalletDefinition } from '../index';
+
+export interface WalletSelectionModalProps {
+  /** Whether the modal is visible */
+  visible: boolean;
+  /** Callback when modal should close */
+  onClose: () => void;
+  /** Custom wallet list (optional, uses SDK's supported wallets by default) */
+  wallets?: WalletDefinition[];
+  /** Custom styles */
+  style?: any;
+}
+
+/**
+ * WalletSelectionModal - Beautiful wallet selection modal
+ * Compatible with @tonconnect/ui-react modal behavior
+ */
+export function WalletSelectionModal({
+  visible,
+  onClose,
+  wallets: customWallets,
+  style,
+}: WalletSelectionModalProps): JSX.Element {
+  const tonConnectUI = useTonConnectUI();
+  const sdk = useTonConnectSDK();
+  const [wallets, setWallets] = React.useState<WalletDefinition[]>([]);
+  const [connectingWallet, setConnectingWallet] = React.useState<string | null>(null);
+
+  // Load wallets
+  React.useEffect(() => {
+    if (customWallets) {
+      setWallets(customWallets);
+    } else {
+      const supportedWallets = sdk.getSupportedWallets();
+      // Filter wallets for current platform
+      const platform = Platform.OS === 'ios' ? 'ios' : Platform.OS === 'android' ? 'android' : 'web';
+      const platformWallets = supportedWallets.filter((w) => w.platforms.includes(platform));
+      setWallets(platformWallets);
+    }
+  }, [sdk, customWallets]);
+
+  // Handle wallet selection
+  const handleSelectWallet = async (wallet: WalletDefinition) => {
+    try {
+      setConnectingWallet(wallet.name);
+      
+      // Set preferred wallet
+      sdk.setPreferredWallet(wallet.name);
+      
+      // Close modal
+      onClose();
+      
+      // Small delay to ensure modal closes
+      await new Promise<void>((resolve) => setTimeout(() => resolve(), 100));
+      
+      // Connect
+      await tonConnectUI.connectWallet();
+    } catch (error) {
+      console.error('Wallet connection error:', error);
+      setConnectingWallet(null);
+      // Re-open modal on error
+      onClose();
+      setTimeout(() => {
+        // Modal will be re-opened by parent if needed
+      }, 500);
+    }
+  };
+
+  return (
+    <Modal
+      visible={visible}
+      animationType="slide"
+      transparent={true}
+      onRequestClose={onClose}
+    >
+      <View style={[styles.overlay, style]}>
+        <View style={styles.modalContainer}>
+          {/* Header */}
+          <View style={styles.header}>
+            <Text style={styles.title}>Connect your TON wallet</Text>
+            <Text style={styles.subtitle}>Choose a wallet to connect to this app</Text>
+            <TouchableOpacity style={styles.closeButton} onPress={onClose}>
+              <Text style={styles.closeButtonText}>✕</Text>
+            </TouchableOpacity>
+          </View>
+
+          {/* Wallet List */}
+          <ScrollView style={styles.walletList} showsVerticalScrollIndicator={false}>
+            {wallets.length === 0 ? (
+              <View style={styles.emptyState}>
+                <Text style={styles.emptyStateText}>No wallets available</Text>
+                <Text style={styles.emptyStateSubtext}>
+                  Please install a TON wallet app to continue
+                </Text>
+              </View>
+            ) : (
+              wallets.map((wallet) => {
+                const isConnecting = connectingWallet === wallet.name;
+                return (
+                  <TouchableOpacity
+                    key={wallet.name}
+                    style={[styles.walletItem, isConnecting && styles.walletItemConnecting]}
+                    onPress={() => handleSelectWallet(wallet)}
+                    disabled={isConnecting}
+                  >
+                    <View style={styles.walletIconContainer}>
+                      {wallet.iconUrl ? (
+                        <Image source={{ uri: wallet.iconUrl }} style={styles.walletIcon} />
+                      ) : (
+                        <View style={styles.walletIconPlaceholder}>
+                          <Text style={styles.walletIconText}>
+                            {wallet.name.charAt(0).toUpperCase()}
+                          </Text>
+                        </View>
+                      )}
+                    </View>
+                    <View style={styles.walletInfo}>
+                      <Text style={styles.walletName}>{wallet.name}</Text>
+                      <Text style={styles.walletAppName}>{wallet.appName}</Text>
+                    </View>
+                    {isConnecting && (
+                      <View style={styles.connectingIndicator}>
+                        <Text style={styles.connectingText}>Connecting...</Text>
+                      </View>
+                    )}
+                  </TouchableOpacity>
+                );
+              })
+            )}
+          </ScrollView>
+
+          {/* Footer */}
+          <View style={styles.footer}>
+            <Text style={styles.footerText}>
+              By connecting, you agree to the app's Terms of Service and Privacy Policy
+            </Text>
+          </View>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: 'rgba(0, 0, 0, 0.5)',
+    justifyContent: 'flex-end',
+  },
+  modalContainer: {
+    backgroundColor: '#1a1a1a',
+    borderTopLeftRadius: 24,
+    borderTopRightRadius: 24,
+    maxHeight: '85%',
+    paddingBottom: Platform.OS === 'ios' ? 34 : 20,
+  },
+  header: {
+    padding: 24,
+    borderBottomWidth: 1,
+    borderBottomColor: '#2a2a2a',
+    position: 'relative',
+  },
+  title: {
+    fontSize: 28,
+    fontWeight: 'bold',
+    color: '#ffffff',
+    marginBottom: 8,
+  },
+  subtitle: {
+    fontSize: 15,
+    color: '#999999',
+    lineHeight: 20,
+  },
+  closeButton: {
+    position: 'absolute',
+    top: 24,
+    right: 24,
+    width: 32,
+    height: 32,
+    borderRadius: 16,
+    backgroundColor: '#2a2a2a',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  closeButtonText: {
+    color: '#ffffff',
+    fontSize: 18,
+    fontWeight: '600',
+  },
+  walletList: {
+    padding: 16,
+    maxHeight: 400,
+  },
+  walletItem: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: 16,
+    backgroundColor: '#2a2a2a',
+    borderRadius: 16,
+    marginBottom: 12,
+    minHeight: 72,
+  },
+  walletItemConnecting: {
+    opacity: 0.7,
+  },
+  walletIconContainer: {
+    marginRight: 16,
+  },
+  walletIcon: {
+    width: 48,
+    height: 48,
+    borderRadius: 12,
+  },
+  walletIconPlaceholder: {
+    width: 48,
+    height: 48,
+    borderRadius: 12,
+    backgroundColor: '#3a3a3a',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  walletIconText: {
+    color: '#ffffff',
+    fontSize: 20,
+    fontWeight: 'bold',
+  },
+  walletInfo: {
+    flex: 1,
+  },
+  walletName: {
+    fontSize: 17,
+    fontWeight: '600',
+    color: '#ffffff',
+    marginBottom: 4,
+  },
+  walletAppName: {
+    fontSize: 14,
+    color: '#999999',
+  },
+  connectingIndicator: {
+    marginLeft: 12,
+  },
+  connectingText: {
+    fontSize: 14,
+    color: '#0088cc',
+    fontWeight: '500',
+  },
+  emptyState: {
+    padding: 40,
+    alignItems: 'center',
+  },
+  emptyStateText: {
+    fontSize: 18,
+    fontWeight: '600',
+    color: '#ffffff',
+    marginBottom: 8,
+  },
+  emptyStateSubtext: {
+    fontSize: 14,
+    color: '#999999',
+    textAlign: 'center',
+  },
+  footer: {
+    padding: 16,
+    borderTopWidth: 1,
+    borderTopColor: '#2a2a2a',
+  },
+  footerText: {
+    fontSize: 12,
+    color: '#666666',
+    textAlign: 'center',
+    lineHeight: 16,
+  },
+});
+

package/src/react/index.ts

@@ -21,4 +21,6 @@ export type {
 } from './TonConnectUIProvider';
 export { TonConnectButton } from './TonConnectButton';
 export type { TonConnectButtonProps } from './TonConnectButton';
+export { WalletSelectionModal } from './WalletSelectionModal';
+export type { WalletSelectionModalProps } from './WalletSelectionModal';
 

package/src/utils/retry.ts

@@ -0,0 +1,101 @@
+/**
+ * Retry Utilities
+ * Helper functions for retrying operations with exponential backoff
+ */
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default: 3) */
+  maxAttempts?: number;
+  /** Initial delay in milliseconds (default: 1000) */
+  initialDelay?: number;
+  /** Maximum delay in milliseconds (default: 10000) */
+  maxDelay?: number;
+  /** Multiplier for exponential backoff (default: 2) */
+  multiplier?: number;
+  /** Function to determine if error should be retried (default: retry all errors) */
+  shouldRetry?: (error: Error) => boolean;
+}
+
+/**
+ * Retry a function with exponential backoff
+ * @param fn - Function to retry
+ * @param options - Retry options
+ * @returns Promise that resolves with the function result
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    initialDelay = 1000,
+    maxDelay = 10000,
+    multiplier = 2,
+    shouldRetry = () => true,
+  } = options;
+
+  let lastError: Error | null = null;
+  let delay = initialDelay;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Don't retry if shouldRetry returns false
+      if (!shouldRetry(lastError)) {
+        throw lastError;
+      }
+
+      // Don't retry on last attempt
+      if (attempt === maxAttempts) {
+        throw lastError;
+      }
+
+      // Wait before retrying
+      await new Promise<void>((resolve) => setTimeout(() => resolve(), delay));
+
+      // Increase delay for next attempt (exponential backoff)
+      delay = Math.min(delay * multiplier, maxDelay);
+    }
+  }
+
+  // This should never be reached, but TypeScript needs it
+  throw lastError || new Error('Retry failed');
+}
+
+/**
+ * Retry with custom delay function
+ * @param fn - Function to retry
+ * @param getDelay - Function that returns delay for each attempt (attempt number, last error)
+ * @param maxAttempts - Maximum number of attempts
+ * @returns Promise that resolves with the function result
+ */
+export async function retryWithCustomDelay<T>(
+  fn: () => Promise<T>,
+  getDelay: (attempt: number, error: Error | null) => number,
+  maxAttempts: number = 3
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Don't retry on last attempt
+      if (attempt === maxAttempts) {
+        throw lastError;
+      }
+
+      // Wait before retrying
+      const delay = getDelay(attempt, lastError);
+      await new Promise<void>((resolve) => setTimeout(() => resolve(), delay));
+    }
+  }
+
+  throw lastError || new Error('Retry failed');
+}
+