@webority/analytics 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webority Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,7 @@
 {
     "name": "@webority/analytics",
-    "version": "0.2.0",
+    "version": "0.3.0",
+    "license": "MIT",
     "type": "module",
     "main": "src/index.js",
     "exports": {
@@ -10,9 +11,9 @@
         "src"
     ],
     "scripts": {
-        "lint": "biome lint ./src",
-        "format": "biome format --write ./src",
-        "check": "biome check ./src",
+        "lint": "biome lint ./src ./test",
+        "format": "biome format --write ./src ./test",
+        "check": "biome check ./src ./test",
         "test": "node test/smoke.mjs"
     },
     "dependencies": {

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) {
@@ -22,25 +22,55 @@ export function initAnalytics(config) {
     });
 
     if (isActive()) {
-        ensurePosthogInitialized();
+        warmUp();
     }
 }
 
+// Starts the loader without waiting for it. The rejection handler is what keeps a failed
+// load inside the package: the bridge clears its cached promise before rethrowing, so the
+// next event retries, and the product never sees an unhandled rejection.
+function warmUp() {
+    ensurePosthogInitialized().catch(() => {
+        // Retried on the next call. Analytics must stay invisible to the product.
+    });
+}
+
 export function setConsent(granted) {
     state.consentOverride = granted;
 
     if (granted && isEligible()) {
-        // A prior revoke leaves an already-initialized instance opted out — re-grant must undo it.
+        // A prior revoke leaves an already-initialized instance opted out, so re-granting must undo it.
         if (state.posthogInstance) {
             state.posthogInstance.opt_in_capturing();
         } else {
-            ensurePosthogInitialized();
+            warmUp();
         }
         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.
+            });
     }
 }
 
@@ -50,9 +80,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() {
@@ -65,7 +102,7 @@ export function resetIdentity() {
 export function registerEvents(names) {
     for (const name of names) {
         if (!EVENT_NAME_PATTERN.test(name)) {
-            throw new Error(`@webority/analytics: invalid event name "${name}" — expected snake_case`);
+            throw new Error(`@webority/analytics: invalid event name "${name}". Expected snake_case.`);
         }
         state.registeredEvents.add(name);
     }
@@ -73,7 +110,7 @@ export function registerEvents(names) {
 
 export function trackEvent(name, props = {}) {
     if (!state.registeredEvents.has(name)) {
-        throw new Error(`@webority/analytics: event "${name}" is not registered — call registerEvents() first`);
+        throw new Error(`@webority/analytics: event "${name}" is not registered. Call registerEvents() first.`);
     }
     capture(name, props);
 }
@@ -92,9 +129,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,17 +11,41 @@ export async function ensurePosthogInitialized() {
     }
 
     const config = state.config;
-    state.posthogInitPromise = import("posthog-js").then((module) => {
-        const posthog = module.default ?? module;
-        posthog.init(config.clientKey, buildInitOptions(config));
-        posthog.register({ product: config.product, surface: config.surface });
-        state.posthogInstance = posthog;
-        return posthog;
-    });
+    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;
+        });
 
     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

package/src/state.js

@@ -8,12 +8,14 @@ export const state = {
     registeredEvents: new Set(Object.values(events)),
 };
 
+// registeredEvents is deliberately not reset: an event name is part of the product's
+// vocabulary, not of one analytics session, so a product that registers at module scope and
+// starts analytics later in a bootstrap effect keeps its registrations.
 export function resetState(config) {
     state.config = config;
     state.consentOverride = null;
     state.posthogInstance = null;
     state.posthogInitPromise = null;
-    state.registeredEvents = new Set(Object.values(events));
 }
 
 export function isEligible() {