@purespectrum1/purescore-client 0.7.0

package/README.md

@@ -0,0 +1,55 @@
+# Purescore Identifier
+
+`@purespectrum1/purescore-client` generates a stable, unique device ID from
+device- and browser-level signals (fingerprinting). It ships as both a Node/TypeScript
+library and a standalone UMD browser bundle, so the same identification logic can run
+in a service or be dropped into a page with a `<script>` tag.
+
+> **Status:** project scaffolding. Build, test, lint and release pipelines are in place;
+> the `src/` implementation is still being added, so the public API below is not final.
+
+## Requirements
+
+| | |
+| --- | --- |
+| Node.js | 20.15.0 (the version CI builds against) |
+| TypeScript | 5.9+ (bundled as a dev dependency) |
+| Browsers | ES5-compatible output, so old browsers are supported |
+
+## Installation
+
+```sh
+npm install @purespectrum1/purescore-client
+```
+
+The package is published to the public npm registry. Because CI installs with
+`--legacy-peer-deps`, use the same flag if you hit peer-dependency conflicts.
+
+### Browser bundle
+
+Browser builds are published to S3 (`purescore-client-package/dist`) as a UMD bundle
+that exposes the global `ps_purescore_identifier`:
+
+```html
+<script src="https://<cdn-host>/dist/bundle.js"></script>
+<script>
+  // window.ps_purescore_identifier
+</script>
+```
+
+Each release also uploads a version-pinned file (`bundle.<version>.js`) alongside the
+floating `bundle.js`. Pin the versioned file in production so a new release cannot
+change behaviour under you.
+
+## Usage
+
+```ts
+import identifier from '@purespectrum1/purescore-client';
+```
+
+The module entry point is `lib/index.js`, with type declarations emitted next to it.
+Concrete API examples will be added here as the implementation lands.
+
+## License
+
+ISC. Maintained by the Data Stars squad.

package/lib/application/auto-init.d.ts

@@ -0,0 +1,44 @@
+import { AutoInitConfig } from '../domain/protocols/services/single-script-injection/auto-init';
+import { CreateTransaction, TrackDetails } from '../domain/protocols/services/device-identifier';
+/**
+ * Guard flag on `window`: a second tag on the same page is a no-op.
+ */
+export declare const INIT_FLAG = "__purescoreIdentifierInitialized";
+export declare const TRANSACTION_CREATION_ATTEMPTS = 3;
+export declare const TRANSACTION_RETRY_DELAY_MS = 1000;
+/**
+ * Finds the script tag that loaded this bundle.
+ *
+ * `document.currentScript` is the direct answer while the tag is executing; the
+ * `data-auto-init` + `data-token` lookup covers dynamically-injected and module
+ * contexts where `currentScript` is null.
+ */
+export declare function resolveScriptTag(): HTMLScriptElement | null;
+/**
+ * Reads the bootstrap configuration off the tag's `data-*` attributes, or
+ * returns null when a required one is missing or unusable.
+ */
+export declare function readAutoInitConfig(tag: HTMLScriptElement): AutoInitConfig | null;
+/**
+ * Bootstraps the Device-Identifier straight from the script tag: no constructor
+ * call and no `trackDetails` call on the buyer side.
+ *
+ * Strictly opt-in — it does nothing unless `data-auto-init="true"` is on the tag
+ * — so every existing integration keeps working exactly as it does today.
+ */
+export declare class AutoInitService {
+    private readonly createDeviceIdentifier;
+    constructor(createDeviceIdentifier: (config: AutoInitConfig) => TrackDetails & CreateTransaction);
+    /**
+     * Runs the bootstrap. Returns true when auto-init took over the calls for this
+     * page, false when the tag opted out or the configuration was unusable.
+     */
+    run(): boolean;
+    private bootstrap;
+    private resolveTransactionId;
+    /**
+     * Registers the transaction, trying up to `TRANSACTION_CREATION_ATTEMPTS` times.
+     * Resolves with undefined when every attempt failed.
+     */
+    private createTransaction;
+}

package/lib/application/auto-init.js

@@ -0,0 +1,245 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoInitService = exports.TRANSACTION_RETRY_DELAY_MS = exports.TRANSACTION_CREATION_ATTEMPTS = exports.INIT_FLAG = void 0;
+exports.resolveScriptTag = resolveScriptTag;
+exports.readAutoInitConfig = readAutoInitConfig;
+const validation_1 = require("../validation");
+const single_script_injection_1 = require("../domain/services/single-script-injection");
+const cache_1 = require("../infra/cache");
+/**
+ * Guard flag on `window`: a second tag on the same page is a no-op.
+ */
+exports.INIT_FLAG = '__purescoreIdentifierInitialized';
+exports.TRANSACTION_CREATION_ATTEMPTS = 3;
+exports.TRANSACTION_RETRY_DELAY_MS = 1000;
+/**
+ * Finds the script tag that loaded this bundle.
+ *
+ * `document.currentScript` is the direct answer while the tag is executing; the
+ * `data-auto-init` + `data-token` lookup covers dynamically-injected and module
+ * contexts where `currentScript` is null.
+ */
+function resolveScriptTag() {
+    var _a;
+    if (typeof document === 'undefined')
+        return null;
+    const current = document.currentScript;
+    if ((_a = current === null || current === void 0 ? void 0 : current.dataset) === null || _a === void 0 ? void 0 : _a.token)
+        return current;
+    return document.querySelector('script[data-auto-init][data-token]');
+}
+/**
+ * Reads the bootstrap configuration off the tag's `data-*` attributes, or
+ * returns null when a required one is missing or unusable.
+ */
+function readAutoInitConfig(tag) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const data = tag.dataset;
+    const errors = [
+        validation_1.ValidationBuilder.of({ value: data.token, fieldName: 'data-token' })
+            .required(),
+        validation_1.ValidationBuilder.of({ value: data.surveyId, fieldName: 'data-survey-id' })
+            .required()
+            .interpolated(),
+        validation_1.ValidationBuilder.of({ value: data.expectedSurveyLoi, fieldName: 'data-expected-survey-loi' })
+            .required()
+            .interpolated()
+            .positiveNumber(),
+        validation_1.ValidationBuilder.of({ value: data.surveyCountry, fieldName: 'data-survey-country' })
+            .required()
+            .interpolated()
+            .countryCode(),
+        validation_1.ValidationBuilder.of({ value: data.surveyLanguage, fieldName: 'data-survey-language' })
+            .required()
+            .interpolated()
+            .languageCode(),
+    ].map(rules => rules.validate()).filter((error) => error !== undefined);
+    if (errors.length) {
+        console.error(`Device-Identifier auto-init: ${errors.map(e => e.message).join('; ')}`);
+        return null;
+    }
+    const config = {
+        token: ((_a = data.token) !== null && _a !== void 0 ? _a : '').trim(),
+        env: ((_b = data.env) === null || _b === void 0 ? void 0 : _b.trim().toLowerCase()) === 'production' ? 'production' : 'staging',
+        callbackName: ((_c = data.callback) === null || _c === void 0 ? void 0 : _c.trim()) || undefined,
+        metadata: parseMetadataAttribute(data.metadata),
+        surveyId: ((_d = data.surveyId) !== null && _d !== void 0 ? _d : '').trim(),
+        expectedSurveyLOI: Number(data.expectedSurveyLoi),
+        surveyCountry: ((_e = data.surveyCountry) !== null && _e !== void 0 ? _e : '').trim().toUpperCase(),
+        surveyLanguage: ((_f = data.surveyLanguage) !== null && _f !== void 0 ? _f : '').trim().toLowerCase(),
+    };
+    const buyerId = optionalField(data.buyerId, 'data-buyer-id');
+    if (buyerId)
+        config.metadata.buyer_id = buyerId;
+    assignDefined(config, {
+        supplierId: optionalField(data.supplierId, 'data-supplier-id'),
+        supplierMemberId: optionalField(data.supplierMemberId, 'data-supplier-member-id'),
+        emailHash: ((_g = data.emailHash) === null || _g === void 0 ? void 0 : _g.trim()) || undefined,
+    });
+    const demographics = {};
+    assignDefined(demographics, {
+        age: optionalField(data.demographicsAge, 'data-demographics-age', rules => rules.positiveNumber(), Number),
+        gender: optionalField(data.demographicsGender, 'data-demographics-gender'),
+        zip: optionalField(data.demographicsZip, 'data-demographics-zip'),
+    });
+    if (Object.keys(demographics).length)
+        config.demographics = demographics;
+    return config;
+}
+/**
+ * Reads an optional attribute. An absent one is simply left out; one that is
+ * present but unusable is reported and dropped rather than treated as fatal,
+ * since the transaction does not depend on it.
+ */
+function optionalField(raw, fieldName, rules = builder => builder, convert = value => value) {
+    const error = rules(validation_1.ValidationBuilder.of({ value: raw, fieldName }).optional().interpolated()).validate();
+    if (error) {
+        console.error(`Device-Identifier auto-init: ${error.message}, ignoring it`);
+        return undefined;
+    }
+    const value = raw === null || raw === void 0 ? void 0 : raw.trim();
+    return value ? convert(value) : undefined;
+}
+/**
+ * Unusable metadata is reported and dropped rather than treated as fatal: the
+ * attribute is optional, so a malformed blob is no reason to abandon the
+ * transaction.
+ */
+function parseMetadataAttribute(raw) {
+    const error = validation_1.ValidationBuilder.of({ value: raw, fieldName: 'data-metadata' }).jsonObject().validate();
+    if (error) {
+        console.error(`Device-Identifier auto-init: ${error.message}, ignoring it`);
+        return {};
+    }
+    return (raw === null || raw === void 0 ? void 0 : raw.trim()) ? JSON.parse(raw) : {};
+}
+/** Copies over only the values that are set, so absent fields stay absent. */
+function assignDefined(target, values) {
+    Object.keys(values).forEach(key => {
+        if (values[key] !== undefined)
+            target[key] = values[key];
+    });
+}
+/**
+ * Bootstraps the Device-Identifier straight from the script tag: no constructor
+ * call and no `trackDetails` call on the buyer side.
+ *
+ * Strictly opt-in — it does nothing unless `data-auto-init="true"` is on the tag
+ * — so every existing integration keeps working exactly as it does today.
+ */
+class AutoInitService {
+    constructor(createDeviceIdentifier) {
+        this.createDeviceIdentifier = createDeviceIdentifier;
+    }
+    /**
+     * Runs the bootstrap. Returns true when auto-init took over the calls for this
+     * page, false when the tag opted out or the configuration was unusable.
+     */
+    run() {
+        var _a;
+        if (typeof window === 'undefined')
+            return false;
+        if (window[exports.INIT_FLAG])
+            return false;
+        const tag = resolveScriptTag();
+        if (!tag)
+            return false;
+        if (((_a = tag.dataset.autoInit) !== null && _a !== void 0 ? _a : '').trim().toLowerCase() !== 'true')
+            return false;
+        const config = readAutoInitConfig(tag);
+        if (!config)
+            return false;
+        window[exports.INIT_FLAG] = true;
+        this.bootstrap(config);
+        return true;
+    }
+    bootstrap(config) {
+        var _a;
+        const deviceIdentifier = this.createDeviceIdentifier(config);
+        const delivery = new single_script_injection_1.ResponseDeliveryService(config.callbackName);
+        const store = new single_script_injection_1.ScheduleStore(config.surveyId, new cache_1.LocalStorageAdapter());
+        const credentials = { token: config.token, env: config.env };
+        // Re-emit the verdict from an earlier page before the schedule resumes, so a
+        // page that only now registers a listener still receives the current one.
+        const buffered = (_a = store.read()) === null || _a === void 0 ? void 0 : _a.lastResponse;
+        if (buffered)
+            delivery.replay(buffered);
+        // The LOI comes off the tag, so every checkpoint is known up front. On a
+        // later page the record already carries it, and `applyLoi` leaves it alone.
+        store.resumeOrCreate();
+        store.applyLoi(config.expectedSurveyLOI);
+        const transactionReady = this.resolveTransactionId(store, deviceIdentifier, config, credentials);
+        const scheduler = new single_script_injection_1.CheckpointScheduler(store, () => __awaiter(this, void 0, void 0, function* () {
+            const transactionId = yield transactionReady;
+            if (!transactionId)
+                throw new Error('no transaction id to send the checkpoint for');
+            const response = yield deviceIdentifier.trackDetails(transactionId, config.metadata, credentials, { surveyId: config.surveyId });
+            store.storeResponse(response);
+            delivery.deliver(response);
+        }));
+        scheduler.start();
+        transactionReady.then(transactionId => {
+            if (!transactionId)
+                scheduler.stop();
+        });
+    }
+    resolveTransactionId(store, deviceIdentifier, config, credentials) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const stored = (_a = store.read()) === null || _a === void 0 ? void 0 : _a.transactionId;
+            if (stored)
+                return stored;
+            const transactionId = yield this.createTransaction(deviceIdentifier, config, credentials);
+            if (transactionId)
+                store.storeTransactionId(transactionId);
+            return transactionId;
+        });
+    }
+    /**
+     * Registers the transaction, trying up to `TRANSACTION_CREATION_ATTEMPTS` times.
+     * Resolves with undefined when every attempt failed.
+     */
+    createTransaction(deviceIdentifier, config, credentials) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const delay = (ms) => {
+                return new Promise(resolve => setTimeout(resolve, ms));
+            };
+            const details = {
+                surveyId: config.surveyId,
+                expectedSurveyLOI: config.expectedSurveyLOI,
+                surveyCountry: config.surveyCountry,
+                surveyLanguage: config.surveyLanguage,
+            };
+            assignDefined(details, {
+                supplierId: config.supplierId,
+                supplierMemberId: config.supplierMemberId,
+                emailHash: config.emailHash,
+                demographics: config.demographics,
+            });
+            for (let attempt = 1; attempt <= exports.TRANSACTION_CREATION_ATTEMPTS; attempt++) {
+                try {
+                    const transactionId = yield deviceIdentifier.createTransaction(details, credentials);
+                    if (transactionId)
+                        return transactionId;
+                }
+                catch (error) {
+                    console.error(`Error creating Device-Intelligence transaction (attempt ${attempt}):`, error);
+                }
+                if (attempt < exports.TRANSACTION_CREATION_ATTEMPTS)
+                    yield delay(exports.TRANSACTION_RETRY_DELAY_MS);
+            }
+            console.error(`Device-Identifier auto-init: could not create the transaction after ${exports.TRANSACTION_CREATION_ATTEMPTS} attempts`);
+            return undefined;
+        });
+    }
+}
+exports.AutoInitService = AutoInitService;

package/lib/application/device-identifier.d.ts

@@ -0,0 +1,116 @@
+import { DeviceIdentifierOptions, DeviceIdentifierConfig, DeviceIdentifierMetadata, BehaviouralBiometricsOptions, BehaviorBiometricsParams, CreateTransaction, TrackDetails, TrackDetailsContext, TransactionDetails } from '../domain/protocols/services/device-identifier';
+/**
+ * DeviceIdentifier class for generating a unique identifier for a browser.
+ */
+export declare class DeviceIdentifier implements TrackDetails, CreateTransaction {
+    /**
+       * Custom hash function.
+       *
+       * If provided, this function will be used to generate the hash instead of the default murmurhash3_32_gc.
+       */
+    private hasher?;
+    /**
+     * Token used to authenticate with the Purescore Intelligence service.
+     */
+    private token;
+    /**
+     * Base URL for the Purescore Identifier service.
+     */
+    private baseUrl;
+    /**
+     * Options stored from the last activateBehavioralBiometricsDetection call,
+     * reused when restarting the collection cycle after each trackDetails flush.
+     */
+    private behaviouralBiometricsOptions?;
+    /**
+     * Service responsible for performing API requests to the Purescore Intelligence service.
+    */
+    private deviceIntelligenceService;
+    private singleScriptInjection?;
+    private screen_resolution?;
+    private screen_orientation?;
+    private canvas?;
+    /**
+     * Constructor for the DeviceIdentifier class.
+     *
+     * @param options - Optional options for customizing the DeviceIdentifier generation.
+     */
+    constructor(options?: DeviceIdentifierOptions | ((value: string, seed: number) => number), config?: DeviceIdentifierConfig);
+    /**
+     * Generates the fingerprint data for the browser.
+     *
+     * @returns An object containing the fingerprint data.
+     */
+    getDetails(): Promise<{
+        hash: number;
+        canvas: string;
+        cookieEnabled: string | boolean;
+        display: {} | import("..").DisplayChecksInput;
+        javaEnabled: string | boolean;
+        tzOffset: number;
+        touchEnabled: boolean;
+        userAgent: string;
+        platform: string;
+        languages: import("..").Language;
+        displayChecks: import("..").DisplayChecks;
+        networkPerformance: import("..").NetworkTimes;
+        isWebCrawler: boolean;
+        audioFingerprint: number;
+        userAgentClientHints: {
+            model: string | undefined;
+        };
+        webdriverEnabled: boolean;
+        estimatedRoundTripTime: number;
+        ua: string;
+        browser: {
+            name?: string;
+            version?: string;
+            major?: string;
+        };
+        engine: {
+            name?: string;
+            version?: string;
+        };
+        os: {
+            name?: string;
+            version?: string;
+        };
+        device: {
+            vendor?: string;
+            model?: string;
+            type?: string;
+        };
+        cpu: {
+            architecture?: string;
+        };
+        isMobile: boolean;
+        isTablet: boolean;
+        isDesktop: boolean;
+    }>;
+    /**
+     * Generates a unique hash from browser and system properties (navigator, screen,
+     * storage, and more), using the provided hasher or murmurhash3_32_gc as a fallback.
+     *
+     * @param {string} [canvasFingerprint] - Precomputed canvas fingerprint to reuse
+     *   instead of recomputing. Only used when the `canvas` option is enabled.
+     * @returns {number} A unique hash representing the user's browser and system.
+     */
+    getIdentity(canvasFingerprint?: string): number;
+    /**
+     * Activates behavioral biometrics detection by starting event listeners for
+     * touch, cursor, and keyboard interactions.
+     *
+     * @param options - Optional configuration for BB detection, such as max data
+     * points for cursor and keystroke tracking.
+     */
+    activateBehavioralBiometricsDetection(options?: BehaviouralBiometricsOptions): void;
+    /**
+     * Deactivates behavioral biometrics detection by stopping all event listeners
+     * for touch, cursor, and keyboard interactions, and marking the detection
+     * as inactive.
+     */
+    deactivateBehavioralBiometricsDetection(): void;
+    createTransaction(details: TransactionDetails, config?: DeviceIdentifierConfig): Promise<string | undefined>;
+    trackDetails(transactionId: string, metadata?: DeviceIdentifierMetadata, config?: DeviceIdentifierConfig, context?: TrackDetailsContext): Promise<Record<string, any>>;
+    sendBehaviorBiometrics(transactionId: string, params: BehaviorBiometricsParams, config?: DeviceIdentifierConfig): Promise<any>;
+}

package/lib/application/device-identifier.js

@@ -0,0 +1,169 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceIdentifier = void 0;
+const device_fingerprint_1 = require("../domain/services/device-fingerprint");
+const behavioural_biometrics_1 = require("../domain/services/behavioural-biometrics");
+const device_intelligence_1 = require("../domain/services/device-intelligence");
+const crosscutting_1 = require("../domain/models/crosscutting");
+const spa_navigation_1 = require("../domain/services/spa-navigation");
+const axios_http_client_1 = require("../infra/http/axios-http-client");
+const cache_1 = require("../infra/cache");
+const hash = new device_fingerprint_1.Hash();
+const storage = new device_fingerprint_1.Storage();
+const display = new device_fingerprint_1.Display();
+const navigatior = new device_fingerprint_1.Navigatior();
+const canvas = new device_fingerprint_1.Canvas();
+const utils = new device_fingerprint_1.Utils();
+const audioFingerprint = new device_fingerprint_1.AudioFingerprint();
+const pointerCapability = new device_fingerprint_1.PointerCapabilityDetector();
+// One collector shared for the lifetime of the page. It owns the trackers, which
+// is what makes behavioural data survive a DeviceIdentifier being re-instantiated.
+const behaviouralBiometrics = new behavioural_biometrics_1.BehaviouralBiometricsCollector(new behavioural_biometrics_1.TouchBehavior(), new behavioural_biometrics_1.CursorBehavior(), new behavioural_biometrics_1.KeyboardMetrics(), new cache_1.SessionStorageAdapter(), new spa_navigation_1.SpaNavigationDetector());
+/**
+ * DeviceIdentifier class for generating a unique identifier for a browser.
+ */
+class DeviceIdentifier {
+    /**
+     * Constructor for the DeviceIdentifier class.
+     *
+     * @param options - Optional options for customizing the DeviceIdentifier generation.
+     */
+    constructor(options, config = {}) {
+        if (typeof options === 'object') {
+            this.hasher = options.hasher;
+            this.screen_resolution = options.screen_resolution;
+            this.screen_orientation = options.screen_orientation;
+            this.canvas = options.canvas;
+            this.singleScriptInjection = options.singleScriptInjection;
+        }
+        else if (typeof options === 'function') {
+            this.hasher = options;
+        }
+        const { token = '', env = 'staging' } = config;
+        this.token = token;
+        this.baseUrl = (0, crosscutting_1.resolveDeviceIntelligenceBaseUrl)(env);
+        this.deviceIntelligenceService = new device_intelligence_1.DeviceIntelligenceService(new axios_http_client_1.AxiosHttpClient(), this.baseUrl, this.token);
+        this.activateBehavioralBiometricsDetection();
+    }
+    /**
+     * Generates the fingerprint data for the browser.
+     *
+     * @returns An object containing the fingerprint data.
+     */
+    getDetails() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const parsedData = navigatior.getDeviceType();
+            const [audioFingerprintResponse, highEntropyClientHints] = yield Promise.all([
+                audioFingerprint.getAudioFingerprint(),
+                navigatior.getHighEntropyClientHints(['model']),
+            ]);
+            const canvasFingerprint = canvas.getCanvasFingerprint();
+            const hash = this.getIdentity(canvasFingerprint);
+            return Object.assign(Object.assign({}, parsedData), { hash, canvas: canvasFingerprint, cookieEnabled: navigatior.isCookieEnabled(), display: display.getDisplayDetails(), javaEnabled: navigatior.isJavaEnabled(), tzOffset: utils.getTimezoneOffset(), touchEnabled: utils.getTouchSupport() || pointerCapability.hasTouchOrPen(), userAgent: navigatior.getUserAgent(), platform: navigatior.getPlatform(), languages: navigatior.getLanguages(), displayChecks: display.displayChecks(), networkPerformance: utils.getNetworkTime(), isWebCrawler: navigatior.isCrawler(), audioFingerprint: audioFingerprintResponse, userAgentClientHints: {
+                    model: highEntropyClientHints === null || highEntropyClientHints === void 0 ? void 0 : highEntropyClientHints.model
+                }, webdriverEnabled: navigatior.isWebDriverEnabled(), estimatedRoundTripTime: navigatior.getEstimatedRoundTripTime() });
+        });
+    }
+    /**
+     * Generates a unique hash from browser and system properties (navigator, screen,
+     * storage, and more), using the provided hasher or murmurhash3_32_gc as a fallback.
+     *
+     * @param {string} [canvasFingerprint] - Precomputed canvas fingerprint to reuse
+     *   instead of recomputing. Only used when the `canvas` option is enabled.
+     * @returns {number} A unique hash representing the user's browser and system.
+     */
+    getIdentity(canvasFingerprint) {
+        // Initialize an array to store the properties that will be used to generate the hash.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const keys = [];
+        const navigatorProperties = navigatior.getNavigatorProperties();
+        const screenProperties = display.getScreenProperties(this.screen_resolution, this.screen_orientation);
+        const storageProperties = storage.getStorageProperties();
+        keys.push(navigatorProperties.userAgent);
+        keys.push(navigatorProperties.language);
+        keys.push(screenProperties.colorDepth);
+        if (screenProperties.resolution) {
+            keys.push(screenProperties.resolution.join('x'));
+        }
+        keys.push(new Date().getTimezoneOffset());
+        keys.push(storageProperties.sessionStorage);
+        keys.push(storageProperties.localStorage);
+        keys.push(storageProperties.indexedDB);
+        keys.push(navigatorProperties.platform);
+        keys.push(navigatorProperties.doNotTrack);
+        if (this.canvas) {
+            keys.push(canvasFingerprint !== null && canvasFingerprint !== void 0 ? canvasFingerprint : canvas.getCanvasFingerprint());
+        }
+        const keyString = keys.join('###');
+        return this.hasher ? this.hasher(keyString, 31) : hash.murmurhash3_32_gc(keyString, 31);
+    }
+    /**
+     * Activates behavioral biometrics detection by starting event listeners for
+     * touch, cursor, and keyboard interactions.
+     *
+     * @param options - Optional configuration for BB detection, such as max data
+     * points for cursor and keystroke tracking.
+     */
+    activateBehavioralBiometricsDetection(options) {
+        if (typeof window === 'undefined')
+            return;
+        this.behaviouralBiometricsOptions = options;
+        behaviouralBiometrics.startCycle(options);
+    }
+    /**
+     * Deactivates behavioral biometrics detection by stopping all event listeners
+     * for touch, cursor, and keyboard interactions, and marking the detection
+     * as inactive.
+     */
+    deactivateBehavioralBiometricsDetection() {
+        behaviouralBiometrics.deactivate();
+    }
+    createTransaction(details_1) {
+        return __awaiter(this, arguments, void 0, function* (details, config = {}) {
+            var _a;
+            const response = yield this.deviceIntelligenceService.performRequest('/v1/transaction', 'post', config, details);
+            const transactionId = (_a = response === null || response === void 0 ? void 0 : response.body) === null || _a === void 0 ? void 0 : _a.transactionId;
+            const succeeded = typeof (response === null || response === void 0 ? void 0 : response.statusCode) === 'number'
+                && response.statusCode < 400
+                && typeof transactionId === 'string'
+                && transactionId.length > 0;
+            return succeeded ? transactionId : undefined;
+        });
+    }
+    trackDetails(transactionId_1) {
+        return __awaiter(this, arguments, void 0, function* (transactionId, metadata = {}, config = {}, context = {}) {
+            var _a;
+            behaviouralBiometrics.pauseWindow();
+            const bbParams = context.surveyId ? Object.assign(Object.assign({}, metadata), { survey_id: context.surveyId }) : metadata;
+            const bbResponse = yield this.sendBehaviorBiometrics(transactionId, bbParams, config);
+            if (bbResponse.statusCode >= 400) {
+                this.deactivateBehavioralBiometricsDetection();
+            }
+            else {
+                behaviouralBiometrics.startCycle(this.behaviouralBiometricsOptions);
+            }
+            const payload = Object.assign(Object.assign({ metadata }, yield this.getDetails()), { transactionId });
+            const response = yield this.deviceIntelligenceService.performRequest(`/v1/respondent/${transactionId}`, 'patch', config, payload);
+            return (_a = response.body) !== null && _a !== void 0 ? _a : response;
+        });
+    }
+    sendBehaviorBiometrics(transactionId_1, params_1) {
+        return __awaiter(this, arguments, void 0, function* (transactionId, params, config = {}) {
+            const { metrics, collectionDuration } = behaviouralBiometrics.snapshot();
+            return this.deviceIntelligenceService.performRequest(`/v1/respondent/${transactionId}/biometrics`, 'post', config, Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, params), metrics), { device: navigatior.getDeviceType().device, collectionDuration }), (this.singleScriptInjection ? { singleScriptInjection: true } : {})), { transactionId })).then(response => {
+                behaviouralBiometrics.reset();
+                return response;
+            });
+        });
+    }
+}
+exports.DeviceIdentifier = DeviceIdentifier;

package/lib/domain/models/crosscutting/device-intelligence.d.ts

@@ -0,0 +1,11 @@
+/**
+ * NOTE: these endpoints are going to be changed to a new domain
+*/
+/** Device-Intelligence API, per environment. */
+export declare const PURESCORE_INTELLIGENCE_BASE_URL: {
+    readonly production: "https://purescore.spectrumsurveys.com";
+    readonly staging: "https://purescore-staging.spectrumsurveys.com";
+};
+export type DeviceIntelligenceEnv = keyof typeof PURESCORE_INTELLIGENCE_BASE_URL;
+/** Anything other than an explicit `production` resolves to staging. */
+export declare function resolveDeviceIntelligenceBaseUrl(env?: string): string;

package/lib/domain/models/crosscutting/device-intelligence.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PURESCORE_INTELLIGENCE_BASE_URL = void 0;
+exports.resolveDeviceIntelligenceBaseUrl = resolveDeviceIntelligenceBaseUrl;
+/**
+ * NOTE: these endpoints are going to be changed to a new domain
+*/
+/** Device-Intelligence API, per environment. */
+exports.PURESCORE_INTELLIGENCE_BASE_URL = {
+    production: 'https://purescore.spectrumsurveys.com',
+    staging: 'https://purescore-staging.spectrumsurveys.com',
+};
+/** Anything other than an explicit `production` resolves to staging. */
+function resolveDeviceIntelligenceBaseUrl(env) {
+    return (env === null || env === void 0 ? void 0 : env.toLowerCase()) === 'production'
+        ? exports.PURESCORE_INTELLIGENCE_BASE_URL.production
+        : exports.PURESCORE_INTELLIGENCE_BASE_URL.staging;
+}

package/lib/domain/models/crosscutting/index.d.ts

@@ -0,0 +1 @@
+export * from './device-intelligence';