posthog-js-lite 3.5.1 → 3.6.0

package/lib/index.d.ts

@@ -70,6 +70,7 @@ declare enum PostHogPersistedProperty {
     Queue = "queue",
     OptedOut = "opted_out",
     SessionId = "session_id",
+    SessionStartTimestamp = "session_start_timestamp",
     SessionLastTimestamp = "session_timestamp",
     PersonProperties = "person_properties",
     GroupProperties = "group_properties",
@@ -105,7 +106,10 @@ type PostHogFetchResponse = {
     json: () => Promise<any>;
 };
 type PostHogEventProperties = {
-    [key: string]: any;
+    [key: string]: JsonType;
+};
+type PostHogGroupProperties = {
+    [type: string]: string | number;
 };
 type PostHogAutocaptureElement = {
     $el_text?: string;
@@ -114,9 +118,7 @@ type PostHogAutocaptureElement = {
     nth_child?: number;
     nth_of_type?: number;
     order?: number;
-} & {
-    [key: string]: any;
-};
+} & PostHogEventProperties;
 type PostHogRemoteConfig = {
     sessionRecording?: boolean | {
         [key: string]: JsonType;
@@ -182,7 +184,7 @@ type PartialWithRequired<T, K extends keyof T> = {
 type PostHogFeatureFlagDetails = PartialWithRequired<PostHogDecideResponse, 'flags' | 'featureFlags' | 'featureFlagPayloads' | 'requestId'>;
 type JsonType = string | number | boolean | null | {
     [key: string]: JsonType;
-} | Array<JsonType>;
+} | Array<JsonType> | JsonType[];
 type FeatureFlagDetail = {
     key: string;
     enabled: boolean;
@@ -430,7 +432,7 @@ declare abstract class PostHogCoreStateless {
     constructor(apiKey: string, options?: PostHogCoreOptions);
     protected logMsgIfDebug(fn: () => void): void;
     protected wrap(fn: () => void): void;
-    protected getCommonEventProperties(): any;
+    protected getCommonEventProperties(): PostHogEventProperties;
     get optedOut(): boolean;
     optIn(): Promise<void>;
     optOut(): Promise<void>;
@@ -445,18 +447,10 @@ declare abstract class PostHogCoreStateless {
      ***/
     protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     protected identifyStatelessImmediate(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
-    protected captureStateless(distinctId: string, event: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): void;
-    protected captureStatelessImmediate(distinctId: string, event: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): Promise<void>;
-    protected aliasStateless(alias: string, distinctId: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): void;
-    protected aliasStatelessImmediate(alias: string, distinctId: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): Promise<void>;
+    protected captureStateless(distinctId: string, event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    protected captureStatelessImmediate(distinctId: string, event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
+    protected aliasStateless(alias: string, distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    protected aliasStatelessImmediate(alias: string, distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): Promise<void>;
     /***
      *** GROUPS
      ***/
@@ -497,9 +491,7 @@ declare abstract class PostHogCoreStateless {
     private _props;
     protected get props(): PostHogEventProperties;
     protected set props(val: PostHogEventProperties | undefined);
-    register(properties: {
-        [key: string]: any;
-    }): Promise<void>;
+    register(properties: PostHogEventProperties): Promise<void>;
     unregister(property: string): Promise<void>;
     /***
      *** QUEUEING AND FLUSHING
@@ -513,7 +505,29 @@ declare abstract class PostHogCoreStateless {
      * Avoids unnecessary promise errors
      */
     private flushBackground;
-    flush(): Promise<any[]>;
+    /**
+     * Flushes the queue
+     *
+     * This function will return a promise that will resolve when the flush is complete,
+     * or reject if there was an error (for example if the server or network is down).
+     *
+     * If there is already a flush in progress, this function will wait for that flush to complete.
+     *
+     * It's recommended to do error handling in the callback of the promise.
+     *
+     * @example
+     * posthog.flush().then(() => {
+     *   console.log('Flush complete')
+     * }).catch((err) => {
+     *   console.error('Flush failed', err)
+     * })
+     *
+     *
+     * @throws PostHogFetchHttpError
+     * @throws PostHogFetchNetworkError
+     * @throws Error
+     */
+    flush(): Promise<void>;
     protected getCustomHeaders(): {
         [key: string]: string;
     };
@@ -532,13 +546,14 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     private flagCallReported;
     protected _decideResponsePromise?: Promise<PostHogDecideResponse | undefined>;
     protected _sessionExpirationTimeSeconds: number;
+    private _sessionMaxLengthSeconds;
     protected sessionProps: PostHogEventProperties;
     constructor(apiKey: string, options?: PostHogCoreOptions);
     protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
     private clearProps;
     on(event: string, cb: (...args: any[]) => void): () => void;
     reset(propertiesToKeep?: PostHogPersistedProperty[]): void;
-    protected getCommonEventProperties(): any;
+    protected getCommonEventProperties(): PostHogEventProperties;
     private enrichProperties;
     /**
      * * @returns {string} The stored session ID for the current session. This may be an empty string if the client is not yet fully initialized.
@@ -553,25 +568,19 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
      * * @returns {string} The stored distinct ID. This may be an empty string if the client is not yet fully initialized.
      */
     getDistinctId(): string;
-    registerForSession(properties: {
-        [key: string]: any;
-    }): void;
+    registerForSession(properties: PostHogEventProperties): void;
     unregisterForSession(property: string): void;
     /***
      *** TRACKING
      ***/
     identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
-    capture(event: string, properties?: {
-        [key: string]: any;
-    }, options?: PostHogCaptureOptions): void;
+    capture(event: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     alias(alias: string): void;
     autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
-    groups(groups: {
-        [type: string]: string | number;
-    }): void;
+    groups(groups: PostHogGroupProperties): void;
     group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
@@ -603,7 +612,7 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     private _decideAsync;
     private setKnownFeatureFlagDetails;
     private getKnownFeatureFlagDetails;
-    private getKnownFeatureFlags;
+    protected getKnownFeatureFlags(): PostHogDecideResponse['featureFlags'] | undefined;
     private getKnownFeatureFlagPayloads;
     private getBootstrappedFeatureFlagDetails;
     private setBootstrappedFeatureFlagDetails;
@@ -628,9 +637,7 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     /***
      *** ERROR TRACKING
      ***/
-    captureException(error: unknown, additionalProperties?: {
-        [key: string]: any;
-    }): void;
+    captureException(error: unknown, additionalProperties?: PostHogEventProperties): void;
     /**
      * Capture written user feedback for a LLM trace. Numeric values are converted to strings.
      * @param traceId The trace ID to capture feedback for.
@@ -666,7 +673,7 @@ declare class PostHog extends PostHogCore {
     getLibraryId(): string;
     getLibraryVersion(): string;
     getCustomUserAgent(): void;
-    getCommonEventProperties(): any;
+    getCommonEventProperties(): PostHogEventProperties;
     private setupHistoryEventTracking;
     private captureNavigationEvent;
 }

package/lib/index.mjs

@@ -1,4 +1,4 @@
-var version = "3.5.1";
+var version = "3.6.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -15,6 +15,7 @@ var PostHogPersistedProperty;
     PostHogPersistedProperty["Queue"] = "queue";
     PostHogPersistedProperty["OptedOut"] = "opted_out";
     PostHogPersistedProperty["SessionId"] = "session_id";
+    PostHogPersistedProperty["SessionStartTimestamp"] = "session_start_timestamp";
     PostHogPersistedProperty["SessionLastTimestamp"] = "session_timestamp";
     PostHogPersistedProperty["PersonProperties"] = "person_properties";
     PostHogPersistedProperty["GroupProperties"] = "group_properties";
@@ -367,6 +368,9 @@ function isTokenInRollout(token, percentage = 0, excludedHashes) {
     const hashInt = parseInt(tokenHash, 16);
     const hashFloat = hashInt / 0xffffffff;
     return hashFloat < percentage;
+}
+function allSettled(promises) {
+    return Promise.all(promises.map((p) => (p ?? Promise.resolve()).then((value) => ({ status: 'fulfilled', value }), (reason) => ({ status: 'rejected', reason }))));
 }
 
 // Copyright (c) 2013 Pieroxy <pieroxy@pieroxy.net>
@@ -1257,6 +1261,7 @@ class PostHogFetchNetworkError extends Error {
         this.name = 'PostHogFetchNetworkError';
     }
 }
+const maybeAdd = (key, value) => value !== undefined ? { [key]: value } : {};
 async function logFlushError(err) {
     if (err instanceof PostHogFetchHttpError) {
         let text = '';
@@ -1517,6 +1522,7 @@ class PostHogCoreStateless {
                 ...extraPayload,
             }),
         };
+        this.logMsgIfDebug(() => console.log('PostHog Debug', 'Decide URL', url));
         // Don't retry /decide API calls
         return this.fetchWithRetry(url, fetchOptions, { retryCount: 0 }, this.featureFlagsRequestTimeoutMs)
             .then((response) => response.json())
@@ -1634,7 +1640,7 @@ class PostHogCoreStateless {
     async getSurveysStateless() {
         await this._initPromise;
         if (this.disableSurveys === true) {
-            this.logMsgIfDebug(() => console.log('Loading surveys is disabled.'));
+            this.logMsgIfDebug(() => console.log('PostHog Debug', 'Loading surveys is disabled.'));
             return [];
         }
         const url = `${this.host}/api/surveys/?token=${this.apiKey}`;
@@ -1757,7 +1763,6 @@ class PostHogCoreStateless {
         }
         catch (err) {
             this._events.emit('error', err);
-            throw err;
         }
     }
     prepareMessage(type, _message, options) {
@@ -1797,15 +1802,38 @@ class PostHogCoreStateless {
             await logFlushError(err);
         });
     }
+    /**
+     * Flushes the queue
+     *
+     * This function will return a promise that will resolve when the flush is complete,
+     * or reject if there was an error (for example if the server or network is down).
+     *
+     * If there is already a flush in progress, this function will wait for that flush to complete.
+     *
+     * It's recommended to do error handling in the callback of the promise.
+     *
+     * @example
+     * posthog.flush().then(() => {
+     *   console.log('Flush complete')
+     * }).catch((err) => {
+     *   console.error('Flush failed', err)
+     * })
+     *
+     *
+     * @throws PostHogFetchHttpError
+     * @throws PostHogFetchNetworkError
+     * @throws Error
+     */
     async flush() {
         // 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.
-        const nextFlushPromise = Promise.allSettled([this.flushPromise]).then(() => {
+        // Use a custom allSettled implementation to avoid issues with patching Promise on RN
+        const nextFlushPromise = allSettled([this.flushPromise]).then(() => {
             return this._flush();
         });
         this.flushPromise = nextFlushPromise;
         void this.addPendingPromise(nextFlushPromise);
-        Promise.allSettled([nextFlushPromise]).then(() => {
+        allSettled([nextFlushPromise]).then(() => {
             // If there are no others waiting to flush, clear the promise.
             // We don't strictly need to do this, but it could make debugging easier
             if (this.flushPromise === nextFlushPromise) {
@@ -1831,7 +1859,7 @@ class PostHogCoreStateless {
         await this._initPromise;
         let queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
         if (!queue.length) {
-            return [];
+            return;
         }
         const sentMessages = [];
         const originalQueueLength = queue.length;
@@ -1902,7 +1930,6 @@ class PostHogCoreStateless {
             sentMessages.push(...batchMessages);
         }
         this._events.emit('flush', sentMessages);
-        return sentMessages;
     }
     async fetchWithRetry(url, options, retryOptions, requestTimeout) {
         var _a;
@@ -1912,7 +1939,14 @@ class PostHogCoreStateless {
             return ctrl.signal;
         });
         const body = options.body ? options.body : '';
-        const reqByteLength = Buffer.byteLength(body, STRING_FORMAT);
+        let reqByteLength = -1;
+        try {
+            reqByteLength = Buffer.byteLength(body, STRING_FORMAT);
+        }
+        catch {
+            const encoded = new TextEncoder().encode(body);
+            reqByteLength = encoded.length;
+        }
         return await retriable(async () => {
             let res = null;
             try {
@@ -2001,6 +2035,7 @@ class PostHogCore extends PostHogCoreStateless {
         const featureFlagsRequestTimeoutMs = options?.featureFlagsRequestTimeoutMs ?? 10000; // 10 seconds
         super(apiKey, { ...options, disableGeoip: disableGeoipOption, featureFlagsRequestTimeoutMs });
         this.flagCallReported = {};
+        this._sessionMaxLengthSeconds = 24 * 60 * 60; // 24 hours
         this.sessionProps = {};
         this.sendFeatureFlagEvent = options?.sendFeatureFlagEvent ?? true;
         this._sessionExpirationTimeSeconds = options?.sessionExpirationTimeSeconds ?? 1800; // 30 minutes
@@ -2074,7 +2109,7 @@ class PostHogCore extends PostHogCoreStateless {
             }
         }
         return {
-            $active_feature_flags: featureFlags ? Object.keys(featureFlags) : undefined,
+            ...maybeAdd('$active_feature_flags', featureFlags ? Object.keys(featureFlags) : undefined),
             ...featureVariantProperties,
             ...super.getCommonEventProperties(),
         };
@@ -2096,18 +2131,26 @@ class PostHogCore extends PostHogCoreStateless {
             return '';
         }
         let sessionId = this.getPersistedProperty(PostHogPersistedProperty.SessionId);
-        const sessionTimestamp = this.getPersistedProperty(PostHogPersistedProperty.SessionLastTimestamp) || 0;
-        if (!sessionId || Date.now() - sessionTimestamp > this._sessionExpirationTimeSeconds * 1000) {
+        const sessionLastTimestamp = this.getPersistedProperty(PostHogPersistedProperty.SessionLastTimestamp) || 0;
+        const sessionStartTimestamp = this.getPersistedProperty(PostHogPersistedProperty.SessionStartTimestamp) || 0;
+        const now = Date.now();
+        const sessionLastDif = now - sessionLastTimestamp;
+        const sessionStartDif = now - sessionStartTimestamp;
+        if (!sessionId ||
+            sessionLastDif > this._sessionExpirationTimeSeconds * 1000 ||
+            sessionStartDif > this._sessionMaxLengthSeconds * 1000) {
             sessionId = uuidv7();
             this.setPersistedProperty(PostHogPersistedProperty.SessionId, sessionId);
+            this.setPersistedProperty(PostHogPersistedProperty.SessionStartTimestamp, now);
         }
-        this.setPersistedProperty(PostHogPersistedProperty.SessionLastTimestamp, Date.now());
+        this.setPersistedProperty(PostHogPersistedProperty.SessionLastTimestamp, now);
         return sessionId;
     }
     resetSessionId() {
         this.wrap(() => {
             this.setPersistedProperty(PostHogPersistedProperty.SessionId, null);
             this.setPersistedProperty(PostHogPersistedProperty.SessionLastTimestamp, null);
+            this.setPersistedProperty(PostHogPersistedProperty.SessionStartTimestamp, null);
         });
     }
     /**
@@ -2159,8 +2202,8 @@ class PostHogCore extends PostHogCoreStateless {
             const userProps = properties?.$set || properties;
             const allProperties = this.enrichProperties({
                 $anon_distinct_id: this.getAnonymousId(),
-                $set: userProps,
-                $set_once: userPropsOnce,
+                ...maybeAdd('$set', userProps),
+                ...maybeAdd('$set_once', userPropsOnce),
             });
             if (distinctId !== previousDistinctId) {
                 // We keep the AnonymousId to be used by decide calls and identify to link the previousId
@@ -2308,14 +2351,16 @@ class PostHogCore extends PostHogCoreStateless {
         }
         return this._decideAsync(sendAnonDistinctId);
     }
-    cacheSessionReplay(response) {
+    cacheSessionReplay(source, response) {
         const sessionReplay = response?.sessionRecording;
         if (sessionReplay) {
             this.setPersistedProperty(PostHogPersistedProperty.SessionReplay, sessionReplay);
-            this.logMsgIfDebug(() => console.log('PostHog Debug', 'Session replay config: ', JSON.stringify(sessionReplay)));
+            this.logMsgIfDebug(() => console.log('PostHog Debug', `Session replay config from ${source}: `, JSON.stringify(sessionReplay)));
         }
-        else {
-            this.logMsgIfDebug(() => console.info('PostHog Debug', 'Session replay config disabled.'));
+        else if (typeof sessionReplay === 'boolean' && sessionReplay === false) {
+            // if session replay is disabled, we don't need to cache it
+            // we need to check for this because the response might be undefined (/flags does not return sessionRecording yet)
+            this.logMsgIfDebug(() => console.info('PostHog Debug', `Session replay config from ${source} disabled.`));
             this.setPersistedProperty(PostHogPersistedProperty.SessionReplay, null);
         }
     }
@@ -2329,25 +2374,30 @@ class PostHogCore extends PostHogCoreStateless {
                     const remoteConfigWithoutSurveys = { ...response };
                     delete remoteConfigWithoutSurveys.surveys;
                     this.logMsgIfDebug(() => console.log('PostHog Debug', 'Fetched remote config: ', JSON.stringify(remoteConfigWithoutSurveys)));
-                    const surveys = response.surveys;
-                    let hasSurveys = true;
-                    if (!Array.isArray(surveys)) {
-                        // If surveys is not an array, it means there are no surveys (its a boolean instead)
-                        this.logMsgIfDebug(() => console.log('PostHog Debug', 'There are no surveys.'));
-                        hasSurveys = false;
-                    }
-                    else {
-                        this.logMsgIfDebug(() => console.log('PostHog Debug', 'Surveys fetched from remote config: ', JSON.stringify(surveys)));
-                    }
-                    if (this.disableSurveys === false && hasSurveys) {
-                        this.setPersistedProperty(PostHogPersistedProperty.Surveys, surveys);
+                    if (this.disableSurveys === false) {
+                        const surveys = response.surveys;
+                        let hasSurveys = true;
+                        if (!Array.isArray(surveys)) {
+                            // If surveys is not an array, it means there are no surveys (its a boolean instead)
+                            this.logMsgIfDebug(() => console.log('PostHog Debug', 'There are no surveys.'));
+                            hasSurveys = false;
+                        }
+                        else {
+                            this.logMsgIfDebug(() => console.log('PostHog Debug', 'Surveys fetched from remote config: ', JSON.stringify(surveys)));
+                        }
+                        if (hasSurveys) {
+                            this.setPersistedProperty(PostHogPersistedProperty.Surveys, surveys);
+                        }
+                        else {
+                            this.setPersistedProperty(PostHogPersistedProperty.Surveys, null);
+                        }
                     }
                     else {
                         this.setPersistedProperty(PostHogPersistedProperty.Surveys, null);
                     }
                     // we cache the surveys in its own storage key
                     this.setPersistedProperty(PostHogPersistedProperty.RemoteConfig, remoteConfigWithoutSurveys);
-                    this.cacheSessionReplay(response);
+                    this.cacheSessionReplay('remote config', response);
                     // we only dont load flags if the remote config has no feature flags
                     if (response.hasFeatureFlags === false) {
                         // resetting flags to empty object
@@ -2404,7 +2454,7 @@ class PostHogCore extends PostHogCoreStateless {
                 this.setKnownFeatureFlagDetails(newFeatureFlagDetails);
                 // Mark that we hit the /decide endpoint so we can capture this in the $feature_flag_called event
                 this.setPersistedProperty(PostHogPersistedProperty.DecideEndpointWasHit, true);
-                this.cacheSessionReplay(res);
+                this.cacheSessionReplay('decide/flags', res);
             }
             return res;
         })
@@ -2490,14 +2540,14 @@ class PostHogCore extends PostHogCoreStateless {
             this.capture('$feature_flag_called', {
                 $feature_flag: key,
                 $feature_flag_response: response,
-                $feature_flag_id: featureFlag?.metadata?.id,
-                $feature_flag_version: featureFlag?.metadata?.version,
-                $feature_flag_reason: featureFlag?.reason?.description ?? featureFlag?.reason?.code,
-                $feature_flag_bootstrapped_response: bootstrappedResponse,
-                $feature_flag_bootstrapped_payload: bootstrappedPayload,
+                ...maybeAdd('$feature_flag_id', featureFlag?.metadata?.id),
+                ...maybeAdd('$feature_flag_version', featureFlag?.metadata?.version),
+                ...maybeAdd('$feature_flag_reason', featureFlag?.reason?.description ?? featureFlag?.reason?.code),
+                ...maybeAdd('$feature_flag_bootstrapped_response', bootstrappedResponse),
+                ...maybeAdd('$feature_flag_bootstrapped_payload', bootstrappedPayload),
                 // If we haven't yet received a response from the /decide endpoint, we must have used the bootstrapped value
                 $used_bootstrap_value: !this.getPersistedProperty(PostHogPersistedProperty.DecideEndpointWasHit),
-                $feature_flag_request_id: details.requestId,
+                ...maybeAdd('$feature_flag_request_id', details.requestId),
             });
         }
         // If we have flags we either return the value (true or string) or false
@@ -2571,7 +2621,7 @@ class PostHogCore extends PostHogCoreStateless {
             .catch((e) => {
             cb?.(e, undefined);
             if (!cb) {
-                this.logMsgIfDebug(() => console.log('[PostHog] Error reloading feature flags', e));
+                this.logMsgIfDebug(() => console.log('PostHog Debug', 'Error reloading feature flags', e));
             }
         });
     }