tersejson 0.1.0

package/dist/analytics.d.ts

@@ -0,0 +1,186 @@
+/**
+ * TerseJSON Analytics
+ *
+ * Opt-in analytics to track compression savings.
+ * Data is anonymous and helps improve the library.
+ */
+/**
+ * Compression event data
+ */
+interface CompressionEvent {
+    /** Timestamp of the compression */
+    timestamp: number;
+    /** Original payload size in bytes */
+    originalSize: number;
+    /** Compressed payload size in bytes */
+    compressedSize: number;
+    /** Number of objects in the array */
+    objectCount: number;
+    /** Number of keys compressed */
+    keysCompressed: number;
+    /** Route/endpoint (optional, anonymized) */
+    endpoint?: string;
+    /** Key pattern used */
+    keyPattern: string;
+}
+/**
+ * Aggregated stats for reporting
+ */
+interface AnalyticsStats {
+    /** Total compression events */
+    totalEvents: number;
+    /** Total bytes before compression */
+    totalOriginalBytes: number;
+    /** Total bytes after compression */
+    totalCompressedBytes: number;
+    /** Total bytes saved */
+    totalBytesSaved: number;
+    /** Average compression ratio (0-1) */
+    averageRatio: number;
+    /** Total objects processed */
+    totalObjects: number;
+    /** Session start time */
+    sessionStart: number;
+    /** Last event time */
+    lastEvent: number;
+}
+/**
+ * Analytics configuration
+ */
+interface AnalyticsConfig {
+    /**
+     * Enable analytics collection
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Send anonymous stats to tersejson.com
+     * Helps improve the library
+     * @default false
+     */
+    reportToCloud: boolean;
+    /**
+     * API key for tersejson.com (optional)
+     * Get one at tersejson.com/dashboard
+     */
+    apiKey?: string;
+    /**
+     * Project/site identifier (optional)
+     */
+    projectId?: string;
+    /**
+     * Callback for each compression event
+     * Use for custom logging/monitoring
+     */
+    onEvent?: (event: CompressionEvent) => void;
+    /**
+     * Callback for periodic stats summary
+     */
+    onStats?: (stats: AnalyticsStats) => void;
+    /**
+     * How often to report stats (ms)
+     * @default 60000 (1 minute)
+     */
+    reportInterval?: number;
+    /**
+     * Include endpoint paths in analytics
+     * Paths are hashed for privacy
+     * @default false
+     */
+    trackEndpoints?: boolean;
+    /**
+     * Cloud reporting endpoint
+     * @default 'https://api.tersejson.com/v1/analytics'
+     */
+    endpoint?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Analytics collector class
+ */
+declare class TerseAnalytics {
+    private config;
+    private events;
+    private stats;
+    private reportTimer?;
+    private isNode;
+    constructor(config?: Partial<AnalyticsConfig>);
+    /**
+     * Create empty stats object
+     */
+    private createEmptyStats;
+    /**
+     * Record a compression event
+     */
+    record(event: Omit<CompressionEvent, 'timestamp'>): void;
+    /**
+     * Get current stats
+     */
+    getStats(): AnalyticsStats;
+    /**
+     * Get formatted stats summary
+     */
+    getSummary(): string;
+    /**
+     * Reset stats
+     */
+    reset(): void;
+    /**
+     * Start periodic reporting to cloud
+     */
+    private startReporting;
+    /**
+     * Stop reporting
+     */
+    stop(): void;
+    /**
+     * Report stats to tersejson.com
+     */
+    private reportToCloud;
+    /**
+     * Hash endpoint for privacy
+     */
+    private hashEndpoint;
+}
+/**
+ * Initialize global analytics
+ */
+declare function initAnalytics(config: Partial<AnalyticsConfig>): TerseAnalytics;
+/**
+ * Get global analytics instance
+ */
+declare function getAnalytics(): TerseAnalytics | null;
+/**
+ * Record an event to global analytics (if initialized)
+ */
+declare function recordEvent(event: Omit<CompressionEvent, 'timestamp'>): void;
+/**
+ * Quick setup for common use cases
+ */
+declare const analytics: {
+    /**
+     * Enable local-only analytics (no cloud reporting)
+     */
+    local(options?: {
+        debug?: boolean;
+        onEvent?: AnalyticsConfig["onEvent"];
+    }): TerseAnalytics;
+    /**
+     * Enable cloud analytics with API key
+     */
+    cloud(apiKey: string, options?: Partial<AnalyticsConfig>): TerseAnalytics;
+    /**
+     * Get current stats
+     */
+    getStats(): AnalyticsStats | null;
+    /**
+     * Get formatted summary
+     */
+    getSummary(): string;
+};
+
+export { type AnalyticsConfig, type AnalyticsStats, type CompressionEvent, TerseAnalytics, analytics, analytics as default, getAnalytics, initAnalytics, recordEvent };

package/dist/analytics.js

@@ -0,0 +1,226 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/analytics.ts
+var DEFAULT_CONFIG = {
+  enabled: false,
+  reportToCloud: false,
+  reportInterval: 6e4,
+  trackEndpoints: false,
+  endpoint: "https://api.tersejson.com/v1/analytics",
+  debug: false
+};
+var TerseAnalytics = class {
+  constructor(config = {}) {
+    this.events = [];
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.isNode = typeof window === "undefined";
+    this.stats = this.createEmptyStats();
+    if (this.config.enabled && this.config.reportToCloud) {
+      this.startReporting();
+    }
+  }
+  /**
+   * Create empty stats object
+   */
+  createEmptyStats() {
+    return {
+      totalEvents: 0,
+      totalOriginalBytes: 0,
+      totalCompressedBytes: 0,
+      totalBytesSaved: 0,
+      averageRatio: 0,
+      totalObjects: 0,
+      sessionStart: Date.now(),
+      lastEvent: Date.now()
+    };
+  }
+  /**
+   * Record a compression event
+   */
+  record(event) {
+    if (!this.config.enabled) return;
+    const fullEvent = {
+      ...event,
+      timestamp: Date.now(),
+      // Hash endpoint for privacy if tracking is enabled
+      endpoint: this.config.trackEndpoints && event.endpoint ? this.hashEndpoint(event.endpoint) : void 0
+    };
+    this.stats.totalEvents++;
+    this.stats.totalOriginalBytes += event.originalSize;
+    this.stats.totalCompressedBytes += event.compressedSize;
+    this.stats.totalBytesSaved += event.originalSize - event.compressedSize;
+    this.stats.totalObjects += event.objectCount;
+    this.stats.lastEvent = fullEvent.timestamp;
+    this.stats.averageRatio = this.stats.totalCompressedBytes / this.stats.totalOriginalBytes;
+    this.events.push(fullEvent);
+    if (this.config.onEvent) {
+      this.config.onEvent(fullEvent);
+    }
+    if (this.config.debug) {
+      const savings = ((1 - event.compressedSize / event.originalSize) * 100).toFixed(1);
+      console.log(`[tersejson:analytics] ${event.originalSize} \u2192 ${event.compressedSize} bytes (${savings}% saved)`);
+    }
+  }
+  /**
+   * Get current stats
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  /**
+   * Get formatted stats summary
+   */
+  getSummary() {
+    const stats = this.stats;
+    const savedKB = (stats.totalBytesSaved / 1024).toFixed(2);
+    const savedPercent = stats.totalOriginalBytes > 0 ? ((1 - stats.averageRatio) * 100).toFixed(1) : "0";
+    return `TerseJSON Stats: ${stats.totalEvents} compressions, ${savedKB}KB saved (${savedPercent}% avg)`;
+  }
+  /**
+   * Reset stats
+   */
+  reset() {
+    this.events = [];
+    this.stats = this.createEmptyStats();
+  }
+  /**
+   * Start periodic reporting to cloud
+   */
+  startReporting() {
+    if (this.reportTimer) return;
+    this.reportTimer = setInterval(() => {
+      this.reportToCloud();
+    }, this.config.reportInterval);
+    if (this.isNode && typeof process !== "undefined") {
+      process.on("beforeExit", () => this.reportToCloud());
+    }
+  }
+  /**
+   * Stop reporting
+   */
+  stop() {
+    if (this.reportTimer) {
+      clearInterval(this.reportTimer);
+      this.reportTimer = void 0;
+    }
+  }
+  /**
+   * Report stats to tersejson.com
+   */
+  async reportToCloud() {
+    if (!this.config.reportToCloud || this.events.length === 0) return;
+    const payload = {
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      stats: this.stats,
+      events: this.events.slice(-100),
+      // Last 100 events only
+      meta: {
+        version: "0.1.0",
+        runtime: this.isNode ? "node" : "browser"
+      }
+    };
+    try {
+      const fetchFn = this.isNode ? (await import('https')).request : globalThis.fetch;
+      if (this.isNode) {
+        const url = new URL(this.config.endpoint);
+        const req = fetchFn({
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: url.pathname,
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          }
+        });
+        req.write(JSON.stringify(payload));
+        req.end();
+      } else {
+        fetchFn(this.config.endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+          keepalive: true
+          // Allow sending on page unload
+        }).catch(() => {
+        });
+      }
+      this.events = [];
+      if (this.config.onStats) {
+        this.config.onStats(this.stats);
+      }
+      if (this.config.debug) {
+        console.log("[tersejson:analytics] Reported stats to cloud");
+      }
+    } catch {
+      if (this.config.debug) {
+        console.log("[tersejson:analytics] Failed to report stats");
+      }
+    }
+  }
+  /**
+   * Hash endpoint for privacy
+   */
+  hashEndpoint(endpoint) {
+    return endpoint.replace(/\/\d+/g, "/:id").replace(/\/[a-f0-9-]{36}/gi, "/:uuid").replace(/\?.*$/, "");
+  }
+};
+var globalAnalytics = null;
+function initAnalytics(config) {
+  globalAnalytics = new TerseAnalytics(config);
+  return globalAnalytics;
+}
+function getAnalytics() {
+  return globalAnalytics;
+}
+function recordEvent(event) {
+  globalAnalytics?.record(event);
+}
+var analytics = {
+  /**
+   * Enable local-only analytics (no cloud reporting)
+   */
+  local(options = {}) {
+    return initAnalytics({
+      enabled: true,
+      reportToCloud: false,
+      debug: options.debug,
+      onEvent: options.onEvent
+    });
+  },
+  /**
+   * Enable cloud analytics with API key
+   */
+  cloud(apiKey, options = {}) {
+    return initAnalytics({
+      ...options,
+      enabled: true,
+      reportToCloud: true,
+      apiKey
+    });
+  },
+  /**
+   * Get current stats
+   */
+  getStats() {
+    return globalAnalytics?.getStats() ?? null;
+  },
+  /**
+   * Get formatted summary
+   */
+  getSummary() {
+    return globalAnalytics?.getSummary() ?? "Analytics not initialized";
+  }
+};
+var analytics_default = analytics;
+
+exports.TerseAnalytics = TerseAnalytics;
+exports.analytics = analytics;
+exports.default = analytics_default;
+exports.getAnalytics = getAnalytics;
+exports.initAnalytics = initAnalytics;
+exports.recordEvent = recordEvent;
+//# sourceMappingURL=analytics.js.map
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/analytics.ts"],"names":[],"mappings":"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","file":"analytics.js","sourcesContent":["/**\n * TerseJSON Analytics\n *\n * Opt-in analytics to track compression savings.\n * Data is anonymous and helps improve the library.\n */\n\n/**\n * Compression event data\n */\nexport interface CompressionEvent {\n  /** Timestamp of the compression */\n  timestamp: number;\n  /** Original payload size in bytes */\n  originalSize: number;\n  /** Compressed payload size in bytes */\n  compressedSize: number;\n  /** Number of objects in the array */\n  objectCount: number;\n  /** Number of keys compressed */\n  keysCompressed: number;\n  /** Route/endpoint (optional, anonymized) */\n  endpoint?: string;\n  /** Key pattern used */\n  keyPattern: string;\n}\n\n/**\n * Aggregated stats for reporting\n */\nexport interface AnalyticsStats {\n  /** Total compression events */\n  totalEvents: number;\n  /** Total bytes before compression */\n  totalOriginalBytes: number;\n  /** Total bytes after compression */\n  totalCompressedBytes: number;\n  /** Total bytes saved */\n  totalBytesSaved: number;\n  /** Average compression ratio (0-1) */\n  averageRatio: number;\n  /** Total objects processed */\n  totalObjects: number;\n  /** Session start time */\n  sessionStart: number;\n  /** Last event time */\n  lastEvent: number;\n}\n\n/**\n * Analytics configuration\n */\nexport interface AnalyticsConfig {\n  /**\n   * Enable analytics collection\n   * @default false\n   */\n  enabled: boolean;\n\n  /**\n   * Send anonymous stats to tersejson.com\n   * Helps improve the library\n   * @default false\n   */\n  reportToCloud: boolean;\n\n  /**\n   * API key for tersejson.com (optional)\n   * Get one at tersejson.com/dashboard\n   */\n  apiKey?: string;\n\n  /**\n   * Project/site identifier (optional)\n   */\n  projectId?: string;\n\n  /**\n   * Callback for each compression event\n   * Use for custom logging/monitoring\n   */\n  onEvent?: (event: CompressionEvent) => void;\n\n  /**\n   * Callback for periodic stats summary\n   */\n  onStats?: (stats: AnalyticsStats) => void;\n\n  /**\n   * How often to report stats (ms)\n   * @default 60000 (1 minute)\n   */\n  reportInterval?: number;\n\n  /**\n   * Include endpoint paths in analytics\n   * Paths are hashed for privacy\n   * @default false\n   */\n  trackEndpoints?: boolean;\n\n  /**\n   * Cloud reporting endpoint\n   * @default 'https://api.tersejson.com/v1/analytics'\n   */\n  endpoint?: string;\n\n  /**\n   * Enable debug logging\n   * @default false\n   */\n  debug?: boolean;\n}\n\n/**\n * Default configuration\n */\nconst DEFAULT_CONFIG: Required<Omit<AnalyticsConfig, 'apiKey' | 'projectId' | 'onEvent' | 'onStats'>> = {\n  enabled: false,\n  reportToCloud: false,\n  reportInterval: 60000,\n  trackEndpoints: false,\n  endpoint: 'https://api.tersejson.com/v1/analytics',\n  debug: false,\n};\n\n/**\n * Analytics collector class\n */\nexport class TerseAnalytics {\n  private config: Required<Omit<AnalyticsConfig, 'apiKey' | 'projectId' | 'onEvent' | 'onStats'>> &\n    Pick<AnalyticsConfig, 'apiKey' | 'projectId' | 'onEvent' | 'onStats'>;\n  private events: CompressionEvent[] = [];\n  private stats: AnalyticsStats;\n  private reportTimer?: ReturnType<typeof setInterval>;\n  private isNode: boolean;\n\n  constructor(config: Partial<AnalyticsConfig> = {}) {\n    this.config = { ...DEFAULT_CONFIG, ...config };\n    this.isNode = typeof window === 'undefined';\n    this.stats = this.createEmptyStats();\n\n    if (this.config.enabled && this.config.reportToCloud) {\n      this.startReporting();\n    }\n  }\n\n  /**\n   * Create empty stats object\n   */\n  private createEmptyStats(): AnalyticsStats {\n    return {\n      totalEvents: 0,\n      totalOriginalBytes: 0,\n      totalCompressedBytes: 0,\n      totalBytesSaved: 0,\n      averageRatio: 0,\n      totalObjects: 0,\n      sessionStart: Date.now(),\n      lastEvent: Date.now(),\n    };\n  }\n\n  /**\n   * Record a compression event\n   */\n  record(event: Omit<CompressionEvent, 'timestamp'>): void {\n    if (!this.config.enabled) return;\n\n    const fullEvent: CompressionEvent = {\n      ...event,\n      timestamp: Date.now(),\n      // Hash endpoint for privacy if tracking is enabled\n      endpoint: this.config.trackEndpoints && event.endpoint\n        ? this.hashEndpoint(event.endpoint)\n        : undefined,\n    };\n\n    // Update stats\n    this.stats.totalEvents++;\n    this.stats.totalOriginalBytes += event.originalSize;\n    this.stats.totalCompressedBytes += event.compressedSize;\n    this.stats.totalBytesSaved += (event.originalSize - event.compressedSize);\n    this.stats.totalObjects += event.objectCount;\n    this.stats.lastEvent = fullEvent.timestamp;\n    this.stats.averageRatio = this.stats.totalCompressedBytes / this.stats.totalOriginalBytes;\n\n    // Store event for batch reporting\n    this.events.push(fullEvent);\n\n    // Call event callback\n    if (this.config.onEvent) {\n      this.config.onEvent(fullEvent);\n    }\n\n    // Debug logging\n    if (this.config.debug) {\n      const savings = ((1 - event.compressedSize / event.originalSize) * 100).toFixed(1);\n      console.log(`[tersejson:analytics] ${event.originalSize} → ${event.compressedSize} bytes (${savings}% saved)`);\n    }\n  }\n\n  /**\n   * Get current stats\n   */\n  getStats(): AnalyticsStats {\n    return { ...this.stats };\n  }\n\n  /**\n   * Get formatted stats summary\n   */\n  getSummary(): string {\n    const stats = this.stats;\n    const savedKB = (stats.totalBytesSaved / 1024).toFixed(2);\n    const savedPercent = stats.totalOriginalBytes > 0\n      ? ((1 - stats.averageRatio) * 100).toFixed(1)\n      : '0';\n\n    return `TerseJSON Stats: ${stats.totalEvents} compressions, ${savedKB}KB saved (${savedPercent}% avg)`;\n  }\n\n  /**\n   * Reset stats\n   */\n  reset(): void {\n    this.events = [];\n    this.stats = this.createEmptyStats();\n  }\n\n  /**\n   * Start periodic reporting to cloud\n   */\n  private startReporting(): void {\n    if (this.reportTimer) return;\n\n    this.reportTimer = setInterval(() => {\n      this.reportToCloud();\n    }, this.config.reportInterval);\n\n    // Report on exit (Node.js only)\n    if (this.isNode && typeof process !== 'undefined') {\n      process.on('beforeExit', () => this.reportToCloud());\n    }\n  }\n\n  /**\n   * Stop reporting\n   */\n  stop(): void {\n    if (this.reportTimer) {\n      clearInterval(this.reportTimer);\n      this.reportTimer = undefined;\n    }\n  }\n\n  /**\n   * Report stats to tersejson.com\n   */\n  private async reportToCloud(): Promise<void> {\n    if (!this.config.reportToCloud || this.events.length === 0) return;\n\n    const payload = {\n      apiKey: this.config.apiKey,\n      projectId: this.config.projectId,\n      stats: this.stats,\n      events: this.events.slice(-100), // Last 100 events only\n      meta: {\n        version: '0.1.0',\n        runtime: this.isNode ? 'node' : 'browser',\n      },\n    };\n\n    try {\n      // Use appropriate fetch based on environment\n      const fetchFn = this.isNode\n        ? (await import('node:https')).request\n        : globalThis.fetch;\n\n      if (this.isNode) {\n        // Node.js - fire and forget\n        const url = new URL(this.config.endpoint);\n        const req = (fetchFn as typeof import('node:https').request)({\n          hostname: url.hostname,\n          port: url.port || 443,\n          path: url.pathname,\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n          },\n        });\n        req.write(JSON.stringify(payload));\n        req.end();\n      } else {\n        // Browser\n        (fetchFn as typeof fetch)(this.config.endpoint, {\n          method: 'POST',\n          headers: { 'Content-Type': 'application/json' },\n          body: JSON.stringify(payload),\n          keepalive: true, // Allow sending on page unload\n        }).catch(() => {}); // Ignore errors\n      }\n\n      // Clear reported events\n      this.events = [];\n\n      // Call stats callback\n      if (this.config.onStats) {\n        this.config.onStats(this.stats);\n      }\n\n      if (this.config.debug) {\n        console.log('[tersejson:analytics] Reported stats to cloud');\n      }\n    } catch {\n      // Silently fail - analytics should never break the app\n      if (this.config.debug) {\n        console.log('[tersejson:analytics] Failed to report stats');\n      }\n    }\n  }\n\n  /**\n   * Hash endpoint for privacy\n   */\n  private hashEndpoint(endpoint: string): string {\n    // Simple hash - just keeps route structure without specifics\n    return endpoint\n      .replace(/\\/\\d+/g, '/:id')\n      .replace(/\\/[a-f0-9-]{36}/gi, '/:uuid')\n      .replace(/\\?.*$/, '');\n  }\n}\n\n/**\n * Global analytics instance (singleton)\n */\nlet globalAnalytics: TerseAnalytics | null = null;\n\n/**\n * Initialize global analytics\n */\nexport function initAnalytics(config: Partial<AnalyticsConfig>): TerseAnalytics {\n  globalAnalytics = new TerseAnalytics(config);\n  return globalAnalytics;\n}\n\n/**\n * Get global analytics instance\n */\nexport function getAnalytics(): TerseAnalytics | null {\n  return globalAnalytics;\n}\n\n/**\n * Record an event to global analytics (if initialized)\n */\nexport function recordEvent(event: Omit<CompressionEvent, 'timestamp'>): void {\n  globalAnalytics?.record(event);\n}\n\n/**\n * Quick setup for common use cases\n */\nexport const analytics = {\n  /**\n   * Enable local-only analytics (no cloud reporting)\n   */\n  local(options: { debug?: boolean; onEvent?: AnalyticsConfig['onEvent'] } = {}) {\n    return initAnalytics({\n      enabled: true,\n      reportToCloud: false,\n      debug: options.debug,\n      onEvent: options.onEvent,\n    });\n  },\n\n  /**\n   * Enable cloud analytics with API key\n   */\n  cloud(apiKey: string, options: Partial<AnalyticsConfig> = {}) {\n    return initAnalytics({\n      ...options,\n      enabled: true,\n      reportToCloud: true,\n      apiKey,\n    });\n  },\n\n  /**\n   * Get current stats\n   */\n  getStats() {\n    return globalAnalytics?.getStats() ?? null;\n  },\n\n  /**\n   * Get formatted summary\n   */\n  getSummary() {\n    return globalAnalytics?.getSummary() ?? 'Analytics not initialized';\n  },\n};\n\nexport default analytics;\n"]}

package/dist/analytics.mjs

@@ -0,0 +1,217 @@
+// src/analytics.ts
+var DEFAULT_CONFIG = {
+  enabled: false,
+  reportToCloud: false,
+  reportInterval: 6e4,
+  trackEndpoints: false,
+  endpoint: "https://api.tersejson.com/v1/analytics",
+  debug: false
+};
+var TerseAnalytics = class {
+  constructor(config = {}) {
+    this.events = [];
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.isNode = typeof window === "undefined";
+    this.stats = this.createEmptyStats();
+    if (this.config.enabled && this.config.reportToCloud) {
+      this.startReporting();
+    }
+  }
+  /**
+   * Create empty stats object
+   */
+  createEmptyStats() {
+    return {
+      totalEvents: 0,
+      totalOriginalBytes: 0,
+      totalCompressedBytes: 0,
+      totalBytesSaved: 0,
+      averageRatio: 0,
+      totalObjects: 0,
+      sessionStart: Date.now(),
+      lastEvent: Date.now()
+    };
+  }
+  /**
+   * Record a compression event
+   */
+  record(event) {
+    if (!this.config.enabled) return;
+    const fullEvent = {
+      ...event,
+      timestamp: Date.now(),
+      // Hash endpoint for privacy if tracking is enabled
+      endpoint: this.config.trackEndpoints && event.endpoint ? this.hashEndpoint(event.endpoint) : void 0
+    };
+    this.stats.totalEvents++;
+    this.stats.totalOriginalBytes += event.originalSize;
+    this.stats.totalCompressedBytes += event.compressedSize;
+    this.stats.totalBytesSaved += event.originalSize - event.compressedSize;
+    this.stats.totalObjects += event.objectCount;
+    this.stats.lastEvent = fullEvent.timestamp;
+    this.stats.averageRatio = this.stats.totalCompressedBytes / this.stats.totalOriginalBytes;
+    this.events.push(fullEvent);
+    if (this.config.onEvent) {
+      this.config.onEvent(fullEvent);
+    }
+    if (this.config.debug) {
+      const savings = ((1 - event.compressedSize / event.originalSize) * 100).toFixed(1);
+      console.log(`[tersejson:analytics] ${event.originalSize} \u2192 ${event.compressedSize} bytes (${savings}% saved)`);
+    }
+  }
+  /**
+   * Get current stats
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  /**
+   * Get formatted stats summary
+   */
+  getSummary() {
+    const stats = this.stats;
+    const savedKB = (stats.totalBytesSaved / 1024).toFixed(2);
+    const savedPercent = stats.totalOriginalBytes > 0 ? ((1 - stats.averageRatio) * 100).toFixed(1) : "0";
+    return `TerseJSON Stats: ${stats.totalEvents} compressions, ${savedKB}KB saved (${savedPercent}% avg)`;
+  }
+  /**
+   * Reset stats
+   */
+  reset() {
+    this.events = [];
+    this.stats = this.createEmptyStats();
+  }
+  /**
+   * Start periodic reporting to cloud
+   */
+  startReporting() {
+    if (this.reportTimer) return;
+    this.reportTimer = setInterval(() => {
+      this.reportToCloud();
+    }, this.config.reportInterval);
+    if (this.isNode && typeof process !== "undefined") {
+      process.on("beforeExit", () => this.reportToCloud());
+    }
+  }
+  /**
+   * Stop reporting
+   */
+  stop() {
+    if (this.reportTimer) {
+      clearInterval(this.reportTimer);
+      this.reportTimer = void 0;
+    }
+  }
+  /**
+   * Report stats to tersejson.com
+   */
+  async reportToCloud() {
+    if (!this.config.reportToCloud || this.events.length === 0) return;
+    const payload = {
+      apiKey: this.config.apiKey,
+      projectId: this.config.projectId,
+      stats: this.stats,
+      events: this.events.slice(-100),
+      // Last 100 events only
+      meta: {
+        version: "0.1.0",
+        runtime: this.isNode ? "node" : "browser"
+      }
+    };
+    try {
+      const fetchFn = this.isNode ? (await import('https')).request : globalThis.fetch;
+      if (this.isNode) {
+        const url = new URL(this.config.endpoint);
+        const req = fetchFn({
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: url.pathname,
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          }
+        });
+        req.write(JSON.stringify(payload));
+        req.end();
+      } else {
+        fetchFn(this.config.endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+          keepalive: true
+          // Allow sending on page unload
+        }).catch(() => {
+        });
+      }
+      this.events = [];
+      if (this.config.onStats) {
+        this.config.onStats(this.stats);
+      }
+      if (this.config.debug) {
+        console.log("[tersejson:analytics] Reported stats to cloud");
+      }
+    } catch {
+      if (this.config.debug) {
+        console.log("[tersejson:analytics] Failed to report stats");
+      }
+    }
+  }
+  /**
+   * Hash endpoint for privacy
+   */
+  hashEndpoint(endpoint) {
+    return endpoint.replace(/\/\d+/g, "/:id").replace(/\/[a-f0-9-]{36}/gi, "/:uuid").replace(/\?.*$/, "");
+  }
+};
+var globalAnalytics = null;
+function initAnalytics(config) {
+  globalAnalytics = new TerseAnalytics(config);
+  return globalAnalytics;
+}
+function getAnalytics() {
+  return globalAnalytics;
+}
+function recordEvent(event) {
+  globalAnalytics?.record(event);
+}
+var analytics = {
+  /**
+   * Enable local-only analytics (no cloud reporting)
+   */
+  local(options = {}) {
+    return initAnalytics({
+      enabled: true,
+      reportToCloud: false,
+      debug: options.debug,
+      onEvent: options.onEvent
+    });
+  },
+  /**
+   * Enable cloud analytics with API key
+   */
+  cloud(apiKey, options = {}) {
+    return initAnalytics({
+      ...options,
+      enabled: true,
+      reportToCloud: true,
+      apiKey
+    });
+  },
+  /**
+   * Get current stats
+   */
+  getStats() {
+    return globalAnalytics?.getStats() ?? null;
+  },
+  /**
+   * Get formatted summary
+   */
+  getSummary() {
+    return globalAnalytics?.getSummary() ?? "Analytics not initialized";
+  }
+};
+var analytics_default = analytics;
+
+export { TerseAnalytics, analytics, analytics_default as default, getAnalytics, initAnalytics, recordEvent };
+//# sourceMappingURL=analytics.mjs.map
+//# sourceMappingURL=analytics.mjs.map