Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@5527cbaec64bfa87b28bf0d6cf2b4a29fa2dc393

Author: github-actions[bot]

common/src/__tests__/freebuff-placements.test.ts

@@ -15,6 +15,7 @@ import {
   PRIMARY_METRICS,
   UNDERSPEND_COPY,
   UNDERSPEND_REASONS,
+  avgCpa,
   avgCpc,
   costPerActivation,
   ctr,
@@ -47,24 +48,24 @@ describe('derived metrics', () => {
       totals({
         impressionsServed: 2_000,
         impressionsViewed: 1_000,
-        billableClicks: 10,
+        clicks: 10,
       }),
     )
 
     expect(value).toBe(0.01)
   })
 
-  it('counts billable clicks in CTR, not raw clicks', () => {
-    // The invoice bills billable clicks, so the dashboard's rate has to use
-    // the same numerator or the two disagree in front of the advertiser.
+  it('keeps CTR diagnostic and counts raw clicks, not only billed clicks', () => {
+    // CPA does not bill a click. CTR must remain a diagnostic of actual click
+    // behaviour across both billing models rather than a disguised invoice rate.
     const value = ctr(
       totals({ impressionsViewed: 1_000, clicks: 20, billableClicks: 10 }),
     )
 
-    expect(value).toBe(0.01)
+    expect(value).toBe(0.02)
   })
 
-  it('computes cost per activation, average CPC and eCPM in dollars', () => {
+  it('computes CPA, CPC and eCPM in dollars', () => {
     const measured = totals({
       activations: 4,
       impressionsViewed: 10_000,
@@ -74,6 +75,7 @@ describe('derived metrics', () => {
     })
 
     expect(costPerActivation(measured)).toBe(15)
+    expect(avgCpa(measured)).toBe(15)
     expect(avgCpc(measured)).toBe(1.5)
     expect(ecpm(measured)).toBe(6)
     expect(spendUsd(measured)).toBe(60)
@@ -201,10 +203,11 @@ describe('copy and configuration', () => {
     // transcript alone is twice the waiting room's slot count.
     const bySurface = (surface: string) =>
       PLACEMENT_SLOTS.filter((slot) => slot.surface === surface).length
-    // CLI transcript + Desktop inline. NOT the eight `CLI-Chat-Inline-N` ids:
+    // CLI transcript + its legacy single slot + both Desktop units. NOT the
+    // eight `CLI-Chat-Inline-N` ids:
     // no shipping client requests those, so selling them would be selling a
     // decaying legacy path.
-    expect(bySurface('cli_chat')).toBe(2)
+    expect(bySurface('cli_chat')).toBe(4)
     expect(bySurface('waiting_room')).toBe(4)
     expect(bySurface('freebuff_web_chat')).toBe(2)
     expect(bySurface('chat_assistant')).toBe(1)
@@ -227,6 +230,16 @@ describe('copy and configuration', () => {
     }
   })
 
+  it('exposes both CPA and CPC primary facts for model-aware dashboards', () => {
+    expect(PRIMARY_METRICS).toEqual([
+      'billableClicks',
+      'activations',
+      'spend',
+      'avgCpc',
+      'avgCpa',
+    ])
+  })
+
   it('never labels impressions as a purchasable unit', () => {
     // eCPM is a derived yield figure for comparison against CPM inventory the
     // advertiser already buys. We do not sell impressions.

common/src/constants/freebuff-placements.ts

@@ -26,8 +26,8 @@ import type { AdCampaignStatus } from './freebuff-ads'
  * `off`), read by `placementsAudience()` in
  * `freebuff/web/src/server/advertisers/placements/access.ts`. What survives
  * here is the implementation-state assertion the knob is set against. Delivery
- * rollups are intentionally honest zeros until aggregation lands; they are not
- * fixtures.
+ * rollups expose coverage alongside delivery; an uncovered day is unknown,
+ * not a zero and never fixture data.
  */
 export const PLACEMENTS_CONSOLE_ENABLED = true
 
@@ -88,9 +88,10 @@ export const ATTRIBUTION_WINDOW_COPY = `Activation counts within ${ACTIVATION_AT
  * exclusivity term. That term does not exist, so chat is sellable -- and it is
  * where nearly all the volume is.
  *
- * `Single-Ad-Unit-1` is deliberately absent: it serves callers that named no
- * surface, and first-party targeting is expressed in surfaces, so a creative
- * could never match it.
+ * `Single-Ad-Unit-1` and `Desktop-Below-Chat` are live legacy slots as well as
+ * the primary inline units. They remain sellable until their clients retire;
+ * leaving either out would route an advertiser's inventory straight past a
+ * rendered surface.
  */
 export const PLACEMENT_SLOTS = [
   { id: 'waiting-room-1', surface: 'waiting_room', available: true },
@@ -101,6 +102,8 @@ export const PLACEMENT_SLOTS = [
   { id: 'CLI-Chat-Inline', surface: 'cli_chat', available: true },
   // Desktop's inline slot -- the largest single placement by fill volume.
   { id: 'Desktop-Inline-Chat', surface: 'cli_chat', available: true },
+  { id: 'Desktop-Below-Chat', surface: 'cli_chat', available: true },
+  { id: 'Single-Ad-Unit-1', surface: 'cli_chat', available: true },
   {
     id: 'Web-Chat-After-User-Message',
     surface: 'freebuff_web_chat',
@@ -127,32 +130,39 @@ export const PLACEMENT_SLOTS = [
  * network already ships.
  */
 export const PRIMARY_METRICS = [
+  'billableClicks',
   'activations',
-  'costPerActivation',
   'spend',
+  'avgCpc',
+  'avgCpa',
 ] as const
 export const DIAGNOSTIC_METRICS = [
   'impressions',
   'clicks',
-  'billableClicks',
   'ctr',
-  'avgCpc',
   'ecpm',
 ] as const
 
 export type PrimaryMetric = (typeof PRIMARY_METRICS)[number]
 export type DiagnosticMetric = (typeof DIAGNOSTIC_METRICS)[number]
-export type PlacementMetric = PrimaryMetric | DiagnosticMetric
+/** Legacy conversion labels remain addressable while conversion reporting is
+ * intentionally hidden from the CPC MVP UI. */
+export type PlacementMetric =
+  | PrimaryMetric
+  | DiagnosticMetric
+  | 'activations'
+  | 'costPerActivation'
 
 export const PLACEMENT_METRIC_LABELS: Record<PlacementMetric, string> = {
-  activations: 'Activations',
-  costPerActivation: 'Cost per activation',
+  activations: 'Billable activations',
+  costPerActivation: 'Avg CPA',
   spend: 'Spend',
   impressions: 'Impressions',
   clicks: 'Clicks',
   billableClicks: 'Billable',
   ctr: 'CTR',
   avgCpc: 'Avg CPC',
+  avgCpa: 'Avg CPA',
   ecpm: 'Effective CPM',
 }
 
@@ -195,10 +205,10 @@ function ratio(numerator: number, denominator: number): number | null {
  * a viewability claim we sell against.
  */
 export function ctr(totals: PlacementTotals): number | null {
-  return ratio(totals.billableClicks, totals.impressionsViewed)
+  return ratio(totals.clicks, totals.impressionsViewed)
 }
 
-/** Spend per activation — the number an advertiser actually judges us on. */
+/** Conversion attribution is not part of the CPC MVP. Kept for broad types. */
 export function costPerActivation(totals: PlacementTotals): number | null {
   const perActivation = ratio(totals.spendCents, totals.activations)
   return perActivation === null ? null : perActivation / 100
@@ -210,6 +220,11 @@ export function avgCpc(totals: PlacementTotals): number | null {
   return perClick === null ? null : perClick / 100
 }
 
+/** Spend per verified, payable activation. */
+export function avgCpa(totals: PlacementTotals): number | null {
+  return costPerActivation(totals)
+}
+
 /**
  * Effective CPM — yield per thousand viewed impressions.
  *

common/src/util/__tests__/ad-experiment.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 
 import {
+  DEFAULT_FIRST_PARTY_BACKFILL,
   DEFAULT_FIRST_PARTY_PRIMARY_PERCENT,
   IMPREZIA_EXPERIMENT_PERCENT,
   adExperimentArmForUser,
@@ -38,6 +39,17 @@ describe('imprezia experiment arm', () => {
 })
 
 describe('first-party request routing', () => {
+  test('keeps an absent runtime configuration on the paid-network-only path', () => {
+    expect(DEFAULT_FIRST_PARTY_PRIMARY_PERCENT).toBe(0)
+    expect(DEFAULT_FIRST_PARTY_BACKFILL).toBe(false)
+    expect(
+      firstPartyAdRouteForUser('user-42', {
+        primaryPercent: DEFAULT_FIRST_PARTY_PRIMARY_PERCENT,
+        backfill: DEFAULT_FIRST_PARTY_BACKFILL,
+      }),
+    ).toBe('paid_network_only')
+  })
+
   test('never routes a missing user id into first-party inventory', () => {
     for (const id of [null, undefined, '']) {
       expect(

common/src/util/__tests__/axiom-only-log.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from 'bun:test'
 
 import {
   ADS_FETCH_COMPLETED_EVENT,
+  ADS_FIRST_PARTY_DECISION_EVENT,
+  ADS_FIRST_PARTY_SETTLEMENT_EVENT,
   CONTEXT_PRUNING_COMPLETED_EVENT,
   getAxiomOnlyLogEvent,
   STREAM_RECOVERY_EVENT,
@@ -61,7 +63,10 @@ describe('getAxiomOnlyLogEvent', () => {
         }),
       ).toBeNull()
       expect(
-        getAxiomOnlyLogEvent({ prompt: 'must not be silently dropped' }, poisonEvent),
+        getAxiomOnlyLogEvent(
+          { prompt: 'must not be silently dropped' },
+          poisonEvent,
+        ),
       ).toBeNull()
     }
   })
@@ -139,30 +144,119 @@ describe('getAxiomOnlyLogEvent', () => {
     })
   })
 
-  test('sanitizes ad-fetch metadata', () => {
+  test('preserves bounded scalar ad-routing metadata and drops identifiers', () => {
     expect(
       getAxiomOnlyLogEvent({
         axiomEvent: ADS_FETCH_COMPLETED_EVENT,
         outcome: 'fill',
         requested_provider: 'gravity',
-        served_provider: 'carbon',
+        served_provider: 'first_party',
+        attempted_provider_chain: 'gravity>first_party',
+        experiment_arm: 'treatment',
+        first_party_route: 'gravity_then_first_party',
+        first_party_primary_percent: 10,
+        first_party_backfill_enabled: true,
+        selection_reason: 'gravity_no_fill_backfill',
         ad_count: 1,
+        surface: 'cli',
         placement_id: 'CLI-Chat-Inline',
         duration_ms: 42,
         client_ua_product: 'freebuff-cli',
+        client_ua_version: '1.2.3',
+        // Arrays must be producer-encoded as attempted_provider_chain.
         attempted_providers: ['gravity', 'carbon'],
+        // High-cardinality identifiers and content do not reach Axiom.
+        userId: 'user-123',
+        advertiser_id: 'advertiser-123',
+        chat_session_id: 'session-123',
+        campaign_ids: ['campaign-123'],
+        creative_ids: ['creative-123'],
+        ad_url: 'https://example.com/secret',
         messages: [{ role: 'user', content: 'secret' }],
       }),
     ).toEqual({
       event: ADS_FETCH_COMPLETED_EVENT,
       data: {
         outcome: 'fill',
         requested_provider: 'gravity',
-        served_provider: 'carbon',
+        served_provider: 'first_party',
+        attempted_provider_chain: 'gravity>first_party',
+        experiment_arm: 'treatment',
+        first_party_route: 'gravity_then_first_party',
+        first_party_primary_percent: 10,
+        first_party_backfill_enabled: true,
+        selection_reason: 'gravity_no_fill_backfill',
         ad_count: 1,
+        surface: 'cli',
         placement_id: 'CLI-Chat-Inline',
         duration_ms: 42,
         client_ua_product: 'freebuff-cli',
+        client_ua_version: '1.2.3',
+      },
+    })
+  })
+
+  test('names and sanitizes first-party selection telemetry', () => {
+    expect(
+      getAxiomOnlyLogEvent({
+        axiomEvent: ADS_FIRST_PARTY_DECISION_EVENT,
+        outcome: 'no_fill',
+        no_fill_reason: 'no_eligible_campaign',
+        placement_count: 2,
+        candidate_count: 4,
+        candidate_load_ms: 8,
+        frequency_status: 'unavailable',
+        frequency_unavailable_cause: 'timeout',
+        frequency_reservation_ms: 75,
+        duration_ms: 11,
+        campaign_ids: ['campaign-123'],
+        creative_ids: ['creative-123'],
+        placement_ids: ['CLI-Chat-Inline'],
+        userId: 'user-123',
+        reasons: ['budget_exhausted'],
+        nested: { private: true },
+      }),
+    ).toEqual({
+      event: ADS_FIRST_PARTY_DECISION_EVENT,
+      data: {
+        outcome: 'no_fill',
+        no_fill_reason: 'no_eligible_campaign',
+        placement_count: 2,
+        candidate_count: 4,
+        candidate_load_ms: 8,
+        frequency_status: 'unavailable',
+        frequency_unavailable_cause: 'timeout',
+        frequency_reservation_ms: 75,
+        duration_ms: 11,
+      },
+    })
+  })
+
+  test('names and sanitizes first-party settlement telemetry', () => {
+    expect(
+      getAxiomOnlyLogEvent(
+        {
+          billing_model: 'cpa',
+          settlement_status: 'charged',
+          amount_cents: 75,
+          balance_cents: 925,
+          duration_ms: 6,
+          userId: 'user-123',
+          advertiser_id: 'advertiser-123',
+          campaign_id: 'campaign-123',
+          ad_impression_id: 'impression-123',
+          error: { message: 'private failure detail' },
+        },
+        ADS_FIRST_PARTY_SETTLEMENT_EVENT,
+      ),
+    ).toEqual({
+      event: ADS_FIRST_PARTY_SETTLEMENT_EVENT,
+      data: {
+        billing_model: 'cpa',
+        settlement_status: 'charged',
+        amount_cents: 75,
+        balance_cents: 925,
+        duration_ms: 6,
       },
     })
   })

common/src/util/ad-experiment.ts

@@ -33,9 +33,12 @@ export const IMPREZIA_EXPERIMENT_PERCENT = 10
 export const FIRST_PARTY_ROUTING_EXPERIMENT =
   'ads_first_party_before_paid_networks_2026_08'
 
-/** Unset env values preserve the initial launch allocation. */
-export const DEFAULT_FIRST_PARTY_PRIMARY_PERCENT = 10
-export const DEFAULT_FIRST_PARTY_BACKFILL = true
+/**
+ * An absent runtime knob is a dark deploy. Allocation is deliberately opt-in:
+ * a missing Infisical value must not take paid-network inventory.
+ */
+export const DEFAULT_FIRST_PARTY_PRIMARY_PERCENT = 0
+export const DEFAULT_FIRST_PARTY_BACKFILL = false
 
 export type FirstPartyAdRoute =
   | 'paid_network_only'