Merge pull request #263 from Phantomcall/feat/react-query-config-issue-226

feat: React Query configuration — stale times, retry policy, backgrou…

Author: jhayniffy

frontend/README.md

@@ -90,6 +90,48 @@ On failure, the Playwright job uploads traces and screenshots to the
 npx playwright show-report path/to/downloaded/playwright-report
 ```
 
+## React Query configuration
+
+All React Query settings are centralized in `src/lib/query/queryClientConfig.ts`. Per-component overrides are discouraged — add a new named constant to `STALE_TIMES` instead.
+
+### Stale times
+
+| Query type | Stale time | Rationale |
+|---|---|---|
+| `policies` | 30 s | Changes only on user-initiated transactions |
+| `claims` | 10 s | Any holder can file; moderate freshness needed |
+| `votes` | 5 s | Active voting windows are time-sensitive |
+| `ledger` | 5 s | New ledger every ~5 s |
+| `default` | 15 s | Catch-all for uncategorized queries |
+
+### Retry policy
+
+- Max **3 retries** for transient errors (network failures, 5xx, 429).
+- **No retry** for 4xx client errors (except 429 with Retry-After).
+- Exponential backoff: 1 s → 2 s → 4 s, capped at 30 s.
+
+### Background refetch
+
+- `refetchOnWindowFocus: false` globally. Enable per-query only for time-sensitive queries (e.g. active votes) by passing `refetchOnWindowFocus: true`.
+- `refetchOnReconnect: true` — always resync after coming back online.
+- `refetchIntervalInBackground: false` — respects the Page Visibility API; no polling on hidden tabs.
+
+### Offline support
+
+Use `useNetworkAwareQuery` (`src/lib/query/useNetworkAwareQuery.ts`) instead of `useQuery` for any query that uses `refetchInterval`. It automatically pauses interval-based refetch when the browser is offline or the tab is hidden, preventing battery drain on mobile.
+
+```ts
+import { useNetworkAwareQuery, STALE_TIMES } from '@/lib/query';
+
+const { data } = useNetworkAwareQuery({
+  queryKey: ['votes', claimId],
+  queryFn: () => fetchVoteTallies(claimId),
+  staleTime: STALE_TIMES.votes,
+  refetchInterval: 5_000,
+  refetchOnWindowFocus: true, // enabled for time-sensitive vote data
+});
+```
+
 ## Analytics
 
 Analytics uses [Plausible](https://plausible.io) (cookieless, no PII).

frontend/package.json

@@ -14,19 +14,20 @@
     "check-docs": "node scripts/check-docs-links.js"
   },
   "dependencies": {
-    "@creit.tech/stellar-wallets-kit": "^2.0.1",
+    "@creit.tech/stellar-wallets-kit": "^1.3.0",
     "@hookform/resolvers": "^5.2.2",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-toast": "^1.2.15",
+    "@tanstack/react-query": "^5.80.7",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
     "next": "^15.5.14",
     "next-intl": "^3.26.5",
-    "next-mdx-remote": "^5.0.0",
+    "next-mdx-remote": "^6.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-hook-form": "^7.72.0",
@@ -35,9 +36,11 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.10.1",
     "@next/bundle-analyzer": "^15.2.3",
     "@playwright/test": "^1.49.0",
     "@tailwindcss/postcss": "^4.2.2",
+    "@tanstack/react-query-devtools": "^5.80.7",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
@@ -55,8 +58,6 @@
     "postcss": "^8.5.8",
     "tailwindcss": "^4.2.2",
     "ts-jest": "^29.4.6",
-    "typescript": "^5",
-    "@axe-core/playwright": "^4.10.1",
-    "@playwright/test": "^1.49.0"
+    "typescript": "^5"
   }
 }

frontend/src/app/layout.tsx

@@ -5,6 +5,7 @@ import "./globals.css";
 import { ThemeProvider } from "@/components/theme-provider";
 import { Toaster } from "@/components/ui/toaster";
 import { inter, ibmPlexMono } from "@/lib/fonts";
+import { QueryProvider } from "@/lib/query";
 
 export const viewport: Viewport = {
   width: "device-width",
@@ -81,11 +82,13 @@ export default async function RootLayout({ children }: { children: React.ReactNo
       </head>
       <body className="font-sans antialiased">
         <ThemeProvider defaultTheme="system" storageKey="niffyinsur-theme">
-          <WalletProvider>
-            {children}
-            <NetworkMismatchModal />
-            <Toaster />
-          </WalletProvider>
+          <QueryProvider>
+            <WalletProvider>
+              {children}
+              <NetworkMismatchModal />
+              <Toaster />
+            </WalletProvider>
+          </QueryProvider>
         </ThemeProvider>
       </body>
     </html>

frontend/src/lib/query/QueryProvider.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useState } from 'react';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+import { createQueryClient } from './queryClientConfig';
+
+interface QueryProviderProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Wraps the app with a QueryClientProvider using the centralized config.
+ * The QueryClient is created once per component mount (useState initializer)
+ * so it is stable across re-renders but not shared across requests in SSR.
+ *
+ * DevTools are included only in development builds (tree-shaken in production).
+ */
+export function QueryProvider({ children }: QueryProviderProps) {
+  const [queryClient] = useState(() => createQueryClient());
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      {process.env.NODE_ENV === 'development' && (
+        <ReactQueryDevtools initialIsOpen={false} />
+      )}
+    </QueryClientProvider>
+  );
+}

frontend/src/lib/query/__tests__/queryClientConfig.test.ts

@@ -0,0 +1,81 @@
+/// <reference types="jest" />
+import { createQueryClient, STALE_TIMES } from '../queryClientConfig';
+
+describe('createQueryClient', () => {
+  it('returns a QueryClient instance', () => {
+    const client = createQueryClient();
+    expect(client).toBeDefined();
+    expect(typeof client.getQueryCache).toBe('function');
+  });
+
+  it('default staleTime matches STALE_TIMES.default', () => {
+    const client = createQueryClient();
+    const defaults = client.getDefaultOptions();
+    expect(defaults.queries?.staleTime).toBe(STALE_TIMES.default);
+  });
+
+  it('does not retry on 4xx errors (except 429)', () => {
+    const client = createQueryClient();
+    const retry = client.getDefaultOptions().queries?.retry;
+    if (typeof retry !== 'function') throw new Error('retry should be a function');
+
+    const err400 = { status: 400 };
+    const err401 = { status: 401 };
+    const err404 = { status: 404 };
+    const err429 = { status: 429 };
+    const err500 = { status: 500 };
+    const networkErr = new Error('Failed to fetch');
+
+    expect(retry(0, err400)).toBe(false);
+    expect(retry(0, err401)).toBe(false);
+    expect(retry(0, err404)).toBe(false);
+    // 429 is retryable
+    expect(retry(0, err429)).toBe(true);
+    // 5xx is retryable up to 3 attempts
+    expect(retry(0, err500)).toBe(true);
+    expect(retry(2, err500)).toBe(true);
+    expect(retry(3, err500)).toBe(false);
+    // Network errors are retryable
+    expect(retry(0, networkErr)).toBe(true);
+  });
+
+  it('retryDelay uses exponential backoff capped at 30s', () => {
+    const client = createQueryClient();
+    const retryDelay = client.getDefaultOptions().queries?.retryDelay;
+    if (typeof retryDelay !== 'function') throw new Error('retryDelay should be a function');
+
+    expect(retryDelay(0, new Error())).toBe(1_000);
+    expect(retryDelay(1, new Error())).toBe(2_000);
+    expect(retryDelay(2, new Error())).toBe(4_000);
+    // Capped at 30s
+    expect(retryDelay(10, new Error())).toBe(30_000);
+  });
+
+  it('refetchOnWindowFocus is false by default', () => {
+    const client = createQueryClient();
+    expect(client.getDefaultOptions().queries?.refetchOnWindowFocus).toBe(false);
+  });
+
+  it('refetchOnReconnect is true', () => {
+    const client = createQueryClient();
+    expect(client.getDefaultOptions().queries?.refetchOnReconnect).toBe(true);
+  });
+
+  it('refetchIntervalInBackground is false', () => {
+    const client = createQueryClient();
+    expect(client.getDefaultOptions().queries?.refetchIntervalInBackground).toBe(false);
+  });
+});
+
+describe('STALE_TIMES', () => {
+  it('votes stale time is shortest (most time-sensitive)', () => {
+    expect(STALE_TIMES.votes).toBeLessThan(STALE_TIMES.claims);
+    expect(STALE_TIMES.claims).toBeLessThan(STALE_TIMES.policies);
+  });
+
+  it('all values are positive numbers', () => {
+    Object.values(STALE_TIMES).forEach((v) => {
+      expect(v).toBeGreaterThan(0);
+    });
+  });
+});

frontend/src/lib/query/index.ts

@@ -0,0 +1,3 @@
+export { createQueryClient, STALE_TIMES } from './queryClientConfig';
+export { QueryProvider } from './QueryProvider';
+export { useNetworkAwareQuery } from './useNetworkAwareQuery';

frontend/src/lib/query/queryClientConfig.ts

@@ -0,0 +1,104 @@
+/**
+ * Centralized React Query configuration for NiffyInsur.
+ *
+ * Rationale
+ * ---------
+ * Default React Query settings (staleTime: 0, retry: 3 with fixed backoff)
+ * are poorly suited to a blockchain-backed app where:
+ *   - On-chain data changes infrequently (new ledger every ~5 s, indexer lags ~15 s).
+ *   - RPC/indexer errors are transient — aggressive retries waste bandwidth.
+ *   - 4xx errors (bad request, unauthorized) are never transient and must not retry.
+ *   - Background refetch on a hidden tab drains mobile battery.
+ *
+ * Stale times (per query type)
+ * ----------------------------
+ *   policies   30 s  — policy state changes only on user action (renew/terminate)
+ *   claims     10 s  — claims can be filed by any holder; moderate freshness needed
+ *   votes       5 s  — active voting windows are time-sensitive
+ *   ledger      5 s  — latest ledger advances every ~5 s
+ *   default    15 s  — catch-all for uncategorized queries
+ *
+ * Retry policy
+ * ------------
+ *   - Max 3 attempts for transient errors (network, 5xx, 429).
+ *   - No retry for 4xx client errors (except 429 Retry-After).
+ *   - Exponential backoff: 1 s → 2 s → 4 s (capped at 30 s).
+ *
+ * Background refetch
+ * ------------------
+ *   - refetchOnWindowFocus: false globally; enabled per-query only for votes.
+ *   - refetchOnReconnect: true — always resync after coming back online.
+ *   - refetchIntervalInBackground: false — respects Page Visibility API.
+ */
+
+import { QueryClient } from '@tanstack/react-query';
+
+// ---------------------------------------------------------------------------
+// Stale time constants — import these in useQuery calls for consistency.
+// ---------------------------------------------------------------------------
+
+export const STALE_TIMES = {
+  /** Policy list / detail — changes only on user-initiated transactions. */
+  policies: 30_000,
+  /** Claims list — any holder can file; moderate freshness. */
+  claims: 10_000,
+  /** Vote tallies — time-sensitive during open voting windows. */
+  votes: 5_000,
+  /** Latest ledger sequence — advances every ~5 s. */
+  ledger: 5_000,
+  /** Default catch-all. */
+  default: 15_000,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Retry predicate — never retry 4xx (except 429).
+// ---------------------------------------------------------------------------
+
+interface MaybeHttpError {
+  status?: number;
+}
+
+function isNonRetryable(error: unknown): boolean {
+  const status = (error as MaybeHttpError)?.status;
+  if (typeof status !== 'number') return false;
+  // 4xx except 429 (rate limit) are client errors — retrying won't help.
+  return status >= 400 && status < 500 && status !== 429;
+}
+
+function retryDelay(attempt: number): number {
+  // Exponential backoff: 1s, 2s, 4s — capped at 30s.
+  return Math.min(1_000 * Math.pow(2, attempt), 30_000);
+}
+
+// ---------------------------------------------------------------------------
+// QueryClient factory — call once at app root.
+// ---------------------------------------------------------------------------
+
+export function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: STALE_TIMES.default,
+        // 3 retries for transient errors; skip for 4xx.
+        retry: (failureCount: number, error: unknown) => {
+          if (isNonRetryable(error)) return false;
+          return failureCount < 3;
+        },
+        retryDelay: (attempt: number) => retryDelay(attempt),
+        // Disable window-focus refetch globally; enable per-query for votes.
+        refetchOnWindowFocus: false,
+        // Always resync after reconnect.
+        refetchOnReconnect: true,
+        // Never refetch in a background tab — respects Page Visibility API.
+        refetchIntervalInBackground: false,
+      },
+      mutations: {
+        retry: (failureCount: number, error: unknown) => {
+          if (isNonRetryable(error)) return false;
+          return failureCount < 2;
+        },
+        retryDelay: (attempt: number) => retryDelay(attempt),
+      },
+    },
+  });
+}