Function createCarbonProvider

web/src/lib/ad-providers/carbon.ts:98–174

(config: { zoneKey: string })

}

export function createCarbonProvider(config: { zoneKey: string }): AdProvider {
  return {
    id: 'carbon',
    fetchAd: async (input: FetchAdInput): Promise<FetchAdResult> => {
      const { clientIp, userAgent, requestUserAgent, testMode, logger, fetch } =
        input

      if (!clientIp || !userAgent) {
        logger.debug(
          { hasIp: !!clientIp, hasUA: !!userAgent },
          '[ads:carbon] Missing required clientIp or userAgent',
        )
        return null
      }

      const params = new URLSearchParams({
        useragent: userAgent,
        forwardedip: clientIp,
      })
      // Carbon's `ignore=yes` loads ads without counting impressions. Use it
      // in non-prod so we never accidentally bill advertisers for dev traffic.
      if (testMode) params.set('ignore', 'yes')

      const url = `${CARBON_URL_BASE}/${config.zoneKey}.json?${params.toString()}`

      const fetchOne = async (): Promise<NormalizedAd | null> => {
        const response = await fetch(url, {
          method: 'GET',
          headers: {
            'User-Agent': requestUserAgent ?? userAgent,
          },
        })
        if (!response.ok) {
          let body: unknown
          try {
            body = await response.text()
          } catch {
            body = 'Unable to parse error response'
          }
          logger.error(
            { url, status: response.status, body },
            '[ads:carbon] API returned error',
          )
          return null
        }
        const data = (await response.json()) as CarbonResponse
        const first = data.ads?.[0]
        if (!first) return null
        return normalizeCarbonAd(first)
      }

      const results = await Promise.all(
        Array.from({ length: CARBON_CHOICE_FETCH_COUNT }, fetchOne),
      )

      // Dedupe by description — Carbon issues a fresh tracker URL per request
      // even for the same creative, so clickUrl/impUrl can't serve as a
      // stable identity key.