@armco/analytics 0.2.11 → 0.2.12

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;
+}

package/transport/beacon-transport.js

@@ -0,0 +1,50 @@
+import { NetworkError } from "../core/errors";
+import { getLogger } from "../utils/logging";
+export class BeaconTransport {
+    constructor(options = {}) {
+        this.logger = getLogger();
+        this.options = options;
+    }
+    async send(endpoint, event) {
+        return this.sendBeacon(endpoint, { event });
+    }
+    async sendBatch(endpoint, events) {
+        return this.sendBeacon(endpoint, { events });
+    }
+    async update(endpoint, payload) {
+        this.logger.warn("BeaconTransport does not support update operations. Use FetchTransport for user identification updates.");
+        return {
+            success: false,
+            error: "Update not supported by BeaconTransport",
+        };
+    }
+    async sendBeacon(endpoint, payload) {
+        if (!navigator.sendBeacon) {
+            this.logger.warn("Beacon API not available, data may be lost");
+            throw new NetworkError("Beacon API not available", undefined, endpoint);
+        }
+        try {
+            const blob = new Blob([JSON.stringify(payload)], {
+                type: "application/json",
+            });
+            const success = navigator.sendBeacon(endpoint, blob);
+            if (success) {
+                this.logger.debug(`Successfully queued beacon to ${endpoint}`);
+                return {
+                    success: true,
+                };
+            }
+            else {
+                this.logger.warn(`Failed to queue beacon to ${endpoint}`);
+                return {
+                    success: false,
+                    error: "Beacon queue full or rejected",
+                };
+            }
+        }
+        catch (error) {
+            this.logger.error(`Error sending beacon to ${endpoint}:`, error);
+            throw new NetworkError(`Failed to send beacon: ${error}`, undefined, endpoint);
+        }
+    }
+}

package/transport/fetch-transport.d.ts

@@ -0,0 +1,20 @@
+import type { Transport, TransportResponse, TrackingEvent } from "../core/types";
+export interface FetchTransportOptions {
+    apiKey?: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+export declare class FetchTransport implements Transport {
+    private options;
+    private logger;
+    constructor(options?: FetchTransportOptions);
+    send(endpoint: string, event: TrackingEvent): Promise<TransportResponse>;
+    sendBatch(endpoint: string, events: TrackingEvent[]): Promise<TransportResponse>;
+    private sendWithRetry;
+    update(endpoint: string, payload: {
+        email: string;
+        anonymousId: string;
+    }): Promise<TransportResponse>;
+    private delay;
+}