@workleap/mixpanel 2.1.9 → 3.0.0

package/src/js/initializeMixpanel.ts

@@ -1,12 +1,54 @@
+import { HasExecutedGuard, type LogRocketInstrumentationPartialClient, type TelemetryContext } from "@workleap-telemetry/core";
 import { createCompositeLogger, type Logger, type RootLogger } from "@workleap/logging";
-import { createBootstrappingStore, createTelemetryContext } from "@workleap/telemetry";
 import { setMixpanelContext } from "./context.ts";
-import { getTrackingEndpoint, type Environment } from "./env.ts";
-import { HasExecutedGuard } from "./HasExecutedGuard.ts";
-import { getSuperProperties, getTelemetryProperties, OtherProperties, setSuperProperties, setSuperProperty } from "./properties.ts";
+import { getTrackingEndpoint, type MixpanelEnvironment } from "./env.ts";
+import { MixpanelClient, type MixpanelGlobalEventProperties } from "./MixpanelClient.ts";
+import { getTelemetryProperties, OtherProperties } from "./properties.ts";
 
+// DEPRECATED: Grace period ends on January 1th 2026.
+// Don't forget to remove the tests as well.
 export const IsInitializedVariableName = "__WLP_MIXPANEL_IS_INITIALIZED__";
 
+// DEPRECATED: Grace period ends on January 1th 2026.
+function registerDeprecatedContextAndGlobalVariables(productId: string, endpoint: string, globalEventProperties: Map<string, unknown>, logger: Logger) {
+    setMixpanelContext({
+        productId,
+        endpoint,
+        globalEventProperties,
+        logger
+    });
+
+    // Indicates to the host applications that Mixpanel has been initialized.
+    // It's useful in cases where an "add-on", like the platform widgets needs
+    // to know whether or not the host application is using Mixpanel.
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    globalThis[IsInitializedVariableName] = true;
+}
+
+///////////////////////////
+
+let registrationGuardInstance: HasExecutedGuard | undefined;
+
+// It's important to use a lazy singleton instead of a singleton to avoid
+// any future probleme related to HMR, tree-shaking, SSR, etc..
+function getRegistrationGuard() {
+    if (!registrationGuardInstance) {
+        registrationGuardInstance = new HasExecutedGuard();
+    }
+
+    return registrationGuardInstance;
+}
+
+// This function should only be used by tests.
+export function __resetRegistrationGuard() {
+    if (registrationGuardInstance) {
+        registrationGuardInstance.reset();
+    }
+}
+
+///////////////////////////
+
 /**
  * @see {@link https://workleap.github.io/wl-telemetry}
  */
@@ -14,96 +56,104 @@ export interface InitializeMixpanelOptions {
     /**
      * An optional tracking endpoint.
      * @default "tracking/track"
+     * @see {@link https://workleap.github.io/wl-telemetry}
      */
     trackingEndpoint?: string;
+    /**
+     * Context including telemetry correlation ids.
+     * @see {@link https://workleap.github.io/wl-telemetry}
+     */
+    telemetryContext?: TelemetryContext;
+    /**
+     * An optional LogRocket client to automatically add the LogRocket
+     * session URL to Mixpanel events once it's available.
+     * @see {@link https://workleap.github.io/wl-telemetry}
+     */
+    logRocketInstrumentationClient?: LogRocketInstrumentationPartialClient;
     /**
      * Whether or not debug information should be logged to the console.
+     * @see {@link https://workleap.github.io/wl-telemetry}
      */
     verbose?: boolean;
     /**
      * An array of RootLogger instances.
+     * @see {@link https://workleap.github.io/wl-telemetry}
      */
     loggers?: RootLogger[];
 }
 
-function registerLogRocketSessionUrlListener(logger: Logger) {
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    if (globalThis.__WLP_LOGROCKET_INSTRUMENTATION_REGISTER_GET_SESSION_URL_LISTENER__) {
-        // Automatically add the LogRocket session URL to all Honeycomb traces as an attribute.
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        globalThis.__WLP_LOGROCKET_INSTRUMENTATION_REGISTER_GET_SESSION_URL_LISTENER__((sessionUrl: string) => {
-            logger
-                .withText("[mixpanel] Received LogRocket session replay URL:")
-                .withText(sessionUrl)
-                .debug();
-
-            setSuperProperty(OtherProperties.LogRocketSessionUrl, sessionUrl);
-        });
-    } else {
-        logger.information("[mixpanel] Cannot integrate with LogRocket because \"globalThis.__WLP_LOGROCKET_INSTRUMENTATION_REGISTER_GET_SESSION_URL_LISTENER__\" is not available.");
+
+export class MixpanelInitializer {
+    readonly #globalEventProperties: MixpanelGlobalEventProperties;
+
+    constructor(globalEventProperties: MixpanelGlobalEventProperties) {
+        this.#globalEventProperties = globalEventProperties;
     }
-}
 
-const initializationGuard = new HasExecutedGuard();
+    initialize(
+        productId: string,
+        envOrTrackingApiBaseUrl: MixpanelEnvironment | (string & {}),
+        options: InitializeMixpanelOptions = {}
+    ) {
+        const {
+            trackingEndpoint,
+            telemetryContext,
+            logRocketInstrumentationClient,
+            verbose = false,
+            loggers = []
+        } = options;
 
-// This function should only be used by tests.
-export function __resetInitializationGuard() {
-    initializationGuard.reset();
+        const logger = createCompositeLogger(verbose, loggers);
+        const endpoint = getTrackingEndpoint(envOrTrackingApiBaseUrl, trackingEndpoint);
+
+        // Set the telemetry correlation ids on every Mixpanel event.
+        if (telemetryContext) {
+            for (const [key, value] of Object.entries(getTelemetryProperties(telemetryContext))) {
+                this.#globalEventProperties.set(key, value);
+            }
+        }
+
+        // If a LogRocket client is already available, register a listener to get the LogRocket session url
+        // once it's available to set it on every Mixpanel event.
+        if (logRocketInstrumentationClient) {
+            logRocketInstrumentationClient.registerGetSessionUrlListener((sessionUrl: string) => {
+                logger
+                    .withText("[mixpanel] Received LogRocket session replay URL:")
+                    .withText(sessionUrl)
+                    .debug();
+
+                this.#globalEventProperties.set(OtherProperties.LogRocketSessionUrl, sessionUrl);
+            });
+        }
+
+        registerDeprecatedContextAndGlobalVariables(productId, endpoint, this.#globalEventProperties, logger);
+
+        logger.information("[mixpanel] Mixpanel is initialized.");
+
+        return new MixpanelClient(productId, endpoint, this.#globalEventProperties, logger);
+    }
 }
 
 /**
- * Creates a function that sends tracking events to the tracking API.
- * @param productId Your product identifier.
+ * Initialize Mixpanel telemetry.
+ * @param productId The Mixpanel product identifier.
  * @param envOrTrackingApiBaseUrl The environment to get the navigation url from or a base URL.
- * @param options Options for creating the tracking function.
- * @returns A function that sends tracking events to the tracking API.
+ * @param options Mixpanel instrumentation options.
+ * @returns {MixpanelClient} A Mixpanel client instance.
  * @see {@link https://workleap.github.io/wl-telemetry}
  */
-export function initializeMixpanel(productId: string, envOrTrackingApiBaseUrl: Environment | (string & {}), options: InitializeMixpanelOptions = {}) {
-    const {
-        trackingEndpoint,
-        verbose = false,
-        loggers = []
-    } = options;
-
-    initializationGuard.throw("[mixpanel] Mixpanel has already been initialized. Did you call the \"initializeMixpanel\" function twice?");
-
-    const logger = createCompositeLogger(verbose, loggers);
-    const endpoint = getTrackingEndpoint(envOrTrackingApiBaseUrl, trackingEndpoint);
-    const telemetryContext = createTelemetryContext(logger);
-
-    setSuperProperties(getTelemetryProperties(telemetryContext));
-
-    const bootstrappingStore = createBootstrappingStore(logger);
-
-    // If LogRocket is already available, register the listener. Otherwise, subscribe to the bootstrapping store
-    // and register the listener once a notification is received that LogRocket is registered.
-    if (bootstrappingStore.state.isLogRocketReady) {
-        registerLogRocketSessionUrlListener(logger);
-    } else {
-        bootstrappingStore.subscribe((action, store, unsubscribe) => {
-            if (store.state.isLogRocketReady) {
-                unsubscribe();
-                registerLogRocketSessionUrlListener(logger);
-            }
-        });
-    }
+export function initializeMixpanel(
+    productId: string,
+    envOrTrackingApiBaseUrl: MixpanelEnvironment | (string & {}),
+    options?: InitializeMixpanelOptions
+) {
+    getRegistrationGuard().throw("[mixpanel] Mixpanel has already been initialized. Did you call the \"initializeMixpanel\" function twice?");
 
-    setMixpanelContext({
+    return new MixpanelInitializer(
+        new Map<string, unknown>()
+    ).initialize(
         productId,
-        endpoint,
-        superProperties: getSuperProperties(),
-        logger
-    });
-
-    // Indicates to the host applications that Mixpanel has been initialized.
-    // It's useful in cases where an "add-on", like the platform widgets needs
-    // to know whether or not the host application is using Mixpanel.
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    globalThis[IsInitializedVariableName] = true;
-
-    logger.information("[mixpanel] Mixpanel is initialized.");
+        envOrTrackingApiBaseUrl,
+        options
+    );
 }

package/src/js/properties.ts

@@ -1,5 +1,5 @@
 
-import type { TelemetryContext } from "@workleap/telemetry";
+import type { TelemetryContext } from "@workleap-telemetry/core";
 import { browserName, browserVersion, deviceType, osName, referringDomain } from "./utils.ts";
 
 export type MixpanelEventProperties = Record<string, unknown>;
@@ -50,30 +50,3 @@ export function getTelemetryProperties(context: TelemetryContext) {
 export const OtherProperties = {
     LogRocketSessionUrl: "LogRocket Session Url"
 };
-
-//////////////////////
-
-export type SuperProperties = Map<string, unknown>;
-
-// Equivalent to: https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript#setting-super-properties.
-const superProperties: SuperProperties = new Map<string, unknown>();
-
-export function setSuperProperty(key: string, value: unknown) {
-    superProperties.set(key, value);
-}
-
-export function setSuperProperties(values: Record<string, unknown>) {
-    Object.keys(values).forEach(x => {
-        superProperties.set(x, values[x]);
-    });
-}
-
-// Must always return the actual reference to the super properties, not a copy
-// because it will breaks the global context.
-export function getSuperProperties() {
-    return superProperties;
-}
-
-export function __clearSuperProperties() {
-    superProperties.clear();
-}

package/src/react/MixpanelContext.tsx

@@ -0,0 +1,41 @@
+import { createContext, type PropsWithChildren, useContext } from "react";
+import type { MixpanelClient } from "../js/MixpanelClient.ts";
+
+export const MixpanelContext = createContext<MixpanelClient | undefined>(undefined);
+
+/**
+ * @see {@link https://workleap.github.io/wl-telemetry}
+ */
+export interface MixpanelProviderProps extends PropsWithChildren {
+    client: MixpanelClient;
+}
+
+/**
+ * @see {@link https://workleap.github.io/wl-telemetry}
+ */
+export function MixpanelProvider(props: MixpanelProviderProps) {
+    const {
+        client,
+        children
+    } = props;
+
+    return (
+        <MixpanelContext.Provider value={client}>
+            {children}
+        </MixpanelContext.Provider>
+    );
+}
+
+/**
+ * Retrieve the Mixpanel client.
+ * @see {@link https://workleap.github.io/wl-telemetry}
+ */
+export function useMixpanelClient() {
+    const client = useContext(MixpanelContext);
+
+    if (!client) {
+        throw new Error("[mixpanel] The useMixpanelClient function is called before a MixpanelClient instance has been provided.");
+    }
+
+    return client;
+}

package/src/react/index.ts

@@ -1,2 +1,4 @@
+export * from "../js/index.ts";
+export { MixpanelProvider, useMixpanelClient } from "./MixpanelContext.tsx";
 export { useTrackingFunction, type UseTrackingFunctionOptions } from "./useTrackingFunction.ts";
 

package/src/react/useTrackingFunction.ts

@@ -1,14 +1,33 @@
-import { useMemo } from "react";
-import { createTrackingFunction, type CreateTrackingFunctionOptions } from "../js/createTrackingFunction.ts";
+import { useContext, useMemo } from "react";
+import { createTrackingFunction, type CreateMixpanelTrackingFunctionOptions } from "../js/createTrackingFunction.ts";
+import { MixpanelContext } from "./MixpanelContext.tsx";
 
-export type UseTrackingFunctionOptions = CreateTrackingFunctionOptions;
+/**
+ * @see {@link https://workleap.github.io/wl-telemetry}
+ */
+export type UseTrackingFunctionOptions = CreateMixpanelTrackingFunctionOptions;
 
+/**
+ * Create a Mixpanel tracking function.
+ * @see {@link https://workleap.github.io/wl-telemetry}
+ */
 export function useTrackingFunction(options: UseTrackingFunctionOptions = {}) {
     const {
         targetProductId
     } = options;
 
+    const client = useContext(MixpanelContext);
+
     return useMemo(() => {
-        return createTrackingFunction({ targetProductId });
-    }, [targetProductId]);
+        const trackOptions = {
+            targetProductId
+        } satisfies CreateMixpanelTrackingFunctionOptions;
+
+        // DEPRECATED: Grace period ends on January 1th 2026.
+        // After the grace period, only create the tracking function from the client, remove the fallback
+        // and also use "useMixpanelClient" to retrieve the client rather than "useContext".
+        return client
+            ? client.createTrackingFunction(trackOptions)
+            : createTrackingFunction(trackOptions);
+    }, [client, targetProductId]);
 }

package/dist/internal.d.ts

@@ -1,2 +0,0 @@
-export { __resetInitializationGuard } from "./js/initializeMixpanel.ts";
-export { __clearSuperProperties } from "./js/properties.ts";

package/dist/internal.js

@@ -1,14 +0,0 @@
-import { __resetInitializationGuard } from "./js/initializeMixpanel.js";
-import { __clearSuperProperties } from "./js/properties.js";
-
-;// CONCATENATED MODULE: external "./js/initializeMixpanel.js"
-
-;// CONCATENATED MODULE: external "./js/properties.js"
-
-;// CONCATENATED MODULE: ./src/internal.ts
-
-
-
-export { __clearSuperProperties, __resetInitializationGuard };
-
-//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"internal.js","sources":["webpack://@workleap/mixpanel/./src/internal.ts"],"sourcesContent":["export { __resetInitializationGuard } from \"./js/initializeMixpanel.ts\";\nexport { __clearSuperProperties } from \"./js/properties.ts\";\n\n"],"names":["__resetInitializationGuard","__clearSuperProperties"],"mappings":";;;;;;;;AAAwE;AACZ"}

package/dist/js/HasExecutedGuard.d.ts

@@ -1,6 +0,0 @@
-export declare class HasExecutedGuard {
-    #private;
-    throw(message: string): void;
-    get hasExecuted(): boolean;
-    reset(): void;
-}

package/dist/js/HasExecutedGuard.js

@@ -1,21 +0,0 @@
-
-;// CONCATENATED MODULE: ./src/js/HasExecutedGuard.ts
-class HasExecutedGuard {
-    #hasExecuted = false;
-    throw(message) {
-        if (this.#hasExecuted) {
-            throw new Error(message);
-        }
-        this.#hasExecuted = true;
-    }
-    get hasExecuted() {
-        return this.#hasExecuted;
-    }
-    reset() {
-        this.#hasExecuted = false;
-    }
-}
-
-export { HasExecutedGuard };
-
-//# sourceMappingURL=HasExecutedGuard.js.map

package/dist/js/HasExecutedGuard.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"js/HasExecutedGuard.js","sources":["webpack://@workleap/mixpanel/./src/js/HasExecutedGuard.ts"],"sourcesContent":["export class HasExecutedGuard {\n    #hasExecuted: boolean = false;\n\n    throw(message: string) {\n        if (this.#hasExecuted) {\n            throw new Error(message);\n        }\n\n        this.#hasExecuted = true;\n    }\n\n    get hasExecuted() {\n        return this.#hasExecuted;\n    }\n\n    reset() {\n        this.#hasExecuted = false;\n    }\n}\n"],"names":["HasExecutedGuard","message","Error"],"mappings":";;AAAO,MAAMA;IACT,YAAY,GAAY,MAAM;IAE9B,MAAMC,OAAe,EAAE;QACnB,IAAI,IAAI,CAAC,YAAY,EAAE;YACnB,MAAM,IAAIC,MAAMD;QACpB;QAEA,IAAI,CAAC,YAAY,GAAG;IACxB;IAEA,IAAI,cAAc;QACd,OAAO,IAAI,CAAC,YAAY;IAC5B;IAEA,QAAQ;QACJ,IAAI,CAAC,YAAY,GAAG;IACxB;AACJ"}

package/src/internal.ts

@@ -1,3 +0,0 @@
-export { __resetInitializationGuard } from "./js/initializeMixpanel.ts";
-export { __clearSuperProperties } from "./js/properties.ts";
-

package/src/js/HasExecutedGuard.ts

@@ -1,19 +0,0 @@
-export class HasExecutedGuard {
-    #hasExecuted: boolean = false;
-
-    throw(message: string) {
-        if (this.#hasExecuted) {
-            throw new Error(message);
-        }
-
-        this.#hasExecuted = true;
-    }
-
-    get hasExecuted() {
-        return this.#hasExecuted;
-    }
-
-    reset() {
-        this.#hasExecuted = false;
-    }
-}