feat(frontend): harden banks API and instrument status telemetry (#1288)

## Summary

- validate `/api/banks` query parameters with Zod and return a machine-readable `INVALID_REQUEST` error on invalid input
- apply the shared rate limiter to `/api/banks`, with unit coverage for quota rejection
- emit consent-aware structured telemetry for Paystack payment status and browser connectivity transitions
- add `make ci` to run the frontend and contract CI matrix locally

## Rationale

Contributors previously had to reconstruct checks from several workflow files. `make ci` provides one local entry point covering the same validation categories: frontend typecheck, lint, build, coverage, E2E, and contract test/build/clippy.

## Testing

- `git diff --check` ✅
- Added banks API and status telemetry unit tests
- `pnpm typecheck`, `pnpm lint`, and `pnpm test:unit` could not be executed locally because dependency installation exceeded the environment time limit before completion.


Closes #1276 
Closes #1265
Closes #1206
Closes #1205

Author: Anthony-19

Dechat/dex_with_fiat_frontend/src/app/api/banks/route.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { NextRequest } from 'next/server';
+
+vi.mock('@/lib/telemetry', () => ({
+  telemetry: {
+    extractTraceFromHeaders: () => ({ traceId: 'trace', spanId: 'parent' }),
+    createSpan: () => ({ spanId: 'span' }),
+    addLog: vi.fn(),
+    finishSpan: vi.fn(),
+    setTraceHeaders: vi.fn(),
+  },
+}));
+
+const { GET } = await import('./route');
+
+function request(query = '', ip = '198.51.100.100') {
+  return new NextRequest(`http://localhost/api/banks${query}`, {
+    headers: { 'x-forwarded-for': ip },
+  });
+}
+
+describe('GET /api/banks', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a machine-readable 400 response for unsupported query parameters', async () => {
+    const response = await GET(request('?country=ghana'));
+
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toMatchObject({
+      success: false,
+      error: { code: 'INVALID_REQUEST' },
+    });
+  });
+
+  it('rejects requests after the shared rate-limit quota is exhausted', async () => {
+    const ip = '198.51.100.101';
+
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+      expect((await GET(request('', ip))).status).toBe(200);
+    }
+
+    const response = await GET(request('', ip));
+    expect(response.status).toBe(429);
+    await expect(response.json()).resolves.toMatchObject({ success: false });
+    expect(response.headers.get('Retry-After')).toBe('60');
+  });
+});

Dechat/dex_with_fiat_frontend/src/app/api/banks/route.ts

@@ -1,11 +1,17 @@
-import { NextResponse } from 'next/server';
+import { NextRequest, NextResponse } from 'next/server';
 import axios from 'axios';
 import { telemetry } from '@/lib/telemetry';
 import { env } from '@/lib/env';
+import { banksQuerySchema } from '@/lib/apiSchemas';
+import { applyRateLimit, getClientIp } from '@/lib/rateLimit';
 
 const PAYSTACK_SECRET_KEY = env.PAYSTACK_SECRET_KEY;
+const RATE_LIMIT = { maxRequests: 30, windowMs: 60_000 };
+
+export async function GET(request: NextRequest) {
+  const limited = applyRateLimit(getClientIp(request), '/api/banks', RATE_LIMIT);
+  if (limited) return limited;
 
-export async function GET(request: Request) {
   const traceContext = telemetry.extractTraceFromHeaders(
     request.headers as Headers,
   );
@@ -20,6 +26,30 @@ export async function GET(request: Request) {
       endpoint: '/api/banks',
     });
 
+    const query = Object.fromEntries(request.nextUrl.searchParams.entries());
+    const validationResult = banksQuerySchema.safeParse(query);
+    if (!validationResult.success) {
+      telemetry.addLog(span.spanId, 'warn', 'Banks query validation failed', {
+        errors: validationResult.error.issues,
+      });
+      telemetry.finishSpan(span.spanId, { success: false, error: 'Invalid request' });
+
+      const response = NextResponse.json(
+        {
+          success: false,
+          error: {
+            code: 'INVALID_REQUEST',
+            issues: validationResult.error.issues,
+          },
+        },
+        { status: 400 },
+      );
+      telemetry.setTraceHeaders(response.headers as Headers, traceContext);
+      return response;
+    }
+
+    const { country } = validationResult.data;
+
     if (!PAYSTACK_SECRET_KEY) {
       telemetry.addLog(
         span.spanId,
@@ -104,11 +134,11 @@ export async function GET(request: Request) {
     // Call real Paystack API to get Nigerian banks
     telemetry.addLog(span.spanId, 'info', 'Calling Paystack API', {
       endpoint: 'https://api.paystack.co/bank',
-      country: 'nigeria',
+      country,
     });
 
     const response = await axios.get(
-      'https://api.paystack.co/bank?country=nigeria',
+      `https://api.paystack.co/bank?country=${country}`,
       {
         headers: {
           Authorization: `Bearer ${PAYSTACK_SECRET_KEY}`,

Dechat/dex_with_fiat_frontend/src/components/OfflineStatusBanner.test.tsx

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { act, render, screen } from '@testing-library/react';
+import { act } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import OfflineStatusBanner from './OfflineStatusBanner';
 import { useOnlineStatus } from '@/hooks/useOnlineStatus';
 import { subscribeToQueuedMessageCount } from '@/lib/offlineMessageQueue';

Dechat/dex_with_fiat_frontend/src/components/OfflineStatusBanner.tsx

@@ -33,7 +33,9 @@ export default function OfflineStatusBanner() {
   // The queue count is owned by `offlineMessageQueue` and published by
   // `useChat` as sends are queued and drained; this component only mirrors it.
   useEffect(() => {
-    return subscribeToQueuedMessageCount(setOptimisticPendingCount);
+    return subscribeToQueuedMessageCount((count) => {
+      setOptimisticPendingCount(count);
+    });
   }, []);
 
   useEffect(() => {

Dechat/dex_with_fiat_frontend/src/hooks/useOnlineStatus.ts

@@ -1,6 +1,7 @@
 'use client';
 
 import { useEffect, useState, useCallback } from 'react';
+import { chatTelemetry } from '@/lib/chatTelemetry';
 
 /**
  * Verify actual internet connectivity by pinging a reliable endpoint.
@@ -40,11 +41,19 @@ export function useOnlineStatus() {
     // Set initial state
     if (typeof window !== 'undefined') {
       setIsOnline(window.navigator.onLine);
+      chatTelemetry.networkStatus({
+        status: window.navigator.onLine ? 'online' : 'offline',
+        source: 'initial',
+      });
     }
 
     const handleOnline = async () => {
       const hasConnectivity = await verifyConnectivity();
       setIsOnline(hasConnectivity);
+      chatTelemetry.networkStatus({
+        status: hasConnectivity ? 'online' : 'offline',
+        source: 'connectivity-check',
+      });
       if (hasConnectivity) {
         setWasOffline(true);
       }
@@ -53,6 +62,7 @@ export function useOnlineStatus() {
     const handleOffline = () => {
       setIsOnline(false);
       setWasOffline(true);
+      chatTelemetry.networkStatus({ status: 'offline', source: 'browser-event' });
     };
 
     if (typeof window !== 'undefined') {

Dechat/dex_with_fiat_frontend/src/hooks/usePaystackWebhookStatus.ts

@@ -3,6 +3,7 @@
 import { useEffect } from 'react';
 import { useToast } from '@/hooks/useToast';
 import { getOrCreateClientSessionId } from '@/lib/clientSession';
+import { chatTelemetry } from '@/lib/chatTelemetry';
 
 interface PaymentStatusStreamEvent {
   reference: string;
@@ -33,6 +34,12 @@ export function usePaystackWebhookStatus() {
     eventSource.onmessage = (event) => {
       try {
         const payload = JSON.parse(event.data) as PaymentStatusStreamEvent;
+        chatTelemetry.paymentStatus({
+          status: payload.status,
+          reference: payload.reference,
+          hasAmount: typeof payload.amount === 'number',
+          hasFailureReason: Boolean(payload.failureReason),
+        });
         if (payload.status === 'success') {
           addToast({
             message: 'Payment confirmed!',

Dechat/dex_with_fiat_frontend/src/hooks/useStatusTelemetry.test.tsx

@@ -0,0 +1,97 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { setTelemetryConsent, type ChatEvent } from '@/lib/chatTelemetry';
+import { ThemeProvider } from '@/contexts/ThemeContext';
+import { useOnlineStatus } from './useOnlineStatus';
+
+vi.mock('@/hooks/useToast', () => ({ useToast: () => ({ addToast: vi.fn() }) }));
+vi.mock('@/lib/clientSession', () => ({
+  getOrCreateClientSessionId: () => 'session-1',
+}));
+
+class MockEventSource {
+  static latest: MockEventSource | undefined;
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onerror: (() => void) | null = null;
+  close = vi.fn();
+
+  constructor(url: string) {
+    void url;
+    MockEventSource.latest = this;
+  }
+}
+
+function captureEvent(): Promise<ChatEvent> {
+  return new Promise((resolve) => {
+    window.addEventListener(
+      'chat:telemetry',
+      (event) => resolve((event as CustomEvent<ChatEvent>).detail),
+      { once: true },
+    );
+  });
+}
+
+describe('status telemetry hooks', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    setTelemetryConsent(true);
+    vi.stubGlobal('EventSource', MockEventSource);
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    });
+  });
+
+  it('emits a structured payment-status event without exposing payment values', async () => {
+    const { usePaystackWebhookStatus } = await import('./usePaystackWebhookStatus');
+    renderHook(() => usePaystackWebhookStatus());
+    const eventPromise = captureEvent();
+
+    act(() => {
+      MockEventSource.latest?.onmessage?.({
+        data: JSON.stringify({ reference: 'payment-ref', status: 'success', amount: 1200 }),
+      } as MessageEvent);
+    });
+
+    await expect(eventPromise).resolves.toMatchObject({
+      name: 'payment_status',
+      payload: {
+        reference: 'payment-ref',
+        status: 'success',
+        hasAmount: true,
+        hasFailureReason: false,
+      },
+    });
+  });
+
+  it('emits the online state in both light and dark theme documents', async () => {
+    Object.defineProperty(window.navigator, 'onLine', { configurable: true, value: false });
+
+    for (const theme of ['light', 'dark']) {
+      localStorage.setItem('theme', theme);
+      const eventPromise = captureEvent();
+      const { unmount } = renderHook(() => useOnlineStatus(), {
+        wrapper: ThemeProvider,
+      });
+
+      await expect(eventPromise).resolves.toMatchObject({
+        name: 'network_status',
+        payload: { status: 'offline', source: 'initial' },
+      });
+      unmount();
+    }
+  });
+
+  it('emits an offline browser-event transition', async () => {
+    const { result } = renderHook(() => useOnlineStatus());
+    await waitFor(() => expect(result.current.isOnline).toBeDefined());
+    const eventPromise = captureEvent();
+
+    act(() => window.dispatchEvent(new Event('offline')));
+
+    await expect(eventPromise).resolves.toMatchObject({
+      name: 'network_status',
+      payload: { status: 'offline', source: 'browser-event' },
+    });
+  });
+});

Dechat/dex_with_fiat_frontend/src/lib/apiSchemas.ts

@@ -30,6 +30,17 @@ export const verifyAccountSchema = z.object({
 
 export type VerifyAccountInput = z.infer<typeof verifyAccountSchema>;
 
+// Schema for the banks endpoint query string. The endpoint currently serves
+// Nigerian NUBAN banks only, so rejecting unsupported query parameters keeps
+// the public contract explicit rather than silently ignoring user input.
+export const banksQuerySchema = z
+  .object({
+    country: z.literal('nigeria').default('nigeria'),
+  })
+  .strict();
+
+export type BanksQuery = z.infer<typeof banksQuerySchema>;
+
 /**
  * Error thrown by {@link fetchWithRetry} when the server answers with a
  * non-OK status.
@@ -65,6 +76,11 @@ export interface RetryConfig {
   retryableErrors?: (error: unknown) => boolean;
 }
 
+interface HttpError extends Error {
+  status?: number;
+  response?: Response;
+}
+
 /**
  * Default retry configuration
  */
@@ -158,8 +174,12 @@ export async function withRetry<T>(
       // Check if error is retryable
       const isRetryableError = mergedConfig.retryableErrors(error);
       const isRetryableStatus =
-        (error instanceof HttpResponseError || error instanceof Response) &&
-        mergedConfig.retryableStatusCodes.includes(error.status);
+        error instanceof Response
+          ? mergedConfig.retryableStatusCodes.includes(error.status)
+          : error instanceof Error &&
+              mergedConfig.retryableStatusCodes.includes(
+                (error as HttpError).status ?? 0,
+              );
 
       if (!isRetryableError && !isRetryableStatus) {
         throw error; // Non-retryable error, throw immediately
@@ -193,7 +213,11 @@ export async function fetchWithRetry(
 
     if (!response.ok) {
       // Throw error to trigger retry for non-OK responses
-      throw new HttpResponseError(response);
+      const error: HttpError = Object.assign(
+        new Error(`HTTP ${response.status}: ${response.statusText}`),
+        { status: response.status, response },
+      );
+      throw error;
     }
 
     return response;

Dechat/dex_with_fiat_frontend/src/lib/chatTelemetry.ts

@@ -13,7 +13,9 @@ export type ChatEventName =
   | 'bridge_open'
   | 'tx_confirm'
   | 'fiat_payout_step'
-  | 'avatar_color_check';
+  | 'avatar_color_check'
+  | 'payment_status'
+  | 'network_status';
 
 export interface ChatEvent<P extends object = Record<string, unknown>> {
   /** Normalized event name. */
@@ -80,6 +82,18 @@ export interface AvatarColorTelemetryPayload {
   avatarTextColor?: string;
 }
 
+export interface PaymentStatusTelemetryPayload {
+  status: 'success' | 'failed' | 'reversed' | 'pending' | 'cancelled';
+  reference: string;
+  hasAmount: boolean;
+  hasFailureReason: boolean;
+}
+
+export interface NetworkStatusTelemetryPayload {
+  status: 'online' | 'offline';
+  source: 'initial' | 'browser-event' | 'connectivity-check';
+}
+
 export interface AccessibleAvatarColorTelemetryPayload
   extends AvatarColorTelemetryPayload {
   avatarTextColor: string;
@@ -450,6 +464,14 @@ export const chatTelemetry = {
     emit('fiat_payout_step', payload);
   },
 
+  paymentStatus(payload: PaymentStatusTelemetryPayload): void {
+    emit('payment_status', payload);
+  },
+
+  networkStatus(payload: NetworkStatusTelemetryPayload): void {
+    emit('network_status', payload);
+  },
+
   /**
    * Emit an `avatar_color_check` event that records whether the avatar
    * foreground/background colour pair meets WCAG AA contrast (4.5:1).