@posthog/core 1.27.9 → 1.28.1

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',
@@ -789,6 +807,10 @@ export abstract class PostHogCoreStateless {
   public async getSurveysStateless(): Promise<SurveyResponse['surveys']> {
     await this._initPromise
 
+    if (this.disabled) {
+      return []
+    }
+
     if (this.disableSurveys === true) {
       this._logger.info('Loading surveys is disabled.')
       return []
@@ -1053,6 +1075,10 @@ export abstract class PostHogCoreStateless {
    * @throws Error
    */
   async flush(): Promise<void> {
+    if (this.disabled) {
+      return
+    }
+
     // Wait for the current flush operation to finish (regardless of success or failure), then try to flush again.
     // Use allSettled instead of finally to be defensive around flush throwing errors immediately rather than rejecting.
     // Use a custom allSettled implementation to avoid issues with patching Promise on RN
@@ -1179,6 +1205,56 @@ 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> {
+    if (this.disabled) {
+      return { kind: 'fatal', error: new Error('The client is disabled') }
+    }
+
+    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,
@@ -1241,6 +1317,10 @@ export abstract class PostHogCoreStateless {
     let hasTimedOut = false
     this.clearFlushTimer()
 
+    if (this.disabled) {
+      return
+    }
+
     const doShutdown = async (): Promise<void> => {
       try {
         await this.promiseQueue.join()

package/src/posthog-core.ts

@@ -566,6 +566,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
 
   private async remoteConfigAsync(): Promise<PostHogRemoteConfig | undefined> {
     await this._initPromise
+    if (this.disabled) {
+      return undefined
+    }
     if (this._remoteConfigResponsePromise) {
       return this._remoteConfigResponsePromise
     }
@@ -578,6 +581,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
   protected async flagsAsync(options?: FlagsAsyncOptions): Promise<PostHogFeatureFlagsResponse | undefined> {
     const { sendAnonDistinctId = true, fetchConfig = false, triggerOnRemoteConfig = false } = options ?? {}
     await this._initPromise
+    if (this.disabled) {
+      return undefined
+    }
     if (this._flagsResponsePromise) {
       // Queue the reload request instead of dropping it
       // This ensures that requests with $anon_distinct_id (from identify()) are not lost

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')
+    })
+  })
+})