@posthog/browser-common 0.9.4 → 0.9.6

package/dist/survey-constants.js

@@ -0,0 +1,144 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+const SurveyEventType = {
+    Activation: 'events',
+    Cancellation: 'cancelEvents'
+};
+const SurveyWidgetType = {
+    Button: 'button',
+    Tab: 'tab',
+    Selector: 'selector'
+};
+const SurveyPosition = {
+    TopLeft: 'top_left',
+    TopRight: 'top_right',
+    TopCenter: 'top_center',
+    MiddleLeft: 'middle_left',
+    MiddleRight: 'middle_right',
+    MiddleCenter: 'middle_center',
+    Left: 'left',
+    Center: 'center',
+    Right: 'right',
+    NextToTrigger: 'next_to_trigger'
+};
+const SurveyTabPosition = {
+    Top: 'top',
+    Left: 'left',
+    Right: 'right',
+    Bottom: 'bottom'
+};
+const SurveyType = {
+    Popover: 'popover',
+    API: 'api',
+    Widget: 'widget',
+    ExternalSurvey: 'external_survey'
+};
+const SurveyQuestionType = {
+    Open: 'open',
+    MultipleChoice: 'multiple_choice',
+    SingleChoice: 'single_choice',
+    Rating: 'rating',
+    Link: 'link'
+};
+const SurveyQuestionBranchingType = {
+    NextQuestion: 'next_question',
+    End: 'end',
+    ResponseBased: 'response_based',
+    SpecificQuestion: 'specific_question'
+};
+const SurveySchedule = {
+    Once: 'once',
+    Recurring: 'recurring',
+    Always: 'always'
+};
+const SurveyEventName = {
+    SHOWN: 'survey shown',
+    DISMISSED: 'survey dismissed',
+    SENT: 'survey sent',
+    ABANDONED: 'survey abandoned'
+};
+const SurveyEventProperties = {
+    SURVEY_ID: '$survey_id',
+    SURVEY_NAME: '$survey_name',
+    SURVEY_RESPONSE: '$survey_response',
+    SURVEY_ITERATION: '$survey_iteration',
+    SURVEY_ITERATION_START_DATE: '$survey_iteration_start_date',
+    SURVEY_PARTIALLY_COMPLETED: '$survey_partially_completed',
+    SURVEY_SUBMISSION_ID: '$survey_submission_id',
+    SURVEY_QUESTIONS: '$survey_questions',
+    SURVEY_COMPLETED: '$survey_completed',
+    PRODUCT_TOUR_ID: '$product_tour_id',
+    SURVEY_LAST_SEEN_DATE: '$survey_last_seen_date',
+    SURVEY_LANGUAGE: '$survey_language'
+};
+const DisplaySurveyType = {
+    Popover: 'popover',
+    Inline: 'inline'
+};
+__webpack_require__.d(__webpack_exports__, {}, {
+    DisplaySurveyType: DisplaySurveyType,
+    SurveyEventName: SurveyEventName,
+    SurveyEventProperties: SurveyEventProperties,
+    SurveyEventType: SurveyEventType,
+    SurveyPosition: SurveyPosition,
+    SurveyQuestionBranchingType: SurveyQuestionBranchingType,
+    SurveyQuestionType: SurveyQuestionType,
+    SurveySchedule: SurveySchedule,
+    SurveyTabPosition: SurveyTabPosition,
+    SurveyType: SurveyType,
+    SurveyWidgetType: SurveyWidgetType
+});
+exports.DisplaySurveyType = __webpack_exports__.DisplaySurveyType;
+exports.SurveyEventName = __webpack_exports__.SurveyEventName;
+exports.SurveyEventProperties = __webpack_exports__.SurveyEventProperties;
+exports.SurveyEventType = __webpack_exports__.SurveyEventType;
+exports.SurveyPosition = __webpack_exports__.SurveyPosition;
+exports.SurveyQuestionBranchingType = __webpack_exports__.SurveyQuestionBranchingType;
+exports.SurveyQuestionType = __webpack_exports__.SurveyQuestionType;
+exports.SurveySchedule = __webpack_exports__.SurveySchedule;
+exports.SurveyTabPosition = __webpack_exports__.SurveyTabPosition;
+exports.SurveyType = __webpack_exports__.SurveyType;
+exports.SurveyWidgetType = __webpack_exports__.SurveyWidgetType;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "DisplaySurveyType",
+    "SurveyEventName",
+    "SurveyEventProperties",
+    "SurveyEventType",
+    "SurveyPosition",
+    "SurveyQuestionBranchingType",
+    "SurveyQuestionType",
+    "SurveySchedule",
+    "SurveyTabPosition",
+    "SurveyType",
+    "SurveyWidgetType"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/survey-constants.mjs

@@ -0,0 +1,76 @@
+const SurveyEventType = {
+    Activation: 'events',
+    Cancellation: 'cancelEvents'
+};
+const SurveyWidgetType = {
+    Button: 'button',
+    Tab: 'tab',
+    Selector: 'selector'
+};
+const SurveyPosition = {
+    TopLeft: 'top_left',
+    TopRight: 'top_right',
+    TopCenter: 'top_center',
+    MiddleLeft: 'middle_left',
+    MiddleRight: 'middle_right',
+    MiddleCenter: 'middle_center',
+    Left: 'left',
+    Center: 'center',
+    Right: 'right',
+    NextToTrigger: 'next_to_trigger'
+};
+const SurveyTabPosition = {
+    Top: 'top',
+    Left: 'left',
+    Right: 'right',
+    Bottom: 'bottom'
+};
+const SurveyType = {
+    Popover: 'popover',
+    API: 'api',
+    Widget: 'widget',
+    ExternalSurvey: 'external_survey'
+};
+const SurveyQuestionType = {
+    Open: 'open',
+    MultipleChoice: 'multiple_choice',
+    SingleChoice: 'single_choice',
+    Rating: 'rating',
+    Link: 'link'
+};
+const SurveyQuestionBranchingType = {
+    NextQuestion: 'next_question',
+    End: 'end',
+    ResponseBased: 'response_based',
+    SpecificQuestion: 'specific_question'
+};
+const SurveySchedule = {
+    Once: 'once',
+    Recurring: 'recurring',
+    Always: 'always'
+};
+const SurveyEventName = {
+    SHOWN: 'survey shown',
+    DISMISSED: 'survey dismissed',
+    SENT: 'survey sent',
+    ABANDONED: 'survey abandoned'
+};
+const SurveyEventProperties = {
+    SURVEY_ID: '$survey_id',
+    SURVEY_NAME: '$survey_name',
+    SURVEY_RESPONSE: '$survey_response',
+    SURVEY_ITERATION: '$survey_iteration',
+    SURVEY_ITERATION_START_DATE: '$survey_iteration_start_date',
+    SURVEY_PARTIALLY_COMPLETED: '$survey_partially_completed',
+    SURVEY_SUBMISSION_ID: '$survey_submission_id',
+    SURVEY_QUESTIONS: '$survey_questions',
+    SURVEY_COMPLETED: '$survey_completed',
+    PRODUCT_TOUR_ID: '$product_tour_id',
+    SURVEY_LAST_SEEN_DATE: '$survey_last_seen_date',
+    SURVEY_LANGUAGE: '$survey_language'
+};
+const DisplaySurveyType = {
+    Popover: 'popover',
+    Inline: 'inline'
+};
+export { DisplaySurveyType, SurveyEventName, SurveyEventProperties, SurveyEventType, SurveyPosition, SurveyQuestionBranchingType, SurveyQuestionType, SurveySchedule, SurveyTabPosition, SurveyType, SurveyWidgetType };

package/dist/survey-event-host.d.ts

@@ -0,0 +1,15 @@
+import type { Properties } from '@posthog/types';
+export interface SurveyCapturedEvent {
+    event: string;
+    properties: Properties;
+}
+/** Event observation and selector registration used by survey and tour triggers. */
+export interface SurveyActionHost {
+    subscribeCapture?: ((listener: (event: string, payload?: SurveyCapturedEvent) => void) => () => void) | undefined;
+    setElementSelectors?: ((selectors: Set<string>, owner?: object) => void) | undefined;
+}
+export interface SurveyEventHost extends SurveyActionHost {
+    subscribeSession?: ((listener: (sessionId: string) => void) => () => void) | undefined;
+    getSessionId(): string | undefined;
+    getProperty<T = unknown>(key: string): T | undefined;
+}

package/dist/survey-event-host.js

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/survey-event-host.mjs

@@ -0,0 +1 @@
+export { };

package/dist/survey-event-receiver-base.d.ts

@@ -0,0 +1,180 @@
+import type { SurveyActionType, SurveyEventWithFilters } from './types/surveys';
+import { ActionMatcher } from './survey-action-matcher';
+import type { SurveyEventHost, SurveyCapturedEvent as CaptureResult } from './survey-event-host';
+import { createLogger } from './utils/logger';
+/**
+ * Interface for items that can be triggered by events/actions.
+ * Both Survey and ProductTour implement this interface.
+ */
+export interface EventTriggerable {
+    id: string;
+    conditions?: {
+        events?: {
+            repeatedActivation?: boolean;
+            values: SurveyEventWithFilters[];
+        } | null;
+        cancelEvents?: {
+            values: SurveyEventWithFilters[];
+        } | null;
+        actions?: {
+            values: SurveyActionType[];
+        } | null;
+    } | null;
+}
+/**
+ * What a captured lifecycle event (shown / dismissed / sent) does to an already-activated item:
+ * - `consume`: it's done — drop it from both the in-memory and persisted sets.
+ * - `persist`: it was shown and should survive a reload — move it from memory into persistence.
+ * - `ignore`: no transition for this item on this event.
+ */
+export type ActivationOutcome = 'consume' | 'persist' | 'ignore';
+/**
+ * Abstract base class for receiving events and matching them to triggerable items.
+ * Subclasses implement type-specific behavior for surveys and product tours.
+ */
+export declare abstract class EventReceiver<T extends EventTriggerable> {
+    private readonly _onActivationChanged?;
+    protected _eventToItems: Map<string, string[]>;
+    protected _cancelEventToItems: Map<string, string[]>;
+    protected readonly _actionToItems: Map<string, string[]>;
+    protected _actionMatcher: ActionMatcher | null | undefined;
+    protected readonly _host: SurveyEventHost;
+    /**
+     * Items armed by an event or action but not yet shown live here, in memory only.
+     * They are intentionally NOT persisted, so they do not survive a page reload: an
+     * event trigger only displays an item in the session the event fired in. Once an
+     * item is shown, surviving items are promoted into persistence (see `onEvent`) so
+     * a reload re-reads and re-displays them until the user interacts — but that
+     * persisted activation is scoped to the triggering session (see
+     * `_getPersistedActivatedIds`), so it does not leak into a brand-new session where
+     * the trigger never fired.
+     */
+    private _pendingActivatedItems;
+    private _captureHookUnsubscribe;
+    private _sessionIdUnsubscribe;
+    constructor(host: SurveyEventHost, _onActivationChanged?: (() => void) | undefined);
+    /** Start after subclass dependencies are initialized; hosts may publish synchronously. */
+    protected _subscribeSession(): void;
+    protected abstract _getActivatedKey(): string;
+    /** Persistence key under which the session id of the persisted activation set is stamped. */
+    protected abstract _getActivatedSessionKey(): string;
+    protected abstract _getShownEventName(): string;
+    protected abstract _getItems(callback: (items: T[]) => void): void;
+    protected abstract _cancelPendingItem(itemId: string): void;
+    protected abstract _getLogger(): ReturnType<typeof createLogger>;
+    protected abstract _setActivatedItems(eligibleItems: string[]): void;
+    /** Persist the session id the current activation set belongs to. */
+    protected abstract _setActivatedSession(sessionId: string): void;
+    /** Forget the persisted session stamp. */
+    protected abstract _clearActivatedSession(): void;
+    /** Check if item is permanently ineligible (e.g. completed/dismissed). Skip adding to activated list. */
+    protected abstract _isItemPermanentlyIneligible(itemId?: string): boolean;
+    /**
+     * Decide what a captured lifecycle `event` does to an already-activated `itemId`. Most items are
+     * consumed when shown (so they only reappear when their trigger fires again). Surveys keep
+     * non-repeatable ones activated — promoting them to session-scoped persistence on shown — until the
+     * user dismisses or answers them, so an event-triggered survey survives a reload within the
+     * triggering session (but not a brand-new session) until it's actually interacted with.
+     */
+    protected abstract _activationOutcome(event: string, itemId: string, eventPayload?: CaptureResult): ActivationOutcome;
+    /**
+     * Whether an item armed by a trigger should be persisted immediately (session-scoped)
+     * instead of kept in memory until it is shown. Overridden by receivers whose items carry a
+     * display delay that must survive a navigation, so the delay can resume from where it left
+     * off on the next page. Default: keep in memory, so the arming is page-scoped and an
+     * exit-intent-style trigger cannot leak an armed item onto a later page load.
+     */
+    protected _shouldPersistArmedActivation(_itemId: string): boolean;
+    /**
+     * Persistence key under which per-item activation timestamps are read from, or null for
+     * receivers that don't track them. Used to resume a display delay across navigations. Writes
+     * go through `_writeActivationTimestamps` / `_clearActivationTimestampsStore` so the register
+     * sink always resolves to a literal key constant.
+     */
+    protected _getActivationTimestampsKey(): string | null;
+    /** Persist the activation timestamp map. Overridden by receivers that track timestamps. */
+    protected _writeActivationTimestamps(_timestamps: Record<string, number>): void;
+    /** Forget the whole activation timestamp map. Overridden by receivers that track timestamps. */
+    protected _clearActivationTimestampsStore(): void;
+    private _doesEventMatchFilter;
+    private _buildEventToItemMap;
+    /**
+     * build a map of (Event1) => [Item1, Item2, Item3]
+     * used for items that should be [activated|cancelled] by Event1
+     */
+    private _getMatchingItems;
+    register(items: T[]): void;
+    replace(items: T[]): void;
+    private _register;
+    private _setupActionBasedItems;
+    private _mergeItemMaps;
+    private _setupEventBasedItems;
+    onEvent(event: string, eventPayload?: CaptureResult): void;
+    onAction(actionName: string): void;
+    /**
+     * Arm items. Most are held in memory only (not persisted) until they are shown, so their
+     * arming is page-scoped. Items that opt in via `_shouldPersistArmedActivation` (those with a
+     * display delay) are persisted right away and stamped with the activation time, so the delay
+     * survives a navigation and resumes from the elapsed time on the next page.
+     */
+    private _activateItems;
+    /**
+     * Move an in-memory activation into persistence so it survives a page reload within the
+     * triggering session. The set is (re)stamped with the current session id; reading it back
+     * via `_getPersistedActivatedIds` discards it once the session rolls over. Because we build
+     * on top of the session-scoped read, a stale set left over from a previous session is
+     * dropped here rather than accumulated.
+     */
+    private _persistActivation;
+    /** Drop items from both the in-memory and persisted activation sets. */
+    private _deactivateItems;
+    private _notifyActivationChanged;
+    /** The raw persisted activation timestamps as stored, ignoring session scoping. */
+    private _getRawActivationTimestamps;
+    /**
+     * Stamp when an item enters persisted activation, so a resumed display delay can be computed
+     * from the elapsed time on a later page load. Repeated triggers do not call this method because
+     * `_persistActivation` returns false while the current activation is still live.
+     */
+    private _recordActivationTimestamp;
+    /** Drop the activation timestamps for the given items. */
+    private _clearActivationTimestamps;
+    /** Forget all activation timestamps (e.g. on reset or a session rollover). */
+    private _clearAllActivationTimestamps;
+    /**
+     * The time (epoch ms) an item was armed by its trigger, or undefined if none is recorded.
+     * Session-scoped: a timestamp is only honored while its activation is still live for the
+     * current session, so a stale entry left in persistence cannot resurrect an expired delay.
+     */
+    getActivationTimestamp(itemId: string): number | undefined;
+    /** The raw persisted set as stored, ignoring session scoping. */
+    private _getRawPersistedActivatedIds;
+    /**
+     * The persisted activations that still belong to the current session. A persisted activation
+     * is scoped to the session the item was shown in: an event/action trigger only earns a display
+     * in the session it fired in, so once the session rolls over the activation is stale and must
+     * not silently re-display the item in a brand-new session where the trigger never fired.
+     */
+    private _getPersistedActivatedIds;
+    /** Stamp the persisted activation set with the current session id. */
+    private _stampActivationSession;
+    /** Forget the session stamp once nothing is persisted under it. */
+    private _clearActivationSession;
+    /**
+     * Drop a persisted activation once the session it was stamped under is no longer current.
+     * Fired on session rotation (idle timeout, max length, cross-tab adoption) — the cases the
+     * read-only session read on the display path cannot observe. Pending timers must also be
+     * cancelled so a fresh trigger in the new session starts its full delay from the new timestamp.
+     */
+    private _onSessionIdChanged;
+    getActivatedIds(): string[];
+    /**
+     * Clear all activations. Called on `posthog.reset()` so a logout or account switch
+     * (without a full page reload) does not leave an event-armed item live for the next
+     * user — the in-memory set would otherwise survive `persistence.clear()`.
+     */
+    dispose(): void;
+    reset(): void;
+    getEventToItemsMap(): Map<string, string[]>;
+    _getActionMatcher(): ActionMatcher | null | undefined;
+}