@thumbmarkjs/thumbmarkjs 0.20.5 → 1.0.0-rc.0

package/src/fingerprint/functions.ts

@@ -1,118 +1,248 @@
-import {componentInterface, getComponentPromises, timeoutInstance} from '../factory'
-import {hash} from '../utils/hash'
-import {raceAll, raceAllPerformance} from '../utils/raceAll'
-import {options} from './options'
-import * as packageJson from '../../package.json'
-
-export function getVersion(): string {
-    return packageJson.version
-}
-
-export async function getFingerprintData(): Promise<componentInterface>  {
-    try {
-        const promiseMap: Record<string, Promise<componentInterface>> = getComponentPromises()
-        const keys: string[] = Object.keys(promiseMap)
-        const promises: Promise<componentInterface>[] = Object.values(promiseMap)
-        const resolvedValues: (componentInterface | undefined)[] = await raceAll(promises, options?.timeout || 1000, timeoutInstance);
-        const validValues: componentInterface[] = resolvedValues.filter((value): value is componentInterface => value !== undefined);
-        const resolvedComponents: Record<string, componentInterface> = {};
-        validValues.forEach((value, index) => {
-            resolvedComponents[keys[index]] = value
-        })
-        return filterFingerprintData(resolvedComponents, options.exclude || [], options.include || [], "")
-    }
-    catch (error) {
-        throw error
-    }
-}
-
-/** 
- * This function filters the fingerprint data based on the exclude and include list
- * @param {componentInterface} obj - components objects from main componentInterface
- * @param {string[]} excludeList - elements to exclude from components objects (e.g : 'canvas', 'system.browser')
- * @param {string[]} includeList - elements to only include from components objects (e.g : 'canvas', 'system.browser')
- * @param {string} path - auto-increment path iterating on key objects from components objects
- * @returns {componentInterface} result - returns the final object before hashing in order to get fingerprint
- */
-export function filterFingerprintData(obj: componentInterface, excludeList: string[], includeList: string[], path: string = ""): componentInterface {
-    const result: componentInterface = {};
-
-    for (const [key, value] of Object.entries(obj)) {
-        const currentPath = path + key + ".";
-
-        if (typeof value === "object" && !Array.isArray(value)) {
-            const filtered = filterFingerprintData(value, excludeList, includeList, currentPath);
-            if (Object.keys(filtered).length > 0) {
-                result[key] = filtered;
-            }
-        } else {
-            const isExcluded = excludeList.some(exclusion => currentPath.startsWith(exclusion));
-            const isIncluded = includeList.some(inclusion => currentPath.startsWith(inclusion));
-
-            if (!isExcluded || isIncluded) {
-                result[key] = value;
-            }
-        }
-    }
-
-    return result;
-}
-
-export async function getFingerprint(includeData?: false): Promise<string>
-export async function getFingerprint(includeData: true): Promise<{ hash: string, data: componentInterface }>
-export async function getFingerprint(includeData?: boolean): Promise<string | { hash: string, data: componentInterface }> {
-    try {
-        const fingerprintData = await getFingerprintData()
-        const thisHash = hash(JSON.stringify(fingerprintData))
-        if (Math.random() < 0.00001 && options.logging) logFingerprintData(thisHash, fingerprintData)
-        if (includeData) {
-            return { hash: thisHash.toString(), data: fingerprintData}
-        } else {
-            return thisHash.toString()
-        }
-    } catch (error) {
-        throw error
-    }
-}
-
-export async function getFingerprintPerformance() {
-    try {
-        const promiseMap = getComponentPromises()
-        const keys = Object.keys(promiseMap)
-        const promises = Object.values(promiseMap)
-        const resolvedValues = await raceAllPerformance(promises, options?.timeout || 1000, timeoutInstance )
-        const resolvedComponents: { [key: string]: any } = {
-            elapsed: {}
-        }
-        resolvedValues.forEach((value, index) => {
-            resolvedComponents[keys[index]] = value.value
-            resolvedComponents["elapsed"][keys[index]] = value.elapsed
-        });
-        return resolvedComponents
-    }
-    catch (error) {
-        throw error
-    }
-}
-
-// Function to log the fingerprint data
-async function logFingerprintData(thisHash: string, fingerprintData: componentInterface) {
-    const url = 'https://logging.thumbmarkjs.com/v1/log'
-    const payload = {
-        thumbmark: thisHash,
-        components: fingerprintData,
-        version: getVersion()
-    };
-    if (!sessionStorage.getItem("_tmjs_l")) {
-        sessionStorage.setItem("_tmjs_l", "1")
-        try {
-            await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json'
-                },
-                body: JSON.stringify(payload)
-            });
-        } catch { } // do nothing
-    }
-}
+/**
+ * ThumbmarkJS: Main fingerprinting and API logic
+ *
+ * This module handles component collection, API calls, uniqueness scoring, and data filtering
+ * for the ThumbmarkJS browser fingerprinting library.
+ *
+ * Exports:
+ *   - getThumbmark
+ *   - getThumbmarkDataFromPromiseMap
+ *   - resolveClientComponents
+ *   - getVersion
+ *   - filterThumbmarkData
+ *
+ * Internal helpers and types are also defined here.
+ */
+
+// ===================== Imports =====================
+import { defaultOptions, optionsInterface } from "./options";
+import { 
+    timeoutInstance,
+    componentInterface,
+    tm_component_promises,
+    customComponents,
+    includeComponent as globalIncludeComponent
+} from "../factory";
+import { hash } from "../utils/hash";
+import { raceAllPerformance } from "../utils/raceAll";
+import * as packageJson from '../../package.json';
+import { filterThumbmarkData } from '../utils/filterComponents'
+
+// ===================== Types & Interfaces =====================
+
+/**
+ * Info returned from the API (IP, classification, uniqueness, etc)
+ */
+interface infoInterface {
+    ip_address?: {
+        ip_address: string,
+        ip_identifier: string,
+        autonomous_system_number: number,
+        ip_version: 'v6' | 'v4',
+    },
+    classification?: {
+        tor: boolean,
+        proxy: boolean, // i.e. vpn and 
+        datacenter: boolean,
+        danger_level: number, // 5 is highest and should be blocked. 0 is no danger.
+    },
+    uniqueness?: {
+        score: number | string
+    }
+}
+
+/**
+ * API response structure
+ */
+interface apiResponse {
+    thumbmark?: string;
+    info?: infoInterface;
+    version?: string;
+}
+
+/**
+ * Final thumbmark response structure
+ */
+interface thumbmarkResponse {
+    components: componentInterface,
+    info: { [key: string]: any },
+    version: string,
+    thumbmark: string,
+    /**
+     * Only present if options.performance is true.
+     */
+    elapsed?: any;
+}
+
+// ===================== Version =====================
+
+/**
+ * Returns the current package version
+ */
+export function getVersion(): string {
+    return packageJson.version;
+}
+
+// ===================== API Call Logic =====================
+
+let currentApiPromise: Promise<apiResponse> | null = null;
+let apiPromiseResult: apiResponse | null = null;
+
+/**
+ * Calls the Thumbmark API with the given components, using caching and deduplication.
+ * Returns a promise for the API response or null on error.
+ */
+export const getApiPromise = (
+    options: optionsInterface,
+    components: componentInterface
+): Promise<apiResponse | null> => {
+    // 1. If a result is already cached and caching is enabled, return it.
+    if (options.cache_api_call && apiPromiseResult) {
+        return Promise.resolve(apiPromiseResult);
+    }
+
+    // 2. If a request is already in flight, return that promise to prevent duplicate calls.
+    if (currentApiPromise) {
+        return currentApiPromise;
+    }
+
+    // 3. Otherwise, initiate a new API call.
+    const endpoint = 'https://api-dev.thumbmarkjs.com/thumbmark';
+    currentApiPromise = fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'x-api-key': options.api_key!,
+            'Authorization': 'custom-authorized',
+        },
+        body: JSON.stringify({ components: components, clientHash: hash(JSON.stringify(components)) }),
+    })
+        .then(response => {
+            // Handle HTTP errors that aren't network errors
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            return response.json();
+        })
+        .then(data => {
+            apiPromiseResult = data;      // Cache the successful result
+            currentApiPromise = null;     // Clear the in-flight promise
+            return data;
+        })
+        .catch(error => {
+            console.error('Error fetching pro data', error);
+            currentApiPromise = null;     // Also clear the in-flight promise on error
+            // Return null instead of a string to prevent downstream crashes
+            return null;
+        });
+
+    return currentApiPromise;
+};
+
+// ===================== Main Thumbmark Logic =====================
+
+/**
+ * Main entry point: collects all components, optionally calls API, and returns thumbmark data.
+ *
+ * @param options - Options for fingerprinting and API
+ * @returns thumbmarkResponse (elapsed is present only if options.performance is true)
+ */
+export async function getThumbmark(options?: optionsInterface): Promise<thumbmarkResponse> {
+    const _options = { ...defaultOptions, ...options };
+    // Merge built-in and user-registered components
+    const allComponents = { ...tm_component_promises, ...customComponents };
+    const { elapsed, resolvedComponents: clientComponentsResult } = await resolveClientComponents(allComponents, _options);
+
+    const apiPromise = _options.api_key ? getApiPromise(_options, clientComponentsResult) : null;
+    const apiResult = apiPromise ? await apiPromise : null;
+
+    // Only add 'elapsed' if performance is true
+    const maybeElapsed = _options.performance ? { elapsed } : {};
+
+    if (apiResult) {
+        const info: infoInterface = apiResult.info || {};
+        return {
+            components: clientComponentsResult,
+            info,
+            version: getVersion(),
+            thumbmark: apiResult.thumbmark || 'undefined',
+            ...maybeElapsed,
+        };
+    }
+    return {
+        thumbmark: hash(JSON.stringify(clientComponentsResult)),
+        components: clientComponentsResult,
+        info: {
+            uniqueness: 'api only'
+        },
+        version: getVersion(),
+        ...maybeElapsed,
+    };
+}
+
+// ===================== Component Resolution & Performance =====================
+
+/**
+ * Resolves and times all filtered component promises from a component function map.
+ *
+ * @param comps - Map of component functions
+ * @param options - Options for filtering and timing
+ * @returns Object with elapsed times and filtered resolved components
+ */
+export async function resolveClientComponents(
+  comps: { [key: string]: (options?: optionsInterface) => Promise<componentInterface | null> },
+  options?: optionsInterface
+): Promise<{ elapsed: Record<string, number>, resolvedComponents: componentInterface }> {
+  const opts = { ...defaultOptions, ...options };
+  const filtered = Object.entries(comps)
+    .filter(([key]) => !opts?.exclude?.includes(key))
+    .filter(([key]) =>
+      opts?.include?.some(e => e.includes('.'))
+        ? opts?.include?.some(e => e.startsWith(key))
+        : opts?.include?.length === 0 || opts?.include?.includes(key)
+    );
+  const keys = filtered.map(([key]) => key);
+  const promises = filtered.map(([_, fn]) => fn());
+  const resolvedValues = await raceAllPerformance(promises, opts?.timeout || 1000, timeoutInstance);
+
+  const elapsed: Record<string, number> = {};
+  const resolvedComponentsRaw: Record<string, componentInterface> = {};
+
+  resolvedValues.forEach((value, index) => {
+    if (value.value != null) {
+      resolvedComponentsRaw[keys[index]] = value.value;
+      elapsed[keys[index]] = value.elapsed ?? 0;
+    }
+  });
+
+  const resolvedComponents = filterThumbmarkData(resolvedComponentsRaw, opts, "");
+  return { elapsed, resolvedComponents };
+}
+
+// ===================== Logging (Internal) =====================
+
+/**
+ * Logs thumbmark data to remote logging endpoint (only once per session)
+ * @internal
+ */
+async function logThumbmarkData(thisHash: string, thumbmarkData: componentInterface) {
+    const url = 'https://logging.thumbmarkjs.com/v1/log';
+    const payload = {
+        thumbmark: thisHash,
+        components: thumbmarkData,
+        version: getVersion()
+    };
+    if (!sessionStorage.getItem("_tmjs_l")) {
+        sessionStorage.setItem("_tmjs_l", "1");
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(payload)
+            });
+        } catch { /* do nothing */ }
+    }
+}
+
+export { globalIncludeComponent as includeComponent };

package/src/fingerprint/legacy_functions.ts

@@ -0,0 +1,54 @@
+/**
+ * This file is here to support legacy implementations.
+ * Eventually, these functions will be removed to keep the library small.
+ */
+
+import { componentInterface } from '../factory'
+import { options} from './options'
+import { resolveClientComponents, getThumbmark } from './functions';
+import { tm_component_promises } from "../factory";
+
+/**
+ * 
+ * @deprecated
+ */
+export async function getFingerprintData() {
+    const thumbmarkData = await getThumbmark(options);
+    return thumbmarkData.components;
+}
+
+/**
+ * 
+ * @param includeData boolean
+ * @deprecated this function is going to be removed. use getThumbmark or Thumbmark class instead.
+ */
+export async function getFingerprint(includeData?: false): Promise<string>
+export async function getFingerprint(includeData: true): Promise<{ hash: string, data: componentInterface }>
+export async function getFingerprint(includeData?: boolean): Promise<string | { hash: string, data: componentInterface }> {
+    try {
+        const thumbmarkData = await getThumbmark(options);
+        if (includeData) {
+            return { hash: thumbmarkData.thumbmark.toString(), data: thumbmarkData.components}
+        } else {
+            return thumbmarkData.thumbmark.toString()
+        }
+    } catch (error) {
+        throw error
+    }
+}
+/**
+ * 
+ * @deprecated use Thumbmark or getThumbmark instead with options
+ */
+export async function getFingerprintPerformance() {
+    try {
+        const { elapsed, resolvedComponents } = await resolveClientComponents(tm_component_promises, options);
+        // Legacy format: merge resolvedComponents and elapsed into one object
+        return {
+            ...resolvedComponents,
+            elapsed
+        };
+    } catch (error) {
+        throw error;
+    }
+}

package/src/fingerprint/options.ts

@@ -1,23 +1,34 @@
 export interface optionsInterface {
-    exclude: string[],
-    include: string[],
+    exclude?: string[],
+    include?: string[],
     webgl_runs?: number,
     canvas_runs?: number,
     permissions_to_check?: PermissionName[], // new option
     retries?: number, // new option
-    timeout: number, // new option
-    logging: boolean
+    timeout?: number, // new option
+    logging?: boolean,
+    api_key?: string,
+    cache_api_call?: boolean,
+    performance?: boolean, // re-added
 }
 
-export let options: optionsInterface = {
+export const defaultOptions: optionsInterface = {
     exclude: [],
     include: [],
     logging: true,
-    timeout: 1000
-}
+    timeout: 5000,
+    cache_api_call: true,
+    performance: false // re-added
+    };
 
+export let options = {...defaultOptions};
+/**
+ * 
+ * @param key @deprecated this function will be removed
+ * @param value 
+ */
 export function setOption<K extends keyof optionsInterface>(key: K, value: optionsInterface[K]) {
-    if (!['include', 'exclude', 'permissions_to_check', 'retries', 'timeout', 'logging'].includes(key))
+    if (!['include', 'exclude', 'permissions_to_check', 'retries', 'timeout', 'logging', 'api_key', 'cache_api_call'].includes(key))
         throw new Error('Unknown option ' + key)
     if (['include', 'exclude', 'permissions_to_check'].includes(key) && !(Array.isArray(value) && value.every(item => typeof item === 'string')) )
         throw new Error('The value of the include, exclude and permissions_to_check must be an array of strings');

package/src/index.ts

@@ -1,6 +1,15 @@
-import { getFingerprint, getFingerprintData, getFingerprintPerformance, getVersion } from './fingerprint/functions'
+import {
+    getFingerprint,
+    getFingerprintData,
+    getFingerprintPerformance
+ } from './fingerprint/legacy_functions'
+import { getThumbmark, getVersion } from './fingerprint/functions'
 import { setOption } from './fingerprint/options'
 import { includeComponent } from './factory'
-import './components'
+import { Thumbmark } from './thumbmark'
 
-export { setOption, getVersion, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent }
+export { Thumbmark, getThumbmark, getVersion,
+
+    // deprecated functions. Don't use anymore.
+    setOption, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent
+}

package/src/thumbmark.ts

@@ -0,0 +1,41 @@
+import { optionsInterface } from "./fingerprint/options";
+import { getThumbmark, getVersion, includeComponent as globalIncludeComponent } from './fingerprint/functions';
+import { defaultOptions } from "./fingerprint/options";
+import { componentInterface } from "./factory";
+
+/**
+ * A client for generating thumbmarks with a persistent configuration.
+ */
+    
+export class Thumbmark {
+    private options: optionsInterface;
+  
+    /**
+     * Creates a new Thumbmarker client instance.
+     * @param options - Default configuration options for this instance.
+     */
+    constructor(options?: optionsInterface) {
+      this.options = { ...defaultOptions, ...options };
+    }
+  
+    /**
+     * Generates a thumbmark using the instance's configuration.
+     * @param overrideOptions - Options to override for this specific call.
+     * @returns The thumbmark result.
+     */
+    public async get(overrideOptions?: optionsInterface): Promise<any> {
+      const finalOptions = { ...this.options, ...overrideOptions };
+      return getThumbmark(finalOptions);
+    }
+    public getVersion(): string {
+      return getVersion()
+    }
+    /**
+     * Register a custom component to be included in the fingerprint.
+     * @param key - The component name
+     * @param fn - The component function
+     */
+    public includeComponent(key: string, fn: (options?: optionsInterface) => Promise<componentInterface | null>) {
+      globalIncludeComponent(key, fn);
+    }
+}

package/src/{declarations.d.ts → types/global.d.ts}

@@ -5,8 +5,8 @@ interface ApplePaySession {
 }
 
 interface Window {
-    webkitAudioContext: typeof AudioContext
     webkitOfflineAudioContext: typeof OfflineAudioContext
+    webkitAudioContext: typeof AudioContext
     ApplePaySession: typeof ApplePaySession
   }
 

package/src/utils/filterComponents.ts

@@ -0,0 +1,42 @@
+import { componentInterface } from "../factory";
+import { optionsInterface } from "../fingerprint/options";
+
+// ===================== Data Filtering =====================
+
+/**
+ * Recursively filters a componentInterface object by include/exclude options.
+ *
+ * @param obj - The object to filter
+ * @param options - Filtering options
+ * @param path - Current path (for recursion)
+ * @returns Filtered object
+ */
+export function filterThumbmarkData(
+    obj: componentInterface,
+    options?: optionsInterface,
+    path: string = ""
+): componentInterface {
+    const result: componentInterface = {};
+    const excludeList = options?.exclude || [];
+    const includeList = options?.include || [];
+
+    for (const [key, value] of Object.entries(obj)) {
+        const currentPath = path + key + ".";
+
+        if (typeof value === "object" && !Array.isArray(value)) {
+            const filtered = filterThumbmarkData(value, options, currentPath);
+            if (Object.keys(filtered).length > 0) {
+                result[key] = filtered;
+            }
+        } else {
+            const isExcluded = excludeList.some(exclusion => currentPath.startsWith(exclusion));
+            const isIncluded = includeList.some(inclusion => currentPath.startsWith(inclusion));
+
+            if (!isExcluded || isIncluded) {
+                result[key] = value;
+            }
+        }
+    }
+
+    return result;
+}

package/src/utils/raceAll.ts

@@ -1,5 +1,3 @@
-import { componentInterface } from '../factory'
-
 type DelayedPromise<T> = Promise<T>;
 
 export function delay<T>(t: number, val: T): DelayedPromise<T> {

package/src/components/index.ts

@@ -1,17 +0,0 @@
-/**
- * Does anyone have a cleaner way of doing this?
- * I want to import all the components in this folder
- * Feels a little dumb I'm doing this manually.
- */
-
-import './audio/audio'
-import './canvas/canvas'
-import './fonts/fonts'
-import './hardware/hardware'
-import './locales/locales'
-import './permissions/permissions'
-import './plugins/plugins'
-import './screen/screen'
-import './system/system'
-import './webgl/webgl'
-import './math/math'

package/src/components/math/math.ts

@@ -1,39 +0,0 @@
-import { componentInterface, includeComponent } from '../../factory'
-
-const getMathInfo = async (): Promise<componentInterface> => {
-    return {
-        acos: Math.acos(0.5),
-        asin: integrate(Math.asin, -1, 1, 97),
-        atan: integrate(Math.atan, -1, 1, 97),
-        cos: integrate(Math.cos, 0, Math.PI, 97),
-        cosh: Math.cosh(9/7),
-        e: Math.E,
-        largeCos: Math.cos(1e20),
-        largeSin: Math.sin(1e20),
-        largeTan: Math.tan(1e20),
-        log: Math.log(1000),
-        pi: Math.PI,
-        sin: integrate(Math.sin, -Math.PI, Math.PI, 97),
-        sinh: integrate(Math.sinh, -9/7, 7/9, 97),
-        sqrt: Math.sqrt(2),
-        tan: integrate(Math.tan, 0, 2 * Math.PI, 97),
-        tanh: integrate(Math.tanh, -9/7, 7/9, 97),
-    }
-}
-
-/** This might be a little excessive, but I wasn't sure what number to pick for some of the
- * trigonometric functions. Using an integral here, so a few numbers are calculated. However,
- * I do this mainly for those integrals that sum up to a small value, otherwise there's no point.
-*/ 
-
-const integrate = (f: (x: number) => number, a: number, b: number, n: number): number => {
-    const h = (b - a) / n;
-    let sum = 0;
-    for (let i = 0; i < n; i++) {
-        const x = a + (i + 0.5) * h;
-        sum += f(x);
-    }
-    return sum * h;
-};
-
-includeComponent('math', getMathInfo);