feat: improve wallet session recovery and error handling

[Emmycivity]

Overview

Improves wallet session recovery and resilience across app reloads and reconnect scenarios, adds graceful handling of expired and corrupted sessions, and standardizes high-frequency wallet error messages across all wallet interaction points.

Related Issue

Closes #13

Before & After Behavior

• Before:
  • Session restoration on app reload did not validate Stellar address formatting, allowing malformed strings or zombie states to cause uncaught errors in downstream Soroban/Horizon RPC calls.
  • Expired or stale sessions in localStorage had no TTL expiration tracking and could leave the app in a broken state.
  • The disconnected banner in the dashboard only refreshed the page (window.location.reload()) rather than triggering an active reconnection flow.
  • Wallet error messages were scattered across multiple components (Login.tsx, DepositModal.tsx, CreditSection.tsx, Perfil.tsx, Retiros.tsx, Tesoreria.tsx), with hardcoded strings and inconsistent cancellation detection.
• After:
  • sessionStore and WalletSessionContext validate Stellar address format (isValidStellarAddress) and enforce session TTL (30 days), automatically and cleanly purging corrupted or expired sessions without crashing.
  • useWallet and WalletSessionContext expose an active reconnect() method, sessionError, and isExpired status, allowing one-click reconnection directly from UI banners.
  • Centralized src/lib/walletErrors.ts parses, classifies, and formats all wallet error codes (CANCELLED, POPUP_BLOCKED, WALLET_LOCKED, WALLET_MISSING, SESSION_EXPIRED, ACCOUNT_MISMATCH, ACCOUNT_NOT_FOUND, INSUFFICIENT_BALANCE, INSUFFICIENT_USDC, NO_LIQUIDITY, ACTIVE_LOAN, TIER_INSUFFICIENT, NETWORK_ERROR, CONTRACT_ERROR, GENERIC) with full i18n support in English and Spanish.

Changes

Wallet & Session Management

• [ADD] src/lib/walletErrors.ts
  • Centralized wallet error parser, classification, cancellation detection, address validation (isValidStellarAddress), and friendly message resolution.
• [MODIFY] src/lib/sessionStore.ts
  • Added saveSession, restoreSession, clearSession, and session TTL expiration checks (30 days).
• [MODIFY] src/context/WalletSessionContext.tsx
  • Added session validation on startup, reconnect() method, sessionError, isExpired, and clean reset handling.
• [MODIFY] src/hooks/useWallet.tsx
  • Exposed reconnect, sessionError, isExpired, clearSessionError, and provider.
• [MODIFY] src/lib/mobileWalletConnectors.ts
  • Standardized cancellation detection and error formatting using walletErrors.
• [MODIFY] src/wallet/FreighterAdapter.ts
  • Replaced direct localStorage access with sessionStore.

UI Components & Feedback

• [MODIFY] src/pages/Login.tsx
  • Integrated getFriendlyWalletMessage and surfaced session expiration feedback on login redirect.
• [MODIFY] src/pages/Index.tsx
  • Updated disconnected / expired session banner with active reconnect() button and error toast feedback.
• [MODIFY] src/components/DepositModal.tsx
  • Standardized error handling with getFriendlyWalletMessage.
• [MODIFY] src/components/CreditSection.tsx
  • Standardized error handling with getFriendlyWalletMessage.
• [MODIFY] src/pages/Retiros.tsx & src/pages/Tesoreria.tsx
  • Migrated from raw localStorage reads to useWallet / sessionStore and standardized contract error handling.
• [MODIFY] src/pages/Perfil.tsx
  • Integrated centralized error messaging for wallet and trustline interactions.
• [MODIFY] src/i18n/locales/en.ts & src/i18n/locales/es.ts
  • Added wallet_errors localization namespace for all error scenarios.

Testing

• [ADD] src/test/walletSessionAndErrors.test.tsx
  • 35 unit and integration tests covering address validation, session persistence, cookie fallback, corrupted data recovery, TTL expiration, error categorization, and hook/context lifecycle.

Verification Results

✓ src/test/example.test.ts (1 test)
✓ src/ws/hub.replay.test.ts (16 tests)
✓ src/test/calculate-score.test.ts (7 tests)
✓ src/test/walletSessionAndErrors.test.tsx (35 tests)

Test Files  4 passed (4)
     Tests  59 passed (59)

Acceptance Criteria	Status
Session state restores predictably after refresh	✅ Validated via restoreSession and WalletSessionProvider integration tests
Expired / invalid sessions handled gracefully	✅ Corrupted addresses and TTL-expired sessions purged cleanly with user feedback
Frequent wallet failures show clear user guidance	✅ Standardized error mapping and actionable messages with i18n support

[vercel]

@Emmycivity is attempting to deploy a commit to the alankcr1-6443's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Emmycivity Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits