@thumbmarkjs/thumbmarkjs 1.0.0 → 1.1.0-rc.1

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

@@ -0,0 +1,87 @@
+/**
+ * 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;
+        proxy: boolean;
+        datacenter: boolean;
+        danger_level: number;
+    };
+    uniqueness?: {
+        score: number | string;
+    };
+    timed_out?: boolean;
+}
+/**
+ * API response structure
+ */
+interface apiResponse {
+    thumbmark?: string;
+    info?: infoInterface;
+    version?: string;
+    components?: componentInterface;
+}
+/**
+ * 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;
+}
+/**
+ * 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

@@ -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,7 @@
+import { getFingerprint, getFingerprintData, getFingerprintPerformance } from './functions/legacy_functions';
+import { getThumbmark } from './functions';
+import { getVersion } from './utils/version';
+import { setOption } from './options';
+import { includeComponent } from './factory';
+import { Thumbmark } from './thumbmark';
+export { Thumbmark, getThumbmark, getVersion, setOption, getFingerprint, getFingerprintData, getFingerprintPerformance, includeComponent };

package/dist/types/options.d.ts

@@ -0,0 +1,28 @@
+export interface optionsInterface {
+    exclude?: string[];
+    include?: string[];
+    permissions_to_check?: PermissionName[];
+    timeout?: number;
+    logging?: boolean;
+    api_key?: string;
+    cache_api_call?: boolean;
+    performance?: boolean;
+}
+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;
+};
+/**
+ *
+ * @param key @deprecated this function will be removed
+ * @param value
+ */
+export declare function setOption<K extends keyof optionsInterface>(key: K, value: optionsInterface[K]): void;

package/dist/types/thumbmark.d.ts

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

@@ -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,8 @@
+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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thumbmarkjs/thumbmarkjs",
-  "version": "1.0.0",
+  "version": "1.1.0-rc.1",
   "description": "",
   "type": "module",
   "main": "./dist/thumbmark.cjs.js",

package/src/components/canvas/index.ts

@@ -20,7 +20,7 @@ export default async function getCanvas(): Promise<componentInterface | null> {
   const name = browser.name.toLowerCase();
   const ver = browser.version.split('.')[0] || '0';
   const majorVer = parseInt(ver, 10);
-  if (name !== 'firefox' && !(name === 'safari' && majorVer >= 17))
+  if (!['firefox', 'brave'].includes(name) && !(name === 'safari' && majorVer >= 17))
     return generateCanvasFingerprint()
   return null;
 }

package/src/components/plugins/index.ts

@@ -1,20 +1,29 @@
 import { componentInterface, includeComponent } from '../../factory'
+import { getBrowser } from '../system/browser';
 
-export default function getPlugins(): Promise<componentInterface> {
-    const plugins: string[] = [];
-  
-    if (navigator.plugins) {
-      for (let i = 0; i < navigator.plugins.length; i++) {
-        const plugin = navigator.plugins[i];
-        plugins.push([plugin.name, plugin.filename, plugin.description ].join("|"));
-      }
+export default async function getPlugins(): Promise<componentInterface | null> {
+  const browser = getBrowser();
+  const name = browser.name.toLowerCase();
+
+  // Brave will scramble the plugins list, so not including it.
+  if (['brave'].includes(name)) {
+    return null;
+  }
+
+  const plugins: string[] = [];
+
+  if (navigator.plugins) {
+    for (let i = 0; i < navigator.plugins.length; i++) {
+      const plugin = navigator.plugins[i];
+      plugins.push([plugin.name, plugin.filename, plugin.description ].join("|"));
     }
-  
-    return new Promise((resolve) => {
-      resolve(
-        {
-          'plugins': plugins
-        }
-      );
-  });
-  }
+  }
+
+  return new Promise((resolve) => {
+    resolve(
+      {
+        'plugins': plugins
+      }
+    );
+});
+}

package/src/functions/index.ts

@@ -8,7 +8,6 @@
  *   - getThumbmark
  *   - getThumbmarkDataFromPromiseMap
  *   - resolveClientComponents
- *   - getVersion
  *   - filterThumbmarkData
  *
  * Internal helpers and types are also defined here.
@@ -25,8 +24,10 @@ import {
 } from "../factory";
 import { hash } from "../utils/hash";
 import { raceAllPerformance } from "../utils/raceAll";
-import * as packageJson from '../../package.json';
+import { getVersion } from "../utils/version";
 import { filterThumbmarkData } from './filterComponents'
+import { logThumbmarkData } from '../utils/log';
+import { API_ENDPOINT } from "../options";
 
 // ===================== Types & Interfaces =====================
 
@@ -42,7 +43,7 @@ interface infoInterface {
     },
     classification?: {
         tor: boolean,
-        proxy: boolean, // i.e. vpn and 
+        proxy: boolean, 
         datacenter: boolean,
         danger_level: number, // 5 is highest and should be blocked. 0 is no danger.
     },
@@ -59,6 +60,7 @@ interface apiResponse {
     thumbmark?: string;
     info?: infoInterface;
     version?: string;
+    components?: componentInterface;
 }
 
 /**
@@ -75,14 +77,7 @@ interface thumbmarkResponse {
     elapsed?: any;
 }
 
-// ===================== Version =====================
 
-/**
- * Returns the current package version
- */
-export function getVersion(): string {
-    return packageJson.version;
-}
 
 // ===================== API Call Logic =====================
 
@@ -108,14 +103,15 @@ export const getApiPromise = (
     }
 
     // 3. Otherwise, initiate a new API call with timeout.
-    const endpoint = 'https://api.thumbmarkjs.com/thumbmark';
+    const endpoint = `${API_ENDPOINT}/thumbmark`;
     const fetchPromise = fetch(endpoint, {
         method: 'POST',
         headers: {
             'x-api-key': options.api_key!,
             'Authorization': 'custom-authorized',
+            'Content-Type': 'application/json',
         },
-        body: JSON.stringify({ components: components, clientHash: hash(JSON.stringify(components)) }),
+        body: JSON.stringify({ components, options, clientHash: hash(JSON.stringify(components)) }),
     })
         .then(response => {
             // Handle HTTP errors that aren't network errors
@@ -143,7 +139,7 @@ export const getApiPromise = (
             resolve({
                 thumbmark: hash(JSON.stringify(components)),
                 info: { timed_out: true },
-                version: packageJson.version,
+                version: getVersion(),
             });
         }, timeoutMs);
     });
@@ -171,24 +167,16 @@ export async function getThumbmark(options?: optionsInterface): Promise<thumbmar
 
     // 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,
-        };
-    }
+    const components = {...clientComponentsResult, ...apiResult?.components || {}};
+    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 */ });
     return {
-        thumbmark: hash(JSON.stringify(clientComponentsResult)),
-        components: clientComponentsResult,
-        info: {
-            uniqueness: 'api only'
-        },
-        version: getVersion(),
+        thumbmark,
+        components: components,
+        info,
+        version,
         ...maybeElapsed,
     };
 }
@@ -232,31 +220,6 @@ export async function resolveClientComponents(
   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/index.ts

@@ -3,7 +3,8 @@ import {
     getFingerprintData,
     getFingerprintPerformance
  } from './functions/legacy_functions'
-import { getThumbmark, getVersion } from './functions'
+import { getThumbmark } from './functions'
+import { getVersion } from './utils/version';
 import { setOption } from './options'
 import { includeComponent } from './factory'
 import { Thumbmark } from './thumbmark'

package/src/options.ts

@@ -6,16 +6,18 @@ export interface optionsInterface {
     logging?: boolean,
     api_key?: string,
     cache_api_call?: boolean,
-    performance?: boolean, // re-added
+    performance?: boolean,
 }
 
+export const API_ENDPOINT = 'https://api.thumbmarkjs.com';
+
 export const defaultOptions: optionsInterface = {
     exclude: [],
     include: [],
     logging: true,
     timeout: 5000,
     cache_api_call: true,
-    performance: false // re-added
+    performance: false
     };
 
 export let options = {...defaultOptions};

package/src/thumbmark.ts

@@ -1,5 +1,6 @@
 import { optionsInterface } from "./options";
-import { getThumbmark, getVersion, includeComponent as globalIncludeComponent } from './functions';
+import { getThumbmark, includeComponent as globalIncludeComponent } from './functions';
+import { getVersion } from "./utils/version";
 import { defaultOptions } from "./options";
 import { componentInterface } from "./factory";
 

package/src/utils/log.ts

@@ -0,0 +1,34 @@
+import { componentInterface } from '../factory';
+import { optionsInterface } from '../options';
+import { getVersion } from './version';
+import { API_ENDPOINT } from '../options';
+
+// ===================== Logging (Internal) =====================
+
+/**
+ * Logs thumbmark data to remote logging endpoint (only once per session)
+ * You can disable this by setting options.logging to false.
+ * @internal
+ */
+export async function logThumbmarkData(thisHash: string, thumbmarkData: componentInterface, options: optionsInterface): Promise<void> {
+    const url = `${API_ENDPOINT}/log`;
+    const payload = {
+        thumbmark: thisHash,
+        components: thumbmarkData,
+        version: getVersion(),
+        options,
+        path: window?.location?.pathname,
+    };
+    if (!sessionStorage.getItem("_tmjs_l") && Math.random() < 0.0001) { // Only log once per session and very rarely
+        sessionStorage.setItem("_tmjs_l", "1");
+        try {
+            await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(payload)
+            });
+        } catch { /* do nothing */ }
+    }
+}

package/src/utils/version.ts

@@ -0,0 +1,8 @@
+import * as packageJson from '../../package.json';
+
+/**
+ * Returns the current package version
+ */
+export function getVersion(): string {
+    return packageJson.version;
+}