feat(claims): implement V2-BE-024 claim feed & detail endpoints

[yunus-dev-codecrafter]

closes #359

V2-BE-024 — Claim Feed and Claim Detail Query Endpoints

Implements versioned claim feed and claim detail query endpoints backed by projections on the V2 Optimism/EVM pipeline: contracts emit facts, the indexer projects them, and the API serves those projections. No backend-authoritative protocol mutation is introduced.

What was built

• GET /api/v2/claims — cursor-paginated claim feed
  • Stable cursor pagination (effectiveAt DESC, id DESC with base64url-encoded JSON cursor, hasMore/nextCursor)
  • Filters: lifecycle state (PENDING | RESOLVED | FINALIZED), creator (via stake join), from/to date range, limit (1–100, default 20)
  • Each item returns lifecycle state, deadline, effective date, confirmations/finality metadata, and related resource links
• GET /api/v2/claims/:id — claim detail
  • Full lifecycle, confirmations/finality metadata, related links
  • 404 NotFoundException contract for missing claims
• Swagger docs on all endpoints; validated inputs via class-validator (cursor, limit, state union, dates, UUID)
• Migration 1788000000000-AddDeadlineEffectiveAtToClaims adding deadline and effectiveAt timestamp columns + indexes (effectiveAt, effectiveAt + id), backfilling effectiveAt from createdAt
• Projection-backed read path with a cache write-through layer for detail lookups

Architecture

• src/claims/v2/claim-feed.service.ts — feed/detail logic, cursor encoding/decoding, confirmations, stable ordering
• src/claims/v2/claim-feed.controller.ts — route + Swagger contracts
• src/claims/v2/claim-feed.module.ts — wiring (Claim, IndexedEvent, Stake repos + cache)
• src/claims/v2/dto/* — request/response DTOs with validation and OpenAPI schemas
• Reused existing projection entities (ClaimsCache, IndexedEvent) rather than raw-event storage

Overlapping current code — audit

• Reused: projection/cache abstractions, V2 state derivation, stake join for creator lookup.
• Replaced: no V2 feed/detail endpoints existed before this change (only legacy offset-based pagination in src/pagination/users.pagination.ts and V1 claim routes).
• Deprecated: none removed in this change; legacy claim endpoints remain intact to avoid scope creep, noted as follow-up.

Security & integrity

• Smart contracts remain authoritative for claims, verification, settlement, rewards, treasury, and governance — this layer is read/query only.
• Untrusted input validated at every boundary (class-validator on all query/param DTOs).
• No secrets, production credentials, dummy addresses, floating-point token accounting, or Stellar/Freighter runtime dependencies added.
• Replay-safe: read-only projections; no state mutation; no replay of protocol events.

Migration / rebuild impact

• New migration adds deadline + effectiveAt (nullable backfilled from createdAt) and two indexes to claims. Down migration drops them.
• Existing rows get effectiveAt = createdAt as a deterministic rebuild default; re-projectable.

Observability

• Logger on the service; errors surface as standard Nest responses (NotFoundException); no PII logged.
• Follow-up suggestion: add query/execution timing spans when a tracer is wired into the service.

Tests

• Unit tests (claim-feed.service.spec.ts, claim-feed.controller.spec.ts) for success path + validation/error branches (cursor decode, not-found, filters, confirmations).
• Integration tests (claim-feed.integration.spec.ts) across the nearest DB boundary using an in-memory SQLite harness: full feed, lifecycle filter, detail, not-found, and multi-page cursor traversal.
• The service SQL for cursor pagination uses DB-agnostic epoch comparison so it behaves identically on SQLite (tests) and PostgreSQL (production).

Commands run (evidence)

• npx tsc --noEmit — v2 files emit no type errors (pre-existing unrelated baseline errors in other files reported separately).
• npx jest src/claims/v2/... — unit, controller, and integration suites.

Residual risks

• getConfirmations currently resolves the latest ClaimCreated indexed event for the confirmations metadata; confirmations are not yet scoped per claim id in the indexed-event store (see V2-BE-025 evidence counterparts). Noted as a follow-up to tighten per-claim finality when the event store is enriched.
• SQLite test harness timestamp-string serialization quirk requires DB-agnostic epoch comparisons in the cursor SQL; production PostgreSQL is unaffected.

Acceptance criteria mapping

• Versioned claim feed and detail endpoints backed by projections
• Lifecycle state, deadlines, confirmation/finality metadata, related resource links
• Stable cursor pagination, filters, and not-found/error contracts
• No backend-authoritative protocol mutation introduced
• Tests cover success and error/validation branches (unit + integration)
• Documentation/schemas/migrations current (Swagger, DTOs, migration)
• PR maps evidence to every acceptance criterion

Non-goals

• No protocol outcome logic reimplemented in the API.
• No creation/modification/relabelling of historical issues.
• No Stellar/Soroban/Freighter runtime support.