@thumbmarkjs/thumbmarkjs 1.6.3 → 1.6.4

package/src/functions/index.ts

@@ -6,7 +6,7 @@
  *
  */
 
-import {defaultOptions, OptionsAfterDefaults, optionsInterface} from "../options";
+import { defaultOptions, OptionsAfterDefaults, optionsInterface } from "../options";
 import {
   timeoutInstance,
   componentInterface,
@@ -27,24 +27,45 @@ import { stableStringify } from "../utils/stableStringify";
 /**
  * Final thumbmark response structure
  */
-interface thumbmarkResponse {
-  components: componentInterface,
-  info: { [key: string]: any },
-  version: string,
-  thumbmark: string,
-  visitorId?: string,
-  elapsed?: any;
+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>;
+  /** Error message if something went wrong */
   error?: string;
+  /** Experimental components (only when options.experimental is true) */
   experimental?: componentInterface;
+  /** Unique identifier for this API request */
+  requestId?: string;
 }
 
 /**
  * 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)
+ * @returns ThumbmarkResponse (elapsed is present only if options.performance is true)
  */
-export async function getThumbmark(options?: optionsInterface): Promise<thumbmarkResponse> {
+export async function getThumbmark(options?: optionsInterface): Promise<ThumbmarkResponse> {
+  // Early exit for non-browser environments (Node.js, Jest, SSR)
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    return {
+      thumbmark: '',
+      components: {},
+      info: {},
+      version: getVersion(),
+      error: 'Browser environment required'
+    };
+  }
+
   const _options = { ...defaultOptions, ...options } as OptionsAfterDefaults;
 
   // Early logging decision
@@ -100,7 +121,7 @@ export async function getThumbmark(options?: optionsInterface): Promise<thumbmar
     logThumbmarkData(thumbmark, components, _options, experimentalComponents).catch(() => { /* do nothing */ });
   }
 
-  const result: thumbmarkResponse = {
+  const result: ThumbmarkResponse = {
     ...(apiResult?.visitorId && { visitorId: apiResult.visitorId }),
     thumbmark,
     components: components,
@@ -108,6 +129,7 @@ export async function getThumbmark(options?: optionsInterface): Promise<thumbmar
     version,
     ...maybeElapsed,
     ...(Object.keys(experimentalComponents).length > 0 && _options.experimental && { experimental: experimentalComponents }),
+    ...(apiResult?.requestId && { requestId: apiResult.requestId }),
   };
 
   return result;

package/src/index.ts

@@ -3,7 +3,7 @@ import {
     getFingerprintData,
     getFingerprintPerformance
 } from './functions/legacy_functions'
-import { getThumbmark } from './functions'
+import { getThumbmark, ThumbmarkResponse } from './functions'
 import { getVersion } from './utils/version';
 import { setOption, optionsInterface, stabilizationExclusionRules } from './options'
 import { includeComponent } from './factory'
@@ -12,7 +12,7 @@ import { filterThumbmarkData } from './functions/filterComponents'
 import { stableStringify } from './utils/stableStringify'
 
 export {
-    Thumbmark, getThumbmark, getVersion,
+    Thumbmark, getThumbmark, getVersion, ThumbmarkResponse,
 
     // Filtering functions for server-side use
     filterThumbmarkData, optionsInterface, stabilizationExclusionRules,

package/src/thumbmark.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Tests for Thumbmark class behavior in Node/Jest environment
+ *
+ * These tests verify that Thumbmark works gracefully when browser APIs
+ * are not available (e.g., in Jest/jsdom or server-side environments).
+ */
+
+import { Thumbmark } from './thumbmark';
+import { jest } from '@jest/globals';
+
+// Polyfill for sessionStorage in Node environment
+if (typeof sessionStorage === 'undefined') {
+    (global as any).sessionStorage = {
+        getItem: jest.fn(),
+        setItem: jest.fn(),
+        removeItem: jest.fn(),
+        clear: jest.fn(),
+        length: 0,
+        key: jest.fn(),
+    };
+}
+
+
+describe('Thumbmark in Node/Jest environment', () => {
+    test('Thumbmark.get() should not throw in non-browser environment', async () => {
+        const tm = new Thumbmark();
+
+        // This should not throw, even if browser APIs are unavailable
+        const result = await tm.get();
+
+        // Should return a valid result with structure
+        expect(result).toBeDefined();
+        expect(result.thumbmark).toBeDefined();
+        expect(typeof result.thumbmark).toBe('string');
+    });
+
+    test('Thumbmark.get() returns valid structure even with missing browser APIs', async () => {
+        const tm = new Thumbmark();
+
+        const result = await tm.get();
+
+        // Verify the response structure
+        expect(result).toHaveProperty('thumbmark');
+        expect(result).toHaveProperty('components');
+        expect(result).toHaveProperty('version');
+        expect(result).toHaveProperty('info');
+
+        // Components should be an object (possibly with fewer values than in real browser)
+        expect(typeof result.components).toBe('object');
+    });
+
+    test('Thumbmark.getVersion() works in any environment', () => {
+        const tm = new Thumbmark();
+        const version = tm.getVersion();
+
+        expect(version).toBeDefined();
+        expect(typeof version).toBe('string');
+    });
+});

package/src/thumbmark.ts

@@ -1,5 +1,5 @@
 import { optionsInterface } from "./options";
-import { getThumbmark, includeComponent as globalIncludeComponent } from './functions';
+import { getThumbmark, includeComponent as globalIncludeComponent, ThumbmarkResponse } from './functions';
 import { getVersion } from "./utils/version";
 import { defaultOptions } from "./options";
 import { componentInterface } from "./factory";
@@ -22,9 +22,9 @@ export class Thumbmark {
     /**
      * Generates a thumbmark using the instance's configuration.
      * @param overrideOptions - Options to override for this specific call.
-     * @returns The thumbmark result.
+     * @returns The thumbmark result containing the fingerprint hash, components, and metadata.
      */
-    public async get(overrideOptions?: optionsInterface): Promise<any> {
+    public async get(overrideOptions?: optionsInterface): Promise<ThumbmarkResponse> {
       const finalOptions = { ...this.options, ...overrideOptions };
       return getThumbmark(finalOptions);
     }

package/src/utils/hash.ts

@@ -4,8 +4,35 @@
  */
 
 function encodeUtf8(text: string): ArrayBuffer {
-  const encoder = new TextEncoder();
-  return encoder.encode(text).buffer;
+  // Use TextEncoder if available (browser, modern Node.js)
+  if (typeof TextEncoder !== 'undefined') {
+    const encoder = new TextEncoder();
+    return encoder.encode(text).buffer;
+  }
+
+  // Fallback for environments without TextEncoder (older Node.js, some test runners)
+  const utf8: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    let charCode = text.charCodeAt(i);
+    if (charCode < 0x80) {
+      utf8.push(charCode);
+    } else if (charCode < 0x800) {
+      utf8.push(0xc0 | (charCode >> 6), 0x80 | (charCode & 0x3f));
+    } else if (charCode < 0xd800 || charCode >= 0xe000) {
+      utf8.push(0xe0 | (charCode >> 12), 0x80 | ((charCode >> 6) & 0x3f), 0x80 | (charCode & 0x3f));
+    } else {
+      // Surrogate pair
+      i++;
+      charCode = 0x10000 + (((charCode & 0x3ff) << 10) | (text.charCodeAt(i) & 0x3ff));
+      utf8.push(
+        0xf0 | (charCode >> 18),
+        0x80 | ((charCode >> 12) & 0x3f),
+        0x80 | ((charCode >> 6) & 0x3f),
+        0x80 | (charCode & 0x3f)
+      );
+    }
+  }
+  return new Uint8Array(utf8).buffer;
 }
 
 function fmix (input : number) : number {