@webority/analytics 0.1.1

package/package.json

@@ -0,0 +1,24 @@
+{
+    "name": "@webority/analytics",
+    "version": "0.1.1",
+    "type": "module",
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src"
+    ],
+    "scripts": {
+        "lint": "biome lint ./src",
+        "format": "biome format --write ./src",
+        "check": "biome check ./src",
+        "test": "node test/smoke.mjs"
+    },
+    "dependencies": {
+        "posthog-js": "1.417.1"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.5.8"
+    }
+}

package/src/analytics.js

@@ -0,0 +1,97 @@
+import { ensurePosthogInitialized } from "./posthog-bridge.js";
+import { isActive, isEligible, resetState, state } from "./state.js";
+import { EVENT_NAME_PATTERN } from "./vocabulary.js";
+
+export function initAnalytics(config) {
+    resetState({
+        host: config.host,
+        clientKey: config.clientKey,
+        product: config.product,
+        surface: config.surface,
+        environment: config.environment,
+        enabled: config.enabled ?? true,
+        getConsent: config.getConsent ?? null,
+        logger: config.logger ?? null,
+    });
+
+    if (isActive()) {
+        ensurePosthogInitialized();
+    }
+}
+
+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.
+        if (state.posthogInstance) {
+            state.posthogInstance.opt_in_capturing();
+        } else {
+            ensurePosthogInitialized();
+        }
+        return;
+    }
+
+    if (!granted && state.posthogInstance) {
+        state.posthogInstance.opt_out_capturing();
+    }
+}
+
+export function identify(publicId, props = {}) {
+    if (!isActive()) {
+        logInactive("identify", { publicId, ...props });
+        return;
+    }
+
+    ensurePosthogInitialized().then((posthog) => {
+        posthog.identify(publicId, props);
+    });
+}
+
+export function resetIdentity() {
+    if (!state.posthogInstance) {
+        return;
+    }
+    state.posthogInstance.reset();
+}
+
+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`);
+        }
+        state.registeredEvents.add(name);
+    }
+}
+
+export function trackEvent(name, props = {}) {
+    if (!state.registeredEvents.has(name)) {
+        throw new Error(`@webority/analytics: event "${name}" is not registered — call registerEvents() first`);
+    }
+    capture(name, props);
+}
+
+function capture(name, props) {
+    if (!isActive()) {
+        logInactive(name, props);
+        return;
+    }
+
+    // environment rides on every event: products may share one PostHog project across
+    // deployed environments (capnix does), so it is the only reliable env discriminator.
+    const merged = {
+        ...props,
+        product: state.config.product,
+        surface: state.config.surface,
+        environment: state.config.environment,
+    };
+    ensurePosthogInitialized().then((posthog) => {
+        posthog.capture(name, merged);
+    });
+}
+
+function logInactive(name, props) {
+    if (state.config?.environment === "Local") {
+        state.config.logger?.info(name, props);
+    }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { identify, initAnalytics, registerEvents, resetIdentity, setConsent, trackEvent } from "./analytics.js";
+export { track } from "./track-helpers.js";
+export { events } from "./vocabulary.js";

package/src/posthog-bridge.js

@@ -0,0 +1,28 @@
+import { 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.
+export async function ensurePosthogInitialized() {
+    if (state.posthogInstance) {
+        return state.posthogInstance;
+    }
+    if (state.posthogInitPromise) {
+        return state.posthogInitPromise;
+    }
+
+    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",
+        });
+        posthog.register({ product: config.product, surface: config.surface });
+        state.posthogInstance = posthog;
+        return posthog;
+    });
+
+    return state.posthogInitPromise;
+}

package/src/state.js

@@ -0,0 +1,40 @@
+import { events } from "./vocabulary.js";
+
+export const state = {
+    config: null,
+    consentOverride: null,
+    posthogInstance: null,
+    posthogInitPromise: null,
+    registeredEvents: new Set(Object.values(events)),
+};
+
+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() {
+    const config = state.config;
+    if (!config) {
+        return false;
+    }
+    return Boolean(config.enabled && config.clientKey && config.environment !== "Local");
+}
+
+export function hasConsent() {
+    if (state.consentOverride !== null) {
+        return state.consentOverride;
+    }
+    const getConsent = state.config?.getConsent;
+    if (typeof getConsent === "function") {
+        return Boolean(getConsent());
+    }
+    return true;
+}
+
+export function isActive() {
+    return isEligible() && hasConsent();
+}

package/src/track-helpers.js

@@ -0,0 +1,8 @@
+import { trackEvent } from "./analytics.js";
+import { trackHelperNames } from "./vocabulary.js";
+
+export const track = Object.freeze(
+    Object.fromEntries(
+        Object.entries(trackHelperNames).map(([camelName, eventName]) => [camelName, (props = {}) => trackEvent(eventName, props)]),
+    ),
+);

package/src/vocabulary.js

@@ -0,0 +1,29 @@
+export const events = Object.freeze({
+    SIGNUP_STARTED: "signup_started",
+    SIGNUP_COMPLETED: "signup_completed",
+    LOGIN_SUCCEEDED: "login_succeeded",
+    ONBOARDING_STARTED: "onboarding_started",
+    ONBOARDING_STEP_COMPLETED: "onboarding_step_completed",
+    ONBOARDING_COMPLETED: "onboarding_completed",
+    SUBSCRIPTION_ACTIVATED: "subscription_activated",
+    SUBSCRIPTION_CANCELLED: "subscription_cancelled",
+    PAYMENT_SUCCEEDED: "payment_succeeded",
+    PAYMENT_FAILED: "payment_failed",
+    FEEDBACK_SUBMITTED: "feedback_submitted",
+});
+
+export const trackHelperNames = Object.freeze({
+    signupStarted: events.SIGNUP_STARTED,
+    signupCompleted: events.SIGNUP_COMPLETED,
+    loginSucceeded: events.LOGIN_SUCCEEDED,
+    onboardingStarted: events.ONBOARDING_STARTED,
+    onboardingStepCompleted: events.ONBOARDING_STEP_COMPLETED,
+    onboardingCompleted: events.ONBOARDING_COMPLETED,
+    subscriptionActivated: events.SUBSCRIPTION_ACTIVATED,
+    subscriptionCancelled: events.SUBSCRIPTION_CANCELLED,
+    paymentSucceeded: events.PAYMENT_SUCCEEDED,
+    paymentFailed: events.PAYMENT_FAILED,
+    feedbackSubmitted: events.FEEDBACK_SUBMITTED,
+});
+
+export const EVENT_NAME_PATTERN = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;