@powerit/cms-tracker 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,486 @@
+/**
+ * PowerIT CMS Tracker TypeScript Definitions
+ */
+
+// ============================================================================
+// Logger Interface
+// ============================================================================
+
+/**
+ * Logger interface for tracker
+ */
+export interface TrackerLogger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+// ============================================================================
+// Privacy Configuration
+// ============================================================================
+
+/**
+ * Input masking options
+ */
+export interface MaskInputOptions {
+  /** Mask password inputs (default: true) */
+  password?: boolean;
+  /** Mask email inputs (default: true) */
+  email?: boolean;
+  /** Mask telephone inputs (default: true) */
+  tel?: boolean;
+  /** Mask credit card inputs (default: true) */
+  creditCard?: boolean;
+  /** Mask regular text inputs (default: false) */
+  text?: boolean;
+  /** Mask textareas (default: false) */
+  textarea?: boolean;
+  /** Mask select elements (default: false) */
+  select?: boolean;
+}
+
+/**
+ * Privacy configuration for session recording
+ */
+export interface TrackerPrivacyConfig {
+  /** Respect browser's Do Not Track setting (default: true) */
+  respectDoNotTrack?: boolean;
+
+  /** CSS class for blocked elements - replaced with placeholder (default: 'rr-block') */
+  blockClass?: string;
+
+  /** CSS selector for blocked elements */
+  blockSelector?: string;
+
+  /** CSS class for ignored elements - no input recording (default: 'rr-ignore') */
+  ignoreClass?: string;
+
+  /** CSS selector for ignored elements */
+  ignoreSelector?: string;
+
+  /** CSS class for masked text (default: 'rr-mask') */
+  maskTextClass?: string;
+
+  /** CSS selector for masked text */
+  maskTextSelector?: string;
+
+  /** Mask all input values (default: true for privacy) */
+  maskAllInputs?: boolean;
+
+  /** Specific input types to mask */
+  maskInputOptions?: MaskInputOptions;
+
+  /** Custom input masking function */
+  maskInputFn?: (text: string, element: HTMLElement) => string;
+
+  /** Custom text masking function */
+  maskTextFn?: (text: string, element: HTMLElement) => string;
+
+  /** CSS attributes to ignore */
+  ignoreCSSAttributes?: string[];
+
+  /** Block recording on specific pages (string prefix or regex patterns) */
+  blockedPages?: (string | RegExp)[];
+
+  /** Only record on specific pages (string prefix or regex patterns) */
+  allowedPages?: (string | RegExp)[];
+}
+
+// ============================================================================
+// Sampling Configuration
+// ============================================================================
+
+/**
+ * Sampling configuration to reduce data volume
+ */
+export interface TrackerSamplingConfig {
+  /** Enable sampling (default: false) */
+  enabled?: boolean;
+
+  /** Percentage of sessions to record (0-100, default: 100) */
+  sessionRate?: number;
+
+  /** Mouse movement sampling (events per second, default: 50) */
+  mousemove?: number | boolean;
+
+  /** Mouse interaction sampling (default: true) */
+  mouseInteraction?: boolean;
+
+  /** Scroll event sampling (events per second, default: 10) */
+  scroll?: number | boolean;
+
+  /** Media interaction sampling (default: true) */
+  media?: boolean;
+
+  /** Input change sampling: 'last' captures only final value (default: 'last') */
+  input?: 'last' | boolean;
+}
+
+// ============================================================================
+// Recording Configuration
+// ============================================================================
+
+/**
+ * DOM recording options
+ */
+export interface TrackerRecordingConfig {
+  /** Record canvas elements (default: false) */
+  recordCanvas?: boolean;
+
+  /** Record cross-origin iframes (default: false) */
+  recordCrossOriginIframes?: boolean;
+
+  /** Inline stylesheets in events (default: true) */
+  inlineStylesheet?: boolean;
+
+  /** Inline images as data URLs (default: false) */
+  inlineImages?: boolean;
+
+  /** Collect fonts for replay (default: false) */
+  collectFonts?: boolean;
+
+  /** Slim DOM options to reduce event size */
+  slimDOMOptions?: {
+    script?: boolean;
+    comment?: boolean;
+    headFavicon?: boolean;
+    headWhitespace?: boolean;
+    headMetaDescKeywords?: boolean;
+    headMetaSocial?: boolean;
+    headMetaRobots?: boolean;
+    headMetaHttpEquiv?: boolean;
+    headMetaAuthorship?: boolean;
+    headMetaVerification?: boolean;
+  };
+}
+
+// ============================================================================
+// Main Configuration
+// ============================================================================
+
+/**
+ * Session tracker configuration
+ */
+export interface TrackerConfig {
+  /** Transport type: 'http' or 'grpc' (default: 'http') */
+  transport?: 'http' | 'grpc';
+
+  /** Custom transport URL (defaults to client baseUrl) */
+  transportUrl?: string;
+
+  /** Privacy settings */
+  privacy?: TrackerPrivacyConfig;
+
+  /** Sampling settings */
+  sampling?: TrackerSamplingConfig;
+
+  /** Recording settings */
+  recording?: TrackerRecordingConfig;
+
+  /** Batch size for sending events (default: 50) */
+  batchSize?: number;
+
+  /** Flush interval in ms (default: 5000) */
+  flushInterval?: number;
+
+  /** Maximum events to queue before forced flush (default: 500) */
+  maxQueueSize?: number;
+
+  /** Compress events before sending (default: true) */
+  compress?: boolean;
+
+  /** Checkout every N events for snapshot (default: 200) */
+  checkoutEveryNth?: number;
+
+  /** Checkout every N ms (default: 300000 = 5 min) */
+  checkoutEveryNms?: number;
+
+  /** Session timeout in ms (default: 1800000 = 30 min) */
+  sessionTimeout?: number;
+
+  /** Storage key prefix (default: 'powerit_tracker') */
+  storageKey?: string;
+
+  /**
+   * Enable logging
+   * - `true`: Use default console logger
+   * - `TrackerLogger`: Use custom logger
+   * - `false` or `undefined`: Disable logging (default)
+   */
+  logger?: boolean | TrackerLogger;
+
+  /** Error handler callback */
+  onError?: (error: Error) => void;
+}
+
+// ============================================================================
+// Session Types
+// ============================================================================
+
+/**
+ * Session information
+ */
+export interface TrackerSession {
+  /** Unique session ID */
+  sessionId: string;
+
+  /** Visitor ID (persistent across sessions) */
+  visitorId: string;
+
+  /** Session start timestamp */
+  startedAt: number;
+
+  /** Last activity timestamp */
+  lastActivityAt: number;
+
+  /** Page URL where session started */
+  entryPage: string;
+
+  /** Full entry URL */
+  entryUrl: string;
+
+  /** Total events recorded */
+  eventCount: number;
+
+  /** Whether session is linked to analytics plugin */
+  linkedToAnalytics: boolean;
+
+  /** Analytics session ID if linked */
+  analyticsSessionId: string | null;
+}
+
+// ============================================================================
+// Compression Types
+// ============================================================================
+
+/**
+ * Compressed events container
+ */
+export interface CompressedEvents {
+  /** Compression type: 'gzip' or 'none' */
+  type: 'gzip' | 'none';
+
+  /** Compressed or raw data */
+  data: string;
+
+  /** Original size in bytes */
+  originalSize: number;
+
+  /** Compressed size in bytes */
+  compressedSize: number;
+}
+
+/**
+ * Compression statistics
+ */
+export interface CompressionStats {
+  /** Original size in bytes */
+  originalSize: number;
+
+  /** Compressed size in bytes */
+  compressedSize: number;
+
+  /** Compression ratio */
+  ratio: string;
+
+  /** Savings percentage */
+  savings: string;
+
+  /** Compression type used */
+  type: 'gzip' | 'none';
+}
+
+// ============================================================================
+// Session Manager Class
+// ============================================================================
+
+/**
+ * Session Manager
+ * Manages visitor and session IDs with persistence
+ */
+export declare class SessionManager {
+  constructor(options?: {
+    storageKey?: string;
+    sessionTimeout?: number;
+  });
+
+  /** Get or create a session */
+  getOrCreateSession(): TrackerSession;
+
+  /** Get current session */
+  getSession(): TrackerSession | null;
+
+  /** Get visitor ID */
+  getVisitorId(): string | null;
+
+  /** Get session ID */
+  getSessionId(): string | null;
+
+  /** Link to analytics session */
+  linkToAnalytics(analyticsTracker: unknown): void;
+
+  /** Update activity timestamp */
+  touch(): void;
+
+  /** Increment event count */
+  incrementEventCount(count?: number): void;
+
+  /** End the current session */
+  endSession(): void;
+
+  /** Check if session is valid */
+  isSessionValid(): boolean;
+}
+
+// ============================================================================
+// Session Recorder Class
+// ============================================================================
+
+/**
+ * Session Recorder
+ * Records user sessions using rrweb
+ */
+export declare class SessionRecorder {
+  constructor(client: unknown, config?: TrackerConfig);
+
+  /**
+   * Initialize the recorder
+   * Sets up transport, session, and event handlers
+   */
+  init(): Promise<SessionRecorder>;
+
+  /** Start recording */
+  start(): void;
+
+  /** Pause recording (keeps session active) */
+  pause(): void;
+
+  /** Resume recording */
+  resume(): void;
+
+  /** Stop recording and flush events */
+  stop(): Promise<void>;
+
+  /** Check if currently recording */
+  isRecording(): boolean;
+
+  /** Check if tracking is enabled */
+  isEnabled(): boolean;
+
+  /** Get current session info */
+  getSession(): TrackerSession | null;
+
+  /** Get visitor ID */
+  getVisitorId(): string | null;
+
+  /** Get session ID */
+  getSessionId(): string | null;
+
+  /** Flush pending events */
+  flush(): Promise<void>;
+
+  /**
+   * Add a custom event to the recording
+   * @param tag - Event tag/name
+   * @param payload - Event payload
+   */
+  addCustomEvent(tag: string, payload?: Record<string, unknown>): void;
+
+  /**
+   * Identify a user
+   * @param userId - User identifier
+   * @param traits - User traits/properties
+   */
+  identify(userId: string, traits?: Record<string, unknown>): void;
+
+  /** Take a full snapshot manually */
+  takeSnapshot(): void;
+
+  /**
+   * Update privacy settings at runtime
+   * @param privacy - Privacy configuration updates
+   */
+  updatePrivacy(privacy: Partial<TrackerPrivacyConfig>): void;
+
+  /** Enable recording */
+  enable(): void;
+
+  /** Disable recording */
+  disable(): void;
+
+  /** Destroy the recorder and cleanup */
+  destroy(): void;
+}
+
+// ============================================================================
+// Privacy Utilities
+// ============================================================================
+
+/** Default privacy configuration */
+export declare const DEFAULT_PRIVACY_CONFIG: TrackerPrivacyConfig;
+
+/** Sensitive CSS selectors that are auto-blocked */
+export declare const SENSITIVE_SELECTORS: string[];
+
+/** Check if Do Not Track is enabled */
+export declare function isDoNotTrackEnabled(): boolean;
+
+/** Check if current page should be recorded */
+export declare function shouldRecordPage(
+  config: TrackerPrivacyConfig,
+  currentPath: string
+): boolean;
+
+/** Build rrweb-compatible privacy config */
+export declare function buildRrwebPrivacyConfig(
+  config: TrackerPrivacyConfig
+): Record<string, unknown>;
+
+/** Merge user privacy config with defaults */
+export declare function mergePrivacyConfig(
+  userConfig?: Partial<TrackerPrivacyConfig>
+): TrackerPrivacyConfig;
+
+// ============================================================================
+// Compression Utilities
+// ============================================================================
+
+/** Compress events using browser's CompressionStream */
+export declare function compressEvents(events: unknown[]): Promise<CompressedEvents>;
+
+/** Decompress events */
+export declare function decompressEvents(compressed: CompressedEvents): Promise<unknown[]>;
+
+/** Estimate compression ratio for events */
+export declare function estimateCompression(events: unknown[]): Promise<CompressionStats>;
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/** Create a session recorder instance */
+export declare function createRecorder(
+  client: unknown,
+  config?: TrackerConfig
+): SessionRecorder;
+
+/** Create a session manager instance */
+export declare function createSessionManager(options?: {
+  storageKey?: string;
+  sessionTimeout?: number;
+}): SessionManager;
+
+// ============================================================================
+// Plugin
+// ============================================================================
+
+/**
+ * Tracker plugin for @powerit/cms-client
+ */
+export declare const trackerPlugin: {
+  name: 'tracker';
+  install(client: unknown, options?: TrackerConfig): () => void;
+};
+
+export default trackerPlugin;