@alumbwe/anvil 1.0.0

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

@@ -0,0 +1,656 @@
+import { WEBSITE_URL } from '@anvil/sdk'
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+import { getAdUserAgent } from '@anvil/common/util/ad-user-agent'
+import { useEffect, useRef, useState } from 'react'
+
+import { useTerminalLayout } from './use-terminal-layout'
+import { getAdsEnabled } from '../commands/ads'
+import { useChatStore } from '../state/chat-store'
+import { isUserActive, subscribeToActivity } from '../utils/activity-tracker'
+import { getAuthToken } from '../utils/auth'
+import { IS_FREEBUFF } from '../utils/constants'
+import { getCliEnv } from '../utils/env'
+import { logger } from '../utils/logger'
+import { AI_MESSAGE_ID_PREFIX } from '../utils/ai-message-id'
+import { trackEvent } from '../utils/analytics'
+import {
+  createLazyResponseAdQueue,
+  MAX_RESPONSE_AD_POOL_SIZE,
+  requestLazyResponseAds,
+} from '../utils/lazy-response-ads'
+
+import type { Message } from '@anvil/sdk'
+import type { ChatMessage } from '../types/chat'
+
+const AD_ROTATION_INTERVAL_MS = 60 * 1000 // 60 seconds per ad
+const MAX_ADS_AFTER_ACTIVITY = 3 // Show up to 3 ads after last activity, then pause fetching new ads
+const ACTIVITY_THRESHOLD_MS = 30_000 // 30 seconds idle threshold for fetching new ads
+const MAX_AD_CACHE_SIZE = 50 // Maximum number of ads to keep in cache
+const ZEROCLICK_IMPRESSIONS_URL = 'https://zeroclick.dev/api/v2/impressions'
+
+// Ad response type (normalized shape across providers; credits added after impression)
+export type AdResponse = {
+  adText: string
+  title: string
+  cta: string
+  url: string
+  favicon: string
+  clickUrl: string
+  impUrl: string
+  provider?: AdProvider
+  impressionIds?: string[]
+  credits?: number // Set after impression is recorded (in cents)
+}
+
+/**
+ * Which upstream ad network to query. The server maps each provider onto the
+ * same normalized response shape, so the rest of the hook is provider-agnostic.
+ */
+export type AdProvider = 'gravity' | 'carbon' | 'zeroclick'
+// Product surfaces the ads API maps to Gravity placements. 'waiting_room' is the
+// legacy wire name for the freebuff landing screen; 'cli_chat' is the inline
+// transcript ad in the coding-agent chat. Values must match the server's
+// AD_SURFACES enum, so don't rename them.
+export type AdSurface = 'waiting_room' | 'cli_chat'
+
+export type GravityAdState = {
+  ads: AdResponse[] | null
+  /**
+   * On-demand ad pools keyed by assistant message id. The renderer repeats a
+   * full pool when the response has more eligible slots than distinct ads.
+   */
+  responseAds: Record<string, AdResponse[]>
+  /** Lazily fill the response's bounded ad pool as slots become eligible. */
+  requestResponseAds: (messageId: string, count: number) => void
+  isLoading: boolean
+  recordClick: (ad: AdResponse) => void
+  recordImpression: (ad: AdResponse) => void
+}
+
+// Consolidated controller state for the ad rotation logic
+type GravityController = {
+  choiceCache: AdResponse[][] // Cache of ad sets (choice or single-ad units)
+  choiceCacheIndex: number
+  impressionsFired: Set<string>
+  adsShownSinceActivity: number
+  tickInFlight: boolean
+  inlineQueue: ReturnType<typeof createLazyResponseAdQueue<AdResponse>>
+  eligibleSlotCounts: Map<string, number>
+}
+
+// Pure helper: add an ad set to the cache
+function addToChoiceCache(ctrl: GravityController, ads: AdResponse[]): void {
+  // ZeroClick offer responses must not be stored for later display. Keep them
+  // out of the rotation cache and only render them for the live request.
+  if (ads.some((ad) => ad.provider === 'zeroclick')) return
+
+  // Deduplicate by checking if any set has the same first impUrl
+  const key = ads[0]?.impUrl
+  if (key && ctrl.choiceCache.some((set) => set[0]?.impUrl === key)) return
+  if (ctrl.choiceCache.length >= MAX_AD_CACHE_SIZE) ctrl.choiceCache.shift()
+  ctrl.choiceCache.push(ads)
+}
+
+// Pure helper: get the next cached ad set
+function nextFromChoiceCache(ctrl: GravityController): AdResponse[] | null {
+  if (ctrl.choiceCache.length === 0) return null
+  const set = ctrl.choiceCache[ctrl.choiceCacheIndex % ctrl.choiceCache.length]!
+  ctrl.choiceCacheIndex = (ctrl.choiceCacheIndex + 1) % ctrl.choiceCache.length
+  return set
+}
+
+/**
+ * A streamed LLM answer (possibly still in flight). Other top-level
+ * 'ai'-variant messages (bash echoes, system notices, mode dividers) are
+ * excluded via the `ai-` id prefix.
+ */
+export function isAnswerMessage(m: ChatMessage): boolean {
+  return (
+    !m.parentId && m.variant === 'ai' && m.id.startsWith(AI_MESSAGE_ID_PREFIX)
+  )
+}
+
+export function isInlineAdEligibleAnswer(m: ChatMessage): boolean {
+  return isAnswerMessage(m) && m.metadata?.allowInlineAds === true
+}
+
+export function claimAdImpression(
+  impressionsFired: Set<string>,
+  impUrl: string,
+): boolean {
+  if (impressionsFired.has(impUrl)) return false
+  impressionsFired.add(impUrl)
+  return true
+}
+
+function trackInlineAdEvent(
+  event: AnalyticsEvent,
+  properties: Record<string, unknown>,
+): void {
+  try {
+    trackEvent(event, properties)
+  } catch (error) {
+    // Telemetry must never interfere with fetching or rendering an ad.
+    logger.debug({ error, event }, '[ads] Failed to track inline ad event')
+  }
+}
+
+type GravityAdOptionsBase = {
+  enabled?: boolean
+  /** Skip the "wait for first user message" gate. Used by the freebuff
+   *  landing screen, which has no conversation but still needs ads. */
+  forceStart?: boolean
+  /** Ad network to request first. The server owns fallback ordering. */
+  provider?: AdProvider
+  /** Product surface requesting the ad. The server maps this to placements. */
+  surface?: AdSurface
+  /** Explicit provider placement id for the rotating `ads[0]` slot. */
+  slotPlacementId?: string
+}
+
+type GravityAdOptions = GravityAdOptionsBase &
+  (
+    | {
+        /** Lazily fetch interspersed ads as the assistant response grows. */
+        inline: true
+        /** Reusable provider placement id for every lazy inline auction. */
+        inlinePlacementId: string
+      }
+    | {
+        inline?: false
+        inlinePlacementId?: never
+      }
+  )
+
+/**
+ * Fetches the rotating ad slot and, with `inline`, one reusable placement each
+ * time another interspersed response slot becomes eligible. Short answers make
+ * no unnecessary inline requests; long answers repeat a pool of four ads.
+ */
+export const useGravityAd = (options?: GravityAdOptions): GravityAdState => {
+  const enabled = options?.enabled ?? true
+  const forceStart = options?.forceStart ?? false
+  const provider: AdProvider = options?.provider ?? 'gravity'
+  const surface = options?.surface
+  const inline = options?.inline ?? false
+  const inlinePlacementId = options?.inlinePlacementId
+  const slotPlacementId = options?.slotPlacementId
+  const [ads, setAds] = useState<AdResponse[] | null>(null)
+  const [responseAds, setResponseAds] = useState<Record<string, AdResponse[]>>(
+    {},
+  )
+  const [isLoading, setIsLoading] = useState(false)
+
+  // Check if terminal height is too small to show ads
+  const { terminalHeight } = useTerminalLayout()
+  const isVeryCompactHeight = terminalHeight <= 17
+
+  // Freebuff always shows ads even on compact screens (ads are mandatory there).
+  const isFreeMode = IS_FREEBUFF
+
+  // Skip ads on very compact screens unless we're in Freebuff (where ads are mandatory)
+  // Also skip if explicitly disabled (e.g. user has a subscription)
+  const shouldHideAds = !enabled || (isVeryCompactHeight && !isFreeMode)
+
+  // Use Zustand selector instead of manual subscription - only rerenders when value changes
+  const hasUserMessagedStore = useChatStore((s) =>
+    s.messages.some((m) => m.variant === 'user'),
+  )
+  // forceStart lets callers (e.g. the landing screen) opt out of the
+  // "wait for the first user message" gate.
+  const shouldStart = forceStart || hasUserMessagedStore
+
+  // Single consolidated controller ref
+  const ctrlRef = useRef<GravityController>({
+    choiceCache: [],
+    choiceCacheIndex: 0,
+    impressionsFired: new Set(),
+    adsShownSinceActivity: 0,
+    tickInFlight: false,
+    inlineQueue: createLazyResponseAdQueue<AdResponse>(),
+    eligibleSlotCounts: new Map(),
+  })
+
+  // Ref for the tick function (avoids useCallback dependency issues)
+  const tickRef = useRef<() => void>(() => {})
+
+  // Ref to track whether ads should be hidden for use in async code
+  const shouldHideAdsRef = useRef(shouldHideAds)
+  shouldHideAdsRef.current = shouldHideAds
+
+  // Fire impression and update credits (called when showing an ad)
+  const recordImpressionOnce = (ad: AdResponse): void => {
+    // Don't record impressions when ads should be hidden
+    if (shouldHideAdsRef.current) return
+
+    const ctrl = ctrlRef.current
+    const { impUrl } = ad
+    if (!claimAdImpression(ctrl.impressionsFired, impUrl)) return
+
+    const recordLocalImpression = async (): Promise<void> => {
+      const authToken = getAuthToken()
+      if (!authToken) {
+        logger.warn('[ads] No auth token, skipping local impression recording')
+        return
+      }
+
+      // Include mode in request - Freebuff should not grant credits (no balance concept).
+      const agentMode = useChatStore.getState().agentMode
+
+      const res = await fetch(`${WEBSITE_URL}/api/v1/ads/impression`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${authToken}`,
+          'User-Agent': getCliAdRequestUserAgent(),
+        },
+        body: JSON.stringify({
+          impUrl,
+          mode: agentMode,
+        }),
+      })
+
+      if (!res.ok) {
+        logger.debug(
+          { status: res.status },
+          '[ads] Failed to record local ad impression',
+        )
+        return
+      }
+
+      const data = await res.json()
+      if (data.creditsGranted > 0) {
+        logger.info(
+          { creditsGranted: data.creditsGranted },
+          '[ads] Ad impression credits granted',
+        )
+        // Also update credits in visible ads
+        setAds((cur) => {
+          if (!cur) return cur
+          return cur.map((a) =>
+            a.impUrl === impUrl ? { ...a, credits: data.creditsGranted } : a,
+          )
+        })
+      }
+    }
+
+    if (ad.provider === 'zeroclick' && ad.impressionIds?.length) {
+      void (async () => {
+        try {
+          const res = await fetch(ZEROCLICK_IMPRESSIONS_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ids: ad.impressionIds }),
+          })
+
+          if (!res.ok) {
+            logger.debug(
+              { status: res.status },
+              '[ads] Failed to record ZeroClick impression',
+            )
+            return
+          }
+        } catch (err) {
+          logger.debug({ err }, '[ads] Failed to record ZeroClick impression')
+          return
+        }
+
+        recordLocalImpression().catch((err) => {
+          logger.debug({ err }, '[ads] Failed to record local ad impression')
+        })
+      })()
+      return
+    }
+
+    recordLocalImpression().catch((err) => {
+      logger.debug({ err }, '[ads] Failed to record ad impression')
+    })
+  }
+
+  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 } : {}),
+      }),
+    })
+      .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
+  const fetchAd = async (params?: {
+    placementId?: string
+  }): Promise<FetchAdResult> => {
+    // Don't fetch ads when they should be hidden
+    if (shouldHideAdsRef.current) return null
+    if (!getAdsEnabled()) return null
+
+    const authToken = getAuthToken()
+    if (!authToken) {
+      logger.warn('[ads] No auth token available')
+      return null
+    }
+
+    // Get message history from runState (populated after LLM responds)
+    const currentRunState = useChatStore.getState().runState
+    const messageHistory =
+      currentRunState?.sessionState?.mainAgentState?.messageHistory ?? []
+    const adMessages = convertToAdMessages(messageHistory)
+
+    // Also check UI messages for the latest user message
+    // (UI messages update immediately, runState.messageHistory updates after LLM responds)
+    const uiMessages = useChatStore.getState().messages
+    const lastUIMessage = [...uiMessages]
+      .reverse()
+      .find((msg) => msg.variant === 'user')
+
+    // If the latest UI user message isn't in our converted history, append it
+    // This ensures we always include the most recent user message even before LLM responds
+    if (lastUIMessage?.content) {
+      const lastAdUserMessage = [...adMessages]
+        .reverse()
+        .find((m) => m.role === 'user')
+      if (
+        !lastAdUserMessage ||
+        !lastAdUserMessage.content.includes(lastUIMessage.content)
+      ) {
+        adMessages.push({
+          role: 'user',
+          content: `<user_message>${lastUIMessage.content}</user_message>`,
+        })
+      }
+    }
+
+    try {
+      const response = await fetch(`${WEBSITE_URL}/api/v1/ads`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${authToken}`,
+          'User-Agent': getCliAdRequestUserAgent(),
+        },
+        body: JSON.stringify({
+          provider,
+          messages: adMessages,
+          sessionId: useChatStore.getState().chatSessionId,
+          device: getDeviceInfo(),
+          ...(surface ? { surface } : {}),
+          ...(params?.placementId ? { placementId: params.placementId } : {}),
+          // Native runtime UAs look bot-like to ad networks. Send the shared
+          // browser-like UA so every provider sees a usable targeting signal.
+          userAgent: getAdUserAgent(),
+        }),
+      })
+
+      if (!response.ok) {
+        let responseBody: unknown
+        try {
+          const contentType = response.headers.get('content-type') ?? ''
+          responseBody = contentType.includes('application/json')
+            ? await response.json()
+            : await response.text()
+        } catch {
+          responseBody = 'Unable to parse error response'
+        }
+        logger.warn(
+          { provider, status: response.status, response: responseBody },
+          '[ads] Web API returned error',
+        )
+        return null
+      }
+
+      const data = await response.json()
+
+      if (Array.isArray(data.ads) && data.ads.length > 0) {
+        return {
+          ads: (data.ads as AdResponse[]).map((ad) => ({
+            ...ad,
+            provider: data.provider ?? provider,
+          })),
+        }
+      }
+    } catch (err) {
+      logger.error({ err, provider }, '[ads] Failed to fetch ad')
+    }
+
+    return null
+  }
+
+  // Update tick function (uses ref to avoid useCallback dependency issues)
+  tickRef.current = () => {
+    void (async () => {
+      const ctrl = ctrlRef.current
+      if (ctrl.tickInFlight) return
+      ctrl.tickInFlight = true
+
+      try {
+        if (!getAdsEnabled()) return
+
+        // Derive "can fetch new ads" from counter and activity (no separate paused ref needed)
+        const canFetchNew =
+          ctrl.adsShownSinceActivity < MAX_ADS_AFTER_ACTIVITY &&
+          isUserActive(ACTIVITY_THRESHOLD_MS)
+
+        const result = canFetchNew
+          ? await fetchAd({ placementId: slotPlacementId })
+          : null
+
+        if (result) {
+          addToChoiceCache(ctrl, result.ads)
+          ctrl.adsShownSinceActivity += 1
+          setAds(result.ads)
+        } else {
+          // Fall back to cached ads
+          const cachedSet = nextFromChoiceCache(ctrl)
+          if (cachedSet) {
+            ctrl.adsShownSinceActivity += 1
+            setAds(cachedSet)
+          } else {
+            setAds((cur) => (cur?.[0]?.provider === 'zeroclick' ? null : cur))
+          }
+        }
+      } finally {
+        ctrl.tickInFlight = false
+      }
+    })()
+  }
+
+  // Reset ads shown counter on user activity
+  useEffect(() => {
+    if (!getAdsEnabled()) return
+    return subscribeToActivity(() => {
+      ctrlRef.current.adsShownSinceActivity = 0
+    })
+  }, [])
+
+  // Start rotation when user sends first message (or immediately if forced).
+  useEffect(() => {
+    if (!shouldStart || !getAdsEnabled() || shouldHideAds) return
+
+    setIsLoading(true)
+
+    // Fetch first ad immediately
+    void (async () => {
+      const result = await fetchAd({ placementId: slotPlacementId })
+      if (result) {
+        const ctrl = ctrlRef.current
+        addToChoiceCache(ctrl, result.ads)
+        setAds(result.ads)
+        ctrl.adsShownSinceActivity = 1
+      }
+      setIsLoading(false)
+    })()
+
+    // Start interval for rotation (consistent 60s intervals)
+    const id = setInterval(() => tickRef.current(), AD_ROTATION_INTERVAL_MS)
+
+    return () => {
+      clearInterval(id)
+    }
+  }, [shouldStart, shouldHideAds, provider, surface])
+
+  // Called by BlocksRenderer only when its streamed node count makes another
+  // between-node slot eligible, until the four-ad pool is full. Requests use
+  // the same placement id and are serialized per answer so higher-value early
+  // results retain their order. The renderer cycles that exact pool for later
+  // slots without additional auctions or impression events.
+  const requestResponseAds = (messageId: string, count: number): void => {
+    if (
+      !inline ||
+      !inlinePlacementId ||
+      count <= 0 ||
+      shouldHideAdsRef.current ||
+      !getAdsEnabled()
+    ) {
+      return
+    }
+
+    const messages = useChatStore.getState().messages
+    const answer = messages.find((m) => m.id === messageId)
+    if (!answer || !isInlineAdEligibleAnswer(answer)) {
+      return
+    }
+
+    const ctrl = ctrlRef.current
+    const previousEligibleCount = ctrl.eligibleSlotCounts.get(messageId) ?? 0
+    if (count > previousEligibleCount) {
+      ctrl.eligibleSlotCounts.set(messageId, count)
+      const telemetryProperties = {
+        response_id: messageId,
+        chat_session_id: useChatStore.getState().chatSessionId,
+        eligible_slot_count: count,
+        pool_size: MAX_RESPONSE_AD_POOL_SIZE,
+        provider,
+        surface,
+        placement_id: inlinePlacementId,
+        is_freebuff: IS_FREEBUFF,
+      }
+      trackInlineAdEvent(
+        AnalyticsEvent.CLI_INLINE_AD_SLOT_ELIGIBLE,
+        telemetryProperties,
+      )
+
+      if (
+        count > MAX_RESPONSE_AD_POOL_SIZE &&
+        previousEligibleCount <= MAX_RESPONSE_AD_POOL_SIZE
+      ) {
+        trackInlineAdEvent(
+          AnalyticsEvent.CLI_INLINE_AD_POOL_REUSED,
+          telemetryProperties,
+        )
+      }
+    }
+
+    void requestLazyResponseAds({
+      queue: ctrl.inlineQueue,
+      messageId,
+      count,
+      fetchOne: async () => {
+        const result = await fetchAd({ placementId: inlinePlacementId })
+        return result?.ads[0] ?? null
+      },
+      onAd: (ad) => {
+        setResponseAds((prev) => ({
+          ...prev,
+          [messageId]: [...(prev[messageId] ?? []), ad],
+        }))
+      },
+    })
+  }
+
+  // Don't return ads when ads should be hidden
+  const visible = shouldStart && !shouldHideAds
+  return {
+    ads: visible ? ads : null,
+    responseAds: visible ? responseAds : {},
+    requestResponseAds,
+    isLoading,
+    recordClick,
+    recordImpression: recordImpressionOnce,
+  }
+}
+
+type AdMessage = { role: 'user' | 'assistant'; content: string }
+
+/**
+ * Convert LLM message history to ad API format.
+ * Includes only user and assistant messages.
+ */
+const convertToAdMessages = (messages: Message[]): AdMessage[] => {
+  const adMessages: AdMessage[] = messages
+    .filter(
+      (message) => message.role === 'assistant' || message.role === 'user',
+    )
+    .filter(
+      (message) =>
+        !message.tags || !message.tags.includes('INSTRUCTIONS_PROMPT'),
+    )
+    .map((message) => ({
+      role: message.role,
+      content: message.content
+        .filter((c) => c.type === 'text')
+        .map((c) => c.text.trim())
+        .filter((c) => c !== '')
+        .join('\n\n')
+        .trim(),
+    }))
+    .filter((message) => message.content !== '')
+
+  return adMessages
+}
+
+/** Device info sent to the ads API for targeting */
+type DeviceInfo = {
+  os: 'macos' | 'windows' | 'linux'
+  timezone: string
+  locale: string
+}
+
+/** Get device info for ads API */
+function getDeviceInfo(): DeviceInfo {
+  // Map Node.js platform to Gravity API os values
+  const platformToOs: Record<string, 'macos' | 'windows' | 'linux'> = {
+    darwin: 'macos',
+    win32: 'windows',
+    linux: 'linux',
+  }
+  const os = platformToOs[process.platform] ?? 'linux'
+
+  // Get IANA timezone (e.g., "America/New_York")
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+
+  // Get locale (e.g., "en-US")
+  const locale = Intl.DateTimeFormat().resolvedOptions().locale
+
+  return { os, timezone, locale }
+}
+
+function getCliAdRequestUserAgent(): string {
+  const product = IS_FREEBUFF ? 'Freebuff-CLI' : 'Anvil-CLI'
+  const version = getCliEnv().ANVIL_CLI_VERSION ?? 'dev'
+  return `${product}/${version}`
+}