@thumbmarkjs/thumbmarkjs 1.1.3-rc.7 → 1.3.0

package/src/functions/index.ts

@@ -4,22 +4,15 @@
  * This module handles component collection, API calls, uniqueness scoring, and data filtering
  * for the ThumbmarkJS browser fingerprinting library.
  *
- * Exports:
- *   - getThumbmark
- *   - getThumbmarkDataFromPromiseMap
- *   - resolveClientComponents
- *   - filterThumbmarkData
- *
- * Internal helpers and types are also defined here.
  */
 
-// ===================== Imports =====================
 import { defaultOptions, optionsInterface } from "../options";
 import { 
     timeoutInstance,
     componentInterface,
     tm_component_promises,
     customComponents,
+    tm_experimental_component_promises,
     includeComponent as globalIncludeComponent
 } from "../factory";
 import { hash } from "../utils/hash";
@@ -27,43 +20,8 @@ import { raceAllPerformance } from "../utils/raceAll";
 import { getVersion } from "../utils/version";
 import { filterThumbmarkData } from './filterComponents'
 import { logThumbmarkData } from '../utils/log';
-import { API_ENDPOINT } from "../options";
-import { getVisitorId, setVisitorId } from "../utils/visitorId";
-
-// ===================== 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,
-        vpn: boolean,
-        bot: boolean,
-        datacenter: boolean,
-        danger_level: number, // 5 is highest and should be blocked. 0 is no danger.
-    },
-    uniqueness?: {
-        score: number | string
-    },
-    timed_out?: boolean; // added for timeout handling
-}
+import { getApiPromise, infoInterface } from "./api";
 
-/**
- * API response structure
- */
-interface apiResponse {
-    info?: infoInterface;
-    version?: string;
-    components?: componentInterface;
-    visitorId?: string;
-}
 
 /**
  * Final thumbmark response structure
@@ -74,101 +32,11 @@ interface thumbmarkResponse {
     version: string,
     thumbmark: string,
     visitorId?: string,
-    /**
-     * Only present if options.performance is true.
-     */
     elapsed?: any;
+    error?: string;
+    experimental?: componentInterface;
 }
 
-
-
-// ===================== 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 with timeout.
-    const endpoint = `${API_ENDPOINT}/thumbmark`;
-    const visitorId = getVisitorId();
-    const requestBody: any = { 
-        components, 
-        options, 
-        clientHash: hash(JSON.stringify(components)), 
-        version: getVersion()
-    };
-    if (visitorId) {
-        requestBody.visitorId = visitorId;
-    }
-    
-    const fetchPromise = fetch(endpoint, {
-        method: 'POST',
-        headers: {
-            'x-api-key': options.api_key!,
-            'Authorization': 'custom-authorized',
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(requestBody),
-    })
-        .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 => {
-            // Handle visitor ID from server response
-            if (data.visitorId && data.visitorId !== visitorId) {
-                setVisitorId(data.visitorId);
-            }
-            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;
-        });
-
-    // Timeout logic
-    const timeoutMs = options.timeout || 5000;
-    const timeoutPromise = new Promise<apiResponse>((resolve) => {
-        setTimeout(() => {
-            resolve({
-                info: { timed_out: true },
-                version: getVersion(),
-            });
-        }, timeoutMs);
-    });
-
-    currentApiPromise = Promise.race([fetchPromise, timeoutPromise]);
-    return currentApiPromise;
-};
-
-// ===================== Main Thumbmark Logic =====================
-
-
-
 /**
  * Main entry point: collects all components, optionally calls API, and returns thumbmark data.
  *
@@ -177,12 +45,41 @@ export const getApiPromise = (
  */
 export async function getThumbmark(options?: optionsInterface): Promise<thumbmarkResponse> {
     const _options = { ...defaultOptions, ...options };
+       
+    // Early logging decision
+    const shouldLog = (!sessionStorage.getItem("_tmjs_l") && Math.random() < 0.0001);
+    
     // Merge built-in and user-registered components
     const allComponents = { ...tm_component_promises, ...customComponents };
     const { elapsed, resolvedComponents: clientComponentsResult } = await resolveClientComponents(allComponents, _options);
 
+    // Resolve experimental components only when logging
+    let experimentalComponents = {};
+    if (shouldLog || _options.experimental) {
+        const { resolvedComponents } = await resolveClientComponents(tm_experimental_component_promises, _options);
+        experimentalComponents = resolvedComponents;
+    }
+
     const apiPromise = _options.api_key ? getApiPromise(_options, clientComponentsResult) : null;
-    const apiResult = apiPromise ? await apiPromise : null;
+    let apiResult = null;
+    
+    if (apiPromise) {
+        try {
+            apiResult = await apiPromise;
+        } catch (error) {
+            // Handle API key/quota errors
+            if (error instanceof Error && error.message === 'INVALID_API_KEY') {
+                return {
+                    error: 'Invalid API key or quota exceeded',
+                    components: {},
+                    info: {},
+                    version: getVersion(),
+                    thumbmark: ''
+                };
+            }
+            throw error; // Re-throw other errors
+        }
+    }
 
     // Only add 'elapsed' if performance is true
     const maybeElapsed = _options.performance ? { elapsed } : {};
@@ -191,7 +88,10 @@ export async function getThumbmark(options?: optionsInterface): Promise<thumbmar
     const info: infoInterface = apiResult?.info || { uniqueness: { score: 'api only' } };
     const thumbmark = hash(JSON.stringify(components));
     const version = getVersion();
-    logThumbmarkData(thumbmark, components, _options).catch(() => { /* do nothing */ });
+    // Only log to server when not in debug mode
+    if (shouldLog) {
+        logThumbmarkData(thumbmark, components, _options, experimentalComponents).catch(() => { /* do nothing */ });
+    }
     
     const result: thumbmarkResponse = {
         ...(apiResult?.visitorId && { visitorId: apiResult.visitorId }),
@@ -200,6 +100,7 @@ export async function getThumbmark(options?: optionsInterface): Promise<thumbmar
         info,
         version,
         ...maybeElapsed,
+        ...(Object.keys(experimentalComponents).length > 0 && _options.experimental && { experimental: experimentalComponents }),
     };
     
     return result;
@@ -244,6 +145,4 @@ export async function resolveClientComponents(
   return { elapsed, resolvedComponents };
 }
 
-
-
 export { globalIncludeComponent as includeComponent };

package/src/options.ts

@@ -8,6 +8,7 @@ export interface optionsInterface {
     cache_api_call?: boolean,
     performance?: boolean,
     stabilize?: string[],
+    experimental?: boolean,
 }
 
 export const API_ENDPOINT = 'https://api.thumbmarkjs.com';
@@ -19,7 +20,8 @@ export const defaultOptions: optionsInterface = {
     logging: true,
     timeout: 5000,
     cache_api_call: true,
-    performance: false
+    performance: false,
+    experimental: false,
     };
 
 export let options = {...defaultOptions};

package/src/utils/log.ts

@@ -10,11 +10,12 @@ import { API_ENDPOINT } from '../options';
  * You can disable this by setting options.logging to false.
  * @internal
  */
-export async function logThumbmarkData(thisHash: string, thumbmarkData: componentInterface, options: optionsInterface): Promise<void> {
+export async function logThumbmarkData(thisHash: string, thumbmarkData: componentInterface, options: optionsInterface, experimentalData: componentInterface = {}): Promise<void> {
     const url = `${API_ENDPOINT}/log`;
     const payload = {
         thumbmark: thisHash,
         components: thumbmarkData,
+        experimental: experimentalData,
         version: getVersion(),
         options,
         path: window?.location?.pathname,

package/dist/types/components/audio/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getAudio(): Promise<componentInterface | null>;

package/dist/types/components/canvas/index.d.ts

@@ -1,3 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getCanvas(): Promise<componentInterface | null>;
-export declare function generateCanvasFingerprint(): Promise<componentInterface>;

package/dist/types/components/fonts/index.d.ts

@@ -1,4 +0,0 @@
-import { componentInterface } from '../../factory';
-import { optionsInterface } from '../../options';
-export default function getFonts(options?: optionsInterface): Promise<componentInterface | null>;
-export declare function getFontMetrics(): Promise<componentInterface>;

package/dist/types/components/hardware/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getHardware(): Promise<componentInterface>;

package/dist/types/components/locales/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getLocales(): Promise<componentInterface>;

package/dist/types/components/math/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getMath(): Promise<componentInterface>;

package/dist/types/components/permissions/index.d.ts

@@ -1,3 +0,0 @@
-import { componentInterface } from '../../factory';
-import { optionsInterface } from '../../options';
-export default function getPermissions(options?: optionsInterface): Promise<componentInterface>;

package/dist/types/components/plugins/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getPlugins(): Promise<componentInterface | null>;

package/dist/types/components/screen/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getScreen(): Promise<componentInterface>;

package/dist/types/components/system/browser.d.ts

@@ -1,7 +0,0 @@
-interface BrowserResult {
-    name: string;
-    version: string;
-}
-export declare function getBrowser(): BrowserResult;
-export declare function isMobileUserAgent(): boolean;
-export {};

package/dist/types/components/system/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getSystem(): Promise<componentInterface>;

package/dist/types/components/webgl/index.d.ts

@@ -1,2 +0,0 @@
-import { componentInterface } from '../../factory';
-export default function getWebGL(): Promise<componentInterface>;

package/dist/types/factory.d.ts

@@ -1,51 +0,0 @@
-/**
- * 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";
-/**
- * @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;
-};
-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/filterComponents.d.ts

@@ -1,10 +0,0 @@
-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
- */
-export declare function filterThumbmarkData(obj: componentInterface, options?: optionsInterface): componentInterface;

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

@@ -1,89 +0,0 @@
-/**
- * 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
- *   - filterThumbmarkData
- *
- * Internal helpers and types are also defined here.
- */
-import { optionsInterface } from "../options";
-import { componentInterface, includeComponent as globalIncludeComponent } from "../factory";
-/**
- * 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;
-        vpn: boolean;
-        bot: boolean;
-        datacenter: boolean;
-        danger_level: number;
-    };
-    uniqueness?: {
-        score: number | string;
-    };
-    timed_out?: boolean;
-}
-/**
- * API response structure
- */
-interface apiResponse {
-    info?: infoInterface;
-    version?: string;
-    components?: componentInterface;
-    visitorId?: string;
-}
-/**
- * Final thumbmark response structure
- */
-interface thumbmarkResponse {
-    components: componentInterface;
-    info: {
-        [key: string]: any;
-    };
-    version: string;
-    thumbmark: string;
-    visitorId?: string;
-    /**
-     * Only present if options.performance is true.
-     */
-    elapsed?: any;
-}
-/**
- * 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: optionsInterface, components: componentInterface) => Promise<apiResponse | null>;
-/**
- * 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): 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 and filtered resolved components
- */
-export declare function resolveClientComponents(comps: {
-    [key: string]: (options?: optionsInterface) => Promise<componentInterface | null>;
-}, options?: optionsInterface): Promise<{
-    elapsed: Record<string, number>;
-    resolvedComponents: componentInterface;
-}>;
-export { globalIncludeComponent as includeComponent };

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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-import { getFingerprint, getFingerprintData, getFingerprintPerformance } from './functions/legacy_functions';
-import { getThumbmark } 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';
-export { Thumbmark, getThumbmark, getVersion, filterThumbmarkData, optionsInterface, stabilizationExclusionRules, setOption, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent };

package/dist/types/options.d.ts

@@ -1,43 +0,0 @@
-export interface optionsInterface {
-    exclude?: string[];
-    include?: string[];
-    permissions_to_check?: PermissionName[];
-    timeout?: number;
-    logging?: boolean;
-    api_key?: string;
-    cache_api_call?: boolean;
-    performance?: boolean;
-    stabilize?: string[];
-}
-export declare const API_ENDPOINT = "https://api.thumbmarkjs.com";
-export declare const defaultOptions: optionsInterface;
-export declare let options: {
-    exclude?: string[] | undefined;
-    include?: string[] | undefined;
-    permissions_to_check?: PermissionName[] | undefined;
-    timeout?: number | undefined;
-    logging?: boolean | undefined;
-    api_key?: string | undefined;
-    cache_api_call?: boolean | undefined;
-    performance?: boolean | undefined;
-    stabilize?: string[] | undefined;
-};
-/**
- *
- * @param key @deprecated this function will be removed
- * @param value
- */
-export declare function setOption<K extends keyof optionsInterface>(key: K, value: optionsInterface[K]): void;
-export declare const stabilizationExclusionRules: {
-    private: {
-        exclude: string[];
-        browsers: string[];
-    }[];
-    iframe: {
-        exclude: string[];
-        browsers: string[];
-    }[];
-    vpn: {
-        exclude: string[];
-    }[];
-};

package/dist/types/thumbmark.d.ts

@@ -1,26 +0,0 @@
-import { optionsInterface } from "./options";
-import { componentInterface } from "./factory";
-/**
- * A client for generating thumbmarks with a persistent configuration.
- */
-export declare class Thumbmark {
-    private options;
-    /**
-     * 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.
-     */
-    get(overrideOptions?: optionsInterface): Promise<any>;
-    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/commonPixels.d.ts

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

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

@@ -1,4 +0,0 @@
-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

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

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

@@ -1,5 +0,0 @@
-/**
- * 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

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

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

@@ -1,8 +0,0 @@
-import { componentInterface } from '../factory';
-import { optionsInterface } from '../options';
-/**
- * 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): Promise<void>;

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

@@ -1,9 +0,0 @@
-type DelayedPromise<T> = Promise<T>;
-export declare function delay<T>(t: number, val: T): DelayedPromise<T>;
-export interface RaceResult<T> {
-    value: T;
-    elapsed?: number;
-}
-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

@@ -1,8 +0,0 @@
-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/version.d.ts

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