feat(badges): consume declarative acquisition platform

src/app/(mobile-ui)/add-money/__tests__/add-money-states.test.tsx

@@ -997,6 +997,27 @@ describe('GROUP 1: Landing / Method Selection', () => {
         expect(screen.getByText('Add Money')).toBeInTheDocument()
     })
 
+    test('an earned Offramp badge keeps its migration entry regardless of provenance', () => {
+        mockUseAuth.mockReturnValue({
+            user: {
+                user: {
+                    username: 'test-user',
+                    userId: 'user-123',
+                    badges: [{ code: 'OFFRAMP_USER' }],
+                },
+            },
+            isFetchingUser: false,
+            fetchUser: jest.fn(),
+        })
+
+        renderWithProviders(<AddMoneyPage />)
+
+        fireEvent.click(screen.getByTestId('action-card-migrate-from-offramp'))
+        expect(mockRouterPush).toHaveBeenCalledWith('/add-money/crypto?network=EVM&source=offramp')
+        expect(screen.getByText('Crypto')).toBeInTheDocument()
+        expect(screen.getByText('Bank Transfer')).toBeInTheDocument()
+    })
+
     test('clicking Crypto opens the network drawer', () => {
         renderWithProviders(<AddMoneyPage />)
 

src/app/(mobile-ui)/card/page.tsx

@@ -626,6 +626,7 @@ const CardPage: FC = () => {
                 const allBadges =
                     user?.user?.badges?.map((b) => ({
                         code: b.code,
+                        iconUrl: b.iconUrl,
                         earnedAt: b.earnedAt,
                     })) ?? cardInfo!.skipBadges.map((code) => ({ code }))
                 return (

src/app/(setup)/setup/page.tsx

@@ -90,16 +90,15 @@ function SetupPageContent() {
 
             // Skip the invite-code gate straight to signup when either:
             //  - an invite code is present (cookie survives the PWA-install hop), or
-            //  - the URL asks for it via ?step=signup — the signal every campaign /
-            //    skip flow already sends (ShhhhhLandingPage, InvitesPage.handleClaim)
-            //    when it pushes to /setup. useZeroDev still reads the campaignTag
-            //    cookie post-signup to award the badge; the step decision no longer
-            //    trusts that cookie.
+            //  - the URL asks for it via ?step=signup — the signal every campaign
+            //    entrypoint sends when it pushes to /setup. After authentication,
+            //    useZeroDev submits the queued opaque campaign list to the canonical
+            //    claim service; the step decision never interprets that cookie.
             //
-            // Why not the campaignTag cookie: it's a session cookie cleared only on a
-            // successful signup, so a returning user who claimed a campaign earlier in
-            // the same session was routed past Landing (the only screen with Log In)
-            // onto Signup, unable to log back in (regression from PR #2346).
+            // Why not the campaignTag cookie: retryable campaign acquisition can
+            // intentionally persist for 30 days. Using it as onboarding state would
+            // route a returning user past Landing (the only screen with Log In) onto
+            // Signup, unable to log back in (regression from PR #2346).
             const inviteCodeFromCookie = getFromCookie('inviteCode')
             const userInviteCode = inviteCode || inviteCodeFromCookie
             const skipInviteGate = !!userInviteCode || searchParams.get('step') === 'signup'

src/app/actions/__tests__/invites-resolution.test.ts

@@ -0,0 +1,89 @@
+import { validateInviteCode } from '../invites'
+import { serverFetch } from '@/utils/api-fetch'
+
+jest.mock('@/utils/api-fetch', () => ({ serverFetch: jest.fn() }))
+
+const mockServerFetch = serverFetch as jest.MockedFunction<typeof serverFetch>
+
+function response(status: number, body: unknown): Response {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: jest.fn().mockResolvedValue(body),
+    } as unknown as Response
+}
+
+describe('validateInviteCode mixed-version resolution', () => {
+    beforeEach(() => jest.clearAllMocks())
+
+    it('treats a typed campaign-only HTTP 409 as a settled transport result', async () => {
+        mockServerFetch.mockResolvedValue(
+            response(409, {
+                message: 'Campaign processed without invite attribution',
+                attributionResolved: false,
+                onboardingResolved: false,
+                username: '',
+                legacyAcquisition: {
+                    campaignTag: 'offramp',
+                    fallback: 'normal_app',
+                    destination: 'offramp_migration',
+                },
+            })
+        )
+
+        await expect(validateInviteCode('offramp')).resolves.toEqual({
+            data: {
+                success: true,
+                attributionResolved: false,
+                onboardingResolved: false,
+                username: '',
+                legacyAcquisition: {
+                    campaignTag: 'offramp',
+                    fallback: 'normal_app',
+                    destination: 'offramp_migration',
+                },
+            },
+        })
+    })
+
+    it('keeps an untyped HTTP 409 as a transport failure', async () => {
+        mockServerFetch.mockResolvedValue(response(409, { error: 'Invite code is not valid' }))
+
+        await expect(validateInviteCode('not-an-invite')).resolves.toEqual({
+            error: 'Invite code is not valid',
+        })
+    })
+
+    it('supports a pre-discriminator HTTP 200 validation response with a username', async () => {
+        mockServerFetch.mockResolvedValue(response(200, { username: 'legacy-inviter' }))
+
+        await expect(validateInviteCode('legacy-invite')).resolves.toEqual({
+            data: {
+                success: true,
+                attributionResolved: true,
+                onboardingResolved: true,
+                username: 'legacy-inviter',
+                legacyAcquisition: undefined,
+            },
+        })
+    })
+
+    it('lets an explicit false discriminator override the legacy username signal', async () => {
+        mockServerFetch.mockResolvedValue(
+            response(200, {
+                username: 'legacy-inviter',
+                attributionResolved: false,
+                onboardingResolved: false,
+            })
+        )
+
+        await expect(validateInviteCode('legacy-invite')).resolves.toMatchObject({
+            data: {
+                success: true,
+                attributionResolved: false,
+                onboardingResolved: false,
+                username: 'legacy-inviter',
+            },
+        })
+    })
+})

src/app/actions/invites.ts

@@ -1,22 +1,47 @@
 import { serverFetch } from '@/utils/api-fetch'
+import { parseLegacyInviteAcquisition, type LegacyInviteAcquisition } from '@/services/invite-acquisition'
+import { isTypedCampaignOnlyInviteResponse, resolveInviteResolutionFlags } from '@/services/invite-response'
 
-export async function validateInviteCode(
-    inviteCode: string
-): Promise<{ data?: { success: boolean; username: string }; error?: string }> {
+export async function validateInviteCode(inviteCode: string): Promise<{
+    data?: {
+        success: boolean
+        attributionResolved: boolean
+        onboardingResolved: boolean
+        username: string
+        legacyAcquisition?: LegacyInviteAcquisition
+    }
+    error?: string
+}> {
     try {
         const response = await serverFetch('/invites/validate', {
             method: 'POST',
             body: JSON.stringify({ inviteCode }),
         })
 
-        if (!response.ok) {
-            const data = await response.json()
-            return { error: data.error || 'Failed to validate invite code.' }
+        const data: unknown = await response.json()
+        const typedCampaignOnly = response.status === 409 && isTypedCampaignOnlyInviteResponse(data)
+
+        if (!response.ok && !typedCampaignOnly) {
+            const error =
+                data && typeof data === 'object' && typeof (data as { error?: unknown }).error === 'string'
+                    ? (data as { error: string }).error
+                    : 'Failed to validate invite code.'
+            return { error }
         }
 
-        const data = await response.json()
+        const body = data && typeof data === 'object' ? (data as Record<string, unknown>) : {}
+        const username = typeof body.username === 'string' ? body.username : ''
+        const resolution = resolveInviteResolutionFlags(data, username.trim().length > 0)
+        const legacyAcquisition = parseLegacyInviteAcquisition(body.legacyAcquisition)
 
-        return { data: { success: true, username: data.username } }
+        return {
+            data: {
+                success: true,
+                ...resolution,
+                username,
+                legacyAcquisition,
+            },
+        }
     } catch (error) {
         console.error('Error calling validate invite code API:', error)
         if (error instanceof Error) {

src/app/invite/page.tsx

@@ -12,7 +12,7 @@ async function getInviteCodeData(inviteCode: string) {
 
     const response = await validateInviteCode(inviteCode)
 
-    if (response.data?.success) {
+    if (response.data?.success && response.data.onboardingResolved) {
         return {
             username: response.data.username,
         }

src/app/shhhhh/ShhhhhLandingPage.tsx

@@ -12,17 +12,18 @@ import { PixelatedCardFace } from '@/components/Card/share-asset/PixelatedCardFa
 import { inflateWaitlistPosition } from '@/components/Card/doorTally.utils'
 import { Sparkle, Star } from '@/assets/illustrations'
 import { cardApi } from '@/services/card'
-import { invitesApi } from '@/services/invites'
-import { saveToCookie } from '@/utils/general.utils'
 import { ANALYTICS_EVENTS } from '@/constants/analytics.consts'
+import { badgeCampaignsFromSearchParams, queuePendingBadgeCampaigns } from '@/components/Invites/badge-campaign-context'
+import { claimAndSettlePendingBadgeCampaigns, isConfirmedBadgeCampaignClaim } from '@/services/badge-campaigns'
+import { captureException } from '@sentry/nextjs'
+import {
+    destinationForShhhhhClaims,
+    queueShhhhhCampaignContinuation,
+    shhhhhCampaignSignupRoute,
+} from './shhhhh-acquisition'
 
 const marqueeMessages = ['IYKYK', 'WORD TRAVELS', 'CLOSED BETA', 'SHHHH', 'PEANUT CLUB']
 
-// /shhhhh?campaign=skip — the Skip Pass link. Awards the WAITLIST_SKIP badge
-// (same contract as /invite?campaign=skip) so friends-of-Peanut skip the line.
-// A BARE visit grants nothing: the door joins the waitlist, it is not a bypass.
-const SKIP_CAMPAIGN = 'skip'
-
 // Inline "you're on the waitlist" confirmation shown in place of the door CTA
 // once the user joins (pre-launch, non-skip path). `dark` = on the black §7.
 function WaitlistJoined({
@@ -227,39 +228,48 @@ export default function ShhhhhLandingPage() {
     }, [user])
 
     const handleCTA = async () => {
-        // /shhhhh?campaign=skip → Skip Pass (awards the badge). A bare press is
-        // NOT a bypass — it joins the waitlist (Hugo 2026-06-07). Read the param
-        // at click time (client-only) — avoids useSearchParams (which would bail
-        // /shhhhh out of static prerendering) and any mount-effect race.
-        const isSkipCampaign =
-            new URLSearchParams(window.location.search).get('campaign')?.toLowerCase() === SKIP_CAMPAIGN
+        // Read opaque campaign identities at click time (client-only) to avoid
+        // bailing static prerendering. The backend resolves award semantics;
+        // provenance is audit-only and does not weaken an earned skip badge.
+        const badgeCampaigns = badgeCampaignsFromSearchParams(new URLSearchParams(window.location.search))
 
         posthog.capture(ANALYTICS_EVENTS.DOOR_TRY, {
             signed_in: !!user,
-            campaign: isSkipCampaign ? SKIP_CAMPAIGN : null,
+            campaign_tags: badgeCampaigns,
         })
 
-        // Skip Pass link → award the badge; the user is in. (The bare door never
-        // awards a badge — see below.)
-        if (isSkipCampaign) {
+        if (badgeCampaigns.length > 0) {
+            const queuedBadgeCampaigns = queuePendingBadgeCampaigns(badgeCampaigns, 30)
             if (!user) {
-                // useZeroDev's post-signup `campaignTag` branch awards the badge
-                // (awaited inside registration, before setup redirects) — so
-                // landing on /card afterwards is race-free.
-                saveToCookie('campaignTag', SKIP_CAMPAIGN)
-                router.push(`/setup?step=signup&redirect_uri=${encodeURIComponent('/card')}`)
+                queueShhhhhCampaignContinuation()
+                router.push(shhhhhCampaignSignupRoute())
                 return
             }
+
+            let destination: '/card' | '/home' = '/home'
             try {
-                await invitesApi.awardBadge(SKIP_CAMPAIGN)
-                posthog.capture(ANALYTICS_EVENTS.INVITE_ACCEPTED, { campaign_tag: SKIP_CAMPAIGN })
-                await fetchUser()
-            } catch (err) {
-                console.error('[shhhhh] awardBadge(skip) failed:', err)
+                const batch = await claimAndSettlePendingBadgeCampaigns(queuedBadgeCampaigns)
+                const confirmed = batch.claims.filter(isConfirmedBadgeCampaignClaim)
+                destination = destinationForShhhhhClaims(batch.claims)
+                if (confirmed.length > 0) {
+                    posthog.capture(ANALYTICS_EVENTS.INVITE_ACCEPTED, {
+                        campaign_tags: confirmed.map((claim) => claim.badgeCampaign),
+                    })
+                    await fetchUser()
+                }
+                if (batch.pending.length > 0) {
+                    captureException(new Error('shhhhh campaign claim retained for retry'), {
+                        tags: { error_type: 'campaign_claim_retryable' },
+                        extra: { pendingCampaigns: batch.pending, claims: batch.claims },
+                    })
+                }
+            } catch (error) {
+                captureException(error, { tags: { error_type: 'campaign_claim_unexpected_failure' } })
             }
-            // Straight into the card flow — the badge award just opened both
-            // gates BE-side; /home would make them hunt for the card CTA.
-            router.push('/card')
+
+            // Only a confirmed Skip Pass continues to the card flow. Unknown,
+            // inactive, expired, malformed, and retryable claims fall back home.
+            router.push(destination)
             return
         }
 

src/app/shhhhh/shhhhh-acquisition.test.ts

@@ -0,0 +1,68 @@
+import { getRedirectUrl } from '@/utils/general.utils'
+import {
+    destinationForShhhhhClaims,
+    queueShhhhhCampaignContinuation,
+    settleShhhhhCampaignContinuation,
+    shhhhhCampaignSignupRoute,
+} from './shhhhh-acquisition'
+
+describe('Shhhhh campaign continuation', () => {
+    beforeEach(() => localStorage.clear())
+
+    it.each(['awarded', 'already_owned'] as const)('continues a confirmed Skip Pass %s to /card', (outcome) => {
+        expect(destinationForShhhhhClaims([{ badgeCampaign: 'skip', badgeCode: 'WAITLIST_SKIP', outcome }])).toBe(
+            '/card'
+        )
+    })
+
+    it.each(['inactive', 'expired', 'unknown', 'definition_missing', 'retryable_error'] as const)(
+        'falls back home for %s',
+        (outcome) => {
+            expect(destinationForShhhhhClaims([{ badgeCampaign: 'skip', badgeCode: 'WAITLIST_SKIP', outcome }])).toBe(
+                '/home'
+            )
+        }
+    )
+
+    it('does not treat an unrelated confirmed badge as a card continuation', () => {
+        expect(
+            destinationForShhhhhClaims([{ badgeCampaign: 'event', badgeCode: 'EVENT_ALUMNI', outcome: 'awarded' }])
+        ).toBe('/home')
+    })
+
+    it('starts signed-out registration without an unconditional card redirect', () => {
+        expect(shhhhhCampaignSignupRoute()).toBe('/setup?step=signup')
+    })
+
+    it.each(['awarded', 'already_owned'] as const)(
+        'replaces the safe signed-out marker with /card after confirmed Skip Pass %s',
+        (outcome) => {
+            queueShhhhhCampaignContinuation()
+            expect(
+                settleShhhhhCampaignContinuation([{ badgeCampaign: 'skip', badgeCode: 'WAITLIST_SKIP', outcome }])
+            ).toBe('/card')
+            expect(getRedirectUrl()).toBe('/card')
+        }
+    )
+
+    it.each(['inactive', 'expired', 'unknown', 'definition_missing', 'retryable_error'] as const)(
+        'keeps the signed-out continuation on the normal app after %s',
+        (outcome) => {
+            queueShhhhhCampaignContinuation()
+            expect(
+                settleShhhhhCampaignContinuation([{ badgeCampaign: 'skip', badgeCode: 'WAITLIST_SKIP', outcome }])
+            ).toBe('/home')
+            expect(getRedirectUrl()).toBe('/home')
+        }
+    )
+
+    it("does not consume another acquisition flow's stored destination", () => {
+        localStorage.setItem('redirect', JSON.stringify('/claim?step=claim'))
+        expect(
+            settleShhhhhCampaignContinuation([
+                { badgeCampaign: 'skip', badgeCode: 'WAITLIST_SKIP', outcome: 'awarded' },
+            ])
+        ).toBeUndefined()
+        expect(getRedirectUrl()).toBe('/claim?step=claim')
+    })
+})