Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@6897ef215f7b0b07c2a6613ef1faef498dd66daa

Author: github-actions[bot]

bun.lock

@@ -16,9 +16,16 @@ import {
   PLACEMENTS_CONSOLE_ENABLED,
   PLACEMENT_METRIC_LABELS,
   PLACEMENT_PREVIEW_WIDTHS,
+  PLACEMENT_FORMATS,
   PLACEMENT_SLOTS,
+  SPONSOR_BREAK_CREATIVE_LIMITS,
+  SPONSOR_BREAK_FORMATS,
+  SPONSOR_BREAK_HERO_SPEC,
   TRACKED_LINK_PLACEMENT_ID,
+  isSponsorBreakPlacement,
+  placementFormat,
   placementSlotLabel,
+  placementSurface,
   PLACEMENT_STATUS_LABELS,
   PRIMARY_METRICS,
   UNDERSPEND_COPY,
@@ -221,12 +228,78 @@ describe('copy and configuration', () => {
     // 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(4)
+    // Plus the three sponsor breaks, which are deliberately the same surface:
+    // a break is a different RENDERER on Desktop chat, not a new surface, and
+    // adding one costs a house creative and a pinned rollup row.
+    expect(bySurface('cli_chat')).toBe(7)
     expect(bySurface('waiting_room')).toBe(4)
     expect(bySurface('freebuff_web_chat')).toBe(2)
     expect(bySurface('chat_assistant')).toBe(1)
   })
 
+  it('gives every slot a format, so no slot renders by guesswork', () => {
+    // The whole point of the column: a renderer asks the catalog how to draw
+    // a slot rather than pattern-matching its id. A slot with no format would
+    // fall through `placementFormat`'s conservative default and silently
+    // render inline, which for a break is a blank-looking card.
+    for (const slot of PLACEMENT_SLOTS) {
+      expect([slot.id, PLACEMENT_FORMATS.includes(slot.format)]).toEqual([
+        slot.id,
+        true,
+      ])
+    }
+  })
+
+  it('names the three sponsor breaks and leaves every other slot inline', () => {
+    const breaks = PLACEMENT_SLOTS.filter((slot) =>
+      isSponsorBreakPlacement(slot.id),
+    ).map((slot) => slot.id)
+    expect(breaks).toEqual([
+      'Desktop-Spotlight',
+      'Desktop-Showcase',
+      'Desktop-Intermission',
+    ])
+    expect(placementFormat('Desktop-Spotlight')).toBe('spotlight')
+    expect(placementFormat('Desktop-Showcase')).toBe('showcase')
+    expect(placementFormat('Desktop-Intermission')).toBe('intermission')
+    // Resolvable as slots, exactly like every other sellable id.
+    for (const id of breaks) expect(placementSurface(id)).toBe('cli_chat')
+    expect(SPONSOR_BREAK_FORMATS).toEqual([
+      'showcase',
+      'spotlight',
+      'intermission',
+    ])
+  })
+
+  it('answers inline for an id it does not know, never undefined', () => {
+    // The conservative direction. An unknown id guessed as a break would turn
+    // one typo into a full-screen interruption; guessed as inline it renders
+    // as the ordinary card it almost certainly is.
+    expect(placementFormat('CLI-Chat-Inline-3')).toBe('inline')
+    expect(placementFormat('some-future-grain')).toBe('inline')
+    expect(isSponsorBreakPlacement('some-future-grain')).toBe(false)
+  })
+
+  it('bounds break copy far below the inline lengths', () => {
+    // A break title renders at display size; inline-length copy does not
+    // shrink to fit, it overflows or truncates mid-word.
+    expect(SPONSOR_BREAK_CREATIVE_LIMITS).toEqual({
+      titleMaxLength: 28,
+      bodyMaxLength: 60,
+      ctaMaxLength: 18,
+    })
+    expect(SPONSOR_BREAK_HERO_SPEC.minWidth).toBe(1024)
+    expect(SPONSOR_BREAK_HERO_SPEC.minHeight).toBe(640)
+    // The floor is itself on-ratio, so the minimum acceptable image passes
+    // both gates rather than being rejected by the one it defines.
+    expect(
+      Math.abs(
+        SPONSOR_BREAK_HERO_SPEC.minWidth / SPONSOR_BREAK_HERO_SPEC.minHeight -
+          SPONSOR_BREAK_HERO_SPEC.aspectRatio,
+      ),
+    ).toBeLessThan(1e-9)
+  })
+
   it('gives every not-serving and underspend reason copy', () => {
     // Each of these is a state we can distinguish. Any reason without copy
     // would render an empty banner, which reads as "broken".

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

@@ -0,0 +1,209 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  ADS_BREAK_CLICKED_EVENT,
+  ADS_BREAK_CLOSED_EVENT,
+  ADS_BREAK_SHOWN_EVENT,
+  buildSponsorBreakEvent,
+  clampDwellMs,
+  isSponsorBreakCloseMethod,
+  readDwellMs,
+  SPONSOR_BREAK_ACCIDENTAL_CLICK_MS,
+  SPONSOR_BREAK_CLOSE_METHODS,
+  SPONSOR_BREAK_DWELL_MAX_MS,
+} from '../sponsor-break-events'
+
+import {
+  ADS_CLIENT_EVENT_HYGIENE_FIELDS,
+  ADS_SPONSOR_BREAK_FIELD_NAMES,
+  getAxiomOnlyLogEvent,
+} from '../../util/axiom-only-log'
+
+/**
+ * COD-453 item 6. Two things are guarded here: the payload builder is TOTAL
+ * (nothing a renderer sends can throw or reject), and the Axiom allowlist
+ * discards everything not on the contract -- these events are emitted from
+ * clients, so the allowlist is the only fence between a renderer and the
+ * dataset.
+ */
+describe('the break close vocabulary', () => {
+  test('is closed, and rejects anything outside it', () => {
+    for (const method of SPONSOR_BREAK_CLOSE_METHODS) {
+      expect(isSponsorBreakCloseMethod(method)).toBe(true)
+    }
+    for (const value of ['dismiss', 'X', '', null, undefined, 3, {}]) {
+      expect(isSponsorBreakCloseMethod(value)).toBe(false)
+    }
+  })
+
+  /**
+   * `escape` is deliberately not pooled with `x`: one is a considered exit and
+   * one is a reflex, and telling them apart is how a format learns whether it
+   * is being read or swatted.
+   */
+  test('keeps the reflex exits separate from the considered ones', () => {
+    expect(SPONSOR_BREAK_CLOSE_METHODS).toContain('x')
+    expect(SPONSOR_BREAK_CLOSE_METHODS).toContain('escape')
+    expect(SPONSOR_BREAK_CLOSE_METHODS).toContain('continue')
+    expect(SPONSOR_BREAK_CLOSE_METHODS).toContain('timer_then_continue')
+    expect(SPONSOR_BREAK_CLOSE_METHODS).toContain('thread_switch')
+  })
+})
+
+describe('clampDwellMs', () => {
+  test('clamps rather than rejecting, exactly like the render delay', () => {
+    expect(clampDwellMs(-5)).toBe(0)
+    expect(clampDwellMs(0)).toBe(0)
+    expect(clampDwellMs(1234.6)).toBe(1235)
+    expect(clampDwellMs('2000')).toBe(2000)
+    expect(clampDwellMs(9e9)).toBe(SPONSOR_BREAK_DWELL_MAX_MS)
+  })
+
+  /**
+   * Absent and unparseable are DELIBERATELY the same value, so nothing
+   * downstream can reconstruct a dwell from timestamps to fill the gap.
+   */
+  test('unknown is null, and is indistinguishable from absent', () => {
+    for (const value of [
+      undefined,
+      null,
+      '',
+      '   ',
+      'abc',
+      {},
+      NaN,
+      Infinity,
+    ]) {
+      expect(clampDwellMs(value)).toBeNull()
+    }
+    expect(readDwellMs(undefined, null, 'abc')).toBeNull()
+  })
+
+  test('reads the first candidate that clamps, so a header wins over a body', () => {
+    expect(readDwellMs('900', 100)).toBe(900)
+    expect(readDwellMs(null, 100)).toBe(100)
+  })
+
+  /**
+   * A one-hour ceiling rather than the render delay's day: a dwell of hours is
+   * a laptop that slept with the break open, which is real and common and
+   * whose value is meaningless. Clamping keeps the row in the denominator
+   * while stopping one suspended machine from owning the p90.
+   */
+  test('the dwell ceiling is far tighter than the render-delay ceiling', () => {
+    expect(SPONSOR_BREAK_DWELL_MAX_MS).toBe(3_600_000)
+    expect(SPONSOR_BREAK_ACCIDENTAL_CLICK_MS).toBe(300)
+  })
+})
+
+describe('buildSponsorBreakEvent', () => {
+  const base = {
+    placementId: 'Desktop-Spotlight',
+    surface: 'cli_chat',
+    format: 'spotlight',
+    arm: 'reduced_spotlight',
+  }
+
+  test('drops every unknown optional rather than emitting a sentinel', () => {
+    expect(buildSponsorBreakEvent(base)).toEqual({
+      placement_id: 'Desktop-Spotlight',
+      surface: 'cli_chat',
+      format: 'spotlight',
+      sponsor_break_arm: 'reduced_spotlight',
+      sample_rate: 1,
+    })
+  })
+
+  test('carries a full close event', () => {
+    expect(
+      buildSponsorBreakEvent({
+        ...base,
+        method: 'timer_then_continue',
+        dwellMs: 4200,
+        timerMs: 3000,
+        timerCompleted: true,
+        clientEventId: 'evt-123',
+        clientFamily: 'desktop',
+        campaignLabel: 'pilot-b',
+        creativeVersion: 3,
+        opportunityId: 'opp_1',
+      }),
+    ).toEqual({
+      placement_id: 'Desktop-Spotlight',
+      surface: 'cli_chat',
+      format: 'spotlight',
+      sponsor_break_arm: 'reduced_spotlight',
+      campaign_label: 'pilot-b',
+      creative_version: 3,
+      opportunity_id: 'opp_1',
+      method: 'timer_then_continue',
+      dwell_ms: 4200,
+      timer_ms: 3000,
+      timer_completed: true,
+      client_event_id: 'evt-123',
+      client_family: 'desktop',
+      sample_rate: 1,
+    })
+  })
+
+  test('a malformed method or event id is dropped, never emitted raw', () => {
+    const built = buildSponsorBreakEvent({
+      ...base,
+      method: 'made-up',
+      clientEventId: 'has spaces and is not a token',
+      dwellMs: 'nope',
+    })
+    expect(built.method).toBeUndefined()
+    expect(built.client_event_id).toBeUndefined()
+    expect(built.dwell_ms).toBeUndefined()
+  })
+})
+
+describe('the Axiom allowlist', () => {
+  const events = [
+    ADS_BREAK_SHOWN_EVENT,
+    ADS_BREAK_CLOSED_EVENT,
+    ADS_BREAK_CLICKED_EVENT,
+  ] as const
+
+  test('keeps the contract and discards everything else', () => {
+    for (const axiomEvent of events) {
+      expect(
+        getAxiomOnlyLogEvent({
+          axiomEvent,
+          placement_id: 'Desktop-Intermission',
+          surface: 'cli_chat',
+          format: 'intermission',
+          sponsor_break_arm: 'reduced_intermission',
+          dwell_ms: 5000,
+          method: 'continue',
+          client_family: 'desktop',
+          sample_rate: 1,
+          // None of these may ship: an id, a url, and free copy.
+          campaign_id: 'camp_secret',
+          userId: 'user-123',
+          landing_url: 'https://advertiser.example',
+          title: 'Buy our thing',
+        }),
+      ).toEqual({
+        event: axiomEvent,
+        data: {
+          placement_id: 'Desktop-Intermission',
+          surface: 'cli_chat',
+          format: 'intermission',
+          sponsor_break_arm: 'reduced_intermission',
+          dwell_ms: 5000,
+          method: 'continue',
+          client_family: 'desktop',
+          sample_rate: 1,
+        },
+      })
+    }
+  })
+
+  test('CI guard: the break allowlist carries the client hygiene fields', () => {
+    for (const field of ADS_CLIENT_EVENT_HYGIENE_FIELDS) {
+      expect(ADS_SPONSOR_BREAK_FIELD_NAMES).toContain(field)
+    }
+  })
+})