@posthog/browser-common 0.9.5 → 0.9.6

package/dist/surveys.mjs

@@ -0,0 +1,495 @@
+import { DisplaySurveyType, SurveyEventName, SurveyEventProperties, SurveyEventType, SurveyPosition, SurveyQuestionBranchingType, SurveyQuestionType, SurveySchedule, SurveyTabPosition, SurveyType, SurveyWidgetType } from "./survey-constants.mjs";
+import { SurveyEventReceiver } from "./survey-event-receiver.mjs";
+import { continueWith } from "./utils/promise-utils.mjs";
+import { isBoolean, isNullish, isNumber, isUndefined } from "@posthog/core";
+import { LOAD_EXT_NOT_FOUND, SURVEYS, SURVEYS_CACHE_TTL_MS, SURVEYS_LOADED_AT, SURVEYS_REFRESH_BACKOFF_MS } from "./surveys-config.mjs";
+import { IN_APP_SURVEY_TYPES, SURVEY_CAPTURING_DISABLED, SURVEY_IN_PROGRESS_PREFIX, SURVEY_LOGGER, SURVEY_SEEN_PREFIX, doesSurveyActivateByAction, doesSurveyActivateByEvent, isSurveyRunning, setSurveySeenOnLocalStorage } from "./utils/survey-utils.mjs";
+const SURVEY_NOT_LOADED = 'SDK is not enabled or survey functionality is not yet loaded';
+const SURVEY_DISABLED = 'Disabled. Not loading surveys.';
+class PostHogSurveys {
+    constructor(_configSource){
+        this._configSource = _configSource;
+        this.name = 'surveys';
+        this._surveyEventReceiver = null;
+        this._surveyManager = null;
+        this._isInitializingSurveys = false;
+        this._surveyInitializationFailed = false;
+        this._surveyCallbacks = [];
+        this._activeMatchingSurveyCallbacks = [];
+        this._getSurveysInFlightPromise = null;
+        this._lastSurveyRefreshFailedAt = null;
+        this._disposed = false;
+        this._renderTimeouts = new Set();
+        this.onRemoteConfig = (result)=>{
+            if (this._disposed) return;
+            if (this._config.disableSurveys) return;
+            if (!result.ok) {
+                this._surveyInitializationFailed = true;
+                this._notifyActiveMatchingSurveyCallbacks({
+                    isLoaded: false,
+                    error: 'Remote config unavailable. Not loading surveys.'
+                });
+                return SURVEY_LOGGER.warn('Remote config unavailable. Not loading surveys.');
+            }
+            const surveys = result.config['surveys'];
+            if (isNullish(surveys)) return SURVEY_LOGGER.warn('Flags not loaded yet. Not loading surveys.');
+            this._isSurveysEnabled = isBoolean(surveys) ? surveys : surveys.length > 0;
+            SURVEY_LOGGER.info(`flags response received, isSurveysEnabled: ${this._isSurveysEnabled}`);
+            this.loadIfEnabled();
+        };
+        this._notifyActiveMatchingSurveyCallbacks = (context)=>{
+            this._activeMatchingSurveyCallbacks.slice().forEach((subscription)=>this._notifyActiveMatchingSurveyCallback(subscription, context));
+        };
+    }
+    setup(client) {
+        if (this._disposed) return;
+        this._initializingClient = client;
+        return continueWith(client.kv.initialize(), ()=>{
+            if (this._initializingClient !== client || this._disposed) return;
+            this._initializingClient = void 0;
+            this._client = client;
+            const subscription = client.onRemoteConfig(this.onRemoteConfig);
+            if (this._disposed) return void subscription.dispose();
+            this._remoteConfigSubscription = subscription;
+            this.loadIfEnabled();
+        });
+    }
+    dispose() {
+        if (this._disposed) return;
+        this._disposed = true;
+        this._initializingClient = void 0;
+        this._client = void 0;
+        this._remoteConfigSubscription?.dispose();
+        this._remoteConfigSubscription = void 0;
+        this._surveyEventReceiver?.dispose();
+        this._surveyEventReceiver = null;
+        this._surveyManager?.dispose?.();
+        this._surveyManager = null;
+        this._surveyCallbacks = [];
+        this._activeMatchingSurveyCallbacks.forEach((subscription)=>{
+            subscription.active = false;
+        });
+        this._activeMatchingSurveyCallbacks = [];
+        this._activeMatchingSurveyConditionsUnsubscribe?.();
+        this._activeMatchingSurveyConditionsUnsubscribe = void 0;
+        this._getSurveysInFlightPromise = null;
+        this._renderTimeouts.forEach((timeout)=>clearTimeout(timeout));
+        this._renderTimeouts.clear();
+    }
+    get _config() {
+        return this._configSource.get();
+    }
+    getRenderContext() {
+        if (!this._client) return;
+        const surveys = this;
+        return {
+            client: this._client,
+            get config () {
+                return surveys._config;
+            },
+            surveys
+        };
+    }
+    initialize() {
+        this.loadIfEnabled();
+    }
+    reset() {
+        this._surveyManager?.clearInMemoryInProgressSurveyState?.();
+        try {
+            this._surveyEventReceiver?.reset();
+            localStorage.removeItem('lastSeenSurveyDate');
+            const surveyKeys = [];
+            for(let i = 0; i < localStorage.length; i++){
+                const key = localStorage.key(i);
+                if (key?.startsWith(SURVEY_SEEN_PREFIX) || key?.startsWith(SURVEY_IN_PROGRESS_PREFIX)) surveyKeys.push(key);
+            }
+            surveyKeys.forEach((key)=>localStorage.removeItem(key));
+        } catch  {}
+        this._notifyActiveMatchingSurveyCallbacks();
+    }
+    loadIfEnabled() {
+        if (this._disposed || !this._client) return;
+        const config = this._config;
+        if (this._surveyManager) return;
+        if (this._isInitializingSurveys) return void SURVEY_LOGGER.info('Already initializing surveys, skipping...');
+        if (config.disableSurveys) return void SURVEY_LOGGER.info(SURVEY_DISABLED);
+        if (config.cookielessMode && this._client.isOptedOut) return void SURVEY_LOGGER.info('Not loading surveys in cookieless mode without consent.');
+        const phExtensions = this._configSource.getExtensions();
+        if (!phExtensions) return void this._handleSurveyLoadError('PostHog Extensions not found.');
+        if (isUndefined(this._isSurveysEnabled) && !config.advancedEnableSurveys) return;
+        const isSurveysEnabled = this._isSurveysEnabled || config.advancedEnableSurveys;
+        this._isInitializingSurveys = true;
+        this._surveyInitializationFailed = false;
+        try {
+            const generateSurveys = phExtensions.generateSurveys;
+            if (generateSurveys) {
+                this._completeSurveyInitialization(generateSurveys, isSurveysEnabled);
+                this._isInitializingSurveys = false;
+                return;
+            }
+            const loadExternalDependency = phExtensions.loadExternalDependency;
+            if (!loadExternalDependency) {
+                this._handleSurveyLoadError(LOAD_EXT_NOT_FOUND);
+                this._isInitializingSurveys = false;
+                return;
+            }
+            loadExternalDependency((err)=>{
+                try {
+                    if (this._disposed) return;
+                    const loadedExtensions = this._configSource.getExtensions();
+                    if (err || !loadedExtensions?.generateSurveys) this._handleSurveyLoadError("Could not load surveys script", err);
+                    else this._completeSurveyInitialization(loadedExtensions.generateSurveys, isSurveysEnabled);
+                } finally{
+                    this._isInitializingSurveys = false;
+                }
+            });
+        } catch (e) {
+            this._isInitializingSurveys = false;
+            this._handleSurveyLoadError('Error initializing surveys', e);
+            throw e;
+        }
+    }
+    _completeSurveyInitialization(generateSurveysFn, isSurveysEnabled) {
+        if (this._disposed) return;
+        this._surveyManager = generateSurveysFn(isSurveysEnabled);
+        this._surveyEventReceiver = new SurveyEventReceiver(this._client, this, this._notifyActiveMatchingSurveyCallbacks);
+        const cachedSurveys = this._client?.kv.get(SURVEYS);
+        if (cachedSurveys) this._registerEventOrActionBasedSurveys(cachedSurveys);
+        SURVEY_LOGGER.info('Surveys loaded successfully');
+        this._startActiveMatchingSurveyConditions();
+        this._notifyActiveMatchingSurveyCallbacks();
+        this._notifySurveyCallbacks({
+            isLoaded: true
+        });
+    }
+    _handleSurveyLoadError(message, error) {
+        this._surveyInitializationFailed = true;
+        SURVEY_LOGGER.error(message, error);
+        this._notifyActiveMatchingSurveyCallbacks({
+            isLoaded: false,
+            error: message
+        });
+        this._notifySurveyCallbacks({
+            isLoaded: false,
+            error: message
+        });
+    }
+    onSurveysLoaded(callback) {
+        this._surveyCallbacks.push(callback);
+        if (this._surveyManager) this._notifySurveyCallbacks({
+            isLoaded: true
+        });
+        return ()=>{
+            this._surveyCallbacks = this._surveyCallbacks.filter((cb)=>cb !== callback);
+        };
+    }
+    getSurveys(callback, forceReload = false) {
+        if (this._disposed) return;
+        const client = this._client;
+        if (!client) return callback([], {
+            isLoaded: false,
+            error: SURVEY_NOT_LOADED
+        });
+        if (this._config.disableSurveys) {
+            SURVEY_LOGGER.info(SURVEY_DISABLED);
+            return callback([]);
+        }
+        const surveys = client.kv.get(SURVEYS);
+        if (surveys && !forceReload) {
+            callback(surveys, {
+                isLoaded: true
+            });
+            if (this._shouldBackgroundRefreshSurveys()) this.getSurveys(()=>{}, true);
+            return;
+        }
+        if (this._getSurveysInFlightPromise) return void this._getSurveysInFlightPromise.then(({ surveys, context })=>{
+            if (!this._disposed) callback(surveys, context);
+        }).catch((error)=>SURVEY_LOGGER.error('Error in survey callback', error));
+        const request = client.sendRequest('/api/surveys/', {
+            method: 'GET',
+            query: {
+                token: client.projectToken
+            },
+            sentAt: 'query',
+            timeoutMs: this._config.requestTimeoutMs
+        }).then((response)=>{
+            try {
+                return this._handleSurveyResponse(client, response);
+            } catch (error) {
+                SURVEY_LOGGER.error('Error processing surveys response', error);
+                return this._handleSurveyResponse(client, {
+                    statusCode: 0,
+                    error
+                });
+            }
+        }, (error)=>this._handleSurveyResponse(client, {
+                statusCode: 0,
+                error
+            }));
+        this._getSurveysInFlightPromise = request;
+        const clearInFlight = ()=>{
+            if (this._getSurveysInFlightPromise === request) this._getSurveysInFlightPromise = null;
+        };
+        request.then((result)=>{
+            clearInFlight();
+            if (!this._disposed) {
+                this._notifyActiveMatchingSurveyCallbacks(result.context);
+                callback(result.surveys, result.context);
+            }
+        }, clearInFlight).catch((error)=>SURVEY_LOGGER.error('Error in survey callback', error));
+    }
+    _handleSurveyResponse(client, response) {
+        if (this._disposed) return {
+            surveys: [],
+            context: {
+                isLoaded: false,
+                error: SURVEY_NOT_LOADED
+            }
+        };
+        const statusCode = response.statusCode;
+        if (200 !== statusCode || !response.json) {
+            const error = `Surveys API could not be loaded, status: ${statusCode}`;
+            if (0 !== statusCode) SURVEY_LOGGER.error(error);
+            else if (!response.error) SURVEY_LOGGER.warn(error);
+            this._lastSurveyRefreshFailedAt = Date.now();
+            return {
+                surveys: [],
+                context: {
+                    isLoaded: false,
+                    error
+                }
+            };
+        }
+        this._lastSurveyRefreshFailedAt = null;
+        const surveys = response.json.surveys || [];
+        client.kv.set({
+            [SURVEYS]: surveys,
+            [SURVEYS_LOADED_AT]: Date.now()
+        });
+        this._registerEventOrActionBasedSurveys(surveys);
+        return {
+            surveys,
+            context: {
+                isLoaded: true
+            }
+        };
+    }
+    _registerEventOrActionBasedSurveys(surveys) {
+        const eventOrActionBasedSurveys = surveys.filter((survey)=>isSurveyRunning(survey) && (doesSurveyActivateByEvent(survey) || doesSurveyActivateByAction(survey)));
+        this._surveyEventReceiver?.replace(eventOrActionBasedSurveys);
+    }
+    _shouldBackgroundRefreshSurveys() {
+        return this._isSurveyCacheStale() && !this._getSurveysInFlightPromise && !this._isSurveyRefreshBackingOff();
+    }
+    _isSurveyCacheStale() {
+        const surveysLoadedAt = this._client?.kv.get(SURVEYS_LOADED_AT);
+        return isNumber(surveysLoadedAt) && Date.now() - surveysLoadedAt > SURVEYS_CACHE_TTL_MS;
+    }
+    _isSurveyRefreshBackingOff() {
+        return isNumber(this._lastSurveyRefreshFailedAt) && Date.now() - this._lastSurveyRefreshFailedAt < SURVEYS_REFRESH_BACKOFF_MS;
+    }
+    markSurveyAsSeen(surveyId, options) {
+        const survey = {
+            id: surveyId,
+            current_iteration: options?.iteration ?? null
+        };
+        setSurveySeenOnLocalStorage(survey);
+        try {
+            localStorage.setItem('lastSeenSurveyDate', new Date().toISOString());
+        } catch  {}
+        this._notifyActiveMatchingSurveyCallbacks();
+    }
+    _notifySurveyCallbacks(context) {
+        for (const callback of this._surveyCallbacks){
+            if (this._disposed) return;
+            try {
+                if (context.isLoaded) this.getSurveys(callback);
+                else callback([], context);
+            } catch (error) {
+                SURVEY_LOGGER.error('Error in survey callback', error);
+            }
+        }
+    }
+    getActiveMatchingSurveys(callback, forceReload = false) {
+        if (isNullish(this._surveyManager)) return void SURVEY_LOGGER.warn('init was not called');
+        return this._surveyManager.getActiveMatchingSurveys(callback, forceReload);
+    }
+    onActiveMatchingSurveysChanged(callback) {
+        if (this._disposed) return ()=>{};
+        const subscription = {
+            callback,
+            active: true,
+            revision: 0
+        };
+        this._activeMatchingSurveyCallbacks.push(subscription);
+        this._startActiveMatchingSurveyConditions();
+        const cached = this._client?.kv.get(SURVEYS);
+        const unavailable = this._config.disableSurveys || !this._surveyManager && this._surveyInitializationFailed && !this._isInitializingSurveys || !cached && !isNullish(this._lastSurveyRefreshFailedAt) && !this._getSurveysInFlightPromise;
+        if (unavailable) this._notifyActiveMatchingSurveyCallback(subscription, {
+            isLoaded: false
+        });
+        else if (this._surveyManager) this._notifyActiveMatchingSurveyCallback(subscription);
+        return ()=>{
+            subscription.active = false;
+            this._activeMatchingSurveyCallbacks = this._activeMatchingSurveyCallbacks.filter((current)=>current !== subscription);
+            if (0 === this._activeMatchingSurveyCallbacks.length) {
+                this._activeMatchingSurveyConditionsUnsubscribe?.();
+                this._activeMatchingSurveyConditionsUnsubscribe = void 0;
+            }
+        };
+    }
+    _startActiveMatchingSurveyConditions() {
+        if (this._surveyManager && this._activeMatchingSurveyCallbacks.length > 0) this._activeMatchingSurveyConditionsUnsubscribe ??= this._configSource.onMatchingConditionsChanged?.(this._notifyActiveMatchingSurveyCallbacks);
+    }
+    _notifyActiveMatchingSurveyCallback(subscription, context) {
+        if (this._disposed || !subscription.active) return;
+        const revision = ++subscription.revision;
+        const deliver = (surveys)=>{
+            if (this._disposed || !subscription.active || revision !== subscription.revision) return;
+            try {
+                const resultContext = context ?? {
+                    isLoaded: true
+                };
+                const result = JSON.stringify([
+                    surveys,
+                    resultContext
+                ]);
+                if (result === subscription.lastResult) return;
+                subscription.lastResult = result;
+                subscription.callback(surveys, resultContext);
+            } catch (error) {
+                SURVEY_LOGGER.error('Error in active matching surveys callback', error);
+            }
+        };
+        try {
+            if (context && !context.isLoaded) deliver([]);
+            else this.getActiveMatchingSurveys(deliver);
+        } catch (error) {
+            SURVEY_LOGGER.error('Error in active matching surveys callback', error);
+        }
+    }
+    _getSurveyById(surveyId) {
+        let survey = null;
+        this.getSurveys((surveys)=>{
+            survey = surveys.find((x)=>x.id === surveyId) ?? null;
+        });
+        return survey;
+    }
+    _checkSurveyEligibility(surveyId) {
+        if (isNullish(this._surveyManager)) return {
+            eligible: false,
+            reason: SURVEY_NOT_LOADED
+        };
+        const survey = 'string' == typeof surveyId ? this._getSurveyById(surveyId) : surveyId;
+        if (!survey) return {
+            eligible: false,
+            reason: 'Survey not found'
+        };
+        return this._surveyManager.checkSurveyEligibility(survey);
+    }
+    _checkSurveyRenderability(surveyId) {
+        if (!this._client?.canCapture) return {
+            eligible: false,
+            reason: SURVEY_CAPTURING_DISABLED
+        };
+        if (isNullish(this._surveyManager)) return {
+            eligible: false,
+            reason: SURVEY_NOT_LOADED
+        };
+        const survey = 'string' == typeof surveyId ? this._getSurveyById(surveyId) : surveyId;
+        if (!survey) return {
+            eligible: false,
+            reason: 'Survey not found'
+        };
+        return this._surveyManager.checkSurveyRenderability(survey);
+    }
+    canRenderSurvey(surveyId) {
+        if (isNullish(this._surveyManager)) {
+            SURVEY_LOGGER.warn('init was not called');
+            return {
+                visible: false,
+                disabledReason: SURVEY_NOT_LOADED
+            };
+        }
+        const eligibility = this._checkSurveyRenderability(surveyId);
+        return {
+            visible: eligibility.eligible,
+            disabledReason: eligibility.reason
+        };
+    }
+    canRenderSurveyAsync(surveyId, forceReload) {
+        if (isNullish(this._surveyManager)) {
+            SURVEY_LOGGER.warn('init was not called');
+            return Promise.resolve({
+                visible: false,
+                disabledReason: SURVEY_NOT_LOADED
+            });
+        }
+        return new Promise((resolve)=>{
+            this.getSurveys((surveys)=>{
+                const survey = surveys.find((x)=>x.id === surveyId) ?? null;
+                if (survey) {
+                    const eligibility = this._checkSurveyRenderability(survey);
+                    resolve({
+                        visible: eligibility.eligible,
+                        disabledReason: eligibility.reason
+                    });
+                } else resolve({
+                    visible: false,
+                    disabledReason: 'Survey not found'
+                });
+            }, forceReload);
+        });
+    }
+    renderSurvey(surveyId, selector, properties) {
+        if (!this._client?.canCapture) return;
+        if (isNullish(this._surveyManager)) return void SURVEY_LOGGER.warn('init was not called');
+        const survey = 'string' == typeof surveyId ? this._getSurveyById(surveyId) : surveyId;
+        if (!survey?.id) return void SURVEY_LOGGER.warn('Survey not found');
+        if (!IN_APP_SURVEY_TYPES.includes(survey.type)) return void SURVEY_LOGGER.warn(`Surveys of type ${survey.type} cannot be rendered in the app`);
+        const elem = ("u" < typeof document ? void 0 : document)?.querySelector(selector);
+        if (!elem) return void SURVEY_LOGGER.warn('Survey element not found');
+        if (survey.appearance?.surveyPopupDelaySeconds) {
+            SURVEY_LOGGER.info(`Rendering survey ${survey.id} with delay of ${survey.appearance.surveyPopupDelaySeconds} seconds`);
+            const timeout = setTimeout(()=>{
+                this._renderTimeouts.delete(timeout);
+                if (this._disposed || !this._client?.canCapture) return;
+                SURVEY_LOGGER.info(`Rendering survey ${survey.id} with delay of ${survey.appearance?.surveyPopupDelaySeconds} seconds`);
+                this._surveyManager?.renderSurvey(survey, elem, properties);
+                SURVEY_LOGGER.info(`Survey ${survey.id} rendered`);
+            }, 1000 * survey.appearance.surveyPopupDelaySeconds);
+            this._renderTimeouts.add(timeout);
+            return;
+        }
+        this._surveyManager.renderSurvey(survey, elem, properties);
+    }
+    displaySurvey(surveyId, options) {
+        if (!this._client?.canCapture) return;
+        if (isNullish(this._surveyManager)) return void SURVEY_LOGGER.warn('init was not called');
+        const survey = this._getSurveyById(surveyId);
+        if (!survey) return void SURVEY_LOGGER.warn('Survey not found');
+        let surveyToDisplay = survey;
+        if (survey.appearance?.surveyPopupDelaySeconds && options.ignoreDelay) surveyToDisplay = {
+            ...survey,
+            appearance: {
+                ...survey.appearance,
+                surveyPopupDelaySeconds: 0
+            }
+        };
+        if (options.displayType !== DisplaySurveyType.Popover && options.initialResponses) SURVEY_LOGGER.warn('initialResponses is only supported for popover surveys. prefill will not be applied.');
+        if (false === options.ignoreConditions) {
+            const eligibility = this._checkSurveyEligibility(survey);
+            if (!eligibility.eligible) return void SURVEY_LOGGER.warn('Survey is not eligible to be displayed: ', eligibility.reason);
+        }
+        if (options.displayType === DisplaySurveyType.Inline) return void this.renderSurvey(surveyToDisplay, options.selector, options.properties);
+        this._surveyManager.handlePopoverSurvey(surveyToDisplay, options);
+    }
+    cancelPendingSurvey(surveyId) {
+        if (isNullish(this._surveyManager)) return void SURVEY_LOGGER.warn('init was not called');
+        this._surveyManager.cancelSurvey(surveyId);
+    }
+    handlePageUnload() {
+        this._surveyManager?.handlePageUnload?.();
+    }
+}
+export { DisplaySurveyType, PostHogSurveys, SurveyEventName, SurveyEventProperties, SurveyEventType, SurveyPosition, SurveyQuestionBranchingType, SurveyQuestionType, SurveySchedule, SurveyTabPosition, SurveyType, SurveyWidgetType };

package/dist/types/surveys.d.ts

@@ -1,91 +1,9 @@
+import type { SurveyWidgetType, SurveyPosition, SurveyTabPosition, SurveyType, SurveyQuestionType, SurveyQuestionBranchingType, SurveySchedule, DisplaySurveyType } from '../survey-constants';
+export type { SurveyEventType, SurveyWidgetType, SurveyPosition, SurveyTabPosition, SurveyType, SurveyQuestionType, SurveyQuestionBranchingType, SurveySchedule, SurveyEventName, SurveyEventProperties, DisplaySurveyType, } from '../survey-constants';
+import type { Properties } from '@posthog/types';
+import type { SurveyResponseValue as CoreSurveyResponseValue } from '@posthog/core';
 import type { PropertyMatchType, SurveyAppearance as CoreSurveyAppearance, SurveyEventWithFilters, SurveyQuestionTranslation, SurveyTranslation, SurveyValidationRule } from '@posthog/core';
 export type { PropertyFilters, PropertyMatchType, PropertyOperator, SurveyEventWithFilters } from '@posthog/core';
-export declare const SurveyEventType: {
-    readonly Activation: 'events';
-    readonly Cancellation: 'cancelEvents';
-};
-export type SurveyEventType = (typeof SurveyEventType)[keyof typeof SurveyEventType];
-export declare const SurveyWidgetType: {
-    readonly Button: 'button';
-    readonly Tab: 'tab';
-    readonly Selector: 'selector';
-};
-export type SurveyWidgetType = (typeof SurveyWidgetType)[keyof typeof SurveyWidgetType];
-export declare const SurveyPosition: {
-    readonly TopLeft: 'top_left';
-    readonly TopRight: 'top_right';
-    readonly TopCenter: 'top_center';
-    readonly MiddleLeft: 'middle_left';
-    readonly MiddleRight: 'middle_right';
-    readonly MiddleCenter: 'middle_center';
-    readonly Left: 'left';
-    readonly Center: 'center';
-    readonly Right: 'right';
-    readonly NextToTrigger: 'next_to_trigger';
-};
-export type SurveyPosition = (typeof SurveyPosition)[keyof typeof SurveyPosition];
-export declare const SurveyTabPosition: {
-    readonly Top: 'top';
-    readonly Left: 'left';
-    readonly Right: 'right';
-    readonly Bottom: 'bottom';
-};
-export type SurveyTabPosition = (typeof SurveyTabPosition)[keyof typeof SurveyTabPosition];
-export declare const SurveyType: {
-    readonly Popover: 'popover';
-    readonly API: 'api';
-    readonly Widget: 'widget';
-    readonly ExternalSurvey: 'external_survey';
-};
-export type SurveyType = (typeof SurveyType)[keyof typeof SurveyType];
-export declare const SurveyQuestionType: {
-    readonly Open: 'open';
-    readonly MultipleChoice: 'multiple_choice';
-    readonly SingleChoice: 'single_choice';
-    readonly Rating: 'rating';
-    readonly Link: 'link';
-};
-export type SurveyQuestionType = (typeof SurveyQuestionType)[keyof typeof SurveyQuestionType];
-export declare const SurveyQuestionBranchingType: {
-    readonly NextQuestion: 'next_question';
-    readonly End: 'end';
-    readonly ResponseBased: 'response_based';
-    readonly SpecificQuestion: 'specific_question';
-};
-export type SurveyQuestionBranchingType = (typeof SurveyQuestionBranchingType)[keyof typeof SurveyQuestionBranchingType];
-export declare const SurveySchedule: {
-    readonly Once: 'once';
-    readonly Recurring: 'recurring';
-    readonly Always: 'always';
-};
-export type SurveySchedule = (typeof SurveySchedule)[keyof typeof SurveySchedule];
-export declare const SurveyEventName: {
-    readonly SHOWN: 'survey shown';
-    readonly DISMISSED: 'survey dismissed';
-    readonly SENT: 'survey sent';
-    readonly ABANDONED: 'survey abandoned';
-};
-export type SurveyEventName = (typeof SurveyEventName)[keyof typeof SurveyEventName];
-export declare const SurveyEventProperties: {
-    readonly SURVEY_ID: '$survey_id';
-    readonly SURVEY_NAME: '$survey_name';
-    readonly SURVEY_RESPONSE: '$survey_response';
-    readonly SURVEY_ITERATION: '$survey_iteration';
-    readonly SURVEY_ITERATION_START_DATE: '$survey_iteration_start_date';
-    readonly SURVEY_PARTIALLY_COMPLETED: '$survey_partially_completed';
-    readonly SURVEY_SUBMISSION_ID: '$survey_submission_id';
-    readonly SURVEY_QUESTIONS: '$survey_questions';
-    readonly SURVEY_COMPLETED: '$survey_completed';
-    readonly PRODUCT_TOUR_ID: '$product_tour_id';
-    readonly SURVEY_LAST_SEEN_DATE: '$survey_last_seen_date';
-    readonly SURVEY_LANGUAGE: '$survey_language';
-};
-export type SurveyEventProperties = (typeof SurveyEventProperties)[keyof typeof SurveyEventProperties];
-export declare const DisplaySurveyType: {
-    readonly Popover: 'popover';
-    readonly Inline: 'inline';
-};
-export type DisplaySurveyType = (typeof DisplaySurveyType)[keyof typeof DisplaySurveyType];
 export type SurveyQuestionDescriptionContentType = 'html' | 'text';
 /** Browser survey appearance, including browser-only placement and rendering options. */
 export interface SurveyAppearance extends Omit<CoreSurveyAppearance, 'position' | 'widgetType'> {
@@ -228,3 +146,82 @@ export interface ActionStepType {
         type?: string;
     }[];
 }
+export type SurveyCallback = (surveys: Survey[], context?: {
+    isLoaded: boolean;
+    error?: string;
+}) => void;
+export interface SurveyElement {
+    text?: string;
+    $el_text?: string;
+    tag_name?: string;
+    href?: string;
+    attr_id?: string;
+    attr_class?: string[];
+    nth_child?: number;
+    nth_of_type?: number;
+    attributes?: Record<string, any>;
+    event_id?: number;
+    order?: number;
+    group_id?: number;
+}
+export type { SurveyRenderReason } from '@posthog/types';
+interface DisplaySurveyOptionsBase {
+    /**
+     * Whether to bypass the survey's targeting and display conditions.
+     * @default false
+     */
+    ignoreConditions: boolean;
+    /**
+     * Whether to bypass the survey's configured popup delay.
+     * @default false
+     */
+    ignoreDelay: boolean;
+    /**
+     * How the survey should be displayed.
+     * @default DisplaySurveyType.Popover
+     */
+    displayType: DisplaySurveyType;
+    /** Additional properties to include in all survey events (shown, sent, dismissed). */
+    properties?: Properties;
+    /** Pre-filled responses by question index (0-based). Only supported for popover surveys. */
+    initialResponses?: Record<number, SurveyResponseValue>;
+}
+/** Options for displaying a survey as a popover. */
+export interface DisplaySurveyPopoverOptions extends DisplaySurveyOptionsBase {
+    displayType: typeof DisplaySurveyType.Popover;
+    /** Override the survey's configured position. */
+    position?: SurveyPosition;
+    /** CSS selector for the element to position the survey next to (when position is NextToTrigger). */
+    selector?: string;
+    /** When true, `survey shown` events will not be emitted automatically. */
+    skipShownEvent?: boolean;
+}
+interface DisplaySurveyInlineOptions extends DisplaySurveyOptionsBase {
+    displayType: typeof DisplaySurveyType.Inline;
+    /** CSS selector for the element where the inline survey should render. */
+    selector: string;
+}
+/** Options for `posthog.displaySurvey()`. */
+export type DisplaySurveyOptions = DisplaySurveyPopoverOptions | DisplaySurveyInlineOptions;
+export interface SurveyConfig {
+    /**
+     * Prefill survey responses from matching URL parameters.
+     *
+     * @default undefined
+     */
+    prefillFromUrl?: boolean;
+    /**
+     * @deprecated No longer used. Surveys will automatically advance past
+     * prefilled questions with skipSubmitButton enabled. If partial response
+     * collection is enabled, partial responses for pre-filled questions will
+     * be submitted automatically on page load.
+     */
+    autoSubmitIfComplete?: boolean;
+    /**
+     * @deprecated No longer used. Pre-filled responses are now sent
+     * immediately when partial responses are enabled, or all required
+     * questions have been pre-filled.
+     */
+    autoSubmitDelay?: number;
+}
+export type SurveyResponseValue = CoreSurveyResponseValue;