@thisbefine/analytics 0.2.0 → 0.3.0

package/dist/core/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACtB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,OAAO,OAAO,KAAG,MAoB7D,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACtB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAyCD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GACxB,QAAQ,MAAM,EACd,OAAO,OAAO,EACd,oBAAkB,KAChB,MAuDF,CAAC"}

package/dist/core/logger.js

@@ -1,8 +1,30 @@
+/**
+ * Format arguments into a message string and optional data
+ */
+const formatArgs = (args) => {
+    if (args.length === 0) {
+        return { message: "" };
+    }
+    const message = String(args[0]);
+    if (args.length === 1) {
+        return { message };
+    }
+    if (args.length === 2 && typeof args[1] === "object" && args[1] !== null) {
+        return { message, data: args[1] };
+    }
+    return {
+        message: args
+            .map((arg) => typeof arg === "object" ? JSON.stringify(arg) : String(arg))
+            .join(" "),
+        data: args.slice(1),
+    };
+};
 /**
  * Create a namespaced debug logger
  *
  * @param prefix - Module name (e.g., "Queue", "Session", "Errors")
  * @param debug - Whether debug mode is enabled
+ * @param structured - Whether to output structured JSON logs
  * @returns Logger interface with log, warn, and error methods
  *
  * @example
@@ -13,8 +35,38 @@
  * logger.error("Failed to send batch:", error);
  * ```
  */
-export const createLogger = (prefix, debug) => {
+export const createLogger = (prefix, debug, structured = false) => {
     const shouldLog = debug && typeof console !== "undefined";
+    const logStructured = (level, args) => {
+        const { message, data } = formatArgs(args);
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            module: prefix,
+            message,
+            ...(data !== undefined && { data }),
+        };
+        console.log(JSON.stringify(entry));
+    };
+    if (structured) {
+        return {
+            log: (...args) => {
+                if (shouldLog) {
+                    logStructured("debug", args);
+                }
+            },
+            warn: (...args) => {
+                if (shouldLog) {
+                    logStructured("warn", args);
+                }
+            },
+            error: (...args) => {
+                if (typeof console !== "undefined") {
+                    logStructured("error", args);
+                }
+            },
+        };
+    }
     return {
         log: (...args) => {
             if (shouldLog) {

package/dist/core/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAE,KAAc,EAAU,EAAE;IACtE,MAAM,SAAS,GAAG,KAAK,IAAI,OAAO,OAAO,KAAK,WAAW,CAAC;IAE1D,OAAO;QACN,GAAG,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;YAC3B,IAAI,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,eAAe,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAChD,CAAC;QACF,CAAC;QACD,IAAI,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;YAC5B,IAAI,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,eAAe,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YACjD,CAAC;QACF,CAAC;QACD,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;YAC7B,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;gBACpC,OAAO,CAAC,KAAK,CAAC,eAAe,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAClD,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}

package/dist/core/privacy.d.ts

@@ -1,15 +1,30 @@
-import type { StorageInterface } from "./types";
+import type { ConsentCategory, ConsentConfig, StorageInterface } from "./types";
 /**
  * Privacy manager handles:
  * - Do Not Track (DNT) detection
  * - Global Privacy Control (GPC) detection
  * - User opt-out/opt-in state
+ * - Granular consent categories (analytics, marketing, functional)
  */
 export declare class Privacy {
     private storage;
     private respectDNT;
     private debug;
-    constructor(storage: StorageInterface, respectDNT: boolean, debug?: boolean);
+    private consentConfig;
+    private consentCategories;
+    constructor(storage: StorageInterface, respectDNT: boolean, debug?: boolean, consentConfig?: ConsentConfig);
+    /**
+     * Load consent categories from storage.
+     * Fails safe: if stored consent is corrupted, returns empty set (no consent)
+     * rather than defaulting to consent, to protect user privacy.
+     */
+    private loadConsentFromStorage;
+    /**
+     * Save consent categories to storage.
+     * Returns true if saved successfully, false otherwise.
+     * Warns on failure since consent preferences may not persist across sessions.
+     */
+    private saveConsentToStorage;
     /**
      * Check if Do Not Track is enabled in the browser
      */
@@ -35,6 +50,38 @@ export declare class Privacy {
      * Check if tracking should be allowed based on all privacy signals
      */
     shouldTrack(): boolean;
+    /**
+     * Check if tracking is allowed for a specific consent category
+     */
+    shouldTrackForCategory(category: ConsentCategory): boolean;
+    /**
+     * Check if a specific consent category is enabled
+     */
+    hasConsent(category: ConsentCategory): boolean;
+    /**
+     * Get all currently consented categories
+     */
+    getConsentedCategories(): ConsentCategory[];
+    /**
+     * Set consent for specific categories (replaces current consent)
+     */
+    setConsent(categories: ConsentCategory[]): void;
+    /**
+     * Grant consent for a specific category
+     */
+    grantConsent(category: ConsentCategory): void;
+    /**
+     * Revoke consent for a specific category
+     */
+    revokeConsent(category: ConsentCategory): void;
+    /**
+     * Grant consent for all categories
+     */
+    grantAllConsent(): void;
+    /**
+     * Revoke consent for all categories
+     */
+    revokeAllConsent(): void;
     /**
      * Get a summary of privacy signals for debugging
      */
@@ -44,6 +91,7 @@ export declare class Privacy {
         optedOut: boolean;
         respectDNT: boolean;
         trackingAllowed: boolean;
+        consentCategories: ConsentCategory[];
     };
     /**
      * Debug logger

package/dist/core/privacy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"privacy.d.ts","sourceRoot":"","sources":["../../src/core/privacy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD;;;;;GAKG;AACH,qBAAa,OAAO;IACnB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,KAAK,CAAU;gBAEX,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,UAAQ;IAMzE;;OAEG;IACH,YAAY,IAAI,OAAO;IAWvB;;;OAGG;IACH,YAAY,IAAI,OAAO;IASvB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,MAAM,IAAI,IAAI;IAKd;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,WAAW,IAAI,OAAO;IAmBtB;;OAEG;IACH,gBAAgB,IAAI;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,OAAO,CAAC;QACpB,eAAe,EAAE,OAAO,CAAC;KACzB;IAUD;;OAEG;IACH,OAAO,CAAC,GAAG;CAKX"}
+{"version":3,"file":"privacy.d.ts","sourceRoot":"","sources":["../../src/core/privacy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAahF;;;;;;GAMG;AACH,qBAAa,OAAO;IACnB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAAuB;gBAG/C,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,OAAO,EACnB,KAAK,UAAQ,EACb,aAAa,CAAC,EAAE,aAAa;IAU9B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IA4B9B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;OAEG;IACH,YAAY,IAAI,OAAO;IAWvB;;;OAGG;IACH,YAAY,IAAI,OAAO;IASvB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,MAAM,IAAI,IAAI;IAKd;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,WAAW,IAAI,OAAO;IAmBtB;;OAEG;IACH,sBAAsB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAO1D;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAI9C;;OAEG;IACH,sBAAsB,IAAI,eAAe,EAAE;IAI3C;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,IAAI;IAQ/C;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAQ7C;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAM9C;;OAEG;IACH,eAAe,IAAI,IAAI;IAMvB;;OAEG;IACH,gBAAgB,IAAI,IAAI;IAMxB;;OAEG;IACH,gBAAgB,IAAI;QACnB,UAAU,EAAE,OAAO,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,OAAO,CAAC;QACpB,eAAe,EAAE,OAAO,CAAC;QACzB,iBAAiB,EAAE,eAAe,EAAE,CAAC;KACrC;IAWD;;OAEG;IACH,OAAO,CAAC,GAAG;CAKX"}

package/dist/core/privacy.js

@@ -1,15 +1,68 @@
 import { STORAGE_KEYS } from "./types";
+/** Storage key for consent categories */
+const CONSENT_KEY = "tif_consent";
+/** All available consent categories */
+const ALL_CATEGORIES = [
+    "analytics",
+    "marketing",
+    "functional",
+];
 /**
  * Privacy manager handles:
  * - Do Not Track (DNT) detection
  * - Global Privacy Control (GPC) detection
  * - User opt-out/opt-in state
+ * - Granular consent categories (analytics, marketing, functional)
  */
 export class Privacy {
-    constructor(storage, respectDNT, debug = false) {
+    constructor(storage, respectDNT, debug = false, consentConfig) {
         this.storage = storage;
         this.respectDNT = respectDNT;
         this.debug = debug;
+        this.consentConfig = consentConfig ?? {};
+        this.consentCategories = this.loadConsentFromStorage();
+    }
+    /**
+     * Load consent categories from storage.
+     * Fails safe: if stored consent is corrupted, returns empty set (no consent)
+     * rather than defaulting to consent, to protect user privacy.
+     */
+    loadConsentFromStorage() {
+        try {
+            const stored = this.storage.get(CONSENT_KEY);
+            if (stored) {
+                const parsed = JSON.parse(stored);
+                if (Array.isArray(parsed)) {
+                    return new Set(parsed.filter((c) => ALL_CATEGORIES.includes(c)));
+                }
+                console.warn("[Thisbefine Privacy] Stored consent data is invalid, failing safe with no consent");
+                return new Set();
+            }
+        }
+        catch (error) {
+            console.warn("[Thisbefine Privacy] Failed to load consent from storage, failing safe with no consent:", error);
+            return new Set();
+        }
+        const defaultConsent = this.consentConfig.defaultConsent ?? true;
+        if (defaultConsent) {
+            return new Set(this.consentConfig.categories ?? ALL_CATEGORIES);
+        }
+        return new Set();
+    }
+    /**
+     * Save consent categories to storage.
+     * Returns true if saved successfully, false otherwise.
+     * Warns on failure since consent preferences may not persist across sessions.
+     */
+    saveConsentToStorage() {
+        try {
+            this.storage.set(CONSENT_KEY, JSON.stringify([...this.consentCategories]));
+            return true;
+        }
+        catch (error) {
+            console.warn("[Thisbefine Privacy] Failed to persist consent to storage. User consent preference may not persist across sessions:", error);
+            return false;
+        }
     }
     /**
      * Check if Do Not Track is enabled in the browser
@@ -70,6 +123,69 @@ export class Privacy {
         }
         return true;
     }
+    /**
+     * Check if tracking is allowed for a specific consent category
+     */
+    shouldTrackForCategory(category) {
+        if (!this.shouldTrack()) {
+            return false;
+        }
+        return this.consentCategories.has(category);
+    }
+    /**
+     * Check if a specific consent category is enabled
+     */
+    hasConsent(category) {
+        return this.consentCategories.has(category);
+    }
+    /**
+     * Get all currently consented categories
+     */
+    getConsentedCategories() {
+        return [...this.consentCategories];
+    }
+    /**
+     * Set consent for specific categories (replaces current consent)
+     */
+    setConsent(categories) {
+        this.consentCategories = new Set(categories.filter((c) => ALL_CATEGORIES.includes(c)));
+        this.saveConsentToStorage();
+        this.log("Consent updated:", [...this.consentCategories]);
+    }
+    /**
+     * Grant consent for a specific category
+     */
+    grantConsent(category) {
+        if (ALL_CATEGORIES.includes(category)) {
+            this.consentCategories.add(category);
+            this.saveConsentToStorage();
+            this.log("Consent granted:", category);
+        }
+    }
+    /**
+     * Revoke consent for a specific category
+     */
+    revokeConsent(category) {
+        this.consentCategories.delete(category);
+        this.saveConsentToStorage();
+        this.log("Consent revoked:", category);
+    }
+    /**
+     * Grant consent for all categories
+     */
+    grantAllConsent() {
+        this.consentCategories = new Set(ALL_CATEGORIES);
+        this.saveConsentToStorage();
+        this.log("All consent granted");
+    }
+    /**
+     * Revoke consent for all categories
+     */
+    revokeAllConsent() {
+        this.consentCategories.clear();
+        this.saveConsentToStorage();
+        this.log("All consent revoked");
+    }
     /**
      * Get a summary of privacy signals for debugging
      */
@@ -80,6 +196,7 @@ export class Privacy {
             optedOut: this.isOptedOut(),
             respectDNT: this.respectDNT,
             trackingAllowed: this.shouldTrack(),
+            consentCategories: this.getConsentedCategories(),
         };
     }
     /**

package/dist/core/privacy.js.map

@@ -1 +1 @@
-{"version":3,"file":"privacy.js","sourceRoot":"","sources":["../../src/core/privacy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,OAAO,OAAO;IAKnB,YAAY,OAAyB,EAAE,UAAmB,EAAE,KAAK,GAAG,KAAK;QACxE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,YAAY;QACX,IAAI,OAAO,SAAS,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;QAEnD,MAAM,GAAG,GACR,SAAS,CAAC,UAAU;YACnB,MAA6C,CAAC,UAAU;YACxD,SAAkD,CAAC,YAAY,CAAC;QAElE,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,KAAK,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,YAAY;QACX,IAAI,OAAO,SAAS,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;QAEnD,OAAO,CACL,SAA2D;aAC1D,oBAAoB,KAAK,IAAI,CAC/B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,UAAU;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,MAAM;QACL,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK;QACJ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,WAAW;QACV,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YACvB,IAAI,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAC7C,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;YAC1C,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;YAC1C,OAAO,KAAK,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACH,gBAAgB;QAOf,OAAO;YACN,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE;YAC/B,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE;YAC/B,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE;YAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,eAAe,EAAE,IAAI,CAAC,WAAW,EAAE;SACnC,CAAC;IACH,CAAC;IAED;;OAEG;IACK,GAAG,CAAC,GAAG,IAAe;QAC7B,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,OAAO,KAAK,WAAW,EAAE,CAAC;YAClD,OAAO,CAAC,GAAG,CAAC,sBAAsB,EAAE,GAAG,IAAI,CAAC,CAAC;QAC9C,CAAC;IACF,CAAC;CACD"}
+{"version":3,"file":"privacy.js","sourceRoot":"","sources":["../../src/core/privacy.ts"],"names":[],"mappings":"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"}

package/dist/core/queue.d.ts

@@ -1,12 +1,21 @@
-import type { AnalyticsEvent, ResolvedConfig } from "./types";
+import type { AnalyticsEvent, FlushResult, ResolvedConfig } from "./types";
 /**
- * Event queue with batching, automatic flushing, and retry logic
+ * Circuit breaker state
+ */
+type CircuitState = "closed" | "open" | "half-open";
+/**
+ * Event queue with batching, automatic flushing, retry logic, offline detection,
+ * persistent storage for crash recovery, and circuit breaker pattern.
  *
  * Features:
  * - Batches events up to flushAt threshold
  * - Flushes automatically after flushInterval
  * - Uses sendBeacon on page unload for reliability
  * - Exponential backoff retry on failure
+ * - Pauses when offline, resumes when online
+ * - Persists queue to localStorage for crash recovery
+ * - Calls onFlushError callback on failures
+ * - Circuit breaker to stop hammering failed servers
  */
 export declare class Queue {
     private items;
@@ -15,11 +24,34 @@ export declare class Queue {
     private visibilityFlushPending;
     private config;
     private logger;
+    private destroyed;
+    private isOnline;
+    private circuitState;
+    private consecutiveFailures;
+    private circuitOpenedAt;
+    private clockOffset;
+    private boundVisibilityHandler;
+    private boundBeforeUnloadHandler;
+    private boundPageHideHandler;
+    private boundOnlineHandler;
+    private boundOfflineHandler;
     constructor(config: ResolvedConfig);
     /**
      * Set up handlers for page unload to ensure events are sent
      */
     private setupUnloadHandlers;
+    /**
+     * Set up handlers for online/offline detection
+     */
+    private setupOnlineHandlers;
+    /**
+     * Restore queue from persistent storage (crash recovery)
+     */
+    private restoreFromStorage;
+    /**
+     * Persist queue to storage for crash recovery
+     */
+    private persistToStorage;
     /**
      * Add an event to the queue
      */
@@ -29,10 +61,41 @@ export declare class Queue {
      *
      * @param useBeacon - Use sendBeacon for page unload scenarios
      * @param depth - Internal recursion depth counter (prevents stack overflow)
+     * @returns FlushResult with success status and any errors
+     */
+    flush(useBeacon?: boolean, depth?: number): Promise<FlushResult>;
+    /**
+     * Notify error callback of flush failure
+     */
+    private notifyError;
+    /**
+     * Check if we can attempt a request based on circuit breaker state
+     */
+    private canAttemptRequest;
+    /**
+     * Record a successful request, closing the circuit
+     */
+    private recordSuccess;
+    /**
+     * Record a failed request, potentially opening the circuit
+     */
+    private recordFailure;
+    /**
+     * Get the current circuit breaker state (for testing/debugging)
+     */
+    get circuitBreakerState(): CircuitState;
+    /**
+     * Update clock offset from server response
+     * Uses the Date header to calculate the difference between client and server time
      */
-    flush(useBeacon?: boolean, depth?: number): Promise<void>;
+    private updateClockOffset;
+    /**
+     * Get the current clock offset (for testing/debugging)
+     */
+    getClockOffset(): number;
     /**
      * Send events using sendBeacon (for page unload)
+     * @returns true if sendBeacon succeeded, false otherwise
      */
     private sendWithBeacon;
     /**
@@ -55,5 +118,15 @@ export declare class Queue {
      * Get the number of events in the queue
      */
     get length(): number;
+    /**
+     * Check if the queue is currently online
+     */
+    get online(): boolean;
+    /**
+     * Destroy the queue, removing all event listeners and clearing timers.
+     * Attempts to flush remaining events before cleanup.
+     */
+    destroy(): Promise<void>;
 }
+export {};
 //# sourceMappingURL=queue.d.ts.map

package/dist/core/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/core/queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9D;;;;;;;;GAQG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,cAAc;IAOlC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAuB3B;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAmBjC;;;;;OAKG;IACG,KAAK,CAAC,SAAS,UAAQ,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0DxD;;OAEG;IACH,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;YACW,aAAa;IA+C3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4D1B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;CACD"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/core/queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG3E;;GAEG;AACH,KAAK,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAQ;IAExB,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,eAAe,CAAuB;IAE9C,OAAO,CAAC,WAAW,CAAK;IAExB,OAAO,CAAC,sBAAsB,CAA6B;IAC3D,OAAO,CAAC,wBAAwB,CAA6B;IAC7D,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,mBAAmB,CAA6B;gBAE5C,MAAM,EAAE,cAAc;IAclC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2B3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IA0BjC;;;;;;OAMG;IACG,KAAK,CAAC,SAAS,UAAQ,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,WAAW,CAAC;IAwH/D;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,IAAI,mBAAmB,IAAI,YAAY,CAEtC;IAED;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;OAEG;YACW,aAAa;IAsE3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAwE1B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAqD9B"}