@armco/analytics 0.2.11 → 0.3.1

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

package/transport/fetch-transport.js

@@ -0,0 +1,112 @@
+import { NetworkError } from "../core/errors";
+import { getLogger } from "../utils/logging";
+export class FetchTransport {
+    constructor(options = {}) {
+        this.logger = getLogger();
+        this.options = {
+            timeout: 5000,
+            maxRetries: 3,
+            retryDelay: 1000,
+            ...options,
+        };
+    }
+    async send(endpoint, event) {
+        return this.sendWithRetry(endpoint, { event }, 0);
+    }
+    async sendBatch(endpoint, events) {
+        return this.sendWithRetry(endpoint, { events }, 0);
+    }
+    async sendWithRetry(endpoint, payload, attempt) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.options.timeout);
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            if (this.options.apiKey) {
+                headers["Authorization"] = `Bearer ${this.options.apiKey}`;
+            }
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                this.logger.debug(`Successfully sent data to ${endpoint}`);
+                return {
+                    success: true,
+                    statusCode: response.status,
+                };
+            }
+            else {
+                const errorText = await response.text().catch(() => "Unknown error");
+                this.logger.warn(`Failed to send data to ${endpoint}: ${response.status} ${errorText}`);
+                if (response.status >= 500 &&
+                    attempt < (this.options.maxRetries ?? 3)) {
+                    await this.delay(this.options.retryDelay ?? 1000);
+                    return this.sendWithRetry(endpoint, payload, attempt + 1);
+                }
+                return {
+                    success: false,
+                    statusCode: response.status,
+                    error: errorText,
+                };
+            }
+        }
+        catch (error) {
+            this.logger.error(`Network error sending to ${endpoint}:`, error);
+            if (attempt < (this.options.maxRetries ?? 3)) {
+                await this.delay(this.options.retryDelay ?? 1000);
+                return this.sendWithRetry(endpoint, payload, attempt + 1);
+            }
+            throw new NetworkError(`Failed to send data after ${attempt + 1} attempts`, undefined, endpoint);
+        }
+    }
+    async update(endpoint, payload) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.options.timeout);
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            if (this.options.apiKey) {
+                headers["Authorization"] = `Bearer ${this.options.apiKey}`;
+            }
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                this.logger.debug(`Successfully updated events for ${payload.email}`);
+                return {
+                    success: true,
+                    statusCode: response.status,
+                };
+            }
+            else {
+                const errorText = await response.text().catch(() => "Unknown error");
+                this.logger.warn(`Failed to update events: ${response.status} ${errorText}`);
+                return {
+                    success: false,
+                    statusCode: response.status,
+                    error: errorText,
+                };
+            }
+        }
+        catch (error) {
+            this.logger.error(`Network error updating events:`, error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/utils/config-loader.d.ts

@@ -0,0 +1,6 @@
+import type { AnalyticsConfig, EnvironmentName } from "../core/types";
+export declare function loadConfigFromFile(): Promise<Partial<AnalyticsConfig> | null>;
+export declare function loadConfig(overrides?: Partial<AnalyticsConfig>): Promise<Partial<AnalyticsConfig>>;
+export declare function detectEnvironment(): EnvironmentName;
+export declare function checkEndpointHealth(url: string): Promise<boolean>;
+export declare function resolveEndpoint(config: Partial<AnalyticsConfig>): Promise<string>;

package/utils/config-loader.js

@@ -0,0 +1,168 @@
+import { getEnvironmentType } from "./helpers";
+import { getLogger } from "./logging";
+const CONFIG_FILE_NAME = "analyticsrc";
+const DEFAULT_FALLBACK_ENDPOINT = "http://localhost:5001/events/add";
+const logger = getLogger();
+export async function loadConfigFromFile() {
+    const envType = getEnvironmentType();
+    if (envType !== "node") {
+        logger.warn("Config file loading is only supported in Node.js environment");
+        return null;
+    }
+    try {
+        const fs = await import("fs");
+        const path = await import("path");
+        const projectRoot = process.cwd();
+        const configPaths = [
+            path.resolve(projectRoot, `${CONFIG_FILE_NAME}.json`),
+            path.resolve(projectRoot, `${CONFIG_FILE_NAME}.ts`),
+            path.resolve(projectRoot, `${CONFIG_FILE_NAME}.js`),
+        ];
+        for (const configPath of configPaths) {
+            if (fs.existsSync(configPath)) {
+                logger.debug(`Loading config from: ${configPath}`);
+                try {
+                    if (configPath.endsWith(".json")) {
+                        const content = fs.readFileSync(configPath, "utf-8");
+                        const config = JSON.parse(content);
+                        logger.info(`Successfully loaded config from ${configPath}`);
+                        return config;
+                    }
+                    else {
+                        const config = await import(configPath);
+                        logger.info(`Successfully loaded config from ${configPath}`);
+                        return config.default || config;
+                    }
+                }
+                catch (error) {
+                    logger.error(`Failed to parse config from ${configPath}:`, error);
+                    continue;
+                }
+            }
+        }
+        logger.warn(`No ${CONFIG_FILE_NAME} file found in project root: ${projectRoot}`);
+        return null;
+    }
+    catch (error) {
+        logger.error("Failed to load config from file:", error);
+        return null;
+    }
+}
+export async function loadConfig(overrides) {
+    const fileConfig = await loadConfigFromFile();
+    if (!fileConfig && !overrides) {
+        throw new Error("No configuration provided. Either create an analyticsrc.json file or provide config programmatically.");
+    }
+    return {
+        ...fileConfig,
+        ...overrides,
+    };
+}
+export function detectEnvironment() {
+    const envType = getEnvironmentType();
+    if (envType === "node") {
+        const nodeEnv = process.env.NODE_ENV?.toLowerCase();
+        if (nodeEnv) {
+            return nodeEnv;
+        }
+        return "development";
+    }
+    if (envType === "browser") {
+        const hostname = window.location.hostname;
+        if (hostname === "localhost" || hostname === "127.0.0.1") {
+            return "development";
+        }
+        if (hostname.includes("staging") || hostname.includes("stage")) {
+            return "staging";
+        }
+        if (hostname.includes("test") || hostname.includes("qa")) {
+            return "test";
+        }
+        return "production";
+    }
+    return "development";
+}
+export async function checkEndpointHealth(url) {
+    try {
+        const envType = getEnvironmentType();
+        if (envType === "node") {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            try {
+                const response = await fetch(url.replace("/events/add", "/health"), {
+                    method: "GET",
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                return response.ok || response.status === 404;
+            }
+            catch {
+                clearTimeout(timeout);
+                return false;
+            }
+        }
+        else if (envType === "browser") {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            try {
+                const response = await fetch(url.replace("/events/add", "/health"), {
+                    method: "GET",
+                    mode: "no-cors",
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                return true;
+            }
+            catch {
+                clearTimeout(timeout);
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveEndpoint(config) {
+    const currentEnv = config.environment || detectEnvironment();
+    logger.info(`Identified environment: ${currentEnv}`);
+    if (typeof config.endpoint === "string") {
+        logger.debug(`Using single endpoint: ${config.endpoint}`);
+        return config.endpoint;
+    }
+    if (config.endpoint && typeof config.endpoint === "object") {
+        const endpoints = config.endpoint;
+        const envEndpoint = endpoints[currentEnv];
+        if (envEndpoint) {
+            logger.info(`Found endpoint for environment '${currentEnv}': ${envEndpoint}`);
+            const isHealthy = await checkEndpointHealth(envEndpoint);
+            if (isHealthy) {
+                logger.info(`Endpoint ${envEndpoint} is reachable`);
+                return envEndpoint;
+            }
+            else {
+                logger.warn(`Endpoint ${envEndpoint} is not reachable, falling back to ${DEFAULT_FALLBACK_ENDPOINT}`);
+                return DEFAULT_FALLBACK_ENDPOINT;
+            }
+        }
+        else {
+            const fallbackOrder = ["development", "local", "staging", "production"];
+            for (const fallbackEnv of fallbackOrder) {
+                if (endpoints[fallbackEnv]) {
+                    logger.warn(`No endpoint configured for '${currentEnv}', using '${fallbackEnv}' endpoint: ${endpoints[fallbackEnv]}`);
+                    return endpoints[fallbackEnv];
+                }
+            }
+            logger.warn(`No endpoint found in configuration, using fallback: ${DEFAULT_FALLBACK_ENDPOINT}`);
+            return DEFAULT_FALLBACK_ENDPOINT;
+        }
+    }
+    if (config.apiKey) {
+        const defaultEndpoint = "https://telemetry.armco.dev/events/add";
+        logger.info(`Using default Armco endpoint: ${defaultEndpoint}`);
+        return defaultEndpoint;
+    }
+    logger.warn(`No endpoint configured, using fallback: ${DEFAULT_FALLBACK_ENDPOINT}`);
+    return DEFAULT_FALLBACK_ENDPOINT;
+}

package/utils/helpers.d.ts

@@ -0,0 +1,15 @@
+import type { Environment } from "../core/types";
+export declare function generateId(): string;
+export declare function getEnvironmentType(): Environment;
+export declare function getEnvironment(): string;
+export declare function isDoNotTrackEnabled(): boolean;
+export declare function isBrowser(): boolean;
+export declare function areCookiesAvailable(): boolean;
+export declare function isLocalStorageAvailable(): boolean;
+export declare function debounce<T extends (...args: unknown[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void;
+export declare function throttle<T extends (...args: unknown[]) => void>(func: T, limit: number): (...args: Parameters<T>) => void;
+export declare function deepClone<T>(obj: T): T;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;
+export declare function getTimestamp(): Date;
+export declare function isArmcoClient(name: string | null): boolean;

package/utils/helpers.js

@@ -0,0 +1,148 @@
+import { v4 as uuidv4 } from "uuid";
+export function generateId() {
+    return uuidv4();
+}
+export function getEnvironmentType() {
+    if (typeof window !== "undefined" && typeof window.document !== "undefined") {
+        return "browser";
+    }
+    else if (typeof process !== "undefined" &&
+        process.versions != null &&
+        process.versions.node != null) {
+        return "node";
+    }
+    else {
+        return "unknown";
+    }
+}
+export function getEnvironment() {
+    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV) {
+        return process.env.NODE_ENV;
+    }
+    try {
+        const getImportMeta = new Function('return typeof import.meta !== "undefined" ? import.meta : null');
+        const meta = getImportMeta();
+        if (meta && meta.env && meta.env.MODE) {
+            return meta.env.MODE;
+        }
+    }
+    catch (e) {
+    }
+    return "development";
+}
+export function isDoNotTrackEnabled() {
+    if (typeof navigator !== "undefined" && "doNotTrack" in navigator) {
+        const doNotTrackValue = navigator.doNotTrack;
+        return doNotTrackValue === "1" || doNotTrackValue === "yes";
+    }
+    return false;
+}
+export function isBrowser() {
+    return getEnvironmentType() === "browser";
+}
+export function areCookiesAvailable() {
+    if (!isBrowser()) {
+        return false;
+    }
+    try {
+        document.cookie = "test=1";
+        const result = document.cookie.indexOf("test=") !== -1;
+        document.cookie = "test=1; expires=Thu, 01-Jan-1970 00:00:01 GMT";
+        return result;
+    }
+    catch {
+        return false;
+    }
+}
+export function isLocalStorageAvailable() {
+    if (!isBrowser()) {
+        return false;
+    }
+    try {
+        const test = "__storage_test__";
+        localStorage.setItem(test, test);
+        localStorage.removeItem(test);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function debounce(func, wait) {
+    let timeout = null;
+    return function (...args) {
+        const later = () => {
+            timeout = null;
+            func.apply(this, args);
+        };
+        if (timeout !== null) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(later, wait);
+    };
+}
+export function throttle(func, limit) {
+    let inThrottle;
+    return function (...args) {
+        if (!inThrottle) {
+            func.apply(this, args);
+            inThrottle = true;
+            setTimeout(() => (inThrottle = false), limit);
+        }
+    };
+}
+export function deepClone(obj) {
+    if (obj === null || typeof obj !== "object") {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (obj instanceof Array) {
+        return obj.map((item) => deepClone(item));
+    }
+    if (obj instanceof Object) {
+        const cloned = {};
+        for (const key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                cloned[key] = deepClone(obj[key]);
+            }
+        }
+        return cloned;
+    }
+    return obj;
+}
+export function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.constructor === Object &&
+        Object.prototype.toString.call(value) === "[object Object]");
+}
+export function deepMerge(target, ...sources) {
+    if (!sources.length) {
+        return target;
+    }
+    const source = sources.shift();
+    if (!source) {
+        return deepMerge(target, ...sources);
+    }
+    for (const key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const sourceValue = source[key];
+            const targetValue = target[key];
+            if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
+                target[key] = deepMerge({ ...targetValue }, sourceValue);
+            }
+            else if (sourceValue !== undefined) {
+                target[key] = sourceValue;
+            }
+        }
+    }
+    return deepMerge(target, ...sources);
+}
+export function getTimestamp() {
+    return new Date();
+}
+export function isArmcoClient(name) {
+    return !!(name && name.startsWith("@armco"));
+}

package/utils/logging.d.ts

@@ -0,0 +1,17 @@
+import type { LogLevel } from "../core/types";
+export declare class Logger {
+    private level;
+    private prefix;
+    constructor(level?: LogLevel, prefix?: string);
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    private format;
+    private shouldLog;
+}
+export declare function getLogger(): Logger;
+export declare function setLogger(logger: Logger): void;
+export declare function createLogger(level?: LogLevel, prefix?: string): Logger;

package/utils/logging.js

@@ -0,0 +1,54 @@
+export class Logger {
+    constructor(level = "info", prefix = "[ANALYTICS]") {
+        this.level = level;
+        this.prefix = prefix;
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    getLevel() {
+        return this.level;
+    }
+    debug(message, ...args) {
+        if (this.shouldLog("debug")) {
+            console.debug(this.format(message), ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.shouldLog("info")) {
+            console.info(this.format(message), ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.shouldLog("warn")) {
+            console.warn(this.format(message), ...args);
+        }
+    }
+    error(message, ...args) {
+        if (this.shouldLog("error")) {
+            console.error(this.format(message), ...args);
+        }
+    }
+    format(message) {
+        return `${this.prefix} ${message}`;
+    }
+    shouldLog(messageLevel) {
+        if (this.level === "none") {
+            return false;
+        }
+        const levels = ["debug", "info", "warn", "error", "none"];
+        const currentLevelIndex = levels.indexOf(this.level);
+        const messageLevelIndex = levels.indexOf(messageLevel);
+        return messageLevelIndex >= currentLevelIndex;
+    }
+}
+let defaultLogger = new Logger();
+export function getLogger() {
+    return defaultLogger;
+}
+export function setLogger(logger) {
+    defaultLogger = logger;
+}
+export function createLogger(level = "info", prefix = "[Analytics]") {
+    return new Logger(level, prefix);
+}

package/utils/validation.d.ts

@@ -0,0 +1,9 @@
+import type { AnalyticsConfig, EventData, User, PageViewEvent, ClickEvent, FormEvent, ErrorEvent } from "../core/types";
+export declare function validateConfig(config: unknown): AnalyticsConfig;
+export declare function validateUser(user: unknown): User;
+export declare function validatePageView(data: unknown): PageViewEvent;
+export declare function validateClickEvent(data: unknown): ClickEvent;
+export declare function validateFormEvent(data: unknown): FormEvent;
+export declare function validateErrorEvent(data: unknown): ErrorEvent;
+export declare function validateEventType(eventType: unknown): string;
+export declare function sanitizeEventData(data: EventData): EventData;