fix: referral page wasn't working

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

knowledge.md

@@ -253,6 +253,30 @@ Important constants are centralized in `common/src/constants.ts`:
 - `CREDITS_REFERRAL_BONUS`: Credits awarded for successful referral
 - Credit limits for different user types
 
+## Referral System
+
+**IMPORTANT**: Referral codes must be applied through the npm-app CLI, not through the web interface.
+
+- Web onboarding flow shows instructions for entering codes in CLI
+- Users must type their referral code in the Codebuff terminal after login
+- Auto-redemption during web login was removed to prevent abuse
+- The `handleReferralCode` function in `npm-app/src/client.ts` handles CLI redemption
+- The `redeemReferralCode` function in `web/src/app/api/referrals/helpers.ts` processes the actual credit granting
+
+### OAuth Referral Code Preservation
+
+**Problem**: NextAuth doesn't preserve referral codes through OAuth flow because:
+
+- NextAuth generates its own state parameter for CSRF/PKCE protection
+- Custom state parameters are ignored/overwritten
+- OAuth callback URLs don't always survive the round trip
+
+**Solution**: Multi-layer approach implemented in SignInButton and ReferralRedirect components:
+
+1. **Primary**: Use absolute callback URLs with referral codes for better NextAuth preservation
+2. **Fallback**: Store referral codes in localStorage before OAuth starts
+3. **Recovery**: ReferralRedirect component on home page catches missed referrals and redirects to onboard page
+
 ## Environment Variables
 
 This project uses [Infisical](https://infisical.com/) for secret management. All secrets are injected at runtime.
@@ -270,6 +294,7 @@ The `.bin/bun` script automatically wraps bun commands with infisical when secre
 **Worktree Support**: The wrapper automatically detects and loads `.env.worktree` files when present, allowing worktrees to override Infisical environment variables (like ports) for local development. This enables multiple worktrees to run simultaneously on different ports without conflicts.
 
 The wrapper also loads environment variables in the correct precedence order:
+
 1. Infisical secrets are loaded first (if needed)
 2. `.env.worktree` is loaded second to override any conflicting variables
 3. This ensures worktree-specific overrides (like custom ports) always take precedence over cached Infisical defaults

web/public/logos/terminal.svg

@@ -141,14 +141,26 @@ export const authOptions: NextAuthOptions = {
       return session
     },
     async redirect({ url, baseUrl }) {
+      console.log('🟡 NextAuth redirect callback:', { url, baseUrl })
+
       const potentialRedirectUrl = new URL(url, baseUrl)
       const authCode = potentialRedirectUrl.searchParams.get('auth_code')
+      let referralCode = potentialRedirectUrl.searchParams.get('referral_code')
+
+      console.log('🟡 NextAuth redirect parsed params:', {
+        authCode: !!authCode,
+        referralCode,
+        allParams: Object.fromEntries(
+          potentialRedirectUrl.searchParams.entries()
+        ),
+      })
 
       if (authCode) {
         const onboardUrl = new URL(`${baseUrl}/onboard`)
         potentialRedirectUrl.searchParams.forEach((value, key) => {
           onboardUrl.searchParams.set(key, value)
         })
+        console.log('🟡 NextAuth CLI flow redirect to:', onboardUrl.toString())
         logger.info(
           { url, authCode, redirectTarget: onboardUrl.toString() },
           'Redirecting CLI flow to /onboard'
@@ -157,13 +169,21 @@ export const authOptions: NextAuthOptions = {
       }
 
       if (url.startsWith('/') || potentialRedirectUrl.origin === baseUrl) {
+        console.log(
+          '🟡 NextAuth web flow redirect to:',
+          potentialRedirectUrl.toString()
+        )
         logger.info(
           { url, redirectTarget: potentialRedirectUrl.toString() },
           'Redirecting web flow to callbackUrl'
         )
         return potentialRedirectUrl.toString()
       }
 
+      console.log(
+        '🟡 NextAuth external/invalid URL, redirect to baseUrl:',
+        baseUrl
+      )
       logger.info(
         { url, baseUrl, redirectTarget: baseUrl },
         'Callback URL is external or invalid, redirecting to baseUrl'

web/src/app/api/auth/[...nextauth]/auth-options.ts

@@ -14,7 +14,7 @@ import { authOptions } from '../api/auth/[...nextauth]/auth-options'
 import { redeemReferralCode } from '../api/referrals/helpers'
 
 import CardWithBeams from '@/components/card-with-beams'
-import { toast } from '@/components/ui/use-toast'
+import { OnboardClientWrapper } from '@/components/onboard/onboard-client-wrapper'
 
 interface PageProps {
   searchParams?: {
@@ -29,16 +29,56 @@ const Onboard = async ({ searchParams = {} }: PageProps) => {
   const session = await getServerSession(authOptions)
   const user = session?.user
 
-  // Check if values are present
-  if (!authCode || !user) {
-    toast({
-      title: 'Uh-oh, spaghettio!',
-      description:
-        'No valid session or auth code. Please try again and reach out to support@codebuff.com if the problem persists.',
-    })
+  console.log('🟢 Onboard Server: Page loaded with params', {
+    authCode: !!authCode,
+    referralCode,
+    hasUser: !!user,
+    userId: user?.id,
+  })
+
+  // Handle referral-only flow (no CLI auth required)
+  if (!user) {
+    console.log('🟢 Onboard Server: No user session, redirecting to app URL')
     return redirect(env.NEXT_PUBLIC_CODEBUFF_APP_URL)
   }
 
+  // Handle all non-CLI flows (web users with or without referral codes)
+  if (!authCode) {
+    const hasReferralInUrl = !!referralCode
+    console.log('🟢 Onboard Server: Non-CLI flow detected', {
+      hasReferralInUrl,
+      referralCode,
+    })
+    const successCard = CardWithBeams({
+      title: 'Welcome to Codebuff!',
+      description: hasReferralInUrl
+        ? "Once you've installed Codebuff, you can close this window."
+        : 'You can close this window.',
+      content: (
+        <div className="flex flex-col space-y-2">
+          <Image
+            src="/auth-success.png"
+            alt="Successful authentication"
+            width={600}
+            height={600}
+          />
+          {hasReferralInUrl && (
+            <p className="text-center text-muted-foreground">
+              Don't forget to enter your referral code in the CLI to claim your
+              bonus credits!
+            </p>
+          )}
+        </div>
+      ),
+    })
+
+    return (
+      <OnboardClientWrapper hasReferralCode={hasReferralInUrl}>
+        {successCard}
+      </OnboardClientWrapper>
+    )
+  }
+
   const [fingerprintId, expiresAt, receivedfingerprintHash] =
     authCode.split('.')
 
@@ -166,41 +206,25 @@ const Onboard = async ({ searchParams = {} }: PageProps) => {
     return !!session.length
   })
 
-  let redeemReferralMessage = <></>
+  // No longer auto-redeem referral codes - users must enter them in CLI
+  let referralMessage = <></>
   if (referralCode) {
-    try {
-      const redeemReferralResp = await redeemReferralCode(referralCode, user.id)
-      const respJson = await redeemReferralResp.json()
-      if (!redeemReferralResp.ok) {
-        throw new Error(respJson.error)
-      }
-      redeemReferralMessage = (
-        <p>
-          You just earned an extra {respJson.credits_redeemed} credits from your
-          referral code!
-        </p>
-      )
-    } catch (e) {
-      console.error(e)
-      const error = e as Error
-      redeemReferralMessage = (
-        <div className="flex flex-col space-y-2">
-          <p>Uh-oh, we couldn't apply your referral code. {error.message}</p>
-          <p>
-            Please try again and reach out to {env.NEXT_PUBLIC_SUPPORT_EMAIL} if
-            the problem persists.
-          </p>
-        </div>
-      )
-    }
+    referralMessage = (
+      <p className="text-center text-muted-foreground">
+        Don't forget to enter your referral code in the CLI to claim your bonus
+        credits!
+      </p>
+    )
   }
 
-  // Render the result
+  // Render the result for CLI flow
   if (didInsert) {
-    return CardWithBeams({
+    const isReferralUser = !!referralCode
+    const successCard = CardWithBeams({
       title: 'Nicely done!',
-      description:
-        'Feel free to close this window and head back to your terminal.',
+      description: isReferralUser
+        ? 'Follow the steps above to install Codebuff, then you can close this window.'
+        : 'Feel free to close this window and head back to your terminal.',
       content: (
         <div className="flex flex-col space-y-2">
           <Image
@@ -209,10 +233,16 @@ const Onboard = async ({ searchParams = {} }: PageProps) => {
             width={600}
             height={600}
           />
-          {redeemReferralMessage}
+          {referralMessage}
         </div>
       ),
     })
+
+    return (
+      <OnboardClientWrapper hasReferralCode={isReferralUser}>
+        {successCard}
+      </OnboardClientWrapper>
+    )
   }
   return CardWithBeams({
     title: 'Uh-oh, spaghettio!',

web/src/app/onboard/page.tsx

@@ -24,6 +24,7 @@ import { toast } from '@/components/ui/use-toast'
 import { useIsMobile } from '@/hooks/use-mobile'
 import { storeSearchParams } from '@/lib/trackConversions'
 import { cn } from '@/lib/utils'
+import { ReferralRedirect } from '@/components/referral-redirect'
 
 function SearchParamsHandler() {
   const searchParams = useSearchParams()
@@ -97,6 +98,7 @@ export default function Home() {
       <Suspense>
         <SearchParamsHandler />
       </Suspense>
+      <ReferralRedirect />
 
       <Section background={SECTION_THEMES.hero.background} hero fullViewport>
         <div