@thumbmarkjs/thumbmarkjs 1.5.1 → 1.6.0

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, experimentalData?: componentInterface): 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/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.5.1",
+  "version": "1.6.0",
   "description": "",
   "type": "module",
   "main": "./dist/thumbmark.cjs.js",

package/src/functions/api.test.ts

@@ -0,0 +1,71 @@
+import {apiResponse, getCachedApiResponse, setCachedApiResponse} from "./api";
+import { defaultOptions } from "../options";
+import {getCache, setCache} from "../utils/cache";
+
+const options = {
+    ...defaultOptions,
+    cache_lifetime_in_ms: 100,
+}
+
+const apiResponse = {
+    identifier: 'test'
+} as apiResponse;
+
+describe('setCachedApiResponse', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    })
+
+    test('it should write the apiResponse to the cache if options allow that', () => {
+        setCachedApiResponse(options, apiResponse);
+        expect(getCache(options).apiResponse).toEqual(apiResponse);
+    });
+
+    test('it should not write if cache if off', () => {
+        setCachedApiResponse({
+            ...options,
+            cache_api_call: false,
+        }, apiResponse);
+
+        expect(getCache(options).apiResponse).not.toBeDefined();
+        expect(getCache(options).apiResponseExpiry).not.toBeDefined();
+    });
+
+    test('it should not write if lifetime is 0', () => {
+        setCachedApiResponse({
+            ...options,
+            cache_lifetime_in_ms: 0
+        }, apiResponse);
+
+        expect(getCache(options).apiResponse).not.toBeDefined();
+        expect(getCache(options).apiResponseExpiry).not.toBeDefined();
+    });
+})
+
+describe('getCachedApiResponse', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    })
+
+    test('it should get from the cache if a value exists there', () => {
+        setCache(options, {
+            apiResponseExpiry: Date.now() + 2000000,
+            apiResponse,
+        });
+
+        const cached = getCachedApiResponse(options);
+        expect(cached).toBeDefined();
+        expect(cached).toEqual(apiResponse);
+    });
+
+    test('it should not return an expiried cache', () => {
+        setCache(options, {
+            apiResponseExpiry: Date.now() - 2000,
+            apiResponse,
+        });
+
+        const cached = getCachedApiResponse(options);
+        expect(cached).not.toBeDefined();
+    })
+
+})

package/src/functions/api.ts

@@ -1,9 +1,10 @@
-import { optionsInterface, DEFAULT_API_ENDPOINT } from '../options';
+import { optionsInterface, DEFAULT_API_ENDPOINT, OptionsAfterDefaults} from '../options';
 import { componentInterface } from '../factory';
 import { getVisitorId, setVisitorId } from '../utils/visitorId';
 import { getVersion } from "../utils/version";
 import { hash } from '../utils/hash';
 import { stableStringify } from '../utils/stableStringify';
+import { getCache, getApiResponseExpiry, setCache } from "../utils/cache";
 
 // ===================== Types & Interfaces =====================
 
@@ -33,7 +34,7 @@ export interface infoInterface {
 /**
  * API response structure
  */
-interface apiResponse {
+export interface apiResponse {
     info?: infoInterface;
     version?: string;
     components?: componentInterface;
@@ -51,12 +52,21 @@ let apiPromiseResult: apiResponse | null = null;
  * Returns a promise for the API response or null on error.
  */
 export const getApiPromise = (
-    options: optionsInterface,
+    options: OptionsAfterDefaults,
     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);
+    if (options.cache_api_call) {
+        // Check the in-memory cache
+        if(apiPromiseResult) {
+            return Promise.resolve(apiPromiseResult);
+        }
+
+        // Check the localStorage cache
+        const cached = getCachedApiResponse(options);
+        if(cached) {
+            return Promise.resolve(cached);
+        }
     }
 
     // 2. If a request is already in flight, return that promise to prevent duplicate calls.
@@ -103,6 +113,7 @@ export const getApiPromise = (
                 setVisitorId(data.visitorId, options);
             }
             apiPromiseResult = data;      // Cache the successful result
+            setCachedApiResponse(options, data); // Cache to localStorage according to options
             currentApiPromise = null;     // Clear the in-flight promise
             return data;
         })
@@ -131,3 +142,36 @@ export const getApiPromise = (
     currentApiPromise = Promise.race([fetchPromise, timeoutPromise]);
     return currentApiPromise;
 };
+
+/**
+ * If a valid cached api response exists, returns it
+ * @param options
+ */
+export function getCachedApiResponse(
+    options: Pick<OptionsAfterDefaults, 'property_name_factory'>,
+): apiResponse | undefined {
+    const cache = getCache(options);
+    if (cache && cache.apiResponse && cache.apiResponseExpiry && Date.now() <= cache.apiResponseExpiry) {
+        return cache.apiResponse;
+    }
+
+    return;
+}
+
+/**
+ * Writes the api response to the cache according to the options
+ * @param options
+ * @param response
+ */
+export function setCachedApiResponse(
+    options: Pick<OptionsAfterDefaults, 'cache_api_call' | 'cache_lifetime_in_ms' | 'property_name_factory'>, response: apiResponse
+): void {
+    if(!options.cache_api_call || !options.cache_lifetime_in_ms) {
+        return;
+    }
+
+    setCache(options, {
+        apiResponseExpiry: getApiResponseExpiry(options),
+        apiResponse: response,
+    });
+}

package/src/functions/index.ts

@@ -6,7 +6,7 @@
  *
  */
 
-import { defaultOptions, optionsInterface } from "../options";
+import {defaultOptions, OptionsAfterDefaults, optionsInterface} from "../options";
 import {
   timeoutInstance,
   componentInterface,
@@ -45,7 +45,7 @@ interface thumbmarkResponse {
  * @returns thumbmarkResponse (elapsed is present only if options.performance is true)
  */
 export async function getThumbmark(options?: optionsInterface): Promise<thumbmarkResponse> {
-  const _options = { ...defaultOptions, ...options };
+  const _options = { ...defaultOptions, ...options } as OptionsAfterDefaults;
 
   // Early logging decision
   const shouldLog = (_options.logging && !sessionStorage.getItem("_tmjs_l") && Math.random() < 0.0001);

package/src/options.test.ts

@@ -0,0 +1,10 @@
+import { DEFAULT_STORAGE_PREFIX, defaultOptions } from "./options";
+
+describe('property_name_factory', () => {
+    test('it should default to the default value', () => {
+        const name = 'mykey';
+        expect(
+            defaultOptions.property_name_factory(name)
+        ).toEqual(`${DEFAULT_STORAGE_PREFIX}_${name}`);
+    })
+})

package/src/options.ts

@@ -1,4 +1,13 @@
-export interface optionsInterface {
+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[],
@@ -7,32 +16,49 @@ export interface optionsInterface {
     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,
 }
 
+export type optionsInterface = Partial<OptionsAfterDefaults>;
+
+// Default to zero to avoid breaking existing integrations
+export const DEFAULT_CACHE_LIFETIME = 0;
+export const MAXIMUM_CACHE_LIFETIME = 259_200_000;
+export const DEFAULT_STORAGE_PREFIX = 'thumbmark';
 export const DEFAULT_API_ENDPOINT = 'https://api.thumbmarkjs.com';
 
-export const defaultOptions: optionsInterface = {
+export const defaultOptions: OptionsAfterDefaults = {
     exclude: [],
     include: [],
     stabilize: ['private', 'iframe'],
     logging: true,
     timeout: 5000,
     cache_api_call: true,
+    cache_lifetime_in_ms: DEFAULT_CACHE_LIFETIME,
     performance: false,
     experimental: false,
+    property_name_factory: (name: string) => {
+        return `${DEFAULT_STORAGE_PREFIX}_${name}`;
+    },
 };
 
-export let options = { ...defaultOptions };
+export let options: OptionsAfterDefaults = { ...defaultOptions };
 /**
  * 
  * @param key @deprecated this function will be removed
  * @param value 
  */
-export function setOption<K extends keyof optionsInterface>(key: K, value: optionsInterface[K]) {
+export function setOption<K extends keyof optionsInterface>(key: K, value: OptionsAfterDefaults[K]) {
     options[key] = value;
 }
 

package/src/utils/cache.test.ts

@@ -0,0 +1,94 @@
+import { Cache, getCache, setCache, getApiResponseExpiry, CACHE_KEY } from "./cache";
+import { DEFAULT_STORAGE_PREFIX, defaultOptions, MAXIMUM_CACHE_LIFETIME } from "../options";
+
+const _options = {
+    property_name_factory: (name: string) => {
+        return `${name}-mypostfix`;
+    },
+    cache_lifetime_in_ms: 0,
+};
+
+const values: Cache = {
+    apiResponseExpiry: 100,
+    apiResponse: {
+        version: '1.2.3',
+    },
+};
+
+const cacheProperty = defaultOptions.property_name_factory(CACHE_KEY);
+const customCacheProperty = _options.property_name_factory(CACHE_KEY);
+
+describe('getCache', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    });
+
+    test('it should return all values from cache', () => {
+        localStorage.setItem(cacheProperty, JSON.stringify(values));
+        const fromStorage = getCache(defaultOptions);
+
+        expect(fromStorage).toEqual(values);
+    });
+
+    test('it should return an empty object in case of nothing cached', () => {
+        expect(getCache(defaultOptions)).toEqual({});
+    });
+
+    test('it should return an empty object in case non-json content', () => {
+        localStorage.setItem(cacheProperty, 'abc123');
+        expect(getCache(defaultOptions)).toEqual({});
+    });
+
+    test('it should return from the correct property', () => {
+        localStorage.setItem(cacheProperty, JSON.stringify(values));
+
+        expect(getCache(_options)).toEqual({});
+        expect(getCache(defaultOptions)).toEqual(values);
+    });
+})
+
+describe('setCache', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    });
+
+    test('it should write given values', () => {
+        setCache(defaultOptions, values);
+        expect(JSON.parse(localStorage.getItem(cacheProperty)!))
+            .toEqual(values);
+    });
+
+    test('it should not touch values that are not provided', () => {
+        setCache(_options, values);
+        setCache(_options, {
+            apiResponseExpiry: 200
+        });
+        const fromStorage = JSON.parse(localStorage.getItem(customCacheProperty)!) as Cache;
+        expect(fromStorage.apiResponseExpiry).toEqual(200);
+        expect(fromStorage.apiResponse!.version).toEqual(values.apiResponse!.version);
+    })
+})
+
+describe('getApiResponseExpiry', () => {
+    const systemTime = 1000;
+    beforeAll(() => {
+        jest.useFakeTimers().setSystemTime(systemTime);
+        localStorage.clear();
+    });
+
+    test('it should return a value based on options', () => {
+        expect(getApiResponseExpiry({
+            cache_lifetime_in_ms: 100,
+        })).toBe(systemTime + 100);
+    });
+
+    test('it should not go over maximum cache lifetime', () => {
+        expect(getApiResponseExpiry({
+            cache_lifetime_in_ms: MAXIMUM_CACHE_LIFETIME + 200,
+        })).toBe(systemTime + MAXIMUM_CACHE_LIFETIME);
+    })
+
+    afterAll(() => {
+        jest.useRealTimers()
+    })
+})

package/src/utils/cache.ts

@@ -0,0 +1,59 @@
+import { apiResponse } from "../functions/api";
+import { MAXIMUM_CACHE_LIFETIME, OptionsAfterDefaults } from "../options";
+
+export const CACHE_KEY = 'cache';
+
+export interface Cache {
+    apiResponse?: apiResponse
+    apiResponseExpiry?: number;
+}
+
+/**
+ * Get all values from cache
+ * @param _options
+ */
+export function getCache(_options: Pick<OptionsAfterDefaults, 'property_name_factory'>): Cache {
+    try {
+        const rawCache = localStorage.getItem(_options.property_name_factory(CACHE_KEY));
+        const jsonCache = JSON.parse(rawCache!);
+        if(!jsonCache) {
+            return {};
+        } else {
+            return jsonCache as Cache;
+        }
+    } catch {
+        // Ignore storage errors
+    }
+
+    return {};
+}
+
+/**
+ * Write given values to cache
+ * @param _options
+ * @param values
+ */
+export function setCache(_options: OptionsAfterDefaults, values: Partial<Cache>): void {
+    const newValues: Cache = {
+        ...getCache(_options),
+        ...values
+    };
+
+    try {
+        localStorage.setItem(_options.property_name_factory(CACHE_KEY), JSON.stringify(newValues));
+    } catch {
+        // Ignore storage errors
+    }
+}
+
+/**
+ * Returns the expiry time for cache
+ * @param _options
+ */
+export function getApiResponseExpiry(_options: Pick<OptionsAfterDefaults, 'cache_lifetime_in_ms'>): number {
+    if(_options.cache_lifetime_in_ms > MAXIMUM_CACHE_LIFETIME) {
+        return Date.now() + MAXIMUM_CACHE_LIFETIME;
+    }
+
+    return Date.now() + _options.cache_lifetime_in_ms;
+}

package/src/utils/visitorId.test.ts

@@ -1,5 +1,5 @@
 import { getVisitorId, setVisitorId } from './visitorId';
-import { optionsInterface, defaultOptions } from '../options';
+import { defaultOptions, options, OptionsAfterDefaults } from '../options';
 
 describe('visitorId storage tests', () => {
     beforeEach(() => {
@@ -21,7 +21,7 @@ describe('visitorId storage tests', () => {
 
         test('should use custom storage property name', () => {
             const visitorId = 'custom-visitor-456';
-            const customOptions: optionsInterface = {
+            const customOptions: OptionsAfterDefaults = {
                 ...defaultOptions,
                 storage_property_name: 'my_custom_visitor_key'
             };
@@ -37,7 +37,7 @@ describe('visitorId storage tests', () => {
         });
 
         test('should return null when storage property does not exist', () => {
-            const options: optionsInterface = {
+            const options: OptionsAfterDefaults = {
                 ...defaultOptions,
                 storage_property_name: 'nonexistent_key'
             };
@@ -56,6 +56,15 @@ describe('visitorId storage tests', () => {
             setVisitorId(newVisitorId, options);
             expect(getVisitorId(options)).toBe(newVisitorId);
         });
+
+        test('should migrate from old value in case new prefix is set', () => {
+            const visitorId = 'test-visitor-123';
+            setVisitorId(visitorId, options);
+            expect(getVisitorId({
+                property_name_factory: (name) => `custom_prefix_${name}`,
+            } as OptionsAfterDefaults)).toBe(visitorId);
+            expect(localStorage.getItem(`custom_prefix_visitor_id`)).toBe(visitorId);
+        })
     });
 
     describe('error handling', () => {

package/src/utils/visitorId.ts

@@ -1,18 +1,42 @@
-import { optionsInterface } from "../options";
+import { DEFAULT_STORAGE_PREFIX, OptionsAfterDefaults } from "../options";
 
 /**
  * Visitor ID storage utilities - localStorage only, server generates IDs
  */
 
-const DEFAULT_STORAGE_PROPERTY_NAME = 'thumbmark_visitor_id';
+const DEFAULT_STORAGE_PROPERTY_NAME = 'visitor_id';
 
+/**
+ * Get the storage property name for visitor id
+ * @param _options
+ */
+export function getVisitorIdPropertyName(
+    _options: Pick<OptionsAfterDefaults, 'storage_property_name' | 'property_name_factory'>
+): string {
+    if(_options.storage_property_name) {
+        return _options.storage_property_name;
+    }
+
+    return _options.property_name_factory(DEFAULT_STORAGE_PROPERTY_NAME);
+}
+
+const DEFAULT_VISITOR_ID_NAME = `${DEFAULT_STORAGE_PREFIX}_${DEFAULT_STORAGE_PROPERTY_NAME}`;
 /**
  * Gets visitor ID from localStorage, returns null if unavailable
  */
-export function getVisitorId(_options: optionsInterface): string | null {
-    const storagePropertyName = _options.storage_property_name || DEFAULT_STORAGE_PROPERTY_NAME;
+export function getVisitorId(_options: OptionsAfterDefaults): string | null {
     try {
-        return localStorage.getItem(storagePropertyName);
+        const propertyName = getVisitorIdPropertyName(_options);
+        let visitorId = localStorage.getItem(propertyName);
+        if(!visitorId && propertyName !== DEFAULT_VISITOR_ID_NAME) {
+            // Migration case in case going from thumbmark prefix to a custom one
+            visitorId = localStorage.getItem(DEFAULT_VISITOR_ID_NAME);
+            if(visitorId) {
+                setVisitorId(visitorId, _options);
+            }
+        }
+
+        return visitorId;
     } catch {
         return null;
     }
@@ -21,10 +45,9 @@ export function getVisitorId(_options: optionsInterface): string | null {
 /**
  * Sets visitor ID in localStorage
  */
-export function setVisitorId(visitorId: string, _options: optionsInterface): void {
-    const storagePropertyName = _options.storage_property_name || DEFAULT_STORAGE_PROPERTY_NAME;
+export function setVisitorId(visitorId: string, _options: OptionsAfterDefaults): void {
     try {
-        localStorage.setItem(storagePropertyName, visitorId);
+        localStorage.setItem(getVisitorIdPropertyName(_options), visitorId);
     } catch {
         // Ignore storage errors
     }