@gem-sdk/clarity-decode 0.8.94

package/src/layout.ts

@@ -0,0 +1,186 @@
+import { Constant } from "@clarity-types/data";
+import { Data, Layout } from "@gem-sdk/clarity-js";
+import { DomData, LayoutEvent, Interaction, RegionVisibility } from "../types/layout";
+
+const AverageWordLength = 6;
+const Space = " ";
+
+export function decode(tokens: Data.Token[]): LayoutEvent {
+    let time = tokens[0] as number;
+    let event = tokens[1] as Data.Event;
+
+    switch (event) {
+        case Data.Event.Document:
+            let documentData: Layout.DocumentData = { width: tokens[2] as number, height: tokens[3] as number };
+            return { time, event, data: documentData };
+        case Data.Event.Region:
+            let regionData: Layout.RegionData[] = [];
+            // From 0.6.15 we send each reach update in an individual event. This allows us to include time with it.
+            // To keep it backward compatible (<= 0.6.14), we look for multiple regions in the same event. This works both with newer and older payloads.
+            // In future, we can update the logic to look deterministically for only 3 fields and remove the for loop.
+            let increment: number;
+            for (let i = 2; i < tokens.length; i += increment) {
+                let region: Layout.RegionData;
+                if (typeof(tokens[i+2]) == Constant.Number) {
+                    region = {
+                        id: tokens[i] as number,
+                        interaction: tokens[i + 1] as number,
+                        visibility: tokens[i + 2] as number,
+                        name: tokens[i + 3] as string
+                    };
+                    increment = 4;
+                } else {
+                    let state = tokens[i + 1] as number;
+                    region = {
+                        id: tokens[i] as number,
+                        // For backward compatibility before 0.6.24 - where region states were sent as a single enum 
+                        // we convert the value into the two states tracked after 0.6.24
+                        interaction:  state >= Interaction.None ? state : Interaction.None,
+                        visibility: state <= RegionVisibility.ScrolledToEnd ? state : RegionVisibility.Rendered,
+                        name: tokens[i + 2] as string
+                    };
+                    increment = 3;
+                }
+                regionData.push(region);
+            }
+            return { time, event, data: regionData };
+        case Data.Event.StyleSheetAdoption:
+            let styleSheetAdoptionData: Layout.StyleSheetData = {
+                id: tokens[2] as number,
+                operation: tokens[3] as number,
+                newIds: tokens[4] as string[]
+            };
+            return { time, event, data: styleSheetAdoptionData };
+        case Data.Event.StyleSheetUpdate:
+            let styleSheetUpdateData: Layout.StyleSheetData = {
+                id: tokens[2] as string,
+                operation: tokens[3] as number,
+                cssRules: tokens[4] as string
+            }
+            return { time, event, data: styleSheetUpdateData };
+        case Data.Event.Animation:
+            let animationData: Layout.AnimationData = {
+                id: tokens[2] as string,
+                operation: tokens[3] as number,
+                keyFrames: tokens[4] as string,
+                timing: tokens[5] as string,
+                timeline: tokens[6] as string,
+                targetId: tokens[7] as number
+            }
+            return { time, event, data: animationData};
+        case Data.Event.Discover:
+        case Data.Event.Mutation:
+        case Data.Event.Snapshot:
+            let lastType = null;
+            let node = [];
+            let tagIndex = 0;
+            let domData: DomData[] = [];
+            for (let i = 2; i < tokens.length; i++) {
+                let token = tokens[i];
+                let type = typeof(token);
+                switch (type) {
+                    case "number":
+                        if (type !== lastType && lastType !== null) {
+                            domData.push(process(node, tagIndex));
+                            node = [];
+                            tagIndex = 0;
+                        }
+                        node.push(token);
+                        tagIndex++;
+                        break;
+                    case "string":
+                        node.push(token);
+                        break;
+                    case "object":
+                        let subtoken = token[0];
+                        let subtype = typeof(subtoken);
+                        switch (subtype) {
+                            case "number":
+                                for (let t of (token as number[])) {
+                                    node.push(tokens.length > t ? tokens[t] : null);
+                                }
+                                break;
+                        }
+                }
+                lastType = type;
+            }
+            // Process last node
+            domData.push(process(node, tagIndex));
+
+            return { time, event, data: domData };
+        case Data.Event.CustomElement:
+            let customElement: Layout.CustomElementData = { name: tokens[2] as string };
+            return { time, event, data: customElement };
+    }
+    return null;
+}
+
+function process(node: any[] | number[], tagIndex: number): DomData {
+    // For backward compatibility, only extract the tag even if position is available as part of the tag name
+    // And, continue computing position in the visualization library from decoded payload.
+    let tag  = node[tagIndex] ? node[tagIndex].split("~")[0] : node[tagIndex];
+    let output: DomData = {
+        id: Math.abs(node[0]),
+        parent: tagIndex > 1 ? node[1] : null,
+        previous: tagIndex > 2 ? node[2] : null,
+        tag
+    };
+    let masked = node[0] < 0;
+    let hasAttribute = false;
+    let attributes: Layout.Attributes = {};
+    let value = null;
+
+    for (let i = tagIndex + 1; i < node.length; i++) {
+        // Explicitly convert the token into a string value
+        let token = node[i].toString();
+        let keyIndex = token.indexOf("=");
+        let firstChar = token[0];
+        let lastChar = token[token.length - 1];
+        if (i === (node.length - 1) && output.tag === "STYLE") {
+            value = token;
+        } else if (output.tag !== Layout.Constant.TextTag && lastChar === ">" && keyIndex === -1) {
+            // Backward compatibility - since v0.6.25
+            // Ignore this conditional block since we no longer compute selectors at decode time to save on uploaded bytes
+            // Instead, we now compute selector and hash at visualization layer where we have access to all payloads together
+        } else if (output.tag !== Layout.Constant.TextTag && firstChar === Layout.Constant.Hash && keyIndex === -1) {
+            let parts = token.substr(1).split(Layout.Constant.Period);
+            if (parts.length === 2) {
+                output.width = num(parts[0]) / Data.Setting.BoxPrecision;
+                output.height = num(parts[1]) / Data.Setting.BoxPrecision;
+            }
+        } else if (output.tag !== Layout.Constant.TextTag && keyIndex > 0) {
+            hasAttribute = true;
+            let k = token.substr(0, keyIndex);
+            let v = token.substr(keyIndex + 1);
+            attributes[k] = v;
+        } else if (output.tag === Layout.Constant.TextTag) {
+            value = masked ? unmask(token) : token;
+        }
+    }
+
+    if (hasAttribute) { output.attributes = attributes; }
+    if (value) { output.value = value; }
+
+    return output;
+}
+
+function num(input: string): number {
+    return input ? parseInt(input, 36) : null;
+}
+
+function unmask(value: string): string {
+    let trimmed = value.trim();
+    if (trimmed.length > 0 && trimmed.indexOf(Space) === -1) {
+        let length = num(trimmed);
+        if (length > 0) {
+            let quotient = Math.floor(length / AverageWordLength);
+            let remainder = length % AverageWordLength;
+            let output = Array(remainder + 1).join(Data.Constant.Mask);
+            for (let i = 0; i < quotient; i++) {
+                output += (i === 0 && remainder === 0 ? Data.Constant.Mask : Space) + Array(AverageWordLength).join(Data.Constant.Mask);
+            }
+            return output;
+        }
+    }
+    return value;
+}

package/src/performance.ts

@@ -0,0 +1,30 @@
+import { Data, Performance } from "@gem-sdk/clarity-js";
+import { PerformanceEvent } from "../types/performance";
+
+export function decode(tokens: Data.Token[]): PerformanceEvent  {
+    let time = tokens[0] as number;
+    let event = tokens[1] as Data.Event;
+    switch (event) {
+        case Data.Event.Navigation:
+            let navigationData: Performance.NavigationData = {
+                fetchStart: tokens[2] as number,
+                connectStart: tokens[3] as number,
+                connectEnd: tokens[4] as number,
+                requestStart: tokens[5] as number,
+                responseStart: tokens[6] as number,
+                responseEnd: tokens[7] as number,
+                domInteractive: tokens[8] as number,
+                domComplete: tokens[9] as number,
+                loadEventStart: tokens[10] as number,
+                loadEventEnd: tokens[11] as number,
+                redirectCount: tokens[12] as number,
+                size: tokens[13] as number,
+                type: tokens[14] as string,
+                protocol: tokens[15] as string,
+                encodedSize: tokens[16] as number,
+                decodedSize: tokens[17] as number
+            };
+            return { time, event, data: navigationData };
+    }
+    return null;
+}

package/test/decode.test.ts

@@ -0,0 +1,62 @@
+import { test, expect } from '@playwright/test';
+import { decode } from '@gem-sdk/clarity-decode';
+
+test.describe('decode function', () => {
+    test('should decode a simple payload', () => {
+        // This is a very simple test that focuses on basic decoding functionality
+        const testPayload = {
+          e: ["0.8.20", 1, 0, 506, "devtools", "1mtqiaz", "1c27tix", 2, 0, 0, 0, "https://test.com/"],
+          a: [
+            [2, 8, 1982, 3098],
+            [29, 11, 1982, 992],
+            [29, 28, 1],
+            [35, 29, 63, 65, 421, 421, 551, 552, 941, 1820, 1821, 1826, 0, 23734, "navigate", "h2", 23434, 138226],
+            [36, 7, 116, 16, 13, "1"],
+            [36, 7, 120, 16, 0, "2"],
+            [36, 7, 203, 16, 13, "3"],
+            [505, 1, 0, ["Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36 Edg/138.0.0.0"], 1, ["https://test.com/"], 3, ["A little bit of this and that!"], 4, ["test.com"], 5, ["BlogPosting"], 9, ["en-US"], 15, ["1xtxvl0"], 17, ["ltr"], 18, ["Story 8", "Story 7", "Story 6"], 20, ["A title!"], 21, ["blogger"], 22, ["macOS"], 23, ["15.5.0"], 24, ["undefined~8", "undefined~138"], 26, ["1.7999999523162842"], 27, ["4g"], 28, ["1979"], 29, ["2"], 31, ["44nejbc7s.6933hhug7"], 32, ["519i394pb.53uwavtzg"], 34, ["America/Los_Angeles"], 35, ["420"], 36, ["1"], 37, ["-1"]],
+            [505, 0, 0, 1752816151601, 1, 1, 3, 34, 4, 35, 5, 3, 7, 4, 8, 1636, 9, 0, 10, 2, 14, 1792, 15, 1120, 16, 24, 25, 9, 26, 0, 27, 0, 31, 1, 32, 0, 33, 8, 34, 8, 35, 0],
+            [506, 47, 0, 1, 1],
+            [550, 48, 488, 493, 484, 16383, 16383, 2, 1, 0, "It's a title", null, "1ltv07afj", "4ppc0yuhe", 1, 0]
+          ],
+        };
+
+        const input = JSON.stringify(testPayload);
+
+        const result = decode(input);
+        
+        expect(typeof result).toBe('object');
+        expect(typeof result.timestamp).toBe('number');
+        expect(typeof result.envelope).toBe('object');
+        expect(result.envelope.version).toBe("0.8.20");
+        expect(result.visibility[0].data.visible).toBe(1);
+        expect(result.contextMenu[0].data.target).toBe(488);
+        expect(result.contextMenu[0].data.button).toBe(2);
+    });
+
+    test('visibility event should be backward compatible to support string values', () => {
+        // This is a very simple test that focuses on basic decoding functionality
+        const testPayload = {
+          e: ["0.8.20", 1, 0, 506, "devtools", "1mtqiaz", "1c27tix", 2, 0, 0, 0, "https://test.com/"],
+          a: [
+            [2, 8, 1982, 3098],
+            [29, 11, 1982, 992],
+            [29, 28, "visible"],
+            [505, 1, 0, ["Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36 Edg/138.0.0.0"], 1, ["https://test.com/"], 3, ["A little bit of this and that!"], 4, ["test.com"], 5, ["BlogPosting"], 9, ["en-US"], 15, ["1xtxvl0"], 17, ["ltr"], 18, ["Story 8", "Story 7", "Story 6"], 20, ["A title!"], 21, ["blogger"], 22, ["macOS"], 23, ["15.5.0"], 24, ["undefined~8", "undefined~138"], 26, ["1.7999999523162842"], 27, ["4g"], 28, ["1979"], 29, ["2"], 31, ["44nejbc7s.6933hhug7"], 32, ["519i394pb.53uwavtzg"], 34, ["America/Los_Angeles"], 35, ["420"], 36, ["1"], 37, ["-1"]],
+            [505, 0, 0, 1752816151601, 1, 1, 3, 34, 4, 35, 5, 3, 7, 4, 8, 1636, 9, 0, 10, 2, 14, 1792, 15, 1120, 16, 24, 25, 9, 26, 0, 27, 0, 31, 1, 32, 0, 33, 8, 34, 8, 35, 0],
+            [506, 47, 0, 1, 1],
+            [550, 48, 488, 493, 484, 16383, 16383, 2, 1, 0, "It's a title", null, "1ltv07afj", "4ppc0yuhe", 1, 0]
+          ],
+        };
+
+        const input = JSON.stringify(testPayload);
+
+        const result = decode(input);
+        
+        expect(typeof result).toBe('object');
+        expect(typeof result.timestamp).toBe('number');
+        expect(typeof result.envelope).toBe('object');
+        expect(result.envelope.version).toBe("0.8.20");
+        expect(result.visibility[0].data.visible).toBe(1);
+    });
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "baseUrl": ".",
+        "paths": {
+            "@src/*": ["src/*"],
+            "@clarity-types/*": ["types/*"]
+        }
+    },
+    "include":["src/**/*.ts", "types/**/*.d.ts", "test/**/*.ts", "rollup.config.ts"],
+    "exclude": ["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"
+    ]
+  }
+}

package/types/core.d.ts

@@ -0,0 +1,8 @@
+import { Core, Data } from "@gem-sdk/clarity-js";
+
+export import Config = Core.Config;
+
+export interface PartialEvent {
+    time: number;
+    event: Data.Event;
+}

package/types/data.d.ts

@@ -0,0 +1,94 @@
+import { Data } from "@gem-sdk/clarity-js";
+import { DiagnosticEvent, FraudEvent, LogEvent, ScriptErrorEvent } from "./diagnostic";
+import { ChangeEvent, ClickEvent, ContextMenuEvent, ClipboardEvent, InputEvent, InteractionEvent, PointerEvent, ResizeEvent, SubmitEvent } from "./interaction";
+import { ScrollEvent, SelectionEvent, TimelineEvent, UnloadEvent, VisibilityEvent, FocusEvent } from "./interaction";
+import { DocumentEvent, DomEvent, LayoutEvent, RegionEvent, CustomElementEvent } from "./layout";
+import { NavigationEvent, PerformanceEvent } from "./performance";
+import { PartialEvent } from "./core";
+
+/* Redeclare enums */
+export import Envelope = Data.Envelope;
+export import Code = Data.Code;
+export import Dimension = Data.Dimension;
+export import Event = Data.Event;
+export import Metric = Data.Metric;
+export import Payload = Data.Payload;
+export import BooleanFlag = Data.BooleanFlag;
+export import Constant = Data.Constant;
+export import Setting = Data.Setting;
+
+/* Data Events */
+export interface BaselineEvent extends PartialEvent { data: Data.BaselineData; }
+export interface DimensionEvent extends PartialEvent { data: Data.DimensionData; }
+export interface MetricEvent extends PartialEvent { data: Data.MetricData; }
+export interface CustomEvent extends PartialEvent { data: Data.CustomData; }
+export interface VariableEvent extends PartialEvent { data: Data.VariableData; }
+export interface PingEvent extends PartialEvent { data: Data.PingData; }
+export interface LimitEvent extends PartialEvent { data: Data.LimitData; }
+export interface SummaryEvent extends PartialEvent { data: Data.SummaryData; }
+export interface UpgradeEvent extends PartialEvent { data: Data.UpgradeData; }
+export interface UploadEvent extends PartialEvent { data: Data.UploadData; }
+export interface ExtractEvent extends PartialEvent { data: Data.ExtractData; }
+export interface ConsentEvent extends PartialEvent { data: Data.ConsentData; }
+export interface DataEvent extends PartialEvent {
+    data: Data.BaselineData |
+    Data.DimensionData | 
+    Data.MetricData |
+    Data.CustomData |
+    Data.VariableData |
+    Data.PingData |
+    Data.LimitData |
+    Data.SummaryData |
+    Data.UpgradeData |
+    Data.UploadData | 
+    Data.ExtractData |
+    Data.ConsentData;
+}
+
+export type DecodedEvent = DataEvent | DiagnosticEvent | InteractionEvent | LayoutEvent | PerformanceEvent;
+
+export interface DecodedPayload {
+    timestamp: number;
+    envelope: Data.Envelope;
+    metric?: MetricEvent[];
+    dimension?: DimensionEvent[];
+    ping?: PingEvent[];
+    limit?: LimitEvent[];
+    script?: ScriptErrorEvent[];
+    input?: InputEvent[];
+    pointer?: PointerEvent[];
+    click?: ClickEvent[];
+    contextMenu?: ContextMenuEvent[];
+    clipboard?: ClipboardEvent[];
+    resize?: ResizeEvent[];
+    scroll?: ScrollEvent[];
+    selection?: SelectionEvent[];
+    change?: ChangeEvent[];
+    submit?: SubmitEvent[];
+    summary?: SummaryEvent[];
+    timeline?: TimelineEvent[];
+    unload?: UnloadEvent[];
+    upgrade?: UpgradeEvent[];
+    upload?: UploadEvent[];
+    visibility?: VisibilityEvent[];
+    focus?: FocusEvent[];
+    region?: RegionEvent[];
+    dom?: DomEvent[];
+    doc?: DocumentEvent[];
+    navigation?: NavigationEvent[];
+    log?: LogEvent[];
+    fraud?: FraudEvent[];
+    baseline?: BaselineEvent[];
+    variable?: VariableEvent[];
+    custom?: CustomEvent[];
+    extract?: ExtractEvent[];
+    consent?: ConsentEvent[];
+    customElement?: CustomElementEvent[];
+}
+
+export interface DecodedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    beta: number;
+}

package/types/diagnostic.d.ts

@@ -0,0 +1,10 @@
+import { Diagnostic } from "@gem-sdk/clarity-js";
+import { PartialEvent } from "./core";
+
+export interface ScriptErrorEvent extends PartialEvent { data: Diagnostic.ScriptErrorData; }
+export interface LogEvent extends PartialEvent { data: Diagnostic.LogData; }
+export interface FraudEvent extends PartialEvent { data: Diagnostic.FraudData; }
+
+export interface DiagnosticEvent extends PartialEvent {
+    data: Diagnostic.FraudData | Diagnostic.LogData | Diagnostic.ScriptErrorData;
+}

package/types/index.d.ts

@@ -0,0 +1,10 @@
+import * as Core from "./core";
+import * as Data from "./data";
+import * as Diagnostic from "./diagnostic";
+import * as Layout from "./layout";
+import * as Interaction from "./interaction";
+import * as Performance from "./performance";
+
+export function decode(data: string): Data.DecodedPayload;
+
+export { Core, Data, Diagnostic, Layout, Interaction, Performance };

package/types/interaction.d.ts

@@ -0,0 +1,46 @@
+import { Interaction } from "@gem-sdk/clarity-js";
+import { PartialEvent } from "./core";
+
+export interface ClickData extends Interaction.ClickData {
+    hashBeta: string;
+}
+
+export interface TimelineData extends Interaction.TimelineData {
+    hashBeta: string;
+}
+
+export interface ClickVizualizationData {
+    doc: HTMLElement;
+    click: HTMLElement;
+    time: number;
+}
+
+export interface InputEvent extends PartialEvent { data: Interaction.InputData; }
+export interface ChangeEvent extends PartialEvent { data: Interaction.ChangeData; }
+export interface ClickEvent extends PartialEvent { data: ClickData; }
+export interface ContextMenuEvent extends PartialEvent { data: ClickData; }
+export interface ClipboardEvent extends PartialEvent { data: Interaction.ClipboardData; }
+export interface PointerEvent extends PartialEvent { data: Interaction.PointerData; }
+export interface ResizeEvent extends PartialEvent { data: Interaction.ResizeData; }
+export interface ScrollEvent extends PartialEvent { data: Interaction.ScrollData; }
+export interface SelectionEvent extends PartialEvent { data: Interaction.SelectionData; }
+export interface SubmitEvent extends PartialEvent { data: Interaction.SubmitData; }
+export interface TimelineEvent extends PartialEvent { data: TimelineData; }
+export interface UnloadEvent extends PartialEvent { data: Interaction.UnloadData; }
+export interface VisibilityEvent extends PartialEvent { data: Interaction.VisibilityData; }
+export interface FocusEvent extends PartialEvent { data: Interaction.FocusData; }
+export interface InteractionEvent extends PartialEvent {
+    data: ClickData |
+    Interaction.ChangeData |
+    Interaction.ClipboardData |
+    Interaction.InputData |
+    Interaction.PointerData |
+    Interaction.ResizeData |
+    Interaction.ScrollData |
+    Interaction.SelectionData |
+    Interaction.SubmitData |
+    TimelineData |
+    Interaction.UnloadData |
+    Interaction.VisibilityData |
+    Interaction.FocusData;
+}

package/types/layout.d.ts

@@ -0,0 +1,36 @@
+import { Layout } from "@gem-sdk/clarity-js";
+import { PartialEvent } from "./core";
+
+export interface RegionEvent extends PartialEvent { data: Layout.RegionData[]; }
+export interface DocumentEvent extends PartialEvent { data: Layout.DocumentData; }
+export interface DomEvent extends PartialEvent { data: DomData[]; }
+export interface StyleSheetEvent extends PartialEvent { data: Layout.StyleSheetData }
+export interface AnimationEvent extends PartialEvent { data: Layout.AnimationData; }
+export interface CustomElementEvent extends PartialEvent { data: Layout.CustomElementData; }
+export interface LayoutEvent extends PartialEvent {
+    data: Layout.RegionData[] | Layout.DocumentData | DomData[] | Layout.StyleSheetData | Layout.AnimationData | Layout.CustomElementData;
+}
+
+/* Redeclare enums */
+export import Constant = Layout.Constant;
+export import Interaction = Layout.InteractionState;
+export import RegionVisibility = Layout.RegionVisibility;
+export import SelectorInput = Layout.SelectorInput;
+export import Selector = Layout.Selector;
+
+/* Event Data */
+export interface DomData {
+    id: number;
+    parent: number;
+    previous: number;
+    tag: string;
+    attributes?: Layout.Attributes;
+    value?: string;
+    width?: number;
+    height?: number;
+    selectorAlpha?: string;
+    hashAlpha?: string;
+    selectorBeta?: string;
+    hashBeta?: string;
+    checksum?: string;
+}

package/types/performance.d.ts

@@ -0,0 +1,7 @@
+import { Performance } from "@gem-sdk/clarity-js";
+import { PartialEvent } from "./core";
+
+export interface NavigationEvent extends PartialEvent { data: Performance.NavigationData; }
+export interface PerformanceEvent extends PartialEvent {
+    data: Performance.NavigationData
+}