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

const balance = await mina.getBalance({
  address: walletAddress,
  chainId: 1,
  tokenAddress: USDC_ADDRESS,
});

console.log(`${balance.formatted} ${balance.token.symbol}`);
// "1000.50 USDC"

if (balance.balanceUsd) {
  console.log(`Worth: $${balance.balanceUsd.toFixed(2)}`);
}

interface BalanceParams {
  /** Wallet address to fetch balance for */
  address: string;
  /** Chain ID */
  chainId: number;
  /** Token contract address (or NATIVE_TOKEN_ADDRESS for native token) */
  tokenAddress: string;
}

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

// Get USDC balance
const usdcBalance = await mina.getBalance({
  address: '0x1234...',
  chainId: 1,
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
});

// Get native ETH balance
const ethBalance = await mina.getBalance({
  address: '0x1234...',
  chainId: 1,
  tokenAddress: NATIVE_TOKEN_ADDRESS,
});

interface MultiBalanceParams {
  /** Wallet address to fetch balances for */
  address: string;
  /** Chain IDs to fetch balances from */
  chainIds: number[];
  /** Optional: specific token addresses per chain */
  tokenAddresses?: Record<number, string[]>;
}

const balances = await mina.getBalances({
  address: walletAddress,
  chainIds: [1, 42161, 10], // Ethereum, Arbitrum, Optimism
  tokenAddresses: {
    1: [USDC_ETH, USDT_ETH],
    42161: [USDC_ARB],
    10: [USDC_OP],
  },
});

interface BalanceWithMetadata extends Balance {
  /** Whether the balance is greater than zero */
  hasBalance: boolean;
}

const balance = await mina.getBalance(params);

if (balance.hasBalance) {
  // User has tokens, can proceed with bridge
  enableBridgeButton();
} else {
  // User has no balance
  showDepositPrompt();
}

interface BalancesResponse {
  /** Balances grouped by chain ID */
  balances: Record<number, BalanceWithMetadata[]>;
  /** Total USD value across all chains */
  totalUsd: number;
  /** Whether the data is from stale cache */
  isStale: boolean;
  /** Timestamp when data was cached (null if fresh) */
  cachedAt: number | null;
}

const response = await mina.getBalances({
  address: walletAddress,
  chainIds: [1, 42161, 10],
});

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

for (const [chainId, chainBalances] of Object.entries(response.balances)) {
  console.log(`Chain ${chainId}:`);
  chainBalances.forEach(b => {
    if (b.hasBalance) {
      console.log(`  ${b.formatted} ${b.token.symbol}`);
    }
  });
}

interface SingleBalanceResponse {
  /** The balance data */
  balance: BalanceWithMetadata;
  /** Whether the data is from stale cache */
  isStale: boolean;
  /** Timestamp when data was cached (null if fresh) */
  cachedAt: number | null;
}

const response = await mina.getBalanceWithMetadata({
  address: walletAddress,
  chainId: 1,
  tokenAddress: USDC_ADDRESS,
});

if (response.isStale) {
  showWarning('Balance data may be outdated');
}

console.log(`Balance: ${response.balance.formatted}`);

interface BalanceValidation {
  /** Overall validation result */
  valid: boolean;
  /** Whether token balance is sufficient */
  tokenSufficient: boolean;
  /** Whether gas balance is sufficient */
  gasSufficient: boolean;
  /** List of warnings if any */
  warnings: BalanceWarning[];
}

const validation = await mina.validateBalance(quote, walletAddress);

if (!validation.valid) {
  validation.warnings.forEach(warning => {
    if (warning.type === 'INSUFFICIENT_BALANCE') {
      console.error(warning.message);
      console.error(`Need ${warning.shortfall} more ${warning.token.symbol}`);
    }
    if (warning.type === 'INSUFFICIENT_GAS') {
      console.error('Not enough gas:', warning.message);
    }
  });
}

interface BalanceWarning {
  /** Type of warning */
  type: BalanceWarningType;
  /** Token that is insufficient */
  token: Token;
  /** Amount required for the transaction */
  required: string;
  /** User's available balance */
  available: string;
  /** Shortfall amount needed */
  shortfall: string;
  /** Human-readable message */
  message: string;
}

type BalanceWarningType = 'INSUFFICIENT_BALANCE' | 'INSUFFICIENT_GAS';

interface BalanceCheckResult {
  /** Whether balance is sufficient for the amount */
  sufficient: boolean;
  /** User's balance in smallest unit */
  balance: string;
  /** User's formatted balance */
  formatted: string;
  /** Balance in USD (if available) */
  balanceUsd?: number;
  /** Required amount in smallest unit */
  required: string;
  /** Shortfall if insufficient (in smallest unit) */
  shortfall?: string;
  /** Token info */
  token: Token;
}

const check = await mina.checkBalance(
  1,                    // chainId
  USDC_ADDRESS,         // tokenAddress
  walletAddress,        // walletAddress
  '1000000000'          // amount (1000 USDC)
);

if (!check.sufficient) {
  console.log(`Need ${check.shortfall} more (${check.formatted} available)`);
}