@thumbmarkjs/thumbmarkjs 1.8.1 → 1.9.1

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.8.1",
+  "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/components/audio/index.ts

@@ -51,7 +51,6 @@ async function createAudioFingerprint(): Promise<componentInterface> {
       
   
     } catch (error) {
-      console.error('Error creating audio fingerprint:', error);
       reject(error);
     }
   

package/src/components/system/browser.ts

@@ -10,6 +10,15 @@ interface BrowserDetectionStrategy {
   detect: () => boolean;
 }
 
+// Module-scoped cache keyed on brave-marker + UA string.
+// Brave masks its UA so we must distinguish brave vs non-brave for the same UA.
+const browserCache = new Map<string, BrowserResult>();
+
+/** Test-only: reset the memoization cache between test runs. */
+export function __resetBrowserCache(): void {
+  browserCache.clear();
+}
+
 // Define a function to parse the user agent string and return the browser name and version
 export function getBrowser(): BrowserResult {
   if (typeof navigator === 'undefined') {
@@ -19,23 +28,34 @@ export function getBrowser(): BrowserResult {
     }
   }
 
+  const isBrave = !!(navigator as any).brave;
+  const cacheKey = (isBrave ? 'B|' : 'N|') + navigator.userAgent;
+  const cached = browserCache.get(cacheKey);
+  if (cached) return cached;
+
   // Check for privacy browsers first (these mask their user agent)
   const privacyBrowserStrategies: BrowserDetectionStrategy[] = [
     {
       name: 'Brave',
-      detect: () => !!(navigator as any).brave
+      detect: () => isBrave
     }
   ];
 
+  let result: BrowserResult;
+
   for (const strategy of privacyBrowserStrategies) {
     if (strategy.detect()) {
-      const result = parseBrowserFromUA(navigator.userAgent);
-      return { name: strategy.name, version: result.version };
+      const parsed = parseBrowserFromUA(navigator.userAgent);
+      result = { name: strategy.name, version: parsed.version };
+      browserCache.set(cacheKey, result);
+      return result;
     }
   }
 
   // Fall back to user agent parsing for standard browsers
-  return parseBrowserFromUA(navigator.userAgent);
+  result = parseBrowserFromUA(navigator.userAgent);
+  browserCache.set(cacheKey, result);
+  return result;
 }
 
 // Parse browser from user agent string