input-tracker/README.md

Cross-platform input tracking library for capturing keyboard and mouse events

# InputTracker

A cross-platform library for tracking keyboard and mouse events with native performance.

## Features

- Track keyboard and mouse events in real-time
- Get detailed cursor information including handle, name, and CSS equivalent
- Configure output location for logs
- Improved JSON schema for easier data processing
- Chainable API for configuration
- Auto-start option
- Cross-platform support (Windows, macOS, Linux)

## Installation

```bash
# Using npm
npm install input-tracker

# Using Yarn
yarn add input-tracker

# Using Bun
bun add input-tracker
```

## Usage

### Basic Usage

```js
import InputTracker from 'input-tracker';

// Create a tracker with default settings
const tracker = new InputTracker();

// Start tracking
tracker.start();

// Later, stop tracking
tracker.stop();

// Clean up when done
tracker.destroy();
```

### Configuration Options

```js
const tracker = new InputTracker({
  // Custom output path for logs (default: "./input-log.json")
  outputPath: './my-logs.json',
  
  // Start tracking immediately (default: false)
  autoStart: true,
  
  // Enable/disable console logging (default: true)
  logToConsole: false
});
```

### API Methods

```js
// Configuration methods (chainable)
tracker.setOutputPath('./new-log-path.json')
       .setLogToConsole(true);

// Start tracking
const started = tracker.start();  // Returns true if started, false if already tracking

// Stop tracking
const stopped = tracker.stop();   // Returns true if stopped, false if already stopped

// Get current cursor information
const cursorInfo = tracker.getCurrentCursorInfo();
// Returns: { handle: 65539, name: "default", cssName: "default", x: 100, y: 200 }

// Get all collected logs
const logs = tracker.getLogs();

// Clear all logs
tracker.clearLogs();

// Clean up resources
tracker.destroy();
```

## Event Data Structure

The logs are stored with the following schema:

```js
{
  // Timestamp in milliseconds
  timestamp: 1622548800000,
  
  // Event type
  type: "keyDown" | "keyUp" | "mouseDown" | "mouseUp" | "mouse-move" | "mouseWheel" | "click" | "cursor" | "unknown",
  
  // Original event string from native code
  rawEvent: "Original event string",
  
  // For cursor events only
  cursor: {
    handle: 65539,
    name: "default",
    cssName: "default",
    x: 100,
    y: 200
  },
  
  // For click events only
  position: {
    x: 100,
    y: 200
  }
}
```

## Example

```js
import InputTracker from 'input-tracker';

// Create a tracker with custom configuration
const tracker = new InputTracker({
  outputPath: './input-log.json',
  autoStart: false,
  logToConsole: true
});

// Start tracking
tracker.start();

// Get current cursor info
const cursorInfo = tracker.getCurrentCursorInfo();
console.log('Current cursor info:', cursorInfo);

// Stop tracking after 5 seconds
setTimeout(() => {
  tracker.stop();
  
  // Get the collected logs
  const logs = tracker.getLogs();
  console.log(`Collected ${logs.length} input events`);
  
  // Clean up resources
  tracker.destroy();
}, 5000);
```

## License

MIT