feat(api): add referral_link field to /api/v1/me endpoint

- Add referral_code and referral_link to valid user fields
- Compute referral_link from referral_code on backend
- Update database contracts and tests
- Allows CLI to fetch ready-to-use referral links

Author: brandonkachen

common/src/testing/impl/agent-runtime.ts

@@ -27,6 +27,7 @@ export const TEST_AGENT_RUNTIME_IMPL = Object.freeze<
     id: 'test-user-id',
     email: 'test-email',
     discord_id: 'test-discord-id',
+    referral_code: 'ref-test-code',
   }),
   fetchAgentFromDatabase: async () => null,
   startAgentRun: async () => 'test-agent-run-id',

common/src/types/contracts/database.ts

@@ -5,8 +5,9 @@ type User = {
   id: string
   email: string
   discord_id: string | null
+  referral_code: string | null
 }
-export const userColumns = ['id', 'email', 'discord_id'] as const
+export const userColumns = ['id', 'email', 'discord_id', 'referral_code'] as const
 export type UserColumn = keyof User
 export type GetUserInfoFromApiKeyInput<T extends UserColumn> = {
   apiKey: string

web/src/app/api/v1/me/__tests__/me.test.ts

@@ -22,11 +22,13 @@ describe('/api/v1/me route', () => {
       id: 'user-123',
       email: 'test@example.com',
       discord_id: 'discord-123',
+      referral_code: 'ref-user-123',
     },
     'test-api-key-456': {
       id: 'user-456',
       email: 'test2@example.com',
       discord_id: null,
+      referral_code: 'ref-user-456',
     },
   }
 
@@ -208,7 +210,7 @@ describe('/api/v1/me route', () => {
       const body = await response.json()
       expect(body.error).toContain('Invalid fields: invalid_field')
       expect(body.error).toContain(
-        `Valid fields are: ${VALID_USER_INFO_FIELDS.join(', ')}`,
+        'Valid fields are: id, email, discord_id, referral_code, referral_link',
       )
     })
 
@@ -298,6 +300,23 @@ describe('/api/v1/me route', () => {
       })
     })
 
+    test('returns referral_link when requested', async () => {
+      const req = new NextRequest(
+        'http://localhost:3000/api/v1/me?fields=referral_link',
+        {
+          headers: { Authorization: 'Bearer test-api-key-123' },
+        },
+      )
+
+      const response = await getMe({
+        ...agentRuntimeImpl,
+        req,
+      })
+      expect(response.status).toBe(200)
+      const body = await response.json()
+      expect(typeof body.referral_link).toBe('string')
+    })
+
     test('handles null discord_id correctly', async () => {
       const req = new NextRequest(
         'http://localhost:3000/api/v1/me?fields=id,discord_id',

web/src/app/api/v1/me/_get.ts

@@ -1,4 +1,5 @@
 import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
+import { getReferralLink } from '@codebuff/common/util/referral'
 import { NextResponse } from 'next/server'
 
 import type { TrackEventFn } from '@codebuff/common/types/contracts/analytics'
@@ -9,7 +10,16 @@ import type { NextRequest } from 'next/server'
 import { VALID_USER_INFO_FIELDS } from '@/db/user'
 import { extractApiKeyFromHeader } from '@/util/auth'
 
-type ValidField = (typeof VALID_USER_INFO_FIELDS)[number]
+const DERIVED_USER_INFO_FIELDS = ['referral_link'] as const
+
+type DerivedField = (typeof DERIVED_USER_INFO_FIELDS)[number]
+type ValidDbField = (typeof VALID_USER_INFO_FIELDS)[number]
+type ValidField = ValidDbField | DerivedField
+
+const ALL_USER_INFO_FIELDS = [
+  ...VALID_USER_INFO_FIELDS,
+  ...DERIVED_USER_INFO_FIELDS,
+] as const
 
 export async function getMe(params: {
   req: NextRequest
@@ -41,15 +51,15 @@ export async function getMe(params: {
     if (requestedFields.length === 0) {
       return NextResponse.json(
         {
-          error: `Invalid fields: empty. Valid fields are: ${VALID_USER_INFO_FIELDS.join(', ')}`,
+          error: `Invalid fields: empty. Valid fields are: ${ALL_USER_INFO_FIELDS.join(', ')}`,
         },
         { status: 400 },
       )
     }
 
     // Validate that all requested fields are valid
     const invalidFields = requestedFields.filter(
-      (f) => !VALID_USER_INFO_FIELDS.includes(f as ValidField),
+      (f) => !ALL_USER_INFO_FIELDS.includes(f as ValidField),
     )
     if (invalidFields.length > 0) {
       trackEvent({
@@ -63,7 +73,7 @@ export async function getMe(params: {
       })
       return NextResponse.json(
         {
-          error: `Invalid fields: ${invalidFields.join(', ')}. Valid fields are: ${VALID_USER_INFO_FIELDS.join(', ')}`,
+          error: `Invalid fields: ${invalidFields.join(', ')}. Valid fields are: ${ALL_USER_INFO_FIELDS.join(', ')}`,
         },
         { status: 400 },
       )
@@ -74,10 +84,29 @@ export async function getMe(params: {
     fields = ['id']
   }
 
+  // Build database field selection (exclude derived fields, always include id)
+  const dbFieldsSet = new Set<ValidDbField>()
+
+  for (const field of fields) {
+    if (VALID_USER_INFO_FIELDS.includes(field as ValidDbField)) {
+      dbFieldsSet.add(field as ValidDbField)
+    }
+  }
+
+  // Always include id for tracking
+  dbFieldsSet.add('id')
+
+  // If referral_link is requested, ensure we also fetch referral_code
+  if (fields.includes('referral_link') && !dbFieldsSet.has('referral_code')) {
+    dbFieldsSet.add('referral_code')
+  }
+
+  const dbFields = Array.from(dbFieldsSet)
+
   // Get user info
   const userInfo = await getUserInfoFromApiKey({
     apiKey,
-    fields,
+    fields: dbFields,
     logger,
   })
 
@@ -98,5 +127,22 @@ export async function getMe(params: {
     logger,
   })
 
-  return NextResponse.json(userInfo)
+  // Build response including derived fields
+  const userInfoRecord = userInfo as Partial<Record<ValidDbField, string | null>>
+
+  const responseBody: Record<string, unknown> = {}
+
+  for (const field of fields) {
+    if (field === 'referral_link') {
+      const referralCode = userInfoRecord.referral_code ?? null
+      responseBody.referral_link =
+        typeof referralCode === 'string' && referralCode.length > 0
+          ? getReferralLink(referralCode)
+          : null
+    } else {
+      responseBody[field] = userInfoRecord[field as ValidDbField] ?? null
+    }
+  }
+
+  return NextResponse.json(responseBody)
 }

web/src/db/user.ts

@@ -7,7 +7,12 @@ import type {
   GetUserInfoFromApiKeyOutput,
 } from '@codebuff/common/types/contracts/database'
 
-export const VALID_USER_INFO_FIELDS = ['id', 'email', 'discord_id'] as const
+export const VALID_USER_INFO_FIELDS = [
+  'id',
+  'email',
+  'discord_id',
+  'referral_code',
+] as const
 
 export async function getUserInfoFromApiKey<
   T extends (typeof VALID_USER_INFO_FIELDS)[number],