View source on GitHub →

Phase 1 Complete: Offline Mode + Error Handling

What Was Implemented

1. Network State Monitoring ✅

New Files:

  • None (integrated into existing client)

Client Changes (sdk/react-native/src/client.ts):

  • Added NetworkState type ('online' | 'offline' | 'slow')
  • Added networkState getter
  • Implemented setupNetworkMonitoring() with NetInfo support
  • Added fallback basic network monitoring (periodic health checks)
  • Added onNetworkStateChange() subscription method
  • Auto-triggers queue processing when coming back online

Hook (sdk/react-native/src/hooks.ts):

  • useNetworkState(client) - Monitor network state with isOnline, isOffline, isSlow flags

2. Operation Queue System ✅

New File (sdk/react-native/src/queue-manager.ts):

  • QueueManager class for persistent operation queuing
  • Stores operations in SecureStorage
  • Retry logic with exponential backoff
  • Max 3 retries with delays: 1s, 2s, 4s
  • Status tracking: pending → processing → completed/failed
  • Queue change listeners

Client Integration:

  • Added queueManager instance
  • Added queue and pendingOperations getters
  • Added queueOperation() for manual queuing
  • Added processQueue() - auto-retries payments, votes
  • Added clearFailedOperations() method
  • Added onQueueChange() subscription

Hook:

  • useQueue(client) - Monitor queue with pendingCount, failedCount, clearFailed()

3. Structured Error Handling ✅

New File (sdk/react-native/src/error-utils.ts):

  • ICNError interface with type, message, userMessage, retryable
  • ICNErrorType enum: Network, Authentication, Validation, NotFound, RateLimit, ServerError, Unknown
  • parseError(response) - Parse HTTP errors into ICNError
  • createError(error, type?) - Wrap JS errors
  • isNetworkError() and isAuthError() helpers
  • User-friendly error messages for all error types

Error Types:

  • Network → "Unable to connect. Please check your internet connection..."
  • Authentication → "Your session has expired. Please log in again."
  • Validation → "Please check your input and try again."
  • RateLimit → "Too many requests. Please wait a moment..."
  • ServerError → "Server error. Please try again later."

4. Mobile UI Updates ✅

HomeScreen Changes:

  • Import useNetworkState and useQueue hooks
  • Enhanced status bar with three sections:
    • Connection status (Connected/Offline)
    • Offline mode indicator (⚠️ when offline)
    • Pending operations badge (shows count)
    • Failed operations badge (tap to clear)
  • Added styles for all new UI elements

Architecture

┌──────────────────────────────────────────────────────────┐
│              CoopWallet Mobile App                       │
│                                                          │
│  HomeScreen                                              │
│  ├─ useNetworkState() → online/offline/slow            │
│  ├─ useQueue() → pending/failed operations              │
│  └─ Auto-refresh on reconnect                           │
│                                                          │
└──────────────────────┬───────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────┐
│              ICNMobileClient                             │
│                                                          │
│  Network Monitoring                                      │
│  ├─ @react-native-community/netinfo (if available)     │
│  └─ Fallback: periodic health checks                    │
│                                                          │
│  Queue Manager                                           │
│  ├─ Persistent storage (SecureStore)                    │
│  ├─ Exponential backoff retry (3 attempts)              │
│  └─ Auto-process when online                            │
│                                                          │
│  Error Handling                                          │
│  ├─ Structured ICNError types                           │
│  ├─ User-friendly messages                              │
│  └─ Retryable flag for auto-retry                       │
│                                                          │
└──────────────────────────────────────────────────────────┘

User Experience Flow

Scenario 1: Payment While Offline

  1. User opens app, sees "⚠️ Offline Mode" badge
  2. User attempts payment
  3. Operation queued automatically
  4. UI shows "1 pending" badge
  5. User regains connectivity
  6. Queue auto-processes
  7. Payment succeeds, badge disappears
  8. Balance updates automatically

Scenario 2: Failed Payment

  1. User sends payment
  2. Server error occurs (500)
  3. Operation retries: 1s delay
  4. Fails again: 2s delay
  5. Fails third time: 4s delay
  6. Operation marked as failed
  7. UI shows "1 failed - tap to clear" badge
  8. User taps badge to remove from queue

Scenario 3: Network Recovery

  1. App goes offline during use
  2. WebSocket disconnects
  3. Status changes to "Offline"
  4. Several operations queued
  5. Network restored
  6. Status changes to "Connected"
  7. Queue auto-processes all pending operations
  8. UI refreshes with latest data

Files Modified

SDK Files

  1. sdk/react-native/src/client.ts (+150 lines)

    • Network monitoring
    • Queue integration
    • Auto-processing logic

  2. sdk/react-native/src/types.ts (+55 lines)

    • NetworkState type
    • QueuedOperation interface
    • ICNError types

  3. sdk/react-native/src/queue-manager.ts (NEW, 163 lines)

    • Complete queue management system

  4. sdk/react-native/src/error-utils.ts (NEW, 155 lines)

    • Error parsing and handling

  5. sdk/react-native/src/hooks.ts (+75 lines)

    • useNetworkState hook
    • useQueue hook

  6. sdk/react-native/src/index.ts (+6 lines)

    • Export new utilities and hooks

Mobile App Files

  1. sdk/react-native/examples/CoopWallet/src/screens/HomeScreen.tsx (+50 lines)
    • Network state display
    • Queue status display
    • Failed operation clearing

Test Status

  • ✅ SDK builds successfully
  • ✅ TypeScript compilation passes
  • ⏳ Runtime testing needed (requires network state changes)
  • ⏳ Queue persistence testing needed

Next Steps

Immediate:

  1. Add toast/snackbar notifications for errors
  2. Test queue persistence across app restarts
  3. Add retry button for failed operations
  4. Better error display in UI

Phase 2: Push Notifications (FCM) Phase 3: Trust Graph Integration

← Back to Docs