Sync public snapshot from freebuff-private

Source: CodebuffAI/freebuff-private@3f383d858fd87cdf193bf51117ae23c9622ac097

Author: github-actions[bot]

common/src/constants/analytics-events.ts

@@ -9,6 +9,8 @@ export enum AnalyticsEvent {
   // per-surface DAU (filter on the `surface` property) and a combined DAU (no
   // filter). The `surface` property is one of: cli, web, chat, desktop, cloud
   // (web = the freebuff.com builder, cloud = connected-repo builder projects).
+  // Native sends additionally carry `client_platform: 'ios' | 'android'`;
+  // surface still describes the mode, and missing platform means unknown.
   // Emission points: cli client analytics; chat's stream route (server-side);
   // desktop's analytics module; web/cloud via the Convex send mutation
   // (PostHog + Axiom, both direct from Convex — see convex/analytics.ts).

common/src/util/__tests__/client-platform.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from 'bun:test'
+import { clientPlatformProperties } from '../client-platform'
+
+test('mobile attribution is per request and missing/invalid origins stay unknown', () => {
+  expect(clientPlatformProperties('ios')).toEqual({ client_platform: 'ios' })
+  expect(clientPlatformProperties('android')).toEqual({ client_platform: 'android' })
+  for (const value of [undefined, null, '', 'browser', 'ios, android', {}, 1]) {
+    expect(clientPlatformProperties(value)).toEqual({})
+  }
+  expect(clientPlatformProperties('ios')).toEqual({ client_platform: 'ios' })
+})

common/src/util/client-platform.ts

@@ -0,0 +1,11 @@
+/** Request origin, independent of the product surface (chat/cloud/desktop).
+ * Optional for older clients; never infer a browser from missing metadata.
+ * Analytics only: client-supplied attribution is not an authorization signal.
+ */
+export type MobileClientPlatform = 'ios' | 'android'
+
+export function clientPlatformProperties(
+  value: unknown,
+): { client_platform?: MobileClientPlatform } {
+  return value === 'ios' || value === 'android' ? { client_platform: value } : {}
+}