@posthog/core 1.41.0 → 1.42.0

package/src/surveys/activation.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from '@jest/globals'
+import { SurveySchedule } from '../types'
+import { canSurveyActivateRepeatedly, doesSurveyActivateByEvent } from './activation'
+
+describe('doesSurveyActivateByEvent', () => {
+  const cases: [string, Parameters<typeof doesSurveyActivateByEvent>[0], boolean][] = [
+    ['non-empty event values', { conditions: { events: { values: [{ name: 'event' }] } } }, true],
+    ['empty event values', { conditions: { events: { values: [] } } }, false],
+    ['undefined conditions', { conditions: undefined }, false],
+    ['null conditions', { conditions: null }, false],
+    ['null events', { conditions: { events: null } }, false],
+  ]
+
+  it.each(cases)('%s returns %p', (_name, survey, expected) => {
+    expect(doesSurveyActivateByEvent(survey)).toBe(expected)
+  })
+})
+
+describe('canSurveyActivateRepeatedly', () => {
+  const cases: [string, Parameters<typeof canSurveyActivateRepeatedly>[0], boolean][] = [
+    ['always schedule without events', { schedule: SurveySchedule.Always }, true],
+    [
+      'events with repeated activation enabled',
+      {
+        schedule: SurveySchedule.Once,
+        conditions: { events: { repeatedActivation: true, values: [{ name: 'event' }] } },
+      },
+      true,
+    ],
+    [
+      'events with repeated activation disabled',
+      {
+        schedule: SurveySchedule.Once,
+        conditions: { events: { repeatedActivation: false, values: [{ name: 'event' }] } },
+      },
+      false,
+    ],
+    [
+      'events without repeated activation',
+      {
+        schedule: SurveySchedule.Once,
+        conditions: { events: { values: [{ name: 'event' }] } },
+      },
+      false,
+    ],
+    [
+      'repeated activation without event values',
+      {
+        schedule: SurveySchedule.Once,
+        conditions: { events: { repeatedActivation: true, values: [] } },
+      },
+      false,
+    ],
+    ['undefined schedule without events', { schedule: undefined }, false],
+    ['null schedule without events', { schedule: null }, false],
+  ]
+
+  it.each(cases)('%s returns %p', (_name, survey, expected) => {
+    expect(canSurveyActivateRepeatedly(survey)).toBe(expected)
+  })
+})

package/src/surveys/activation.ts

@@ -0,0 +1,28 @@
+import { Survey, SurveySchedule } from '../types'
+
+// conditions is narrowed to the fields these predicates actually read, so both SDKs'
+// Survey shapes (which still drift in nested condition types) satisfy it structurally.
+type SurveyForRepeatActivation = Pick<Survey, 'schedule'> & {
+  conditions?: {
+    events?: {
+      repeatedActivation?: boolean
+      values?: { name: string }[]
+    } | null
+  } | null
+}
+
+export function doesSurveyActivateByEvent(survey: SurveyForRepeatActivation): boolean {
+  return !!survey.conditions?.events?.values?.length
+}
+
+/**
+ * Platform-independent part of "can this survey show again after being seen":
+ * event-repeated activation or an 'always' schedule. SDKs may OR in
+ * platform-specific state (e.g. the web SDK's in-progress partial responses).
+ */
+export function canSurveyActivateRepeatedly(survey: SurveyForRepeatActivation): boolean {
+  return (
+    (doesSurveyActivateByEvent(survey) && !!survey.conditions?.events?.repeatedActivation) ||
+    survey.schedule === SurveySchedule.Always
+  )
+}

package/src/surveys/events.ts

@@ -1,3 +1,4 @@
+import { SurveyWithIteration } from './keys'
 import { SurveyResponses, SurveyResponseValue } from '../types'
 import { isArray, isNullish, isUndefined } from '../utils'
 
@@ -73,8 +74,3 @@ type SurveyQuestionForResponses = {
 type SurveyForResponses = {
   questions: SurveyQuestionForResponses[]
 }
-
-type SurveyWithIteration = {
-  id: string
-  current_iteration?: number | null
-}

package/src/surveys/index.ts

@@ -16,3 +16,5 @@ export {
   getLanguageFromStoredPersonProperties,
   normalizeLanguageCode,
 } from './translations'
+export { canSurveyActivateRepeatedly, doesSurveyActivateByEvent } from './activation'
+export { getSurveyIterationKey, isSurveyKeyForSurvey, type SurveyWithIteration } from './keys'

package/src/surveys/keys.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from '@jest/globals'
+import { getSurveyIterationKey, isSurveyKeyForSurvey } from './keys'
+
+describe('getSurveyIterationKey', () => {
+  const cases: [number | null | undefined, string][] = [
+    [2, 'survey-1_2'],
+    [1, 'survey-1_1'],
+    [0, 'survey-1'],
+    [null, 'survey-1'],
+    [undefined, 'survey-1'],
+  ]
+
+  it.each(cases)('current_iteration %p produces key %p', (currentIteration, expected) => {
+    expect(getSurveyIterationKey({ id: 'survey-1', current_iteration: currentIteration })).toBe(expected)
+  })
+})
+
+describe('isSurveyKeyForSurvey', () => {
+  it.each([
+    ['bare id', 'abc', 'abc', true],
+    ['first iteration', 'abc_1', 'abc', true],
+    ['later iteration', 'abc_12', 'abc', true],
+    ['different survey id', 'def_1', 'abc', false],
+    ['prefix collision with bare id', 'abcd', 'abc', false],
+    ['prefix collision with iteration key', 'abcd_1', 'abc', false],
+  ])('%s: key %p for survey %p returns %p', (_name, key, surveyId, expected) => {
+    expect(isSurveyKeyForSurvey(key, surveyId)).toBe(expected)
+  })
+})

package/src/surveys/keys.ts

@@ -0,0 +1,23 @@
+import { Survey } from '../types'
+
+export type SurveyWithIteration = Pick<Survey, 'id' | 'current_iteration'>
+
+/**
+ * True when a stored display-state key belongs to the given survey: its bare id
+ * or any iteration-qualified `id_n` key.
+ */
+export function isSurveyKeyForSurvey(key: string, surveyId: string): boolean {
+  return key === surveyId || key.startsWith(`${surveyId}_`)
+}
+
+/**
+ * Iteration-qualified survey identifier ('id' or 'id_iteration'), used to key
+ * per-survey display state (seen, in-progress, ...). Keying by iteration lets a
+ * repeating survey become visible again when a new iteration starts.
+ */
+export function getSurveyIterationKey(survey: SurveyWithIteration): string {
+  if (survey.current_iteration && survey.current_iteration > 0) {
+    return `${survey.id}_${survey.current_iteration}`
+  }
+  return survey.id
+}

package/src/types.ts

@@ -633,43 +633,49 @@ export type SurveyAppearance = {
   widgetColor?: string
 }
 
-export enum SurveyPosition {
-  TopLeft = 'top_left',
-  TopCenter = 'top_center',
-  TopRight = 'top_right',
-  MiddleLeft = 'middle_left',
-  MiddleCenter = 'middle_center',
-  MiddleRight = 'middle_right',
-  Left = 'left',
-  Right = 'right',
-  Center = 'center',
-}
+export const SurveyPosition = {
+  TopLeft: 'top_left',
+  TopCenter: 'top_center',
+  TopRight: 'top_right',
+  MiddleLeft: 'middle_left',
+  MiddleCenter: 'middle_center',
+  MiddleRight: 'middle_right',
+  Left: 'left',
+  Right: 'right',
+  Center: 'center',
+} as const
+export type SurveyPosition = (typeof SurveyPosition)[keyof typeof SurveyPosition]
 
-export enum SurveyWidgetType {
-  Button = 'button',
-  Tab = 'tab',
-  Selector = 'selector',
-}
+export const SurveyWidgetType = {
+  Button: 'button',
+  Tab: 'tab',
+  Selector: 'selector',
+} as const
+export type SurveyWidgetType = (typeof SurveyWidgetType)[keyof typeof SurveyWidgetType]
 
-export enum SurveyType {
-  Popover = 'popover',
-  API = 'api',
-  Widget = 'widget',
-  ExternalSurvey = 'external_survey',
-}
+export const SurveyType = {
+  Popover: 'popover',
+  API: 'api',
+  Widget: 'widget',
+  ExternalSurvey: 'external_survey',
+} as const
+export type SurveyType = (typeof SurveyType)[keyof typeof SurveyType]
 
 export type SurveyQuestion = BasicSurveyQuestion | LinkSurveyQuestion | RatingSurveyQuestion | MultipleSurveyQuestion
 
-export enum SurveyQuestionDescriptionContentType {
-  Html = 'html',
-  Text = 'text',
-}
+export const SurveyQuestionDescriptionContentType = {
+  Html: 'html',
+  Text: 'text',
+} as const
+export type SurveyQuestionDescriptionContentType =
+  (typeof SurveyQuestionDescriptionContentType)[keyof typeof SurveyQuestionDescriptionContentType]
 
 // Survey validation types
-export enum SurveyValidationType {
-  MinLength = 'min_length',
-  MaxLength = 'max_length',
-}
+export const SurveyValidationType = {
+  MinLength: 'min_length',
+  MaxLength: 'max_length',
+} as const
+export type SurveyValidationType = (typeof SurveyValidationType)[keyof typeof SurveyValidationType]
 
 export interface SurveyValidationRule {
   type: SurveyValidationType
@@ -710,16 +716,16 @@ type SurveyQuestionBase = {
 }
 
 export type BasicSurveyQuestion = SurveyQuestionBase & {
-  type: SurveyQuestionType.Open
+  type: typeof SurveyQuestionType.Open
 }
 
 export type LinkSurveyQuestion = SurveyQuestionBase & {
-  type: SurveyQuestionType.Link
+  type: typeof SurveyQuestionType.Link
   link?: string | null
 }
 
 export type RatingSurveyQuestion = SurveyQuestionBase & {
-  type: SurveyQuestionType.Rating
+  type: typeof SurveyQuestionType.Rating
   display: SurveyRatingDisplay
   scale: 2 | 3 | 5 | 7 | 10
   lowerBoundLabel: string
@@ -727,49 +733,52 @@ export type RatingSurveyQuestion = SurveyQuestionBase & {
   skipSubmitButton?: boolean
 }
 
-export enum SurveyRatingDisplay {
-  Number = 'number',
-  Emoji = 'emoji',
-}
+export const SurveyRatingDisplay = {
+  Number: 'number',
+  Emoji: 'emoji',
+} as const
+export type SurveyRatingDisplay = (typeof SurveyRatingDisplay)[keyof typeof SurveyRatingDisplay]
 
 export type MultipleSurveyQuestion = SurveyQuestionBase & {
-  type: SurveyQuestionType.SingleChoice | SurveyQuestionType.MultipleChoice
+  type: typeof SurveyQuestionType.SingleChoice | typeof SurveyQuestionType.MultipleChoice
   choices: string[]
   hasOpenChoice?: boolean
   shuffleOptions?: boolean
   skipSubmitButton?: boolean
 }
 
-export enum SurveyQuestionType {
-  Open = 'open',
-  MultipleChoice = 'multiple_choice',
-  SingleChoice = 'single_choice',
-  Rating = 'rating',
-  Link = 'link',
-}
+export const SurveyQuestionType = {
+  Open: 'open',
+  MultipleChoice: 'multiple_choice',
+  SingleChoice: 'single_choice',
+  Rating: 'rating',
+  Link: 'link',
+} as const
+export type SurveyQuestionType = (typeof SurveyQuestionType)[keyof typeof SurveyQuestionType]
 
-export enum SurveyQuestionBranchingType {
-  NextQuestion = 'next_question',
-  End = 'end',
-  ResponseBased = 'response_based',
-  SpecificQuestion = 'specific_question',
-}
+export const SurveyQuestionBranchingType = {
+  NextQuestion: 'next_question',
+  End: 'end',
+  ResponseBased: 'response_based',
+  SpecificQuestion: 'specific_question',
+} as const
+export type SurveyQuestionBranchingType = (typeof SurveyQuestionBranchingType)[keyof typeof SurveyQuestionBranchingType]
 
 export type NextQuestionBranching = {
-  type: SurveyQuestionBranchingType.NextQuestion
+  type: typeof SurveyQuestionBranchingType.NextQuestion
 }
 
 export type EndBranching = {
-  type: SurveyQuestionBranchingType.End
+  type: typeof SurveyQuestionBranchingType.End
 }
 
 export type ResponseBasedBranching = {
-  type: SurveyQuestionBranchingType.ResponseBased
+  type: typeof SurveyQuestionBranchingType.ResponseBased
   responseValues: Record<string, any>
 }
 
 export type SpecificQuestionBranching = {
-  type: SurveyQuestionBranchingType.SpecificQuestion
+  type: typeof SurveyQuestionBranchingType.SpecificQuestion
   index: number
 }
 
@@ -783,20 +792,22 @@ export type SurveyResponses = Record<string, SurveyResponseValue>
 
 export type SurveyCallback = (surveys: Survey[]) => void
 
-export enum SurveyMatchType {
-  Regex = 'regex',
-  NotRegex = 'not_regex',
-  Exact = 'exact',
-  IsNot = 'is_not',
-  Icontains = 'icontains',
-  NotIcontains = 'not_icontains',
-}
+export const SurveyMatchType = {
+  Regex: 'regex',
+  NotRegex: 'not_regex',
+  Exact: 'exact',
+  IsNot: 'is_not',
+  Icontains: 'icontains',
+  NotIcontains: 'not_icontains',
+} as const
+export type SurveyMatchType = (typeof SurveyMatchType)[keyof typeof SurveyMatchType]
 
-export enum SurveySchedule {
-  Once = 'once',
-  Recurring = 'recurring',
-  Always = 'always',
-}
+export const SurveySchedule = {
+  Once: 'once',
+  Recurring: 'recurring',
+  Always: 'always',
+} as const
+export type SurveySchedule = (typeof SurveySchedule)[keyof typeof SurveySchedule]
 
 export type SurveyElement = {
   text?: string
@@ -853,9 +864,9 @@ export type Survey = {
   }
   start_date?: string
   end_date?: string
-  current_iteration?: number
-  current_iteration_start_date?: string
-  schedule?: SurveySchedule
+  current_iteration?: number | null
+  current_iteration_start_date?: string | null
+  schedule?: SurveySchedule | null
 }
 
 export type SurveyActionType = {
@@ -865,11 +876,12 @@ export type SurveyActionType = {
 }
 
 /** Sync with plugin-server/src/types.ts */
-export enum ActionStepStringMatching {
-  Contains = 'contains',
-  Exact = 'exact',
-  Regex = 'regex',
-}
+export const ActionStepStringMatching = {
+  Contains: 'contains',
+  Exact: 'exact',
+  Regex: 'regex',
+} as const
+export type ActionStepStringMatching = (typeof ActionStepStringMatching)[keyof typeof ActionStepStringMatching]
 
 export type ActionStepType = {
   event?: string