feat: telemetry (#1932)

* feat: telemetry

- Added telemetry support to track document opens for usage-based billing.
- Introduced `initTelemetry` method in the Editor class to initialize telemetry based on configuration.
- Created tests for telemetry functionality, ensuring correct behavior when enabled/disabled and with various configurations.
- Updated Editor and SuperDoc configurations to include telemetry options and license key handling.
- Enhanced SuperConverter to manage document creation timestamps for unique identification.

* refactor: streamline document handling and telemetry logging

- Simplified telemetry logging in the Editor class by removing unnecessary comments and enhancing debug output for document information.
- Removed redundant isNewFile tracking in SuperDoc, allowing automatic handling based on context.

* feat: enhance telemetry license key handling

- Introduced default community license key in the Editor class for telemetry initialization.
- Updated `initTelemetry` function to use the default license key when none is provided.
- Added tests to verify behavior with default and custom license keys.
- Improved documentation for the community license key usage.

* test: update telemetry test endpoint URL

* feat: enhance document tracking and identifier generation

- Introduced a guard flag to prevent double-tracking of document opens in the Editor class.
- Updated document identifier generation to be asynchronous, ensuring metadata is available before tracking.
- Enhanced SuperConverter to manage document timestamps and unique identifiers more effectively.
- Added new utility methods for generating Word-compatible timestamps and content hashes.
- Improved test coverage for document identifier resolution and timestamp handling in various scenarios.

* refactor: simplify telemetry configuration and improve document tracking

- Renamed `isNewFile` to `isBlankDoc` in SuperConverter for clarity regarding document creation context.
- Updated related comments and documentation to reflect the new naming and functionality.
- Enhanced test cases to align with the refactored telemetry and document handling logic.

* refactor: streamline document tracking and metadata generation

- Ensured document metadata is generated regardless of telemetry settings

* refactor: enhance telemetry integration and license key handling

- Simplified license key management in telemetry initialization.
- Updated tests to reflect changes in license key usage and ensure correct behavior.
- Introduced COMMUNITY_LICENSE_KEY constant for consistent license key usage across modules.

* refactor: update telemetry configuration and constructor parameters

* refactor: enhance telemetry logging and update endpoint

* fix: disable telemetry by default

Author: andrii-harbour

packages/super-editor/src/core/Editor.telemetry.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Telemetry, COMMUNITY_LICENSE_KEY } from '@superdoc/common';
+
+// Mock the Telemetry class to verify it's called correctly
+vi.mock('@superdoc/common', () => ({
+  Telemetry: vi.fn().mockImplementation(() => ({
+    trackDocumentOpen: vi.fn(),
+  })),
+  COMMUNITY_LICENSE_KEY: 'community-and-eval-agplv3',
+}));
+
+// Test the telemetry initialization logic in isolation
+// This mirrors the #initTelemetry method in Editor.ts
+function initTelemetry(options: {
+  telemetry?: { enabled: boolean; endpoint?: string; metadata?: Record<string, unknown> } | null;
+  licenseKey?: string;
+}): Telemetry | null {
+  const { telemetry: telemetryConfig, licenseKey } = options;
+
+  // Skip if telemetry is not enabled
+  if (!telemetryConfig?.enabled) {
+    return null;
+  }
+
+  try {
+    return new Telemetry({
+      enabled: true,
+      endpoint: telemetryConfig.endpoint,
+      licenseKey: licenseKey === undefined ? COMMUNITY_LICENSE_KEY : licenseKey,
+      metadata: telemetryConfig.metadata,
+    });
+  } catch {
+    // Fail silently - telemetry should never break the app
+    return null;
+  }
+}
+
+describe('Editor Telemetry Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('telemetry disabled', () => {
+    it('does not create Telemetry instance when disabled', () => {
+      const result = initTelemetry({
+        telemetry: { enabled: false },
+        licenseKey: 'test-key',
+      });
+
+      expect(result).toBeNull();
+      expect(Telemetry).not.toHaveBeenCalled();
+    });
+
+    it('does not create Telemetry instance when telemetry config is null', () => {
+      const result = initTelemetry({
+        telemetry: null,
+        licenseKey: 'test-key',
+      });
+
+      expect(result).toBeNull();
+      expect(Telemetry).not.toHaveBeenCalled();
+    });
+
+    it('does not create Telemetry instance when telemetry config is undefined', () => {
+      const result = initTelemetry({
+        licenseKey: 'test-key',
+      });
+
+      expect(result).toBeNull();
+      expect(Telemetry).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('telemetry enabled', () => {
+    it('creates Telemetry instance when enabled', () => {
+      const result = initTelemetry({
+        telemetry: { enabled: true },
+        licenseKey: 'test-key',
+      });
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledTimes(1);
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: undefined,
+        licenseKey: 'test-key',
+        metadata: undefined,
+      });
+    });
+  });
+
+  describe('license key handling', () => {
+    it('uses COMMUNITY_LICENSE_KEY when licenseKey not provided', () => {
+      const result = initTelemetry({
+        telemetry: { enabled: true },
+      });
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledTimes(1);
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: undefined,
+        licenseKey: 'community-and-eval-agplv3',
+        metadata: undefined,
+      });
+    });
+
+    it('passes custom license key when provided', () => {
+      const customKey = 'my-custom-license-key';
+      const result = initTelemetry({
+        telemetry: { enabled: true },
+        licenseKey: customKey,
+      });
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: undefined,
+        licenseKey: customKey,
+        metadata: undefined,
+      });
+    });
+  });
+
+  describe('telemetry with custom endpoint', () => {
+    it('passes custom endpoint to Telemetry', () => {
+      const customEndpoint = 'https://custom.telemetry.com/v1/events';
+      const result = initTelemetry({
+        telemetry: { enabled: true, endpoint: customEndpoint },
+        licenseKey: 'test-key',
+      });
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: customEndpoint,
+        licenseKey: 'test-key',
+        metadata: undefined,
+      });
+    });
+  });
+
+  describe('telemetry with metadata', () => {
+    it('passes metadata to Telemetry', () => {
+      const metadata = {
+        customerId: 'customer-123',
+        plan: 'enterprise',
+      };
+      const result = initTelemetry({
+        telemetry: { enabled: true, metadata },
+        licenseKey: 'test-key',
+      });
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: undefined,
+        licenseKey: 'test-key',
+        metadata,
+      });
+    });
+
+    it('passes nested metadata to Telemetry', () => {
+      const metadata = {
+        customerId: 'customer-123',
+        nested: { key: 'value', deep: { level: 2 } },
+      };
+      const result = initTelemetry({
+        telemetry: { enabled: true, metadata },
+        licenseKey: 'test-key',
+      });
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: undefined,
+        licenseKey: 'test-key',
+        metadata,
+      });
+    });
+  });
+
+  describe('full configuration', () => {
+    it('passes all config options to Telemetry', () => {
+      const config = {
+        telemetry: {
+          enabled: true,
+          endpoint: 'https://custom.endpoint.com/collect',
+          metadata: { customerId: 'abc', env: 'production' },
+        },
+        licenseKey: 'license-key-123',
+      };
+
+      const result = initTelemetry(config);
+
+      expect(result).not.toBeNull();
+      expect(Telemetry).toHaveBeenCalledWith({
+        enabled: true,
+        endpoint: 'https://custom.endpoint.com/collect',
+        licenseKey: 'license-key-123',
+        metadata: { customerId: 'abc', env: 'production' },
+      });
+    });
+  });
+});

packages/super-editor/src/core/Editor.ts

@@ -54,6 +54,7 @@ import type { EditorRenderer } from './renderers/EditorRenderer.js';
 import { ProseMirrorRenderer } from './renderers/ProseMirrorRenderer.js';
 import { BLANK_DOCX_DATA_URI } from './blank-docx.js';
 import { getArrayBufferFromUrl } from '@core/super-converter/helpers.js';
+import { Telemetry, COMMUNITY_LICENSE_KEY } from '@superdoc/common';
 
 declare const __APP_VERSION__: string;
 declare const version: string | undefined;
@@ -243,6 +244,16 @@ export class Editor extends EventEmitter<EditorEventMap> {
    */
   setHighContrastMode?: (enabled: boolean) => void;
 
+  /**
+   * Telemetry instance for tracking document opens
+   */
+  #telemetry: Telemetry | null = null;
+
+  /**
+   * Guard flag to prevent double-tracking document open
+   */
+  #documentOpenTracked = false;
+
   options: EditorOptions = {
     element: null,
     selector: null,
@@ -327,6 +338,12 @@ export class Editor extends EventEmitter<EditorEventMap> {
 
     // header/footer editors may have parent(main) editor set
     parentEditor: null,
+
+    // License key (defaults to community license)
+    licenseKey: COMMUNITY_LICENSE_KEY,
+
+    // Telemetry configuration
+    telemetry: null,
   };
 
   /**
@@ -393,6 +410,7 @@ export class Editor extends EventEmitter<EditorEventMap> {
     this.#checkHeadless(resolvedOptions);
     this.setOptions(resolvedOptions);
     this.#renderer = resolvedOptions.renderer ?? (domAvailable ? new ProseMirrorRenderer() : null);
+    this.#initTelemetry();
 
     const { setHighContrastMode } = useHighContrastMode();
     this.setHighContrastMode = setHighContrastMode;
@@ -454,6 +472,53 @@ export class Editor extends EventEmitter<EditorEventMap> {
       if (this.isDestroyed) return;
       this.emit('create', { editor: this });
     }, 0);
+
+    // Generate metadata and track telemetry (non-blocking)
+    this.#trackDocumentOpen();
+  }
+
+  /**
+   * Initialize telemetry if configured
+   */
+  #initTelemetry(): void {
+    const { telemetry: telemetryConfig, licenseKey } = this.options;
+
+    // Skip if telemetry is not enabled
+    if (!telemetryConfig?.enabled) {
+      console.debug('[super-editor] Telemetry: disabled');
+      return;
+    }
+
+    try {
+      this.#telemetry = new Telemetry({
+        enabled: true,
+        endpoint: telemetryConfig.endpoint,
+        licenseKey: licenseKey === undefined ? COMMUNITY_LICENSE_KEY : licenseKey,
+        metadata: telemetryConfig.metadata,
+      });
+      console.debug('[super-editor] Telemetry: enabled');
+    } catch {
+      // Fail silently - telemetry should never break the app
+    }
+  }
+
+  /**
+   * Ensure document metadata is generated and track telemetry if enabled
+   */
+  #trackDocumentOpen(): void {
+    // Always generate metadata (GUID, timestamp) regardless of telemetry
+    this.getDocumentIdentifier().then((documentId) => {
+      // Only track if telemetry enabled and not already tracked
+      if (!this.#telemetry || this.#documentOpenTracked) return;
+
+      try {
+        const documentCreatedAt = this.converter?.getDocumentCreatedTimestamp?.() || null;
+        this.#telemetry.trackDocumentOpen(documentId, documentCreatedAt);
+        this.#documentOpenTracked = true;
+      } catch {
+        // Fail silently - telemetry should never break the app
+      }
+    });
   }
 
   /**
@@ -992,6 +1057,9 @@ export class Editor extends EventEmitter<EditorEventMap> {
       if (this.isDestroyed) return;
       this.emit('create', { editor: this });
     }, 0);
+
+    // Generate metadata and track telemetry (non-blocking)
+    this.#trackDocumentOpen();
   }
 
   unmount(): void {
@@ -1553,6 +1621,7 @@ export class Editor extends EventEmitter<EditorEventMap> {
         documentId: this.options.documentId,
         mockWindow: this.options.mockWindow ?? null,
         mockDocument: this.options.mockDocument ?? null,
+        isNewFile: this.options.isNewFile ?? false,
       });
     }
   }
@@ -2118,7 +2187,8 @@ export class Editor extends EventEmitter<EditorEventMap> {
   }
 
   /**
-   * Get document identifier (async - may generate hash)
+   * Get document unique identifier (async)
+   * Returns a stable identifier for the document (identifierHash or contentHash)
    */
   async getDocumentIdentifier(): Promise<string | null> {
     return (await this.converter?.getDocumentIdentifier()) || null;
@@ -2521,6 +2591,11 @@ export class Editor extends EventEmitter<EditorEventMap> {
 
       const numberingData = this.converter.convertedXml['word/numbering.xml'];
       const numbering = this.converter.schemaToXml(numberingData.elements[0]);
+
+      // Export core.xml (contains dcterms:created timestamp)
+      const coreXmlData = this.converter.convertedXml['docProps/core.xml'];
+      const coreXml = coreXmlData?.elements?.[0] ? this.converter.schemaToXml(coreXmlData.elements[0]) : null;
+
       const updatedDocs: Record<string, string> = {
         ...this.options.customUpdatedFiles,
         'word/document.xml': String(documentXml),
@@ -2531,6 +2606,7 @@ export class Editor extends EventEmitter<EditorEventMap> {
         // Replace & with &amp; in styles.xml as DOCX viewers can't handle it
         'word/styles.xml': String(styles).replace(/&/gi, '&amp;'),
         ...updatedHeadersFooters,
+        ...(coreXml ? { 'docProps/core.xml': String(coreXml) } : {}),
       };
 
       if (hasCustomSettings) {