@armco/analytics 0.2.11 → 0.2.12

package/package.json

@@ -1,25 +1,11 @@
 {
   "name": "@armco/analytics",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Universal Analytics Library for Browser and Node.js",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "index.js",
+  "types": "index.d.ts",
   "type": "module",
-  "scripts": {
-    "build": "npx ts-node build.js",
-    "lint": "npx eslint --ext .ts src/",
-    "lint:tests": "npx eslint --ext .ts tests/",
-    "start": "node ./dist --env=production",
-    "dev": "nodemon",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "test:unit": "jest --testPathPattern=tests/unit",
-    "test:integration": "jest --testPathPattern=tests/integration",
-    "publish:local": "./publish-local.sh",
-    "publish:sh": "./publish.sh",
-    "publish:sh:minor": "./publish.sh minor"
-  },
+  "scripts": {},
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ReStruct-Corporate-Advantage/analytics.git"
@@ -37,27 +23,11 @@
     "url": "https://github.com/ReStruct-Corporate-Advantage/analytics/issues"
   },
   "homepage": "https://github.com/ReStruct-Corporate-Advantage/analytics#readme",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "devDependencies": {
-    "@jest/globals": "^29.7.0",
-    "@types/fs-extra": "^11.0.1",
-    "@types/jest": "^29.5.11",
-    "@types/js-cookie": "^3.0.3",
-    "@types/node": "^20.4.2",
-    "@types/uuid": "^9.0.2",
-    "fs-extra": "^11.1.1",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.1.6"
-  },
+  "devDependencies": {},
   "dependencies": {
     "js-cookie": "^3.0.5",
     "jstz": "^2.1.1",
     "uuid": "^9.0.0",
     "zod": "^4.1.13"
   }
-}
+}

package/plugins/auto-track/click.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin, PluginContext } from "../../core/types";
+export declare class ClickTrackingPlugin implements Plugin {
+    name: string;
+    version: string;
+    private context?;
+    private logger;
+    private boundHandler?;
+    init(context: PluginContext): void;
+    private attachHandlers;
+    private handleClick;
+    private isTrackable;
+    private extractClickData;
+    private getElementPath;
+    destroy(): void;
+}

package/plugins/auto-track/click.js

@@ -0,0 +1,95 @@
+import { isBrowser } from "../../utils/helpers";
+import { getLogger } from "../../utils/logging";
+const TRACKED_ELEMENTS = [
+    "a[href]",
+    "button",
+    "input[type='button']",
+    "input[type='submit']",
+    "input[type='reset']",
+    "[role='button']",
+    "[role='link']",
+    "[data-track='true']",
+];
+export class ClickTrackingPlugin {
+    constructor() {
+        this.name = "ClickTrackingPlugin";
+        this.version = "1.0.0";
+        this.logger = getLogger();
+    }
+    init(context) {
+        if (!isBrowser()) {
+            this.logger.warn("Click tracking only available in browser");
+            return;
+        }
+        this.context = context;
+        this.attachHandlers();
+        this.logger.info("Click tracking initialized");
+    }
+    attachHandlers() {
+        this.boundHandler = this.handleClick.bind(this);
+        document.addEventListener("click", this.boundHandler, true);
+    }
+    handleClick(e) {
+        const element = e.target;
+        if (!this.isTrackable(element)) {
+            return;
+        }
+        const clickData = this.extractClickData(element);
+        if (this.context) {
+            this.context.track("CLICK", clickData);
+        }
+    }
+    isTrackable(element) {
+        return (element.matches(TRACKED_ELEMENTS.join(", ")) ||
+            element.onclick != null ||
+            window.getComputedStyle(element).cursor === "pointer");
+    }
+    extractClickData(element) {
+        const data = {
+            elementType: element.tagName.toLowerCase(),
+            elementId: element.id || undefined,
+            elementText: element.textContent?.trim() || undefined,
+            elementClasses: Array.from(element.classList),
+            elementPath: this.getElementPath(element),
+        };
+        if ("href" in element) {
+            data.href = element.href;
+        }
+        if ("value" in element && element.value) {
+            data.value = element.value;
+        }
+        const dataAttributes = { ...element.dataset };
+        if (Object.keys(dataAttributes).length > 0) {
+            data.dataAttributes = dataAttributes;
+        }
+        return data;
+    }
+    getElementPath(element) {
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            if (current.id) {
+                selector += `#${current.id}`;
+                path.unshift(selector);
+                break;
+            }
+            else if (current.className) {
+                const classes = Array.from(current.classList)
+                    .filter((c) => c.trim())
+                    .join(".");
+                if (classes) {
+                    selector += `.${classes}`;
+                }
+            }
+            path.unshift(selector);
+            current = current.parentElement;
+        }
+        return path.join(" > ");
+    }
+    destroy() {
+        if (this.boundHandler) {
+            document.removeEventListener("click", this.boundHandler, true);
+        }
+    }
+}

package/plugins/auto-track/error.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin, PluginContext } from "../../core/types";
+export declare class ErrorTrackingPlugin implements Plugin {
+    name: string;
+    version: string;
+    private context?;
+    private logger;
+    private boundErrorHandler?;
+    private boundRejectionHandler?;
+    init(context: PluginContext): void;
+    private attachHandlers;
+    private handleError;
+    private handleRejection;
+    trackError(error: Error | string): void;
+    destroy(): void;
+}

package/plugins/auto-track/error.js

@@ -0,0 +1,65 @@
+import { isBrowser } from "../../utils/helpers";
+import { getLogger } from "../../utils/logging";
+export class ErrorTrackingPlugin {
+    constructor() {
+        this.name = "ErrorTrackingPlugin";
+        this.version = "1.0.0";
+        this.logger = getLogger();
+    }
+    init(context) {
+        if (!isBrowser()) {
+            this.logger.warn("Error tracking only available in browser");
+            return;
+        }
+        this.context = context;
+        this.attachHandlers();
+        this.logger.info("Error tracking initialized");
+    }
+    attachHandlers() {
+        this.boundErrorHandler = this.handleError.bind(this);
+        window.addEventListener("error", this.boundErrorHandler);
+        this.boundRejectionHandler = this.handleRejection.bind(this);
+        window.addEventListener("unhandledrejection", this.boundRejectionHandler);
+    }
+    handleError(e) {
+        const errorData = {
+            errorMessage: e.message,
+            errorStack: e.error?.stack,
+            errorType: e.error?.name || "Error",
+            filename: e.filename,
+            lineNumber: e.lineno,
+            columnNumber: e.colno,
+        };
+        if (this.context) {
+            this.context.track("ERROR", errorData);
+        }
+    }
+    handleRejection(e) {
+        const errorData = {
+            errorMessage: e.reason?.message || String(e.reason),
+            errorStack: e.reason?.stack,
+            errorType: "UnhandledPromiseRejection",
+        };
+        if (this.context) {
+            this.context.track("ERROR", errorData);
+        }
+    }
+    trackError(error) {
+        const errorData = {
+            errorMessage: typeof error === "string" ? error : error.message,
+            errorStack: typeof error === "string" ? undefined : error.stack,
+            errorType: typeof error === "string" ? "Error" : error.name,
+        };
+        if (this.context) {
+            this.context.track("ERROR", errorData);
+        }
+    }
+    destroy() {
+        if (this.boundErrorHandler) {
+            window.removeEventListener("error", this.boundErrorHandler);
+        }
+        if (this.boundRejectionHandler) {
+            window.removeEventListener("unhandledrejection", this.boundRejectionHandler);
+        }
+    }
+}

package/plugins/auto-track/form.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin, PluginContext } from "../../core/types";
+export declare class FormTrackingPlugin implements Plugin {
+    name: string;
+    version: string;
+    private context?;
+    private logger;
+    private boundHandler?;
+    init(context: PluginContext): void;
+    private attachHandlers;
+    private handleSubmit;
+    private extractFormData;
+    destroy(): void;
+}

package/plugins/auto-track/form.js

@@ -0,0 +1,54 @@
+import { isBrowser } from "../../utils/helpers";
+import { getLogger } from "../../utils/logging";
+export class FormTrackingPlugin {
+    constructor() {
+        this.name = "FormTrackingPlugin";
+        this.version = "1.0.0";
+        this.logger = getLogger();
+    }
+    init(context) {
+        if (!isBrowser()) {
+            this.logger.warn("Form tracking only available in browser");
+            return;
+        }
+        this.context = context;
+        this.attachHandlers();
+        this.logger.info("Form tracking initialized");
+    }
+    attachHandlers() {
+        this.boundHandler = this.handleSubmit.bind(this);
+        document.addEventListener("submit", this.boundHandler, true);
+    }
+    handleSubmit(e) {
+        const form = e.target;
+        const formData = this.extractFormData(form);
+        if (this.context) {
+            this.context.track("FORM_SUBMIT", formData);
+        }
+    }
+    extractFormData(form) {
+        const data = {
+            formId: form.id || undefined,
+            formName: form.name || undefined,
+            formAction: form.action || undefined,
+            formMethod: form.method || undefined,
+        };
+        const fields = [];
+        const formElements = form.elements;
+        for (let i = 0; i < formElements.length; i++) {
+            const element = formElements[i];
+            if (element.name) {
+                fields.push(element.name);
+            }
+        }
+        if (fields.length > 0) {
+            data.fields = fields;
+        }
+        return data;
+    }
+    destroy() {
+        if (this.boundHandler) {
+            document.removeEventListener("submit", this.boundHandler, true);
+        }
+    }
+}

package/plugins/auto-track/page.d.ts

@@ -0,0 +1,14 @@
+import type { Plugin, PluginContext, PageViewEvent } from "../../core/types";
+export declare class PageTrackingPlugin implements Plugin {
+    name: string;
+    version: string;
+    private context?;
+    private logger;
+    private lastUrl?;
+    init(context: PluginContext): void;
+    private attachHandlers;
+    private trackCurrentPage;
+    private getPageName;
+    trackPage(data: Partial<PageViewEvent>): void;
+    destroy(): void;
+}

package/plugins/auto-track/page.js

@@ -0,0 +1,71 @@
+import { isBrowser } from "../../utils/helpers";
+import { getLogger } from "../../utils/logging";
+export class PageTrackingPlugin {
+    constructor() {
+        this.name = "PageTrackingPlugin";
+        this.version = "1.0.0";
+        this.logger = getLogger();
+    }
+    init(context) {
+        if (!isBrowser()) {
+            this.logger.warn("Page tracking only available in browser");
+            return;
+        }
+        this.context = context;
+        this.attachHandlers();
+        this.trackCurrentPage();
+        this.logger.info("Page tracking initialized");
+    }
+    attachHandlers() {
+        window.addEventListener("load", () => this.trackCurrentPage());
+        window.addEventListener("popstate", () => this.trackCurrentPage());
+        window.addEventListener("hashchange", () => this.trackCurrentPage());
+    }
+    trackCurrentPage() {
+        const url = window.location.href;
+        if (url === this.lastUrl) {
+            return;
+        }
+        this.lastUrl = url;
+        const pageData = {
+            pageName: this.getPageName(),
+            url: url,
+            referrer: document.referrer || undefined,
+            title: document.title || undefined,
+        };
+        if (this.context) {
+            this.context.track("PAGE_VIEW", pageData);
+        }
+    }
+    getPageName() {
+        if (document.title) {
+            return document.title;
+        }
+        const pathname = window.location.pathname;
+        if (pathname === "/" || pathname === "") {
+            return "Home";
+        }
+        return pathname
+            .split("/")
+            .filter((part) => part)
+            .map((part) => part
+            .split("-")
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(" "))
+            .join(" - ");
+    }
+    trackPage(data) {
+        const pageData = {
+            pageName: data.pageName || this.getPageName(),
+            url: data.url || window.location.href,
+            referrer: data.referrer || document.referrer || undefined,
+            title: data.title || document.title || undefined,
+        };
+        if (this.context) {
+            this.context.track("PAGE_VIEW", pageData);
+        }
+        this.lastUrl = pageData.url;
+    }
+    destroy() {
+    }
+}

package/plugins/enrichment/session.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin, PluginContext, TrackingEvent } from "../../core/types";
+export declare class SessionPlugin implements Plugin {
+    name: string;
+    version: string;
+    private context?;
+    private sessionId;
+    private tabId;
+    private logger;
+    init(context: PluginContext): void;
+    processEvent(event: TrackingEvent): void;
+    private startSession;
+    private getTabId;
+    private storeSession;
+    private extendSession;
+    getSessionId(): string | null;
+    terminateSession(): void;
+    destroy(): void;
+}

package/plugins/enrichment/session.js

@@ -0,0 +1,81 @@
+import { generateId } from "../../utils/helpers";
+import { getLogger } from "../../utils/logging";
+const SESSION_KEY = "ar_session_id";
+const TAB_KEY = "ar_tab_id";
+const SESSION_EXPIRATION_MINUTES = 30;
+export class SessionPlugin {
+    constructor() {
+        this.name = "SessionPlugin";
+        this.version = "1.0.0";
+        this.sessionId = null;
+        this.tabId = null;
+        this.logger = getLogger();
+    }
+    init(context) {
+        this.context = context;
+        this.startSession();
+    }
+    processEvent(event) {
+        if (!this.sessionId) {
+            this.startSession();
+        }
+        event.sessionId = this.sessionId ?? undefined;
+        this.extendSession();
+    }
+    startSession() {
+        this.tabId = this.getTabId();
+        this.sessionId = generateId();
+        this.storeSession();
+        this.logger.debug("Session started:", this.sessionId);
+    }
+    getTabId() {
+        if (typeof sessionStorage === "undefined") {
+            return generateId();
+        }
+        let tabId = sessionStorage.getItem(TAB_KEY);
+        if (!tabId) {
+            tabId = `${generateId()}-${Date.now()}`;
+            sessionStorage.setItem(TAB_KEY, tabId);
+        }
+        return tabId;
+    }
+    storeSession() {
+        if (!this.context || !this.sessionId || !this.tabId) {
+            return;
+        }
+        const expirationDate = new Date();
+        expirationDate.setMinutes(expirationDate.getMinutes() + SESSION_EXPIRATION_MINUTES);
+        const cookieName = `${SESSION_KEY}_${this.tabId}`;
+        this.context.storage.setItem(cookieName, this.sessionId, {
+            expires: expirationDate,
+            secure: true,
+            sameSite: "lax",
+        });
+    }
+    extendSession() {
+        if (!this.sessionId) {
+            return;
+        }
+        this.storeSession();
+    }
+    getSessionId() {
+        if (!this.sessionId && this.context) {
+            const tabId = this.getTabId();
+            const cookieName = `${SESSION_KEY}_${tabId}`;
+            this.sessionId = this.context.storage.getItem(cookieName);
+        }
+        return this.sessionId;
+    }
+    terminateSession() {
+        if (!this.context || !this.tabId) {
+            return;
+        }
+        const cookieName = `${SESSION_KEY}_${this.tabId}`;
+        this.context.storage.removeItem(cookieName);
+        this.sessionId = null;
+        this.logger.debug("Session terminated");
+    }
+    destroy() {
+        this.terminateSession();
+    }
+}

package/plugins/enrichment/user.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin, PluginContext, TrackingEvent, User } from "../../core/types";
+export declare class UserPlugin implements Plugin {
+    name: string;
+    version: string;
+    private context?;
+    private user;
+    private anonymousId;
+    private logger;
+    init(context: PluginContext): void;
+    processEvent(event: TrackingEvent): void;
+    identify(user: User): Promise<void>;
+    private generateAnonymousId;
+    private loadUser;
+    private storeUser;
+    getUser(): User | null;
+    getUserId(): string | null;
+    logout(): void;
+    private updateAnonymousEvents;
+    destroy(): void;
+}

package/plugins/enrichment/user.js

@@ -0,0 +1,152 @@
+import { generateId, getEnvironmentType } from "../../utils/helpers";
+import { validateUser } from "../../utils/validation";
+import { getLogger } from "../../utils/logging";
+const USER_KEY = "ar_user";
+const ANONYMOUS_ID_KEY = "ar_anonymous_id";
+export class UserPlugin {
+    constructor() {
+        this.name = "UserPlugin";
+        this.version = "1.0.0";
+        this.user = null;
+        this.anonymousId = null;
+        this.logger = getLogger();
+    }
+    init(context) {
+        this.context = context;
+        this.loadUser();
+        if (!this.user) {
+            this.generateAnonymousId();
+        }
+    }
+    processEvent(event) {
+        if (this.user) {
+            event.userId = this.user.email;
+            event.data = {
+                ...event.data,
+                user: this.user,
+            };
+        }
+        else if (this.anonymousId) {
+            event.userId = this.anonymousId;
+        }
+    }
+    async identify(user) {
+        try {
+            const validatedUser = validateUser(user);
+            this.user = validatedUser;
+            this.storeUser(validatedUser);
+            if (this.context && this.anonymousId) {
+                const previousAnonymousId = this.anonymousId;
+                this.context.storage.removeItem(ANONYMOUS_ID_KEY);
+                this.context.track("IDENTIFY", {
+                    anonymousId: previousAnonymousId,
+                    email: validatedUser.email,
+                });
+                if (getEnvironmentType() === "browser") {
+                    await this.updateAnonymousEvents(validatedUser.email, previousAnonymousId);
+                }
+                this.anonymousId = null;
+            }
+            this.logger.info("User identified:", validatedUser.email);
+        }
+        catch (error) {
+            this.logger.error("Failed to identify user:", error);
+            throw error;
+        }
+    }
+    generateAnonymousId() {
+        if (!this.context) {
+            return;
+        }
+        this.anonymousId = this.context.storage.getItem(ANONYMOUS_ID_KEY);
+        if (!this.anonymousId) {
+            this.anonymousId = generateId();
+            this.context.storage.setItem(ANONYMOUS_ID_KEY, this.anonymousId);
+            this.logger.debug("Anonymous ID generated:", this.anonymousId);
+        }
+    }
+    loadUser() {
+        if (!this.context) {
+            return;
+        }
+        const storedUser = this.context.storage.getItem(USER_KEY);
+        if (storedUser) {
+            try {
+                this.user = JSON.parse(storedUser);
+                this.logger.debug("User loaded from storage:", this.user?.email);
+            }
+            catch (error) {
+                this.logger.error("Failed to parse stored user:", error);
+            }
+        }
+    }
+    storeUser(user) {
+        if (!this.context) {
+            return;
+        }
+        try {
+            this.context.storage.setItem(USER_KEY, JSON.stringify(user));
+        }
+        catch (error) {
+            this.logger.error("Failed to store user:", error);
+        }
+    }
+    getUser() {
+        return this.user;
+    }
+    getUserId() {
+        return this.user?.email ?? this.anonymousId;
+    }
+    logout() {
+        if (!this.context) {
+            return;
+        }
+        this.context.storage.removeItem(USER_KEY);
+        this.user = null;
+        this.generateAnonymousId();
+        this.logger.info("User logged out");
+    }
+    async updateAnonymousEvents(email, anonymousId) {
+        if (!this.context) {
+            return;
+        }
+        const { config, transport } = this.context;
+        if (!transport.update) {
+            this.logger.debug("Transport does not support update, skipping event tagging");
+            return;
+        }
+        let updateEndpoint = config.updateEndpoint;
+        if (!updateEndpoint) {
+            if (config.apiKey) {
+                updateEndpoint = "https://telemetry.armco.dev/events/tag";
+            }
+            else if (config.endpoint) {
+                updateEndpoint = config.endpoint.replace("/add", "/tag");
+            }
+            else {
+                this.logger.warn("No update endpoint configured, skipping event tagging");
+                return;
+            }
+        }
+        try {
+            this.logger.info(`Updating anonymous events (${anonymousId}) with user identity (${email})`);
+            const response = await transport.update(updateEndpoint, {
+                email,
+                anonymousId,
+            });
+            if (response.success) {
+                this.logger.info(`Successfully tagged ${anonymousId} events with user ${email}`);
+            }
+            else {
+                this.logger.warn(`Failed to tag events: ${response.error || "Unknown error"}`);
+            }
+        }
+        catch (error) {
+            this.logger.error("Error updating anonymous events:", error);
+        }
+    }
+    destroy() {
+        this.user = null;
+        this.anonymousId = null;
+    }
+}