@webority/analytics 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webority/analytics",
-    "version": "0.1.1",
+    "version": "0.2.1",
     "type": "module",
     "main": "src/index.js",
     "exports": {

package/src/analytics.js

@@ -1,5 +1,5 @@
 import { ensurePosthogInitialized } from "./posthog-bridge.js";
-import { isActive, isEligible, resetState, state } from "./state.js";
+import { hasConsent, isActive, isEligible, resetState, state } from "./state.js";
 import { EVENT_NAME_PATTERN } from "./vocabulary.js";
 
 export function initAnalytics(config) {
@@ -12,6 +12,13 @@ export function initAnalytics(config) {
         enabled: config.enabled ?? true,
         getConsent: config.getConsent ?? null,
         logger: config.logger ?? null,
+        // Off unless the product asks: replay records page content, so turning it on is the
+        // product's disclosed decision, never a package default.
+        sessionRecording: {
+            enabled: config.sessionRecording?.enabled ?? false,
+            maskAllInputs: config.sessionRecording?.maskAllInputs ?? true,
+            maskTextSelector: config.sessionRecording?.maskTextSelector ?? null,
+        },
     });
 
     if (isActive()) {
@@ -32,8 +39,29 @@ export function setConsent(granted) {
         return;
     }
 
-    if (!granted && state.posthogInstance) {
+    if (!granted) {
+        // Revoking before init finishes must still opt out: the instance does not exist yet,
+        // and init would otherwise start capturing under the consent that has just been withdrawn.
+        optOutWhenReady();
+    }
+}
+
+function optOutWhenReady() {
+    if (state.posthogInstance) {
         state.posthogInstance.opt_out_capturing();
+        return;
+    }
+
+    if (state.posthogInitPromise) {
+        state.posthogInitPromise
+            .then((posthog) => {
+                if (!hasConsent()) {
+                    posthog?.opt_out_capturing();
+                }
+            })
+            .catch(() => {
+                // Init failed on its own; nothing was capturing.
+            });
     }
 }
 
@@ -43,9 +71,16 @@ export function identify(publicId, props = {}) {
         return;
     }
 
-    ensurePosthogInitialized().then((posthog) => {
-        posthog.identify(publicId, props);
-    });
+    ensurePosthogInitialized()
+        .then((posthog) => {
+            if (!posthog || !hasConsent()) {
+                return;
+            }
+            posthog.identify(publicId, props);
+        })
+        .catch(() => {
+            // Load failure is retried on the next call. Do not surface it as an unhandled rejection.
+        });
 }
 
 export function resetIdentity() {
@@ -85,9 +120,16 @@ function capture(name, props) {
         surface: state.config.surface,
         environment: state.config.environment,
     };
-    ensurePosthogInitialized().then((posthog) => {
-        posthog.capture(name, merged);
-    });
+    ensurePosthogInitialized()
+        .then((posthog) => {
+            if (!posthog || !hasConsent()) {
+                return;
+            }
+            posthog.capture(name, merged);
+        })
+        .catch(() => {
+            // Load failure is retried on the next call. Do not surface it as an unhandled rejection.
+        });
 }
 
 function logInactive(name, props) {

package/src/posthog-bridge.js

@@ -1,4 +1,4 @@
-import { state } from "./state.js";
+import { hasConsent, state } from "./state.js";
 
 // Dynamic import keeps posthog-js out of the module graph entirely for callers that
 // never go active (e.g. Local environment) — it assumes browser globals at init time.
@@ -11,18 +11,60 @@ export async function ensurePosthogInitialized() {
     }
 
     const config = state.config;
-    state.posthogInitPromise = import("posthog-js").then((module) => {
-        const posthog = module.default ?? module;
-        posthog.init(config.clientKey, {
-            api_host: config.host,
-            autocapture: false,
-            capture_pageview: true,
-            persistence: "localStorage",
+    state.posthogInitPromise = import("posthog-js")
+        .then((module) => {
+            const posthog = module.default ?? module;
+            // Consent can flip while posthog-js is still downloading. Opting out in the init
+            // options stops the pageview init would send before a later opt_out_capturing() call.
+            const options = applyConsentToInitOptions(buildInitOptions(config), hasConsent());
+            posthog.init(config.clientKey, options);
+            if (!hasConsent()) {
+                posthog.opt_out_capturing();
+            }
+            posthog.register({ product: config.product, surface: config.surface });
+            state.posthogInstance = posthog;
+            return posthog;
+        })
+        .catch((error) => {
+            // A rejected init left in place would fail every later event without retrying.
+            state.posthogInitPromise = null;
+            throw error;
         });
-        posthog.register({ product: config.product, surface: config.surface });
-        state.posthogInstance = posthog;
-        return posthog;
-    });
 
     return state.posthogInitPromise;
 }
+
+/**
+ * Copies init options and, when consent is absent, sets the flag that keeps init itself
+ * from capturing. Pure so the smoke test can lock the consent decision without a browser.
+ */
+export function applyConsentToInitOptions(options, consentGranted) {
+    if (consentGranted) {
+        return options;
+    }
+
+    return { ...options, opt_out_capturing_by_default: true };
+}
+
+/**
+ * The posthog-js init options for a config. Pure, so the smoke test can assert the mapping
+ * without a browser: replay stays off unless the product enabled it, and the masking choices
+ * ride through only when it is on.
+ */
+export function buildInitOptions(config) {
+    const recording = config.sessionRecording ?? { enabled: false };
+    const options = {
+        api_host: config.host,
+        autocapture: false,
+        capture_pageview: true,
+        persistence: "localStorage",
+        disable_session_recording: !recording.enabled,
+    };
+    if (recording.enabled) {
+        options.session_recording = {
+            maskAllInputs: recording.maskAllInputs ?? true,
+            ...(recording.maskTextSelector ? { maskTextSelector: recording.maskTextSelector } : {}),
+        };
+    }
+    return options;
+}