@affogatosoftware/recorder 1.0.1

package/dist/recorder/eventRecorder.js

@@ -0,0 +1,399 @@
+import { logger } from "../logger";
+import { post } from "../requests";
+import { MaskingLevel } from "./recorder";
+import { assertNever } from "../utils";
+export class EventRecorder {
+    window;
+    recorderSettings;
+    eventsBuffer = [];
+    isRunning = false;
+    tagsToCapture = new Set(["button", "a", "select", "textarea", "input"]);
+    queryParamsAllowed = new Set([
+        "utm_source",
+        "source",
+        "ref",
+        "utm_medium",
+        "medium",
+        "utm_campaign",
+        "campaign",
+        "utm_content",
+        "content",
+        "utm_term",
+        "term"
+    ]);
+    // private piiAttribute = "data-pii";
+    flushIntervalMs = 2000;
+    capturedSessionId;
+    flushTimerId = null;
+    constructor(window, recorderSettings) {
+        this.window = window;
+        this.recorderSettings = recorderSettings;
+    }
+    start = () => {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        this.eventsBuffer = [];
+        const originalPushState = this.window.history.pushState.bind(this.window.history);
+        this.window.history.pushState = (data, unused, url) => {
+            let urlString = "";
+            if (url instanceof URL) {
+                urlString = url.toString();
+            }
+            else if (url) {
+                urlString = url;
+            }
+            else {
+                urlString = "";
+            }
+            this.handlePageView(urlString);
+            return originalPushState(data, unused, url);
+        };
+        this.window.addEventListener("pageshow", (e) => {
+            try {
+                this.handlePageView(this.window.location.pathname);
+            }
+            catch (error) {
+                logger.error("Failed to capture URL change event", error);
+            }
+        });
+        this.window.addEventListener("change", this.handler);
+        this.window.addEventListener("click", this.handler);
+        this.window.addEventListener("keydown", this.handler);
+        this.scheduleFlush();
+    };
+    scheduleFlush = () => {
+        if (this.flushTimerId) {
+            clearTimeout(this.flushTimerId);
+        }
+        this.flushTimerId = setTimeout(this.flush, this.flushIntervalMs);
+    };
+    flush = async () => {
+        if (this.eventsBuffer.length > 0 && this.capturedSessionId) {
+            try {
+                const response = await post(`/public/captured-sessions/${this.capturedSessionId}/ui-events`, this.eventsBuffer, { withCredentials: false });
+                if (response.status !== 201) {
+                    logger.error("Failed to save ui events", response.data);
+                }
+                this.eventsBuffer = [];
+            }
+            catch (error) {
+                logger.error("Failed to save ui events", error);
+                this.eventsBuffer = [];
+            }
+        }
+        this.scheduleFlush();
+    };
+    handlePageView = (path) => {
+        if (!this.isRunning) {
+            return;
+        }
+        try {
+            const timestamp = Date.now();
+            const isPathAbsolute = path.charAt(0) === "/";
+            if (!isPathAbsolute) {
+                path = this.window.location.pathname + "/" + path;
+            }
+            const url = new URL(this.window.location.protocol + "//" + this.window.location.host + path + this.window.location.search);
+            const sanitizedUrlString = this.sanitizeUrlParams(url.toString(), this.queryParamsAllowed);
+            const sanitizedUrl = new URL(sanitizedUrlString);
+            const searchParamsArray = Array.from(sanitizedUrl.searchParams);
+            const interactionEvent = {
+                eventType: "page_view",
+                timestamp,
+                text: path,
+                host: sanitizedUrl.hostname,
+                path,
+            };
+            if (searchParamsArray.length > 0) {
+                interactionEvent.queryParams = searchParamsArray;
+            }
+            this.eventsBuffer.push(interactionEvent);
+        }
+        catch (error) {
+            logger.error("Failed to capture URL change event", error);
+        }
+    };
+    sanitizeUrlParams = (url, paramsAllowed) => {
+        try {
+            const urlObj = new URL(url);
+            for (const key of urlObj.searchParams.keys()) {
+                if (!paramsAllowed.has(key.toLowerCase())) {
+                    urlObj.searchParams.set(key, "$redacted");
+                }
+            }
+            return urlObj.toString();
+        }
+        catch (e) {
+            logger.error("Failed to sanitize URL params", e);
+            return url;
+        }
+    };
+    handler = (e) => {
+        if (!this.isRunning) {
+            return;
+        }
+        try {
+            const eventType = e.type;
+            const target = e.target;
+            const tagName = target?.tagName.toLowerCase();
+            if (!(tagName && this.tagsToCapture.has(tagName))) {
+                return;
+            }
+            const url = new URL(this.window.location.href);
+            const host = url.hostname;
+            const path = url.pathname;
+            const timestamp = Date.now();
+            const domContext = this.captureDomContext(target);
+            switch (e.type) {
+                case "click":
+                    const clickEvent = this.handleClick(target, tagName, timestamp, host, path);
+                    this.eventsBuffer.push(clickEvent);
+                    break;
+                case "keydown":
+                    const keyEvent = this.handleKeyDown(e, tagName, target, timestamp, host, path);
+                    this.eventsBuffer.push(keyEvent);
+                    break;
+                case "change":
+                    const changeEvent = this.handleChange(target, tagName, timestamp, host, path);
+                    this.eventsBuffer.push(changeEvent);
+                    break;
+                default:
+                    this.eventsBuffer.push({
+                        eventType,
+                        tagName,
+                        timestamp,
+                        host,
+                        path,
+                        text: null,
+                        domContext
+                    });
+            }
+        }
+        catch (error) {
+            logger.error("Failed to capture event", error);
+        }
+    };
+    handleChange(target, tagName, timestamp, host, path) {
+        let text = null;
+        if (target instanceof HTMLSelectElement) {
+            text = target.options[target.selectedIndex].text;
+        }
+        switch (this.recorderSettings.maskingLevel) {
+            case MaskingLevel.None:
+                break;
+            case MaskingLevel.All:
+                text = null;
+                break;
+            case null:
+            case MaskingLevel.InputAndTextArea:
+                break;
+            case MaskingLevel.InputPasswordOrEmailAndTextArea:
+                break;
+            default:
+                assertNever(this.recorderSettings.maskingLevel);
+        }
+        return {
+            eventType: "change",
+            tagName,
+            timestamp,
+            text: text === "" ? null : text,
+            host,
+            path,
+            domContext: this.captureDomContext(target)
+        };
+    }
+    handleClick(target, tagName, timestamp, host, path) {
+        let text = "";
+        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+            const labelText = this.findInputOrSelectOrTextAreaLabel(target);
+            if (labelText) {
+                text = labelText;
+            }
+            else if (target.placeholder) {
+                text = target.placeholder;
+            }
+        }
+        else if (target instanceof HTMLSelectElement) {
+            const labelText = this.findInputOrSelectOrTextAreaLabel(target);
+            if (labelText) {
+                text = labelText;
+            }
+            else {
+                text = target.value + " (" + target.options[target.selectedIndex].text + ")";
+            }
+        }
+        else if (target instanceof HTMLButtonElement) {
+            text = target.innerText;
+        }
+        else if (target instanceof HTMLAnchorElement) {
+            text = target.href;
+        }
+        else if (target instanceof HTMLImageElement) {
+            text = target.src;
+        }
+        switch (this.recorderSettings.maskingLevel) {
+            case MaskingLevel.None:
+                break;
+            case MaskingLevel.All:
+                text = null;
+                break;
+            case null:
+            case MaskingLevel.InputAndTextArea:
+                if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+                    text = null;
+                }
+                break;
+            case MaskingLevel.InputPasswordOrEmailAndTextArea:
+                if (target instanceof HTMLTextAreaElement) {
+                    text = null;
+                }
+                else if (target instanceof HTMLInputElement) {
+                    if (target.type === "password" || target.type === "email" || target.type === "e-mail") {
+                        text = null;
+                    }
+                }
+                break;
+            default:
+                assertNever(this.recorderSettings.maskingLevel);
+        }
+        return {
+            eventType: "click",
+            tagName,
+            timestamp,
+            text: text === "" ? null : text,
+            host,
+            path,
+            domContext: this.captureDomContext(target)
+        };
+    }
+    handleKeyDown(e, tagName, target, timestamp, host, path) {
+        const kbe = e;
+        const key = kbe.key;
+        let text = null;
+        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+            const labelText = this.findInputOrSelectOrTextAreaLabel(target);
+            if (labelText) {
+                text = labelText;
+            }
+            else if (target.placeholder) {
+                text = target.placeholder;
+            }
+        }
+        switch (this.recorderSettings.maskingLevel) {
+            case MaskingLevel.None:
+                break;
+            case MaskingLevel.All:
+                text = null;
+                break;
+            case null:
+            case MaskingLevel.InputAndTextArea:
+                if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+                    text = null;
+                }
+                break;
+            case MaskingLevel.InputPasswordOrEmailAndTextArea:
+                if (target instanceof HTMLTextAreaElement) {
+                    text = null;
+                }
+                else if (target instanceof HTMLInputElement) {
+                    if (target.type === "password" || target.type === "email" || target.type === "e-mail") {
+                        text = null;
+                    }
+                }
+                break;
+            default:
+                assertNever(this.recorderSettings.maskingLevel);
+        }
+        return {
+            eventType: "keydown",
+            tagName,
+            timestamp,
+            text,
+            key,
+            host,
+            path,
+            domContext: this.captureDomContext(target)
+        };
+    }
+    findInputOrSelectOrTextAreaLabel = (el) => {
+        const allowedTags = new Set(["input", "select", "textarea"]);
+        if (!el || !allowedTags.has(el.tagName.toLowerCase()))
+            return null;
+        /* 1. <label><input|select …></label> (label wraps the control) */
+        const wrappingLabel = el.closest("label");
+        if (wrappingLabel) {
+            // Take only the TEXT_NODEs that are direct children of <label>
+            const text = Array.from(wrappingLabel.childNodes)
+                .filter(node => node.nodeName.toLowerCase() !== "select")
+                .map(node => (node.textContent ?? "").trim())
+                .filter(Boolean) // remove empty strings
+                .join(" ")
+                .trim();
+            if (text)
+                return text;
+        }
+        /* 2. <label for="id">…</label>  +  <input|select id="id" …> */
+        const id = el.id;
+        if (id) {
+            const explicitLabel = el.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`);
+            if (explicitLabel) {
+                const text = Array.from(explicitLabel.childNodes)
+                    .filter(node => node.nodeName.toLowerCase() !== "select")
+                    .map(node => (node.textContent ?? "").trim())
+                    .filter(Boolean)
+                    .join(" ")
+                    .trim();
+                if (text)
+                    return text;
+            }
+        }
+        /* 3. Accessibility fall-backs */
+        const ariaLabel = el.getAttribute("aria-label");
+        if (ariaLabel)
+            return ariaLabel.trim();
+        const ariaLabelledBy = el.getAttribute("aria-labelledby");
+        if (ariaLabelledBy) {
+            const ref = el.ownerDocument.getElementById(ariaLabelledBy);
+            return ref?.textContent?.trim() || null;
+        }
+        return null;
+    };
+    stop = () => {
+        this.isRunning = false;
+        this.window.removeEventListener("change", this.handler);
+        this.window.removeEventListener("click", this.handler);
+        this.window.removeEventListener("keydown", this.handler);
+        if (this.flushTimerId) {
+            clearTimeout(this.flushTimerId);
+            this.flushTimerId = null;
+        }
+    };
+    captureDomContext = (targetElement) => {
+        const context = [];
+        context.push(this.toJsonNode(targetElement));
+        let current = targetElement.parentElement;
+        while (current != null && context.length < 6) {
+            context.push(this.toJsonNode(current));
+            current = current.parentElement;
+        }
+        return context;
+    };
+    toJsonNode = (node) => {
+        const attrs = {};
+        // Collect safe attributes only
+        ["id", "class", "name", "type", "role", "aria-label"].forEach((key) => {
+            const val = node.getAttribute(key);
+            if (val)
+                attrs[key] = val;
+        });
+        return {
+            tag: node.tagName.toLowerCase(),
+            attrs
+        };
+    };
+    setCapturedSessionId(uuid) {
+        this.capturedSessionId = uuid;
+    }
+}

package/dist/recorder/recorder.d.ts

@@ -0,0 +1,49 @@
+export declare class Recorder {
+    private window;
+    private publicToken;
+    private recorderSettings;
+    private sessionRecorder;
+    private eventRecorder;
+    private capturedSessionId;
+    private pingIntervalMs;
+    private pingTimeout;
+    constructor(window: Window, publicToken: string, recorderSettings: RecorderSettings);
+    private schedulePing;
+    private ping;
+    /**
+     * Start both recorders
+     */
+    start(): void;
+    /**
+     * Stop both recorders
+     */
+    stop(): void;
+    private collectCapturedUserMetadata;
+}
+export interface RecorderSettings {
+    maskingLevel: MaskingLevel | null;
+}
+export declare enum MaskingLevel {
+    None = "none",
+    All = "all",
+    InputAndTextArea = "input-and-textarea",
+    InputPasswordOrEmailAndTextArea = "input-password-or-email-and-textarea"
+}
+export interface CapturedUserMetadata {
+    browserName?: string;
+    browserVersion?: string;
+    osName?: string;
+    osVersion?: string;
+    deviceType?: string;
+    browserLanguage?: string;
+    browserTimeZone?: string;
+    referringUrl?: string;
+    referringDomain?: string;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmContent?: string;
+    utmTerm?: string;
+}

package/dist/recorder/recorder.js

@@ -0,0 +1,112 @@
+import { SessionRecorder } from "./sessionRecorder";
+import { EventRecorder } from "./eventRecorder";
+import { post, put } from "../requests";
+import { UAParser } from "ua-parser-js";
+export class Recorder {
+    window;
+    publicToken;
+    recorderSettings;
+    sessionRecorder;
+    eventRecorder;
+    capturedSessionId = null;
+    pingIntervalMs = 20000;
+    pingTimeout = null;
+    constructor(window, publicToken, recorderSettings) {
+        this.window = window;
+        this.publicToken = publicToken;
+        this.recorderSettings = recorderSettings;
+        if (recorderSettings.maskingLevel == null) {
+            recorderSettings.maskingLevel = MaskingLevel.InputAndTextArea;
+        }
+        this.sessionRecorder = new SessionRecorder(recorderSettings);
+        this.eventRecorder = new EventRecorder(window, recorderSettings);
+        post(`public/captured-sessions`, { publicToken }, { withCredentials: false })
+            .then(response => {
+            const id = response.data;
+            this.capturedSessionId = id;
+            this.sessionRecorder.setCapturedSessionId(id);
+            this.eventRecorder.setCapturedSessionId(id);
+            this.schedulePing();
+            const capturedUserMetadata = this.collectCapturedUserMetadata();
+            post(`public/captured-sessions/${this.capturedSessionId}/captured-session/metadata`, capturedUserMetadata, { withCredentials: false });
+        })
+            .catch(error => {
+            console.error(error);
+            this.sessionRecorder.stop();
+            this.eventRecorder.stop();
+        });
+    }
+    schedulePing() {
+        if (this.pingTimeout) {
+            clearTimeout(this.pingTimeout);
+        }
+        this.pingTimeout = setTimeout(this.ping, this.pingIntervalMs);
+    }
+    ping = async () => {
+        await put(`public/captured-sessions/${this.capturedSessionId}/ping`, {}, { withCredentials: false });
+        this.schedulePing();
+    };
+    /**
+     * Start both recorders
+     */
+    start() {
+        this.sessionRecorder.start();
+        this.eventRecorder.start();
+    }
+    /**
+     * Stop both recorders
+     */
+    stop() {
+        this.sessionRecorder.stop();
+        this.eventRecorder.stop();
+    }
+    collectCapturedUserMetadata = () => {
+        const ua = new UAParser();
+        const browserName = ua.getBrowser().name;
+        const browserVersion = ua.getBrowser().version;
+        const osName = ua.getOS().name;
+        const osVersion = ua.getOS().version;
+        const deviceType = (ua.getDevice().type ?? "desktop"); // undefined ⇒ desktop
+        const browserLanguage = navigator.language;
+        const browserTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const referringUrl = document.referrer || undefined;
+        let referringDomain;
+        try {
+            referringDomain = referringUrl ? new URL(referringUrl).hostname : undefined;
+        }
+        catch { /* ignore malformed referrer */ }
+        const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+        const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+        const url = new URL(window.location.href);
+        const utmSource = url.searchParams.get("utm_source") || url.searchParams.get("source") || url.searchParams.get("ref") || undefined;
+        const utmMedium = url.searchParams.get("utm_medium") || url.searchParams.get("medium") || undefined;
+        const utmCampaign = url.searchParams.get("utm_campaign") || url.searchParams.get("campaign") || undefined;
+        const utmContent = url.searchParams.get("utm_content") || url.searchParams.get("content") || undefined;
+        const utmTerm = url.searchParams.get("utm_term") || url.searchParams.get("term") || undefined;
+        return {
+            browserName,
+            browserVersion,
+            osName,
+            osVersion,
+            deviceType,
+            browserLanguage,
+            browserTimeZone,
+            referringUrl,
+            referringDomain,
+            viewportWidth,
+            viewportHeight,
+            utmSource,
+            utmMedium,
+            utmCampaign,
+            utmContent,
+            utmTerm
+        };
+    };
+}
+export var MaskingLevel;
+(function (MaskingLevel) {
+    MaskingLevel["None"] = "none";
+    MaskingLevel["All"] = "all";
+    MaskingLevel["InputAndTextArea"] = "input-and-textarea";
+    MaskingLevel["InputPasswordOrEmailAndTextArea"] = "input-password-or-email-and-textarea";
+})(MaskingLevel || (MaskingLevel = {}));

package/dist/recorder/sessionRecorder.d.ts

@@ -0,0 +1,19 @@
+import { type RecorderSettings } from "./recorder";
+export interface SessionBuffer {
+    data: any[];
+}
+export declare class SessionRecorder {
+    private recorderSettings;
+    private capturedSessionId;
+    private buffer;
+    private stopFn;
+    private readonly flushIntervalMs;
+    private flushTimer;
+    constructor(recorderSettings: RecorderSettings);
+    setCapturedSessionId(id: string): void;
+    start: () => void;
+    private scheduleFlush;
+    private flush;
+    stop: () => void;
+    private clearAllBufferData;
+}

package/dist/recorder/sessionRecorder.js

@@ -0,0 +1,104 @@
+import { record } from "rrweb";
+import { patch } from "../requests";
+import { logger } from "../logger";
+import { MaskingLevel } from "./recorder";
+import { assertNever } from "../utils";
+export class SessionRecorder {
+    recorderSettings;
+    capturedSessionId = null;
+    buffer;
+    stopFn;
+    flushIntervalMs;
+    flushTimer;
+    constructor(recorderSettings) {
+        this.recorderSettings = recorderSettings;
+        this.buffer = {
+            data: []
+        };
+        this.flushIntervalMs = 2000; // 2 * 1000
+    }
+    setCapturedSessionId(id) {
+        this.capturedSessionId = id;
+    }
+    start = () => {
+        if (Object.assign === undefined) {
+            return;
+        }
+        this.buffer = {
+            data: []
+        };
+        const recordOptions = {
+            emit: (event) => {
+                this.buffer.data.push(event);
+            },
+            blockClass: "scry-block"
+        };
+        switch (this.recorderSettings.maskingLevel) {
+            case MaskingLevel.None:
+                break;
+            case MaskingLevel.All:
+                recordOptions.maskTextFn = (input) => input.replaceAll(/./g, "*");
+                break;
+            case null:
+            case MaskingLevel.InputAndTextArea:
+                recordOptions.maskAllInputs = true;
+                break;
+            case MaskingLevel.InputPasswordOrEmailAndTextArea:
+                recordOptions.maskInputOptions = {
+                    password: true,
+                    email: true,
+                    textarea: true
+                };
+                break;
+            default:
+                assertNever(this.recorderSettings.maskingLevel);
+        }
+        this.stopFn = record(recordOptions);
+        this.scheduleFlush();
+    };
+    // separate method for scheduling flush
+    scheduleFlush = () => {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+        }
+        this.flushTimer = setTimeout(this.flush, this.flushIntervalMs);
+    };
+    // preserve data on flush failure
+    flush = async () => {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (this.capturedSessionId && this.buffer.data.length > 0) {
+            try {
+                let response = await patch(`public/captured-sessions/${this.capturedSessionId}/recording`, this.buffer, { withCredentials: false });
+                if (response.status >= 400) {
+                    logger.error(`status ${response.status} when trying to save session recording data.`);
+                    logger.error(response.data);
+                }
+                else {
+                    // clear buffer only if response was successful
+                    this.clearAllBufferData();
+                }
+            }
+            catch (error) {
+                logger.error("Error flushing session data:", error);
+                // TODO add a failure count that will eventually stop, so we don't store a ton of data and hog client memory.
+                // do not clear the buffer, so we retry next time
+            }
+        }
+        this.scheduleFlush();
+    };
+    stop = () => {
+        if (this.stopFn) {
+            this.stopFn();
+        }
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+    };
+    clearAllBufferData = () => {
+        this.buffer.data = [];
+    };
+}

package/dist/requests.d.ts

@@ -0,0 +1,7 @@
+import { type AxiosRequestConfig } from "axios";
+export declare const get: <T = unknown>(url: string, config?: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<T, any>>;
+export declare const post: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<T, any>>;
+export declare const del: <T = unknown>(url: string, config?: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<T, any>>;
+export declare const put: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<T, any>>;
+export declare const patch: <T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<T, any>>;
+export declare const postForm: <T = unknown>(url: string, data: unknown, config?: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<T, any>>;