@thumbmarkjs/thumbmarkjs 1.9.0 → 1.9.1

package/dist/types/factory.d.ts

@@ -0,0 +1,66 @@
+/**
+ * This file is used to create the includeComponent function as well as the interfaces each of the
+ * fingerprint components must implement.
+ *
+ */
+import { optionsInterface } from './options';
+import getAudio from "./components/audio";
+import getCanvas from "./components/canvas";
+import getFonts from "./components/fonts";
+import getHardware from "./components/hardware";
+import getLocales from "./components/locales";
+import getMath from "./components/math";
+import getPermissions from "./components/permissions";
+import getPlugins from "./components/plugins";
+import getScreen from "./components/screen";
+import getSystem from "./components/system";
+import getWebGL from "./components/webgl";
+import getIntl from "./components/intl";
+import getMediaDevices from "./components/mediaDevices";
+import getWebRTC from "./components/webrtc";
+import getMathML from "./components/mathml";
+import getSpeech from "./components/speech";
+/**
+ * @description key->function map of built-in components. Do not call the function here.
+ */
+export declare const tm_component_promises: {
+    audio: typeof getAudio;
+    canvas: typeof getCanvas;
+    fonts: typeof getFonts;
+    hardware: typeof getHardware;
+    locales: typeof getLocales;
+    math: typeof getMath;
+    permissions: typeof getPermissions;
+    plugins: typeof getPlugins;
+    screen: typeof getScreen;
+    system: typeof getSystem;
+    webgl: typeof getWebGL;
+    webrtc: typeof getWebRTC;
+    speech: typeof getSpeech;
+};
+/**
+ * @description key->function map of experimental components. Only resolved during logging.
+ */
+export declare const tm_experimental_component_promises: {
+    intl: typeof getIntl;
+    mathml: typeof getMathML;
+    mediadevices: typeof getMediaDevices;
+};
+export interface componentInterface {
+    [key: string]: string | string[] | number | boolean | componentInterface;
+}
+export interface componentFunctionInterface {
+    (options?: optionsInterface): Promise<componentInterface | null>;
+}
+export declare const customComponents: {
+    [name: string]: componentFunctionInterface | null;
+};
+export declare const timeoutInstance: componentInterface;
+/**
+ * includeComponent is the function each custom component function needs to call in order for the component to be included
+ * in the fingerprint.
+ * @param {string} name - the name identifier of the component
+ * @param {componentFunctionInterface} creationFunction - the function that implements the component
+ * @returns nothing
+ */
+export declare const includeComponent: (name: string, creationFunction: componentFunctionInterface, options?: optionsInterface) => void;

package/dist/types/functions/api.d.ts

@@ -0,0 +1,73 @@
+import { OptionsAfterDefaults } from '../options';
+import { componentInterface } from '../factory';
+/**
+ * Info returned from the API (IP, classification, uniqueness, etc)
+ */
+export interface infoInterface {
+    ip_address?: {
+        ip_address: string;
+        ip_identifier: string;
+        autonomous_system_number: number;
+        ip_version: 'v6' | 'v4';
+    };
+    classification?: {
+        tor: boolean;
+        vpn: boolean;
+        bot: boolean;
+        datacenter: boolean;
+        danger_level: number;
+    };
+    uniqueness?: {
+        score: number | string;
+    };
+    country?: {
+        iso_code: string;
+        name: string;
+        continent: {
+            code: string;
+            name: string;
+        };
+    };
+    visitor?: {
+        id: string;
+        isNew: boolean;
+        firstSeen: string;
+        lastSeen: string;
+    };
+    signals?: {
+        timezone_country_mismatch?: boolean;
+    };
+    timed_out?: boolean;
+}
+/**
+ * API response structure
+ */
+export interface apiResponse {
+    info?: infoInterface;
+    version?: string;
+    components?: componentInterface;
+    visitorId?: string;
+    thumbmark?: string;
+    requestId?: string;
+    metadata?: string | object;
+}
+export declare class ApiError extends Error {
+    status: number;
+    constructor(status: number);
+}
+/**
+ * Calls the Thumbmark API with the given components, using caching and deduplication.
+ * Returns a promise for the API response or null on error.
+ */
+export declare const getApiPromise: (options: OptionsAfterDefaults, components: componentInterface) => Promise<apiResponse | null>;
+/**
+ * If a valid cached api response exists, returns it
+ * @param options
+ */
+export declare function getCachedApiResponse(options: Pick<OptionsAfterDefaults, 'property_name_factory'>): apiResponse | undefined;
+/**
+ * Writes the api response to the cache according to the options
+ * @param options
+ * @param response
+ */
+export declare function setCachedApiResponse(options: Pick<OptionsAfterDefaults, 'cache_api_call' | 'cache_lifetime_in_ms' | 'property_name_factory'>, response: apiResponse): void;

package/dist/types/functions/filterComponents.d.ts

@@ -0,0 +1,15 @@
+import { componentInterface } from "../factory";
+import { optionsInterface } from "../options";
+/**
+ * Filters a componentInterface object based on include/exclude and stabilization options.
+ *
+ * @param obj - The object to filter
+ * @param options - Filtering options
+ * @returns Filtered object
+ */
+/**
+ * Builds the full exclusion list from user options and stabilization rules,
+ * taking browser detection into account.
+ */
+export declare function getExcludeList(options?: optionsInterface, obj?: componentInterface): string[];
+export declare function filterThumbmarkData(obj: componentInterface, options?: optionsInterface): componentInterface;

package/dist/types/functions/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ThumbmarkJS: Main fingerprinting and API logic
+ *
+ * This module handles component collection, API calls, uniqueness scoring, and data filtering
+ * for the ThumbmarkJS browser fingerprinting library.
+ *
+ */
+import { optionsInterface } from "../options";
+import { componentInterface, componentFunctionInterface, includeComponent as globalIncludeComponent } from "../factory";
+import { infoInterface } from "./api";
+/**
+ * Final thumbmark response structure
+ */
+export interface ThumbmarkError {
+    type: 'component_timeout' | 'component_error' | 'api_timeout' | 'api_error' | 'api_unauthorized' | 'network_error' | 'fatal';
+    message: string;
+    component?: string;
+}
+export interface ThumbmarkResponse {
+    /** Hash of all components - the main fingerprint identifier */
+    thumbmark: string;
+    /** All resolved fingerprint components */
+    components: componentInterface;
+    /** Information from the API (IP, classification, uniqueness score) */
+    info: infoInterface;
+    /** Library version */
+    version: string;
+    /** Persistent visitor identifier (requires API key) */
+    visitorId?: string;
+    /** Performance timing for each component (only when options.performance is true) */
+    elapsed?: Record<string, number>;
+    /** Structured error array. Present only when errors occurred. */
+    error?: ThumbmarkError[];
+    /** Experimental components (only when options.experimental is true) */
+    experimental?: componentInterface;
+    /** Unique identifier for this API request */
+    requestId?: string;
+    /** Metadata echoed back from the API */
+    metadata?: string | object;
+}
+/**
+ * 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 declare function getThumbmark(options?: optionsInterface, instanceCustomComponents?: Record<string, componentFunctionInterface | null>): Promise<ThumbmarkResponse>;
+/**
+ * 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, filtered resolved components, errors, and pipeline phase timings
+ */
+export declare function resolveClientComponents(comps: {
+    [key: string]: (options?: optionsInterface) => Promise<componentInterface | null>;
+}, options?: optionsInterface): Promise<{
+    elapsed: Record<string, number>;
+    resolvedComponents: componentInterface;
+    errors: ThumbmarkError[];
+    pipelineTimings: Record<string, number>;
+}>;
+export { globalIncludeComponent as includeComponent };

package/dist/types/functions/legacy_functions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This file is here to support legacy implementations.
+ * Eventually, these functions will be removed to keep the library small.
+ */
+import { componentInterface } from '../factory';
+/**
+ *
+ * @deprecated
+ */
+export declare function getFingerprintData(): Promise<componentInterface>;
+/**
+ *
+ * @param includeData boolean
+ * @deprecated this function is going to be removed. use getThumbmark or Thumbmark class instead.
+ */
+export declare function getFingerprint(includeData?: false): Promise<string>;
+export declare function getFingerprint(includeData: true): Promise<{
+    hash: string;
+    data: componentInterface;
+}>;
+/**
+ *
+ * @deprecated use Thumbmark or getThumbmark instead with options
+ */
+export declare function getFingerprintPerformance(): Promise<{
+    elapsed: Record<string, number>;
+}>;

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+import { getFingerprint, getFingerprintData, getFingerprintPerformance } from './functions/legacy_functions';
+import { getThumbmark, ThumbmarkResponse, ThumbmarkError } from './functions';
+import { getVersion } from './utils/version';
+import { setOption, optionsInterface, stabilizationExclusionRules } from './options';
+import { includeComponent } from './factory';
+import { Thumbmark } from './thumbmark';
+import { filterThumbmarkData } from './functions/filterComponents';
+import { stableStringify } from './utils/stableStringify';
+export { Thumbmark, getThumbmark, getVersion, ThumbmarkResponse, ThumbmarkError, filterThumbmarkData, optionsInterface, stabilizationExclusionRules, stableStringify, setOption, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent };

package/dist/types/options.d.ts

@@ -0,0 +1,76 @@
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export interface OptionsAfterDefaults {
+    /**
+     * A function to customise localStorage names used by thumbmark
+     * @param name Original name of the storage property eg. visitor_id
+     * @returns The name under which the storage property should be saved eg. myprefix_visitor_id
+     */
+    property_name_factory: (name: string) => string;
+    /**
+     * @deprecated use property_name_factory
+     */
+    storage_property_name?: string;
+    exclude?: string[];
+    include?: string[];
+    permissions_to_check?: PermissionName[];
+    timeout?: number;
+    logging?: boolean;
+    api_key?: string;
+    api_endpoint?: string;
+    /**
+     * @deprecated This will be removed in Thumbmarkjs 2.0, use cache_lifetime_in_ms instead
+     */
+    cache_api_call?: boolean;
+    /**
+     * How long the cache will be valid for, maximum is 72h (259_200_000)
+     */
+    cache_lifetime_in_ms: number;
+    performance?: boolean;
+    stabilize?: string[];
+    experimental?: boolean;
+    /**
+     * Optional metadata to pass through to the API and webhooks.
+     * Can be a static JSON object or a function that returns a JSON object (evaluated at request time).
+     * This field is excluded from fingerprint calculation.
+     * Maximum length: 1000 characters when stringified.
+     * @example metadata: { userId: "123", eventType: "login" }
+     * @example metadata: () => ({ timestamp: Date.now(), sessionId: "abc" })
+     */
+    metadata?: JSONValue | (() => JSONValue);
+}
+export type optionsInterface = Partial<OptionsAfterDefaults>;
+export declare const DEFAULT_CACHE_LIFETIME = 0;
+export declare const MAXIMUM_CACHE_LIFETIME = 259200000;
+export declare const DEFAULT_STORAGE_PREFIX = "thumbmark";
+export declare const DEFAULT_API_ENDPOINT = "https://api.thumbmarkjs.com";
+export declare const defaultOptions: OptionsAfterDefaults;
+export declare let options: OptionsAfterDefaults;
+/**
+ *
+ * @param key @deprecated this function will be removed
+ * @param value
+ */
+export declare function setOption<K extends keyof optionsInterface>(key: K, value: OptionsAfterDefaults[K]): void;
+export declare const stabilizationExclusionRules: {
+    private: {
+        exclude: string[];
+        browsers: string[];
+    }[];
+    iframe: ({
+        exclude: string[];
+        browsers: string[];
+    } | {
+        exclude: string[];
+        browsers?: undefined;
+    })[];
+    vpn: {
+        exclude: string[];
+    }[];
+    always: {
+        exclude: string[];
+        browsers: string[];
+    }[];
+};
+export {};

package/dist/types/thumbmark.d.ts

@@ -0,0 +1,28 @@
+import { optionsInterface } from "./options";
+import { ThumbmarkResponse } from './functions';
+import { componentInterface } from "./factory";
+/**
+ * A client for generating thumbmarks with a persistent configuration.
+ */
+export declare class Thumbmark {
+    private options;
+    private customComponents;
+    /**
+     * Creates a new Thumbmarker client instance.
+     * @param options - Default configuration options for this instance.
+     */
+    constructor(options?: optionsInterface);
+    /**
+     * Generates a thumbmark using the instance's configuration.
+     * @param overrideOptions - Options to override for this specific call.
+     * @returns The thumbmark result containing the fingerprint hash, components, and metadata.
+     */
+    get(overrideOptions?: optionsInterface): Promise<ThumbmarkResponse>;
+    getVersion(): string;
+    /**
+     * Register a custom component to be included in the fingerprint.
+     * @param key - The component name
+     * @param fn - The component function
+     */
+    includeComponent(key: string, fn: (options?: optionsInterface) => Promise<componentInterface | null>): void;
+}

package/dist/types/utils/cache.d.ts

@@ -0,0 +1,23 @@
+import { apiResponse } from "../functions/api";
+import { OptionsAfterDefaults } from "../options";
+export declare const CACHE_KEY = "cache";
+export interface Cache {
+    apiResponse?: apiResponse;
+    apiResponseExpiry?: number;
+}
+/**
+ * Get all values from cache
+ * @param _options
+ */
+export declare function getCache(_options: Pick<OptionsAfterDefaults, 'property_name_factory'>): Cache;
+/**
+ * Write given values to cache
+ * @param _options
+ * @param values
+ */
+export declare function setCache(_options: OptionsAfterDefaults, values: Partial<Cache>): void;
+/**
+ * Returns the expiry time for cache
+ * @param _options
+ */
+export declare function getApiResponseExpiry(_options: Pick<OptionsAfterDefaults, 'cache_lifetime_in_ms'>): number;

package/dist/types/utils/commonPixels.d.ts

@@ -0,0 +1 @@
+export declare function getCommonPixels(images: ImageData[], width: number, height: number): ImageData;

package/dist/types/utils/ephemeralIFrame.d.ts

@@ -0,0 +1,4 @@
+export declare function ephemeralIFrame(callback: ({ iframe }: {
+    iframe: Document;
+}) => void): Promise<any>;
+export declare function wait<T = void>(durationMs: number, resolveWith?: T): Promise<T>;

package/dist/types/utils/getMostFrequent.d.ts

@@ -0,0 +1,5 @@
+export declare function mostFrequentValuesInArrayOfDictionaries(arr: {
+    [key: string]: any;
+}[], keys: string[]): {
+    [key: string]: any;
+};

package/dist/types/utils/hash.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This code is taken from https://github.com/LinusU/murmur-128/blob/master/index.js
+ * But instead of dependencies to encode-utf8 and fmix, I've implemented them here.
+ */
+export declare function hash(key: ArrayBuffer | string, seed?: number): string;

package/dist/types/utils/imageDataToDataURL.d.ts

@@ -0,0 +1 @@
+export declare function imageDataToDataURL(imageData: ImageData): string;

package/dist/types/utils/log.d.ts

@@ -0,0 +1,9 @@
+import { componentInterface } from '../factory';
+import { optionsInterface } from '../options';
+import type { ThumbmarkError } from '../functions';
+/**
+ * Logs thumbmark data to remote logging endpoint (only once per session)
+ * You can disable this by setting options.logging to false.
+ * @internal
+ */
+export declare function logThumbmarkData(thisHash: string, thumbmarkData: componentInterface, options: optionsInterface, experimentalData?: componentInterface, errors?: ThumbmarkError[]): Promise<void>;

package/dist/types/utils/raceAll.d.ts

@@ -0,0 +1,10 @@
+type DelayedPromise<T> = Promise<T>;
+export declare function delay<T>(t: number, val: T): DelayedPromise<T>;
+export interface RaceResult<T> {
+    value: T;
+    elapsed?: number;
+    error?: string;
+}
+export declare function raceAllPerformance<T>(promises: Promise<T>[], timeoutTime: number, timeoutVal: T): Promise<RaceResult<T>[]>;
+export declare function raceAll<T>(promises: Promise<T>[], timeoutTime: number, timeoutVal: T): Promise<(T | undefined)[]>;
+export {};

package/dist/types/utils/sort.d.ts

@@ -0,0 +1,8 @@
+import { componentInterface } from '../factory';
+/**
+ * Recursively sorts the keys of a component object alphabetically.
+ * This ensures a consistent order for hashing.
+ * @param obj The component object to sort.
+ * @returns A new object with sorted keys.
+ */
+export declare function sortComponentKeys(obj: componentInterface): componentInterface;

package/dist/types/utils/stableStringify.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stable JSON stringify implementation
+ * Based on fast-json-stable-stringify by Evgeny Poberezkin
+ * https://github.com/epoberezkin/fast-json-stable-stringify
+ *
+ * This implementation ensures consistent JSON serialization by sorting object keys,
+ * which is critical for generating stable hashes from fingerprint data.
+ */
+/**
+ * Converts data to a stable JSON string with sorted keys
+ *
+ * @param data - The data to stringify
+ * @returns Stable JSON string representation
+ * @throws TypeError if circular reference is detected
+ *
+ * @example
+ * ```typescript
+ * const obj = { b: 2, a: 1 };
+ * stableStringify(obj); // '{"a":1,"b":2}'
+ * ```
+ */
+export declare function stableStringify(data: any): string;

package/dist/types/utils/version.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns the current package version
+ */
+export declare function getVersion(): string;

package/dist/types/utils/visitorId.d.ts

@@ -0,0 +1,14 @@
+import { OptionsAfterDefaults } from "../options";
+/**
+ * Get the storage property name for visitor id
+ * @param _options
+ */
+export declare function getVisitorIdPropertyName(_options: Pick<OptionsAfterDefaults, 'storage_property_name' | 'property_name_factory'>): string;
+/**
+ * Gets visitor ID from localStorage, returns null if unavailable
+ */
+export declare function getVisitorId(_options: OptionsAfterDefaults): string | null;
+/**
+ * Sets visitor ID in localStorage
+ */
+export declare function setVisitorId(visitorId: string, _options: OptionsAfterDefaults): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thumbmarkjs/thumbmarkjs",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "",
   "type": "module",
   "main": "./dist/thumbmark.cjs.js",
@@ -22,7 +22,8 @@
     "test": "jest",
     "test:e2e": "npx playwright test",
     "build": "rm -rf dist/* && rm -rf types/* && rollup -c",
-    "watch": "rollup -c -w"
+    "watch": "rollup -c -w",
+    "perf": "playwright test perf/perf.spec.ts"
   },
   "keywords": [
     "thumbmark",

package/src/functions/filterComponents.test.ts

@@ -161,6 +161,17 @@ describe('getExcludeList', () => {
         // Should not throw
         expect(() => getExcludeList({ ...defaultOptions }, obj)).not.toThrow();
     });
+
+    test('non-array string exclude does not throw and is ignored', () => {
+        const result = getExcludeList({ ...defaultOptions, exclude: 'one' as any, stabilize: [] });
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).not.toContain('one');
+    });
+
+    test('non-array object exclude does not throw and is ignored', () => {
+        const result = getExcludeList({ ...defaultOptions, exclude: {} as any, stabilize: [] });
+        expect(Array.isArray(result)).toBe(true);
+    });
 });
 
 // ── filterThumbmarkData ─────────────────────────────────────────
@@ -235,4 +246,28 @@ describe('filterThumbmarkData', () => {
         expect((result.audio as componentInterface).other).toBe('jkl');
         expect((result.audio as componentInterface).sampleHash).toBeUndefined();
     });
+
+    test('non-array string include does not throw and does not rescue excluded keys', () => {
+        const result = filterThumbmarkData(testData, {
+            ...defaultOptions,
+            exclude: ['one'],
+            include: 'one' as any,
+            stabilize: [],
+        });
+        // Bad include is treated as empty, so 'one' stays excluded
+        expect(result.one).toBeUndefined();
+        expect(result.two).toBe(2);
+    });
+
+    test('null include does not throw and behaves as empty include', () => {
+        const result = filterThumbmarkData(testData, {
+            ...defaultOptions,
+            exclude: ['two'],
+            include: null as any,
+            stabilize: [],
+        });
+        // null include treated as empty, so 'two' stays excluded
+        expect(result.two).toBeUndefined();
+        expect(result.one).toBe('1');
+    });
 });

package/src/functions/filterComponents.ts

@@ -27,7 +27,7 @@ export function getExcludeList(options?: optionsInterface, obj?: componentInterf
 
     const name = browser.name.toLowerCase();
     const majorVer = parseInt(browser.version.split('.')[0] || '0', 10);
-    const excludeList = [...(options?.exclude || [])];
+    const excludeList = Array.isArray(options?.exclude) ? [...options.exclude] : [];
     const stabilizationOptions = [...new Set([...(options?.stabilize || []), 'always'])];
 
     for (const option of stabilizationOptions) {
@@ -52,7 +52,7 @@ export function filterThumbmarkData(
     options?: optionsInterface,
 ): componentInterface {
     const excludeList = getExcludeList(options, obj);
-    const includeList = options?.include || [];
+    const includeList = Array.isArray(options?.include) ? options.include : [];
 
     /**
      * Inner recursive function to perform the actual filtering.
@@ -84,6 +84,5 @@ export function filterThumbmarkData(
         return result;
     }
 
-    // Start the filtering process
     return performFilter(obj);
 }