npm package: @quotientjs/browser-fingerprint
Description: A lightweight, privacy-conscious browser fingerprinting library for identifying unique browsers.
Latest version: 0.1.5

# @quotientjs/browser-fingerprint

A lightweight, privacy-conscious browser fingerprinting library for identifying unique browsers.

## Features

- Create unique browser fingerprints based on browser characteristics
- High-entropy components for reliable identification
- Handle fingerprint storage and tracking
- Compare fingerprints for similarity
- Configurable collection options
- Supports both localStorage and sessionStorage

## Installation

```bash
pnpm add @quotientjs/browser-fingerprint
```

## Usage

```typescript
import BrowserFingerprint from "@quotientjs/browser-fingerprint";

// Create a new fingerprinter
const fingerprinter = new BrowserFingerprint();

// Get the fingerprint (automatically saved to localStorage)
const fingerprint = fingerprinter.get();

console.log("Fingerprint hash:", fingerprint.hash);
```

### Advanced Options

```typescript
// More options
const fingerprinter = new BrowserFingerprint(
  {
    // Fingerprint options
    excludeComponents: ["canvas", "webgl"], // Exclude privacy-sensitive components
    includeAudio: true,
    includeCanvas: true,
    includeWebGL: true,
    includeFonts: true,
    detectScreenOrientation: true,
  },
  {
    // Storage options
    storageKey: "my_app_fingerprint",
    useSessionStorage: false, // Use localStorage by default
    maxFingerprints: 10,
    similarityThreshold: 0.85,
  },
);
```

### Working with Fingerprints

```typescript
// Get fingerprint without saving
const fingerprint = fingerprinter.get(false);

// Access all stored fingerprints
const allFingerprints = fingerprinter.getAll();

// Access the storage for more advanced operations
const storage = fingerprinter.getStorage();

// Find the most common fingerprint
const mostFrequent = storage.getMostFrequent();

// Find the most recent fingerprint
const mostRecent = storage.getMostRecent();

// Find a specific fingerprint by hash
const specificFingerprint = storage.findByHash(fingerprint.hash);

// Find a similar fingerprint
const similarFingerprint = storage.findSimilar(fingerprint);

// Clear all fingerprints
fingerprinter.clear();
```

## API Reference

### BrowserFingerprint

The main class for fingerprinting operations.

#### Methods

- `get(save = true)`: Gets or creates a fingerprint
- `getAll()`: Returns all stored fingerprints
- `clear()`: Clears all stored fingerprints
- `getStorage()`: Returns the storage instance

### FingerprintStorage

Handles storing and retrieving fingerprints.

#### Methods

- `getAll()`: Returns all stored fingerprints
- `save(fingerprint, source)`: Saves a fingerprint
- `clear()`: Clears all stored fingerprints
- `getMostRecent()`: Gets the most recently seen fingerprint
- `getMostFrequent()`: Gets the most frequently seen fingerprint
- `findByHash(hash)`: Finds a fingerprint by hash
- `findSimilar(fingerprint)`: Finds a similar fingerprint

### Utility Functions

- `createFingerprint(options)`: Creates a new fingerprint
- `calculateSimilarity(fp1, fp2)`: Calculates similarity between fingerprints
- `isSameFingerprint(fp1, fp2, threshold)`: Determines if two fingerprints match

## Development

```bash
# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build
```

## License

Internal use only.