@ianmenethil/zp-devicefp 0.1.0 → 0.2.0

package/docs/api-reference.md

@@ -1,472 +1,520 @@
-# API Reference
-
-Complete reference for `@ianmenethil/zp-devicefp` — every type, method, option, event, and export.
-
----
-
-## Exports
-
-| Export | Kind | Description |
-|--------|------|-------------|
-| `createFingerprintClient` | function | Async factory that returns a configured `FingerprintClient` |
-| `LIBRARY_VERSION` | `string` | Semantic version of the library (e.g. `"0.1.0"`) |
-| `SCHEMA_VERSION` | `number` | Schema version for the result shape (integer, bumped on breaking changes) |
-
----
-
-## `createFingerprintClient(options?)`
-
-Factory function. Returns `Promise<FingerprintClient>`.
-
-```ts
-import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
-
-const client = await createFingerprintClient({
-	timeoutMs: 1500,
-	extended: false,
-	debug: false,
-});
-```
-
-### Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `options` | `CollectOptions` | `{}` | Configuration overrides applied to all subsequent `collect()` / `collectSync()` calls. Can be overridden per-call. |
-
----
-
-## `CollectOptions`
-
-```ts
-interface CollectOptions {
-	include?: SignalName[];
-	exclude?: SignalName[];
-	timeoutMs?: number;
-	abortSignal?: AbortSignal;
-	extended?: boolean;
-	debug?: boolean;
-}
-```
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `include` | `SignalName[]` | undefined | Whitelist of signals to collect. When set, only these signals run. |
-| `exclude` | `SignalName[]` | undefined | Blacklist of signals to skip. |
-| `timeoutMs` | `number` | `1500` | Per-signal timeout in milliseconds. Signals exceeding this return `status: 'timeout'`. |
-| `abortSignal` | `AbortSignal` | undefined | Pass an `AbortController.signal` to cancel in-flight collection. Aborted signals return `status: 'error'`. |
-| `extended` | `boolean` | `false` | When `true`, includes extended-tier signals in the collection. |
-| `debug` | `boolean` | `false` | Enable debug logging (passed to signal collectors via context). |
-
-### Signal resolution order
-
-1. Start with core signals (`ua`, `uaHints`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `audio`).
-2. If `extended: true`, add all 9 extended signals.
-3. In `collectSync()` mode, remove signals without `supportsSync: true`.
-4. If `include` is set, keep only signals present in the list.
-5. Remove any signals listed in `exclude`.
-
----
-
-## `FingerprintClient`
-
-The object returned by `createFingerprintClient()`.
-
-```ts
-interface FingerprintClient {
-	collect(options?: CollectOptions): Promise<FingerprintResult>;
-	collectSync(options?: Omit<CollectOptions, 'timeoutMs' | 'abortSignal'>): FingerprintResult;
-	upload(result: FingerprintResult, options: UploadOptions): Promise<Response>;
-	on<K extends keyof EventPayloadMap>(event: K, cb: (payload: EventPayloadMap[K]) => void): () => void;
-}
-```
-
-### `client.collect(options?)`
-
-Collects signals asynchronously. All signals run in parallel with per-signal timeouts. Emits `progress`, `warning`, and `complete` events.
-
-```ts
-const result = await client.collect({ extended: true, timeoutMs: 3000 });
-console.log(result.thumbprint);
-console.log(result.confidence);
-```
-
-- **Returns**: `Promise<FingerprintResult>`
-- **Events emitted**: `progress` (per signal), `warning` (on non-fatal issues), `complete` (once, with final result)
-
-### `client.collectSync(options?)`
-
-Collects signals synchronously. Only signals with `supportsSync: true` will run. Timeout and abort are not supported — the `timeoutMs` and `abortSignal` fields are excluded from the options type.
-
-```ts
-const result = client.collectSync();
-console.log(result.thumbprint);
-```
-
-- **Returns**: `FingerprintResult`
-- **Sync-capable signals** (13): `ua`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `frameInfo`, `networkInfo`, `paymentSupport`, `referrerInfo`, `navigationInfo`
-- **NOT sync-capable** (6): `uaHints`, `audio`, `mediaDevices`, `permissions`, `webrtc`, `riskSignals`
-
-### `client.upload(result, options)`
-
-Posts a fingerprint result to a remote endpoint via HTTP POST.
-
-```ts
-const response = await client.upload(result, {
-	endpoint: 'https://api.example.com/fingerprint',
-	headers: { 'Authorization': 'Bearer token' },
-	bodyExtras: { sessionId: 'abc123' },
-});
-```
-
-Payload shape:
-```json
-{
-	"fingerprint": { /* full FingerprintResult */ },
-	"...bodyExtras keys..."
-}
-```
-
-- **Returns**: `Promise<Response>` — native `fetch` Response
-- **Throws**: if `fetch` is not available in the runtime
-
-### `client.on(event, callback)`
-
-Subscribe to lifecycle events during async collection.
-
-```ts
-const unsubscribe = client.on('progress', (event) => {
-	console.log(`${event.completed}/${event.total}: ${event.signal}`);
-});
-
-// Later, remove the listener:
-unsubscribe();
-```
-
-- **Returns**: `() => void` — call to unsubscribe
-
----
-
-## Events
-
-| Event | Payload Type | When Emitted |
-|-------|-------------|--------------|
-| `progress` | `ProgressEvent` | After each signal completes during `collect()` |
-| `warning` | `WarningEvent` | When a non-fatal issue occurs (unsupported signal, blocked API, etc.) |
-| `complete` | `CompleteEvent` | After all signals finish in `collect()` |
-
-### `ProgressEvent`
-
-```ts
-interface ProgressEvent {
-	completed: number;  // signals completed so far
-	total: number;      // total signals requested
-	signal: SignalName; // name of the signal that just completed
-	result: SignalResult; // the signal's collection result
-}
-```
-
-### `WarningEvent`
-
-```ts
-interface WarningEvent {
-	signal?: SignalName;  // which signal triggered the warning, if applicable
-	message: string;       // human-readable warning message
-}
-```
-
-### `CompleteEvent`
-
-```ts
-interface CompleteEvent {
-	result: FingerprintResult; // the completed fingerprint result
-}
-```
-
----
-
-## `FingerprintResult`
-
-The complete output of `collect()` or `collectSync()`.
-
-```ts
-interface FingerprintResult {
-	schemaVersion: number;
-	libraryVersion: string;
-	thumbprint: string;
-	confidence: number;
-	componentHashes: Partial<Record<SignalName, string>>;
-	signals: Partial<Record<SignalName, SignalResult>>;
-	antiSpoof: AntiSpoofReport;
-	warnings: string[];
-	diagnostics: CollectorDiagnostics;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `schemaVersion` | `number` | Schema version (currently `1`). Bumped on breaking result shape changes. |
-| `libraryVersion` | `string` | Library version that produced this result (e.g. `"0.1.0"`). |
-| `thumbprint` | `string` | SHA-256 hash of all component hashes combined. The primary fingerprint identifier. |
-| `confidence` | `number` | 0–1 score. 0 = unreliable, 1 = high confidence. Weighted average of signal quality blended with anti-spoof score. |
-| `componentHashes` | `Partial<Record<SignalName, string>>` | Per-signal SHA-256 hashes of canonicalized signal values. Only present for signals that returned `value`. |
-| `signals` | `Partial<Record<SignalName, SignalResult>>` | Raw signal collection results, keyed by signal name. |
-| `antiSpoof` | `AntiSpoofReport` | Cross-signal coherence analysis and automation detection. |
-| `warnings` | `string[]` | Non-fatal warnings from the collection run. |
-| `diagnostics` | `CollectorDiagnostics` | Metadata about what ran and how long it took. |
-
-### Thumbprint derivation
-
-1. Each signal value is canonicalized (deterministic JSON serialization with sorted keys, normalized numbers, ISO dates).
-2. Each canonicalized value is hashed with SHA-256 → `componentHashes`.
-3. Component hashes are sorted by name, serialized as `[[name, hash], ...]`, canonicalized, and hashed once more → `thumbprint`.
-
----
-
-## `SignalResult`
-
-The result of collecting a single signal.
-
-```ts
-interface SignalResult<T = unknown> {
-	status: 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
-	value?: T;
-	durationMs: number;
-	error?: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `status` | `SignalStatus` | Outcome of the collection attempt. |
-| `value` | `T` (optional) | The collected signal data. Only present when `status` is `'ok'`. |
-| `durationMs` | `number` | Wall-clock milliseconds spent collecting this signal. |
-| `error` | `string` (optional) | Human-readable error description. Present when status is not `'ok'`. |
-
-### `SignalStatus`
-
-```ts
-type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
-```
-
-| Value | Meaning |
-|-------|---------|
-| `ok` | Signal collected successfully. `value` is populated. |
-| `unsupported` | The required browser API is not available. |
-| `blocked` | The API exists but access was denied (e.g. permissions, secure context). |
-| `timeout` | Collection exceeded the per-signal timeout. |
-| `error` | An unexpected error occurred during collection. |
-
----
-
-## `AntiSpoofReport`
-
-Cross-signal coherence analysis.
-
-```ts
-interface AntiSpoofReport {
-	score: number;
-	anomalies: string[];
-	automationHints: string[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `score` | `number` | Normalized score 0–1. 0 = automated/bot, 1 = genuine user. Each anomaly deducts 0.12; each automation hint deducts 0.18. Floor at 0, ceiling at 1. |
-| `anomalies` | `string[]` | Specific inconsistencies found between signals. |
-| `automationHints` | `string[]` | Indicators of headless, automated, or bot environments. |
-
-### Anomaly codes
-
-| Code | Trigger |
-|------|---------|
-| `ua_platform_mismatch` | `navigator.platform` contradicts UA Client Hints platform |
-| `touch_claim_without_touch_points` | iPhone UA but `maxTouchPoints` is 0 |
-| `mobile_ua_desktop_screen` | Android UA but screen width >= 1600px |
-| `windows_ua_mac_platform` | Windows UA string but platform reports macOS |
-| `implausible_device_memory` | `deviceMemory` < 0.25 or > 64 GB |
-| `tiny_screen_geometry` | Screen width and height both < 200px |
-
-### Automation hint codes
-
-| Code | Trigger |
-|------|---------|
-| `navigator_webdriver` | `navigator.webdriver` is truthy |
-| `headless_user_agent` | UA string contains `"headless"` |
-
----
-
-## `CollectorDiagnostics`
-
-```ts
-interface CollectorDiagnostics {
-	requestedSignals: SignalName[];
-	completedSignals: SignalName[];
-	elapsedMs: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `requestedSignals` | `SignalName[]` | Signals requested for the run (after include/exclude/mode resolution). |
-| `completedSignals` | `SignalName[]` | Signals that produced a result (any status). Sorted alphabetically. |
-| `elapsedMs` | `number` | Total wall-clock milliseconds for the entire run (rounded to 3 decimal places). |
-
----
-
-## `UploadOptions`
-
-```ts
-interface UploadOptions {
-	endpoint: string;
-	headers?: Record<string, string>;
-	bodyExtras?: Record<string, unknown>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `endpoint` | `string` | URL to POST the fingerprint payload to. |
-| `headers` | `Record<string, string>` | Additional HTTP headers merged with `content-type: application/json`. |
-| `bodyExtras` | `Record<string, unknown>` | Extra properties merged into the JSON body alongside `fingerprint`. |
-
----
-
-## Confidence scoring
-
-Each signal has a fixed weight. The base confidence is the weighted ratio of earned points to available points.
-
-### Signal weights
-
-| Signal | Weight | Signal | Weight |
-|--------|--------|--------|--------|
-| `canvas` | 1.0 | `audio` | 0.9 |
-| `webgl` | 1.0 | `fonts` | 0.9 |
-| `screen` | 0.8 | `webrtc` | 0.8 |
-| `uaHints` | 0.7 | `hardware` | 0.7 |
-| `riskSignals` | 0.7 | `mediaDevices` | 0.6 |
-| `networkInfo` | 0.6 | `ua` | 0.5 |
-| `locale` | 0.5 | `storage` | 0.4 |
-| `permissions` | 0.4 | `navigationInfo` | 0.4 |
-| `frameInfo` | 0.3 | `referrerInfo` | 0.3 |
-| `paymentSupport` | 0.2 | | |
-
-### Points per status
-
-| Status | Points earned |
-|--------|---------------|
-| `ok` | Full weight |
-| `unsupported` | 35% of weight |
-| `blocked` | 35% of weight |
-| `timeout` | 15% of weight |
-| `error` | 0% |
-
-### Final score
-
-```
-base = earned / available
-final = base * (0.65 + antiSpoofScore * 0.35)
-```
-
-The anti-spoof score blends 35% into the final confidence, meaning a low anti-spoof score drags confidence down proportionally.
-
----
-
-## Internal constants
-
-These values are used internally to configure the library. They are not public exports but are documented here for reference.
-
-| Constant | Type | Value |
-|----------|------|-------|
-| `CORE_SIGNALS` | `SignalName[]` | `['ua', 'uaHints', 'locale', 'screen', 'hardware', 'storage', 'fonts', 'canvas', 'webgl', 'audio']` |
-| `EXTENDED_SIGNALS` | `SignalName[]` | `['mediaDevices', 'permissions', 'webrtc', 'frameInfo', 'networkInfo', 'paymentSupport', 'referrerInfo', 'navigationInfo', 'riskSignals']` |
-| `SYNC_SIGNALS` | `SignalName[]` | `['ua', 'locale', 'screen', 'hardware', 'storage', 'fonts', 'canvas', 'webgl', 'frameInfo', 'networkInfo', 'paymentSupport', 'referrerInfo', 'navigationInfo']` |
-| `DEFAULT_TIMEOUT_MS` | `number` | `1500` |
-| `DEFAULT_FONT_LIST` | `string[]` | `['Arial', 'Helvetica Neue', 'Times New Roman', 'Georgia', 'Courier New', 'Trebuchet MS', 'Verdana', 'Tahoma', 'Impact', 'Comic Sans MS']` |
-| `DEFAULT_PERMISSION_NAMES` | `readonly string[]` | `['geolocation', 'notifications', 'camera', 'microphone']` |
-| `DEFAULT_UA_HINTS` | `readonly string[]` | `['architecture', 'bitness', 'formFactors', 'fullVersionList', 'model', 'platform', 'platformVersion', 'wow64']` |
-
----
-
-## CDN / IIFE API
-
-When loaded via `<script>` tag, the library attaches to `window.DeviceFP`.
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.min.js"></script>
-<script>
-	const client = await window.DeviceFP.createFingerprintClient({ timeoutMs: 1500 });
-	const result = await client.collect();
-	console.log(window.DeviceFP.LIBRARY_VERSION);
-	console.log(window.DeviceFP.SCHEMA_VERSION);
-</script>
-```
-
-### `window.DeviceFP` shape
-
-| Property | Type |
-|----------|------|
-| `createFingerprintClient` | `(options?: CollectOptions) => Promise<FingerprintClient>` |
-| `LIBRARY_VERSION` | `string` |
-| `SCHEMA_VERSION` | `number` |
-
-### CDN files
-
-| File | Format | Description |
-|------|--------|-------------|
-| `zp.dfp.js` | IIFE | Unminified global bundle |
-| `zp.dfp.min.js` | IIFE | Minified global bundle |
-| `zp.dfp.obf.js` | IIFE | Minified + obfuscated global bundle |
-| `zp.dfp.esm.js` | ESM | Module for `import()` / `<script type="module">` |
-| `zp.dfp.manifest.json` | JSON | SRI integrity hashes for all CDN files |
-
-### CDN sources
-
-| Source | Base URL |
-|--------|----------|
-| jsDelivr | `https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/` |
-| Self-hosted | `https://cdn.zenithpayments.support/devicefp/latest/` |
-
----
-
-## NPM package layout
-
-```text
-@ianmenethil/zp-devicefp/
-├── dist/npm/
-│   ├── index.mjs       # ESM entry (browser, ES2022)
-│   ├── index.cjs       # CJS entry (Node 22+)
-│   └── index.d.ts      # Public type declarations
-├── dist/cdn/
-│   ├── zp.dfp.js       # IIFE (unminified)
-│   ├── zp.dfp.min.js   # IIFE (minified)
-│   ├── zp.dfp.obf.js   # IIFE (minified + obfuscated)
-│   ├── zp.dfp.esm.js   # ESM for import()
-│   └── zp.dfp.manifest.json
-```
-
----
-
-## NPM usage
-
-```bash
-bun add @ianmenethil/zp-devicefp
-```
-
-```ts
-import {
-	createFingerprintClient,
-	LIBRARY_VERSION,
-	SCHEMA_VERSION,
-} from '@ianmenethil/zp-devicefp';
-
-const client = await createFingerprintClient({ timeoutMs: 2000 });
-const result = await client.collect({ extended: true });
-
-// Upload to your backend
-await client.upload(result, {
-	endpoint: '/api/fingerprint',
-	bodyExtras: { userId: 'u_123' },
-});
-```
+# API Reference
+
+Complete reference for `@ianmenethil/zp-devicefp` — every type, method, option, event, and export.
+
+---
+
+## Exports
+
+### Functions
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `createFingerprintClient` | `(options?: CollectOptions) => Promise<FingerprintClient>` | Async factory that returns a configured `FingerprintClient` |
+
+### Constants
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `LIBRARY_VERSION` | `string` | Semantic version of the library (e.g. `"0.1.1"`) |
+| `SCHEMA_VERSION` | `number` | Schema version for the result shape (integer, bumped on breaking changes) |
+| `CORE_SIGNALS` | `SignalName[]` | The 10 signals collected by default |
+| `EXTENDED_SIGNALS` | `SignalName[]` | The 11 signals requiring `extended: true` |
+| `SYNC_SIGNALS` | `SignalName[]` | The 13 signals that support `collectSync()` |
+| `DEFAULT_TIMEOUT_MS` | `number` | Default per-signal timeout: `1500` |
+| `DEFAULT_FONT_LIST` | `string[]` | The 70 font faces probed during font detection (Fingerprint2 / Cardinal Commerce set) |
+| `DEFAULT_PERMISSION_NAMES` | `readonly string[]` | The 4 permission names queried by the permissions signal |
+| `DEFAULT_UA_HINTS` | `readonly string[]` | The 8 high-entropy UA-CH hints requested |
+
+---
+
+## `createFingerprintClient(options?)`
+
+Factory function. Returns `Promise<FingerprintClient>`.
+
+```ts
+import { createFingerprintClient } from '@ianmenethil/zp-devicefp';
+
+const client = await createFingerprintClient({
+	timeoutMs: 1500,
+	extended: false,
+	debug: false,
+});
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options` | `CollectOptions` | `{}` | Configuration overrides applied to all subsequent `collect()` / `collectSync()` calls. Can be overridden per-call. |
+
+---
+
+## `CollectOptions`
+
+```ts
+interface CollectOptions {
+	include?: SignalName[];
+	exclude?: SignalName[];
+	timeoutMs?: number;
+	abortSignal?: AbortSignal;
+	extended?: boolean;
+	debug?: boolean;
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `include` | `SignalName[]` | undefined | Whitelist of signals to collect. When set, only these signals run. |
+| `exclude` | `SignalName[]` | undefined | Blacklist of signals to skip. |
+| `timeoutMs` | `number` | `1500` | Per-signal timeout in milliseconds. Signals exceeding this return `status: 'timeout'`. |
+| `abortSignal` | `AbortSignal` | undefined | Pass an `AbortController.signal` to cancel in-flight collection. Aborted signals return `status: 'error'`. |
+| `extended` | `boolean` | `false` | When `true`, includes extended-tier signals in the collection. |
+| `debug` | `boolean` | `false` | Enable debug logging (passed to signal collectors via context). |
+
+### Signal resolution order
+
+1. Start with core signals (`ua`, `uaHints`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `audio`).
+2. If `extended: true`, add all 11 extended signals.
+3. In `collectSync()` mode, remove signals not in the `SYNC_SIGNALS` set.
+4. If `include` is set, keep only signals present in the list.
+5. Remove any signals listed in `exclude`.
+
+---
+
+## `FingerprintClient`
+
+The object returned by `createFingerprintClient()`.
+
+```ts
+interface FingerprintClient {
+	collect(options?: CollectOptions): Promise<FingerprintResult>;
+	collectSync(options?: Omit<CollectOptions, 'timeoutMs' | 'abortSignal'>): FingerprintResult;
+	on<K extends keyof EventPayloadMap>(event: K, cb: (payload: EventPayloadMap[K]) => void): () => void;
+}
+```
+
+### `client.collect(options?)`
+
+Collects signals asynchronously. All signals run in parallel with per-signal timeouts. Emits `progress`, `warning`, and `complete` events.
+
+```ts
+const result = await client.collect({ extended: true, timeoutMs: 3000 });
+console.log(result.thumbprint);
+console.log(result.confidence);
+```
+
+- **Returns**: `Promise<FingerprintResult>`
+- **Events emitted**: `progress` (per signal), `warning` (on non-fatal issues), `complete` (once, with final result)
+
+### `client.collectSync(options?)`
+
+Collects signals synchronously. Only signals in the `SYNC_SIGNALS` set will run. Timeout and abort are not supported — the `timeoutMs` and `abortSignal` fields are excluded from the options type.
+
+```ts
+const result = client.collectSync();
+console.log(result.thumbprint);
+```
+
+- **Returns**: `FingerprintResult`
+- **Sync-capable signals** (13): `ua`, `locale`, `screen`, `hardware`, `storage`, `fonts`, `canvas`, `webgl`, `frameInfo`, `networkInfo`, `paymentSupport`, `referrerInfo`, `navigationInfo`
+- **NOT sync-capable** (8): `uaHints`, `audio`, `mediaDevices`, `permissions`, `webrtc`, `riskSignals`, `adblock`, `geolocation`
+
+### `client.on(event, callback)`
+
+Subscribe to lifecycle events during async collection.
+
+```ts
+const unsubscribe = client.on('progress', (event) => {
+	console.log(`${event.completed}/${event.total}: ${event.signal}`);
+});
+
+// Later, remove the listener:
+unsubscribe();
+```
+
+- **Returns**: `() => void` — call to unsubscribe
+
+---
+
+## Events
+
+| Event | Payload Type | When Emitted |
+|-------|-------------|--------------|
+| `progress` | `ProgressEvent` | After each signal completes during `collect()` |
+| `warning` | `WarningEvent` | When a non-fatal issue occurs (unsupported signal, blocked API, etc.) |
+| `complete` | `CompleteEvent` | After all signals finish in `collect()` |
+
+### `ProgressEvent`
+
+```ts
+interface ProgressEvent {
+	completed: number;  // signals completed so far
+	total: number;      // total signals requested
+	signal: SignalName; // name of the signal that just completed
+	result: SignalResult; // the signal's collection result
+}
+```
+
+### `WarningEvent`
+
+```ts
+interface WarningEvent {
+	signal?: SignalName;  // which signal triggered the warning, if applicable
+	message: string;       // human-readable warning message
+}
+```
+
+### `CompleteEvent`
+
+```ts
+interface CompleteEvent {
+	result: FingerprintResult; // the completed fingerprint result
+}
+```
+
+---
+
+## `FingerprintResult`
+
+The complete output of `collect()` or `collectSync()`.
+
+```ts
+interface FingerprintResult {
+	schemaVersion: number;
+	libraryVersion: string;
+	thumbprint: string;
+	confidence: number;
+	componentHashes: Partial<Record<SignalName, string>>;
+	signals: Partial<Record<SignalName, SignalResult>>;
+	antiSpoof: AntiSpoofReport;
+	warnings: string[];
+	diagnostics: CollectorDiagnostics;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schemaVersion` | `number` | Schema version (currently `2`). Bumped on breaking result shape changes. |
+| `libraryVersion` | `string` | Library version that produced this result (e.g. `"0.1.1"`). |
+| `thumbprint` | `string` | SHA-256 hash of all component hashes combined. The primary fingerprint identifier. |
+| `confidence` | `number` | 0–1 score. 0 = unreliable, 1 = high confidence. Weighted average of signal quality blended with anti-spoof score. |
+| `componentHashes` | `Partial<Record<SignalName, string>>` | Per-signal SHA-256 hashes of canonicalized signal values. Only present for signals that returned `value`. |
+| `signals` | `Partial<Record<SignalName, SignalResult>>` | Raw signal collection results, keyed by signal name. |
+| `antiSpoof` | `AntiSpoofReport` | Cross-signal coherence analysis and automation detection. |
+| `warnings` | `string[]` | Non-fatal warnings from the collection run. |
+| `diagnostics` | `CollectorDiagnostics` | Metadata about what ran and how long it took. |
+
+### Thumbprint derivation
+
+1. Each signal value is canonicalized (deterministic JSON serialization with sorted keys, normalized numbers, ISO dates).
+2. Each canonicalized value is hashed with SHA-256 → `componentHashes`.
+3. Component hashes are sorted by name, serialized as `[[name, hash], ...]`, canonicalized, and hashed once more → `thumbprint`.
+
+---
+
+## `SignalResult`
+
+The result of collecting a single signal.
+
+```ts
+interface SignalResult<T = unknown> {
+	status: 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
+	value?: T;
+	durationMs: number;
+	error?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `SignalStatus` | Outcome of the collection attempt. |
+| `value` | `T` (optional) | The collected signal data. Only present when `status` is `'ok'`. |
+| `durationMs` | `number` | Wall-clock milliseconds spent collecting this signal. |
+| `error` | `string` (optional) | Human-readable error description. Present when status is not `'ok'`. |
+
+### `SignalStatus`
+
+```ts
+type SignalStatus = 'ok' | 'unsupported' | 'blocked' | 'timeout' | 'error';
+```
+
+| Value | Meaning |
+|-------|---------|
+| `ok` | Signal collected successfully. `value` is populated. |
+| `unsupported` | The required browser API is not available. |
+| `blocked` | The API exists but access was denied (e.g. permissions, secure context). |
+| `timeout` | Collection exceeded the per-signal timeout. |
+| `error` | An unexpected error occurred during collection. |
+
+---
+
+## `AntiSpoofReport`
+
+Cross-signal coherence analysis.
+
+```ts
+interface AntiSpoofReport {
+	score: number;
+	anomalies: string[];
+	automationHints: string[];
+	fakedOS: boolean;
+	fakedBrowser: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `score` | `number` | Normalized score 0–1. 0 = automated/bot, 1 = genuine user. Each anomaly deducts 0.12; each automation hint deducts 0.18. Floor at 0, ceiling at 1. |
+| `anomalies` | `string[]` | Specific inconsistencies found between signals. |
+| `automationHints` | `string[]` | Indicators of headless, automated, or bot environments. |
+| `fakedOS` | `boolean` | `true` when `ua_platform_mismatch` is in `anomalies` — the UA string's OS contradicts `navigator.platform`. |
+| `fakedBrowser` | `boolean` | `true` when the UA claims a browser whose characteristic globals are missing (requires `riskSignals` to be collected). |
+
+### Anomaly codes
+
+| Code | Trigger |
+|------|---------|
+| `ua_platform_mismatch` | `navigator.platform` contradicts UA Client Hints platform |
+| `touch_claim_without_touch_points` | iPhone UA but `maxTouchPoints` is 0 |
+| `mobile_ua_desktop_screen` | Android UA but screen width >= 1600px |
+| `windows_ua_mac_platform` | Windows UA string but platform reports macOS |
+| `implausible_device_memory` | `deviceMemory` < 0.25 or > 64 GB |
+| `tiny_screen_geometry` | Screen width and height both < 200px |
+
+### Automation hint codes
+
+| Code | Trigger |
+|------|---------|
+| `navigator_webdriver` | `navigator.webdriver` is truthy |
+| `headless_user_agent` | UA string contains `"headless"` |
+
+---
+
+## `CollectorDiagnostics`
+
+```ts
+interface CollectorDiagnostics {
+	requestedSignals: SignalName[];
+	completedSignals: SignalName[];
+	elapsedMs: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `requestedSignals` | `SignalName[]` | Signals requested for the run (after include/exclude/mode resolution). |
+| `completedSignals` | `SignalName[]` | Signals that produced a result (any status). Sorted alphabetically. |
+| `elapsedMs` | `number` | Total wall-clock milliseconds for the entire run (rounded to 3 decimal places). |
+
+---
+
+---
+
+## Confidence scoring
+
+Each signal has a fixed weight. The base confidence is the weighted ratio of earned points to available points.
+
+### Signal weights
+
+| Signal | Weight | Signal | Weight |
+|--------|--------|--------|--------|
+| `canvas` | 1.0 | `audio` | 0.9 |
+| `webgl` | 1.0 | `fonts` | 0.9 |
+| `screen` | 0.8 | `webrtc` | 0.8 |
+| `uaHints` | 0.7 | `hardware` | 0.7 |
+| `riskSignals` | 0.7 | `mediaDevices` | 0.6 |
+| `networkInfo` | 0.6 | `ua` | 0.5 |
+| `locale` | 0.5 | `storage` | 0.4 |
+| `permissions` | 0.4 | `navigationInfo` | 0.4 |
+| `frameInfo` | 0.3 | `referrerInfo` | 0.3 |
+| `paymentSupport` | 0.2 | | |
+
+### Points per status
+
+| Status | Points earned |
+|--------|---------------|
+| `ok` | Full weight |
+| `unsupported` | 35% of weight |
+| `blocked` | 35% of weight |
+| `timeout` | 15% of weight |
+| `error` | 0% |
+
+### Final score
+
+```
+base = earned / available
+final = base * (0.65 + antiSpoofScore * 0.35)
+```
+
+The anti-spoof score blends 35% into the final confidence, meaning a low anti-spoof score drags confidence down proportionally.
+
+---
+
+## Source constants
+
+These values are exported from `src/constants.ts` and re-exported from the package entry point (`src/index.ts`). Import them directly:
+
+```ts
+import {
+  CORE_SIGNALS,
+  EXTENDED_SIGNALS,
+  SYNC_SIGNALS,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_FONT_LIST,
+  DEFAULT_PERMISSION_NAMES,
+  DEFAULT_UA_HINTS,
+} from '@ianmenethil/zp-devicefp';
+```
+
+| Constant | Type | Value |
+|----------|------|-------|
+| `CORE_SIGNALS` | `SignalName[]` | `['ua', 'uaHints', 'locale', 'screen', 'hardware', 'storage', 'fonts', 'canvas', 'webgl', 'audio']` |
+| `EXTENDED_SIGNALS` | `SignalName[]` | `['mediaDevices', 'permissions', 'webrtc', 'frameInfo', 'networkInfo', 'paymentSupport', 'referrerInfo', 'navigationInfo', 'riskSignals', 'adblock', 'geolocation']` |
+| `SYNC_SIGNALS` | `SignalName[]` | `['ua', 'locale', 'screen', 'hardware', 'storage', 'fonts', 'canvas', 'webgl', 'frameInfo', 'networkInfo', 'paymentSupport', 'referrerInfo', 'navigationInfo']` |
+| `DEFAULT_TIMEOUT_MS` | `number` | `1500` |
+| `DEFAULT_FONT_LIST` | `string[]` | 70 font faces — Fingerprint2 / Cardinal Commerce set (Andale Mono, Arial, Baskerville, Calibri, Comic Sans MS, Consolas, Courier New, Georgia, Helvetica, Impact, Times New Roman, Verdana, Wingdings, and 57 more) |
+| `DEFAULT_PERMISSION_NAMES` | `readonly string[]` | `['geolocation', 'notifications', 'camera', 'microphone']` |
+| `DEFAULT_UA_HINTS` | `readonly string[]` | `['architecture', 'bitness', 'formFactors', 'fullVersionList', 'model', 'platform', 'platformVersion', 'wow64']` |
+
+---
+
+## CDN / IIFE API
+
+When loaded via `<script>` tag, the library attaches to `window.DeviceFP`.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/zp.dfp.min.js"></script>
+<script>
+	const client = await window.DeviceFP.createFingerprintClient({ timeoutMs: 1500 });
+	const result = await client.collect();
+	console.log(window.DeviceFP.LIBRARY_VERSION);
+	console.log(window.DeviceFP.SCHEMA_VERSION);
+</script>
+```
+
+### `window.DeviceFP` shape
+
+| Property | Type |
+|----------|------|
+| `createFingerprintClient` | `(options?: CollectOptions) => Promise<FingerprintClient>` |
+| `LIBRARY_VERSION` | `string` |
+| `SCHEMA_VERSION` | `number` |
+
+### CDN files
+
+| File | Format | Description |
+|------|--------|-------------|
+| `zp.dfp.js` | IIFE | Unminified global bundle |
+| `zp.dfp.min.js` | IIFE | Minified global bundle |
+| `zp.dfp.obf.js` | IIFE | Minified + obfuscated global bundle |
+| `zp.dfp.esm.js` | ESM | Module for `import()` / `<script type="module">` |
+| `zp.dfp.manifest.json` | JSON | SRI integrity hashes for all CDN files |
+
+### CDN sources
+
+| Source | Base URL |
+|--------|----------|
+| jsDelivr | `https://cdn.jsdelivr.net/npm/@ianmenethil/zp-devicefp/dist/cdn/` |
+| Self-hosted | `https://cdn.zenithpayments.support/devicefp/` |
+
+---
+
+## Error handling
+
+Every signal result includes an explicit `status` field. The library never swallows errors silently — each signal that fails reports its outcome and, where applicable, an error message.
+
+### Signal-level errors
+
+Each `SignalResult.status` can be one of:
+
+| Status | Meaning | `value` | `error` |
+|--------|---------|---------|---------|
+| `ok` | Collected successfully | Present | Absent |
+| `unsupported` | Required browser API not available | Absent | Present |
+| `blocked` | API exists but access denied (permissions, secure context) | Absent | Present |
+| `timeout` | Collection exceeded `timeoutMs` | Absent | `"Signal collection timed out."` |
+| `error` | Unexpected error during collection | Absent | Present |
+
+### Aborted collections
+
+When an `AbortSignal` fires before or during collection:
+
+- Signals not yet started return `status: 'error'` with `error: 'Collection aborted before signal execution started.'`.
+- In-flight signals return `status: 'error'` with `error: 'Collection aborted.'`.
+
+The `collect()` promise still resolves — the abort does not reject. Aborted/missing signals appear in `signals` with `status: 'error'` like any other failure.
+
+### Warnings
+
+Non-fatal issues during collection (e.g., a signal API is unavailable, a signal has no collector registered) are reported via:
+
+- The `warnings` array in `FingerprintResult` (accumulated across the run).
+- The `warning` event on the event emitter (emitted in real-time during `collect()`).
+
+---
+
+## Extension and customization
+
+The library does not currently expose a public extension API for registering custom signal collectors. The `SignalCollector` interface and `collectorMap` exist internally (`src/types/internal.ts`, `src/signals/index.ts`) but are not re-exported from the package entry point.
+
+To extend the library, the supported approach is:
+
+- **Include/exclude signals** via `CollectOptions.include` and `CollectOptions.exclude` to control which of the 21 built-in signals are collected.
+- **Set `extended: true`** to add the 11 extended-tier signals to a collection run.
+- **Adjust `timeoutMs`** per-run to balance thoroughness against latency.
+- **Use `AbortSignal`** to cancel collection early from application code.
+- **Use the event system** (`client.on('progress', ...)`, `client.on('warning', ...)`, `client.on('complete', ...)`) to observe and react to collection progress.
+
+---
+
+## Limitations and non-goals
+
+- **Browser-side fingerprints are probabilistic**, not identity proofs. The thumbprint is a best-effort device identifier that can change across browser updates, privacy settings, and hardware changes.
+- **Font detection is bounded** to 70 common fonts measured against 3 generic families. It does not scan the full system font catalog.
+- **The anti-spoof report is heuristic** — combine with server-side context (IP reputation, behavioral analysis, request headers) for fraud or login-risk decisions.
+- **No server-side identity resolution** — the library computes a client thumbprint only. Deriving authoritative server-side identities, clustering, and deduplication are the caller's responsibility.
+- **No runtime dependencies** — this is intentional. The library bundles its own SHA-256 implementation and does not load external resources.
+- **No battery, sensor, or installed-app probes** — these are excluded by design for privacy and stability reasons.
+
+---
+
+## NPM package layout
+
+```text
+@ianmenethil/zp-devicefp/
+├── dist/npm/
+│   ├── index.mjs       # ESM entry (browser, ES2022)
+│   ├── index.cjs       # CJS entry (Node 22+)
+│   └── index.d.ts      # Public type declarations
+├── dist/cdn/
+│   ├── zp.dfp.js       # IIFE (unminified)
+│   ├── zp.dfp.min.js   # IIFE (minified)
+│   ├── zp.dfp.obf.js   # IIFE (minified + obfuscated)
+│   ├── zp.dfp.esm.js   # ESM for import()
+│   └── zp.dfp.manifest.json
+```
+
+---
+
+## NPM usage
+
+```bash
+bun add @ianmenethil/zp-devicefp
+```
+
+```ts
+import {
+	createFingerprintClient,
+	LIBRARY_VERSION,
+	SCHEMA_VERSION,
+	CORE_SIGNALS,
+	EXTENDED_SIGNALS,
+} from '@ianmenethil/zp-devicefp';
+
+const client = await createFingerprintClient({ timeoutMs: 2000 });
+const result = await client.collect({ extended: true });
+
+console.log(result.thumbprint);
+console.log(result.confidence);
+```