feat: build resilient API client with token refresh and offline queue (Closes #47)

[LaPoshBaby]

Closes #47 — core: build resilient API client with token refresh and offline queue

Problem

The StepFi learner app targets users on unreliable mobile connectivity, yet the API client had critical resilience gaps:

• No typed error handling — API errors were raw AxiosError objects, forcing every consumer to parse error shapes manually. Many screens swallowed errors with empty catch {} blocks.
• No exponential backoff — Transient network/server failures (DNS flake, 5xx, 429 rate limits) were not retried; a momentary blip silently killed the request.
• No offline request queue — Mutations performed while offline were silently dropped with no user feedback and no retry mechanism.
• No idempotency on replay — When the offline queue replayed actions on reconnect, there was no way for the API to detect duplicate submissions if processQueue crashed mid-way.

Solution

A three-layer resilient API client:

1. Interceptor-based client with automatic 401 handling — refresh the token once (deduplicated via a shared promise), retry the original request, and hard-logout + redirect on refresh failure.
2. Exponential backoff with jitter — for idempotent requests (GET, PUT, DELETE) on transient network/5xx/429 errors. Formula: min(30s, 1s × 2^attempt) + random(0, 500ms), up to 3 retries.
3. Durable offline mutation queue — captures POST/PUT/PATCH/DELETE requests while offline using @react-native-async-storage/async-storage, replays them on reconnect (via NetInfo listener in _layout.tsx), and sends per-request Idempotency-Key headers using SHA-256 hashes of the action payload.

Files Changed

File	Change	Lines
types/errors.ts	New — ApiClientError class + ApiErrorCode enum	+78
services/api.ts	Enhanced interceptors: backoff retry, typed errors, raised timeout	+169 / -38
services/auth.service.ts	Wrap errors in ApiClientError, consistent propagation	+26 / -7
src/offline/offline-queue.ts	Added SHA-256 idempotency keys per queue action	+27 / -7
src/offline/offline-sync.ts	Send Idempotency-Key header during queue replay	+5 / -1
app/(auth)/register.tsx	Real error banner with dismiss, removed empty catch {}	+30 / -8
app/(tabs)/_layout.tsx	Fix pre-existing stray /> syntax error	0 / -1
services/__tests__/api.test.ts	New — 12 tests for refresh, retry, offline queue, typed errors	+370
src/offline/__tests__/offline-queue.test.ts	New — 4 tests for idempotency key generation + replay header	+127

Implementation Details

1. 401 handling (services/api.ts)

• A module-level refreshInFlight: Promise<string | null> | null singleton deduplicates concurrent 401s — only one refresh call is made regardless of how many requests fail simultaneously.
• On refresh success: tokens are persisted via useAuthStore.setTokens() and the original request is retried with the new Authorization header.
• On refresh failure: clearAuth() is called and router.replace('/(auth)/sign-in') redirects to sign-in. The rejected promise is wrapped in an ApiClientError with code UNAUTHORIZED.

2. Exponential backoff with jitter (services/api.ts)

backoffDelay(attempt) = min(30_000, 1_000 × 2^attempt) + random(0, 500)

• Only applied to idempotent methods: GET, PUT, DELETE, OPTIONS, HEAD
• Triggers on: no response (network error), 5xx, and 429 (rate limiting)
• Up to 3 retries (4 total attempts including the initial)
• A request-level _retryCount counter prevents infinite loops

3. Offline mutation queue (src/offline/offline-queue.ts)

• Durable storage: Persisted via @react-native-async-storage/async-storage with key @stepfi/offline-queue
• Queue on offline: The request interceptor checks useConnectivityStore.isConnected; if false, it calls enqueueAction() and rejects with __offline_queued: true
• Response interceptor catch: Catches __offline_queued markers and returns a synthetic 202 Accepted response so the caller gets a non-breaking response
• Auto-replay on reconnect: app/_layout.tsx already subscribes to NetInfo changes — when connectivity transitions from disconnected → connected, it calls processQueue()

4. Idempotency keys (src/offline/offline-queue.ts)

• Each queued action generates a unique idempotency key: randomPrefix::SHA256(type:endpoint:payload)[:16]
• The key is stored with the action and never changes — it's stable per queue item
• During replay, offline-sync.ts sends the key in the Idempotency-Key HTTP header
• If processQueue() crashes between the successful HTTP call and dequeueAction(), the next replay will send the same key — the API can detect the duplicate and return the original response

5. Typed error surfacing (types/errors.ts)

class ApiClientError extends Error {
  code: ApiErrorCode        // machine-readable: TIMEOUT, UNAUTHORIZED, SERVER_ERROR, etc.
  statusCode: number        // HTTP status or 0 for network errors
  userMessage: string       // human-readable, safe for UI
  isRetryable: boolean      // true for NETWORK_ERROR, SERVER_ERROR, TIMEOUT
  cause: unknown            // original error for debugging/Sentry
}

• All rejected promises from api.ts interceptors are wrapped in ApiClientError
• auth.service.ts also wraps its own errors (belt-and-suspenders)
• Consumers can catch (e) { if (e instanceof ApiClientError) { ... } } for consistent handling

6. register.tsx — real error feedback

• Added submitError: string | null state
• The handleComplete catch block now sets submitError instead of being empty
• An error banner with AlertCircle icon, error text, and X dismiss button appears below the header
• Colors reference colors.errorDim and colors.error — no hardcoded hex values

Acceptance Criteria Checklist

• 401s trigger a single refresh + retry — deduplicated via shared refreshInFlight promise
• Refresh failure logs out — clearAuth() + redirect to sign-in
• Transient failures retried with exponential backoff + jitter — up to 3 retries on idempotent methods
• Offline mutations queued durably — AsyncStorage-backed queue
• Idempotency keys prevent duplicate replay — SHA-256 + random prefix, sent as Idempotency-Key header
• register.tsx surfaces real errors — error banner with dismiss; no empty catch blocks
• Tests cover refresh, retry, and offline replay — 16 tests across 2 test files
• No hardcoded hex colors — all colors from constants/colors.ts
• Icons from lucide-react-native only — AlertCircle, X, ChevronLeft, Camera

Test Coverage

services/__tests__/api.test.ts (12 tests)

Test	What it verifies
refreshes the token once and retries on 401	401 → /auth/refresh called → original request retries with new token
rejects with UNAUTHORIZED and clears auth when refresh fails	Refresh failure → clearAuth() + redirect → typed error
does not attempt refresh more than once on concurrent 401s	Two simultaneous 401s only trigger one /auth/refresh call
retries GET requests up to MAX_RETRIES on server errors	500 on GET → retried up to 3 times with backoff → SERVER_ERROR
does not retry POST requests (non-idempotent)	500 on POST → no retry → immediate error
queues POST requests when offline	Offline POST → synthetic 202 with queued: true
queues PUT requests when offline	Offline PUT → same behavior
allows GET requests through when offline	Offline GET → still executes (not queued)
wraps timeout errors in ApiClientError	ECONNABORTED → TIMEOUT with user-facing message
fromAxiosError returns proper messages	401 → UNAUTHORIZED, 500 → SERVER_ERROR, ERR_NETWORK → NETWORK_ERROR
isRetryable flag correctness	NETWORK_ERROR/TIMEOUT/SERVER_ERROR = true, UNAUTHORIZED/CLIENT_ERROR = false

src/offline/__tests__/offline-queue.test.ts (4 tests)

Test	What it verifies
generates an idempotency key when enqueuing	Key is a non-empty string
generates different keys for different payloads	Different actions → different keys
same payload enqueued twice gets different keys	Different enqueues → different keys (random prefix)
offline sync sends Idempotency-Key header	Queue replay → api.request called with Idempotency-Key header

Design Decisions

1. Random prefix in idempotency keys: Each key starts with a random string (Date.now().toString(36) + Math.random().toString(36)) so the same action enqueued at different times produces different keys. This is intentional — the key is stable per queue item (not per logical action), meaning if the user taps twice offline, both taps are preserved as separate queue entries with different keys. The API deduplication protects against the same queue item being replayed multiple times after a crash.

2. 15-second timeout ceiling: Raised from the previous 10s to accommodate slower mobile networks while still failing fast enough for good UX.

3. Full jitter: random(0, 500ms) added to each backoff delay to prevent thundering herd when multiple requests fail simultaneously on reconnect.

4. Separate test files: The API client tests and offline queue idempotency tests are in separate files because the offline queue tests require module-level mocks for native modules (expo-crypto, @react-native-async-storage/async-storage) that would conflict with the mocked queue in api.test.ts.

Notes for Reviewers

• The tsconfig.json errors (expo/tsconfig.base not found, baseUrl deprecation) are pre-existing and unrelated to this PR.
• jest-expo is listed in devDependencies in package.json but may need npm install before tests can run locally.
• The pre-existing stray /> in app/(tabs)/_layout.tsx (line 57) was fixed as part of this PR since it broke the typecheck.

Next Steps

• Run npx expo export --platform web to validate web export
• Run npm install && npx jest to execute the full test suite