@purespectrum1/purescore-client 0.7.0

package/lib/domain/protocols/services/single-script-injection/auto-init.d.ts

@@ -0,0 +1,120 @@
+import { DeviceIdentifierMetadata } from '../device-identifier';
+/**
+ * A single scheduled Device-Intelligence call.
+ */
+export interface ScheduleCheckpoint {
+    /**
+     * 1-based checkpoint number. Checkpoint `n` is only fired once every
+     * checkpoint before it has been sent, so this doubles as the ordering key.
+     */
+    n: number;
+    /**
+     * Absolute epoch milliseconds at which this checkpoint becomes due.
+     */
+    dueAt: number;
+}
+/**
+ * The `ps_di_schedule_<surveyId>` record.
+ *
+ * It is keyed by survey id and handed to a storage adapter rather than
+ * held in page memory, so that a page navigation resumes the schedule instead of
+ * restarting it: `startedAt` is written once, by the very first page load of the
+ * transaction.
+ */
+export interface ScheduleRecord {
+    /**
+     * The survey the schedule belongs to.
+     */
+    surveyId: string;
+    /**
+     * Length of the interview, in minutes, from `data-expected-survey-loi`. Null
+     * only between creating the record and applying the LOI to it.
+     */
+    loi: number | null;
+    /**
+     * Epoch milliseconds of the first page load of this transaction.
+     */
+    startedAt: number;
+    /**
+     * When each call should be performed.
+     */
+    checkpoints: ScheduleCheckpoint[];
+    /**
+     * How many checkpoints have already been delivered. A checkpoint is only
+     * fired when `n > sent`, so this is what keeps a page reload from repeating
+     * a call that already went out.
+     */
+    sent: number;
+    /**
+     * Epoch milliseconds after which the record is considered stale and replaced.
+     */
+    expiry: number;
+    /**
+     * Replay buffer: the most recent Device-Intelligence response, so a page that
+     * registers a listener after the checkpoint fired still receives the verdict.
+     */
+    lastResponse?: Record<string, any> | null;
+    /**
+     * The respondent's transaction id.
+     */
+    transactionId?: string | null;
+}
+/**
+ * The bootstrap configuration read off the `data-*` attributes of the script tag.
+ */
+export interface AutoInitConfig {
+    /**
+     * `data-token` — Device-Intelligence bearer token.
+     */
+    token: string;
+    /**
+     * `data-env` — defaults to `staging`.
+     */
+    env: 'staging' | 'production';
+    /**
+     * `buyer_id` from `data-buyer-id`, when it is set.
+     */
+    metadata: DeviceIdentifierMetadata;
+    /**
+     * `data-callback` — name of a global function to invoke with the response.
+     */
+    callbackName?: string;
+    /**
+     * `data-survey-id`.
+     */
+    surveyId: string;
+    /**
+     * `data-expected-survey-loi` — length of the interview, in minutes. Drives the
+     * checkpoint schedule.
+     */
+    expectedSurveyLOI: number;
+    /**
+     * `data-survey-country` — ISO 3166-1 alpha-2, upper case (`US`).
+     */
+    surveyCountry: string;
+    /**
+     * `data-survey-language` — ISO 639-1, lower case (`en`).
+     */
+    surveyLanguage: string;
+    /**
+     * `data-supplier-id`.
+     */
+    supplierId?: string;
+    /**
+     * `data-supplier-member-id`.
+     */
+    supplierMemberId?: string;
+    /**
+     * `data-email-hash` — accepted as-is, not validated yet.
+     */
+    emailHash?: string;
+    /**
+     * `data-demographics-age`, `data-demographics-gender` and
+     * `data-demographics-zip`; only the ones that are set.
+     */
+    demographics?: {
+        age?: number;
+        gender?: string;
+        zip?: string;
+    };
+}

package/lib/domain/protocols/services/single-script-injection/auto-init.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/domain/protocols/services/single-script-injection/index.d.ts

@@ -0,0 +1 @@
+export * from './auto-init';

package/lib/domain/protocols/services/single-script-injection/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./auto-init"), exports);

package/lib/domain/services/behavioural-biometrics/collector.d.ts

@@ -0,0 +1,94 @@
+import { BehaviouralBiometricsOptions } from '../../protocols/services/device-identifier';
+import { GetStorage, RemoveStorage, SetStorage } from '../../protocols/cache';
+import { CursorBehavior } from './cursor-behavior';
+import { KeyboardMetrics } from './keystroke-metrics';
+import { SpaNavigationDetector } from '../spa-navigation';
+import { TouchBehavior } from './touch-behavior';
+/**
+ * How long the tracker listeners stay attached collecting interactions before
+ * they auto-detach (one collection cycle).
+ */
+export declare const BB_WINDOW_MS = 300000;
+export declare const BB_BUCKET_MS = 30000;
+export declare const BB_MAX_BUCKETS: number;
+export type MetricsBucket = {
+    touchBehavior: ReturnType<TouchBehavior['getTouchBehaviorBiometrics']>;
+    cursorBehavior: ReturnType<CursorBehavior['getCursorBehaviorBiometrics']>;
+    keystrokeDynamics: ReturnType<KeyboardMetrics['getKeyboardMetrics']>;
+};
+/** What a flush needs: the metrics to send and how long they took to gather. */
+export type BehaviouralBiometricsSnapshot = {
+    metrics: MetricsBucket;
+    collectionDuration: number;
+};
+/**
+ * Collects behavioural biometrics across a respondent's session.
+ *
+ * A cycle attaches the trackers and seals their output into a bucket every
+ * `BB_BUCKET_MS`, keeping at most `BB_MAX_BUCKETS` before the window expires and
+ * the listeners detach. Buckets and in-progress buffers are mirrored into
+ * storage so a page navigation resumes the cycle rather than restarting it.
+ *
+ * One instance is shared for the lifetime of the page: the trackers it owns are
+ * what makes behavioural data survive a `DeviceIdentifier` being re-instantiated.
+ */
+export declare class BehaviouralBiometricsCollector {
+    private readonly touch;
+    private readonly cursor;
+    private readonly keyboard;
+    private readonly spaNavigation;
+    private buckets;
+    private bucketTimer;
+    private durationTimer;
+    private bucketsSealedThisWindow;
+    private collectionDuration;
+    private cycleActive;
+    private activeOptions;
+    private readonly snapshots;
+    constructor(touch: TouchBehavior, cursor: CursorBehavior, keyboard: KeyboardMetrics, storage: GetStorage & SetStorage & RemoveStorage, spaNavigation: SpaNavigationDetector);
+    /**
+     * Attaches the trackers without the bucket cycle, for callers that flush on
+     * their own schedule.
+     */
+    startTrackers(options?: BehaviouralBiometricsOptions): void;
+    /**
+     * Starts a fresh collection cycle: re-attaches the listeners and restarts the
+     * bucket-sealing timer, stopping any active window first so the trackers can be
+     * (re)initialized cleanly.
+     */
+    startCycle(options?: BehaviouralBiometricsOptions): void;
+    /** Stops sealing buckets, leaving the collected data in place for a flush. */
+    pauseWindow(): void;
+    /** Detaches everything and discards what was collected. */
+    deactivate(): void;
+    /**
+     * The metrics worth sending: the most recent bucket that captured something,
+     * falling back to whatever the trackers hold right now.
+     */
+    snapshot(): BehaviouralBiometricsSnapshot;
+    /** Clears everything a successful flush has already delivered. */
+    reset(): void;
+    /**
+     * On SPA navigations (Next.js, Nuxt, SvelteKit, etc.), re-attach tracker
+     * listeners and reset the collection window so interactions on the new page are
+     * not missed when the previous window had already expired.
+     */
+    private installSpaReArm;
+    private startWindow;
+    /** Restores the buffers of whichever trackers were just wiped. */
+    private hydrate;
+    private sealCurrentBucket;
+    /** Snapshots whatever the trackers have captured in the in-progress bucket. */
+    private captureLive;
+    /**
+     * A bucket is "zeroed" when it captured no behavioural signal at all, and is
+     * never worth sending. The rule itself lives in the validation layer.
+     */
+    private isZeroed;
+    private mostRecentNonZeroedBucket;
+    private persistable;
+    private resetTrackers;
+    private startDurationTimer;
+    private stopDurationTimer;
+    private stopBucketTimer;
+}

package/lib/domain/services/behavioural-biometrics/collector.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BehaviouralBiometricsCollector = exports.BB_MAX_BUCKETS = exports.BB_BUCKET_MS = exports.BB_WINDOW_MS = void 0;
+const validation_1 = require("../../../validation");
+const snapshot_store_1 = require("../snapshot-store");
+/**
+ * How long the tracker listeners stay attached collecting interactions before
+ * they auto-detach (one collection cycle).
+ */
+exports.BB_WINDOW_MS = 300000; // 5 minutes
+exports.BB_BUCKET_MS = 30000; // 30 seconds
+exports.BB_MAX_BUCKETS = Math.floor(exports.BB_WINDOW_MS / exports.BB_BUCKET_MS);
+const BB_PERSIST_KEY = 'ps_deviceIdentifier_behavioralBiometrics';
+/**
+ * Collects behavioural biometrics across a respondent's session.
+ *
+ * A cycle attaches the trackers and seals their output into a bucket every
+ * `BB_BUCKET_MS`, keeping at most `BB_MAX_BUCKETS` before the window expires and
+ * the listeners detach. Buckets and in-progress buffers are mirrored into
+ * storage so a page navigation resumes the cycle rather than restarting it.
+ *
+ * One instance is shared for the lifetime of the page: the trackers it owns are
+ * what makes behavioural data survive a `DeviceIdentifier` being re-instantiated.
+ */
+class BehaviouralBiometricsCollector {
+    constructor(touch, cursor, keyboard, storage, spaNavigation) {
+        this.touch = touch;
+        this.cursor = cursor;
+        this.keyboard = keyboard;
+        this.spaNavigation = spaNavigation;
+        this.buckets = [];
+        this.bucketTimer = null;
+        this.durationTimer = null;
+        this.bucketsSealedThisWindow = 0;
+        this.collectionDuration = 0;
+        this.cycleActive = false;
+        this.activeOptions = undefined;
+        this.snapshots = new snapshot_store_1.SnapshotStore(BB_PERSIST_KEY, () => this.persistable(), storage);
+    }
+    /**
+     * Attaches the trackers without the bucket cycle, for callers that flush on
+     * their own schedule.
+     */
+    startTrackers(options) {
+        this.touch.startTracking(options);
+        this.cursor.startTracking(options === null || options === void 0 ? void 0 : options.cursorMaxDataPoints);
+        this.keyboard.startTracking(options === null || options === void 0 ? void 0 : options.keystrokeMaxDataPoints);
+    }
+    /**
+     * Starts a fresh collection cycle: re-attaches the listeners and restarts the
+     * bucket-sealing timer, stopping any active window first so the trackers can be
+     * (re)initialized cleanly.
+     */
+    startCycle(options) {
+        this.cycleActive = true;
+        this.activeOptions = options;
+        this.installSpaReArm();
+        this.startWindow(options);
+        this.snapshots.start();
+    }
+    /** Stops sealing buckets, leaving the collected data in place for a flush. */
+    pauseWindow() {
+        this.stopBucketTimer();
+    }
+    /** Detaches everything and discards what was collected. */
+    deactivate() {
+        this.cycleActive = false;
+        this.activeOptions = undefined;
+        this.stopBucketTimer();
+        this.stopDurationTimer();
+        this.buckets = [];
+        this.collectionDuration = 0;
+        this.snapshots.stop();
+        this.touch.stopTracking();
+        this.cursor.stopTracking();
+        this.keyboard.stopTracking();
+        this.resetTrackers();
+    }
+    /**
+     * The metrics worth sending: the most recent bucket that captured something,
+     * falling back to whatever the trackers hold right now.
+     */
+    snapshot() {
+        var _a;
+        return {
+            metrics: (_a = this.mostRecentNonZeroedBucket()) !== null && _a !== void 0 ? _a : this.captureLive(),
+            collectionDuration: this.collectionDuration,
+        };
+    }
+    /** Clears everything a successful flush has already delivered. */
+    reset() {
+        this.resetTrackers();
+        this.buckets = [];
+        this.collectionDuration = 0;
+        this.snapshots.stop();
+        this.snapshots.clear();
+    }
+    /**
+     * On SPA navigations (Next.js, Nuxt, SvelteKit, etc.), re-attach tracker
+     * listeners and reset the collection window so interactions on the new page are
+     * not missed when the previous window had already expired.
+     */
+    installSpaReArm() {
+        this.spaNavigation.install(() => {
+            if (!this.cycleActive)
+                return;
+            this.startWindow(this.activeOptions);
+        });
+    }
+    startWindow(options) {
+        this.stopBucketTimer();
+        this.stopDurationTimer();
+        this.bucketsSealedThisWindow = 0;
+        // startTracking() calls resetData() internally, but only when that tracker
+        // is not already listening. Capture each tracker's "was reset" signal
+        // independently so we hydrate only the ones whose buffers were just wiped —
+        // never overwriting a tracker that still has fresher in-memory data.
+        const touchWasReset = !this.touch.hasActiveListeners();
+        const cursorWasReset = !this.cursor.hasActiveListeners();
+        const keyboardWasReset = !this.keyboard.hasActiveListeners();
+        this.startTrackers(options);
+        if (touchWasReset || cursorWasReset || keyboardWasReset) {
+            this.hydrate({ touchWasReset, cursorWasReset, keyboardWasReset });
+        }
+        this.startDurationTimer();
+        this.bucketTimer = setInterval(() => {
+            this.sealCurrentBucket();
+            this.bucketsSealedThisWindow++;
+            if (this.bucketsSealedThisWindow >= exports.BB_MAX_BUCKETS) {
+                this.stopBucketTimer();
+                this.stopDurationTimer();
+                this.touch.stopTracking();
+                this.cursor.stopTracking();
+                this.keyboard.stopTracking();
+            }
+        }, exports.BB_BUCKET_MS);
+    }
+    /** Restores the buffers of whichever trackers were just wiped. */
+    hydrate({ touchWasReset, cursorWasReset, keyboardWasReset }) {
+        var _a, _b;
+        const stored = this.snapshots.read();
+        if (stored === null || stored === void 0 ? void 0 : stored.state) {
+            if (touchWasReset && stored.state.touchBehavior)
+                this.touch.restoreState(stored.state.touchBehavior);
+            if (cursorWasReset && stored.state.cursorBehavior)
+                this.cursor.restoreState(stored.state.cursorBehavior);
+            if (keyboardWasReset && stored.state.keystrokeDynamics)
+                this.keyboard.restoreState(stored.state.keystrokeDynamics);
+            this.collectionDuration = (_a = stored.state.collectionDuration) !== null && _a !== void 0 ? _a : 0;
+        }
+        else {
+            this.collectionDuration = 0;
+        }
+        if (this.buckets.length === 0 && ((_b = stored === null || stored === void 0 ? void 0 : stored.buckets) === null || _b === void 0 ? void 0 : _b.length)) {
+            this.buckets = stored.buckets.slice(-exports.BB_MAX_BUCKETS);
+        }
+    }
+    sealCurrentBucket() {
+        const bucket = this.captureLive();
+        if (!this.isZeroed(bucket)) {
+            this.buckets.push(bucket);
+            if (this.buckets.length > exports.BB_MAX_BUCKETS) {
+                this.buckets = this.buckets.slice(-exports.BB_MAX_BUCKETS);
+            }
+        }
+        this.collectionDuration = 0;
+        this.resetTrackers();
+    }
+    /** Snapshots whatever the trackers have captured in the in-progress bucket. */
+    captureLive() {
+        return {
+            touchBehavior: this.touch.getTouchBehaviorBiometrics(),
+            cursorBehavior: this.cursor.getCursorBehaviorBiometrics(),
+            keystrokeDynamics: this.keyboard.getKeyboardMetrics(),
+        };
+    }
+    /**
+     * A bucket is "zeroed" when it captured no behavioural signal at all, and is
+     * never worth sending. The rule itself lives in the validation layer.
+     */
+    isZeroed(bucket) {
+        return new validation_1.BehaviouralSignal(bucket).validate() !== undefined;
+    }
+    mostRecentNonZeroedBucket() {
+        for (let i = this.buckets.length - 1; i >= 0; i--) {
+            if (!this.isZeroed(this.buckets[i]))
+                return this.buckets[i];
+        }
+        return null;
+    }
+    persistable() {
+        return {
+            state: {
+                touchBehavior: this.touch.getState(),
+                cursorBehavior: this.cursor.getState(),
+                keystrokeDynamics: this.keyboard.getState(),
+                collectionDuration: this.collectionDuration,
+            },
+            buckets: this.buckets,
+        };
+    }
+    resetTrackers() {
+        this.touch.resetData();
+        this.cursor.resetData();
+        this.keyboard.resetData();
+    }
+    startDurationTimer() {
+        this.stopDurationTimer();
+        this.durationTimer = setInterval(() => {
+            this.collectionDuration++;
+            if (this.collectionDuration >= exports.BB_BUCKET_MS / 1000) {
+                this.collectionDuration = 0;
+            }
+        }, 1000);
+    }
+    stopDurationTimer() {
+        if (this.durationTimer !== null) {
+            clearInterval(this.durationTimer);
+            this.durationTimer = null;
+        }
+    }
+    stopBucketTimer() {
+        if (this.bucketTimer !== null) {
+            clearInterval(this.bucketTimer);
+            this.bucketTimer = null;
+        }
+    }
+}
+exports.BehaviouralBiometricsCollector = BehaviouralBiometricsCollector;

package/lib/domain/services/behavioural-biometrics/cursor-behavior.d.ts

@@ -0,0 +1,87 @@
+import { MousePoint, MouseVelocity, MouseAcceleration, ScrollEvent, CursorBehaviorMetrics } from '../../protocols/services/behavioural-biometrics/cursor-behavior';
+export declare class CursorBehavior {
+    private movements;
+    private velocities;
+    private accelerations;
+    private scrolls;
+    private lastPoint;
+    private lastVelocity;
+    private lastSampleTime;
+    private angleChangeCount;
+    private lastAngle;
+    private hoverStart;
+    private isTracking;
+    private mouseMoveHandler;
+    private mouseDownHandler;
+    private wheelHandler;
+    private scrollHandler;
+    private readonly sampleRate;
+    private readonly significantAngleChange;
+    private maxDataPoints;
+    private readonly pruneInterval;
+    private pruneCounter;
+    constructor();
+    /**
+     * Start tracking mouse behavior
+     */
+    startTracking(maxDataPoints?: number): void;
+    /**
+     * Stops tracking cursor behavior without clearing collected data.
+     */
+    stopTracking(): void;
+    /**
+     * Returns true if this tracker currently has its DOM listeners attached.
+     */
+    hasActiveListeners(): boolean;
+    /**
+     * Snapshot of raw event buffers for cross-page persistence.
+     */
+    getState(): {
+        movements: MousePoint[];
+        velocities: MouseVelocity[];
+        accelerations: MouseAcceleration[];
+        scrolls: ScrollEvent[];
+        angleChangeCount: number;
+    };
+    /**
+     * Restores raw event buffers from a snapshot. Transient fields (lastPoint,
+     * lastVelocity, hoverStart, etc.) are not restored — they only make sense
+     * within a continuous interaction sequence on a single page.
+     */
+    restoreState(state: {
+        movements?: MousePoint[];
+        velocities?: MouseVelocity[];
+        accelerations?: MouseAcceleration[];
+        scrolls?: ScrollEvent[];
+        angleChangeCount?: number;
+    }): void;
+    /**
+     * Reset all collected data
+     */
+    resetData(): void;
+    /**
+     * Get current behavioral metrics
+     */
+    getCursorBehaviorBiometrics(): CursorBehaviorMetrics;
+    private handleMouseMove;
+    private handleMouseDown;
+    private handleWheel;
+    private handleScroll;
+    private calculateVelocity;
+    private calculateAcceleration;
+    private calculateDistance;
+    private pruneOldData;
+    private calculateAverageSpeed;
+    private calculateMaxSpeed;
+    private calculateMinSpeed;
+    private calculateSpeedStdDev;
+    private calculateAverageAcceleration;
+    private calculateMaxAcceleration;
+    private countDecelerations;
+    private countAccelerations;
+    private calculateAverageCurvature;
+    private calculateStraightLinePercentage;
+    private calculateAverageJerkiness;
+    private calculateTotalScrollDistance;
+    private calculateAverageScrollVelocity;
+}