refactor(referral): enhance claim qualification logic and error handling

[sundayonah]

Description

Fixes referral payout rules so rewards align with product spec: a referrer should not be paid until the referred user qualifies, and the referrer must also meet their own requirements.

Problem: tryClaimOne treated referrer and referee as fully independent — each party only needed their own KYC (Tier 1) and qualifying transaction volume. A referrer could receive $1 USDC even when their referee had not verified phone or completed enough volume.

Solution: Introduced checkPartyQualification() to centralize KYC + volume checks per wallet. Updated tryClaimOne to apply different rules by role:

Claimant	Requirements to receive reward
Referee (invitee)	Own Tier 1 KYC + ≥ min volume (NEXT_PUBLIC_REFERRAL_MIN_QUALIFYING_VOLUME_USD, default $20) since the referral code was applied
Referrer	Own Tier 1 KYC + ≥ min volume and referee Tier 1 KYC + ≥ min volume (same volume window from referrals.created_at)

Error messages distinguish claimant vs referee failures (e.g. "Your referee must verify their phone number..." vs "You must verify your phone number...").

Impacts:

• Server-only change in app/api/referral/claim/route.ts (GET auto-claim + POST manual claim)
• No API contract changes — same endpoints and response shapes; failed claims still return KYC_REQUIRED / VOLUME_NOT_MET
• Referrers who previously auto-claimed before their referee qualified will no longer be paid until both parties meet requirements
• Payout mechanics unchanged: $1 USDC on Base per completed referral_claims row

Alternatives considered:

• Referee-only gate (referrer needs no own KYC/volume) — rejected per product requirement that referrer must also qualify
• Independent qualification (original behavior) — rejected; allowed premature referrer payouts

References

N/A — internal referral program behavior fix.

Testing

Manual (staging or local with Supabase + rewards wallet configured):

1. Referee only qualifies — B applies A’s code, B completes phone KYC + $20+ volume, A has not → B receives $1 on referral hub load; A stays pending.
2. Referrer only qualifies — A has KYC + volume, B has not → neither receives payout; A sees referee-specific skip/errors on auto-claim.
3. Both qualify — A and B each meet KYC + volume → both receive $1 USDC; total_earned updates in referral hub.
4. Idempotency — reopen referral hub after successful claim → no duplicate payouts (referral_claims per wallet).

No unit tests added — claim logic is server-side with Supabase + on-chain dependencies; covered by manual QA above.

• This change adds test coverage for new/changed/fixed functionality

Checklist

• I have added documentation and tests for new/changed functionality in this PR
• All active GitHub checks for tests, formatting, and security are passing
• The correct base branch is being used, if not main

By submitting a PR, I agree to Paycrest's Contributor Code of Conduct and Contribution Guide.

Summary by CodeRabbit

• New Features

  • Referral claims can be initiated by either the referrer or the referred party.
  • Eligibility now enforces KYC and transaction-volume checks with clearer, subject-specific failure messages.
  • Multi-currency referral volumes are converted and validated (reducing silent failures).

• Bug Fixes

  • Fixed referral modal eligibility flow to wait for full referral-status checks before marking as checked.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d352666b-f167-4f36-b641-b9af611bf224

📥 Commits

Reviewing files that changed from the base of the PR and between 40e9ce9 and 7a270ff.

📒 Files selected for processing (2)

• app/api/referral/claim/route.ts
• app/components/MainPageContent.tsx

---

📝 Walkthrough

Walkthrough

Extracts KYC and volume checks into a reusable helper with structured QualificationResult, adds conditional cNGN→USD conversion, updates tryClaimOne to allow referrer-or-referee callers and role-dependent checks, and tweaks client gating state for referral modal eligibility.

Changes

Referral Claim Qualification Refactor

Layer / File(s)	Summary
Type contracts and KYC validation app/api/referral/claim/route.ts	Introduces QualificationResult and QualificationSubject, USD-stable and cNGN symbols, and implements KYC tier lookup that returns KYC_CHECK_FAILED or subject-specific KYC_REQUIRED.
Volume qualification with currency normalization app/api/referral/claim/route.ts	Normalizes USDC/USDT as 1:1 USD, detects cNGN, fetches NGN→USD rate from external aggregator with timeout, converts cNGN to USD, and fails with VERIFICATION_ERROR on fetch/parse or VOLUME_NOT_MET when below threshold.
Authorization and tryClaimOne orchestration app/api/referral/claim/route.ts	Allows claim attempts only by referrer or referred wallet, requires both parties' qualification when caller is referrer (otherwise only claimant), runs checkPartyQualification per subject, and returns the first standardized ClaimResult failure.
Client gating and handler docs app/api/referral/claim/route.ts, app/components/MainPageContent.tsx	GET handler comments updated to reflect KYC/volume behavior; client-side checkReferralStatus now sets isReferralDataChecked to false on early-return when prerequisites are missing.

Sequence Diagram

sequenceDiagram
  participant Caller
  participant tryClaimOne
  participant checkPartyQualification
  participant Supabase as Supabase(KYC)
  participant Aggregator as ExternalAggregator

  Caller->>tryClaimOne: POST claim (wallet)
  tryClaimOne->>tryClaimOne: verify caller equals referrer or referred
  alt Caller is Referrer
    tryClaimOne->>checkPartyQualification: check referrer (KYC + volume)
    checkPartyQualification->>Supabase: fetch tier
    Supabase-->>checkPartyQualification: tier response
    alt cNGN present
      checkPartyQualification->>Aggregator: fetch NGN→USD rate (with timeout)
      Aggregator-->>checkPartyQualification: rate or error
    end
    checkPartyQualification-->>tryClaimOne: qualification result
    tryClaimOne->>checkPartyQualification: check referee (KYC + volume)
    checkPartyQualification->>Supabase: fetch tier
    Supabase-->>checkPartyQualification: tier response
    checkPartyQualification-->>tryClaimOne: qualification result
  else Caller is Referee
    tryClaimOne->>checkPartyQualification: check referee (KYC + volume)
    checkPartyQualification->>Supabase: fetch tier
    Supabase-->>checkPartyQualification: tier response
    alt cNGN present
      checkPartyQualification->>Aggregator: fetch NGN→USD rate (with timeout)
      Aggregator-->>checkPartyQualification: rate or error
    end
    checkPartyQualification-->>tryClaimOne: qualification result
  end

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly Related PRs

• paycrest/noblocks#520: Overlaps in replacing fetchKYCStatus with direct Supabase user_kyc_profiles tier lookup that this PR also refactors into checkPartyQualification.

Suggested Reviewers

• onahprosper
• 5ran6
• chibie

Poem

🐰 I hopped through code with a careful squeak,
Split KYC and volume, made checks less bleak,
cNGN converted, roles checked with grace,
Two wallets may claim — each finds its place. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: refactoring referral claim qualification logic with enhanced error handling, which aligns with the primary focus of the PR.
Description check	✅ Passed	The description comprehensively covers the problem, solution with detailed requirements table, impacts, alternatives, and manual testing scenarios. All template sections are well-populated.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

app/api/referral/claim/route.ts (1)

97-106: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Don’t turn FX lookup failures into false VOLUME_NOT_MET rejections.

Line 104 swallows every cNGN rate lookup failure, and Lines 114-127 then treat that qualifying volume as 0. That makes eligible users fail qualification whenever the aggregator is down, misconfigured, or slow. Please return a transient verification error here instead, and add a timeout so the claim request is not blocked indefinitely by the rate service.

Suggested fix

   let ngnPerUsd: number | null = null;
   if (hasCngn) {
     try {
       const rateUrl = `${process.env.NEXT_PUBLIC_AGGREGATOR_URL}/rates/USDC/1/NGN`;
-      const rateRes = await fetch(rateUrl);
+      const rateRes = await fetch(rateUrl, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!rateRes.ok) {
+        throw new Error(`rate lookup failed with status ${rateRes.status}`);
+      }
       const rateJson = (await rateRes.json()) as { data?: string };
       const parsed = Number(rateJson?.data);
-      if (parsed > 0) ngnPerUsd = parsed;
+      if (parsed > 0) {
+        ngnPerUsd = parsed;
+      } else {
+        throw new Error("invalid NGN rate payload");
+      }
     } catch {
-      // If rate fetch fails, cNGN txs will be skipped (counted as 0).
+      return {
+        ok: false,
+        code: "VERIFICATION_ERROR",
+        message: "Unable to verify qualifying transaction volume. Please try again later.",
+      };
     }
   }

Also applies to: 114-128

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/api/referral/claim/route.ts` around lines 97 - 106, The FX lookup
currently swallows all errors in the hasCngn block
(rateUrl/rateRes/rateJson/parsed setting ngnPerUsd) which causes downstream
qualification to treat cNGN volume as 0 and trigger VOLUME_NOT_MET; change this
to use a fetch with a bounded timeout (AbortController or equivalent) and if the
rate fetch fails or times out, surface a transient verification error instead of
silently setting ngnPerUsd to 0 — i.e., return or throw a transient error
response from the claim route so the request can be retried, and only fall back
to zero if you explicitly decide that is safe after a successful, non-timed-out
fetch. Ensure you update the hasCngn/ngnPerUsd logic and any code paths that
compare volumes against VOLUME_NOT_MET to rely on the explicit transient error
path rather than a default zero.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/api/referral/claim/route.ts`:
- Around line 162-178: Move the completed-claim lookup/short-circuit so it runs
before building/executing the qualificationChecks block: check whether the claim
is already completed (the existing "completed" lookup/short-circuit) before
creating qualificationChecks and before the loop that awaits each check (the for
(const check of qualificationChecks) { const qualification = await check; ...
}). Only run checkPartyQualification for referrer/referred wallets (controlled
by isReferrerClaim, referrerWallet, referredWallet, referralCreatedAt) when the
claim is new or pending; if the claim is completed return immediately and do not
perform KYC/volume revalidation.

---

Outside diff comments:
In `@app/api/referral/claim/route.ts`:
- Around line 97-106: The FX lookup currently swallows all errors in the hasCngn
block (rateUrl/rateRes/rateJson/parsed setting ngnPerUsd) which causes
downstream qualification to treat cNGN volume as 0 and trigger VOLUME_NOT_MET;
change this to use a fetch with a bounded timeout (AbortController or
equivalent) and if the rate fetch fails or times out, surface a transient
verification error instead of silently setting ngnPerUsd to 0 — i.e., return or
throw a transient error response from the claim route so the request can be
retried, and only fall back to zero if you explicitly decide that is safe after
a successful, non-timed-out fetch. Ensure you update the hasCngn/ngnPerUsd logic
and any code paths that compare volumes against VOLUME_NOT_MET to rely on the
explicit transient error path rather than a default zero.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c9dc40d2-e303-4029-9bf8-9bc5e27f3a2d

📥 Commits

Reviewing files that changed from the base of the PR and between a19aaa3 and 40e9ce9.

📒 Files selected for processing (1)

• app/api/referral/claim/route.ts

[Dprof-in-tech]

@sundayonah please review coderabbit

[Dprof-in-tech]

@sundayonah please review coderabbit

not neccessary anymore.