@armco/analytics 0.2.10 → 0.2.12

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,3 @@
+import type { AnalyticsConfig } from "../core/types";
+export declare function loadConfigFromFile(): Promise<Partial<AnalyticsConfig> | null>;
+export declare function loadConfig(overrides?: Partial<AnalyticsConfig>): Promise<Partial<AnalyticsConfig>>;

package/utils/config-loader.js

@@ -0,0 +1,59 @@
+import { getEnvironmentType } from "./helpers";
+import { getLogger } from "./logging";
+const CONFIG_FILE_NAME = "analyticsrc";
+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,
+    };
+}

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;

package/utils/validation.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { ValidationError } from "../core/errors";
+const configSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().url().optional(),
+    hostProjectName: z.string().optional(),
+    trackEvents: z.array(z.string()).optional(),
+    submissionStrategy: z.enum(["ONEVENT", "DEFER"]).optional(),
+    showConsentPopup: z.boolean().optional(),
+    logLevel: z.enum(["debug", "info", "warn", "error", "none"]).optional(),
+    samplingRate: z.number().min(0).max(1).optional(),
+    enableLocation: z.boolean().optional(),
+    enableAutoTrack: z.boolean().optional(),
+    respectDoNotTrack: z.boolean().optional(),
+    batchSize: z.number().positive().optional(),
+    flushInterval: z.number().positive().optional(),
+    maxRetries: z.number().nonnegative().optional(),
+    retryDelay: z.number().positive().optional(),
+});
+const userSchema = z.object({
+    email: z.string().email("Invalid email address"),
+    id: z.string().optional(),
+    name: z.string().optional(),
+}).passthrough();
+const pageViewSchema = z.object({
+    pageName: z.string().min(1, "Page name is required"),
+    url: z.string().url("Invalid URL"),
+    referrer: z.string().optional(),
+    title: z.string().optional(),
+}).passthrough();
+const clickEventSchema = z.object({
+    elementType: z.string().min(1, "Element type is required"),
+    elementId: z.string().optional(),
+    elementText: z.string().optional(),
+    elementClasses: z.array(z.string()).optional(),
+    elementPath: z.string().optional(),
+    href: z.string().optional(),
+    value: z.string().optional(),
+}).passthrough();
+const formEventSchema = z.object({
+    formId: z.string().optional(),
+    formName: z.string().optional(),
+    formAction: z.string().optional(),
+    formMethod: z.string().optional(),
+}).passthrough();
+const errorEventSchema = z.object({
+    errorMessage: z.string().min(1, "Error message is required"),
+    errorStack: z.string().optional(),
+    errorType: z.string().optional(),
+}).passthrough();
+export function validateConfig(config) {
+    try {
+        return configSchema.parse(config);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+            throw new ValidationError(`Configuration validation failed: ${messages.join(", ")}`);
+        }
+        throw error;
+    }
+}
+export function validateUser(user) {
+    try {
+        return userSchema.parse(user);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+            throw new ValidationError(`User validation failed: ${messages.join(", ")}`);
+        }
+        throw error;
+    }
+}
+export function validatePageView(data) {
+    try {
+        return pageViewSchema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+            throw new ValidationError(`Page view validation failed: ${messages.join(", ")}`);
+        }
+        throw error;
+    }
+}
+export function validateClickEvent(data) {
+    try {
+        return clickEventSchema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+            throw new ValidationError(`Click event validation failed: ${messages.join(", ")}`);
+        }
+        throw error;
+    }
+}
+export function validateFormEvent(data) {
+    try {
+        return formEventSchema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+            throw new ValidationError(`Form event validation failed: ${messages.join(", ")}`);
+        }
+        throw error;
+    }
+}
+export function validateErrorEvent(data) {
+    try {
+        return errorEventSchema.parse(data);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.issues.map((err) => `${err.path.join(".")}: ${err.message}`);
+            throw new ValidationError(`Error event validation failed: ${messages.join(", ")}`);
+        }
+        throw error;
+    }
+}
+export function validateEventType(eventType) {
+    if (typeof eventType !== "string" || eventType.trim().length === 0) {
+        throw new ValidationError("Event type must be a non-empty string");
+    }
+    return eventType.trim();
+}
+export function sanitizeEventData(data) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value === "function" || value === undefined) {
+            continue;
+        }
+        if (typeof value === "string") {
+            sanitized[key] = value.trim();
+        }
+        else if (Array.isArray(value)) {
+            sanitized[key] = value.map((item) => typeof item === "string" ? item.trim() : item);
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}

package/.npmignore

@@ -1,6 +0,0 @@
-tsconfig*
-package-lock.json
-build.ts
-build.js
-node_modules
-index.ts

package/analytics.d.ts

@@ -1,19 +0,0 @@
-import { startSession, getSessionId } from "./session";
-import { User, Event, ConfigType } from "./index.interface";
-declare let enabled: boolean | null;
-declare function loadConfiguration(): Promise<any>;
-declare function getEnvironment(): string;
-declare function getEnvironmentType(): "browser" | "node" | "unknown";
-export declare function sendBulkData(data: Event[], callback?: Function): Promise<void>;
-declare function trackEvent(event: string | Event, data?: any): void;
-declare function trackPageView(pageName: string, data?: {
-    [key: string]: any;
-}): void;
-declare function trackError(errorMessage: string): void;
-declare function enableTracking(enable: boolean): void;
-declare function generateAnonymousId(): string;
-declare function identify(appUser: User): void;
-declare function sendHostProjectName(): void;
-declare function init(config?: ConfigType): void;
-declare function logout(): void;
-export { enabled as analyticsEnabled, init, identify, getEnvironmentType, getEnvironment, loadConfiguration, logout, trackEvent, trackPageView, trackError, enableTracking, generateAnonymousId, sendHostProjectName, getSessionId, startSession, };