@armco/analytics 0.2.11 → 0.3.1

package/plugins/enrichment/user.js

@@ -0,0 +1,159 @@
+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();
+        }
+        const userId = this.getUserId();
+        if (userId) {
+            this.logger.info(`Tracking User as ${userId}`);
+        }
+    }
+    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.resolvedEndpoint) {
+                updateEndpoint = config.resolvedEndpoint.replace("/add", "/tag");
+            }
+            else if (typeof config.endpoint === "string") {
+                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;
+    }
+}

package/plugins/node/http-request-tracking.d.ts

@@ -0,0 +1,54 @@
+import type { Plugin, PluginContext, EventData } from "../../core/types";
+export interface HTTPRequestEvent extends EventData {
+    method: string;
+    path: string;
+    query?: Record<string, string | string[]>;
+    statusCode?: number;
+    duration?: number;
+    clientIp?: string;
+    userAgent?: string;
+    origin?: string;
+    referer?: string;
+    serverHostname?: string;
+    serverName?: string;
+    requestId?: string;
+    errorMessage?: string;
+}
+export interface HTTPRequestMetadata {
+    method: string;
+    path: string;
+    query?: Record<string, string | string[]>;
+    headers?: Record<string, string | string[] | undefined>;
+    clientIp?: string;
+    serverHostname?: string;
+    serverName?: string;
+    requestId?: string;
+    startTime: number;
+}
+export declare class HTTPRequestTrackingPlugin implements Plugin {
+    name: string;
+    version: string;
+    platform: "node";
+    private context?;
+    private logger;
+    private trackRequests;
+    private trackResponses;
+    private ignoreRoutes;
+    private requestMap;
+    constructor(options?: {
+        trackRequests?: boolean;
+        trackResponses?: boolean;
+        ignoreRoutes?: string[];
+    });
+    init(context: PluginContext): void;
+    trackRequestStart(metadata: HTTPRequestMetadata): void;
+    trackRequestEnd(requestId: string, statusCode: number, error?: Error): void;
+    private extractClientIp;
+    private extractUserAgent;
+    private extractReferer;
+    private detectOrigin;
+    private getServerHostname;
+    private shouldIgnoreRoute;
+    private generateRequestId;
+    destroy(): void;
+}

package/plugins/node/http-request-tracking.js

@@ -0,0 +1,158 @@
+import { getLogger } from "../../utils/logging";
+export class HTTPRequestTrackingPlugin {
+    constructor(options) {
+        this.name = "HTTPRequestTrackingPlugin";
+        this.version = "1.0.0";
+        this.platform = "node";
+        this.logger = getLogger();
+        this.trackRequests = true;
+        this.trackResponses = true;
+        this.ignoreRoutes = [];
+        this.requestMap = new Map();
+        this.trackRequests = options?.trackRequests ?? true;
+        this.trackResponses = options?.trackResponses ?? true;
+        this.ignoreRoutes = options?.ignoreRoutes ?? [];
+    }
+    init(context) {
+        this.context = context;
+        this.logger.debug("HTTP Request Tracking Plugin initialized");
+    }
+    trackRequestStart(metadata) {
+        if (!this.trackRequests || !this.context) {
+            return;
+        }
+        if (this.shouldIgnoreRoute(metadata.path)) {
+            this.logger.debug(`Ignoring route: ${metadata.path}`);
+            return;
+        }
+        const requestId = metadata.requestId || this.generateRequestId();
+        this.requestMap.set(requestId, { ...metadata, requestId });
+        const event = {
+            method: metadata.method,
+            path: metadata.path,
+            query: metadata.query,
+            clientIp: this.extractClientIp(metadata),
+            userAgent: this.extractUserAgent(metadata),
+            origin: this.detectOrigin(metadata),
+            referer: this.extractReferer(metadata),
+            serverHostname: metadata.serverHostname || this.getServerHostname(),
+            serverName: metadata.serverName,
+            requestId,
+        };
+        this.context.track("HTTP_REQUEST_START", event);
+    }
+    trackRequestEnd(requestId, statusCode, error) {
+        if (!this.trackResponses || !this.context) {
+            return;
+        }
+        const metadata = this.requestMap.get(requestId);
+        if (!metadata) {
+            this.logger.warn(`No metadata found for request: ${requestId}`);
+            return;
+        }
+        const duration = Date.now() - metadata.startTime;
+        const event = {
+            method: metadata.method,
+            path: metadata.path,
+            query: metadata.query,
+            statusCode,
+            duration,
+            clientIp: this.extractClientIp(metadata),
+            userAgent: this.extractUserAgent(metadata),
+            origin: this.detectOrigin(metadata),
+            referer: this.extractReferer(metadata),
+            serverHostname: metadata.serverHostname || this.getServerHostname(),
+            serverName: metadata.serverName,
+            requestId,
+            errorMessage: error?.message,
+        };
+        this.context.track("HTTP_REQUEST_END", event);
+        this.requestMap.delete(requestId);
+    }
+    extractClientIp(metadata) {
+        if (metadata.clientIp) {
+            return metadata.clientIp;
+        }
+        const headers = metadata.headers;
+        if (!headers) {
+            return undefined;
+        }
+        const ipHeaders = [
+            "x-forwarded-for",
+            "x-real-ip",
+            "cf-connecting-ip",
+            "x-client-ip",
+            "x-forwarded",
+            "forwarded-for",
+            "forwarded",
+        ];
+        for (const header of ipHeaders) {
+            const value = headers[header];
+            if (value) {
+                const ip = Array.isArray(value) ? value[0] : value;
+                return ip.split(",")[0].trim();
+            }
+        }
+        return undefined;
+    }
+    extractUserAgent(metadata) {
+        const headers = metadata.headers;
+        if (!headers) {
+            return undefined;
+        }
+        const ua = headers["user-agent"];
+        return Array.isArray(ua) ? ua[0] : ua;
+    }
+    extractReferer(metadata) {
+        const headers = metadata.headers;
+        if (!headers) {
+            return undefined;
+        }
+        const referer = headers["referer"] || headers["referrer"];
+        return Array.isArray(referer) ? referer[0] : referer;
+    }
+    detectOrigin(metadata) {
+        const headers = metadata.headers;
+        if (!headers) {
+            return "unknown";
+        }
+        const referer = headers["referer"] || headers["referrer"];
+        const origin = headers["origin"];
+        const userAgent = headers["user-agent"];
+        if (referer || origin) {
+            return Array.isArray(origin) ? origin[0] : (origin || "frontend");
+        }
+        const ua = Array.isArray(userAgent) ? userAgent[0] : userAgent;
+        if (ua && (ua.includes("Mozilla") || ua.includes("Chrome") || ua.includes("Safari"))) {
+            return "frontend";
+        }
+        return "backend";
+    }
+    getServerHostname() {
+        try {
+            if (typeof require !== "undefined") {
+                const os = require("os");
+                return os.hostname();
+            }
+        }
+        catch {
+        }
+        return "unknown";
+    }
+    shouldIgnoreRoute(path) {
+        return this.ignoreRoutes.some((pattern) => {
+            if (pattern.includes("*")) {
+                const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+                return regex.test(path);
+            }
+            return path === pattern;
+        });
+    }
+    generateRequestId() {
+        return `req_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+    }
+    destroy() {
+        this.requestMap.clear();
+        this.logger.debug("HTTP Request Tracking Plugin destroyed");
+    }
+}

package/storage/cookie-storage.d.ts

@@ -0,0 +1,8 @@
+import type { StorageManager, StorageOptions } from "../core/types";
+export declare class CookieStorage implements StorageManager {
+    private logger;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string, options?: StorageOptions): void;
+    removeItem(key: string): void;
+    clear(): void;
+}

package/storage/cookie-storage.js

@@ -0,0 +1,60 @@
+import Cookies from "js-cookie";
+import { StorageError } from "../core/errors";
+import { getLogger } from "../utils/logging";
+export class CookieStorage {
+    constructor() {
+        this.logger = getLogger();
+    }
+    getItem(key) {
+        try {
+            const value = Cookies.get(key);
+            return value !== undefined ? value : null;
+        }
+        catch (error) {
+            this.logger.error(`Failed to get cookie: ${key}`, error);
+            throw new StorageError(`Failed to get cookie: ${key}`);
+        }
+    }
+    setItem(key, value, options) {
+        try {
+            const cookieOptions = {};
+            if (options?.expires) {
+                cookieOptions.expires = options.expires;
+            }
+            if (options?.secure) {
+                cookieOptions.secure = true;
+            }
+            if (options?.sameSite) {
+                cookieOptions.sameSite = options.sameSite;
+            }
+            Cookies.set(key, value, cookieOptions);
+        }
+        catch (error) {
+            this.logger.error(`Failed to set cookie: ${key}`, error);
+            throw new StorageError(`Failed to set cookie: ${key}`);
+        }
+    }
+    removeItem(key) {
+        try {
+            Cookies.remove(key);
+        }
+        catch (error) {
+            this.logger.error(`Failed to remove cookie: ${key}`, error);
+            throw new StorageError(`Failed to remove cookie: ${key}`);
+        }
+    }
+    clear() {
+        try {
+            const cookies = document.cookie.split(";");
+            for (const cookie of cookies) {
+                const eqPos = cookie.indexOf("=");
+                const name = eqPos > -1 ? cookie.slice(0, eqPos) : cookie;
+                Cookies.remove(name.trim());
+            }
+        }
+        catch (error) {
+            this.logger.error("Failed to clear cookies", error);
+            throw new StorageError("Failed to clear cookies");
+        }
+    }
+}

package/storage/hybrid-storage.d.ts

@@ -0,0 +1,12 @@
+import type { StorageManager, StorageOptions } from "../core/types";
+export declare class HybridStorage implements StorageManager {
+    private primary;
+    private fallback;
+    private logger;
+    constructor();
+    getItem(key: string): string | null;
+    setItem(key: string, value: string, options?: StorageOptions): void;
+    removeItem(key: string): void;
+    clear(): void;
+    isAvailable(): boolean;
+}

package/storage/hybrid-storage.js

@@ -0,0 +1,108 @@
+import { CookieStorage } from "./cookie-storage";
+import { LocalStorage } from "./local-storage";
+import { areCookiesAvailable, isLocalStorageAvailable } from "../utils/helpers";
+import { getLogger } from "../utils/logging";
+export class HybridStorage {
+    constructor() {
+        this.primary = null;
+        this.fallback = null;
+        this.logger = getLogger();
+        if (areCookiesAvailable()) {
+            this.primary = new CookieStorage();
+            this.logger.debug("Using cookies as primary storage");
+        }
+        if (isLocalStorageAvailable()) {
+            if (this.primary) {
+                this.fallback = new LocalStorage();
+                this.logger.debug("Using localStorage as fallback storage");
+            }
+            else {
+                this.primary = new LocalStorage();
+                this.logger.debug("Using localStorage as primary storage");
+            }
+        }
+        if (!this.primary) {
+            this.logger.warn("No storage mechanism available");
+        }
+    }
+    getItem(key) {
+        if (!this.primary) {
+            return null;
+        }
+        try {
+            return this.primary.getItem(key);
+        }
+        catch (error) {
+            this.logger.warn("Primary storage failed, trying fallback", error);
+            if (this.fallback) {
+                try {
+                    return this.fallback.getItem(key);
+                }
+                catch (fallbackError) {
+                    this.logger.error("Both storage mechanisms failed", fallbackError);
+                    return null;
+                }
+            }
+            return null;
+        }
+    }
+    setItem(key, value, options) {
+        if (!this.primary) {
+            return;
+        }
+        try {
+            this.primary.setItem(key, value, options);
+        }
+        catch (error) {
+            this.logger.warn("Primary storage failed, trying fallback", error);
+            if (this.fallback) {
+                try {
+                    this.fallback.setItem(key, value, options);
+                }
+                catch (fallbackError) {
+                    this.logger.error("Both storage mechanisms failed", fallbackError);
+                }
+            }
+        }
+    }
+    removeItem(key) {
+        if (!this.primary) {
+            return;
+        }
+        try {
+            this.primary.removeItem(key);
+        }
+        catch (error) {
+            this.logger.warn("Primary storage failed, trying fallback", error);
+        }
+        if (this.fallback) {
+            try {
+                this.fallback.removeItem(key);
+            }
+            catch (fallbackError) {
+                this.logger.error("Fallback storage failed", fallbackError);
+            }
+        }
+    }
+    clear() {
+        if (this.primary) {
+            try {
+                this.primary.clear();
+            }
+            catch (error) {
+                this.logger.error("Failed to clear primary storage", error);
+            }
+        }
+        if (this.fallback) {
+            try {
+                this.fallback.clear();
+            }
+            catch (error) {
+                this.logger.error("Failed to clear fallback storage", error);
+            }
+        }
+    }
+    isAvailable() {
+        return this.primary !== null;
+    }
+}

package/storage/local-storage.d.ts

@@ -0,0 +1,8 @@
+import type { StorageManager, StorageOptions } from "../core/types";
+export declare class LocalStorage implements StorageManager {
+    private logger;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string, options?: StorageOptions): void;
+    removeItem(key: string): void;
+    clear(): void;
+}

package/storage/local-storage.js

@@ -0,0 +1,65 @@
+import { StorageError } from "../core/errors";
+import { getLogger } from "../utils/logging";
+export class LocalStorage {
+    constructor() {
+        this.logger = getLogger();
+    }
+    getItem(key) {
+        try {
+            const stored = localStorage.getItem(key);
+            if (!stored) {
+                return null;
+            }
+            try {
+                const parsed = JSON.parse(stored);
+                if (parsed.expires && Date.now() > parsed.expires) {
+                    this.removeItem(key);
+                    return null;
+                }
+                return parsed.value;
+            }
+            catch {
+                return stored;
+            }
+        }
+        catch (error) {
+            this.logger.error(`Failed to get from localStorage: ${key}`, error);
+            throw new StorageError(`Failed to get from localStorage: ${key}`);
+        }
+    }
+    setItem(key, value, options) {
+        try {
+            let toStore = value;
+            if (options?.expires) {
+                const storageValue = {
+                    value,
+                    expires: options.expires.getTime(),
+                };
+                toStore = JSON.stringify(storageValue);
+            }
+            localStorage.setItem(key, toStore);
+        }
+        catch (error) {
+            this.logger.error(`Failed to set in localStorage: ${key}`, error);
+            throw new StorageError(`Failed to set in localStorage: ${key}`);
+        }
+    }
+    removeItem(key) {
+        try {
+            localStorage.removeItem(key);
+        }
+        catch (error) {
+            this.logger.error(`Failed to remove from localStorage: ${key}`, error);
+            throw new StorageError(`Failed to remove from localStorage: ${key}`);
+        }
+    }
+    clear() {
+        try {
+            localStorage.clear();
+        }
+        catch (error) {
+            this.logger.error("Failed to clear localStorage", error);
+            throw new StorageError("Failed to clear localStorage");
+        }
+    }
+}

package/storage/memory-storage.d.ts

@@ -0,0 +1,9 @@
+import type { StorageManager, StorageOptions } from "../core/types";
+export declare class MemoryStorage implements StorageManager {
+    private store;
+    private logger;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string, _options?: StorageOptions): void;
+    removeItem(key: string): void;
+    clear(): void;
+}

package/storage/memory-storage.js

@@ -0,0 +1,22 @@
+import { getLogger } from "../utils/logging";
+export class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+        this.logger = getLogger();
+    }
+    getItem(key) {
+        return this.store.get(key) ?? null;
+    }
+    setItem(key, value, _options) {
+        this.store.set(key, value);
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        if (this.store.size > 0) {
+            this.logger.debug("Clearing in-memory analytics storage");
+        }
+        this.store.clear();
+    }
+}

package/transport/beacon-transport.d.ts

@@ -0,0 +1,16 @@
+import type { Transport, TransportResponse, TrackingEvent } from "../core/types";
+export interface BeaconTransportOptions {
+    apiKey?: string;
+}
+export declare class BeaconTransport implements Transport {
+    private options;
+    private logger;
+    constructor(options?: BeaconTransportOptions);
+    send(endpoint: string, event: TrackingEvent): Promise<TransportResponse>;
+    sendBatch(endpoint: string, events: TrackingEvent[]): Promise<TransportResponse>;
+    update(endpoint: string, payload: {
+        email: string;
+        anonymousId: string;
+    }): Promise<TransportResponse>;
+    private sendBeacon;
+}