@thumbmarkjs/thumbmarkjs
Version:
   • 8.6 kB
TypeScript
type JSONValue = string | number | boolean | null | JSONValue[] | {
[key: string]: JSONValue;
};
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);
}
type optionsInterface = Partial<OptionsAfterDefaults>;
/**
*
* @param key @deprecated this function will be removed
* @param value
*/
declare function setOption<K extends keyof optionsInterface>(key: K, value: OptionsAfterDefaults[K]): void;
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[];
}[];
};
/**
* This file is used to create the includeComponent function as well as the interfaces each of the
* fingerprint components must implement.
*
*/
interface componentInterface {
[key: string]: string | string[] | number | boolean | componentInterface;
}
interface componentFunctionInterface {
(options?: optionsInterface): Promise<componentInterface | null>;
}
/**
* 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
*/
declare const includeComponent: (name: string, creationFunction: componentFunctionInterface, options?: optionsInterface) => void;
/**
* This file is here to support legacy implementations.
* Eventually, these functions will be removed to keep the library small.
*/
/**
*
* @deprecated
*/
declare function getFingerprintData(): Promise<componentInterface>;
/**
*
* @param includeData boolean
* @deprecated this function is going to be removed. use getThumbmark or Thumbmark class instead.
*/
declare function getFingerprint(includeData?: false): Promise<string>;
declare function getFingerprint(includeData: true): Promise<{
hash: string;
data: componentInterface;
}>;
/**
*
* @deprecated use Thumbmark or getThumbmark instead with options
*/
declare function getFingerprintPerformance(): Promise<{
elapsed: Record<string, number>;
}>;
/**
* 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;
};
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;
}
/**
* ThumbmarkJS: Main fingerprinting and API logic
*
* This module handles component collection, API calls, uniqueness scoring, and data filtering
* for the ThumbmarkJS browser fingerprinting library.
*
*/
/**
* Final thumbmark response structure
*/
interface ThumbmarkError {
type: 'component_timeout' | 'component_error' | 'api_timeout' | 'api_error' | 'api_unauthorized' | 'network_error' | 'fatal';
message: string;
component?: string;
}
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)
*/
declare function getThumbmark(options?: optionsInterface, instanceCustomComponents?: Record<string, componentFunctionInterface | null>): Promise<ThumbmarkResponse>;
/**
* Returns the current package version
*/
declare function getVersion(): string;
/**
* A client for generating thumbmarks with a persistent configuration.
*/
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;
}
declare function filterThumbmarkData(obj: componentInterface, options?: optionsInterface): componentInterface;
/**
* 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}'
* ```
*/
declare function stableStringify(data: any): string;
export { Thumbmark, type ThumbmarkError, type ThumbmarkResponse, filterThumbmarkData, getFingerprint, getFingerprintData, getFingerprintPerformance, getThumbmark, getVersion, includeComponent, type optionsInterface, setOption, stabilizationExclusionRules, stableStringify };