writetrack 0.1.0 → 0.3.0

package/dist/react/index.d.ts

@@ -1,300 +1,24 @@
+import { WriteTrack } from 'writetrack';
 import { RefObject } from 'react';
 
-/**
- * Raw Event Data Structures
- *
- * Defines the structure for raw input events collected during typing sessions.
- * This is the foundation layer containing unprocessed user interaction data.
- */
-/**
- * Raw session data containing all collected events
- */
-interface RawEventData {
-    /** Primary keystroke events */
-    events: KeystrokeEvent[];
-    /** Clipboard operation events (optional) */
-    clipboardEvents?: ClipboardEvent[];
-    /** Undo/redo operation events (optional) */
-    undoRedoEvents?: UndoRedoEvent[];
-    /** Text selection events (optional) */
-    selectionEvents?: SelectionEvent[];
-    /** Final text that was typed */
-    rawText: string;
-    /** Session start time (unix timestamp) */
-    sessionStartTime: number;
-    /** Session end time (unix timestamp) */
-    sessionEndTime: number;
-}
-/**
- * Individual keystroke event
- */
-interface KeystrokeEvent {
-    /** Key identifier (character or key name) */
-    key: string;
-    /** Physical key code */
-    code: string;
-    /** Event type */
-    type: 'keydown' | 'keyup';
-    /** High-precision timestamp (performance.now()) */
-    timestamp: number;
-    /** Key hold duration (for keyup events) */
-    dwellTime?: number;
-    /** Time to next key press (for keydown events) */
-    flightTime?: number;
-    /** Whether this keystroke was part of a correction */
-    isCorrection?: boolean;
-    /** Whether this keystroke was part of a typing burst */
-    isBurst?: boolean;
-    /** Window focus state at time of keystroke */
-    windowFocused: boolean;
-    /** Time since last mouse interaction */
-    timeSinceLastMouse: number;
-    /** Character position in text at time of keystroke */
-    cursorPosition?: number;
-    /** Modifier key states */
-    modifiers?: ModifierState;
-}
-/**
- * Modifier key states
- */
-interface ModifierState {
-    ctrl: boolean;
-    alt: boolean;
-    shift: boolean;
-    meta: boolean;
-}
-/**
- * Clipboard operation event
- */
-interface ClipboardEvent {
-    /** Clipboard operation type */
-    type: 'copy' | 'paste' | 'cut';
-    /** Event timestamp */
-    timestamp: number;
-    /** Text position where operation occurred */
-    position: number;
-    /** Length of text affected */
-    length: number;
-    /** Keyboard shortcut used */
-    shortcut: string;
-    /** Actual clipboard content (optional for privacy) */
-    content?: string;
-    /** Text state before operation (optional) */
-    beforeText?: string;
-    /** Text state after operation (optional) */
-    afterText?: string;
-    /** Text that was replaced by paste (optional) */
-    replacedText?: string;
-    /** Range of text replaced by paste (optional) */
-    replacedRange?: {
-        start: number;
-        end: number;
-    };
-}
-/**
- * Text selection event
- */
-interface SelectionEvent {
-    /** Event type */
-    type: 'select';
-    /** Event timestamp */
-    timestamp: number;
-    /** Start position of selection */
-    startPosition: number;
-    /** End position of selection */
-    endPosition: number;
-    /** Length of selected text */
-    selectedLength: number;
-    /** Selected text content (optional for privacy) */
-    selectedText?: string;
-    /** How the selection was made */
-    method: 'mouse' | 'keyboard' | 'programmatic';
-}
-/**
- * Undo/Redo operation event
- */
-interface UndoRedoEvent {
-    /** Operation type */
-    type: 'undo' | 'redo';
-    /** Event timestamp */
-    timestamp: number;
-    /** Keyboard shortcut used */
-    shortcut: string;
-    /** Text state before operation */
-    beforeText: string;
-    /** Text state after operation */
-    afterText: string;
+export interface UseWriteTrackOptions {
+  /** Auto-start tracking when element is available (default: true) */
+  autoStart?: boolean;
 }
 
-/**
- * Session Metadata Data Structures
- *
- * Defines metadata for the capture session context.
- */
-/**
- * Session metadata returned by getData()
- */
-interface SessionMetadata {
-    /** Tool identification and version */
-    tool: ToolInfo;
-    /** Target element type (e.g., 'textarea', 'input', 'div') */
-    targetElement: string;
-    /** Collection timestamp (ISO8601) */
-    timestamp: string;
-    /** Session duration in milliseconds */
-    duration: number;
-}
-/**
- * Tool identification
- */
-interface ToolInfo {
-    /** Tool name */
-    name: string;
-    /** Tool version */
-    version: string;
-    /** Tool category (internal use — set by training pipeline, not capture SDK) */
-    category?: 'human' | 'selenium' | 'playwright' | 'puppeteer' | 'cypress' | 'webdriverio' | 'other';
-}
-
-/**
- * WriteTrack Data Schema v2.0.0 - Main Schema Definition
- *
- * This is the unified, versioned schema for all WriteTrack data structures.
- * It provides a single source of truth for data formats across the entire system.
- */
-
-/**
- * Main WriteTrack Data Schema Interface
- * This is the top-level structure for all WriteTrack data exports
- */
-interface WriteTrackDataSchema {
-    /** Schema version for compatibility and migration */
-    version: '2.0.0';
-    /** Session metadata */
-    metadata: SessionMetadata;
-    /** Raw session data (keystrokes, clipboard, selection events) */
-    session: RawEventData;
-    /** Data quality metrics and validation status */
-    quality: DataQualityMetrics;
-    /** True when data was captured without a valid license (production use) */
-    unlicensed?: boolean;
-}
-/**
- * Data Quality Assessment
- */
-interface DataQualityMetrics {
-    /** Overall data quality score (0-1) */
-    overallScore: number;
-    /** Data completeness percentage */
-    completeness: number;
-    /** Event sequence consistency validation */
-    sequenceValid: boolean;
-    /** Timing data integrity status */
-    timingValid: boolean;
-    /** Session duration in milliseconds */
-    sessionDuration: number;
-    /** Total number of events collected */
-    eventCount: number;
-    /** Quality assessment level */
-    qualityLevel: 'POOR' | 'FAIR' | 'GOOD' | 'EXCELLENT';
-    /** Quality issues identified */
-    issues: string[];
-    /** Validation timestamp */
-    validatedAt: string;
+export interface UseWriteTrackReturn {
+  /** Reset the tracker and clear state */
+  reset: () => void;
+  /** Start tracking (if autoStart was false) */
+  start: () => void;
+  /** Stop tracking */
+  stop: () => void;
+  /** Whether the tracker is currently active */
+  isTracking: boolean;
+  /** Access to the underlying WriteTrack instance */
+  tracker: WriteTrack | null;
 }
 
-interface WriteTrackOptions {
-    target: HTMLElement;
-    license?: string;
-}
-declare class WriteTrack {
-    protected keystrokeEvents: KeystrokeEvent[];
-    protected clipboardEvents: ClipboardEvent[];
-    protected undoRedoEvents: UndoRedoEvent[];
-    protected selectionEvents: SelectionEvent[];
-    private pendingKeydowns;
-    protected lastMouseActivity: number;
-    protected sessionStartTime: number;
-    protected lastKeyTime: number;
-    protected lastKeyUpTime: number;
-    protected repeatedKeyTracker: Map<string, number[]>;
-    private focusStartTime;
-    private lastSelection;
-    protected readonly BURST_THRESHOLD = 150;
-    protected readonly PAUSE_THRESHOLD = 1000;
-    protected readonly CORRECTION_KEYS: Set<string>;
-    private readonly targetType;
-    protected readonly target: HTMLElement;
-    private readonly license?;
-    /**
-     * Create a WriteTrack instance
-     * @param optionsOrTarget - Either an HTMLElement (demo mode) or WriteTrackOptions object
-     */
-    constructor(optionsOrTarget: WriteTrackOptions | HTMLElement);
-    private validateLicenseAsync;
-    private setupEventListeners;
-    /**
-     * Technique 6: Observe target's parent for childList changes.
-     * If target is removed from DOM, stop recording.
-     */
-    private setupTargetObserver;
-    private isRecordingEnabled;
-    private recordKeydown;
-    private recordKeyup;
-    private recordMouseActivity;
-    private recordWindowFocus;
-    private detectKeyboardShortcuts;
-    private recordClipboardEvent;
-    private recordSelection;
-    private checkSelectionAfterMouse;
-    private recordSelectionChange;
-    private getSelection;
-    private getSelectedTextLength;
-    private recordVisibilityChange;
-    private getShortcutString;
-    private getCurrentCursorPosition;
-    private isMacPlatform;
-    private trackRepeatedKey;
-    /**
-     * Check if the license is valid
-     */
-    isLicenseValid(): boolean;
-    /**
-     * Check if license validation has completed
-     */
-    isLicenseValidated(): boolean;
-    /**
-     * Check if the target element was detached from the DOM
-     */
-    isTargetDetached(): boolean;
-    start(): void;
-    stop(): void;
-    getRawEvents(): KeystrokeEvent[];
-    getClipboardEvents(): ClipboardEvent[];
-    getUndoRedoEvents(): UndoRedoEvent[];
-    getSelectionEvents(): SelectionEvent[];
-    getSessionDuration(): number;
-    getKeystrokeCount(): number;
-    getText(): string;
-    getData(): WriteTrackDataSchema;
-}
-
-interface UseWriteTrackOptions {
-    /** Auto-start tracking when element is available (default: true) */
-    autoStart?: boolean;
-}
-interface UseWriteTrackReturn {
-    /** Reset the tracker and clear state */
-    reset: () => void;
-    /** Start tracking (if autoStart was false) */
-    start: () => void;
-    /** Stop tracking */
-    stop: () => void;
-    /** Whether the tracker is currently active */
-    isTracking: boolean;
-    /** Access to the underlying WriteTrack instance */
-    tracker: WriteTrack | null;
-}
 /**
  * React hook for WriteTrack keystroke analysis
  *
@@ -307,8 +31,8 @@ interface UseWriteTrackReturn {
  *   const handleSubmit = (e: FormEvent) => {
  *     e.preventDefault();
  *     if (tracker) {
- *       const features = tracker.getBehavioralFeatures();
- *       console.log('Features:', features);
+ *       const data = tracker.getData();
+ *       console.log('Data:', data);
  *     }
  *   };
  *
@@ -321,6 +45,7 @@ interface UseWriteTrackReturn {
  * }
  * ```
  */
-declare function useWriteTrack(ref: RefObject<HTMLElement | null>, options?: UseWriteTrackOptions): UseWriteTrackReturn;
-
-export { type UseWriteTrackOptions, type UseWriteTrackReturn, useWriteTrack };
+export declare function useWriteTrack(
+  ref: RefObject<HTMLElement | null>,
+  options?: UseWriteTrackOptions
+): UseWriteTrackReturn;

package/dist/vue/index.d.ts

@@ -1,300 +1,24 @@
+import { WriteTrack } from 'writetrack';
 import { Ref, ShallowRef } from 'vue';
 
-/**
- * Raw Event Data Structures
- *
- * Defines the structure for raw input events collected during typing sessions.
- * This is the foundation layer containing unprocessed user interaction data.
- */
-/**
- * Raw session data containing all collected events
- */
-interface RawEventData {
-    /** Primary keystroke events */
-    events: KeystrokeEvent[];
-    /** Clipboard operation events (optional) */
-    clipboardEvents?: ClipboardEvent[];
-    /** Undo/redo operation events (optional) */
-    undoRedoEvents?: UndoRedoEvent[];
-    /** Text selection events (optional) */
-    selectionEvents?: SelectionEvent[];
-    /** Final text that was typed */
-    rawText: string;
-    /** Session start time (unix timestamp) */
-    sessionStartTime: number;
-    /** Session end time (unix timestamp) */
-    sessionEndTime: number;
-}
-/**
- * Individual keystroke event
- */
-interface KeystrokeEvent {
-    /** Key identifier (character or key name) */
-    key: string;
-    /** Physical key code */
-    code: string;
-    /** Event type */
-    type: 'keydown' | 'keyup';
-    /** High-precision timestamp (performance.now()) */
-    timestamp: number;
-    /** Key hold duration (for keyup events) */
-    dwellTime?: number;
-    /** Time to next key press (for keydown events) */
-    flightTime?: number;
-    /** Whether this keystroke was part of a correction */
-    isCorrection?: boolean;
-    /** Whether this keystroke was part of a typing burst */
-    isBurst?: boolean;
-    /** Window focus state at time of keystroke */
-    windowFocused: boolean;
-    /** Time since last mouse interaction */
-    timeSinceLastMouse: number;
-    /** Character position in text at time of keystroke */
-    cursorPosition?: number;
-    /** Modifier key states */
-    modifiers?: ModifierState;
-}
-/**
- * Modifier key states
- */
-interface ModifierState {
-    ctrl: boolean;
-    alt: boolean;
-    shift: boolean;
-    meta: boolean;
-}
-/**
- * Clipboard operation event
- */
-interface ClipboardEvent {
-    /** Clipboard operation type */
-    type: 'copy' | 'paste' | 'cut';
-    /** Event timestamp */
-    timestamp: number;
-    /** Text position where operation occurred */
-    position: number;
-    /** Length of text affected */
-    length: number;
-    /** Keyboard shortcut used */
-    shortcut: string;
-    /** Actual clipboard content (optional for privacy) */
-    content?: string;
-    /** Text state before operation (optional) */
-    beforeText?: string;
-    /** Text state after operation (optional) */
-    afterText?: string;
-    /** Text that was replaced by paste (optional) */
-    replacedText?: string;
-    /** Range of text replaced by paste (optional) */
-    replacedRange?: {
-        start: number;
-        end: number;
-    };
-}
-/**
- * Text selection event
- */
-interface SelectionEvent {
-    /** Event type */
-    type: 'select';
-    /** Event timestamp */
-    timestamp: number;
-    /** Start position of selection */
-    startPosition: number;
-    /** End position of selection */
-    endPosition: number;
-    /** Length of selected text */
-    selectedLength: number;
-    /** Selected text content (optional for privacy) */
-    selectedText?: string;
-    /** How the selection was made */
-    method: 'mouse' | 'keyboard' | 'programmatic';
-}
-/**
- * Undo/Redo operation event
- */
-interface UndoRedoEvent {
-    /** Operation type */
-    type: 'undo' | 'redo';
-    /** Event timestamp */
-    timestamp: number;
-    /** Keyboard shortcut used */
-    shortcut: string;
-    /** Text state before operation */
-    beforeText: string;
-    /** Text state after operation */
-    afterText: string;
+export interface UseWriteTrackOptions {
+  /** Auto-start tracking when element is available (default: true) */
+  autoStart?: boolean;
 }
 
-/**
- * Session Metadata Data Structures
- *
- * Defines metadata for the capture session context.
- */
-/**
- * Session metadata returned by getData()
- */
-interface SessionMetadata {
-    /** Tool identification and version */
-    tool: ToolInfo;
-    /** Target element type (e.g., 'textarea', 'input', 'div') */
-    targetElement: string;
-    /** Collection timestamp (ISO8601) */
-    timestamp: string;
-    /** Session duration in milliseconds */
-    duration: number;
-}
-/**
- * Tool identification
- */
-interface ToolInfo {
-    /** Tool name */
-    name: string;
-    /** Tool version */
-    version: string;
-    /** Tool category (internal use — set by training pipeline, not capture SDK) */
-    category?: 'human' | 'selenium' | 'playwright' | 'puppeteer' | 'cypress' | 'webdriverio' | 'other';
-}
-
-/**
- * WriteTrack Data Schema v2.0.0 - Main Schema Definition
- *
- * This is the unified, versioned schema for all WriteTrack data structures.
- * It provides a single source of truth for data formats across the entire system.
- */
-
-/**
- * Main WriteTrack Data Schema Interface
- * This is the top-level structure for all WriteTrack data exports
- */
-interface WriteTrackDataSchema {
-    /** Schema version for compatibility and migration */
-    version: '2.0.0';
-    /** Session metadata */
-    metadata: SessionMetadata;
-    /** Raw session data (keystrokes, clipboard, selection events) */
-    session: RawEventData;
-    /** Data quality metrics and validation status */
-    quality: DataQualityMetrics;
-    /** True when data was captured without a valid license (production use) */
-    unlicensed?: boolean;
-}
-/**
- * Data Quality Assessment
- */
-interface DataQualityMetrics {
-    /** Overall data quality score (0-1) */
-    overallScore: number;
-    /** Data completeness percentage */
-    completeness: number;
-    /** Event sequence consistency validation */
-    sequenceValid: boolean;
-    /** Timing data integrity status */
-    timingValid: boolean;
-    /** Session duration in milliseconds */
-    sessionDuration: number;
-    /** Total number of events collected */
-    eventCount: number;
-    /** Quality assessment level */
-    qualityLevel: 'POOR' | 'FAIR' | 'GOOD' | 'EXCELLENT';
-    /** Quality issues identified */
-    issues: string[];
-    /** Validation timestamp */
-    validatedAt: string;
+export interface UseWriteTrackReturn {
+  /** Reset the tracker and clear state */
+  reset: () => void;
+  /** Start tracking (if autoStart was false) */
+  start: () => void;
+  /** Stop tracking */
+  stop: () => void;
+  /** Whether the tracker is currently active */
+  isTracking: Ref<boolean>;
+  /** Access to the underlying WriteTrack instance */
+  tracker: ShallowRef<WriteTrack | null>;
 }
 
-interface WriteTrackOptions {
-    target: HTMLElement;
-    license?: string;
-}
-declare class WriteTrack {
-    protected keystrokeEvents: KeystrokeEvent[];
-    protected clipboardEvents: ClipboardEvent[];
-    protected undoRedoEvents: UndoRedoEvent[];
-    protected selectionEvents: SelectionEvent[];
-    private pendingKeydowns;
-    protected lastMouseActivity: number;
-    protected sessionStartTime: number;
-    protected lastKeyTime: number;
-    protected lastKeyUpTime: number;
-    protected repeatedKeyTracker: Map<string, number[]>;
-    private focusStartTime;
-    private lastSelection;
-    protected readonly BURST_THRESHOLD = 150;
-    protected readonly PAUSE_THRESHOLD = 1000;
-    protected readonly CORRECTION_KEYS: Set<string>;
-    private readonly targetType;
-    protected readonly target: HTMLElement;
-    private readonly license?;
-    /**
-     * Create a WriteTrack instance
-     * @param optionsOrTarget - Either an HTMLElement (demo mode) or WriteTrackOptions object
-     */
-    constructor(optionsOrTarget: WriteTrackOptions | HTMLElement);
-    private validateLicenseAsync;
-    private setupEventListeners;
-    /**
-     * Technique 6: Observe target's parent for childList changes.
-     * If target is removed from DOM, stop recording.
-     */
-    private setupTargetObserver;
-    private isRecordingEnabled;
-    private recordKeydown;
-    private recordKeyup;
-    private recordMouseActivity;
-    private recordWindowFocus;
-    private detectKeyboardShortcuts;
-    private recordClipboardEvent;
-    private recordSelection;
-    private checkSelectionAfterMouse;
-    private recordSelectionChange;
-    private getSelection;
-    private getSelectedTextLength;
-    private recordVisibilityChange;
-    private getShortcutString;
-    private getCurrentCursorPosition;
-    private isMacPlatform;
-    private trackRepeatedKey;
-    /**
-     * Check if the license is valid
-     */
-    isLicenseValid(): boolean;
-    /**
-     * Check if license validation has completed
-     */
-    isLicenseValidated(): boolean;
-    /**
-     * Check if the target element was detached from the DOM
-     */
-    isTargetDetached(): boolean;
-    start(): void;
-    stop(): void;
-    getRawEvents(): KeystrokeEvent[];
-    getClipboardEvents(): ClipboardEvent[];
-    getUndoRedoEvents(): UndoRedoEvent[];
-    getSelectionEvents(): SelectionEvent[];
-    getSessionDuration(): number;
-    getKeystrokeCount(): number;
-    getText(): string;
-    getData(): WriteTrackDataSchema;
-}
-
-interface UseWriteTrackOptions {
-    /** Auto-start tracking when element is available (default: true) */
-    autoStart?: boolean;
-}
-interface UseWriteTrackReturn {
-    /** Reset the tracker and clear state */
-    reset: () => void;
-    /** Start tracking (if autoStart was false) */
-    start: () => void;
-    /** Stop tracking */
-    stop: () => void;
-    /** Whether the tracker is currently active */
-    isTracking: Ref<boolean>;
-    /** Access to the underlying WriteTrack instance */
-    tracker: ShallowRef<WriteTrack | null>;
-}
 /**
  * Vue 3 composable for WriteTrack keystroke analysis
  *
@@ -309,8 +33,8 @@ interface UseWriteTrackReturn {
  *
  * function handleSubmit() {
  *   if (tracker.value) {
- *     const features = tracker.value.getBehavioralFeatures();
- *     console.log('Features:', features);
+ *     const data = tracker.value.getData();
+ *     console.log('Data:', data);
  *   }
  * }
  * </script>
@@ -323,6 +47,7 @@ interface UseWriteTrackReturn {
  * </template>
  * ```
  */
-declare function useWriteTrack(elementRef: Ref<HTMLElement | null>, options?: UseWriteTrackOptions): UseWriteTrackReturn;
-
-export { type UseWriteTrackOptions, type UseWriteTrackReturn, useWriteTrack };
+export declare function useWriteTrack(
+  elementRef: Ref<HTMLElement | null>,
+  options?: UseWriteTrackOptions
+): UseWriteTrackReturn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writetrack",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Lightweight keystroke telemetry capture for web applications",
   "main": "dist/index.cjs",
@@ -26,6 +26,12 @@
     "./browser": {
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/browser/index.js"
+    },
+    "./pipes": {
+      "types": "./dist/esm/pipes.d.ts",
+      "browser": "./dist/browser/pipes.js",
+      "import": "./dist/esm/pipes.js",
+      "require": "./dist/pipes.cjs"
     }
   },
   "peerDependencies": {
@@ -45,6 +51,10 @@
     "dist/esm/index.d.ts",
     "dist/browser/index.js",
     "dist/index.cjs",
+    "dist/esm/pipes.js",
+    "dist/esm/pipes.d.ts",
+    "dist/browser/pipes.js",
+    "dist/pipes.cjs",
     "dist/react/",
     "dist/vue/",
     "cli/init.js",