feat: add createAnalysisReport function for dense scoring reports

- Implemented createAnalysisReport to generate a concise report containing visitor ID, confidence, aggregate weights, risk verdicts, and raw component results.
- Updated index files to export the new function.
- Enhanced documentation to include details about the new report format.
- Modified examples and tests to demonstrate the usage of createAnalysisReport.
- Adjusted browser demo to display ID analysis alongside existing report formats.

Author: MADEVAL

README.md

@@ -10,6 +10,15 @@ FingerprintJS by BotBlocker is a browser fingerprinting and device intelligence
 
 The runtime has no production dependencies, performs no network calls by default, and exposes privacy-aware collector policies, deterministic identity hashing, report-only risk signals, bot evidence, private-mode indicators, confidence scoring, storage state, and compact diagnostics.
 
+## Core Advantages
+
+- Stable visitor identity is separated from risk and diagnostic evidence. Volatile, bot, private-mode, tamper, storage, network, and capability signals can enrich reports without changing the default `visitorId`.
+- Backend verification is included through `@botblocker/fingerprintjs/server`: replay protection, client hash recomputation, server-only hashing, explainable backend reports, and pluggable network risk checks.
+- Tamper, bot, and private-mode evidence is returned as scored, explainable signals instead of a single opaque identifier.
+- Use-case presets provide practical defaults for privacy-first analytics, login risk, checkout risk, bot defense, and fraud defense.
+- The SDK is self-hostable, dependency-free at runtime, works through ESM, CommonJS, and a direct script tag, and performs no network calls unless the host application sends results to its own backend.
+- Output formats cover product integration, backend scoring, and debugging: compact report, dense ID analysis report, full raw report, and standalone JSON inspector.
+
 ## Install And Build
 
 ```bash
@@ -35,7 +44,7 @@ Each package entry supports ESM `import` and CommonJS `require`. Browser builds
 ## ESM Usage
 
 ```js
-import { hashComponents, loadClient } from '@botblocker/fingerprintjs';
+import { createAnalysisReport, hashComponents, loadClient } from '@botblocker/fingerprintjs';
 
 const client = await loadClient({
   namespace: 'my-product',
@@ -54,13 +63,15 @@ const result = await client.get({
 const bot = result.components.find((component) => component.id === 'browser.botDetection');
 const privacy = result.components.find((component) => component.id === 'browser.privacyMode');
 const recalculated = await hashComponents(result.components, { namespace: 'my-product' });
+const analysis = createAnalysisReport(result, { recalculatedHash: recalculated });
 
 console.log({
   visitorId: result.visitorId,
   bot: bot?.value?.verdict,
   privateMode: privacy?.value?.verdict,
   confidence: result.confidence,
-  hashMatches: recalculated.visitorId === result.visitorId
+  hashMatches: recalculated.visitorId === result.visitorId,
+  analysis
 });
 ```
 
@@ -190,15 +201,16 @@ Collection confidence and identity confidence are both exposed. `confidence.scor
 
 ## Reports And Demo
 
-The browser demo in [examples/browser.html](examples/browser.html) renders two reports side by side and tracks repeated runs:
+The browser demo in [examples/browser.html](examples/browser.html) renders three reports side by side and tracks repeated runs:
 
-- Compact report: concise identity, risk, quality, calculations, and every capability with status.
-- Full report: raw SDK result, recalculated hash, derived calculations, and every component value/error.
+- Compact report: concise identity, risk, quality, calculations, and every capability with status, role, hashability, weight, duration, value summary, and error state.
+- ID analysis report: shortest dense format for backend scoring. It contains `id`, request metadata, confidence, aggregate weights, hash checks, risk verdicts, and every component's role, status, weight, raw result, and error.
+- Full report: raw SDK result, recalculated hash, all-signals hash, derived calculations, stability data, explainable report, ID analysis report, and every component value/error.
 - Stability view: baseline visitor ID, current visitor ID, identity input count, report-only count, changed identity/report-only components, and recent run history.
 
-Both reports include all collected capabilities and calculation data. Use the `extended` profile in the demo to exercise the full collector pack and confirm that report-only changes do not move the stable visitor ID.
+All demo outputs are generated from the same `IdentifyResult`. The compact and ID analysis formats include every collected capability; the full format additionally embeds the raw result and explainable report. Use the `extended` profile in the demo to exercise the full collector pack and confirm that report-only changes do not move the stable visitor ID.
 
-The debug inspector in [examples/inspector.html](examples/inspector.html) accepts an `IdentifyResult` or full demo report JSON and explains identity components, report-only components, tamper, bot, and private-mode evidence.
+The debug inspector in [examples/inspector.html](examples/inspector.html) accepts an `IdentifyResult`, full demo report JSON, or ID analysis report JSON and explains identity components, report-only components, tamper, bot, and private-mode evidence.
 
 ## Verification
 

dist/browser/fingerprintjs-botblocker.js

@@ -43,6 +43,7 @@ var FingerprintJSBotBlocker = (() => {
     VERSION: () => VERSION,
     canonicalStringify: () => canonicalStringify,
     componentsToDebugString: () => componentsToDebugString,
+    createAnalysisReport: () => createAnalysisReport,
     createApiFeaturesCollector: () => createApiFeaturesCollector,
     createBotDetectionCollector: () => createBotDetectionCollector,
     createBrowserCollectorPack: () => createBrowserCollectorPack,
@@ -3257,6 +3258,29 @@ var FingerprintJSBotBlocker = (() => {
       components
     });
   }
+  function createAnalysisReport(result, options = {}) {
+    assertResult2(result);
+    const identityComponents = new Set(result.meta && Array.isArray(result.meta.identityComponents) ? result.meta.identityComponents : []);
+    const components = Object.freeze(result.components.map((component) => analysisComponent(component, identityComponents)));
+    const risk = buildRiskSummary(result.components);
+    return Object.freeze({
+      id: result.visitorId || null,
+      requestId: result.requestId || null,
+      namespace: result.namespace || "default",
+      profile: result.meta && result.meta.profile ? result.meta.profile : null,
+      confidence: result.confidence || null,
+      weights: summarizeWeights(result.components, result.confidence || {}, identityComponents),
+      totals: Object.freeze({
+        total: components.length,
+        ok: countStatus(result.components, "ok"),
+        identity: components.filter((component) => component.role === "identity").length,
+        reportOnly: components.filter((component) => component.role === "report-only").length
+      }),
+      hash: buildHashSummary(result, options),
+      risk,
+      components
+    });
+  }
   function explainComponent(component, identityComponents = [], options = {}) {
     const identitySet = identityComponents instanceof Set ? identityComponents : new Set(identityComponents);
     const role = identitySet.has(component.id) ? "identity" : "report-only";
@@ -3289,6 +3313,54 @@ var FingerprintJSBotBlocker = (() => {
     }
     return component.hashable === false ? "report_only_collector" : "excluded_by_identity_policy";
   }
+  function analysisComponent(component, identityComponents) {
+    return Object.freeze({
+      id: component.id,
+      role: identityComponents.has(component.id) ? "identity" : "report-only",
+      status: component.status,
+      weight: component.weight,
+      category: component.category,
+      sensitivity: component.sensitivity,
+      mode: component.mode,
+      stability: component.stability,
+      hashable: component.hashable,
+      durationMs: component.durationMs,
+      result: component.status === "ok" ? component.value : null,
+      error: component.error || null
+    });
+  }
+  function summarizeWeights(components, confidence, identityComponents) {
+    const okComponents = components.filter((component) => component.status === "ok");
+    const identityOkComponents = okComponents.filter((component) => identityComponents.has(component.id));
+    const reportOnlyOkComponents = okComponents.filter((component) => !identityComponents.has(component.id));
+    return Object.freeze({
+      total: round2(sumWeights(components)),
+      ok: round2(sumWeights(okComponents)),
+      identity: round2(sumWeights(identityOkComponents)),
+      reportOnly: round2(sumWeights(reportOnlyOkComponents)),
+      collected: Number.isFinite(confidence.collectedWeight) ? confidence.collectedWeight : null,
+      possible: Number.isFinite(confidence.possibleWeight) ? confidence.possibleWeight : null,
+      qualityCollected: confidence.collectionQuality && Number.isFinite(confidence.collectionQuality.collectedWeight) ? confidence.collectionQuality.collectedWeight : null,
+      qualityPossible: confidence.collectionQuality && Number.isFinite(confidence.collectionQuality.possibleWeight) ? confidence.collectionQuality.possibleWeight : null
+    });
+  }
+  function buildHashSummary(result, options) {
+    const recalculated = options.recalculatedHash || null;
+    const allSignals = options.allSignalsHash || null;
+    return Object.freeze({
+      algorithm: result.meta && result.meta.hashAlgorithm ? result.meta.hashAlgorithm : null,
+      recalculatedVisitorId: recalculated ? recalculated.visitorId : null,
+      recalculatedMatches: recalculated ? recalculated.visitorId === result.visitorId : null,
+      allSignalsVisitorId: allSignals ? allSignals.visitorId : null,
+      allSignalsDiffers: allSignals ? allSignals.visitorId !== result.visitorId : null
+    });
+  }
+  function sumWeights(components) {
+    return components.reduce((total, component) => total + (Number.isFinite(component.weight) ? Number(component.weight) : 0), 0);
+  }
+  function round2(value) {
+    return Math.round(Number(value || 0) * 1e3) / 1e3;
+  }
   function summarizeValue(value) {
     if (value === null) {
       return null;

dist/browser/fingerprintjs-botblocker.min.js

@@ -36,6 +36,7 @@ __export(src_exports, {
   VERSION: () => VERSION,
   canonicalStringify: () => canonicalStringify,
   componentsToDebugString: () => componentsToDebugString,
+  createAnalysisReport: () => createAnalysisReport,
   createApiFeaturesCollector: () => createApiFeaturesCollector,
   createBotDetectionCollector: () => createBotDetectionCollector,
   createBrowserCollectorPack: () => createBrowserCollectorPack,
@@ -3251,6 +3252,29 @@ function createExplainableReport(result, options = {}) {
     components
   });
 }
+function createAnalysisReport(result, options = {}) {
+  assertResult2(result);
+  const identityComponents = new Set(result.meta && Array.isArray(result.meta.identityComponents) ? result.meta.identityComponents : []);
+  const components = Object.freeze(result.components.map((component) => analysisComponent(component, identityComponents)));
+  const risk = buildRiskSummary(result.components);
+  return Object.freeze({
+    id: result.visitorId || null,
+    requestId: result.requestId || null,
+    namespace: result.namespace || "default",
+    profile: result.meta && result.meta.profile ? result.meta.profile : null,
+    confidence: result.confidence || null,
+    weights: summarizeWeights(result.components, result.confidence || {}, identityComponents),
+    totals: Object.freeze({
+      total: components.length,
+      ok: countStatus(result.components, "ok"),
+      identity: components.filter((component) => component.role === "identity").length,
+      reportOnly: components.filter((component) => component.role === "report-only").length
+    }),
+    hash: buildHashSummary(result, options),
+    risk,
+    components
+  });
+}
 function explainComponent(component, identityComponents = [], options = {}) {
   const identitySet = identityComponents instanceof Set ? identityComponents : new Set(identityComponents);
   const role = identitySet.has(component.id) ? "identity" : "report-only";
@@ -3283,6 +3307,54 @@ function explainReason(component, role) {
   }
   return component.hashable === false ? "report_only_collector" : "excluded_by_identity_policy";
 }
+function analysisComponent(component, identityComponents) {
+  return Object.freeze({
+    id: component.id,
+    role: identityComponents.has(component.id) ? "identity" : "report-only",
+    status: component.status,
+    weight: component.weight,
+    category: component.category,
+    sensitivity: component.sensitivity,
+    mode: component.mode,
+    stability: component.stability,
+    hashable: component.hashable,
+    durationMs: component.durationMs,
+    result: component.status === "ok" ? component.value : null,
+    error: component.error || null
+  });
+}
+function summarizeWeights(components, confidence, identityComponents) {
+  const okComponents = components.filter((component) => component.status === "ok");
+  const identityOkComponents = okComponents.filter((component) => identityComponents.has(component.id));
+  const reportOnlyOkComponents = okComponents.filter((component) => !identityComponents.has(component.id));
+  return Object.freeze({
+    total: round2(sumWeights(components)),
+    ok: round2(sumWeights(okComponents)),
+    identity: round2(sumWeights(identityOkComponents)),
+    reportOnly: round2(sumWeights(reportOnlyOkComponents)),
+    collected: Number.isFinite(confidence.collectedWeight) ? confidence.collectedWeight : null,
+    possible: Number.isFinite(confidence.possibleWeight) ? confidence.possibleWeight : null,
+    qualityCollected: confidence.collectionQuality && Number.isFinite(confidence.collectionQuality.collectedWeight) ? confidence.collectionQuality.collectedWeight : null,
+    qualityPossible: confidence.collectionQuality && Number.isFinite(confidence.collectionQuality.possibleWeight) ? confidence.collectionQuality.possibleWeight : null
+  });
+}
+function buildHashSummary(result, options) {
+  const recalculated = options.recalculatedHash || null;
+  const allSignals = options.allSignalsHash || null;
+  return Object.freeze({
+    algorithm: result.meta && result.meta.hashAlgorithm ? result.meta.hashAlgorithm : null,
+    recalculatedVisitorId: recalculated ? recalculated.visitorId : null,
+    recalculatedMatches: recalculated ? recalculated.visitorId === result.visitorId : null,
+    allSignalsVisitorId: allSignals ? allSignals.visitorId : null,
+    allSignalsDiffers: allSignals ? allSignals.visitorId !== result.visitorId : null
+  });
+}
+function sumWeights(components) {
+  return components.reduce((total, component) => total + (Number.isFinite(component.weight) ? Number(component.weight) : 0), 0);
+}
+function round2(value) {
+  return Math.round(Number(value || 0) * 1e3) / 1e3;
+}
 function summarizeValue(value) {
   if (value === null) {
     return null;
@@ -3322,6 +3394,7 @@ function countStatus(components, status) {
   VERSION,
   canonicalStringify,
   componentsToDebugString,
+  createAnalysisReport,
   createApiFeaturesCollector,
   createBotDetectionCollector,
   createBrowserCollectorPack,

dist/index.cjs

@@ -195,6 +195,7 @@ export function createStabilityMonitor(options?: { historyLimit?: number }): {
   snapshot(): Record<string, unknown>;
 };
 export function diffComponents(previousComponents?: ComponentResult[], currentComponents?: ComponentResult[], identityComponentIds?: string[]): Record<string, unknown>;
+export function createAnalysisReport(result: IdentifyResult, options?: { recalculatedHash?: HashComponentsResult; allSignalsHash?: HashComponentsResult }): Record<string, unknown>;
 export function createExplainableReport(result: IdentifyResult, options?: { generatedAt?: string; includeValues?: boolean }): Record<string, unknown>;
 export function explainComponent(component: ComponentResult, identityComponents?: string[] | Set<string>, options?: { includeValues?: boolean }): Record<string, unknown>;
 export function canonicalStringify(value: unknown): string;

dist/index.d.ts

@@ -3190,6 +3190,29 @@ function createExplainableReport(result, options = {}) {
     components
   });
 }
+function createAnalysisReport(result, options = {}) {
+  assertResult2(result);
+  const identityComponents = new Set(result.meta && Array.isArray(result.meta.identityComponents) ? result.meta.identityComponents : []);
+  const components = Object.freeze(result.components.map((component) => analysisComponent(component, identityComponents)));
+  const risk = buildRiskSummary(result.components);
+  return Object.freeze({
+    id: result.visitorId || null,
+    requestId: result.requestId || null,
+    namespace: result.namespace || "default",
+    profile: result.meta && result.meta.profile ? result.meta.profile : null,
+    confidence: result.confidence || null,
+    weights: summarizeWeights(result.components, result.confidence || {}, identityComponents),
+    totals: Object.freeze({
+      total: components.length,
+      ok: countStatus(result.components, "ok"),
+      identity: components.filter((component) => component.role === "identity").length,
+      reportOnly: components.filter((component) => component.role === "report-only").length
+    }),
+    hash: buildHashSummary(result, options),
+    risk,
+    components
+  });
+}
 function explainComponent(component, identityComponents = [], options = {}) {
   const identitySet = identityComponents instanceof Set ? identityComponents : new Set(identityComponents);
   const role = identitySet.has(component.id) ? "identity" : "report-only";
@@ -3222,6 +3245,54 @@ function explainReason(component, role) {
   }
   return component.hashable === false ? "report_only_collector" : "excluded_by_identity_policy";
 }
+function analysisComponent(component, identityComponents) {
+  return Object.freeze({
+    id: component.id,
+    role: identityComponents.has(component.id) ? "identity" : "report-only",
+    status: component.status,
+    weight: component.weight,
+    category: component.category,
+    sensitivity: component.sensitivity,
+    mode: component.mode,
+    stability: component.stability,
+    hashable: component.hashable,
+    durationMs: component.durationMs,
+    result: component.status === "ok" ? component.value : null,
+    error: component.error || null
+  });
+}
+function summarizeWeights(components, confidence, identityComponents) {
+  const okComponents = components.filter((component) => component.status === "ok");
+  const identityOkComponents = okComponents.filter((component) => identityComponents.has(component.id));
+  const reportOnlyOkComponents = okComponents.filter((component) => !identityComponents.has(component.id));
+  return Object.freeze({
+    total: round2(sumWeights(components)),
+    ok: round2(sumWeights(okComponents)),
+    identity: round2(sumWeights(identityOkComponents)),
+    reportOnly: round2(sumWeights(reportOnlyOkComponents)),
+    collected: Number.isFinite(confidence.collectedWeight) ? confidence.collectedWeight : null,
+    possible: Number.isFinite(confidence.possibleWeight) ? confidence.possibleWeight : null,
+    qualityCollected: confidence.collectionQuality && Number.isFinite(confidence.collectionQuality.collectedWeight) ? confidence.collectionQuality.collectedWeight : null,
+    qualityPossible: confidence.collectionQuality && Number.isFinite(confidence.collectionQuality.possibleWeight) ? confidence.collectionQuality.possibleWeight : null
+  });
+}
+function buildHashSummary(result, options) {
+  const recalculated = options.recalculatedHash || null;
+  const allSignals = options.allSignalsHash || null;
+  return Object.freeze({
+    algorithm: result.meta && result.meta.hashAlgorithm ? result.meta.hashAlgorithm : null,
+    recalculatedVisitorId: recalculated ? recalculated.visitorId : null,
+    recalculatedMatches: recalculated ? recalculated.visitorId === result.visitorId : null,
+    allSignalsVisitorId: allSignals ? allSignals.visitorId : null,
+    allSignalsDiffers: allSignals ? allSignals.visitorId !== result.visitorId : null
+  });
+}
+function sumWeights(components) {
+  return components.reduce((total, component) => total + (Number.isFinite(component.weight) ? Number(component.weight) : 0), 0);
+}
+function round2(value) {
+  return Math.round(Number(value || 0) * 1e3) / 1e3;
+}
 function summarizeValue(value) {
   if (value === null) {
     return null;
@@ -3260,6 +3331,7 @@ export {
   VERSION,
   canonicalStringify,
   componentsToDebugString,
+  createAnalysisReport,
   createApiFeaturesCollector,
   createBotDetectionCollector,
   createBrowserCollectorPack,