Merge pull request #256 from darcszn/feat/claim-status-notifications

feat: claim status notifications with permission UX, polling backoff, and SSE

Author: jhayniffy

backend/src/claims/claims.controller.ts

@@ -10,6 +10,8 @@ import {
   HttpCode,
   HttpStatus,
   Body,
+  Res,
+  BadRequestException,
 } from '@nestjs/common';
 import {
   ApiTags,
@@ -19,6 +21,7 @@ import {
   ApiQuery,
 } from '@nestjs/swagger';
 import { Throttle } from '@nestjs/throttler';
+import type { Response } from 'express';
 import { ClaimsService } from './claims.service';
 import { ClaimsListResponseDto, ClaimDetailResponseDto } from './dto/claim.dto';
 import { BuildClaimTransactionDto } from './dto/build-claim-transaction.dto';
@@ -28,6 +31,9 @@ import { WalletAddress } from '../auth/decorators/wallet-address.decorator';
 import { RateLimitGuard } from '../rate-limit/rate-limit.guard';
 import { MAX_LIMIT, DEFAULT_LIMIT } from '../helpers/pagination';
 
+/** Maximum claim IDs accepted per status-poll or SSE subscription. */
+const MAX_WATCH_IDS = 50;
+
 @ApiTags('claims')
 @Controller('claims')
 export class ClaimsController {
@@ -122,4 +128,65 @@ export class ClaimsController {
   async submitTransaction(@Body() dto: SubmitTransactionDto) {
     return this.claimsService.submitTransaction(dto.transactionXdr);
   }
-}
+
+  // ── Claim status polling (for watched claims) ────────────────────────────
+
+  /**
+   * GET /api/claims/status?claimId=1&claimId=2
+   * Returns the current status for up to MAX_WATCH_IDS claim IDs.
+   * Used by the frontend polling loop (useClaimWatcher).
+   * Latency: indexer lag + cache TTL, typically < 30 s on Mainnet.
+   */
+  @Get('status')
+  @Throttle({ default: { limit: 30, ttl: 60_000 } })
+  @ApiOperation({ summary: 'Poll current status for a set of watched claim IDs' })
+  @ApiQuery({ name: 'claimId', required: true, isArray: true, type: String })
+  @ApiResponse({ status: 200, description: 'Array of { claimId, status, updatedAt }' })
+  async getClaimStatuses(
+    @Query('claimId') claimId: string | string[],
+  ): Promise<{ claimId: string; status: string; updatedAt: string }[]> {
+    const ids = (Array.isArray(claimId) ? claimId : [claimId]).slice(0, MAX_WATCH_IDS);
+    if (ids.length === 0) throw new BadRequestException('At least one claimId is required.');
+    return this.claimsService.getClaimStatuses(ids);
+  }
+
+  // ── SSE stream for claim status changes ──────────────────────────────────
+
+  /**
+   * GET /api/claims/status/stream?claimId=1&claimId=2
+   * Server-Sent Events stream that pushes status-change events for watched claims.
+   * Falls back gracefully — clients use polling if SSE is unavailable.
+   * Max latency: indexer lag + push delay, typically < 15 s on Mainnet.
+   */
+  @Get('status/stream')
+  @Throttle({ default: { limit: 5, ttl: 60_000 } })
+  @ApiOperation({ summary: 'SSE stream for watched claim status changes' })
+  @ApiQuery({ name: 'claimId', required: true, isArray: true, type: String })
+  @ApiResponse({ status: 200, description: 'text/event-stream' })
+  streamClaimStatuses(
+    @Query('claimId') claimId: string | string[],
+    @Res() res: Response,
+  ): void {
+    const ids = (Array.isArray(claimId) ? claimId : [claimId]).slice(0, MAX_WATCH_IDS);
+
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no'); // disable nginx buffering
+    res.flushHeaders();
+
+    const send = (data: object) => {
+      res.write(`data: ${JSON.stringify(data)}\n\n`);
+    };
+
+    // Send a heartbeat every 25 s to keep the connection alive through proxies.
+    const heartbeat = setInterval(() => res.write(': heartbeat\n\n'), 25_000);
+
+    // Subscribe to status changes for the requested claim IDs.
+    const unsubscribe = this.claimsService.subscribeToStatusChanges(ids, send);
+
+    res.on('close', () => {
+      clearInterval(heartbeat);
+      unsubscribe();
+    });
+  }

backend/src/claims/claims.service.ts

@@ -323,4 +323,74 @@ export class ClaimsService {
 
     return result;
   }
+
+  // ── Claim status polling & SSE ───────────────────────────────────────────
+
+  /**
+   * Returns the current status for a set of claim IDs.
+   * Used by the frontend polling loop (GET /api/claims/status).
+   */
+  async getClaimStatuses(
+    claimIds: string[],
+  ): Promise<{ claimId: string; status: string; updatedAt: string }[]> {
+    const numericIds = claimIds.map(Number).filter((n) => !isNaN(n));
+    if (numericIds.length === 0) return [];
+
+    const claims = await this.prisma.claim.findMany({
+      where: { id: { in: numericIds } },
+      select: { id: true, status: true, updatedAt: true },
+    });
+
+    return claims.map((c) => ({
+      claimId: String(c.id),
+      status: c.status.toLowerCase(),
+      updatedAt: c.updatedAt.toISOString(),
+    }));
+  }
+
+  /**
+   * Subscribes a SSE client to status changes for the given claim IDs.
+   * Returns an unsubscribe function to call when the client disconnects.
+   *
+   * Implementation: lightweight in-process pub/sub via a Map of listeners.
+   * In a multi-instance deployment, replace with a Redis pub/sub channel.
+   */
+  subscribeToStatusChanges(
+    claimIds: string[],
+    send: (data: object) => void,
+  ): () => void {
+    const idSet = new Set(claimIds);
+
+    const listener = (update: { claimId: string; status: string; updatedAt: string }) => {
+      if (idSet.has(update.claimId)) {
+        send(update);
+      }
+    };
+
+    ClaimsService.statusListeners.add(listener);
+    return () => ClaimsService.statusListeners.delete(listener);
+  }
+
+  /**
+   * Publishes a status-change event to all active SSE subscribers.
+   * Call this from the indexer or queue consumer whenever a claim status changes.
+   */
+  static publishStatusChange(update: {
+    claimId: string;
+    status: string;
+    updatedAt: string;
+  }): void {
+    for (const listener of ClaimsService.statusListeners) {
+      try {
+        listener(update);
+      } catch {
+        // Ignore errors from individual listeners (e.g. closed connections).
+      }
+    }
+  }
+
+  // In-process listener registry. Replace with Redis pub/sub for multi-instance.
+  private static readonly statusListeners = new Set<
+    (update: { claimId: string; status: string; updatedAt: string }) => void
+  >();
 }

docs/claim-notification-latency.md

@@ -0,0 +1,65 @@
+# Claim Status Notification Latency
+
+## Overview
+
+This document describes the expected end-to-end latency between an on-chain
+claim status change and a user receiving a browser notification or in-app toast.
+
+---
+
+## Latency Budget (Mainnet)
+
+| Stage | Typical | Worst-case |
+|---|---|---|
+| Ledger close (Stellar Mainnet) | ~5 s | ~10 s |
+| Indexer ingestion lag | 1–3 ledgers (~5–15 s) | ~30 s during re-index |
+| Backend cache TTL (`CACHE_TTL_SECONDS`) | 0–60 s | 60 s |
+| Frontend polling interval (base) | 15 s | 60 s (after 2 failures) |
+| **Total (polling path)** | **~35 s** | **~150 s** |
+| SSE push delay (when SSE is active) | < 1 s after indexer ingestion | ~30 s |
+| **Total (SSE path)** | **~20 s** | **~60 s** |
+
+> **Agreed maximum latency (SLO):** status changes surface within **2 minutes**
+> under normal operating conditions on Mainnet.
+
+---
+
+## Polling vs SSE
+
+- The frontend attempts an SSE connection to `GET /api/claims/status/stream`
+  first (`useRealtimeTallies` for tallies; `useClaimWatcher` for status).
+- If SSE is unavailable or errors, the client falls back to polling
+  `GET /api/claims/status` with exponential backoff (base 15 s, cap 60 s).
+- Polling is **paused** when `document.visibilityState === "hidden"` (Page
+  Visibility API) to reduce battery drain on mobile browsers.
+- Polling resumes immediately when the tab becomes visible again.
+
+---
+
+## Battery Impact
+
+- Base polling interval is 15 s (vs 5 s for tally updates) to reduce wake-ups.
+- Backoff caps at 60 s after consecutive failures — no tight retry loops.
+- Tab-hidden pause eliminates background polling entirely on mobile.
+- SSE keeps a single persistent connection instead of repeated HTTP requests;
+  a 25 s heartbeat comment keeps it alive through proxies without extra data.
+
+---
+
+## Indexer Lag
+
+The backend indexer may lag behind the chain by 1–3 ledgers (~5–15 s) under
+normal conditions. During re-indexing or RPC downtime this can extend to ~30 s.
+The `ConsistencyMetadataDto.isStale` flag is set when `indexerLag > 5 ledgers`.
+
+For trust-critical views (e.g. claim detail page), use chain reads via Soroban
+simulation which always reflect the current ledger state.
+
+---
+
+## Multi-instance Deployment Note
+
+The current SSE implementation uses an in-process listener registry
+(`ClaimsService.statusListeners`). In a multi-instance deployment, replace this
+with a Redis pub/sub channel so all instances can push to all connected clients.
+See `backend/src/claims/claims.service.ts` — `subscribeToStatusChanges`.

frontend/src/components/claims/ClaimsBoard.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 // Feature: claims-board
-// Requirements: 1.1, 1.2, 1.3, 1.4, 4.1, 4.3, 6.1, 6.5, 9.2
+// Requirements: 1.1, 1.2, 1.3, 1.4, 4.1, 4.3, 6.1, 6.5, 9.2, 10.x
 
 import React, { useState, useCallback, useRef, useEffect } from "react";
 
@@ -86,6 +86,22 @@ export function ClaimsBoard() {
   // ── Notifications (Req 10.1, 10.2, 10.3) ─────────────────────────────────
   useNotifications(localClaims, filters);
 
+  // ── Claim status change notifications ────────────────────────────────────
+  const [notifEnabled, setNotifEnabled] = useState(false);
+  // Read from localStorage after mount (avoids SSR mismatch).
+  useEffect(() => {
+    setNotifEnabled(getClaimNotificationsEnabled());
+  }, []);
+
+  const { notify } = useClaimStatusNotifications(notifEnabled);
+
+  // Watch all currently visible claim IDs for status changes.
+  useClaimWatcher({
+    claimIds: claimIds,
+    onStatusChange: notify,
+    enabled: notifEnabled,
+  });
+
   // ── Real-time tally updates (Req 6.1, 6.5) ────────────────────────────────
   const claimIds = localClaims.map((c) => c.claim_id);
 
@@ -118,6 +134,19 @@ export function ClaimsBoard() {
   // ── Render ────────────────────────────────────────────────────────────────
   return (
     <div className="flex flex-col gap-4">
+      {/* Notification permission banner — shown once, never nagged */}
+      <NotificationPermissionBanner
+        onDismiss={() => setNotifEnabled(getClaimNotificationsEnabled())}
+      />
+
+      {/* Settings toggle (inline; move to a settings page as needed) */}
+      <ClaimNotificationsToggle
+        enabled={notifEnabled}
+        onChange={(v) => {
+          setClaimNotificationsEnabled(v);
+          setNotifEnabled(v);
+        }}
+      />
       {/* Re-auth prompt (Req 4.3) */}
       {showReauthPrompt && (
         <div