@posthog/core 1.49.2 → 1.50.1

package/src/utils/otlp-any-value.ts

@@ -0,0 +1,225 @@
+// The OTLP `AnyValue` encoder, shared by the logs, metrics and traces senders.
+//
+// Every value here comes from application code, so the encoder's job is to
+// produce a payload the ingestion service accepts no matter what it is handed.
+// A value the server refuses doesn't fail on its own — it 400s the whole
+// request, taking every other record in the batch with it.
+
+import type { OtlpAnyValue, OtlpKeyValue } from '@posthog/types'
+import type { Logger } from '../types'
+import { isArray, isBoolean, isNull, isNullish, isUndefined } from './type-utils'
+import {
+  CIRCULAR_VALUE,
+  FUNCTION_VALUE,
+  MAX_JSON_SAFE_VALUE_DEPTH,
+  MAX_JSON_SAFE_VALUE_ITEMS,
+  MAX_JSON_SAFE_VALUE_NODES,
+  sanitizeString,
+  TRUNCATED_VALUE,
+  UNSERIALIZABLE_VALUE,
+} from './json-utils'
+
+// 2^63 — one past int64 max.
+const INT64_RANGE_LIMIT = 9223372036854775808
+
+// The same bound for the bigint branch. A decimal string rather than a `n`
+// literal: this module reaches the browser bundle, which compiles to ES5, and
+// a bigint literal there is a syntax error rather than a runtime fallback.
+const INT64_RANGE_LIMIT_DECIMAL = '9223372036854775808'
+
+const propertyIsEnumerable = Object.prototype.propertyIsEnumerable
+
+interface EncodeState {
+  /** Containers on the current path, so a back-reference becomes a marker. */
+  ancestors: WeakSet<object>
+  remainingNodes: number
+}
+
+function newState(): EncodeState {
+  return { ancestors: new WeakSet(), remainingNodes: MAX_JSON_SAFE_VALUE_NODES }
+}
+
+export function toOtlpAnyValue(value: unknown, logger?: Logger): OtlpAnyValue {
+  try {
+    return encodeAnyValue(value, logger, newState(), 0)
+  } catch {
+    // Runs inside `captureLog`, the metrics flush and span encoding: an error
+    // escaping here surfaces in the caller's own code.
+    return { stringValue: UNSERIALIZABLE_VALUE }
+  }
+}
+
+export function toOtlpKeyValueList(attrs: Record<string, unknown>, logger?: Logger): OtlpKeyValue[] {
+  try {
+    return encodeKeyValueList(attrs, logger, newState(), 0)
+  } catch {
+    return []
+  }
+}
+
+function encodeBigInt(value: bigint, logger: Logger | undefined): OtlpAnyValue {
+  const decimal = value.toString()
+  const limit = BigInt(INT64_RANGE_LIMIT_DECIMAL)
+  if (value >= limit || value < -limit) {
+    logger?.debug(`Attribute ${decimal} is outside the int64 range; encoding it as a string`)
+    return { stringValue: decimal }
+  }
+  return { intValue: decimal }
+}
+
+function encodeAnyValue(value: unknown, logger: Logger | undefined, state: EncodeState, depth: number): OtlpAnyValue {
+  if (state.remainingNodes <= 0) {
+    return { stringValue: TRUNCATED_VALUE }
+  }
+  state.remainingNodes--
+
+  if (isBoolean(value)) {
+    return { boolValue: value }
+  }
+  // Reaching this branch proves BigInt exists, so the limit can be built here
+  // rather than at module load.
+  if (typeof value === 'bigint') {
+    return encodeBigInt(value, logger)
+  }
+  // typeof, not core's isNumber, which excludes NaN — proto3 JSON distinguishes
+  // a non-finite float from an ordinary string.
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      return { stringValue: String(value) }
+    }
+    if (Number.isInteger(value)) {
+      if (Number.isSafeInteger(value)) {
+        return { intValue: String(value) }
+      }
+      // Past MAX_SAFE_INTEGER only BigInt gives the double's exact decimal:
+      // `String(-(2**63))` lands 192 below int64 min, outside the field it is
+      // about to be parsed into. Without BigInt the value rides as a string,
+      // which is never range-checked.
+      if (typeof BigInt === 'undefined') {
+        return { stringValue: String(value) }
+      }
+      const decimal = BigInt(value).toString()
+      if (value >= INT64_RANGE_LIMIT || value < -INT64_RANGE_LIMIT) {
+        // An out-of-range intValue 400s the whole logs request; on the metrics
+        // path it is swallowed server-side and the metric just disappears.
+        logger?.debug(`Attribute ${decimal} is outside the int64 range; encoding it as a string`)
+        return { stringValue: decimal }
+      }
+      return { intValue: decimal }
+    }
+    return { doubleValue: value }
+  }
+  if (typeof value === 'string') {
+    return { stringValue: sanitizeString(value) }
+  }
+  // `String(value)` would put a function's source text on the wire.
+  if (typeof value === 'function') {
+    return { stringValue: FUNCTION_VALUE }
+  }
+  if (typeof value === 'symbol') {
+    return { stringValue: String(value) }
+  }
+  if (typeof value === 'object' && value !== null) {
+    if (state.ancestors.has(value)) {
+      return { stringValue: CIRCULAR_VALUE }
+    }
+    if (depth >= MAX_JSON_SAFE_VALUE_DEPTH) {
+      return { stringValue: TRUNCATED_VALUE }
+    }
+    if (value instanceof Date) {
+      const time = value.getTime()
+      const iso = Number.isFinite(time) ? value.toISOString() : String(value)
+      // An overridden toISOString can return a non-string, which the server
+      // refuses for the whole request.
+      return { stringValue: typeof iso === 'string' ? sanitizeString(iso) : String(iso) }
+    }
+    // Registered before the toJSON probe: a toJSON returning a structure that
+    // references its own object is a cycle like any other.
+    state.ancestors.add(value)
+    try {
+      // The representation a value defines for itself — dayjs, Decimal, an ORM
+      // document, and a cross-realm Date that fails the `instanceof` above.
+      try {
+        const toJSON = (value as { toJSON?: unknown }).toJSON
+        if (typeof toJSON === 'function') {
+          return encodeAnyValue(toJSON.call(value), logger, state, depth + 1)
+        }
+      } catch {
+        // A throwing toJSON falls through to the plain walk.
+      }
+      if (isArray(value)) {
+        return { arrayValue: { values: encodeArrayValues(value, logger, state, depth + 1) } }
+      }
+      return {
+        kvlistValue: {
+          values: encodeKeyValueList(value as Record<string, unknown>, logger, state, depth + 1),
+        },
+      }
+    } finally {
+      // Siblings that reference the same object are duplication, not a cycle.
+      state.ancestors.delete(value)
+    }
+  }
+  return { stringValue: sanitizeString(String(value)) }
+}
+
+function encodeArrayValues(
+  values: unknown[],
+  logger: Logger | undefined,
+  state: EncodeState,
+  depth: number
+): OtlpAnyValue[] {
+  const result: OtlpAnyValue[] = []
+  const itemCount = Math.min(values.length, MAX_JSON_SAFE_VALUE_ITEMS)
+  let index = 0
+  for (; index < itemCount && state.remainingNodes > 0; index++) {
+    try {
+      const element = index in values ? values[index] : undefined
+      // Dropped: proto3 JSON has no null AnyValue, and both `null` and `{}` here
+      // are rejected for the whole request.
+      if (isNullish(element)) {
+        continue
+      }
+      result.push(encodeAnyValue(element, logger, state, depth))
+    } catch {
+      result.push({ stringValue: UNSERIALIZABLE_VALUE })
+    }
+  }
+  if (values.length > index) {
+    result.push({ stringValue: TRUNCATED_VALUE })
+  }
+  return result
+}
+
+function encodeKeyValueList(
+  attrs: Record<string, unknown>,
+  logger: Logger | undefined,
+  state: EncodeState,
+  depth: number
+): OtlpKeyValue[] {
+  const result: OtlpKeyValue[] = []
+  for (const key in attrs) {
+    // for...in walks the prototype chain once own keys are exhausted. Skipped
+    // rather than broken out of: a proxy can yield keys in any order.
+    if (!propertyIsEnumerable.call(attrs, key)) {
+      continue
+    }
+    if (result.length >= MAX_JSON_SAFE_VALUE_ITEMS || state.remainingNodes <= 0) {
+      // Reported rather than written into the attributes: a synthetic key would
+      // land in the user's own namespace and could collide with a real one.
+      logger?.debug('Attributes truncated: the value exceeds the OTLP encoder budget')
+      break
+    }
+    try {
+      const value = attrs[key]
+      if (isNull(value) || isUndefined(value)) {
+        continue
+      }
+      result.push({ key: sanitizeString(key), value: encodeAnyValue(value, logger, state, depth) })
+    } catch {
+      // A getter that throws costs its own key, not the whole record.
+      result.push({ key: sanitizeString(key), value: { stringValue: UNSERIALIZABLE_VALUE } })
+    }
+  }
+  return result
+}

package/src/utils/otlp-resource.spec.ts

@@ -0,0 +1,125 @@
+import { buildResourceAttributes } from '../logs/logs-utils'
+import type { ResolvedPostHogLogsConfig } from '../logs/types'
+import { buildMetricsResourceAttributes } from '../metrics/metrics-utils'
+import type { ResolvedPostHogMetricsConfig } from '../metrics/types'
+import { normalizeOsName, osResourceAttributes } from './otlp-resource'
+
+const shared = {
+  serviceName: 'checkout',
+  serviceVersion: '2.1.0',
+  environment: 'production',
+  resourceAttributes: { 'host.name': 'web-01' },
+}
+
+const conflicting = {
+  serviceName: 'checkout',
+  serviceVersion: '2.1.0',
+  environment: 'production',
+  resourceAttributes: {
+    'service.name': 'hijacked',
+    'service.version': '0.0.0',
+    'deployment.environment': 'hijacked-env',
+    'telemetry.sdk.name': 'hijacked-sdk',
+    'telemetry.sdk.version': '0.0.0',
+    'host.name': 'web-01',
+  },
+}
+
+const bothSignals = (partial: object): Record<string, unknown>[] => [
+  buildResourceAttributes(partial as ResolvedPostHogLogsConfig, 'posthog-node', '1.0.0'),
+  buildMetricsResourceAttributes(partial as ResolvedPostHogMetricsConfig, 'posthog-node', '1.0.0'),
+]
+
+describe('shared OTLP resource attributes', () => {
+  it.each([
+    ['a fully populated config', shared],
+    ['a config with conflicting user attributes', conflicting],
+    ['an empty config', {}],
+  ])('produces the same attributes for logs and metrics given %s', (_label, config) => {
+    const [logs, metrics] = bothSignals(config)
+    expect(metrics).toEqual(logs)
+    expect(Object.keys(metrics)).toEqual(Object.keys(logs))
+  })
+
+  it('layers the identity keys over user resource attributes', () => {
+    for (const attributes of bothSignals(conflicting)) {
+      expect(attributes).toEqual({
+        'service.name': 'checkout',
+        'service.version': '2.1.0',
+        'deployment.environment': 'production',
+        'telemetry.sdk.name': 'posthog-node',
+        'telemetry.sdk.version': '1.0.0',
+        'host.name': 'web-01',
+      })
+    }
+  })
+
+  it('keeps user resource attributes that do not collide', () => {
+    for (const attributes of bothSignals(shared)) {
+      expect(attributes).toEqual({
+        'host.name': 'web-01',
+        'service.name': 'checkout',
+        'deployment.environment': 'production',
+        'service.version': '2.1.0',
+        'telemetry.sdk.name': 'posthog-node',
+        'telemetry.sdk.version': '1.0.0',
+      })
+    }
+  })
+
+  it('falls back to unknown_service and omits unset optional keys', () => {
+    for (const attributes of bothSignals({})) {
+      expect(attributes).toEqual({
+        'service.name': 'unknown_service',
+        'telemetry.sdk.name': 'posthog-node',
+        'telemetry.sdk.version': '1.0.0',
+      })
+    }
+  })
+})
+
+describe('osResourceAttributes', () => {
+  it.each([
+    // node:os platform() identifiers rather than os.name values
+    ['darwin', 'macOS'],
+    ['win32', 'Windows'],
+    ['linux', 'Linux'],
+    ['android', 'Android'],
+    ['freebsd', 'FreeBSD'],
+    // detectOS spellings
+    ['Mac OS X', 'macOS'],
+    ['iOS', 'iOS'],
+    ['Android', 'Android'],
+    ['Windows', 'Windows'],
+    ['Linux', 'Linux'],
+  ])('normalizes %s to %s', (raw, expected) => {
+    expect(normalizeOsName(raw)).toBe(expected)
+  })
+
+  it('passes an unmapped name through rather than dropping it', () => {
+    expect(normalizeOsName('Haiku')).toBe('Haiku')
+    expect(normalizeOsName('constructor')).toBe('constructor')
+  })
+
+  it.each([undefined, ''])('returns undefined for %p', (raw) => {
+    expect(normalizeOsName(raw)).toBeUndefined()
+  })
+
+  it('agrees with the names posthog-ios and posthog-android already send', () => {
+    // Both SDKs ship these values today; a divergence here splits one filter in two.
+    expect(normalizeOsName('darwin')).toBe('macOS')
+    expect(normalizeOsName('Mac OS X')).toBe('macOS')
+    expect(normalizeOsName('iOS')).toBe('iOS')
+    expect(normalizeOsName('Android')).toBe('Android')
+  })
+
+  it('omits either key rather than emitting it empty', () => {
+    expect(osResourceAttributes('darwin', undefined)).toEqual({ 'os.name': 'macOS' })
+    expect(osResourceAttributes(undefined, '14.0')).toEqual({ 'os.version': '14.0' })
+    expect(osResourceAttributes('', '')).toEqual({})
+    expect(osResourceAttributes('win32', '10.0.26100')).toEqual({
+      'os.name': 'Windows',
+      'os.version': '10.0.26100',
+    })
+  })
+})

package/src/utils/otlp-resource.ts

@@ -0,0 +1,89 @@
+/**
+ * Shape the logs and metrics resolved configs share for resource
+ * attribution. Generic over the attribute value type so each signal keeps its
+ * own value union.
+ */
+export interface OtlpResourceConfig<TAttributeValue> {
+  serviceName?: string
+  serviceVersion?: string
+  environment?: string
+  resourceAttributes?: Record<string, TAttributeValue>
+}
+
+/**
+ * OTLP resource attributes shared by the logs and metrics envelopes.
+ *
+ * User `resourceAttributes` are spread first, then SDK-controlled keys on top so
+ * a stray user key can't clobber the ingestion-attribution ones; the dedicated
+ * `serviceName` / `environment` / `serviceVersion` fields are how you override
+ * those three.
+ *
+ * @internal Shared within this SDK; not part of the stable public API.
+ */
+export function buildOtlpResourceAttributes<TAttributeValue>(
+  config: OtlpResourceConfig<TAttributeValue>,
+  sdkName: string,
+  sdkVersion: string
+): Record<string, TAttributeValue | string> {
+  return {
+    ...config.resourceAttributes,
+    'service.name': config.serviceName || 'unknown_service',
+    ...(config.environment && { 'deployment.environment': config.environment }),
+    ...(config.serviceVersion && { 'service.version': config.serviceVersion }),
+    'telemetry.sdk.name': sdkName,
+    'telemetry.sdk.version': sdkVersion,
+  }
+}
+
+/**
+ * OTLP `os.name` values, keyed by the spellings the JS SDKs detect natively:
+ * `node:os` `platform()` identifiers and the names `detectOS` reads out of a
+ * user agent.
+ *
+ * OpenTelemetry defines `os.name` as the human-readable OS name; the lowercase
+ * identifiers (`darwin`, `win32`) are `node:os` `platform()` values, not
+ * `os.name` values.
+ * The values match what `posthog-ios` and `posthog-android` send for the
+ * platforms they cover.
+ */
+const OS_NAMES: Record<string, string> = {
+  // node:os platform()
+  darwin: 'macOS',
+  win32: 'Windows',
+  linux: 'Linux',
+  android: 'Android',
+  freebsd: 'FreeBSD',
+  openbsd: 'OpenBSD',
+  sunos: 'SunOS',
+  aix: 'AIX',
+  // detectOS
+  'Mac OS X': 'macOS',
+}
+
+/**
+ * Normalizes a natively-detected OS name against the table above.
+ * Unrecognized names pass through: a wrong-looking value beats dropping an OS
+ * we have not mapped yet.
+ *
+ * @internal Shared within this SDK; not part of the stable public API.
+ */
+export function normalizeOsName(name: string | undefined): string | undefined {
+  if (!name) {
+    return undefined
+  }
+  return Object.prototype.hasOwnProperty.call(OS_NAMES, name) ? OS_NAMES[name] : name
+}
+
+/**
+ * The `os.name` / `os.version` resource attribute pair, with either key omitted
+ * rather than emitted empty when the host cannot determine it.
+ *
+ * @internal Exposed for cross-package use within this SDK; not part of the stable public API.
+ */
+export function osResourceAttributes(name: string | undefined, version: string | undefined): Record<string, string> {
+  const osName = normalizeOsName(name)
+  return {
+    ...(osName ? { 'os.name': osName } : {}),
+    ...(version ? { 'os.version': version } : {}),
+  }
+}

package/src/utils/user-agent-utils.ts

@@ -57,10 +57,16 @@ const DUCKDUCKGO = 'DuckDuckGo'
 const PALE_MOON = 'Pale Moon'
 const WATERFOX = 'Waterfox'
 const BRAVE = 'Brave'
+const CLAUDE = 'Claude'
+const CODEX = 'Codex'
+const CHATGPT = 'ChatGPT'
 const GOOGLE_SEARCH_APP = 'Google Search App'
 
 const BROWSER_VERSION_REGEX_SUFFIX = '(\\d+(\\.\\d+)?)'
 const DEFAULT_BROWSER_VERSION_REGEX = new RegExp('Version/' + BROWSER_VERSION_REGEX_SUFFIX)
+const AI_APP_VERSION_REGEX = new RegExp(
+  '(' + CLAUDE + '|' + CODEX + '|' + CHATGPT + ')\\/' + BROWSER_VERSION_REGEX_SUFFIX
+)
 
 /**
  * Hints from sources outside the User-Agent string. These let us identify Brave
@@ -82,10 +88,10 @@ function browserFromHints(hints: BrowserDetectionHints | undefined): string | nu
 }
 
 /**
- * Opt-in tweaks to UA-string detection. These change how existing traffic is
- * attributed, so the host SDK gates them (behind its `2026-05-30` config
- * defaults) rather than enabling them unconditionally — turning one on
- * reattributes browsers that were previously reported as something else.
+ * Opt-in tweaks to UA-string detection. Turning one on reattributes browsers
+ * that were previously reported as something else, so the host SDK gates
+ * shifts big enough to move users' metrics behind its `2026-05-30` config
+ * defaults. Smaller reattributions ship unconditionally in `detectBrowser`.
  */
 export interface BrowserDetectionOptions {
   // Surface the Google Search App as its own browser via its `GSA/` UA marker
@@ -181,8 +187,9 @@ export const detectBrowser = function (
   } else if (includes(user_agent, EDGE) || includes(user_agent, 'Edg/')) {
     return MICROSOFT_EDGE
   }
-  // Chromium forks that DO stamp themselves into the UA. These must be
-  // checked before Chrome because their UA also contains `Chrome/`.
+  // Chromium forks and Chromium-based apps that DO stamp themselves into the
+  // UA. These must be checked before Chrome because their UA also contains
+  // `Chrome/`.
   else if (includes(user_agent, VIVALDI + '/')) {
     return VIVALDI
   } else if (includes(user_agent, 'YaBrowser/')) {
@@ -191,6 +198,12 @@ export const detectBrowser = function (
     return WHALE
   } else if (includes(user_agent, DUCKDUCKGO + '/') || includes(user_agent, 'Ddg/')) {
     return DUCKDUCKGO
+  } else if (includes(user_agent, CLAUDE + '/')) {
+    return CLAUDE
+  } else if (includes(user_agent, CODEX + '/')) {
+    return CODEX
+  } else if (includes(user_agent, CHATGPT + '/')) {
+    return CHATGPT
   } else if (includes(user_agent, 'FBIOS')) {
     return FACEBOOK + ' ' + MOBILE
   } else if (includes(user_agent, 'UCWEB') || includes(user_agent, 'UCBrowser')) {
@@ -257,6 +270,9 @@ const versionRegexes: Record<string, RegExp[]> = {
   // Brave don't, which is why hint-based Brave detection returns a null
   // version: we have no UA marker to parse.
   [BRAVE]: [new RegExp(BRAVE + '\\/' + BROWSER_VERSION_REGEX_SUFFIX)],
+  [CLAUDE]: [AI_APP_VERSION_REGEX],
+  [CODEX]: [AI_APP_VERSION_REGEX],
+  [CHATGPT]: [AI_APP_VERSION_REGEX],
   // DuckDuckGo on iOS uses `Ddg/`, on Android/desktop preview it uses `DuckDuckGo/`.
   [DUCKDUCKGO]: [new RegExp('(DuckDuckGo|Ddg)\\/' + BROWSER_VERSION_REGEX_SUFFIX)],
   [PALE_MOON]: [new RegExp('PaleMoon\\/' + BROWSER_VERSION_REGEX_SUFFIX)],