Track ad clicks in PostHog

cli/src/chat.tsx

@@ -174,7 +174,7 @@ export const Chat = ({
   })
   const hasSubscription = subscriptionData?.hasSubscription ?? false
 
-  const { ads, recordImpression } = useGravityAd({
+  const { ads, recordClick, recordImpression } = useGravityAd({
     enabled: IS_FREEBUFF || !hasSubscription,
     provider: 'gravity',
     fallbackProvider: 'zeroclick',
@@ -1464,7 +1464,11 @@ export const Chat = ({
         )}
 
         {ads && (IS_FREEBUFF || getAdsEnabled()) && (
-          <ChoiceAdBanner ads={ads} onImpression={recordImpression} />
+          <ChoiceAdBanner
+            ads={ads}
+            onClick={recordClick}
+            onImpression={recordImpression}
+          />
         )}
 
         {reviewMode ? (

cli/src/components/choice-ad-banner.tsx

@@ -11,6 +11,7 @@ import type { AdResponse } from '../hooks/use-gravity-ad'
 
 interface ChoiceAdBannerProps {
   ads: AdResponse[]
+  onClick?: (ad: AdResponse) => void
   onImpression?: (ad: AdResponse) => void
 }
 
@@ -61,7 +62,11 @@ function columnWidths(count: number, availableWidth: number): number[] {
   return Array.from({ length: count }, (_, i) => base + (i < remainder ? 1 : 0))
 }
 
-export const ChoiceAdBanner: React.FC<ChoiceAdBannerProps> = ({ ads, onImpression }) => {
+export const ChoiceAdBanner: React.FC<ChoiceAdBannerProps> = ({
+  ads,
+  onClick,
+  onImpression,
+}) => {
   const theme = useTheme()
   const { terminalWidth } = useTerminalDimensions()
   const [hoveredIndex, setHoveredIndex] = useState<number | null>(null)
@@ -115,7 +120,9 @@ export const ChoiceAdBanner: React.FC<ChoiceAdBannerProps> = ({ ads, onImpressio
             <Button
               key={ad.impUrl}
               onClick={() => {
-                if (ad.clickUrl) safeOpen(ad.clickUrl)
+                if (!ad.clickUrl) return
+                onClick?.(ad)
+                safeOpen(ad.clickUrl)
               }}
               onMouseOver={() => setHoveredIndex(i)}
               onMouseOut={() => setHoveredIndex(null)}

cli/src/components/waiting-room-screen.tsx

@@ -299,7 +299,7 @@ export const WaitingRoomScreen: React.FC<WaitingRoomScreenProps> = ({
   // forceStart bypasses the "wait for first user message" gate inside the hook,
   // which would otherwise block ads here since no conversation exists yet.
   // Try Gravity first, then fall back to ZeroClick when Gravity doesn't fill.
-  const { ads, recordImpression } = useGravityAd({
+  const { ads, recordClick, recordImpression } = useGravityAd({
     enabled: true,
     forceStart: true,
     provider: 'gravity',
@@ -733,7 +733,11 @@ export const WaitingRoomScreen: React.FC<WaitingRoomScreenProps> = ({
           }}
         >
           {ads ? (
-            <ChoiceAdBanner ads={ads} onImpression={recordImpression} />
+            <ChoiceAdBanner
+              ads={ads}
+              onClick={recordClick}
+              onImpression={recordImpression}
+            />
           ) : (
             <text style={{ fg: theme.muted }}>
               {'─'.repeat(terminalWidth)}

cli/src/hooks/use-gravity-ad.ts

@@ -42,6 +42,7 @@ export type AdSurface = 'waiting_room'
 export type GravityAdState = {
   ads: AdResponse[] | null
   isLoading: boolean
+  recordClick: (ad: AdResponse) => void
   recordImpression: (ad: AdResponse) => void
 }
 
@@ -231,6 +232,35 @@ export const useGravityAd = (options?: {
     })
   }
 
+  const recordClick = (ad: AdResponse): void => {
+    const authToken = getAuthToken()
+    if (!authToken) {
+      logger.warn('[ads] No auth token, skipping ad click recording')
+      return
+    }
+
+    void fetch(`${WEBSITE_URL}/api/v1/ads/click`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${authToken}`,
+        'User-Agent': getCliAdRequestUserAgent(),
+      },
+      body: JSON.stringify({ impUrl: ad.impUrl, surface: surface ?? 'chat' }),
+    })
+      .then((res) => {
+        if (!res.ok) {
+          logger.debug(
+            { status: res.status },
+            '[ads] Failed to record ad click',
+          )
+        }
+      })
+      .catch((err) => {
+        logger.debug({ err }, '[ads] Failed to record ad click')
+      })
+  }
+
   type FetchAdResult = { ads: AdResponse[] } | null
 
   // Fetch an ad via web API
@@ -411,6 +441,7 @@ export const useGravityAd = (options?: {
   return {
     ads: visible ? ads : null,
     isLoading,
+    recordClick,
     recordImpression: recordImpressionOnce,
   }
 }

common/src/constants/analytics-events.ts

@@ -136,6 +136,7 @@ export enum AnalyticsEvent {
 
   // Web - Ads API
   ADS_API_AUTH_ERROR = 'api.ads_auth_error',
+  ADS_CLICKED = 'ads.clicked',
 
   // Web - Token Count API
   TOKEN_COUNT_REQUEST = 'api.token_count_request',

web/src/app/api/v1/ads/click/_post.ts

@@ -0,0 +1,125 @@
+import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
+import db from '@codebuff/internal/db'
+import * as schema from '@codebuff/internal/db/schema'
+import { and, eq, isNull } from 'drizzle-orm'
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+
+import { requireUserFromApiKey } from '../../_helpers'
+
+import type { TrackEventFn } from '@codebuff/common/types/contracts/analytics'
+import type { GetUserInfoFromApiKeyFn } from '@codebuff/common/types/contracts/database'
+import type {
+  Logger,
+  LoggerWithContextFn,
+} from '@codebuff/common/types/contracts/logger'
+import type { NextRequest } from 'next/server'
+
+const bodySchema = z.object({
+  impUrl: z.url(),
+  surface: z.enum(['chat', 'waiting_room']).optional(),
+})
+
+export async function postAdClick(params: {
+  req: NextRequest
+  getUserInfoFromApiKey: GetUserInfoFromApiKeyFn
+  logger: Logger
+  loggerWithContext: LoggerWithContextFn
+  trackEvent: TrackEventFn
+}) {
+  const { req, getUserInfoFromApiKey, loggerWithContext, trackEvent } = params
+  const baseLogger = params.logger
+
+  let impUrl: string
+  let surface: z.infer<typeof bodySchema>['surface']
+  try {
+    const json = await req.json()
+    const parsed = bodySchema.safeParse(json)
+    if (!parsed.success) {
+      return NextResponse.json(
+        { error: 'Invalid request body', details: parsed.error.format() },
+        { status: 400 },
+      )
+    }
+    impUrl = parsed.data.impUrl
+    surface = parsed.data.surface
+  } catch {
+    return NextResponse.json(
+      { error: 'Invalid JSON in request body' },
+      { status: 400 },
+    )
+  }
+
+  const authed = await requireUserFromApiKey({
+    req,
+    getUserInfoFromApiKey,
+    logger: baseLogger,
+    loggerWithContext,
+    trackEvent,
+    authErrorEvent: AnalyticsEvent.ADS_API_AUTH_ERROR,
+  })
+  if (!authed.ok) return authed.response
+
+  const { userId, logger } = authed.data
+
+  const adRecord = await db.query.adImpression.findFirst({
+    where: eq(schema.adImpression.imp_url, impUrl),
+  })
+
+  if (!adRecord || adRecord.user_id !== userId) {
+    logger.warn(
+      {
+        userId,
+        adUserId: adRecord?.user_id,
+        impUrl,
+      },
+      '[ads] Ad click not found for user',
+    )
+    return NextResponse.json(
+      { success: false, error: 'Ad not found' },
+      { status: 404 },
+    )
+  }
+
+  trackEvent({
+    event: AnalyticsEvent.ADS_CLICKED,
+    userId,
+    properties: {
+      ad_impression_id: adRecord.id,
+      provider: adRecord.provider,
+      title: adRecord.title,
+      cta: adRecord.cta,
+      ad_url: adRecord.url,
+      already_clicked: Boolean(adRecord.clicked_at),
+      impression_recorded: Boolean(adRecord.impression_fired_at),
+      surface,
+    },
+    logger,
+  })
+
+  try {
+    await db
+      .update(schema.adImpression)
+      .set({ clicked_at: new Date() })
+      .where(
+        and(
+          eq(schema.adImpression.id, adRecord.id),
+          isNull(schema.adImpression.clicked_at),
+        ),
+      )
+  } catch (error) {
+    logger.error(
+      {
+        userId,
+        impUrl,
+        error:
+          error instanceof Error
+            ? { name: error.name, message: error.message }
+            : error,
+      },
+      '[ads] Failed to update ad click record',
+    )
+  }
+
+  return NextResponse.json({ success: true })
+}

web/src/app/api/v1/ads/click/route.ts

@@ -0,0 +1,18 @@
+import { trackEvent } from '@codebuff/common/analytics'
+
+import { postAdClick } from './_post'
+
+import type { NextRequest } from 'next/server'
+
+import { getUserInfoFromApiKey } from '@/db/user'
+import { logger, loggerWithContext } from '@/util/logger'
+
+export async function POST(req: NextRequest) {
+  return postAdClick({
+    req,
+    getUserInfoFromApiKey,
+    logger,
+    loggerWithContext,
+    trackEvent,
+  })
+}