abstract class MinaError extends Error {
  /** Unique error code for programmatic handling */
  abstract readonly code: string;
  /** Whether this error is recoverable via retry */
  abstract readonly recoverable: boolean;
  /** The step where this error occurred */
  readonly step?: StepType;
  /** User-friendly error message for display */
  readonly userMessage: string;
  /** Suggested recovery action */
  readonly recoveryAction: RecoveryAction;
  /** Additional details for debugging */
  readonly details?: Record<string, unknown>;
}

type RecoveryAction =
  | 'retry'
  | 'add_funds'
  | 'increase_slippage'
  | 'try_different_amount'
  | 'try_again'
  | 'fetch_new_quote'
  | 'contact_support'
  | 'switch_network'
  | 'check_allowance'
  | 'adjust_slippage';

class InsufficientBalanceError extends MinaError {
  readonly code = 'INSUFFICIENT_BALANCE';
  readonly recoverable = false;
  readonly required: string;   // Amount needed
  readonly available: string;  // Amount user has
  readonly token: string;      // Token symbol
}

class NoRouteFoundError extends MinaError {
  readonly code = 'NO_ROUTE_FOUND';
  readonly recoverable = false;
  readonly fromChainId: number;
  readonly toChainId: number;
  readonly fromToken: string;
  readonly toToken: string;
}

class SlippageExceededError extends MinaError {
  readonly code = 'SLIPPAGE_EXCEEDED';
  readonly recoverable = true;
  readonly expectedAmount: string;
  readonly actualAmount: string;
  readonly slippageTolerance: number;
}

class InvalidSlippageError extends MinaError {
  readonly code = 'INVALID_SLIPPAGE';
  readonly recoverable = false;
  readonly provided: number;
  readonly min: number;
  readonly max: number;
}

class TransactionFailedError extends MinaError {
  readonly code = 'TRANSACTION_FAILED';
  readonly recoverable = true;
  readonly txHash?: string;
  readonly chainId: number;
  readonly reason?: string;
}

class UserRejectedError extends MinaError {
  readonly code = 'USER_REJECTED';
  readonly recoverable = false;
}

class NetworkError extends MinaError {
  readonly code = 'NETWORK_ERROR';
  readonly recoverable = true;
  readonly endpoint?: string;
  readonly statusCode?: number;
}

class DepositFailedError extends MinaError {
  readonly code = 'DEPOSIT_FAILED';
  readonly recoverable = true;
  readonly bridgeTxHash?: string;
  readonly depositTxHash?: string;
  readonly amount: string;
}

class ChainFetchError extends Error {
  readonly code = 'CHAIN_FETCH_FAILED';
  readonly recoveryAction = 'retry';
  readonly cachedAvailable: boolean;
}

class MaxRetriesExceededError extends MinaError {
  readonly code = 'MAX_RETRIES_EXCEEDED';
  readonly recoverable = false;
  readonly previousErrors: Error[];
  readonly executionId: string;
}

class QuoteExpiredError extends MinaError {
  readonly code = 'QUOTE_EXPIRED';
  readonly recoverable = true;
  readonly quoteId: string;
  readonly expiredAt: number;
}

class TokenFetchError extends Error {
  readonly code = 'TOKEN_FETCH_FAILED';
  readonly recoveryAction = 'retry';
  readonly cachedAvailable: boolean;
  readonly chainId?: number;
}

class BalanceFetchError extends Error {
  readonly code = 'BALANCE_FETCH_FAILED';
  readonly recoveryAction = 'retry';
  readonly cachedAvailable: boolean;
  readonly chainId?: number;
}

class InvalidAddressError extends Error {
  readonly code = 'INVALID_ADDRESS';
  readonly address: string;
}

class QuoteFetchError extends MinaError {
  readonly code = 'QUOTE_FETCH_FAILED';
  readonly recoverable = true;
}

class MinimumDepositError extends MinaError {
  readonly code = 'MINIMUM_DEPOSIT_NOT_MET';
  readonly recoverable = false;
  readonly minimumAmount: string;
  readonly requestedAmount: string;
}

class InsufficientGasError extends MinaError {
  readonly code = 'INSUFFICIENT_GAS';
  readonly recoverable = false;
  readonly required: string;
  readonly available: string;
}

class DepositTransactionError extends MinaError {
  readonly code = 'DEPOSIT_TRANSACTION_FAILED';
  readonly recoverable = true;
  readonly txHash?: string;
  readonly reason?: string;
}

// Typically thrown when monitoring times out or is manually cancelled

// Thrown when the L1 address format is invalid

// Check if error is any MinaError
function isMinaError(error: unknown): error is MinaError;

// Check if error is recoverable
function isRecoverableError(error: unknown): boolean;

// Specific error type guards
function isInsufficientBalanceError(error: unknown): error is InsufficientBalanceError;
function isNoRouteFoundError(error: unknown): error is NoRouteFoundError;
function isSlippageExceededError(error: unknown): error is SlippageExceededError;
function isInvalidSlippageError(error: unknown): error is InvalidSlippageError;
function isTransactionFailedError(error: unknown): error is TransactionFailedError;
function isUserRejectedError(error: unknown): error is UserRejectedError;
function isNetworkError(error: unknown): error is NetworkError;
function isDepositFailedError(error: unknown): error is DepositFailedError;
function isMaxRetriesExceededError(error: unknown): error is MaxRetriesExceededError;
function isQuoteExpiredError(error: unknown): error is QuoteExpiredError;

import {
  isMinaError,
  isInsufficientBalanceError,
  isUserRejectedError
} from '@mina-bridge/sdk';

try {
  const result = await mina.execute({ quote, signer });
} catch (error) {
  if (isMinaError(error)) {
    // Display user-friendly message
    showError(error.userMessage);

    // Handle specific recovery actions
    switch (error.recoveryAction) {
      case 'add_funds':
        showDepositModal();
        break;
      case 'fetch_new_quote':
        await refreshQuote();
        break;
      case 'retry':
        await retryExecution();
        break;
    }
  }
}

try {
  await mina.execute({ quote, signer });
} catch (error) {
  if (isUserRejectedError(error)) {
    // User cancelled - just reset UI
    resetUI();
    return;
  }

  if (isInsufficientBalanceError(error)) {
    showError(`Need ${error.required} ${error.token}, have ${error.available}`);
    return;
  }

  if (isSlippageExceededError(error)) {
    const increase = confirm('Slippage exceeded. Increase tolerance?');
    if (increase) {
      await retryWithHigherSlippage();
    }
    return;
  }

  // Unknown error
  console.error('Unexpected error:', error);
  showError('Something went wrong. Please try again.');
}

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

try {
  await mina.execute({ quote, signer });
} catch (error) {
  if (isRecoverableError(error)) {
    showRetryButton();
  } else {
    showContactSupport();
  }
}

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

try {
  // Some operation that might throw
} catch (error) {
  const minaError = normalizeError(error, 'bridge');
  // Now you can safely access .code, .userMessage, etc.
  console.log(minaError.code);
  console.log(minaError.userMessage);
}