clarity-js 0.6.23

package/src/layout/selector.ts

@@ -0,0 +1,24 @@
+import { Attributes, Constant } from "../../types/layout";
+
+export default function(tag: string, prefix: string, attributes: Attributes, position: number): string {
+    let suffix = position ? `:nth-of-type(${position})` : Constant.Empty;
+    switch (tag) {
+        case "STYLE":
+        case "TITLE":
+        case "LINK":
+        case "META":
+        case Constant.TextTag:
+        case Constant.DocumentTag:
+            return Constant.Empty;
+        case "HTML":
+            return Constant.HTML;
+        default:
+            if (prefix === null) { return Constant.Empty; }
+            tag = tag.indexOf(Constant.SvgPrefix) === 0 ? tag.substr(Constant.SvgPrefix.length) : tag;
+            let selector = `${prefix}${tag}${suffix}`;
+            if (Constant.Class in attributes && attributes[Constant.Class].length > 0) {
+                selector = `${prefix}${tag}.${attributes.class.trim().split(/\s+/).join(".")}${suffix}`;
+            }
+            return selector;
+    }
+}

package/src/layout/target.ts

@@ -0,0 +1,44 @@
+import { Privacy } from "@clarity-types/core";
+import { Event } from "@clarity-types/data";
+import { TargetMetadata } from "@clarity-types/layout";
+import hash from "@src/core/hash";
+import { track } from "@src/layout/region";
+import * as dom from "@src/layout/dom";
+import * as mutation from "@src/layout/mutation";
+
+export function target(evt: UIEvent): Node {
+    let path = evt.composed && evt.composedPath ? evt.composedPath() : null;
+    let node = (path && path.length > 0 ? path[0] : evt.target) as Node;
+    mutation.active(); // Mark active periods of time so mutations can continue uninterrupted
+    return node.nodeType === Node.DOCUMENT_NODE ? (node as Document).documentElement : node;
+}
+
+export function link(node: Node): HTMLAnchorElement {
+    while (node && node !== document) {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            let element = node as HTMLElement;
+            if (element.tagName === "A") {
+                return element as HTMLAnchorElement;
+            }
+        }
+        node = node.parentNode;
+    }
+    return null;
+}
+
+export function metadata(node: Node, event: Event): TargetMetadata {
+    // If the node is null, we return a reserved value for id: 0. Valid assignment of id begins from 1+.
+    let output: TargetMetadata = { id: 0, hash: null, selector: null, privacy: Privacy.Text, node };
+    if (node) {
+        let value = dom.get(node);
+        if (value !== null) {
+            output.id = value.id;
+            output.hash = value.selector ? hash(value.selector) : null;
+            output.selector = value.selector;
+            output.privacy = value.metadata.privacy;
+            if (value.region) { track(value.region, event); }
+        }
+    }
+
+    return output;
+}

package/src/layout/traverse.ts

@@ -0,0 +1,28 @@
+import { Task, Timer } from "@clarity-types/core";
+import { Source } from "@clarity-types/layout";
+import * as task from "@src/core/task";
+import processNode from "./node";
+
+export default async function(root: Node, timer: Timer, source: Source): Promise<void> {
+    let queue = [root];
+    while (queue.length > 0) {
+        let node = queue.shift();
+        let next = node.firstChild;
+
+        while (next) {
+            queue.push(next);
+            next = next.nextSibling;
+        }
+      
+        // Check the status of current task to see if we should yield before continuing
+        let state = task.state(timer);
+        if (state === Task.Wait) { state = await task.suspend(timer); }
+        if (state === Task.Stop) { break; }
+
+        // Check if processing a node gives us a pointer to one of its sub nodes for traversal
+        // E.g. an element node may give us a pointer to traverse shadowDom if shadowRoot property is set
+        // Or, an iframe from the same origin could give a pointer to it's document for traversing contents of iframe.
+        let subnode = processNode(node, source);
+        if (subnode) { queue.push(subnode); }
+    }
+}

package/src/performance/connection.ts

@@ -0,0 +1,37 @@
+import { BooleanFlag, Event } from "@clarity-types/data";
+import { ConnectionData, NavigatorConnection } from "@clarity-types/performance";
+import encode from "./encode";
+
+// Reference: https://wicg.github.io/netinfo/
+export let data: ConnectionData;
+
+export function start(): void {
+    // Check if the client supports Navigator.Connection: https://developer.mozilla.org/en-US/docs/Web/API/Navigator/connection
+    // This is an experimental API so we go a bit deeper in our check and ensure that values returned are valid
+    if (navigator &&
+        "connection" in navigator &&
+        "downlink" in navigator["connection"] &&
+        typeof navigator["connection"]["downlink"] === "number") {
+        (navigator["connection"] as NavigatorConnection).addEventListener("change", recompute);
+        recompute();
+    }
+}
+
+function recompute(): void {
+    let connection = navigator["connection"] as NavigatorConnection;
+    data = {
+        downlink: connection.downlink,
+        rtt: connection.rtt,
+        saveData: connection.saveData ? BooleanFlag.True : BooleanFlag.False,
+        type: connection.effectiveType
+    };
+    encode(Event.Connection);
+}
+
+export function reset(): void {
+    data = null;
+}
+
+export function stop(): void {
+    reset();
+}

package/src/performance/encode.ts

@@ -0,0 +1,40 @@
+import {Event, Token} from "@clarity-types/data";
+import { time } from "@src/core/time";
+import { queue } from "@src/data/upload";
+import * as connection from "@src/performance/connection";
+import * as navigation from "@src/performance/navigation";
+
+export default async function(type: Event): Promise<void> {
+    let t = time();
+    let tokens: Token[] = [t, type];
+    switch (type) {
+        case Event.Connection:
+            tokens.push(connection.data.downlink);
+            tokens.push(connection.data.rtt);
+            tokens.push(connection.data.saveData);
+            tokens.push(connection.data.type);
+            connection.reset();
+            queue(tokens, false);
+            break;
+        case Event.Navigation:
+            tokens.push(navigation.data.fetchStart);
+            tokens.push(navigation.data.connectStart);
+            tokens.push(navigation.data.connectEnd);
+            tokens.push(navigation.data.requestStart);
+            tokens.push(navigation.data.responseStart);
+            tokens.push(navigation.data.responseEnd);
+            tokens.push(navigation.data.domInteractive);
+            tokens.push(navigation.data.domComplete);
+            tokens.push(navigation.data.loadEventStart);
+            tokens.push(navigation.data.loadEventEnd);
+            tokens.push(navigation.data.redirectCount);
+            tokens.push(navigation.data.size);
+            tokens.push(navigation.data.type);
+            tokens.push(navigation.data.protocol);
+            tokens.push(navigation.data.encodedSize);
+            tokens.push(navigation.data.decodedSize);
+            navigation.reset();
+            queue(tokens, false);
+            break;
+    }
+}

package/src/performance/index.ts

@@ -0,0 +1,15 @@
+import * as connection from "@src/performance/connection";
+import * as navigation from "@src/performance/navigation";
+import * as observer from "@src/performance/observer";
+
+export function start(): void {
+    navigation.reset();
+    connection.start();
+    observer.start();
+}
+
+export function stop(): void {
+    observer.stop();
+    connection.stop();
+    navigation.reset();
+}

package/src/performance/navigation.ts

@@ -0,0 +1,31 @@
+import { Event } from "@clarity-types/data";
+import { NavigationData } from "@clarity-types/performance";
+import encode from "./encode";
+
+export let data: NavigationData = null;
+
+export function reset(): void {
+    data = null;
+}
+
+export function compute(entry: PerformanceNavigationTiming): void {
+    data = {
+        fetchStart: Math.round(entry.fetchStart),
+        connectStart: Math.round(entry.connectStart),
+        connectEnd: Math.round(entry.connectEnd),
+        requestStart: Math.round(entry.requestStart),
+        responseStart: Math.round(entry.responseStart),
+        responseEnd: Math.round(entry.responseEnd),
+        domInteractive: Math.round(entry.domInteractive),
+        domComplete: Math.round(entry.domComplete),
+        loadEventStart: Math.round(entry.loadEventStart),
+        loadEventEnd: Math.round(entry.loadEventEnd),
+        redirectCount: Math.round(entry.redirectCount),
+        size: entry.transferSize ? entry.transferSize : 0,
+        type: entry.type,
+        protocol: entry.nextHopProtocol,
+        encodedSize: entry.encodedBodySize ? entry.encodedBodySize : 0,
+        decodedSize: entry.decodedBodySize ? entry.decodedBodySize : 0
+    };
+    encode(Event.Navigation);
+}

package/src/performance/observer.ts

@@ -0,0 +1,87 @@
+import { Code, Constant, Dimension, Metric, Severity } from "@clarity-types/data";
+import { bind } from "@src/core/event";
+import measure from "@src/core/measure";
+import { setTimeout } from "@src/core/timeout";
+import * as dimension from "@src/data/dimension";
+import * as metric from "@src/data/metric";
+import * as internal from "@src/diagnostic/internal";
+import * as navigation from "@src/performance/navigation";
+
+let observer: PerformanceObserver;
+const types: string[] = [Constant.Navigation, Constant.Resource, Constant.LongTask, Constant.FID, Constant.CLS, Constant.LCP];
+
+export function start(): void {
+    // Check the browser support performance observer as a pre-requisite for any performance measurement
+    if (window["PerformanceObserver"] && PerformanceObserver.supportedEntryTypes) {
+        // Start monitoring performance data after page has finished loading.
+        // If the document.readyState is not yet complete, we intentionally call observe using a setTimeout.
+        // This allows us to capture loadEventEnd on navigation timeline.
+        if (document.readyState !== "complete") {
+            bind(window, "load", setTimeout.bind(this, observe, 0));
+        } else { observe(); }
+    } else { internal.log(Code.PerformanceObserver, Severity.Info); }
+}
+
+function observe(): void {
+    // Some browsers will throw an error for unsupported entryType, e.g. "layout-shift"
+    // In those cases, we log it as a warning and continue with rest of the Clarity processing
+    try {
+        if (observer) { observer.disconnect(); }
+        observer = new PerformanceObserver(measure(handle) as PerformanceObserverCallback);
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe
+        // "buffered" flag indicates whether buffered entries should be queued into the observer's buffer.
+        // It must only be used only with the "type" option, and cannot be used with entryTypes.
+        // This is why we need to individually "observe" each supported type
+        for (let x of types) {
+            if (PerformanceObserver.supportedEntryTypes.indexOf(x) >= 0) {
+                // Initialize CLS with a value of zero. It's possible (and recommended) for sites to not have any cumulative layout shift.
+                // In those cases, we want to still initialize the metric in Clarity
+                if (x === Constant.CLS) { metric.sum(Metric.CumulativeLayoutShift, 0); }
+                observer.observe({type: x, buffered: true});
+            }
+        }
+    } catch { internal.log(Code.PerformanceObserver, Severity.Warning); }
+}
+
+function handle(entries: PerformanceObserverEntryList): void {
+    process(entries.getEntries());
+}
+
+function process(entries: PerformanceEntryList): void {
+    let visible = "visibilityState" in document ? document.visibilityState === "visible" : true;
+    for (let i = 0; i < entries.length; i++) {
+        let entry = entries[i];
+        switch (entry.entryType) {
+            case Constant.Navigation:
+                navigation.compute(entry as PerformanceNavigationTiming);
+                break;
+            case Constant.Resource:
+                dimension.log(Dimension.NetworkHosts, host(entry.name));
+                break;
+            case Constant.LongTask:
+                metric.count(Metric.LongTaskCount);
+                break;
+            case Constant.FID:
+                if (visible) { metric.max(Metric.FirstInputDelay, entry["processingStart"] - entry.startTime); }
+                break;
+            case Constant.CLS:
+                // Scale the value to avoid sending back floating point number
+                if (visible && !entry["hadRecentInput"]) { metric.sum(Metric.CumulativeLayoutShift, entry["value"] * 1000); }
+                break;
+            case Constant.LCP:
+                if (visible) { metric.max(Metric.LargestPaint, entry.startTime); }
+                break;
+        }
+    }
+}
+
+export function stop(): void {
+    if (observer) { observer.disconnect(); }
+    observer = null;
+}
+
+function host(url: string): string {
+    let a = document.createElement("a");
+    a.href = url;
+    return a.hostname;
+}

package/test/core.test.ts

@@ -0,0 +1,82 @@
+import { expect } from 'chai';
+import { Browser, Page } from 'playwright';
+import { launch, markup, node, text } from './helper';
+import { Data, decode } from "clarity-decode";
+
+let browser: Browser;
+let page: Page;
+
+describe('Core Tests', () => {
+    before(async () => {
+        browser = await launch();
+    });
+
+    beforeEach(async () => {
+        page = await browser.newPage();
+        await page.goto('about:blank');
+    });
+
+    afterEach(async () => {
+        await page.close();
+    });
+
+    after(async () => {
+        await browser.close();
+        browser = null;
+    });
+
+    it('should mask sensitive content by default', async () => {
+        let encoded: string[] = await markup(page, "core.html");
+        let decoded = encoded.map(x => decode(x));
+        let heading = text(decoded, "one");
+        let address = text(decoded, "two");
+        let email = node(decoded, "attributes.id", "eml");
+        let password = node(decoded, "attributes.id", "pwd");
+        let search = node(decoded, "attributes.id", "search");
+
+        // Non-sensitive fields continue to pass through with sensitive bits masked off
+        expect(heading, "Thanks for your order •••••••••");
+
+        // Sensitive fields, including input fields, are randomized and masked
+        expect(address, "•••••• ••••• ••••• ••••• ••••• •••••");
+        expect(email.attributes.value, "••••• •••• •••• ••••");
+        expect(password.attributes.value, "••••• ••••");
+        expect(search.attributes.value, "••••• •••• ••••");
+    });
+
+    it('should mask all text in strict mode', async () => {
+        let encoded: string[] = await markup(page, "core.html", { content: false });
+        let decoded = encoded.map(x => decode(x));
+        let heading = text(decoded, "one");
+        let address = text(decoded, "two");
+        let email = node(decoded, "attributes.id", "eml");
+        let password = node(decoded, "attributes.id", "pwd");
+        let search = node(decoded, "attributes.id", "search");
+
+        // All fields are randomized and masked
+        expect(heading, "• ••••• ••••• ••••• ••••• •••••");
+        expect(address, "•••••• ••••• ••••• ••••• ••••• •••••");
+        expect(email.attributes.value, "••••• •••• •••• ••••");
+        expect(password.attributes.value, "••••• ••••");
+        expect(search.attributes.value, "••••• •••• ••••");
+    });
+
+    it('should mask all text in relaxed mode', async () => {
+        let encoded: string[] = await markup(page, "core.html", { unmask: ["body"] });
+        let decoded = encoded.map(x => decode(x));
+        let heading = text(decoded, "one");
+        let address = text(decoded, "two");
+        let email = node(decoded, "attributes.id", "eml");
+        let password = node(decoded, "attributes.id", "pwd");
+        let search = node(decoded, "attributes.id", "search");
+
+        // Text flows through unmasked for non-sensitive fields, including input fields
+        expect(heading, "Thanks for your order #2AB700GH");
+        expect(address, "1 Microsoft Way, Redmond, WA - 98052");
+        expect(search.attributes.value, "hello world");
+
+        // Sensitive fields are still masked
+        expect(email.attributes.value, "••••• •••• •••• ••••");
+        expect(password.attributes.value, "••••• ••••");
+    });
+});

package/test/helper.ts

@@ -0,0 +1,104 @@
+import { Core, Data, Layout } from "clarity-decode";
+import * as fs from 'fs';
+import * as path from 'path';
+import { Browser, Page, chromium } from 'playwright';
+
+export async function launch(): Promise<Browser> {
+    return chromium.launch({ headless: true, args: ['--no-sandbox'] });
+}
+
+export async function markup(page: Page, file: string, override: Core.Config = null): Promise<string[]> {
+    const html = fs.readFileSync(path.resolve(__dirname, `./html/${file}`), 'utf8');
+    await page.setContent(html.replace("</body>", `
+        <script>
+          window.payloads = [];
+          ${fs.readFileSync(path.resolve(__dirname, `../build/clarity.min.js`), 'utf8')};
+          clarity("start", ${config(override)});
+        </script>
+        </body>
+    `));
+    await page.waitForFunction("payloads && payloads.length > 1");
+    return await page.evaluate('payloads');
+}
+
+export function node(decoded: Data.DecodedPayload[], key: string, value: string | number, tag: string = null): Layout.DomData {
+    let sub = null;
+
+    // Exploding nested keys into key and sub key
+    if (key.indexOf(".") > 0) {
+        const parts = key.split(".");
+        if (parts.length === 2) {
+            key = parts[0];
+            sub = parts[1];
+        }
+    }
+
+    // Walking over the decoded payload to find the right match
+    for (let i = decoded.length - 1; i > 0; i--) {
+        if (decoded[i].dom) {
+            for (let j = 0; j < decoded[i].dom.length; j++) {
+                if (decoded[i].dom[j].data) {
+                    for (let k = 0; k < decoded[i].dom[j].data.length; k++) {
+                        let d = decoded[i].dom[j].data[k];
+                        if ((sub && d[key] && d[key][sub] === value) ||
+                            (d[key] && d[key] === value)) {
+                                if ((tag && d.tag === tag) || tag === null) {
+                                    return d;
+                                }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+
+export function text(decoded: Data.DecodedPayload[], id: string): string {
+    let parent = node(decoded, "attributes.id", id);
+    if (parent) {
+        let child = node(decoded, "parent", parent.id, "*T");
+        if (child && child.value) {
+            return child.value;
+        }
+    }
+    return null;
+}
+
+
+function config(override: Core.Config): string {
+    const settings = {
+        delay: 100,
+        content: true,
+        upload: payload => { window["payloads"].push(payload); window["clarity"]("upgrade", "test"); }
+    }
+
+    // Process overrides
+    if (override){
+        for (let key of Object.keys(override)) {
+            settings[key] = override[key];
+        }
+    }
+
+    // Serialize configuration
+    let output = "";
+    for (let key of Object.keys(settings)) {
+        switch (key) {
+            case "upload":
+                output += `${JSON.stringify(key)}: ${settings[key].toString()},`;
+                break;
+            case "projectId":
+            case "mask":
+            case "unmask":
+            case "regions":
+            case "cookies":
+                output += `${JSON.stringify(key)}: ${JSON.stringify(settings[key])},`;
+                break;
+            default:
+                output += `${JSON.stringify(key)}: ${settings[key]},`;
+                break;
+        }
+    }
+    output += `"projectId": "test"`;
+    return "{" + output + "}";
+}

package/test/html/core.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Core Tests</title>
+</head>
+<body>
+  <div>
+    <h1 id="one">Thanks for your order #2AB700GH</h1>
+    <p id="two" class="address-details">1 Microsoft Way, Redmond, WA - 98052</p>
+  </div>
+  <form name="login">
+    <input type="email" id="eml" title="Email" value="random@email.test">
+    <input type="password" id="pwd" title="Password" maxlength="16" value="passw0rd">
+    <input type="search" id="search" title="Search" value="hello world">
+  </form>
+</body>
+</html>

package/test/tsconfig.test.json

@@ -0,0 +1,6 @@
+{
+    "extends": "../tsconfig.json",
+    "compilerOptions": {
+      "module": "commonjs"
+    }
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+    "compilerOptions": {
+        "module": "esnext",
+        "target": "es5",
+        "lib": ["es6", "dom", "es2016", "es2017"],
+        "moduleResolution": "node",
+        "forceConsistentCasingInFileNames": true,
+        "noImplicitReturns": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "resolveJsonModule": true,
+        "esModuleInterop": true,
+        "baseUrl": ".",
+        "paths": {
+            "@src/*": ["src/*"],
+            "@clarity-types/*": ["types/*"]
+        }
+    },
+    "include":["src/**/*.ts","types/**/*.d.ts"],
+    "exclude": ["test", "node_modules", "build"]
+}

package/tslint.json

@@ -0,0 +1,33 @@
+{
+  "extends": "tslint:recommended",
+  "rules": {
+    "max-line-length": [
+      true,
+      140
+    ],
+    "no-console": [
+      false
+    ],
+    "no-string-literal": false,
+    "prefer-const": false,
+    "prefer-for-of": false,
+    "object-literal-sort-keys": false,
+    "one-variable-per-declaration": false,
+    "trailing-comma": [
+      false
+    ],
+    "variable-name": false,
+    "interface-name": false,
+    "interface-over-type-literal": false,
+    "only-arrow-functions": false,
+    "typedef": [
+      true,
+      "call-signature",
+      "parameter",
+      "property-declaration",
+      "member-variable-declaration",
+      "object-destructuring",
+      "array-destructuring"
+    ]
+  }
+}