Sync public snapshot from freebuff-private

github-actions[bot] · github-actions[bot] · commit 71677145b57c · 2026-07-04T22:56:28.000Z
Source: CodebuffAI/freebuff-private@0d342808d8c6c43c7e7560419eacebd59b3d1b11
diff --git a/common/src/constants/analytics-events.ts b/common/src/constants/analytics-events.ts
@@ -251,7 +251,12 @@ export enum AnalyticsEvent {
   FREEBUFF_REDDIT_FUNNEL_CLI_INSTALLED = 'freebuff.reddit_funnel.cli_installed',
   FREEBUFF_REDDIT_FUNNEL_LOGIN = 'freebuff.reddit_funnel.login',
   FREEBUFF_REDDIT_FUNNEL_SIGN_UP = 'freebuff.reddit_funnel.sign_up',
-  FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT = 'freebuff.reddit_funnel.first_prompt',
+  FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT_CLI = 'freebuff.reddit_funnel.first_prompt_cli',
+  FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT_WEB = 'freebuff.reddit_funnel.first_prompt_web',
+  FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT_CHAT = 'freebuff.reddit_funnel.first_prompt_chat',
+  FREEBUFF_REDDIT_FUNNEL_RETENTION_1D_CLI = 'freebuff.reddit_funnel.retention_1d_cli',
+  FREEBUFF_REDDIT_FUNNEL_RETENTION_7D_CLI = 'freebuff.reddit_funnel.retention_7d_cli',
+  FREEBUFF_REDDIT_FUNNEL_RETENTION_24D_CLI = 'freebuff.reddit_funnel.retention_24d_cli',
   FREEBUFF_REDDIT_FUNNEL_GRAVITY_AD_CLICK = 'freebuff.reddit_funnel.gravity_ad_click',
 
   // Freebuff web /chat ads experiment (server-rendered Gravity ads vs the
diff --git a/common/src/reddit-capi.ts b/common/src/reddit-capi.ts
@@ -0,0 +1,175 @@
+import { createHash } from 'node:crypto'
+
+import { IS_PROD } from '@codebuff/common/env'
+import { extractClientIp } from '@codebuff/common/util/rate-limit'
+import type { Logger } from '@codebuff/common/types/contracts/logger'
+import type {
+  RedditFirstPromptCapiEventName,
+  RedditRetentionCapiEventName,
+} from '@codebuff/common/util/reddit-capi-events'
+
+export type { RedditFirstPromptCapiEventName, RedditRetentionCapiEventName }
+
+/** Reddit Ads pixel ID (public, also used for CAPI endpoint). */
+export const REDDIT_PIXEL_ID = 'a2_j6o59svbxzzn'
+
+const REDDIT_CAPI_ENDPOINT = `https://ads-api.reddit.com/api/v3/pixels/${REDDIT_PIXEL_ID}/conversion_events`
+
+export type RedditActionSource = 'WEBSITE' | 'APP' | 'PHYSICAL_STORE' | 'OTHER'
+
+export type RedditCapiUser = {
+  email?: string | null
+  externalId?: string | null
+  ipAddress?: string | null
+  userAgent?: string | null
+  clickId?: string | null
+  uuid?: string | null
+}
+
+export type RedditCapiCustomEvent =
+  | RedditFirstPromptCapiEventName
+  | RedditRetentionCapiEventName
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function normalizeEmail(email: string): string {
+  return email.trim().toLowerCase()
+}
+
+function buildUserPayload(user: RedditCapiUser) {
+  const payload: Record<string, string> = {}
+
+  if (user.email) {
+    payload.email = sha256(normalizeEmail(user.email))
+  }
+  if (user.externalId) {
+    payload.external_id = sha256(user.externalId.trim())
+  }
+  if (user.ipAddress) {
+    payload.ip_address = user.ipAddress
+  }
+  if (user.userAgent) {
+    payload.user_agent = user.userAgent
+  }
+  if (user.clickId) {
+    payload.click_id = user.clickId
+  }
+  if (user.uuid) {
+    payload.uuid = user.uuid
+  }
+
+  return Object.keys(payload).length > 0 ? payload : undefined
+}
+
+export type SendRedditCustomConversionParams = {
+  /** Conversion access token from Reddit Events Manager (env-provided; no-op when unset). */
+  accessToken: string | undefined
+  customEventName: RedditCapiCustomEvent
+  conversionId: string
+  actionSource: RedditActionSource
+  eventSourceUrl?: string
+  user: RedditCapiUser
+  fetchImpl?: typeof fetch
+  logger?: Logger
+}
+
+/** Fire-and-forget Reddit Conversions API custom event. Never throws. */
+export async function sendRedditCustomConversion(
+  params: SendRedditCustomConversionParams,
+): Promise<void> {
+  if (!IS_PROD || !params.accessToken) {
+    return
+  }
+
+  const fetchImpl = params.fetchImpl ?? fetch
+  const eventAt = Date.now()
+  const user = buildUserPayload(params.user)
+
+  const body = {
+    data: {
+      events: [
+        {
+          event_at: eventAt,
+          action_source: params.actionSource,
+          ...(params.eventSourceUrl
+            ? { event_source_url: params.eventSourceUrl }
+            : {}),
+          type: {
+            tracking_type: 'CUSTOM',
+            custom_event_name: params.customEventName,
+          },
+          ...(params.user.clickId ? { click_id: params.user.clickId } : {}),
+          metadata: {
+            conversion_id: params.conversionId,
+          },
+          ...(user ? { user } : {}),
+        },
+      ],
+      partner: 'FREEBUFF',
+      partner_version: '1.0.0',
+    },
+  }
+
+  try {
+    const response = await fetchImpl(REDDIT_CAPI_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${params.accessToken}`,
+        'Content-Type': 'application/json',
+        'User-Agent': 'freebuff/1.0 (reddit-capi)',
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(3_000),
+    })
+    if (!response.ok) {
+      params.logger?.warn(
+        {
+          status: response.status,
+          responseBody: (await response.text().catch(() => '')).slice(0, 500),
+          customEventName: params.customEventName,
+          conversionId: params.conversionId,
+        },
+        'Reddit CAPI rejected conversion event',
+      )
+    }
+  } catch (error) {
+    // Best-effort ad attribution; never block product flows.
+    params.logger?.warn(
+      {
+        error,
+        customEventName: params.customEventName,
+        conversionId: params.conversionId,
+      },
+      'Reddit CAPI conversion request failed',
+    )
+  }
+}
+
+export function redditConversionId(
+  event: RedditCapiCustomEvent,
+  userId: string,
+  suffix?: string,
+): string {
+  return [event.toLowerCase(), userId, suffix ?? String(Date.now())].join('_')
+}
+
+/**
+ * Identity fields shared by every server-side Reddit conversion call, built
+ * from the incoming request's headers. Surface-specific attribution (click id,
+ * uuid) is layered on by callers that have it.
+ */
+export function redditUserFromRequestHeaders(params: {
+  userId: string
+  email?: string | null
+  headers: { get(name: string): string | null }
+}): RedditCapiUser {
+  const ip = extractClientIp(params.headers)
+  return {
+    email: params.email,
+    externalId: params.userId,
+    ipAddress: ip === 'unknown' ? undefined : ip,
+    userAgent: params.headers.get('user-agent')?.trim() || undefined,
+  }
+}
diff --git a/common/src/util/__tests__/reddit-freebuff-retention.test.ts b/common/src/util/__tests__/reddit-freebuff-retention.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, test } from 'bun:test'
+
+import {
+  getFreebuffRetentionMilestonesToFire,
+  isFirstFreebuffPrompt,
+  planFreebuffRedditConversionEvents,
+} from '@codebuff/common/util/reddit-freebuff-retention'
+
+describe('isFirstFreebuffPrompt', () => {
+  test('returns true on first-ever usage day', () => {
+    expect(
+      isFirstFreebuffPrompt({
+        previousUsageDays: [],
+        newUsageDayRecorded: true,
+      }),
+    ).toBe(true)
+  })
+
+  test('returns false on repeat prompts same day', () => {
+    expect(
+      isFirstFreebuffPrompt({
+        previousUsageDays: ['2026-06-30'],
+        newUsageDayRecorded: false,
+      }),
+    ).toBe(false)
+  })
+
+  test('returns false on a later usage day', () => {
+    expect(
+      isFirstFreebuffPrompt({
+        previousUsageDays: ['2026-06-30'],
+        newUsageDayRecorded: true,
+      }),
+    ).toBe(false)
+  })
+})
+
+describe('getFreebuffRetentionMilestonesToFire', () => {
+  test('returns nothing on first-ever usage day', () => {
+    expect(
+      getFreebuffRetentionMilestonesToFire({
+        previousUsageDays: [],
+        todayDateKey: '2026-06-30',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual([])
+  })
+
+  test('returns nothing when no new usage day was recorded', () => {
+    expect(
+      getFreebuffRetentionMilestonesToFire({
+        previousUsageDays: ['2026-06-30'],
+        todayDateKey: '2026-07-01',
+        newUsageDayRecorded: false,
+      }),
+    ).toEqual([])
+  })
+
+  test('fires 1d retention on day 1', () => {
+    expect(
+      getFreebuffRetentionMilestonesToFire({
+        previousUsageDays: ['2026-06-30'],
+        todayDateKey: '2026-07-01',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual([1])
+  })
+
+  test('does not repeat 1d on day 2', () => {
+    expect(
+      getFreebuffRetentionMilestonesToFire({
+        previousUsageDays: ['2026-06-30', '2026-07-01'],
+        todayDateKey: '2026-07-02',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual([])
+  })
+
+  test('fires 7d retention on day 7', () => {
+    expect(
+      getFreebuffRetentionMilestonesToFire({
+        previousUsageDays: ['2026-06-30', '2026-07-01'],
+        todayDateKey: '2026-07-07',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual([7])
+  })
+
+  test('fires 1d, 7d, and 24d when user returns after a long gap', () => {
+    expect(
+      getFreebuffRetentionMilestonesToFire({
+        previousUsageDays: ['2026-06-01'],
+        todayDateKey: '2026-07-01',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual([1, 7, 24])
+  })
+})
+
+describe('planFreebuffRedditConversionEvents', () => {
+  test('first prompt only on day 0', () => {
+    expect(
+      planFreebuffRedditConversionEvents({
+        previousUsageDays: [],
+        todayDateKey: '2026-06-30',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual({ fireFirstPrompt: true, retentionMilestones: [] })
+  })
+
+  test('1d retention without first prompt on day 1', () => {
+    expect(
+      planFreebuffRedditConversionEvents({
+        previousUsageDays: ['2026-06-30'],
+        todayDateKey: '2026-07-01',
+        newUsageDayRecorded: true,
+      }),
+    ).toEqual({ fireFirstPrompt: false, retentionMilestones: [1] })
+  })
+})
diff --git a/common/src/util/reddit-capi-events.ts b/common/src/util/reddit-capi-events.ts
@@ -0,0 +1,44 @@
+import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
+
+import type { FreebuffRedditRetentionMilestoneDays } from '@codebuff/common/util/reddit-freebuff-retention'
+
+export type RedditFirstPromptSurface = 'cli' | 'web' | 'chat'
+
+/** PostHog/analytics event fired alongside the Reddit CAPI first-prompt conversion. */
+export const REDDIT_FIRST_PROMPT_ANALYTICS_EVENTS: Record<
+  RedditFirstPromptSurface,
+  AnalyticsEvent
+> = {
+  cli: AnalyticsEvent.FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT_CLI,
+  web: AnalyticsEvent.FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT_WEB,
+  chat: AnalyticsEvent.FREEBUFF_REDDIT_FUNNEL_FIRST_PROMPT_CHAT,
+}
+
+export type RedditFirstPromptCapiEventName =
+  | 'FirstPromptCli'
+  | 'FirstPromptWeb'
+  | 'FirstPromptChat'
+
+export type RedditRetentionCapiEventName =
+  | 'Retention1dCli'
+  | 'Retention7dCli'
+  | 'Retention24dCli'
+
+export function redditFirstPromptCapiEventName(
+  surface: RedditFirstPromptSurface,
+): RedditFirstPromptCapiEventName {
+  switch (surface) {
+    case 'cli':
+      return 'FirstPromptCli'
+    case 'web':
+      return 'FirstPromptWeb'
+    case 'chat':
+      return 'FirstPromptChat'
+  }
+}
+
+export function redditRetentionCapiEventName(
+  milestone: FreebuffRedditRetentionMilestoneDays,
+): RedditRetentionCapiEventName {
+  return `Retention${milestone}dCli`
+}
diff --git a/common/src/util/reddit-freebuff-retention.ts b/common/src/util/reddit-freebuff-retention.ts
