@posthog/core 1.27.9 → 1.28.0

package/src/posthog-core-stateless.ts

@@ -1,3 +1,4 @@
+import type { OtlpLogsPayload } from '@posthog/types'
 import { SimpleEventEmitter } from './eventemitter'
 import { getFeatureFlagValue, normalizeFlagsResponse } from './featureFlagUtils'
 import { gzipCompress, isGzipSupported } from './gzip'
@@ -94,6 +95,23 @@ function isPostHogFetchContentTooLargeError(err: unknown): err is PostHogFetchHt
   return typeof err === 'object' && err instanceof PostHogFetchHttpError && err.status === 413
 }
 
+/**
+ * Outcome of a logs batch send. Keeps HTTP error classification inside core
+ * (single source of truth — same policy events already use in `_flush()`) so
+ * PostHogLogs doesn't need to know about specific error types.
+ *
+ *   - ok            → records are accepted; drop them from the queue
+ *   - too-large     → 413; caller should halve batch size and retry same records
+ *   - retry-later   → network error; caller keeps records and retries next cycle
+ *   - fatal         → anything else (auth, malformed, etc.); caller drops the
+ *                     batch and surfaces the error
+ */
+export type SendLogsBatchOutcome =
+  | { kind: 'ok' }
+  | { kind: 'too-large' }
+  | { kind: 'retry-later'; error: unknown }
+  | { kind: 'fatal'; error: unknown }
+
 export enum QuotaLimitedFeature {
   FeatureFlags = 'feature_flags',
   Recordings = 'recordings',
@@ -1179,6 +1197,52 @@ export abstract class PostHogCoreStateless {
     this._events.emit('flush', sentMessages)
   }
 
+  /**
+   * Sends a pre-built OTLP logs payload to `/i/v1/logs`. Returns a tagged
+   * outcome instead of throwing so PostHogLogs doesn't have to know about the
+   * core's error class hierarchy. Error classification lives here (single
+   * source of truth, same policy the events `_flush()` uses for its own
+   * 413 / network / fatal handling).
+   *
+   * 413 is passed through as `too-large` (not auto-retried) so the caller can
+   * shrink `maxBatchRecordsPerPost` and retry the same records.
+   */
+  async _sendLogsBatch(payload: OtlpLogsPayload): Promise<SendLogsBatchOutcome> {
+    const serialized = JSON.stringify(payload)
+    const url = `${this.host}/i/v1/logs?token=${encodeURIComponent(this.apiKey)}`
+
+    const gzippedPayload = !this.disableCompression ? await gzipCompress(serialized, this.isDebug) : null
+    const fetchOptions: PostHogFetchOptions = {
+      method: 'POST',
+      headers: {
+        ...this.getCustomHeaders(),
+        'Content-Type': 'application/json',
+        ...(gzippedPayload !== null && { 'Content-Encoding': 'gzip' }),
+      },
+      body: gzippedPayload || serialized,
+    }
+
+    try {
+      await this.fetchWithRetry(url, fetchOptions, {
+        retryCheck: (err) => {
+          if (isPostHogFetchContentTooLargeError(err)) {
+            return false
+          }
+          return isPostHogFetchError(err)
+        },
+      })
+      return { kind: 'ok' }
+    } catch (err) {
+      if (isPostHogFetchContentTooLargeError(err)) {
+        return { kind: 'too-large' }
+      }
+      if (err instanceof PostHogFetchNetworkError) {
+        return { kind: 'retry-later', error: err }
+      }
+      return { kind: 'fatal', error: err }
+    }
+  }
+
   private async fetchWithRetry(
     url: string,
     options: PostHogFetchOptions,

package/src/surveys/events.spec.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  buildSurveyResponseProperties,
+  getSurveyInteractionProperty,
+  getSurveyResponseKey,
+  getSurveyResponseValue,
+  surveyHasResponses,
+} from './events'
+
+describe('survey event helpers', () => {
+  const survey = {
+    id: 'survey-1',
+    current_iteration: 2,
+    questions: [
+      { id: 'q1', question: 'Rate us', originalQuestionIndex: 0 },
+      { id: 'q2', question: 'Anything else?', originalQuestionIndex: 1 },
+    ],
+  }
+
+  it('builds response properties with current and legacy response keys', () => {
+    const responses = {
+      [getSurveyResponseKey('q1')]: 5,
+      [getSurveyResponseKey('q2')]: ['fast', 'clear'],
+    }
+
+    expect(buildSurveyResponseProperties(responses, survey)).toEqual({
+      $survey_questions: [
+        { id: 'q1', question: 'Rate us', response: 5 },
+        { id: 'q2', question: 'Anything else?', response: ['fast', 'clear'] },
+      ],
+      $survey_response_q1: 5,
+      $survey_response_q2: ['fast', 'clear'],
+      $survey_response: 5,
+      $survey_response_1: ['fast', 'clear'],
+    })
+  })
+
+  it('copies array response values before returning them', () => {
+    const responses = { [getSurveyResponseKey('q1')]: ['a'] }
+
+    const response = getSurveyResponseValue(responses, 'q1')
+
+    expect(response).toEqual(['a'])
+    expect(response).not.toBe(responses.$survey_response_q1)
+  })
+
+  it('detects non-nullish responses and builds interaction property names', () => {
+    expect(surveyHasResponses({ $survey_response_q1: null })).toBe(false)
+    expect(surveyHasResponses({ $survey_response_q1: 0 })).toBe(true)
+    expect(getSurveyInteractionProperty(survey, 'responded')).toBe('$survey_responded/survey-1/2')
+  })
+})

package/src/surveys/events.ts

@@ -0,0 +1,80 @@
+import { SurveyResponses, SurveyResponseValue } from '../types'
+import { isArray, isNullish, isUndefined } from '../utils'
+
+export const SURVEY_LANGUAGE_PROPERTY = '$survey_language'
+
+export function getSurveyResponseKey(questionId: string): string {
+  return `$survey_response_${questionId}`
+}
+
+export function getSurveyOldResponseKey(originalQuestionIndex: number): string {
+  return originalQuestionIndex === 0 ? '$survey_response' : `$survey_response_${originalQuestionIndex}`
+}
+
+export function getSurveyResponseValue(
+  responses: SurveyResponses,
+  questionId?: string
+): SurveyResponseValue | undefined {
+  if (!questionId) {
+    return null
+  }
+  const response = responses[getSurveyResponseKey(questionId)]
+  if (isArray(response)) {
+    return [...response]
+  }
+  return response
+}
+
+export function buildSurveyResponseProperties(
+  responses: SurveyResponses = {},
+  survey: SurveyForResponses
+): Record<string, unknown> {
+  const oldFormatResponses: SurveyResponses = {}
+  survey.questions.forEach((question: SurveyQuestionForResponses) => {
+    if (isUndefined(question.originalQuestionIndex)) {
+      return
+    }
+    const oldResponseKey = getSurveyOldResponseKey(question.originalQuestionIndex)
+    const response = getSurveyResponseValue(responses, question.id)
+    if (!isUndefined(response)) {
+      oldFormatResponses[oldResponseKey] = response
+    }
+  })
+
+  return {
+    $survey_questions: survey.questions.map((question: SurveyQuestionForResponses) => ({
+      id: question.id,
+      question: question.question,
+      response: getSurveyResponseValue(responses, question.id),
+    })),
+    ...responses,
+    ...oldFormatResponses,
+  }
+}
+
+export function surveyHasResponses(responses: SurveyResponses = {}): boolean {
+  return Object.values(responses).some((response) => !isNullish(response))
+}
+
+export function getSurveyInteractionProperty(survey: SurveyWithIteration, action: string): string {
+  let surveyProperty = `$survey_${action}/${survey.id}`
+  if (survey.current_iteration && survey.current_iteration > 0) {
+    surveyProperty = `$survey_${action}/${survey.id}/${survey.current_iteration}`
+  }
+
+  return surveyProperty
+}
+type SurveyQuestionForResponses = {
+  id?: string
+  question: string
+  originalQuestionIndex?: number
+}
+
+type SurveyForResponses = {
+  questions: SurveyQuestionForResponses[]
+}
+
+type SurveyWithIteration = {
+  id: string
+  current_iteration?: number | null
+}

package/src/surveys/index.ts

@@ -0,0 +1,18 @@
+export { getValidationError, getLengthFromRules, getRequirementsHint } from './validation'
+export {
+  buildSurveyResponseProperties,
+  getSurveyInteractionProperty,
+  getSurveyOldResponseKey,
+  getSurveyResponseKey,
+  getSurveyResponseValue,
+  SURVEY_LANGUAGE_PROPERTY,
+  surveyHasResponses,
+} from './events'
+export {
+  applySurveyTranslation,
+  detectSurveyLanguage,
+  findBestTranslationMatch,
+  getBaseLanguage,
+  getLanguageFromStoredPersonProperties,
+  normalizeLanguageCode,
+} from './translations'

package/src/surveys/translations.spec.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  applySurveyTranslation,
+  detectSurveyLanguage,
+  findBestTranslationMatch,
+  getLanguageFromStoredPersonProperties,
+} from './translations'
+import { Survey, SurveyQuestionType, SurveyType } from '../types'
+
+const createBaseSurvey = (): Survey => ({
+  id: 'test-survey',
+  name: 'Test Survey',
+  description: 'Test Description',
+  type: SurveyType.Popover,
+  questions: [
+    {
+      type: SurveyQuestionType.Open,
+      question: 'What do you think?',
+      id: 'q1',
+      originalQuestionIndex: 0,
+    },
+  ],
+  appearance: {
+    thankYouMessageHeader: 'Thank you!',
+    thankYouMessageDescription: 'We appreciate your feedback',
+    thankYouMessageCloseButtonText: 'Close',
+  },
+})
+
+describe('survey translations', () => {
+  describe('detectSurveyLanguage', () => {
+    it.each([
+      {
+        name: 'prioritizes override language',
+        input: {
+          overrideLanguage: 'de',
+          storedPersonProperties: { language: 'es' },
+          locale: 'fr',
+        },
+        expected: 'de',
+      },
+      {
+        name: 'uses person language when override is missing',
+        input: {
+          storedPersonProperties: { language: 'es' },
+          locale: 'fr',
+        },
+        expected: 'es',
+      },
+      {
+        name: 'falls back to locale',
+        input: {
+          storedPersonProperties: { some_other_property: 'value' },
+          locale: 'fr-CA',
+        },
+        expected: 'fr-CA',
+      },
+      {
+        name: 'returns null when no sources exist',
+        input: {
+          storedPersonProperties: { some_other_property: 'value' },
+        },
+        expected: null,
+      },
+      {
+        name: 'trims override language',
+        input: {
+          overrideLanguage: '  es  ',
+        },
+        expected: 'es',
+      },
+    ])('$name', ({ input, expected }) => {
+      expect(detectSurveyLanguage(input)).toBe(expected)
+    })
+
+    it('reads language from stored person properties', () => {
+      expect(getLanguageFromStoredPersonProperties({ language: 'it' })).toBe('it')
+      expect(getLanguageFromStoredPersonProperties({ language: '   ' })).toBeNull()
+      expect(getLanguageFromStoredPersonProperties({})).toBeNull()
+    })
+  })
+
+  describe('findBestTranslationMatch', () => {
+    it('supports exact and base-language matches', () => {
+      expect(findBestTranslationMatch({ fr: {}, 'fr-CA': {} }, 'FR-ca')).toBe('fr-CA')
+      expect(findBestTranslationMatch({ fr: {} }, 'fr-CA')).toBe('fr')
+      expect(findBestTranslationMatch({ es: {} }, 'de')).toBeNull()
+    })
+  })
+
+  describe('applySurveyTranslation', () => {
+    it('returns original survey when no translations exist', () => {
+      const survey = createBaseSurvey()
+      const result = applySurveyTranslation(survey, 'fr')
+
+      expect(result.survey).toEqual(survey)
+      expect(result.matchedKey).toBeNull()
+    })
+
+    it('applies survey-level translations', () => {
+      const survey = createBaseSurvey()
+      survey.translations = {
+        fr: {
+          name: 'Enquete Test',
+          thankYouMessageHeader: 'Merci',
+          thankYouMessageDescription: 'Merci pour votre retour',
+          thankYouMessageCloseButtonText: 'Fermer',
+        },
+      }
+
+      const result = applySurveyTranslation(survey, 'fr')
+
+      expect(result.survey.name).toBe('Enquete Test')
+      expect(result.survey.appearance?.thankYouMessageHeader).toBe('Merci')
+      expect(result.survey.appearance?.thankYouMessageDescription).toBe('Merci pour votre retour')
+      expect(result.survey.appearance?.thankYouMessageCloseButtonText).toBe('Fermer')
+      expect(result.matchedKey).toBe('fr')
+    })
+
+    it('applies question-level translations', () => {
+      const survey = createBaseSurvey()
+      survey.questions = [
+        {
+          type: SurveyQuestionType.Rating,
+          question: 'How was it?',
+          id: 'q1',
+          originalQuestionIndex: 0,
+          display: 'number',
+          scale: 5,
+          lowerBoundLabel: 'Bad',
+          upperBoundLabel: 'Great',
+          translations: {
+            pt: {
+              question: 'Como foi?',
+              lowerBoundLabel: 'Ruim',
+              upperBoundLabel: 'Otimo',
+            },
+          },
+        },
+        {
+          type: SurveyQuestionType.MultipleChoice,
+          question: 'Pick one',
+          id: 'q2',
+          originalQuestionIndex: 1,
+          choices: ['One', 'Other'],
+          hasOpenChoice: true,
+          translations: {
+            pt: {
+              choices: ['Um', 'Outro'],
+            },
+          },
+        },
+      ]
+
+      const result = applySurveyTranslation(survey, 'pt-BR')
+
+      expect(result.survey.questions[0].question).toBe('Como foi?')
+      expect('lowerBoundLabel' in result.survey.questions[0] && result.survey.questions[0].lowerBoundLabel).toBe('Ruim')
+      expect('upperBoundLabel' in result.survey.questions[0] && result.survey.questions[0].upperBoundLabel).toBe(
+        'Otimo'
+      )
+      expect('choices' in result.survey.questions[1] && result.survey.questions[1].choices).toEqual(['Um', 'Outro'])
+      expect(result.matchedKey).toBe('pt')
+    })
+
+    it('uses question-level match when there is no survey-level translation', () => {
+      const survey = createBaseSurvey()
+      survey.questions[0].translations = {
+        de: {
+          question: 'Was denkst du?',
+        },
+      }
+
+      const result = applySurveyTranslation(survey, 'de')
+
+      expect(result.survey.questions[0].question).toBe('Was denkst du?')
+      expect(result.matchedKey).toBe('de')
+    })
+
+    it('preserves custom survey and question fields for shared consumers', () => {
+      const survey = {
+        name: 'Custom Survey',
+        customSurveyField: true,
+        questions: [
+          {
+            question: 'Pick one',
+            customQuestionField: 'native-renderer',
+            translations: {
+              fr: {
+                question: 'Choisissez une option',
+              },
+            },
+          },
+        ],
+      }
+
+      const result = applySurveyTranslation(survey, 'fr')
+
+      expect(result.survey.customSurveyField).toBe(true)
+      expect(result.survey.questions[0].question).toBe('Choisissez une option')
+      expect(result.survey.questions[0].customQuestionField).toBe('native-renderer')
+      expect(result.matchedKey).toBe('fr')
+    })
+  })
+})

package/src/surveys/translations.ts

@@ -0,0 +1,244 @@
+import { SurveyQuestionTranslation, SurveyTranslation } from '../types'
+import { createLogger, isArray, isUndefined } from '../utils'
+
+const logger = createLogger('[SurveyTranslations]')
+
+export type DetectSurveyLanguageOptions = {
+  overrideLanguage?: unknown
+  storedPersonProperties?: unknown
+  locale?: unknown
+}
+
+function getTrimmedLanguage(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+export function getLanguageFromStoredPersonProperties(storedPersonProperties: unknown): string | null {
+  if (
+    !storedPersonProperties ||
+    typeof storedPersonProperties !== 'object' ||
+    !('language' in storedPersonProperties)
+  ) {
+    return null
+  }
+
+  return getTrimmedLanguage(storedPersonProperties.language)
+}
+
+export function detectSurveyLanguage({
+  overrideLanguage,
+  storedPersonProperties,
+  locale,
+}: DetectSurveyLanguageOptions): string | null {
+  const explicitLanguage = getTrimmedLanguage(overrideLanguage)
+  if (explicitLanguage) {
+    logger.info(`Using override display language: ${explicitLanguage}`)
+    return explicitLanguage
+  }
+
+  const personLanguage = getLanguageFromStoredPersonProperties(storedPersonProperties)
+  if (personLanguage) {
+    logger.info(`Using person property language: ${personLanguage}`)
+    return personLanguage
+  }
+
+  const detectedLocale = getTrimmedLanguage(locale)
+  if (detectedLocale) {
+    logger.info(`Using detected locale: ${detectedLocale}`)
+    return detectedLocale
+  }
+
+  logger.info('No user language detected')
+  return null
+}
+
+export function normalizeLanguageCode(languageCode: string): string {
+  return languageCode.toLowerCase()
+}
+
+export function getBaseLanguage(languageCode: string): string {
+  return languageCode.split('-')[0]
+}
+
+export function findBestTranslationMatch(
+  translations: Record<string, unknown> | undefined,
+  targetLanguage: string
+): string | null {
+  if (!translations || !targetLanguage) {
+    return null
+  }
+
+  const normalizedTarget = normalizeLanguageCode(targetLanguage)
+
+  const exactMatch = Object.keys(translations).find((key) => normalizeLanguageCode(key) === normalizedTarget)
+  if (exactMatch) {
+    logger.debug(`Found exact translation match: ${exactMatch}`)
+    return exactMatch
+  }
+
+  if (normalizedTarget.includes('-')) {
+    const baseLanguage = getBaseLanguage(normalizedTarget)
+    const baseMatch = Object.keys(translations).find((key) => normalizeLanguageCode(key) === baseLanguage)
+    if (baseMatch) {
+      logger.debug(`Found base language translation match: ${baseMatch} (from ${targetLanguage})`)
+      return baseMatch
+    }
+  }
+
+  return null
+}
+
+function isTranslatedChoices(
+  questionTranslation: SurveyQuestionTranslation
+): questionTranslation is SurveyQuestionTranslation & { choices: string[] } {
+  return isArray(questionTranslation.choices)
+}
+
+function hasThankYouTranslation(translation: SurveyTranslation): boolean {
+  return (
+    !isUndefined(translation.thankYouMessageHeader) ||
+    !isUndefined(translation.thankYouMessageDescription) ||
+    !isUndefined(translation.thankYouMessageCloseButtonText)
+  )
+}
+
+type TranslatableSurveyAppearance = {
+  thankYouMessageHeader?: string
+  thankYouMessageDescription?: string | null
+  thankYouMessageCloseButtonText?: string
+}
+
+type TranslatableSurveyQuestion = {
+  question: string
+  description?: string | null
+  buttonText?: string
+  link?: string | null
+  lowerBoundLabel?: string
+  upperBoundLabel?: string
+  choices?: string[]
+  translations?: Record<string, SurveyQuestionTranslation>
+}
+
+type TranslatableSurvey<TQuestion extends TranslatableSurveyQuestion = TranslatableSurveyQuestion> = {
+  name: string
+  translations?: Record<string, SurveyTranslation>
+  appearance?: TranslatableSurveyAppearance | null
+  questions: TQuestion[]
+}
+
+function mergeQuestionTranslation<TQuestion extends TranslatableSurveyQuestion>(
+  question: TQuestion,
+  targetLanguage: string
+): { question: TQuestion; matchedKey: string | null; hasChanges: boolean } {
+  const translationKey = findBestTranslationMatch(question.translations, targetLanguage)
+  if (!translationKey) {
+    return { question, matchedKey: null, hasChanges: false }
+  }
+
+  const questionTranslation = question.translations?.[translationKey]
+  if (!questionTranslation) {
+    return { question, matchedKey: null, hasChanges: false }
+  }
+
+  const translated: TQuestion = { ...question }
+  let hasChanges = false
+
+  if (!isUndefined(questionTranslation.question)) {
+    translated.question = questionTranslation.question
+    hasChanges = true
+  }
+  if (!isUndefined(questionTranslation.description)) {
+    translated.description = questionTranslation.description
+    hasChanges = true
+  }
+  if (!isUndefined(questionTranslation.buttonText)) {
+    translated.buttonText = questionTranslation.buttonText
+    hasChanges = true
+  }
+
+  if ('link' in translated && !isUndefined(questionTranslation.link)) {
+    translated.link = questionTranslation.link
+    hasChanges = true
+  }
+
+  if ('lowerBoundLabel' in translated && !isUndefined(questionTranslation.lowerBoundLabel)) {
+    translated.lowerBoundLabel = questionTranslation.lowerBoundLabel
+    hasChanges = true
+  }
+  if ('upperBoundLabel' in translated && !isUndefined(questionTranslation.upperBoundLabel)) {
+    translated.upperBoundLabel = questionTranslation.upperBoundLabel
+    hasChanges = true
+  }
+
+  if ('choices' in translated && isTranslatedChoices(questionTranslation)) {
+    translated.choices = questionTranslation.choices
+    hasChanges = true
+  }
+
+  return {
+    question: hasChanges ? translated : question,
+    matchedKey: hasChanges ? translationKey : null,
+    hasChanges,
+  }
+}
+
+export function applySurveyTranslation<
+  TQuestion extends TranslatableSurveyQuestion,
+  TSurvey extends TranslatableSurvey<TQuestion>,
+>(survey: TSurvey, targetLanguage: string): { survey: TSurvey; matchedKey: string | null } {
+  const translationKey = findBestTranslationMatch(survey.translations, targetLanguage)
+
+  const translated: TSurvey = { ...survey }
+  let hasTranslation = false
+
+  if (translationKey) {
+    const translation = survey.translations?.[translationKey]
+    if (translation) {
+      logger.info(`Applying survey-level translation for language: ${translationKey}`)
+
+      if (!isUndefined(translation.name)) {
+        translated.name = translation.name
+        hasTranslation = true
+      }
+
+      if (translated.appearance) {
+        translated.appearance = { ...translated.appearance }
+
+        if (!isUndefined(translation.thankYouMessageHeader)) {
+          translated.appearance.thankYouMessageHeader = translation.thankYouMessageHeader
+          hasTranslation = true
+        }
+        if (!isUndefined(translation.thankYouMessageDescription)) {
+          translated.appearance.thankYouMessageDescription = translation.thankYouMessageDescription
+          hasTranslation = true
+        }
+        if (!isUndefined(translation.thankYouMessageCloseButtonText)) {
+          translated.appearance.thankYouMessageCloseButtonText = translation.thankYouMessageCloseButtonText
+          hasTranslation = true
+        }
+      } else if (hasThankYouTranslation(translation)) {
+        hasTranslation = true
+      }
+    }
+  }
+
+  const translatedResults = survey.questions.map((question) => mergeQuestionTranslation(question, targetLanguage))
+  const translatedQuestions = translatedResults.map((result) => result.question)
+  const anyQuestionTranslated = translatedResults.some((result) => result.hasChanges)
+
+  let questionMatchedKey: string | null = null
+  if (!translationKey) {
+    questionMatchedKey = translatedResults.find((result) => result.matchedKey)?.matchedKey || null
+  }
+
+  if (anyQuestionTranslated) {
+    translated.questions = translatedQuestions
+    hasTranslation = true
+    logger.info(`Applied question-level translations for language: ${targetLanguage}`)
+  }
+
+  return {
+    survey: translated,
+    matchedKey: hasTranslation ? translationKey || questionMatchedKey : null,
+  }
+}

package/src/testing/test-utils.ts

@@ -36,6 +36,7 @@ export const delay = (ms: number): Promise<void> => {
 
 export const createMockLogger = (): Logger => {
   return {
+    debug: jest.fn((...args) => console.debug(...args)),
     info: jest.fn((...args) => console.log(...args)),
     warn: jest.fn((...args) => console.warn(...args)),
     error: jest.fn((...args) => console.error(...args)),