Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@5a2a97d0f4016c91c8d8ee0f8a85d7aba237e75d

Author: github-actions[bot]

bun.lock

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test'
+
+import { adSignalsAllowed, readAdSignalsConsent } from '../android-ad-signals'
+
+describe('adSignalsAllowed', () => {
+  test('outside the region, collected unless denied', () => {
+    expect(adSignalsAllowed({ country: 'US', consent: 'unknown' })).toBe(true)
+    expect(adSignalsAllowed({ country: 'us', consent: 'unknown' })).toBe(true)
+    expect(adSignalsAllowed({ country: 'US', consent: 'denied' })).toBe(false)
+  })
+
+  test('inside the region or unresolved, only granted collects', () => {
+    for (const country of ['FR', 'GB', 'CH', 'IS', null, '']) {
+      expect(adSignalsAllowed({ country, consent: 'unknown' })).toBe(false)
+      expect(adSignalsAllowed({ country, consent: 'granted' })).toBe(true)
+    }
+  })
+
+  test('the header reads only the two explicit choices', () => {
+    expect(readAdSignalsConsent('Granted ')).toBe('granted')
+    expect(readAdSignalsConsent('denied')).toBe('denied')
+    expect(readAdSignalsConsent('yes')).toBe('unknown')
+    expect(readAdSignalsConsent(null)).toBe('unknown')
+  })
+})

common/src/ads/__tests__/android-ad-signals.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The consent rule for the Android app's extra ad signals: the bucketed
+ * `client_context` it sends with an auction and the `landing` block of its
+ * engagement record. Serving an ad and counting its impression and click are
+ * not covered by this rule; they run for everyone.
+ *
+ * Outside the EEA, the UK and Switzerland the signals are collected without a
+ * prompt (disclosed in the Play Data Safety form and the privacy policy).
+ * Inside them, reading device state for advertising needs the user's consent
+ * (ePrivacy Art. 5(3)), so the app asks once and sends nothing until the user
+ * agrees. An unresolved country counts as inside: not knowing where someone
+ * is is not a basis for collecting.
+ *
+ * The app applies the rule before it reads anything; the server applies it
+ * again by the edge's country, so an old build or a wrong SIM hint cannot
+ * store what the rule forbids.
+ */
+
+/** The app's report of the user's choice. Absent means `unknown`. */
+export const AD_SIGNALS_CONSENT_HEADER = 'x-freebuff-ad-signals'
+export const AD_SIGNALS_CONSENT_VALUES = [
+  'granted',
+  'denied',
+  'unknown',
+] as const
+export type AdSignalsConsent = (typeof AD_SIGNALS_CONSENT_VALUES)[number]
+
+/**
+ * EEA (27) + the EFTA members of the EEA (IS, LI, NO) + UK + CH, ISO 3166-1
+ * alpha-2 upper case. The same set the placements identity match gates on
+ * (`IDENTITY_GATED_COUNTRIES`); kept here because `common` cannot import the
+ * web app.
+ */
+export const AD_SIGNALS_CONSENT_COUNTRIES: ReadonlySet<string> = new Set([
+  'AT',
+  'BE',
+  'BG',
+  'HR',
+  'CY',
+  'CZ',
+  'DK',
+  'EE',
+  'FI',
+  'FR',
+  'DE',
+  'GR',
+  'HU',
+  'IE',
+  'IT',
+  'LV',
+  'LT',
+  'LU',
+  'MT',
+  'NL',
+  'PL',
+  'PT',
+  'RO',
+  'SK',
+  'SI',
+  'ES',
+  'SE',
+  'IS',
+  'LI',
+  'NO',
+  'GB',
+  'CH',
+])
+
+export function readAdSignalsConsent(
+  value: string | null | undefined,
+): AdSignalsConsent {
+  const normalized = value?.trim().toLowerCase()
+  return normalized === 'granted' || normalized === 'denied'
+    ? normalized
+    : 'unknown'
+}
+
+/**
+ * Whether the extra signals may be collected and stored. A `denied` choice is
+ * honoured everywhere; inside the consent region (or with no country) only
+ * `granted` allows them.
+ */
+export function adSignalsAllowed(params: {
+  country: string | null | undefined
+  consent: AdSignalsConsent
+}): boolean {
+  if (params.consent === 'denied') return false
+  if (params.consent === 'granted') return true
+  const country = params.country?.trim().toUpperCase()
+  if (!country) return false
+  return !AD_SIGNALS_CONSENT_COUNTRIES.has(country)
+}

common/src/ads/android-ad-signals.ts

@@ -0,0 +1,16 @@
+/** Native inventory has its own attribution; never alias it to a web or iOS slot. */
+export const ANDROID_AD_SURFACE = 'android' as const
+export const ANDROID_AD_PLACEMENTS = [
+  {
+    id: 'Android-Chat-After-Assistant-Message',
+    label: 'Chat · after an answer',
+  },
+  {
+    id: 'Android-Coding-After-Assistant-Message',
+    label: 'Coding · after an answer',
+  },
+] as const
+
+export function isAndroidAdPlacement(id: string | null | undefined): boolean {
+  return ANDROID_AD_PLACEMENTS.some((slot) => slot.id === id)
+}

common/src/ads/android-placements.ts

@@ -0,0 +1,17 @@
+import { isAndroidAdPlacement } from './android-placements'
+import { isIOSAdPlacement } from './ios-placements'
+
+export type MobileAdSurface = 'ios' | 'android'
+
+/** The native app that owns a placement, or null for every web/desktop slot. */
+export function mobileAdPlacementSurface(
+  id: string | null | undefined,
+): MobileAdSurface | null {
+  if (isIOSAdPlacement(id)) return 'ios'
+  if (isAndroidAdPlacement(id)) return 'android'
+  return null
+}
+
+export function isMobileAdPlacement(id: string | null | undefined): boolean {
+  return mobileAdPlacementSurface(id) !== null
+}

common/src/ads/mobile-placements.ts

@@ -172,7 +172,7 @@ describe('house ad catalog', () => {
     expect(HOUSE_AD_DISPLAY_CREATIVE).toBe(HOUSE_AD_DISPLAY_VARIATIONS[0]!)
   })
 
-  test('every sellable surface has house copy except the explicit iOS opt-out', () => {
+  test('every sellable surface has house copy except the explicit phone opt-outs', () => {
     // The seed script groups slots by surface and skips a surface it has no
     // creatives for. Without this, adding a slot on a new surface would leave
     // that surface out of the campaign silently -- the run would report
@@ -183,9 +183,9 @@ describe('house ad catalog', () => {
       ),
     )
     for (const surface of surfacesWithSlots) {
-      // iOS deliberately has no automatic subscription promotion or seeded
-      // house campaign. Mobile inventory requires a separate, explicit rollout.
-      if (surface === 'ios') {
+      // The phones deliberately have no automatic subscription promotion or
+      // seeded house campaign. Mobile inventory is an explicit campaign choice.
+      if (surface === 'ios' || surface === 'android') {
         expect(Object.hasOwn(HOUSE_AD_VARIATIONS, surface)).toBe(false)
         continue
       }

common/src/constants/__tests__/freebuff-house-ad.test.ts

@@ -19,6 +19,10 @@ import {
 
 import { AD_CAMPAIGN_STATUSES } from './freebuff-ads'
 import { IOS_AD_PLACEMENTS, IOS_AD_SURFACE } from '../ads/ios-placements'
+import {
+  ANDROID_AD_PLACEMENTS,
+  ANDROID_AD_SURFACE,
+} from '../ads/android-placements'
 
 import type { AdCampaignStatus } from './freebuff-ads'
 
@@ -266,6 +270,12 @@ const ORIGINAL_PLACEMENT_SLOTS = [
     available: true,
     format: 'inline' as const,
   })),
+  ...ANDROID_AD_PLACEMENTS.map(({ id }) => ({
+    id,
+    surface: ANDROID_AD_SURFACE,
+    available: true,
+    format: 'inline' as const,
+  })),
   {
     id: 'waiting-room-1',
     surface: 'waiting_room',

common/src/constants/freebuff-placements.ts

@@ -712,3 +712,39 @@ describe('wave 2 collector helpers', () => {
     expect(gpuVendorOf('0x5143')).toBe('qualcomm')
   })
 })
+
+describe('Android fields', () => {
+  test('a full android block parses', () => {
+    const android = {
+      powerSave: false,
+      charging: true,
+      battery: '50-80',
+      dataSaver: false,
+      metered: true,
+      orientation: 'portrait',
+      windowClass: 'compact',
+      multiWindow: false,
+      keyboard: true,
+      hardwareKeyboard: false,
+      entry: 'notification',
+      installSource: 'play',
+      standby: 'active',
+      notifications: true,
+      lowRam: false,
+      fontScale: '1',
+    }
+    expect(parseAdClientContext({ v: 1, android })?.android).toEqual(android)
+  })
+
+  test('an unknown android value drops the whole context', () => {
+    expect(parseAdClientContext({ v: 1, android: { entry: 'widget' } })).toBeUndefined()
+  })
+
+  test('landing parses and is bounded', () => {
+    const base = { v: 1, impUrl: 'https://freebuff.com/api/ads/first-party/impression/x' }
+    const landing = { source: 'custom_tabs', loaded: true, loadMs: 800, maxScrollPct: 75, interacted: false, visibleMs: 30_000 }
+    expect(parseAdEngagement({ ...base, landing })?.landing).toEqual(landing)
+    expect(parseAdEngagement({ ...base, landing: { maxScrollPct: 101 } })).toBeUndefined()
+    expect(parseAdEngagement({ ...base, landing: { source: 'webview' } })).toBeUndefined()
+  })
+})

common/src/types/__tests__/ad-client-context.test.ts

@@ -239,6 +239,24 @@ export const EDIT_RATIO_BUCKETS = ['<5%', '5-15%', '15-30%', '30%+'] as const
 /** rendered ad card size, CSS pixels */
 export const CARD_DIMENSION_BUCKETS = ['<120', '120-300', '300-600', '600+'] as const
 
+// Android. Only values the app reads without a runtime permission, and never one that names the device: no
+// advertising id, installed-app list, usage stats, location, sensors or accessibility state
+// (docs/freebuff-android.md, "Ad signals").
+export const BATTERY_BUCKETS = ['<15', '15-50', '50-80', '80+'] as const
+export const ORIENTATIONS = ['portrait', 'landscape'] as const
+/** Material window size class of the app window, by width */
+export const WINDOW_CLASSES = ['compact', 'medium', 'expanded'] as const
+/** what brought the app to the foreground for this session */
+export const ANDROID_ENTRIES = ['launcher', 'notification', 'share', 'deep_link', 'recents', 'other'] as const
+/** who installed the app (`PackageManager.getInstallSourceInfo`), classified; never the raw package name */
+export const INSTALL_SOURCES = ['play', 'other_store', 'sideload', 'unknown'] as const
+/** `UsageStatsManager.getAppStandbyBucket()` for our own app: how engaged the OS thinks the user is with Freebuff */
+export const STANDBY_BUCKETS = ['active', 'working_set', 'frequent', 'rare', 'restricted', 'other'] as const
+export const FONT_SCALE_BUCKETS = ['<1', '1', '1-1.3', '1.3+'] as const
+
+/** Where a post-click landing measurement came from. */
+export const LANDING_SOURCES = ['custom_tabs'] as const
+
 /**
  * Developer-tool vendors whose adoption after a click is recorded (`postClick.packageInstalled` / `mcpAdded`). A
  * package or MCP server outside this list is never reported, only whether it matched the clicked ad's vendor.
@@ -450,6 +468,31 @@ export const adClientContextSchema = z.object({
     })
     .partial()
     .optional(),
+  /** Android app only. Device-wide facts reuse `sys`, `net`, `ui`, `app` and `attn`; these have no other home. */
+  android: z
+    .object({
+      powerSave: z.boolean(),
+      charging: z.boolean(),
+      battery: z.enum(BATTERY_BUCKETS),
+      /** Data Saver restricts this app's background data */
+      dataSaver: z.boolean(),
+      metered: z.boolean(),
+      orientation: z.enum(ORIENTATIONS),
+      windowClass: z.enum(WINDOW_CLASSES),
+      /** split screen, freeform or picture-in-picture */
+      multiWindow: z.boolean(),
+      /** the soft keyboard is showing, which covers the lower part of the transcript */
+      keyboard: z.boolean(),
+      hardwareKeyboard: z.boolean(),
+      entry: z.enum(ANDROID_ENTRIES),
+      installSource: z.enum(INSTALL_SOURCES),
+      standby: z.enum(STANDBY_BUCKETS),
+      notifications: z.boolean(),
+      lowRam: z.boolean(),
+      fontScale: z.enum(FONT_SCALE_BUCKETS),
+    })
+    .partial()
+    .optional(),
   /** web only */
   web: z
     .object({
@@ -532,6 +575,29 @@ export const adEngagementSchema = z.object({
     })
     .partial()
     .optional(),
+  /**
+   * What happened on the advertiser's page after the click, as the in-app browser reports it (Android Custom Tabs
+   * navigation and engagement callbacks). Scroll depth and interaction only, never page content or URLs. Its own key
+   * rather than part of `postClick`, so the EEA/UK consent rule can drop it whole.
+   */
+  landing: z
+    .object({
+      source: z.enum(LANDING_SOURCES),
+      /** the page finished loading */
+      loaded: z.boolean(),
+      /** the page failed to load */
+      failed: z.boolean(),
+      /** ms from the click until the page finished loading */
+      loadMs: ms,
+      /** deepest scroll reached, percent of the page */
+      maxScrollPct: z.number().int().min(0).max(100),
+      /** the user tapped or typed on the page */
+      interacted: z.boolean(),
+      /** ms the page was open before the user left it */
+      visibleMs: ms,
+    })
+    .partial()
+    .optional(),
   postClick: z
     .object({
       /** the window blurred after the click, i.e. the external browser actually took focus */