npm package: @neuraltrust/trustgate-client
Description: A browser-based bot detection library that wraps HTTP clients and collects fingerprinting data
Latest version: 1.0.0

# TrustGate Client

A browser-based bot detection library that wraps HTTP clients and collects fingerprinting data to help identify and prevent bot traffic.

## Features

- 🔍 **Environment Fingerprinting**: Collects browser environment data (User-Agent, languages, timezone, screen resolution, etc.)
- 🖼️ **Visual Fingerprinting**: Canvas, WebGL, and AudioContext fingerprinting
- 🛜 **Network Information**: Connection type, downlink, RTT
- 🧪 **Automation Detection**: Detects headless browsers and automation tools
- 🔐 **Persistence Checking**: Verifies cookies, localStorage, sessionStorage, and indexedDB support
- 🔄 **HTTP Client Wrapper**: Wraps existing HTTP clients or provides a simple built-in client

## Installation

```bash
npm install trustgate-client
```

## Development

### CI/CD

This project uses GitHub Actions for continuous integration and continuous delivery. The workflow automatically runs unit tests and builds the project on every push to the main branch and on pull requests.

[![Unit Tests and Build](https://github.com/NeuralTrust/bot-detection/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/NeuralTrust/bot-detection/actions/workflows/unit-tests.yml)

## Usage

### Basic Usage

```javascript
import { TrustGateClient } from 'trustgate-client';

// Create a new client with default options
const botDetection = new TrustGateClient();

// Collect bot detection data
const data = botDetection.collectData();
console.log(data);
```

### Wrapping an Existing HTTP Client

```javascript
import axios from 'axios';
import { TrustGateClient } from 'trustgate-client';

// Create a new client that wraps axios
const botDetection = new TrustGateClient({
  httpClient: axios,
  appendTo: 'headers' // Add data to request headers (default)
});

// Now use axios as normal, bot detection data will be automatically added
// Using async/await
const fetchData = async () => {
  try {
    const response = await axios.get('https://api.example.com/data');
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

fetchData();
```

### Using the Built-in HTTP Client

```javascript
import { TrustGateClient } from 'trustgate-client';

// Create a new client
const botDetection = new TrustGateClient({
  appendTo: 'body' // Add data to request body instead of headers
});

// Create a simple HTTP client with bot detection
const httpClient = botDetection.createHttpClient();

// Use the HTTP client with async/await
const fetchData = async () => {
  try {
    const response = await httpClient.get('https://api.example.com/data');
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

fetchData();
```

### Configuration Options

```javascript
import { TrustGateClient } from 'trustgate-client';

const botDetection = new TrustGateClient({
  // Where to append the collected data ('headers' or 'body')
  appendTo: 'headers',

  // HTTP client to wrap (optional)
  httpClient: null,

  // Enable/disable specific collectors
  collectEnvironment: true,
  collectVisualFingerprint: true,
  collectNetworkInfo: true,
  detectAutomation: true,
  checkPersistence: true
});
```

## Collected Data

The library collects the following data:

### Environment Data

- User-Agent (browser, operating system)
- Languages (navigator.language, navigator.languages)
- Timezone and offset
- Screen resolution and window size
- Color depth
- Plugins installed
- Browser feature support

### Visual Fingerprinting

- Canvas fingerprinting (rendering text, shapes, colors)
- WebGL fingerprinting (vendor, renderer, version, extensions)
- AudioContext fingerprinting (sample rate, channel count)

### Network Information

- Connection type, effective type, downlink, RTT

### Automation Detection

- navigator.webdriver check
- Chrome headless detection
- Automation tool properties (Puppeteer, Playwright, etc.)
- Inconsistency detection (resolution, timezone, etc.)

### Persistence Checks

- Cookies enabled
- LocalStorage/SessionStorage/IndexedDB support

## TypeScript Support

This library includes full TypeScript support with type definitions. You can use it in your TypeScript projects as follows:

### Basic TypeScript Usage

```typescript
import { TrustGateClient, TrustGateClientOptions } from 'trustgate-client';

// Define options with TypeScript types
const options: TrustGateClientOptions = {
  appendTo: 'headers',
  collectEnvironment: true
};

// Create a new client with typed options
const botDetection = new TrustGateClient(options);

// Collect bot detection data
const data = botDetection.collectData();

// Create a simple HTTP client with bot detection
const httpClient = botDetection.createHttpClient();

// Use the HTTP client
httpClient.get('https://api.example.com/data')
  .then(response => console.log(response.data))
  .catch(error => console.error(error));
```

### Advanced TypeScript Usage

```typescript
import { 
  TrustGateClient, 
  TrustGateClientOptions, 
  HttpClient, 
  HttpClientResponse 
} from 'trustgate-client';

// Create a client with typed options
const botDetection = new TrustGateClient({
  appendTo: 'body',
  collectVisualFingerprint: true,
  detectAutomation: true
});

// Create an HTTP client with custom headers
const httpClient: HttpClient = botDetection.createHttpClient({
  headers: {
    'Custom-Header': 'Value'
  }
});

// Use with async/await
async function fetchData(): Promise<any> {
  try {
    const response: HttpClientResponse = await httpClient.get('https://api.example.com/data');
    return response.data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}
```

### TypeScript Configuration

The library includes a `tsconfig.json` file for TypeScript configuration. If you're using this library in your TypeScript project, you can build the types with:

```bash
npm run build:types
```

You can also check the types without emitting files:

```bash
npm run check-types
```

For a complete TypeScript example, see `examples/typescript-example.ts`.

## Browser Compatibility

This library is designed for modern browsers and may not work in older browsers that don't support the required APIs.

## License

MIT