clarity-js 0.6.23

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "clarity-js",
+  "version": "0.6.23",
+  "description": "An analytics library that uses web page interactions to generate aggregated insights",
+  "author": "Microsoft Corp.",
+  "license": "MIT",
+  "main": "build/clarity.js",
+  "module": "build/clarity.module.js",
+  "unpkg": "build/clarity.min.js",
+  "types": "types/index.d.ts",
+  "keywords": [
+    "clarity",
+    "Microsoft",
+    "interactions",
+    "cursor",
+    "pointer",
+    "instrumentation",
+    "analytics"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/clarity.git",
+    "directory": "packages/clarity-js"
+  },
+  "bugs": {
+    "url": "https://github.com/microsoft/clarity/issues"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^19.0.1",
+    "@rollup/plugin-node-resolve": "^13.0.2",
+    "@types/chai": "^4.2.21",
+    "@types/mocha": "^8.2.3",
+    "@types/resize-observer-browser": "^0.1.6",
+    "chai": "^4.2.0",
+    "del-cli": "^4.0.1",
+    "husky": "^7.0.1",
+    "lint-staged": "^11.0.1",
+    "mocha": "^9.0.2",
+    "playwright": "^1.6.2",
+    "rollup": "^2.53.2",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-typescript2": "^0.30.0",
+    "ts-mocha": "^8.0.0",
+    "tslib": "^2.3.0",
+    "tslint": "^6.1.3",
+    "typescript": "^4.3.5"
+  },
+  "scripts": {
+    "build": "yarn build:clean && yarn build:main",
+    "build:main": "rollup -c rollup.config.ts",
+    "build:clean": "del-cli build/*",
+    "test": "ts-mocha -p test/tsconfig.test.json test/**/*.test.ts",
+    "tslint": "tslint --project ./",
+    "tslint:fix": "tslint --fix --project ./ --force"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.ts": [
+      "tslint --format codeFrame"
+    ]
+  }
+}

package/rollup.config.ts

@@ -0,0 +1,38 @@
+import commonjs from "@rollup/plugin-commonjs";
+import resolve from "@rollup/plugin-node-resolve";
+import typescript from "rollup-plugin-typescript2";
+import { terser } from "rollup-plugin-terser";
+import pkg from "./package.json";
+
+export default [
+  {
+    input: "src/index.ts",
+    output: [
+      { file: pkg.main, format: "cjs", exports: "named" },
+      { file: pkg.module, format: "es", exports: "named" }
+    ],
+    plugins: [
+      resolve(),
+      typescript({ rollupCommonJSResolveHack: true, clean: true }),
+      commonjs({ include: ["node_modules/**"] })
+    ],
+    onwarn(message, warn) {
+      if (message.code === 'CIRCULAR_DEPENDENCY') { return; }
+      warn(message);
+    }
+  },
+  {
+    input: "src/global.ts",
+    output: [ { file: pkg.unpkg, format: "iife", exports: "named" } ],
+    onwarn(message, warn) {
+      if (message.code === 'CIRCULAR_DEPENDENCY') { return; }
+      warn(message);
+    },
+    plugins: [
+      resolve(),
+      typescript({ rollupCommonJSResolveHack: true, clean: true }),
+      terser({output: {comments: false}}),
+      commonjs({ include: ["node_modules/**"] })
+    ]
+  }
+];

package/src/clarity.ts

@@ -0,0 +1,54 @@
+import { Config, Module } from "@clarity-types/core";
+import { Constant } from "@clarity-types/data";
+import * as core from "@src/core";
+import measure from "@src/core/measure";
+import * as task from "@src/core/task";
+import version from "@src/core/version";
+import * as data from "@src/data";
+import * as diagnostic from "@src/diagnostic";
+import * as interaction from "@src/interaction";
+import * as layout from "@src/layout";
+import * as performance from "@src/performance";
+export { version };
+export { consent, event, identify, set, upgrade, metadata } from "@src/data";
+
+const modules: Module[] = [diagnostic, layout, interaction, performance];
+
+export function start(config: Config = null): void {
+  // Check that browser supports required APIs and we do not attempt to start Clarity multiple times
+  if (core.check()) {
+    core.config(config);
+    core.start();
+    data.start();
+    modules.forEach(x => measure(x.start)());
+  }
+}
+
+// By default Clarity is asynchronous and will yield by looking for requestIdleCallback.
+// However, there can still be situations with single page apps where a user action can result
+// in the whole DOM being destroyed and reconstructed. While Clarity will perform favorably out of the box,
+// we do allow external clients to manually pause Clarity for that short burst of time and minimize
+// performance impact even further. For reference, we are talking single digit milliseconds optimization here, not seconds.
+export function pause(): void {
+  if (core.active()) {
+    data.event(Constant.Clarity, Constant.Pause);
+    task.pause();
+  }
+}
+
+// This is how external clients can get out of pause state, and resume Clarity to continue monitoring the page
+export function resume(): void {
+  if (core.active()) {
+    task.resume();
+    data.event(Constant.Clarity, Constant.Resume);
+  }
+}
+
+export function stop(): void {
+  if (core.active()) {
+    // Stop modules in the reverse order of their initialization
+    modules.slice().reverse().forEach(x => measure(x.stop)());
+    data.stop();
+    core.stop();
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,21 @@
+import { Config, Time } from "@clarity-types/core";
+
+let config: Config = {
+    projectId: null,
+    delay: 1 * Time.Second,
+    cssRules: false,
+    lean: false,
+    track: true,
+    content: true,
+    mask: [],
+    unmask: [],
+    regions: [],
+    metrics: [],
+    cookies: [],
+    report: null,
+    upload: null,
+    fallback: null,
+    upgrade: null
+};
+
+export default config;

package/src/core/copy.ts

@@ -0,0 +1,3 @@
+export default function<T>(input: T): T {
+    return JSON.parse(JSON.stringify(input));
+}

package/src/core/event.ts

@@ -0,0 +1,25 @@
+import { BrowserEvent } from "@clarity-types/core";
+import measure from "./measure";
+
+let bindings: BrowserEvent[] = [];
+
+export function bind(target: EventTarget, event: string, listener: EventListener, capture: boolean = false): void {
+    listener = measure(listener) as EventListener;
+    // Wrapping following lines inside try / catch to cover edge cases where we might try to access an inaccessible element.
+    // E.g. Iframe may start off as same-origin but later turn into cross-origin, and the following lines will throw an exception.
+    try {
+      target.addEventListener(event, listener, capture);
+      bindings.push({ event, target, listener, capture });
+    } catch { /* do nothing */ }
+}
+
+export function reset(): void {
+  // Walk through existing list of bindings and remove them all
+  for (let binding of bindings) {
+    // Wrapping inside try / catch to avoid situations where the element may be destroyed before we get a chance to unbind
+    try {
+      binding.target.removeEventListener(binding.event, binding.listener, binding.capture);
+    } catch { /* do nothing */ }
+  }
+  bindings = [];
+}

package/src/core/hash.ts

@@ -0,0 +1,19 @@
+// tslint:disable: no-bitwise
+export default function(input: string): string {
+    // Code inspired from C# GetHashCode: https://github.com/Microsoft/referencesource/blob/master/mscorlib/system/string.cs
+    let hash = 0;
+    let hashOne = 5381;
+    let hashTwo = hashOne;
+    for (let i = 0; i < input.length; i += 2) {
+        let charOne = input.charCodeAt(i);
+        hashOne = ((hashOne << 5) + hashOne) ^ charOne;
+        if (i + 1 < input.length) {
+            let charTwo = input.charCodeAt(i + 1);
+            hashTwo = ((hashTwo << 5) + hashTwo) ^ charTwo;
+        }
+    }
+    // Replace the magic number from C# implementation (1566083941) with a smaller prime number (11579)
+    // This ensures we don't hit integer overflow and prevent collisions
+    hash = Math.abs(hashOne + (hashTwo * 11579));
+    return hash.toString(36);
+}

package/src/core/history.ts

@@ -0,0 +1,69 @@
+import { Code, Constant, Setting, Severity } from "@clarity-types/data";
+import * as clarity from "@src/clarity";
+import { bind } from "@src/core/event";
+import * as internal from "@src/diagnostic/internal";
+
+let pushState = null;
+let replaceState = null;
+let url = null;
+let count = 0;
+
+export function start(): void {
+    url = getCurrentUrl();
+    count = 0;
+    bind(window, "popstate", compute);
+    
+    // Add a proxy to history.pushState function
+    if (pushState === null) { pushState = history.pushState; }
+    history.pushState = function(): void {
+        if (check()) {
+            pushState.apply(this, arguments);
+            compute();
+        }
+    };
+
+    // Add a proxy to history.replaceState function
+    if (replaceState === null) { replaceState = history.replaceState; }
+    history.replaceState = function(): void {
+        if (check()) {
+            replaceState.apply(this, arguments);
+            compute();
+        }
+    };
+}
+
+function check(): boolean {
+    if (count++ > Setting.CallStackDepth) {
+        internal.log(Code.CallStackDepth, Severity.Info);
+        return false;
+    }
+    return true;
+}
+
+function compute(): void {
+    if (url !== getCurrentUrl() && count <= Setting.CallStackDepth) {
+        clarity.stop();
+        window.setTimeout(clarity.start, Setting.RestartDelay);
+    }
+}
+
+function getCurrentUrl(): string {
+    return location.href ? location.href.replace(location.hash, Constant.Empty) : location.href;
+}
+
+export function stop(): void {
+    // Restore original function definition of history.pushState
+    if (pushState !== null) {
+        history.pushState = pushState;
+        pushState = null;
+    }
+
+    // Restore original function definition of history.replaceState
+    if (replaceState !== null) {
+        history.replaceState = replaceState;
+        replaceState = null;
+    }
+    
+    url = null;
+    count = 0;
+}

package/src/core/index.ts

@@ -0,0 +1,79 @@
+import { Config } from "@clarity-types/core";
+import { Constant } from "@clarity-types/data";
+import configuration from "@src/core/config";
+import * as event from "@src/core/event";
+import * as history from "@src/core/history";
+import * as report from "@src/core/report";
+import * as task from "@src/core/task";
+import * as time from "@src/core/time";
+import * as clarity from "@src/clarity";
+import * as custom from "@src/data/custom";
+
+let status = false;
+
+export function start(): void {
+    status = true;
+    time.start();
+    task.reset();
+    event.reset();
+    report.reset();
+    history.start();
+}
+
+export function stop(): void {
+    history.stop();
+    report.reset();
+    event.reset();
+    task.reset();
+    time.stop();
+    status = false;
+}
+
+export function active(): boolean {
+    return status;
+}
+
+export function check(): boolean {
+    try {
+        return status === false &&
+            typeof Promise !== "undefined" &&
+            window["MutationObserver"] &&
+            document["createTreeWalker"] &&
+            "now" in Date &&
+            "now" in performance &&
+            typeof WeakMap !== "undefined";
+    } catch (ex) {
+        return false;
+    }
+}
+
+export function config(override: Config): boolean {
+    // Process custom configuration overrides, if available
+    if (override === null || status) { return false; }
+    for (let key in override) {
+        if (key in configuration) { configuration[key] = override[key]; }
+    }
+    return true;
+}
+
+// Suspend ends the current Clarity instance after a configured timeout period
+// The way it differs from the "end" call is that it starts listening to
+// user interaction events as soon as it terminates existing clarity instance.
+// On the next interaction, it automatically starts another instance under a different page id
+// E.g. if configured timeout is 10m, and user stays inactive for an hour.
+// In this case, we will suspend clarity after 10m of inactivity and after another 50m when user interacts again
+// Clarity will restart and start another instance seamlessly. Effectively not missing any active time, but also
+// not holding the session during inactive time periods.
+export function suspend(): void {
+    if (status) {
+        custom.event(Constant.Clarity, Constant.Suspend);
+        clarity.stop();
+        ["document", "touchstart"].forEach(x => event.bind(document, x, restart));
+        ["resize", "scroll", "pageshow"].forEach(x => event.bind(window, x, restart));
+    }
+}
+
+function restart(): void {
+    clarity.start();
+    custom.event(Constant.Clarity, Constant.Restart);
+}

package/src/core/measure.ts

@@ -0,0 +1,17 @@
+import { Setting } from "@clarity-types/core";
+import { Metric } from "@clarity-types/data";
+import * as metric from "@src/data/metric";
+
+// tslint:disable-next-line: ban-types
+export default function (method: Function): Function {
+    return function (): void {
+        let start = performance.now();
+        method.apply(this, arguments);
+        let duration = performance.now() - start;
+        metric.sum(Metric.TotalCost, duration);
+        if (duration > Setting.LongTask) {
+            metric.count(Metric.LongTaskCount);
+            metric.max(Metric.ThreadBlockedTime, duration);
+        }
+    };
+}

package/src/core/report.ts

@@ -0,0 +1,27 @@
+import { Report } from "@clarity-types/core";
+import { Check } from "@clarity-types/data";
+import config from "@src/core/config";
+import { data } from "@src/data/metadata";
+
+let history: string[];
+
+export function reset(): void {
+    history = [];
+}
+
+export function report(check: Check, message: string = null): void {
+    // Do not report the same message twice for the same page
+    if (history && history.indexOf(message) === -1) {
+        const url = config.report;
+        if (url && url.length > 0) {
+            let payload: Report = {c: check, p: data.projectId, u: data.userId, s: data.sessionId, n: data.pageNum };
+            if (message) payload.m = message;
+            // Using POST request instead of a GET request (img-src) to not violate existing CSP rules
+            // Since, Clarity already uses XHR to upload data, we stick with similar POST mechanism for reporting too
+            let xhr = new XMLHttpRequest();
+            xhr.open("POST", url);
+            xhr.send(JSON.stringify(payload));
+            history.push(message);
+        }
+    }
+}

package/src/core/scrub.ts

@@ -0,0 +1,102 @@
+import { Privacy } from "@clarity-types/core";
+import * as Data from "@clarity-types/data";
+import * as Layout from "@clarity-types/layout";
+
+export default function(value: string, hint: string, privacy: Privacy, mangle: boolean = false): string {
+    if (value) {
+        switch (privacy) {
+            case Privacy.None:
+                return value;
+            case Privacy.Sensitive:
+                switch (hint) {
+                    case Layout.Constant.TextTag:
+                    case "value":
+                    case "placeholder":
+                        return redact(value);
+                    case "input":
+                        return mangleToken(value);
+                }
+                return value;
+            case Privacy.Text:
+            case Privacy.TextImage:
+                switch (hint) {
+                    case Layout.Constant.TextTag:
+                        return mangle ? mangleText(value) : mask(value);
+                    case "src":
+                    case "srcset":
+                    case "title":
+                    case "alt":
+                        return privacy === Privacy.TextImage ? Data.Constant.Empty : value;
+                    case "value":
+                    case "click":
+                    case "input":
+                        return mangleToken(value);
+                    case "placeholder":
+                        return mask(value);
+                }
+                break;
+        }
+    }
+    return value;
+}
+
+function mangleText(value: string): string {
+    let trimmed = value.trim();
+    if (trimmed.length > 0) {
+        let first = trimmed[0];
+        let index = value.indexOf(first);
+        let prefix = value.substr(0, index);
+        let suffix = value.substr(index + trimmed.length);
+        return `${prefix}${trimmed.length.toString(36)}${suffix}`;
+    }
+    return value;
+}
+
+function mask(value: string): string {
+    return value.replace(/\S/gi, Data.Constant.Mask);
+}
+
+function mangleToken(value: string): string {
+    let length = ((Math.floor(value.length / Data.Setting.WordLength) + 1) * Data.Setting.WordLength);
+    let output: string = Layout.Constant.Empty;
+    for (let i = 0; i < length; i++) {
+        output += i > 0 && i % Data.Setting.WordLength === 0 ? Data.Constant.Space : Data.Constant.Mask;
+    }
+    return output;
+}
+
+function redact(value: string): string {
+    let spaceIndex = -1;
+    let hasDigit = false;
+    let hasEmail = false;
+    let hasWhitespace = false;
+    let array = null;
+    for (let i = 0; i < value.length; i++) {
+        let c = value.charCodeAt(i);
+        hasDigit = hasDigit || (c >= 48 && c <= 57); // Check for digits in the current word
+        hasEmail = hasEmail || c === 64; // Check for @ sign anywhere within the current word
+        hasWhitespace = c === 9 || c === 10 || c === 13 || c === 32; // Whitespace character (32: blank space | 9: \t | 10: \n | 13: \r)
+
+        // Process each word as an individual token to redact any sensitive information
+        if (i === 0 || i === value.length - 1 || hasWhitespace) {
+            // Performance optimization: Lazy load string -> array conversion only when required
+            if (hasDigit || hasEmail) {
+                if (array === null) { array = value.split(Data.Constant.Empty); }
+                mutate(array, spaceIndex, hasWhitespace ? i : i + 1);
+            }
+            // Reset digit and email flags after every word boundary, except the beginning of string
+            if (hasWhitespace) {
+                hasDigit = false;
+                hasEmail = false;
+                spaceIndex = i;
+            }
+        }
+    }
+    return array ? array.join(Data.Constant.Empty) : value;
+}
+
+function mutate(array: string[], start: number, end: number): void {
+    for (let i = start + 1; i < end; i++) {
+        array[i] = Data.Constant.Mask;
+    }
+}