@dashgram/javascript 1.0.0

package/dist/index.js

@@ -0,0 +1,148 @@
+import { Config } from "./core/config";
+import { Context } from "./core/context";
+import { Session } from "./core/session";
+import { Transport } from "./transport/transport";
+import { BatchProcessor } from "./transport/batch-processor";
+import { CoreTracker } from "./trackers/core-tracker";
+import { InteractionTracker } from "./trackers/interaction-tracker";
+import { DeepTracker } from "./trackers/deep-tracker";
+import { getTimestamp, isBrowser } from "./utils/helpers";
+import { getTelegramUserId } from "./utils/telegram";
+class DashgramSDK {
+    constructor() {
+        this.config = null;
+        this.context = null;
+        this.session = null;
+        this.transport = null;
+        this.batchProcessor = null;
+        this.trackers = [];
+        this.isInitialized = false;
+    }
+    init(userConfig) {
+        if (this.isInitialized) {
+            console.warn("Dashgram: Already initialized");
+            return;
+        }
+        if (!isBrowser()) {
+            console.warn("Dashgram: Not running in browser environment");
+            return;
+        }
+        try {
+            this.config = new Config(userConfig);
+            this.context = new Context();
+            this.session = new Session();
+            this.transport = new Transport(this.config);
+            this.batchProcessor = new BatchProcessor(this.config, this.transport);
+            this.setupTrackers();
+            this.batchProcessor.start();
+            this.isInitialized = true;
+            this.log("Initialized successfully", {
+                projectId: this.config.get("projectId"),
+                trackLevel: this.config.getTrackLevel()
+            });
+        }
+        catch (error) {
+            console.error("Dashgram: Initialization failed", error);
+            throw error;
+        }
+    }
+    setupTrackers() {
+        if (!this.config)
+            return;
+        const trackCallback = (event, properties) => {
+            this.trackAuto(event, properties);
+        };
+        const coreTracker = new CoreTracker(this.config, trackCallback);
+        this.trackers.push(coreTracker);
+        coreTracker.start();
+        const interactionTracker = new InteractionTracker(this.config, trackCallback);
+        this.trackers.push(interactionTracker);
+        interactionTracker.start();
+        const deepTracker = new DeepTracker(this.config, trackCallback);
+        this.trackers.push(deepTracker);
+        deepTracker.start();
+    }
+    track(event, properties = {}) {
+        this.ensureInitialized();
+        const fullEvent = this.buildEvent(event, properties, "manual");
+        this.batchProcessor.addEvent(fullEvent);
+        this.log("Tracked event", { event, properties });
+    }
+    trackAuto(event, properties = {}) {
+        if (!this.isInitialized)
+            return;
+        const fullEvent = this.buildEvent(event, properties, "auto");
+        this.batchProcessor.addEvent(fullEvent);
+        this.log("Auto-tracked event", { event, properties });
+    }
+    buildEvent(event, properties, source) {
+        this.ensureInitialized();
+        this.session.renewIfExpired();
+        this.session.updateLastActivity();
+        return {
+            event,
+            properties,
+            timestamp: getTimestamp(),
+            source,
+            level: this.config.getTrackLevel(),
+            session_id: this.session.getSessionId(),
+            user_id: this.context.getUserId() || getTelegramUserId(),
+            context: this.context.getContext()
+        };
+    }
+    identify(userId, traits = {}) {
+        this.ensureInitialized();
+        this.context.setUserId(userId);
+        this.track("identify", {
+            user_id: userId,
+            ...traits
+        });
+        this.log("Identified user", { userId, traits });
+    }
+    setTrackLevel(level) {
+        this.ensureInitialized();
+        const oldLevel = this.config.getTrackLevel();
+        this.config.setTrackLevel(level);
+        this.trackers.forEach(tracker => {
+            tracker.stop();
+            tracker.start();
+        });
+        this.log("Track level changed", { from: oldLevel, to: level });
+    }
+    async flush() {
+        this.ensureInitialized();
+        await this.batchProcessor.flushAsync();
+        this.log("Flushed all events");
+    }
+    reset() {
+        this.ensureInitialized();
+        this.session.reset();
+        this.context.clearUserId();
+        this.log("Reset session and user");
+    }
+    shutdown() {
+        if (!this.isInitialized) {
+            return;
+        }
+        this.trackers.forEach(tracker => tracker.stop());
+        this.trackers = [];
+        this.batchProcessor.flush();
+        this.batchProcessor.stop();
+        this.isInitialized = false;
+        this.log("Shutdown complete");
+    }
+    ensureInitialized() {
+        if (!this.isInitialized) {
+            throw new Error("Dashgram: SDK not initialized. Call init() first.");
+        }
+    }
+    log(...args) {
+        if (this.config?.isDebug()) {
+            console.log("[Dashgram SDK]", ...args);
+        }
+    }
+}
+const DashgramMini = new DashgramSDK();
+export { DashgramError, InvalidCredentialsError, DashgramAPIError, NetworkError, DashgramConfigurationError } from "./errors";
+export { DashgramMini };
+export default DashgramMini;

package/dist/trackers/base-tracker.d.ts

@@ -0,0 +1,17 @@
+import type { TrackLevel, EventProperties } from '../types';
+import type { Config } from '../core/config';
+export type TrackCallback = (event: string, properties: EventProperties) => void;
+export declare abstract class BaseTracker {
+    protected config: Config;
+    protected trackCallback: TrackCallback;
+    protected isActive: boolean;
+    protected level: TrackLevel;
+    constructor(config: Config, trackCallback: TrackCallback, level: TrackLevel);
+    start(): void;
+    stop(): void;
+    protected track(event: string, properties?: EventProperties): void;
+    protected abstract setup(): void;
+    protected abstract teardown(): void;
+    protected log(...args: any[]): void;
+}
+//# sourceMappingURL=base-tracker.d.ts.map

package/dist/trackers/base-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-tracker.d.ts","sourceRoot":"","sources":["../../src/trackers/base-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAK7C,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,KAAK,IAAI,CAAC;AAKjF,8BAAsB,WAAW;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC;IACvC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAS;IACpC,SAAS,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEhB,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU;IAS3E,KAAK,IAAI,IAAI;IAkBb,IAAI,IAAI,IAAI;IAaZ,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,eAAoB,GAAG,IAAI;IActE,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI,IAAI;IAKhC,SAAS,CAAC,QAAQ,CAAC,QAAQ,IAAI,IAAI;IAKnC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;CAKpC"}

package/dist/trackers/base-tracker.js

@@ -0,0 +1,41 @@
+export class BaseTracker {
+    constructor(config, trackCallback, level) {
+        this.isActive = false;
+        this.config = config;
+        this.trackCallback = trackCallback;
+        this.level = level;
+    }
+    start() {
+        if (this.isActive) {
+            return;
+        }
+        const currentLevel = this.config.getTrackLevel();
+        if (currentLevel >= this.level) {
+            this.isActive = true;
+            this.setup();
+            this.log(`Started (level ${this.level})`);
+        }
+    }
+    stop() {
+        if (!this.isActive) {
+            return;
+        }
+        this.isActive = false;
+        this.teardown();
+        this.log(`Stopped`);
+    }
+    track(event, properties = {}) {
+        if (!this.isActive) {
+            return;
+        }
+        this.trackCallback(event, {
+            ...properties,
+            _tracker: this.constructor.name,
+        });
+    }
+    log(...args) {
+        if (this.config.isDebug()) {
+            console.log(`[Dashgram ${this.constructor.name}]`, ...args);
+        }
+    }
+}

package/dist/trackers/core-tracker.d.ts

@@ -0,0 +1,14 @@
+import { BaseTracker } from './base-tracker';
+import type { Config } from '../core/config';
+import type { TrackCallback } from './base-tracker';
+export declare class CoreTracker extends BaseTracker {
+    private unsubscribers;
+    private hasTrackedAppOpen;
+    constructor(config: Config, trackCallback: TrackCallback);
+    protected setup(): void;
+    protected teardown(): void;
+    private trackAppOpen;
+    private setupVisibilityTracking;
+    private setupUnloadTracking;
+}
+//# sourceMappingURL=core-tracker.d.ts.map

package/dist/trackers/core-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-tracker.d.ts","sourceRoot":"","sources":["../../src/trackers/core-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMpD,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa;IAIxD,SAAS,CAAC,KAAK,IAAI,IAAI;IAgBvB,SAAS,CAAC,QAAQ,IAAI,IAAI;IAS1B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,uBAAuB;IAuB/B,OAAO,CAAC,mBAAmB;CAuB5B"}

package/dist/trackers/core-tracker.js

@@ -0,0 +1,64 @@
+import { BaseTracker } from './base-tracker';
+export class CoreTracker extends BaseTracker {
+    constructor(config, trackCallback) {
+        super(config, trackCallback, 1);
+        this.unsubscribers = [];
+        this.hasTrackedAppOpen = false;
+    }
+    setup() {
+        if (typeof window === 'undefined') {
+            return;
+        }
+        this.trackAppOpen();
+        this.track('session_start', {});
+        this.setupVisibilityTracking();
+        this.setupUnloadTracking();
+    }
+    teardown() {
+        this.unsubscribers.forEach((unsubscribe) => unsubscribe());
+        this.unsubscribers = [];
+    }
+    trackAppOpen() {
+        if (this.hasTrackedAppOpen) {
+            return;
+        }
+        this.track('app_open', {
+            referrer: document.referrer || 'direct',
+        });
+        this.hasTrackedAppOpen = true;
+    }
+    setupVisibilityTracking() {
+        const handleVisibilityChange = () => {
+            if (document.visibilityState === 'hidden') {
+                this.track('app_close', {
+                    visibility_state: 'hidden',
+                });
+            }
+            else if (document.visibilityState === 'visible') {
+                this.track('app_open', {
+                    visibility_state: 'visible',
+                });
+            }
+        };
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+        this.unsubscribers.push(() => {
+            document.removeEventListener('visibilitychange', handleVisibilityChange);
+        });
+    }
+    setupUnloadTracking() {
+        const handleUnload = () => {
+            this.track('app_close', {
+                reason: 'unload',
+            });
+            this.track('session_end', {});
+        };
+        window.addEventListener('pagehide', handleUnload);
+        this.unsubscribers.push(() => {
+            window.removeEventListener('pagehide', handleUnload);
+        });
+        window.addEventListener('beforeunload', handleUnload);
+        this.unsubscribers.push(() => {
+            window.removeEventListener('beforeunload', handleUnload);
+        });
+    }
+}

package/dist/trackers/deep-tracker.d.ts

@@ -0,0 +1,19 @@
+import { BaseTracker } from "./base-tracker";
+import type { Config } from "../core/config";
+import type { TrackCallback } from "./base-tracker";
+export declare class DeepTracker extends BaseTracker {
+    private unsubscribers;
+    private observers;
+    private clickTracker;
+    private maxScrollDepth;
+    constructor(config: Config, trackCallback: TrackCallback);
+    protected setup(): void;
+    protected teardown(): void;
+    private setupScrollTracking;
+    private setupVisibilityTracking;
+    private setupRageClickTracking;
+    private setupLongTaskTracking;
+    private setupWebVitals;
+    private setupTelegramTracking;
+}
+//# sourceMappingURL=deep-tracker.d.ts.map

package/dist/trackers/deep-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-tracker.d.ts","sourceRoot":"","sources":["../../src/trackers/deep-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AASnD,qBAAa,WAAY,SAAQ,WAAW;IAC1C,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,SAAS,CAAwD;IACzE,OAAO,CAAC,YAAY,CAAoD;IACxE,OAAO,CAAC,cAAc,CAAI;gBAEd,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa;IAIxD,SAAS,CAAC,KAAK,IAAI,IAAI;IAavB,SAAS,CAAC,QAAQ,IAAI,IAAI;IAa1B,OAAO,CAAC,mBAAmB;IA8B3B,OAAO,CAAC,uBAAuB;IA+D/B,OAAO,CAAC,sBAAsB;IA6C9B,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,cAAc;IAmFtB,OAAO,CAAC,qBAAqB;CA+B9B"}

package/dist/trackers/deep-tracker.js

@@ -0,0 +1,241 @@
+import { BaseTracker } from "./base-tracker";
+import { throttle } from "../utils/helpers";
+import { getScrollDepth } from "../utils/device";
+import { subscribeToTelegramEvent } from "../utils/telegram";
+export class DeepTracker extends BaseTracker {
+    constructor(config, trackCallback) {
+        super(config, trackCallback, 3);
+        this.unsubscribers = [];
+        this.observers = [];
+        this.clickTracker = new Map();
+        this.maxScrollDepth = 0;
+    }
+    setup() {
+        if (typeof window === "undefined") {
+            return;
+        }
+        this.setupScrollTracking();
+        this.setupVisibilityTracking();
+        this.setupRageClickTracking();
+        this.setupLongTaskTracking();
+        this.setupWebVitals();
+        this.setupTelegramTracking();
+    }
+    teardown() {
+        this.unsubscribers.forEach(unsubscribe => unsubscribe());
+        this.unsubscribers = [];
+        this.observers.forEach(observer => observer.disconnect());
+        this.observers = [];
+        this.clickTracker.clear();
+    }
+    setupScrollTracking() {
+        const handleScroll = throttle(() => {
+            const depth = getScrollDepth();
+            if (depth > this.maxScrollDepth) {
+                this.maxScrollDepth = depth;
+                const milestones = [25, 50, 75, 100];
+                const milestone = milestones.find(m => depth >= m && this.maxScrollDepth - depth < m);
+                if (milestone) {
+                    this.track("scroll_depth", {
+                        depth: milestone,
+                        max_depth: this.maxScrollDepth
+                    });
+                }
+            }
+        }, 500);
+        window.addEventListener("scroll", handleScroll, { passive: true });
+        this.unsubscribers.push(() => {
+            window.removeEventListener("scroll", handleScroll);
+        });
+    }
+    setupVisibilityTracking() {
+        if (!("IntersectionObserver" in window)) {
+            return;
+        }
+        const observer = new IntersectionObserver(entries => {
+            entries.forEach(entry => {
+                if (entry.isIntersecting) {
+                    const element = entry.target;
+                    const selector = element.getAttribute("data-track-visible");
+                    if (selector) {
+                        this.track("element_visible", {
+                            element: selector,
+                            intersection_ratio: entry.intersectionRatio
+                        });
+                        observer.unobserve(element);
+                    }
+                }
+            });
+        }, { threshold: 0.5 });
+        document.querySelectorAll("[data-track-visible]").forEach(element => {
+            observer.observe(element);
+        });
+        this.observers.push(observer);
+        const mutationObserver = new MutationObserver(mutations => {
+            mutations.forEach(mutation => {
+                mutation.addedNodes.forEach(node => {
+                    if (node instanceof Element) {
+                        if (node.hasAttribute("data-track-visible")) {
+                            observer.observe(node);
+                        }
+                        node.querySelectorAll("[data-track-visible]").forEach(el => {
+                            observer.observe(el);
+                        });
+                    }
+                });
+            });
+        });
+        mutationObserver.observe(document.body, {
+            childList: true,
+            subtree: true
+        });
+        this.unsubscribers.push(() => {
+            mutationObserver.disconnect();
+        });
+    }
+    setupRageClickTracking() {
+        const RAGE_THRESHOLD = 5;
+        const RAGE_TIMEOUT = 2000;
+        const handleClick = (event) => {
+            const target = event.target;
+            if (!target)
+                return;
+            const tracker = this.clickTracker.get(target);
+            if (tracker) {
+                tracker.count++;
+                clearTimeout(tracker.timer);
+                if (tracker.count >= RAGE_THRESHOLD) {
+                    this.track("rage_click", {
+                        element: target.tagName.toLowerCase(),
+                        click_count: tracker.count
+                    });
+                    this.clickTracker.delete(target);
+                }
+                else {
+                    tracker.timer = setTimeout(() => {
+                        this.clickTracker.delete(target);
+                    }, RAGE_TIMEOUT);
+                }
+            }
+            else {
+                const timer = setTimeout(() => {
+                    this.clickTracker.delete(target);
+                }, RAGE_TIMEOUT);
+                this.clickTracker.set(target, { count: 1, timer });
+            }
+        };
+        document.addEventListener("click", handleClick);
+        this.unsubscribers.push(() => {
+            document.removeEventListener("click", handleClick);
+        });
+    }
+    setupLongTaskTracking() {
+        if (!("PerformanceObserver" in window)) {
+            return;
+        }
+        try {
+            const observer = new PerformanceObserver(list => {
+                for (const entry of list.getEntries()) {
+                    if (entry.duration > 50) {
+                        this.track("long_task", {
+                            duration: Math.round(entry.duration),
+                            start_time: Math.round(entry.startTime)
+                        });
+                    }
+                }
+            });
+            observer.observe({ entryTypes: ["longtask"] });
+            this.observers.push(observer);
+        }
+        catch (error) {
+            this.log("Long task tracking not supported");
+        }
+    }
+    setupWebVitals() {
+        if (!("PerformanceObserver" in window)) {
+            return;
+        }
+        try {
+            const lcpObserver = new PerformanceObserver(list => {
+                const entries = list.getEntries();
+                const lastEntry = entries[entries.length - 1];
+                this.track("web_vital_lcp", {
+                    value: Math.round(lastEntry.renderTime || lastEntry.loadTime),
+                    element: lastEntry.element?.tagName.toLowerCase()
+                });
+            });
+            lcpObserver.observe({ entryTypes: ["largest-contentful-paint"] });
+            this.observers.push(lcpObserver);
+        }
+        catch (error) {
+            this.log("LCP tracking not supported");
+        }
+        try {
+            const fidObserver = new PerformanceObserver(list => {
+                const entries = list.getEntries();
+                entries.forEach((entry) => {
+                    this.track("web_vital_fid", {
+                        value: Math.round(entry.processingStart - entry.startTime),
+                        event_type: entry.name
+                    });
+                });
+            });
+            fidObserver.observe({ entryTypes: ["first-input"] });
+            this.observers.push(fidObserver);
+        }
+        catch (error) {
+            this.log("FID tracking not supported");
+        }
+        let clsValue = 0;
+        try {
+            const clsObserver = new PerformanceObserver(list => {
+                const entries = list.getEntries();
+                entries.forEach((entry) => {
+                    if (!entry.hadRecentInput) {
+                        clsValue += entry.value;
+                    }
+                });
+            });
+            clsObserver.observe({ entryTypes: ["layout-shift"] });
+            this.observers.push(clsObserver);
+            const reportCLS = () => {
+                if (clsValue > 0) {
+                    this.track("web_vital_cls", {
+                        value: Math.round(clsValue * 1000) / 1000
+                    });
+                }
+            };
+            window.addEventListener("visibilitychange", () => {
+                if (document.visibilityState === "hidden") {
+                    reportCLS();
+                }
+            });
+            this.unsubscribers.push(() => {
+                reportCLS();
+            });
+        }
+        catch (error) {
+            this.log("CLS tracking not supported");
+        }
+    }
+    setupTelegramTracking() {
+        const unsubTheme = subscribeToTelegramEvent("themeChanged", () => {
+            this.track("telegram_theme_changed", {});
+        });
+        this.unsubscribers.push(unsubTheme);
+        const unsubViewport = subscribeToTelegramEvent("viewportChanged", () => {
+            this.track("telegram_viewport_changed", {
+                is_expanded: window.Telegram?.WebApp?.isExpanded
+            });
+        });
+        this.unsubscribers.push(unsubViewport);
+        const unsubBack = subscribeToTelegramEvent("backButtonClicked", () => {
+            this.track("telegram_back_button_clicked", {});
+        });
+        this.unsubscribers.push(unsubBack);
+        const unsubMain = subscribeToTelegramEvent("mainButtonClicked", () => {
+            this.track("telegram_main_button_clicked", {});
+        });
+        this.unsubscribers.push(unsubMain);
+    }
+}

package/dist/trackers/interaction-tracker.d.ts

@@ -0,0 +1,17 @@
+import { BaseTracker } from './base-tracker';
+import type { Config } from '../core/config';
+import type { TrackCallback } from './base-tracker';
+export declare class InteractionTracker extends BaseTracker {
+    private unsubscribers;
+    private lastPath;
+    constructor(config: Config, trackCallback: TrackCallback);
+    protected setup(): void;
+    protected teardown(): void;
+    private trackScreenView;
+    private setupHistoryTracking;
+    private setupClickTracking;
+    private setupFormTracking;
+    private setupInputTracking;
+    private setupErrorTracking;
+}
+//# sourceMappingURL=interaction-tracker.d.ts.map

package/dist/trackers/interaction-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-tracker.d.ts","sourceRoot":"","sources":["../../src/trackers/interaction-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AASpD,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,QAAQ,CAAc;gBAElB,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa;IAIxD,SAAS,CAAC,KAAK,IAAI,IAAI;IAgBvB,SAAS,CAAC,QAAQ,IAAI,IAAI;IAQ1B,OAAO,CAAC,eAAe;IAoBvB,OAAO,CAAC,oBAAoB;IAgC5B,OAAO,CAAC,kBAAkB;IA+B1B,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,kBAAkB;IA4B1B,OAAO,CAAC,kBAAkB;CAgC3B"}