@gem-sdk/clarity-js 0.8.94

package/types/data.d.ts

@@ -0,0 +1,611 @@
+import { Time } from "@clarity-types/core";
+export type Target = (number | Node);
+export type Token = (string | number | number[] | string[] | (string | number)[]);
+export type DecodedToken = (any | any[]);
+
+export type MetadataCallback = (data: Metadata, playback: boolean, consentStatus?: ConsentState) => void;
+export interface MetadataCallbackOptions {
+    callback: MetadataCallback,
+    wait: boolean,
+    recall: boolean,
+    called: boolean,
+    consentInfo: boolean
+}
+export type SignalCallback = (data: ClaritySignal) => void
+
+/* Enum */
+export const enum Event {
+    /* Data */
+    Metric = 0,
+    Dimension = 1,
+    Upload = 2,
+    Upgrade = 3,
+    Baseline = 4,
+    Discover = 5,
+    Mutation = 6,
+    Region = 7,
+    Document = 8,
+    Click = 9,
+    Scroll = 10,
+    Resize = 11,
+    MouseMove = 12,
+    MouseDown = 13,
+    MouseUp = 14,
+    MouseWheel = 15,
+    DoubleClick = 16,
+    TouchStart = 17,
+    TouchEnd = 18,
+    TouchMove = 19,
+    TouchCancel = 20,
+    Selection = 21,
+    Timeline = 22,
+    Page = 23,
+    Custom = 24,
+    Ping = 25,
+    Unload = 26,
+    Input = 27,
+    Visibility = 28,
+    Navigation = 29,
+    /**
+     * @deprecated No longer support Network Connection
+     */
+    Connection = 30,
+    ScriptError = 31,
+    /**
+     * @deprecated No longer support Image Error
+     */
+    ImageError = 32,
+    Log = 33,
+    Variable = 34,
+    Limit = 35,
+    Summary = 36,
+    /**
+     * @deprecated No longer support Box event
+     */
+    Box = 37,
+    Clipboard = 38,
+    Submit = 39,
+    Extract = 40,
+    Fraud = 41,
+    Change = 42,
+    Snapshot = 43,
+    Animation = 44,
+    StyleSheetAdoption = 45,
+    StyleSheetUpdate = 46,
+    Consent = 47,
+    ContextMenu = 48,
+    // 49 is reserved for internal use
+    Focus = 50,
+    CustomElement = 51,
+    Chat = 52,
+
+    // Apps specific events
+    WebViewDiscover = 100,
+    WebViewMutation = 101,
+    MutationError = 102,
+    FragmentVisibility = 103,
+    Keystrokes = 104,
+    BackGesture = 105,
+    WebViewStatus = 106,
+    AppInstallReferrer = 107
+    // 200-300 reserved for internal use
+}
+
+export const enum Metric {
+    ClientTimestamp = 0,
+    Playback = 1,
+    TotalBytes = 2,
+    LayoutCost = 3,
+    TotalCost = 4,
+    InvokeCount = 5,
+    ThreadBlockedTime = 6,
+    LongTaskCount = 7,
+    LargestPaint = 8,
+    CumulativeLayoutShift = 9,
+    FirstInputDelay = 10,
+    RatingValue = 11,
+    RatingCount = 12,
+    ProductPrice = 13,
+    ScreenWidth = 14,
+    ScreenHeight = 15,
+    ColorDepth = 16,
+    ReviewCount = 17,
+    BestRating = 18,
+    WorstRating = 19,
+    CartPrice = 20,
+    CartShipping = 21,
+    CartDiscount = 22,
+    CartTax = 23,
+    CartTotal = 24,
+    EventCount = 25,
+    Automation = 26,
+    Mobile = 27,
+    UploadTime = 28,
+    SinglePage = 29,
+    /**
+     * @deprecated Browser API is deprecated. Reference: https://developer.mozilla.org/en-US/docs/Web/API/Performance/memory
+     */
+    UsedMemory = 30,
+    Iframed = 31,
+    MaxTouchPoints = 32,
+    HardwareConcurrency = 33,
+    DeviceMemory = 34,
+    Electron = 35,
+    /**
+     * @deprecated No longer tracking
+     */
+    ConstructedStyles = 36,
+    /**
+     * @deprecated Move it to dimension as it'll report only last value
+     */
+    InteractionNextPaint = 37,
+    HistoryClear = 38,
+    AngularZone = 39,
+    // 200-300 reserved for internal use
+}
+
+export const enum Dimension {
+    UserAgent = 0,
+    Url = 1,
+    Referrer = 2,
+    PageTitle = 3,
+    NetworkHosts = 4,
+    SchemaType = 5,
+    ProductBrand = 6,
+    ProductAvailability = 7,
+    AuthorName = 8,
+    Language = 9,
+    ProductName = 10,
+    ProductCategory = 11,
+    ProductSku = 12,
+    ProductCurrency = 13,
+    ProductCondition = 14,
+    TabId = 15,
+    PageLanguage = 16,
+    DocumentDirection = 17,
+    Headline = 18,
+    MetaType = 19,
+    MetaTitle = 20,
+    Generator = 21,
+    Platform = 22,
+    PlatformVersion = 23,
+    Brand = 24,
+    Model = 25,
+    DevicePixelRatio = 26,
+    ConnectionType = 27,
+    Dob = 28,
+    CookieVersion = 29,
+    DeviceFamily = 30, // Allows iOS SDK to override the DeviceFamily value parsed from UserAgent.
+    InitialScrollTop = 31,
+    InitialScrollBottom = 32,
+    AncestorOrigins = 33,
+    Timezone = 34,
+    TimezoneOffset = 35,
+    Consent = 36,
+    InteractionNextPaint = 37
+    // 200-300 reserved for internal use
+}
+
+export const enum Check {
+    None = 0,
+    Payload = 1,
+    Shutdown = 2,
+    Retry = 3,
+    Bytes = 4,
+    Collection = 5,
+    Server = 6,
+    Page = 7
+}
+
+export const enum Code {
+    RunTask = 0,
+    CssRules = 1,
+    MutationObserver = 2,
+    PerformanceObserver = 3,
+    CallStackDepth = 4,
+    Selector = 5,
+    Metric = 6,
+    /**
+     * @deprecated No longer support ContentSecurityPolicy
+     */
+    ContentSecurityPolicy = 7,
+    Config = 8,
+    FunctionExecutionTime = 9,
+    LeanLimit = 10,
+    BFCache = 11,
+}
+
+export const enum Severity {
+    Info = 0,
+    Warning = 1,
+    Error = 2,
+    Fatal = 3
+}
+
+export const enum Upload {
+    Async = 0,
+    Beacon = 1
+}
+
+export const enum BooleanFlag {
+    False = 0,
+    True = 1
+}
+
+export const enum GCMConsent {
+    Unknown = 0,
+    Granted = 1,
+    Denied = 2
+}
+
+export const enum IframeStatus {
+    Unknown = 0,
+    TopFrame = 1,
+    Iframe = 2
+}
+
+export const enum Setting {
+    Expire = 365, // 1 Year
+    SessionExpire = 1, // 1 Day
+    CookieVersion = 2, // Increment this version every time there's a cookie schema change
+    SessionTimeout = 30 * Time.Minute, // 30 minutes
+    CookieInterval = 1, // 1 Day
+    PingInterval = 1 * Time.Minute, // 1 Minute
+    PingTimeout = 5 * Time.Minute, // 5 Minutes
+    SummaryInterval = 100, // Same events within 100ms will be collapsed into single summary
+    ClickText = 25, // Maximum number of characters to send as part of Click event's text field
+    ClickClass = 50, // Maximum number of characters to send as part of Click event's class name
+    ClickTag = 10, // Maximum number of characters to send as part of Click event's tag
+    ClickId = 25, // Maximum number of characters to send as part of Click event's id
+    PayloadLimit = 128, // Do not allow more than specified payloads per page
+    PageLimit = 128, // Do not allow more than 128 pages in a session
+    ShutdownLimit = 2 * Time.Hour, // Shutdown instrumentation after specified time
+    RetryLimit = 1, // Maximum number of attempts to upload a payload before giving up
+    PlaybackBytesLimit = 10 * 1024 * 1024, // 10MB
+    CollectionLimit = 128, // Number of unique entries for dimensions
+    ClickPrecision = 32767, // 2^15 - 1
+    ClickParentTraversal = 10, // Maximum number of parent elements to traverse when computing relative click coordinates
+    BoxPrecision = 100, // Up to 2 decimal points (e.g. 34.56)
+    ScriptErrorLimit = 5, // Do not send the same script error more than 5 times per page
+    DimensionLimit = 256, // Do not extract dimensions which are over 256 characters
+    WordLength = 5, // Estimated average size of a word,
+    RestartDelay = 250, // Wait for 250ms before starting to wire up again
+    CallStackDepth = 20, // Maximum call stack depth before bailing out
+    RatingScale = 100, // Scale rating to specified scale
+    ViewportIntersectionRatio = 0.05, // Ratio of intersection area in comparison to viewport area before it's marked visible
+    IntersectionRatio = 0.8, // Ratio of intersection area in comparison to element's area before it's marked visible
+    MaxFirstPayloadBytes = 1 * 1024 * 1024, // 1MB: Cap the very first payload to a maximum of 1MB
+    MegaByte = 1024 * 1024, // 1MB
+    UploadFactor = 3, // Slow down sequence by specified factor
+    MinUploadDelay = 100, // Minimum time before we are ready to flush events to the server
+    MaxUploadDelay = 30 * Time.Second, // Do flush out payload once every 30s,
+    ExtractLimit = 10000, // Do not extract more than 10000 characters
+    ChecksumPrecision = 28, // n-bit integer to represent token hash
+    UploadTimeout = 15000, // Timeout in ms for XHR requests
+    LongTask = 30, // Long Task threshold in ms
+    MaxBeaconPayloadBytes = 64 * 1024, // 64KB: Cap the beacon payload to a maximum of 64KB
+}
+
+export const enum Character {
+    Zero = 48,
+    Nine = 57,
+    At = 64,
+    Blank = 32,
+    Tab = 9,
+    NewLine = 10,
+    Return = 13
+}
+
+export const enum ApplicationPlatform {
+    WebApp = 0
+}
+
+export const enum Constant {
+    Auto = "Auto",
+    Config = "Config",
+    Clarity = "clarityGemX",
+    Restart = "restart",
+    Suspend = "suspend",
+    Pause = "pause",
+    Resume = "resume",
+    Report = "report",
+    Memory = "memory",
+    Empty = "",
+    Space = " ",
+    Expires = "expires=",
+    Domain = "domain=",
+    Dropped = "*na*",
+    Comma = ",",
+    Dot = ".",
+    At = "@",
+    Asterix = "*",
+    Semicolon = ";",
+    Equals = "=",
+    Path = ";path=/",
+    Target = "target",
+    Blank = "_blank",
+    Parent = "_parent",
+    Top = "_top",
+    String = "string",
+    Number = "number",
+    Email = "email",
+    CookieKey = "_clck", // Clarity Cookie Key
+    SessionKey = "_clsk", // Clarity Session Key
+    TabKey = "_cltk", // Clarity Tab Key
+    Pipe = "|",
+    End = "END",
+    Upgrade = "UPGRADE",
+    Action = "ACTION",
+    Signal = "SIGNAL",
+    Extract = "EXTRACT",
+    Snapshot = "SNAPSHOT",
+    Module = "MODULE",
+    UserHint = "userHint",
+    UserType = "userType",
+    UserId = "userId",
+    SessionId = "sessionId",
+    PageId = "pageId",
+    Mask = "•", // Placeholder character for explicitly masked content
+    Digit = "▫", // Placeholder character for digits
+    Letter = "▪", // Placeholder character for letters
+    SessionStorage = "sessionStorage",
+    Cookie = "cookie",
+    Navigation = "navigation",
+    Resource = "resource",
+    LongTask = "longtask",
+    FID = "first-input",
+    CLS = "layout-shift",
+    LCP = "largest-contentful-paint",
+    PerformanceEventTiming = "event",
+    HTTPS = "https://",
+    CompressionStream = "CompressionStream",
+    Accept = "Accept",
+    ClarityGzip = "application/x-clarity-gzip",
+    Tilde = "~",
+    ArrayStart = "[",
+    ConditionStart = "{",
+    ConditionEnd = "}",
+    Seperator = "<SEP>",
+    Timeout = "Timeout",
+    Bang = "!",
+    SHA256 = "SHA-256",
+    Electron = "Electron",
+    Caret = "^",
+    Granted = "granted",
+    Denied = "denied",
+    AdStorage = "ad_storage",
+    AnalyticsStorage = "analytics_storage",
+}
+
+export const enum XMLReadyState {
+    Unsent = 0,
+    Opened = 1,
+    Headers_Recieved = 2,
+    Loading = 3,
+    Done = 4
+}
+
+export const enum ConsentSource {
+    Implicit = 0,
+    API = 1,
+    GCM = 2,
+    TCF = 3,
+    APIv1 = 4,
+    APIv2 = 5,
+    Cookie = 6,
+    Default = 7,
+    // 100-255 Reserved for CMP integration, both internal and external
+    ClarityShopifyPixel = 100,
+    ClarityShopifyApp = 101,
+    UET = 102,
+
+    //CMPs
+    CmpMyAgilePrivacy = 150,
+    CmpUserCentrics = 151,
+    CmpCookiebot = 152,
+    CmpAxeptio = 153,
+    CmpCookiehub = 154,
+    CmpCookieYes = 155,
+    CmpWebTofee = 156,
+    CmpWPConsent = 157,
+    CmpSeersAI = 158,
+    // Reserved to indicate an unknown consent source
+    Unknown = 255,
+}
+
+/* Helper Interfaces */
+
+export interface Payload {
+    e: Token[]; /* Envelope */
+    a: Token[][]; /* Events that are used for data analysis */
+    p: Token[][]; /* Events that are primarily used for session playback */
+}
+
+export interface EncodedPayload {
+    e: string; /* Envelope */
+    a: string; /* Analytics Payload */
+    p: string; /* Playback Payload */
+}
+
+export interface Metadata {
+    projectId: string;
+    userId: string;
+    sessionId: string;
+    pageNum: number;
+}
+
+export interface Session {
+    session: string;
+    ts: number;
+    count: number;
+    upgrade: BooleanFlag;
+    upload: string;
+}
+
+export interface User {
+    id: string;
+    version: number;
+    expiry: number;
+    consent: BooleanFlag;
+    dob: number;
+}
+
+export interface Envelope extends Metadata {
+    sequence: number;
+    start: number;
+    duration: number;
+    version: string;
+    upload: Upload;
+    end: BooleanFlag;
+    applicationPlatform: number;
+    url: string;
+}
+
+export interface Transit {
+    [key: number]: {
+        data: string;
+        attempts: number;
+    };
+}
+
+export interface BaselineState {
+    time: number;
+    event: number;
+    data: BaselineData;
+}
+
+/* Event Data */
+export interface BaselineData {
+    visible: BooleanFlag;
+    docWidth: number;
+    docHeight: number;
+    screenWidth: number;
+    screenHeight: number;
+    scrollX: number;
+    scrollY: number;
+    pointerX: number;
+    pointerY: number;
+    activityTime: number;
+    scrollTime: number;
+    pointerTime?: number;
+    moveX?: number;
+    moveY?: number;
+    moveTime?: number;
+    downX?: number;
+    downY?: number;
+    downTime?: number;
+    upX?: number;
+    upY?: number;
+    upTime?: number;
+    pointerPrevX?: number;
+    pointerPrevY?: number;
+    pointerPrevTime?: number;
+    modules: number[];
+}
+
+export interface IdentityData {
+    userId: string;
+    userHint: string;
+    sessionId?: string;
+    pageId?: string;
+}
+
+export interface DimensionData {
+    [key: number]: string[];
+}
+
+export interface VariableData {
+    [name: string]: string[];
+}
+
+// Eventually custom event can be expanded to contain more properties
+// For now, restricting to key value pair where both key & value are strings
+// The way it's different from variable is that Custom Event has a notion of time
+// Whereas variables have no timing element and eventually will turn into custom dimensions
+export interface CustomData {
+    key?: string;
+    value: string;
+}
+
+export interface MetricData {
+    [key: number]: number;
+}
+
+export interface PingData {
+    gap: number;
+}
+
+export interface LimitData {
+    check: number;
+}
+
+export interface SummaryData {
+    [event: number]: [number, number][]; // Array of [start, duration] for every event type
+}
+
+export interface UpgradeData {
+    key: string;
+}
+
+export interface ExtractData {
+    [key: number]: { [subkey: number]: string }; // Array of { subkey: number } representing the extracted data
+}
+
+export interface UploadData {
+    sequence: number;
+    attempts: number;
+    status: number;
+}
+
+export interface ClaritySignal {
+    type: string
+    value?: number
+}
+
+export interface PerformanceEventTiming extends PerformanceEntry {
+    duration: DOMHighResTimeStamp;
+    interactionId: number;
+}
+
+export interface Interaction {
+    id: number;
+    latency: number;
+}
+
+export interface ConsentState {
+    source?: ConsentSource;
+    ad_Storage?: string;
+    analytics_Storage?: string;
+}
+
+export const enum ConsentType {
+    None = 0,
+    Implicit = 1,
+    General = 2
+}
+
+export interface ConsentData {
+    source: ConsentSource;
+    ad_Storage: BooleanFlag;
+    analytics_Storage: BooleanFlag;
+}
+
+export interface GCMConsentState {
+    ad_Storage: GCMConsent;
+    analytics_Storage: GCMConsent;
+}
+
+export interface DiscoverTrigger {
+    scrollDepthPercent?: number; // trigger khi scroll đến X% chiều cao trang
+    clickCount?: number;         // trigger sau X lần click
+    activeTimeMs?: number;       // window tối đa để nhận trigger (ms)
+    delayMs?: number;            // delay thêm sau khi điều kiện thỏa trước khi fire
+    maxPlaybackBytes?: number;   // trigger khi buffer đạt X bytes
+}
+
+export interface GemXConfig {
+    debug: boolean;
+    excludeClassNames: string[];
+    ignoreMutationClassNames: string[];
+    discoverTrigger: DiscoverTrigger | null;
+}

package/types/diagnostic.d.ts

@@ -0,0 +1,24 @@
+import { Code, Severity, Target } from "./data";
+
+/* Event Data */
+export interface ScriptErrorData {
+    source: string;
+    message: string;
+    line: number;
+    column: number;
+    stack: string;
+}
+
+export interface LogData {
+    code: Code;
+    name: string;
+    message: string;
+    stack: string;
+    severity: Severity;
+}
+
+export interface FraudData {
+    id: number;
+    target: number;
+    checksum: string;
+}

package/types/global.d.ts

@@ -0,0 +1,43 @@
+declare global {
+  interface Window {
+      clarityOverrides?: { [key: string]: ((...args: any[]) => any) | undefined };
+    GemXHeatmap?: {
+      debug: boolean;
+      excludeClassNames: string[];
+      ignoreMutationClassNames?: string[];
+      discoverTrigger?: {
+        scrollDepthPercent?: number;
+        clickCount?: number;
+        activeTimeMs?: number;
+        maxPlaybackBytes?: number;
+      };
+      __debug?: Array<{ event: number; selector: string[]; hash: string[] }>;
+      __domSnapshot?: string[];
+    };
+    google_tag_data?: {
+      ics: {
+        addListener: (keys: string[], callback: () => void) => void;
+        getConsentState: (key: string) => any;
+        usedUpdate: boolean;
+      };
+    };
+    LiveChatWidget?: {
+      off(eventName: string, callback: (data: any) => void): unknown;
+      on: (eventName: string, callback: (data: any) => void) => void;
+    };
+    tidioChatApi?: {
+      on: (eventName: string, callback: (data: any) => void) => void;
+    };
+    $crisp?: {
+      push: (
+        args: [action: string, eventName: string, callback: (data: any) => void]
+      ) => void;
+    };
+  }
+
+  interface Function {
+    dn?: number;
+  }
+}
+
+export {};

package/types/index.d.ts

@@ -0,0 +1,46 @@
+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";
+
+interface Clarity {
+  start: (config?: Core.Config) => void;
+  stop: () => void;
+  pause: () => void;
+  resume: () => void;
+  upgrade: (key: string) => void;
+  consent: (status?: boolean) => void;
+  consentv2: (consentState?: Data.ConsentState, source?: number) => void;
+  event: (name: string, value: string) => void;
+  set: (variable: string, value: string | string[]) => void;
+  identify: (userId: string, sessionId?: string, pageId?: string, userHint?: string) => void;
+  metadata: (callback: Data.MetadataCallback, wait?: boolean, recall?: boolean, consentInfo?: boolean) => void;
+  signal: (callback: Data.SignalCallback) => void;
+}
+
+interface Selector {
+  get: (input: Layout.SelectorInput, type: Layout.Selector) => string;
+  reset: () => void;
+}
+    
+interface Gemx {
+  set: (config: Partial<Data.GemXConfig>) => void;
+  get: () => Data.GemXConfig;
+}
+
+interface Helper {
+  get: (node: Node) => Layout.NodeValue;
+  getNode: (id: number) => Node;
+  hash: (input: string) => string;
+  lookup: (hash: string) => number;
+  selector: Selector;
+  gemx: Gemx;
+}
+
+declare const clarity: Clarity;
+declare const helper: Helper;
+declare const version: string;
+
+export { clarity, version, helper, Core, Data, Diagnostic, Layout, Interaction, Performance };