posthog-js-lite 2.6.1 → 3.0.0-beta.1

package/lib/posthog-core/src/index.d.ts

@@ -1,4 +1,4 @@
-import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PosthogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType } from './types';
+import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PostHogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType } from './types';
 import { RetriableOptions } from './utils';
 export * as utils from './utils';
 import { LZString } from './lz-string';
@@ -9,44 +9,49 @@ export declare abstract class PostHogCoreStateless {
     private flushAt;
     private flushInterval;
     private requestTimeout;
+    private featureFlagsRequestTimeoutMs;
     private captureMode;
     private removeDebugCallback?;
-    private debugMode;
     private disableGeoip;
-    private _optoutOverride;
+    disabled: boolean;
+    private defaultOptIn;
     private pendingPromises;
     protected _events: SimpleEventEmitter;
     protected _flushTimer?: any;
     protected _retryOptions: RetriableOptions;
+    protected _initPromise: Promise<void>;
+    protected _isInitialized: boolean;
     abstract fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse>;
     abstract getLibraryId(): string;
     abstract getLibraryVersion(): string;
     abstract getCustomUserAgent(): string | void;
     abstract getPersistedProperty<T>(key: PostHogPersistedProperty): T | undefined;
     abstract setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected wrap(fn: () => void): void;
     protected getCommonEventProperties(): any;
     get optedOut(): boolean;
-    optIn(): void;
-    optOut(): void;
+    optIn(): Promise<void>;
+    optOut(): Promise<void>;
     on(event: string, cb: (...args: any[]) => void): () => void;
     debug(enabled?: boolean): void;
+    get isDebug(): boolean;
     private buildPayload;
     protected addPendingPromise(promise: Promise<any>): void;
     /***
      *** TRACKING
      ***/
-    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
-    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): this;
+    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): void;
     /***
      *** FEATURE FLAGS
      ***/
@@ -67,8 +72,8 @@ export declare abstract class PostHogCoreStateless {
     flushAsync(): Promise<any>;
     flush(callback?: (err?: any, data?: any) => void): void;
     private fetchWithRetry;
-    shutdownAsync(): Promise<void>;
-    shutdown(): void;
+    shutdownAsync(shutdownTimeoutMs?: number): Promise<void>;
+    shutdown(shutdownTimeoutMs?: number): void;
 }
 export declare abstract class PostHogCore extends PostHogCoreStateless {
     private sendFeatureFlagEvent;
@@ -76,8 +81,8 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     protected _decideResponsePromise?: Promise<PostHogDecideResponse | undefined>;
     protected _sessionExpirationTimeSeconds: number;
     protected sessionProps: PostHogEventProperties;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
-    protected setupBootstrap(options?: Partial<PosthogCoreOptions>): void;
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
     private get props();
     private set props(value);
     private clearProps;
@@ -85,15 +90,24 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     on(event: string, cb: (...args: any[]) => void): () => void;
     reset(propertiesToKeep?: PostHogPersistedProperty[]): void;
     protected getCommonEventProperties(): any;
-    enrichProperties(properties?: PostHogEventProperties): any;
-    getSessionId(): string | undefined;
+    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.
+     */
+    getSessionId(): string;
     resetSessionId(): void;
+    /**
+     * * @returns {string} The stored anonymous ID. This may be an empty string if the client is not yet fully initialized.
+     */
     getAnonymousId(): string;
+    /**
+     * * @returns {string} The stored distinct ID. This may be an empty string if the client is not yet fully initialized.
+     */
     getDistinctId(): string;
-    unregister(property: string): void;
+    unregister(property: string): Promise<void>;
     register(properties: {
         [key: string]: any;
-    }): void;
+    }): Promise<void>;
     registerForSession(properties: {
         [key: string]: any;
     }): void;
@@ -101,39 +115,39 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     /***
      *** TRACKING
      ***/
-    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     capture(event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
-    alias(alias: string): this;
-    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
+    alias(alias: string): void;
+    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
     groups(groups: {
         [type: string]: string | number;
-    }): this;
-    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
-    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    }): void;
+    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
      * PROPERTIES
      ***/
     setPersonPropertiesForFlags(properties: {
         [type: string]: string;
-    }): this;
+    }): void;
     resetPersonPropertiesForFlags(): void;
     /** @deprecated - Renamed to setPersonPropertiesForFlags */
     personProperties(properties: {
         [type: string]: string;
-    }): this;
+    }): void;
     setGroupPropertiesForFlags(properties: {
         [type: string]: Record<string, string>;
-    }): this;
+    }): void;
     resetGroupPropertiesForFlags(): void;
     /** @deprecated - Renamed to setGroupPropertiesForFlags */
     groupProperties(properties: {
         [type: string]: Record<string, string>;
-    }): this;
+    }): void;
     /***
      *** FEATURE FLAGS
      ***/
@@ -154,7 +168,7 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     reloadFeatureFlagsAsync(sendAnonDistinctId?: boolean): Promise<PostHogDecideResponse['featureFlags'] | undefined>;
     onFeatureFlags(cb: (flags: PostHogDecideResponse['featureFlags']) => void): () => void;
     onFeatureFlag(key: string, cb: (value: string | boolean) => void): () => void;
-    overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): void;
+    overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): Promise<void>;
 }
 export * from './types';
 export { LZString };

package/lib/posthog-core/src/types.d.ts

@@ -1,20 +1,36 @@
-export declare type PosthogCoreOptions = {
+export declare type PostHogCoreOptions = {
+    /** PostHog API host, usually 'https://app.posthog.com' or 'https://eu.posthog.com' */
     host?: string;
+    /** The number of events to queue before sending to PostHog (flushing) */
     flushAt?: number;
+    /** The interval in milliseconds between periodic flushes */
     flushInterval?: number;
-    enable?: boolean;
+    /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */
+    disabled?: boolean;
+    /** If set to false the SDK will not track until the `optIn` function is called. */
+    defaultOptIn?: boolean;
+    /** Whether to track that `getFeatureFlag` was called (used by Experiments) */
     sendFeatureFlagEvent?: boolean;
+    /** Whether to load feature flags when initialized or not */
     preloadFeatureFlags?: boolean;
+    /** Option to bootstrap the library with given distinctId and feature flags */
     bootstrap?: {
         distinctId?: string;
         isIdentifiedId?: boolean;
         featureFlags?: Record<string, boolean | string>;
         featureFlagPayloads?: Record<string, JsonType>;
     };
+    /** How many times we will retry HTTP requests. Defaults to 3. */
     fetchRetryCount?: number;
+    /** The delay between HTTP request retries, Defaults to 3 seconds. */
     fetchRetryDelay?: number;
+    /** Timeout in milliseconds for any calls. Defaults to 10 seconds. */
     requestTimeout?: number;
+    /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */
+    featureFlagsRequestTimeoutMs?: number;
+    /** For Session Analysis how long before we expire a session (defaults to 30 mins) */
     sessionExpirationTimeSeconds?: number;
+    /** Whether to post events to PostHog in JSON or compressed format */
     captureMode?: 'json' | 'form';
     disableGeoip?: boolean;
 };
@@ -92,7 +108,7 @@ export declare type PostHogDecideResponse = {
     errorsWhileComputingFlags: boolean;
     sessionRecording: boolean;
 };
-export declare type PosthogFlagsAndPayloadsResponse = {
+export declare type PostHogFlagsAndPayloadsResponse = {
     featureFlags: PostHogDecideResponse['featureFlags'];
     featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];
 };

package/lib/posthog-core/src/utils.d.ts

@@ -1,11 +1,12 @@
 export declare function assert(truthyValue: any, message: string): void;
 export declare function removeTrailingSlash(url: string): string;
 export interface RetriableOptions {
-    retryCount?: number;
-    retryDelay?: number;
-    retryCheck?: (err: any) => boolean;
+    retryCount: number;
+    retryDelay: number;
+    retryCheck: (err: any) => boolean;
 }
-export declare function retriable<T>(fn: () => Promise<T>, props?: RetriableOptions): Promise<T>;
+export declare function retriable<T>(fn: () => Promise<T>, props: RetriableOptions): Promise<T>;
 export declare function currentTimestamp(): number;
 export declare function currentISOTime(): string;
 export declare function safeSetTimeout(fn: () => void, timeout: number): any;
+export declare const isPromise: (obj: any) => obj is Promise<any>;

package/lib/posthog-core/src/vendor/uuidv7.d.ts

@@ -0,0 +1,179 @@
+/** Represents a UUID as a 16-byte byte array. */
+export declare class UUID {
+    readonly bytes: Readonly<Uint8Array>;
+    /** @param bytes - The 16-byte byte array representation. */
+    private constructor();
+    /**
+     * Creates an object from the internal representation, a 16-byte byte array
+     * containing the binary UUID representation in the big-endian byte order.
+     *
+     * This method does NOT shallow-copy the argument, and thus the created object
+     * holds the reference to the underlying buffer.
+     *
+     * @throws TypeError if the length of the argument is not 16.
+     */
+    static ofInner(bytes: Readonly<Uint8Array>): UUID;
+    /**
+     * Builds a byte array from UUIDv7 field values.
+     *
+     * @param unixTsMs - A 48-bit `unix_ts_ms` field value.
+     * @param randA - A 12-bit `rand_a` field value.
+     * @param randBHi - The higher 30 bits of 62-bit `rand_b` field value.
+     * @param randBLo - The lower 32 bits of 62-bit `rand_b` field value.
+     * @throws RangeError if any field value is out of the specified range.
+     */
+    static fromFieldsV7(unixTsMs: number, randA: number, randBHi: number, randBLo: number): UUID;
+    /**
+     * Builds a byte array from a string representation.
+     *
+     * This method accepts the following formats:
+     *
+     * - 32-digit hexadecimal format without hyphens: `0189dcd553117d408db09496a2eef37b`
+     * - 8-4-4-4-12 hyphenated format: `0189dcd5-5311-7d40-8db0-9496a2eef37b`
+     * - Hyphenated format with surrounding braces: `{0189dcd5-5311-7d40-8db0-9496a2eef37b}`
+     * - RFC 4122 URN format: `urn:uuid:0189dcd5-5311-7d40-8db0-9496a2eef37b`
+     *
+     * Leading and trailing whitespaces represents an error.
+     *
+     * @throws SyntaxError if the argument could not parse as a valid UUID string.
+     */
+    static parse(uuid: string): UUID;
+    /**
+     * @returns The 8-4-4-4-12 canonical hexadecimal string representation
+     * (`0189dcd5-5311-7d40-8db0-9496a2eef37b`).
+     */
+    toString(): string;
+    /**
+     * @returns The 32-digit hexadecimal representation without hyphens
+     * (`0189dcd553117d408db09496a2eef37b`).
+     */
+    toHex(): string;
+    /** @returns The 8-4-4-4-12 canonical hexadecimal string representation. */
+    toJSON(): string;
+    /**
+     * Reports the variant field value of the UUID or, if appropriate, "NIL" or
+     * "MAX".
+     *
+     * For convenience, this method reports "NIL" or "MAX" if `this` represents
+     * the Nil or Max UUID, although the Nil and Max UUIDs are technically
+     * subsumed under the variants `0b0` and `0b111`, respectively.
+     */
+    getVariant(): "VAR_0" | "VAR_10" | "VAR_110" | "VAR_RESERVED" | "NIL" | "MAX";
+    /**
+     * Returns the version field value of the UUID or `undefined` if the UUID does
+     * not have the variant field value of `0b10`.
+     */
+    getVersion(): number | undefined;
+    /** Creates an object from `this`. */
+    clone(): UUID;
+    /** Returns true if `this` is equivalent to `other`. */
+    equals(other: UUID): boolean;
+    /**
+     * Returns a negative integer, zero, or positive integer if `this` is less
+     * than, equal to, or greater than `other`, respectively.
+     */
+    compareTo(other: UUID): number;
+}
+/**
+ * Encapsulates the monotonic counter state.
+ *
+ * This class provides APIs to utilize a separate counter state from that of the
+ * global generator used by {@link uuidv7} and {@link uuidv7obj}. In addition to
+ * the default {@link generate} method, this class has {@link generateOrAbort}
+ * that is useful to absolutely guarantee the monotonically increasing order of
+ * generated UUIDs. See their respective documentation for details.
+ */
+export declare class V7Generator {
+    private timestamp;
+    private counter;
+    /** The random number generator used by the generator. */
+    private readonly random;
+    /**
+     * Creates a generator object with the default random number generator, or
+     * with the specified one if passed as an argument. The specified random
+     * number generator should be cryptographically strong and securely seeded.
+     */
+    constructor(randomNumberGenerator?: {
+        /** Returns a 32-bit random unsigned integer. */
+        nextUint32(): number;
+    });
+    /**
+     * Generates a new UUIDv7 object from the current timestamp, or resets the
+     * generator upon significant timestamp rollback.
+     *
+     * This method returns a monotonically increasing UUID by reusing the previous
+     * timestamp even if the up-to-date timestamp is smaller than the immediately
+     * preceding UUID's. However, when such a clock rollback is considered
+     * significant (i.e., by more than ten seconds), this method resets the
+     * generator and returns a new UUID based on the given timestamp, breaking the
+     * increasing order of UUIDs.
+     *
+     * See {@link generateOrAbort} for the other mode of generation and
+     * {@link generateOrResetCore} for the low-level primitive.
+     */
+    generate(): UUID;
+    /**
+     * Generates a new UUIDv7 object from the current timestamp, or returns
+     * `undefined` upon significant timestamp rollback.
+     *
+     * This method returns a monotonically increasing UUID by reusing the previous
+     * timestamp even if the up-to-date timestamp is smaller than the immediately
+     * preceding UUID's. However, when such a clock rollback is considered
+     * significant (i.e., by more than ten seconds), this method aborts and
+     * returns `undefined` immediately.
+     *
+     * See {@link generate} for the other mode of generation and
+     * {@link generateOrAbortCore} for the low-level primitive.
+     */
+    generateOrAbort(): UUID | undefined;
+    /**
+     * Generates a new UUIDv7 object from the `unixTsMs` passed, or resets the
+     * generator upon significant timestamp rollback.
+     *
+     * This method is equivalent to {@link generate} except that it takes a custom
+     * timestamp and clock rollback allowance.
+     *
+     * @param rollbackAllowance - The amount of `unixTsMs` rollback that is
+     * considered significant. A suggested value is `10_000` (milliseconds).
+     * @throws RangeError if `unixTsMs` is not a 48-bit positive integer.
+     */
+    generateOrResetCore(unixTsMs: number, rollbackAllowance: number): UUID;
+    /**
+     * Generates a new UUIDv7 object from the `unixTsMs` passed, or returns
+     * `undefined` upon significant timestamp rollback.
+     *
+     * This method is equivalent to {@link generateOrAbort} except that it takes a
+     * custom timestamp and clock rollback allowance.
+     *
+     * @param rollbackAllowance - The amount of `unixTsMs` rollback that is
+     * considered significant. A suggested value is `10_000` (milliseconds).
+     * @throws RangeError if `unixTsMs` is not a 48-bit positive integer.
+     */
+    generateOrAbortCore(unixTsMs: number, rollbackAllowance: number): UUID | undefined;
+    /** Initializes the counter at a 42-bit random integer. */
+    private resetCounter;
+    /**
+     * Generates a new UUIDv4 object utilizing the random number generator inside.
+     *
+     * @internal
+     */
+    generateV4(): UUID;
+}
+/**
+ * Generates a UUIDv7 string.
+ *
+ * @returns The 8-4-4-4-12 canonical hexadecimal string representation
+ * ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").
+ */
+export declare const uuidv7: () => string;
+/** Generates a UUIDv7 object. */
+export declare const uuidv7obj: () => UUID;
+/**
+ * Generates a UUIDv4 string.
+ *
+ * @returns The 8-4-4-4-12 canonical hexadecimal string representation
+ * ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").
+ */
+export declare const uuidv4: () => string;
+/** Generates a UUIDv4 object. */
+export declare const uuidv4obj: () => UUID;

package/lib/posthog-web/src/types.d.ts

@@ -1,6 +1,6 @@
-import { PosthogCoreOptions } from '../../posthog-core/src';
+import { PostHogCoreOptions } from '../../posthog-core/src';
 export declare type PostHogOptions = {
     autocapture?: boolean;
     persistence?: 'localStorage' | 'sessionStorage' | 'cookie' | 'memory';
     persistence_name?: string;
-} & PosthogCoreOptions;
+} & PostHogCoreOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-js-lite",
-  "version": "2.6.1",
+  "version": "3.0.0-beta.1",
   "main": "lib/index.cjs.js",
   "module": "lib/index.esm.js",
   "types": "lib/index.d.ts",

package/src/types.ts

@@ -1,7 +1,7 @@
-import { PosthogCoreOptions } from '../../posthog-core/src'
+import { PostHogCoreOptions } from '../../posthog-core/src'
 
 export type PostHogOptions = {
   autocapture?: boolean
   persistence?: 'localStorage' | 'sessionStorage' | 'cookie' | 'memory'
   persistence_name?: string
-} & PosthogCoreOptions
+} & PostHogCoreOptions

package/test/posthog-web.spec.ts

@@ -2,9 +2,10 @@
  * @jest-environment jsdom
  */
 
+import { waitForPromises } from 'posthog-core/test/test-utils/test-utils'
 import { PostHog } from '..'
 
-describe('PosthogWeb', () => {
+describe('PostHogWeb', () => {
   let fetch: jest.Mock
   jest.useRealTimers()
 
@@ -41,13 +42,14 @@ describe('PosthogWeb', () => {
   })
 
   describe('init', () => {
-    it('should initialise', () => {
+    it('should initialise', async () => {
       const posthog = new PostHog('TEST_API_KEY', {
         flushAt: 1,
       })
       expect(posthog.optedOut).toEqual(false)
 
       posthog.capture('test')
+      await waitForPromises()
 
       expect(fetch).toHaveBeenCalledTimes(2)
     })
@@ -57,6 +59,8 @@ describe('PosthogWeb', () => {
         flushAt: 1,
       })
 
+      await waitForPromises()
+
       expect(fetch).toHaveBeenCalledWith('https://app.posthog.com/decide/?v=3', {
         body: JSON.stringify({
           token: 'TEST_API_KEY',

package/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    "lib": ["DOM", "ES2015", "ES2022.Error"]
+    "lib": ["DOM", "ES2020", "ES2022.Error"]
   }
 }