fix: normalize referral code casing and throw on API failures

- Fix case-sensitive ref- prefix check: REF-abc123 now properly
normalizes to ref-abc123 instead of ref-REF-abc123 - Extract
normalizeReferralCode utility function to router-utils.ts for cleaner,
reusable code - Throw error on non-OK API responses in fetchUserDetails
so React Query enters error state and ReferralBanner shows proper error
message - Add tests for mixed-case prefix normalization (REF-, Ref-,
rEf-) - Add comprehensive fetchUserDetails tests for API failure
handling (401, 403, 404, 500) - Add tests for successful responses and
environment validation

Author: brandonkachen

cli/src/__tests__/referral-mode.test.ts

@@ -218,14 +218,49 @@ describe('referral-mode', () => {
       expect(referralCode).toBe('ref-abc123')
     })
 
-    test('code with REF- (uppercase) does NOT get recognized', () => {
+    test('code with REF- (uppercase) gets normalized to lowercase prefix', () => {
       const userInput = 'REF-abc123'
-      const referralCode = userInput.startsWith('ref-')
-        ? userInput
+      const userInputLower = userInput.toLowerCase()
+      // Normalize: case-insensitive prefix check, strip and re-add lowercase prefix
+      const referralCode = userInputLower.startsWith('ref-')
+        ? `ref-${userInput.slice(4)}`
+        : `ref-${userInput}`
+
+      // Should strip REF- and re-add ref- to preserve the code portion
+      expect(referralCode).toBe('ref-abc123')
+    })
+
+    test('code with Ref- (mixed case) gets normalized to lowercase prefix', () => {
+      const userInput = 'Ref-XYZ789'
+      const userInputLower = userInput.toLowerCase()
+      const referralCode = userInputLower.startsWith('ref-')
+        ? `ref-${userInput.slice(4)}`
+        : `ref-${userInput}`
+
+      expect(referralCode).toBe('ref-XYZ789')
+    })
+
+    test('code with rEf- (random case) gets normalized to lowercase prefix', () => {
+      const userInput = 'rEf-Code123'
+      const userInputLower = userInput.toLowerCase()
+      const referralCode = userInputLower.startsWith('ref-')
+        ? `ref-${userInput.slice(4)}`
+        : `ref-${userInput}`
+
+      expect(referralCode).toBe('ref-Code123')
+    })
+
+    test('preserves code portion casing when normalizing prefix', () => {
+      // User typed "REF-ABC123" - should become "ref-ABC123", not "ref-abc123"
+      const userInput = 'REF-ABC123'
+      const userInputLower = userInput.toLowerCase()
+      const referralCode = userInputLower.startsWith('ref-')
+        ? `ref-${userInput.slice(4)}`
         : `ref-${userInput}`
 
-      // Should add another ref- prefix because startsWith is case-sensitive
-      expect(referralCode).toBe('ref-REF-abc123')
+      expect(referralCode).toBe('ref-ABC123')
+      // Code portion should preserve original casing
+      expect(referralCode.slice(4)).toBe('ABC123')
     })
   })
 

cli/src/commands/__tests__/router-input.test.ts

@@ -1,12 +1,12 @@
 import { describe, test, expect } from 'bun:test'
 
+import { findCommand, COMMAND_REGISTRY } from '../command-registry'
 import {
   normalizeInput,
   parseCommand,
   isSlashCommand,
   isReferralCode,
 } from '../router-utils'
-import { findCommand, COMMAND_REGISTRY } from '../command-registry'
 
 describe('router-utils', () => {
   describe('normalizeInput', () => {

cli/src/commands/command-registry.ts

@@ -1,13 +1,14 @@
 import { handleInitializationFlowLocally } from './init'
 import { handleReferralCode } from './referral'
+import { normalizeReferralCode } from './router-utils'
 import { handleUsageCommand } from './usage'
 import { useChatStore } from '../state/chat-store'
 import { useLoginStore } from '../state/login-store'
 import { getSystemMessage, getUserMessage } from '../utils/message-history'
 
-import type { ChatMessage } from '../types/chat'
 import type { MultilineInputHandle } from '../components/multiline-input'
 import type { InputValue } from '../state/chat-store'
+import type { ChatMessage } from '../types/chat'
 import type { SendMessageFn } from '../types/contracts/send-message'
 import type { User } from '../utils/auth'
 import type { AgentMode } from '../utils/constants'
@@ -81,10 +82,10 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
     aliases: ['redeem'],
     handler: async (params, args) => {
       const trimmedArgs = args.trim()
-      
+
       // If user provided a code directly, redeem it immediately
       if (trimmedArgs) {
-        const code = trimmedArgs.startsWith('ref-') ? trimmedArgs : `ref-${trimmedArgs}`
+        const code = normalizeReferralCode(trimmedArgs)
         try {
           const { postUserMessage } = await handleReferralCode(code)
           params.setMessages((prev) => [
@@ -93,7 +94,8 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
             ...postUserMessage([]),
           ])
         } catch (error) {
-          const errorMessage = error instanceof Error ? error.message : 'Unknown error'
+          const errorMessage =
+            error instanceof Error ? error.message : 'Unknown error'
           params.setMessages((prev) => [
             ...prev,
             getUserMessage(params.inputValue.trim()),
@@ -104,7 +106,7 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
         clearInput(params)
         return
       }
-      
+
       // Otherwise enter referral mode
       useChatStore.getState().setInputMode('referral')
       params.saveToHistory(params.inputValue.trim())
@@ -136,7 +138,10 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
       params.logoutMutation.mutate(undefined, {
         onSettled: () => {
           resetLoginState()
-          params.setMessages((prev) => [...prev, getSystemMessage('Logged out.')])
+          params.setMessages((prev) => [
+            ...prev,
+            getSystemMessage('Logged out.'),
+          ])
           clearInput(params)
           setTimeout(() => {
             params.setUser(null)
@@ -171,7 +176,7 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
     handler: async (params, args) => {
       const { postUserMessage } = handleInitializationFlowLocally()
       const trimmed = params.inputValue.trim()
-      
+
       params.saveToHistory(trimmed)
       clearInput(params)
 
@@ -187,7 +192,11 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
         return
       }
 
-      params.sendMessage({ content: trimmed, agentMode: params.agentMode, postUserMessage })
+      params.sendMessage({
+        content: trimmed,
+        agentMode: params.agentMode,
+        postUserMessage,
+      })
       setTimeout(() => {
         params.scrollToLatest()
       }, 0)

cli/src/commands/router-utils.ts

@@ -70,3 +70,23 @@ export function isReferralCode(input: string): boolean {
 export function extractReferralCode(input: string): string {
   return normalizeInput(input.trim())
 }
+
+const REFERRAL_PREFIX = 'ref-'
+
+/**
+ * Normalize a referral code by ensuring it has the lowercase 'ref-' prefix.
+ * Handles case-insensitive prefix detection (REF-, Ref-, etc.) and preserves
+ * the original casing of the code portion.
+ *
+ * @example
+ * normalizeReferralCode('abc123')      // => 'ref-abc123'
+ * normalizeReferralCode('ref-abc123')  // => 'ref-abc123'
+ * normalizeReferralCode('REF-ABC123')  // => 'ref-ABC123'
+ * normalizeReferralCode('Ref-XYZ')     // => 'ref-XYZ'
+ */
+export function normalizeReferralCode(code: string): string {
+  const trimmed = code.trim()
+  const hasPrefix = trimmed.toLowerCase().startsWith(REFERRAL_PREFIX)
+  const codeWithoutPrefix = hasPrefix ? trimmed.slice(REFERRAL_PREFIX.length) : trimmed
+  return `${REFERRAL_PREFIX}${codeWithoutPrefix}`
+}

cli/src/commands/router.ts

@@ -11,6 +11,7 @@ import {
   isSlashCommand,
   isReferralCode,
   extractReferralCode,
+  normalizeReferralCode,
 } from './router-utils'
 import { useChatStore } from '../state/chat-store'
 import { getSystemMessage, getUserMessage } from '../utils/message-history'
@@ -97,11 +98,13 @@ export async function routeUserPrompt(
 
   // Handle referral mode input
   if (inputMode === 'referral') {
-    // Validate and normalize the referral code
-    // Valid codes are alphanumeric with optional dashes, 3-50 chars
+    // Validate the referral code (3-50 alphanumeric chars with optional dashes)
     const codePattern = /^[a-zA-Z0-9-]{3,50}$/
-    const codeWithoutPrefix = trimmed.startsWith('ref-') ? trimmed.slice(4) : trimmed
-    
+    // Strip prefix if present for validation (case-insensitive)
+    const codeWithoutPrefix = trimmed.toLowerCase().startsWith('ref-')
+      ? trimmed.slice(4)
+      : trimmed
+
     if (!codePattern.test(codeWithoutPrefix)) {
       setMessages((prev) => [
         ...prev,
@@ -113,8 +116,8 @@ export async function routeUserPrompt(
       setInputMode('default')
       return
     }
-    
-    const referralCode = trimmed.startsWith('ref-') ? trimmed : `ref-${trimmed}`
+
+    const referralCode = normalizeReferralCode(trimmed)
     try {
       const { postUserMessage: referralPostMessage } =
         await handleReferralCode(referralCode)

cli/src/hooks/__tests__/use-user-details-query.test.ts

@@ -0,0 +1,184 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from 'bun:test'
+
+import { fetchUserDetails } from '../use-user-details-query'
+
+import type { Logger } from '@codebuff/common/types/contracts/logger'
+
+describe('fetchUserDetails', () => {
+  const mockLogger: Logger = {
+    error: mock(() => {}),
+    warn: mock(() => {}),
+    info: mock(() => {}),
+    debug: mock(() => {}),
+    trace: mock(() => {}),
+    fatal: mock(() => {}),
+    child: mock(() => mockLogger),
+  }
+
+  const originalEnv = process.env.NEXT_PUBLIC_CODEBUFF_APP_URL
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    process.env.NEXT_PUBLIC_CODEBUFF_APP_URL = 'https://test.codebuff.com'
+  })
+
+  afterEach(() => {
+    process.env.NEXT_PUBLIC_CODEBUFF_APP_URL = originalEnv
+    globalThis.fetch = originalFetch
+  })
+
+  describe('API failure handling', () => {
+    test('throws error on 401 Unauthorized response', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 401,
+        } as Response),
+      )
+
+      await expect(
+        fetchUserDetails({
+          authToken: 'invalid-token',
+          fields: ['referral_link'] as const,
+          logger: mockLogger,
+        }),
+      ).rejects.toThrow('Failed to fetch user details (HTTP 401)')
+    })
+
+    test('throws error on 500 Internal Server Error response', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 500,
+        } as Response),
+      )
+
+      await expect(
+        fetchUserDetails({
+          authToken: 'valid-token',
+          fields: ['referral_link'] as const,
+          logger: mockLogger,
+        }),
+      ).rejects.toThrow('Failed to fetch user details (HTTP 500)')
+    })
+
+    test('throws error on 403 Forbidden response', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 403,
+        } as Response),
+      )
+
+      await expect(
+        fetchUserDetails({
+          authToken: 'valid-token',
+          fields: ['referral_link'] as const,
+          logger: mockLogger,
+        }),
+      ).rejects.toThrow('Failed to fetch user details (HTTP 403)')
+    })
+
+    test('throws error on 404 Not Found response', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 404,
+        } as Response),
+      )
+
+      await expect(
+        fetchUserDetails({
+          authToken: 'valid-token',
+          fields: ['id', 'email'] as const,
+          logger: mockLogger,
+        }),
+      ).rejects.toThrow('Failed to fetch user details (HTTP 404)')
+    })
+
+    test('logs error before throwing on API failure', async () => {
+      const errorSpy = mock(() => {})
+      const testLogger: Logger = {
+        ...mockLogger,
+        error: errorSpy,
+      }
+
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 500,
+        } as Response),
+      )
+
+      await expect(
+        fetchUserDetails({
+          authToken: 'valid-token',
+          fields: ['referral_link'] as const,
+          logger: testLogger,
+        }),
+      ).rejects.toThrow()
+
+      expect(errorSpy).toHaveBeenCalled()
+    })
+  })
+
+  describe('successful responses', () => {
+    test('returns user details on successful response', async () => {
+      const mockUserDetails = {
+        referral_link: 'https://codebuff.com/r/abc123',
+      }
+
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          json: () => Promise.resolve(mockUserDetails),
+        } as Response),
+      )
+
+      const result = await fetchUserDetails({
+        authToken: 'valid-token',
+        fields: ['referral_link'] as const,
+        logger: mockLogger,
+      })
+
+      expect(result).toEqual(mockUserDetails)
+    })
+
+    test('returns null referral_link when not set', async () => {
+      const mockUserDetails = {
+        referral_link: null,
+      }
+
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          json: () => Promise.resolve(mockUserDetails),
+        } as Response),
+      )
+
+      const result = await fetchUserDetails({
+        authToken: 'valid-token',
+        fields: ['referral_link'] as const,
+        logger: mockLogger,
+      })
+
+      expect(result?.referral_link).toBe(null)
+    })
+  })
+
+  describe('environment validation', () => {
+    test('throws error when NEXT_PUBLIC_CODEBUFF_APP_URL is not set', async () => {
+      delete process.env.NEXT_PUBLIC_CODEBUFF_APP_URL
+
+      await expect(
+        fetchUserDetails({
+          authToken: 'valid-token',
+          fields: ['referral_link'] as const,
+          logger: mockLogger,
+        }),
+      ).rejects.toThrow('NEXT_PUBLIC_CODEBUFF_APP_URL is not set')
+    })
+  })
+})