@webority/analytics 0.2.1 → 0.4.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.1",
+    "version": "0.4.0",
+    "license": "MIT",
     "type": "module",
     "main": "src/index.js",
     "exports": {
@@ -10,15 +11,16 @@
         "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": {
-        "posthog-js": "1.417.1"
+    "peerDependencies": {
+        "posthog-js": "^1.417.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.8"
+        "@biomejs/biome": "2.5.8",
+        "posthog-js": "1.417.1"
     }
 }

package/src/analytics.js

@@ -1,5 +1,5 @@
 import { ensurePosthogInitialized } from "./posthog-bridge.js";
-import { hasConsent, isActive, isEligible, resetState, state } from "./state.js";
+import { hasConsent, isActive, isEligible, resetState, state, WARNED_EVENT_LIMIT } from "./state.js";
 import { EVENT_NAME_PATTERN } from "./vocabulary.js";
 
 export function initAnalytics(config) {
@@ -22,19 +22,28 @@ 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;
     }
@@ -93,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);
     }
@@ -101,11 +110,42 @@ 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`);
+        warnUnregisteredOnce(name);
+        return;
     }
     capture(name, props);
 }
 
+// Parity with IAnalyticsClient.Track on the server half: the same developer mistake never
+// throws there, it is logged and the event is dropped. A throw here runs inside the user's
+// browser and can take out the handler that raised it, so the browser half must not be the
+// harsher one. Once per name, because a misregistered event usually sits in a hot path.
+function warnUnregisteredOnce(name) {
+    if (state.warnedUnregisteredEvents.has(name)) {
+        return;
+    }
+    if (state.warnedUnregisteredEvents.size < WARNED_EVENT_LIMIT) {
+        state.warnedUnregisteredEvents.add(name);
+    }
+
+    const logger = state.config?.logger;
+    const message = `@webority/analytics: event "${name}" is not registered, so it was dropped. Call registerEvents() first.`;
+    if (typeof logger?.warn === "function") {
+        logger.warn(message);
+        return;
+    }
+    if (typeof logger?.info === "function") {
+        logger.info(message);
+        return;
+    }
+
+    // The no-console rule exists to stop debug logging, and passing no logger is the default.
+    // Routing the one diagnostic this package emits to a logger nobody passed would hide exactly
+    // the mistake the warning exists to surface.
+    // biome-ignore lint/suspicious/noConsole: the package's one diagnostic must be visible by default
+    console.warn(message);
+}
+
 function capture(name, props) {
     if (!isActive()) {
         logInactive(name, props);

package/src/posthog-bridge.js

@@ -1,7 +1,7 @@
 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.
+// never go active (e.g. Local environment), because it assumes browser globals at init time.
 export async function ensurePosthogInitialized() {
     if (state.posthogInstance) {
         return state.posthogInstance;

package/src/state.js

@@ -6,14 +6,23 @@ export const state = {
     posthogInstance: null,
     posthogInitPromise: null,
     registeredEvents: new Set(Object.values(events)),
+    warnedUnregisteredEvents: new Set(),
 };
 
+// The warning exists to reach a developer once. After this many distinct bad names the message
+// has landed, and a product building names from data must not grow the set for the life of the tab.
+export const WARNED_EVENT_LIMIT = 50;
+
+// 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. warnedUnregisteredEvents
+// follows it for the same reason: the warning is about the code, not about one session, so
+// re-initializing must not make the same mistake shout again.
 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() {