Balance Service

import {
  getBalance,
  getBalances,
  getChainBalances,
  getBalanceWithMetadata,
  validateBalance,
  checkBalance,
  createBalanceCache,
  BalanceCache,
  BalanceFetchError,
  InvalidAddressError,
  isBalanceFetchError,
  isInvalidAddressError,
} from '@mina-bridge/sdk/services/balance';

async function getBalance(
  chainId: number,
  tokenAddress: string,
  walletAddress: string,
  cache?: BalanceCache
): Promise<Balance>

import { getBalance, NATIVE_TOKEN_ADDRESS } from '@mina-bridge/sdk';

// Get USDC balance on Ethereum
const usdcBalance = await getBalance(
  1,
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  '0xYourWalletAddress...'
);

console.log(`USDC: ${usdcBalance.formatted}`);       // "1234.56"
console.log(`USD Value: $${usdcBalance.balanceUsd}`); // "1234.56"

// Get native ETH balance
const ethBalance = await getBalance(
  1,
  NATIVE_TOKEN_ADDRESS,
  '0xYourWalletAddress...'
);

console.log(`ETH: ${ethBalance.formatted}`);

async function getBalances(
  walletAddress: string,
  chainIds: number[],
  tokenAddresses?: Record<number, string[]>,
  cache?: BalanceCache
): Promise<BalancesResponse>

// Get native token balances on multiple chains
const response = await getBalances(
  '0x...',
  [1, 42161, 137]  // Ethereum, Arbitrum, Polygon
);

console.log(`Total portfolio: $${response.totalUsd.toFixed(2)}`);

// Access balances by chain
Object.entries(response.balances).forEach(([chainId, balances]) => {
  console.log(`Chain ${chainId}:`);
  balances.forEach(b => {
    console.log(`  ${b.token.symbol}: ${b.formatted}`);
  });
});

// Get specific tokens per chain
const response = await getBalances(
  '0x...',
  [1, 42161],
  {
    1: [
      '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
      '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
    ],
    42161: [
      '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', // USDC on Arbitrum
    ],
  }
);

async function getChainBalances(
  walletAddress: string,
  chainId: number,
  cache?: BalanceCache
): Promise<BalanceWithMetadata[]>

const balances = await getChainBalances('0x...', 1);

// Filter to tokens with non-zero balance
const nonZeroBalances = balances.filter(b => b.hasBalance);

console.log(`You have ${nonZeroBalances.length} tokens on Ethereum:`);
nonZeroBalances.forEach(b => {
  console.log(`  ${b.token.symbol}: ${b.formatted} ($${b.balanceUsd ?? 0})`);
});

async function getBalanceWithMetadata(
  chainId: number,
  tokenAddress: string,
  walletAddress: string,
  cache?: BalanceCache
): Promise<BalanceWithMetadata>

const balance = await getBalanceWithMetadata(
  1,
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  '0x...'
);

if (balance.hasBalance) {
  console.log(`Amount: ${balance.formatted} ${balance.token.symbol}`);
  console.log(`Price: $${balance.priceUsd}`);
  console.log(`Value: $${balance.balanceUsd}`);
}

async function validateBalance(
  quote: Quote,
  walletAddress: string,
  cache?: BalanceCache
): Promise<BalanceValidation>

const quote = await mina.getQuote({ ... });
const validation = await validateBalance(quote, '0x...');

if (!validation.valid) {
  validation.warnings.forEach(warning => {
    switch (warning.type) {
      case 'INSUFFICIENT_BALANCE':
        console.error(
          `Need ${warning.shortfall} more ${warning.token.symbol}`
        );
        break;
      case 'INSUFFICIENT_GAS':
        console.error(
          `Need ${warning.shortfall} more ${warning.token.symbol} for gas`
        );
        break;
      case 'LOW_GAS':
        console.warn(warning.message);
        break;
    }
  });
}

async function checkBalance(
  chainId: number,
  tokenAddress: string,
  walletAddress: string,
  amount: string,
  cache?: BalanceCache
): Promise<BalanceCheckResult>

// Check before showing quote UI
const check = await checkBalance(
  1,
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  '0x...',
  '1000000000' // 1000 USDC (6 decimals)
);

if (!check.sufficient) {
  console.log(`Balance: ${check.formatted}`);
  console.log(`Required: ${check.required}`);
  console.log(`Shortfall: ${check.shortfall}`);
} else {
  console.log('Sufficient balance to proceed');
}

class BalanceFetchError extends MinaError {
  readonly code: 'BALANCE_FETCH_FAILED';
  readonly chainId: number;
  readonly tokenAddress: string;
  readonly recoverable: true;
  readonly recoveryAction: 'retry';
  readonly cachedAvailable: boolean;
}

try {
  const balance = await getBalance(1, tokenAddress, walletAddress);
} catch (error) {
  if (isBalanceFetchError(error)) {
    console.error(`Failed to fetch balance for chain ${error.chainId}`);
    if (error.cachedAvailable) {
      console.log('Cached data may be available');
    }
  }
}

class InvalidAddressError extends MinaError {
  readonly code: 'INVALID_ADDRESS';
  readonly address: string;
  readonly recoverable: false;
}

try {
  const balance = await getBalance(1, tokenAddress, 'invalid-address');
} catch (error) {
  if (isInvalidAddressError(error)) {
    console.error(`Invalid address: ${error.address}`);
  }
}

class BalanceCache {
  /** Get cached balance if not expired */
  getBalance(
    chainId: number,
    tokenAddress: string,
    walletAddress: string
  ): { data: Balance; cachedAt: number } | null;

  /** Store balance in cache */
  setBalance(
    chainId: number,
    tokenAddress: string,
    walletAddress: string,
    balance: Balance
  ): void;

  /** Invalidate cache for a wallet or all */
  invalidate(walletAddress?: string): void;

  /** Check if cached balance exists (even if expired) */
  hasCached(
    chainId: number,
    tokenAddress: string,
    walletAddress: string
  ): boolean;

  /** Get balance even if expired (for fallback) */
  getBalanceStale(
    chainId: number,
    tokenAddress: string,
    walletAddress: string
  ): { data: Balance; cachedAt: number } | null;
}

const cache = createBalanceCache();

// First request - fetches from API
const balance1 = await getBalance(1, tokenAddr, walletAddr, cache);

// Second request within 30 seconds - uses cache
const balance2 = await getBalance(1, tokenAddr, walletAddr, cache);

// Force refresh for specific wallet
cache.invalidate('0x...');

// Force refresh all
cache.invalidate();

interface Balance {
  /** Token metadata */
  token: Token;
  /** Balance in smallest unit */
  balance: string;
  /** Balance formatted with decimals */
  formatted: string;
  /** Balance in USD */
  balanceUsd?: number;
}

interface BalanceWithMetadata extends Balance {
  /** Whether balance is greater than 0 */
  hasBalance: boolean;
  /** Chain ID */
  chainId: number;
  /** Current token price in USD */
  priceUsd?: number;
}

interface BalanceValidation {
  /** Whether validation passed */
  valid: boolean;
  /** Array of warnings */
  warnings: BalanceWarning[];
  /** Source token balance */
  tokenBalance: Balance;
  /** Native token balance for gas */
  gasBalance: Balance;
}

interface BalanceWarning {
  type: 'INSUFFICIENT_BALANCE' | 'INSUFFICIENT_GAS' | 'LOW_GAS';
  message: string;
  token: Token;
  required?: string;
  available: string;
  shortfall?: string;
}

interface BalanceCheckResult {
  /** Whether balance is sufficient */
  sufficient: boolean;
  /** Current balance in smallest unit */
  balance: string;
  /** Formatted balance */
  formatted: string;
  /** Required amount */
  required: string;
  /** Amount short (if insufficient) */
  shortfall?: string;
}