[jasmine874]

Closes #927
Closes #928
Closes #929
Closes #930

Issues

#927 Implement comprehensive error handling and user-friendly error messages

Overview

Add clear error messages and recovery suggestions for all error scenarios.

Requirements

• Define error types
• Create error message templates
• Implement error boundaries
• Add recovery suggestions
• Log errors for debugging
• Test error scenarios

Acceptance Criteria

[ ] All errors caught
[ ] Messages helpful
[ ] Recovery options clear
[ ] Errors logged
[ ] Users not confused

Definition of Done

All CI checks must pass before the PR is reviewed.

#928 Add retry logic with exponential backoff for failed operations

Overview

Automatically retry failed operations with exponential backoff.

Requirements

• Identify retryable operations
• Implement retry handler
• Add exponential backoff
• Set maximum retry limits
• Add retry notifications
• Track retry metrics

Acceptance Criteria

[ ] Transient failures retried
[ ] Backoff prevents thundering herd
[ ] User notified of retries
[ ] No infinite retries
[ ] Metrics available

Definition of Done

All CI checks must pass before the PR is reviewed.

#929 Implement offline queue for failed transactions

Overview

Queue failed transactions and retry when connection restored.

Requirements

• Detect connectivity changes
• Queue failed operations
• Persist queue to storage
• Retry on connection restore
• Allow manual retry/discard
• Notify user of queue status

Acceptance Criteria

[ ] Queue works offline
[ ] Queue survives app restart
[ ] Retries succeed on reconnect
[ ] User can manage queue
[ ] Performance not impacted

Definition of Done

All CI checks must pass before the PR is reviewed.

#930 Add comprehensive API documentation with OpenAPI/Swagger

Overview

Create machine-readable API documentation with examples.

Requirements

• Define OpenAPI schema
• Document all endpoints
• Add request/response examples
• Include error scenarios
• Generate interactive docs
• Keep docs synchronized

Acceptance Criteria

[ ] All endpoints documented
[ ] Examples working
[ ] Docs up-to-date
[ ] Interactive docs functional
[ ] Easy to understand

Definition of Done

All CI checks must pass before the PR is reviewed.

Summary

Implement in dependency order: error taxonomy and retry utility first (errors.ts), then parser, API clients, hooks, offline queue and UI, then OpenAPI docs and CI tests. Keep backward-compatible exports (classifyError, classifyRpcError, ParsedStellarError) to avoid breaking existing callers. Use fake timers for backoff tests and fake-indexeddb for queue persistence tests. Ensure all new modules are covered by both Jest and Vitest where applicable, and that the OpenAPI drift test fails CI when routes change without spec updates.

Changes

• Define a unified AppError taxonomy and message-template system. Add an AppError class/union with codes (network, validation, auth, wallet, contract, rate_limit, unknown), severity, retryable flag, and user-safe messages. Add message templates and recovery-suggestion mappings keyed by error code, plus a structured logger helper. Keep existing classifyError/classifyRpcError exports for backward compatibility. Also add a reusable retry utility (retryWithBackoff) with max attempts, base/max delay, jitter, isRetryable predicate, cancellation support, and in-memory metrics counters (attempts, successes, failures, latency) exposed for debugging. Add unit tests for error mapping, templates, and retry/backoff behavior using fake timers. (src/lib/errors.ts)
• Extend the Stellar error parser to normalize Stellar/Horizon/RPC errors into the new AppError taxonomy. Map known result codes (tx_insufficient_fee, tx_bad_seq, etc.) to AppError codes with retryable flags and recovery suggestions, and fall back to a generic AppError for unknown codes. Preserve the existing ParsedStellarError API for current callers. Add unit tests covering known codes, Horizon response shapes, and unknown errors. (src/lib/stellarErrorParser.ts)
• Wrap the CSRF-aware fetch wrapper so all mutating API calls throw AppError instances on non-OK responses (mapping HTTP status to error codes) and use retryWithBackoff for transient failures (network errors, 5xx, 429) with exponential backoff and jitter. Keep the existing single 403 CSRF retry behavior, and emit retry notifications via a callback/event so the UI can toast. Add tests for AppError mapping and retry behavior. (src/lib/apiClient.ts)
• Integrate the shared retry utility into the 429 rate-limit fetch wrapper: replace the single ad-hoc retry with retryWithBackoff honoring Retry-After, max attempts, and jitter, while preserving the RateLimitContext notification behavior. Throw AppError on final failure and record retry metrics. Add tests for backoff, Retry-After parsing, and max-attempt limits. (src/lib/api.ts)
• Harden the offline transaction queue: define a serializable queued-transaction schema with id, payload, status, attempts, timestamps, and error info; persist to IndexedDB with a localStorage fallback and hydrate on startup; add connectivity listeners that drain the queue on reconnect using retryWithBackoff; expose manual retry/discard APIs and queue-status notifications. Ensure batching/debouncing so performance is not impacted. Add tests for persistence across restart, reconnect retry, and manual management. (src/lib/offlineQueue.ts)
• Implement the OfflineQueueSync component to hydrate the persisted queue on mount, subscribe to online/offline events, drain the queue on reconnect using the retry utility, update item statuses, and surface queue status plus manual retry/discard actions via toasts and banners. Debounce reconnect handling to avoid duplicate drains. Add tests for reconnect retry and manual management. (src/components/OfflineQueueSync.tsx)
• Update the OfflineBanner to also display offline-queue status (number of queued transactions, pending retries) and a link/action to manage the queue, while keeping the existing online/offline detection. Ensure accessibility attributes remain correct. (src/components/OfflineBanner.tsx)
• Update the root ErrorBoundary to use the new AppError taxonomy and message templates: render friendly user-safe messages, recovery suggestions (retry, go back, contact support), and structured logging via the shared logger. Preserve Sentry capture and copy-details behavior. Add tests for rendering friendly messages and recovery actions. (src/components/ErrorBoundary.tsx)
• Update the app-level error page to classify the error with the shared taxonomy, show a friendly message and recovery suggestions, and log via the structured logger instead of raw console.error. Keep the dev-only details section. (src/app/error.tsx)
• Update the global error page to use the shared error taxonomy for a friendly message and recovery suggestions, and log via the structured logger in addition to Sentry. Keep inline styles since this renders outside the app shell. (src/app/global-error.tsx)
• Update the dashboard route error boundary to classify the error, render a friendly message with recovery suggestions, and log via the structured logger. Preserve Sentry event ID display and retry/home actions. (src/app/dashboard/error.tsx)
• Update the payments route error boundary to classify the error, render a friendly message with recovery suggestions, and log via the structured logger. Preserve Sentry event ID display and retry/dashboard actions. (src/app/payments/error.tsx)
• Update the invoice detail route error boundary to classify the error, render a friendly message with recovery suggestions, and log via the structured logger. Preserve Sentry event ID display and retry/dashboard actions. (src/app/invoice/[id]/error.tsx)
• Refactor the transaction retry hook to use the shared retryWithBackoff utility instead of its own delay loop, keeping toast notifications for retries and final failure, respecting cancellation, and recording retry metrics. Ensure no infinite retries and that AppError retryable flags drive decisions. Add tests with fake timers. (src/hooks/useTransactionWithRetry.ts)
• Wrap payment submission (simulation and confirm) in retryWithBackoff for transient failures, convert errors to AppError with friendly messages, and surface retry notifications via the toast context. On unrecoverable network failure, enqueue the transaction in the offline queue. Add tests for retry and queue handoff. (src/hooks/usePaymentSubmission.ts)
• Integrate retryWithBackoff around Horizon submission and confirmation polling for transient network errors, convert failures to AppError with friendly messages, emit retry toasts, and record metrics. On persistent network failure, enqueue the transaction in the offline queue. Preserve user-rejection handling and double-submit guard. (src/hooks/useStellarTransaction.ts)
• Extend the toast context to support retry/queue notifications: add helpers for showing retry countdowns, queue status, and actionable toasts (retry/discard) while keeping existing success/error/info/loading APIs. Ensure deduplication and auto-dismiss behavior remain correct. (src/contexts/ToastContext.tsx)
• Add a retry/queue configuration section to the app config: max retry attempts, base and max backoff delays, jitter factor, offline queue limits, and feature flags. Export typed constants for use by the retry utility, API client, and offline queue. (src/lib/config.ts)
• Author an OpenAPI 3.1 specification covering every API route with schemas, request/response examples, auth, and error responses aligned with the AppError taxonomy. Include example payloads and error scenarios, and document how to regenerate/update the spec. (public/openapi.json)
• Add a CI test that validates the OpenAPI spec (schema validity, required fields, examples) and compares documented paths/methods against the actual route handlers to detect drift. Fail CI when docs are out of sync. (src/tests/openapi.test.ts)
• Add a Swagger UI route that serves the interactive OpenAPI documentation from public/openapi.json, with a link from developer docs. Ensure the route is excluded from CSP-sensitive inline script restrictions or uses nonce-compatible loading. (src/app/api-docs/page.tsx)
• Update the middleware matcher to exclude the API docs route and static OpenAPI spec from CSP nonce processing where appropriate, ensuring Swagger UI assets load correctly while keeping CSP protections for the rest of the app. (src/middleware.ts)
• Update Jest configuration to include tests for the new error taxonomy, retry utility, offline queue, and OpenAPI spec validation, and ensure coverage thresholds account for the new modules. (jest.config.js)
• Update Vitest configuration to include the new test files and ensure jsdom environment supports IndexedDB mocks for offline queue tests and fetch mocks for retry tests. (vitest.config.ts)
• Add shared test setup for the new reliability features: mock IndexedDB (fake-indexeddb), mock navigator.onLine and online/offline events, mock fetch, and reset retry metrics between tests. (vitest.setup.ts)
• Add Jest setup mocks for IndexedDB, navigator.onLine, online/offline events, and fetch so the new error, retry, and offline queue tests run reliably. (jest.setup.ts)
• Add Playwright end-to-end tests covering error boundary rendering with friendly messages, retry behavior on transient failures, offline queue persistence and reconnect retry, and the interactive API docs page. (playwright.config.ts)

[drips-wave]

@jasmine874 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

[vercel]

@jasmine874 is attempting to deploy a commit to the kingsman-99's projects Team on Vercel.

A member of the Team first needs to authorize it.