@trlogic/tracker-web/README.md

Formica Tracker Web SDK

# @trlogic/tracker-web

Formica Tracker Web SDK — browser-side fraud detection, risk scoring, and event tracking. Architecture mirrors the Android and iOS Tracker SDKs (DI container, collector pipeline, event coordinator, filter engine).

## Installation

```bash
npm install @trlogic/tracker-web
```

## Quick Start

```typescript
import { TrackerSDK, TrackerConfiguration } from "@trlogic/tracker-web";

const config: TrackerConfiguration = {
  tenant: "your-tenant",
  apiUrl: "https://your-api-url.com",
  apiKey: "your-api-key",
};

const tracker = new TrackerSDK.Builder().setConfiguration(config).build();

tracker.initialize({
  onSuccess: () => console.log("Tracker initialized"),
  onError: (error) => console.error("Init failed", error),
});
```

## Features

### Event Tracking

The SDK automatically tracks browser events via built-in listeners:

| Event Type          | Trigger                                          |
| ------------------- | ------------------------------------------------ |
| `PAGE_VIEW`         | SPA navigation (pushState/replaceState/popstate) |
| `CLICK`             | Document click events                            |
| `SCROLL`            | Window scroll events (debounced)                 |
| `VISIBILITY_CHANGE` | Tab focus/blur                                   |
| `RISK_ALERT`        | Risk score threshold exceeded                    |

### Custom Events

```typescript
// Fire-and-forget
tracker.triggerCustomEvent("checkout", { orderId: "12345", amount: 99.99 });

// With callback
tracker.triggerCustomEventSync(
  "payment",
  { method: "card" },
  {
    onSuccess: (result) => console.log("Event sent", result),
    onError: (error) => console.error("Failed", error),
  },
);
```

### User-Defined Values

```typescript
tracker.setUserDefinedValue("userId", "usr_abc123");
tracker.setUserDefinedValue("sessionType", "premium");

const values = tracker.getUserDefinedValues();
```

### Variable Collection (39+ Types)

| Category         | Variables                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Device**       | `DEVICE_FINGERPRINT`, `SCREEN_RESOLUTION`, `USER_AGENT`, `BROWSER`, `OS`, `LANGUAGE`, `TIMEZONE`, `PLATFORM`, `SDK_VERSION`                            |
| **Network**      | `IP_ADDRESS`, `REACHABLE`                                                                                                                              |
| **Risk Metrics** | `SUSPICIOUS_ACTIVITY`, `SUSPICIOUS_BROWSER`, `REMOTE_ACCESS_SCORE`, `REMOTE_ACCESS_FLAGS_JSON`, `ENVIRONMENT_CHANGE_SCORE`, `ENVIRONMENT_CHANGE_FLAGS` |
| **Behavior**     | `NO_MOUSE_MOVE_DURATION_MS`, `CLICK_ONLY_PATTERN`, `FAST_PAGE_TRANSITION`, `NAVIGATION_VELOCITY`, `FORM_FILL_ANOMALY`, `INPUT_PASTE_RATIO`             |
| **Detection**    | `HEADLESS_INDICATOR_COUNT`, `REDIRECT_DETECTED`                                                                                                        |
| **Screen**       | `VIEW_DURATION`, `URL`, `ELEMENT`, `COOKIE`, `JAVASCRIPT`, `EVENT`                                                                                     |

### Risk Scoring

The `SecurityCollector` computes a composite remote access score (0–1) from:

- Unnatural mouse movement patterns
- Clipboard paste anomalies
- Low FPS detection (screen sharing/remote control)
- Click-only patterns (no mouse movement)
- Headless browser indicators (WebGL, plugins, webdriver)
- Environment change detection (language/timezone/OS/browser drift)
- Form fill timing anomalies

## Configuration

```typescript
const config: TrackerConfiguration = {
  tenant: "your-tenant",
  apiUrl: "https://api.example.com",
  apiKey: "your-api-key",
  timeout: 10000, // HTTP timeout (ms), default: 10000
  queueProcessInterval: 5000, // Event queue drain interval (ms), default: 5000
};
```

## Bundle Formats

| Format | File                    | Use Case                                     |
| ------ | ----------------------- | -------------------------------------------- |
| ESM    | `dist/index.esm.min.js` | Modern bundlers (Vite, Webpack 5, Rollup)    |
| UMD    | `dist/index.umd.min.js` | Universal (Node.js + browser)                |
| AMD    | `dist/index.amd.js`     | RequireJS                                    |
| IIFE   | `dist/index.js`         | `<script>` tag (exposes `TrackerWeb` global) |
| CJS    | `dist/bundle.js`        | Legacy Node.js / CommonJS                    |

### Script Tag Usage

```html
<script src="dist/index.js"></script>
<script>
  const { TrackerSDK } = TrackerWeb;
  const tracker = new TrackerSDK.Builder()
    .setConfiguration({ tenant: "t", apiUrl: "https://...", apiKey: "k" })
    .build();
  tracker.initialize();
</script>
```

## Architecture

```
src/
├── core/
│   ├── model/          # TrackerEventType, TrackerVariableType, FilterOperator, etc.
│   ├── contract/       # DataCollector, EventStorage, NetworkService interfaces
│   ├── engine/         # FilterEngine, EventCoordinator, TrackerEngine
│   ├── base/           # BaseDataCollector, CachedDataCollector
│   └── scheduler/      # PeriodicDataScheduler
├── collector/          # DeviceCollector, NetworkCollector, SecurityCollector, ScreenActivityCollector
├── listener/           # PageViewListener, ClickListener, ScrollListener, VisibilityListener
├── service/            # InMemoryEventStorage, DefaultNetworkService, EventService
├── di/                 # DataPayload, TrackerModule (DI container)
├── util/               # Logger, HttpClient, BrowserDetector, FilterUtil
├── tracker.ts          # TrackerSDK (public API with Builder pattern)
└── index.ts            # Barrel exports
```

## Development

```bash
# Install dependencies
npm install

# Build all formats
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format code
npm run format

# Check formatting
npm run format:check

# Clean build artifacts
npm run clean
```

## Testing with Tracker CLI

Start the local test server:

```bash
# In the tracker CLI project
./tracker server -p 8000

# Web SDK config is served at:
# GET http://localhost:8000/sentinel/v1
# Headers: api-key, tenant, platform: web
```

Then use the example app:

```bash
cd example
npm install
npm start
# Open http://localhost:3000
```

## Browser Support

- Chrome 80+
- Firefox 78+
- Safari 14+
- Edge 80+

## License

This project is licensed under the terms specified in the LICENSE file.