@clue-ai/browser-sdk 0.0.1

package/dist/capture/page.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startPageCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/capture/page.js

@@ -0,0 +1,78 @@
+import { getCurrentPageSnapshot } from "./location";
+export const startPageCapture = (context) => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    let pageEnteredAtMs = Date.now();
+    const emitPageView = () => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const snapshot = getCurrentPageSnapshot();
+        context.onEvent({
+            type: "page_view",
+            occurredAtMs: Date.now(),
+            payload: {
+                viewId: context.getViewId(),
+                screenKey: snapshot.screenKey,
+                path: snapshot.path,
+                urlCanonical: snapshot.urlCanonical,
+                pageTitleCandidate: snapshot.pageTitleCandidate,
+                routeNameCandidate: null,
+                primaryHeadingCandidate: snapshot.primaryHeadingCandidate,
+            },
+        });
+    };
+    const handlePageLeave = () => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        const snapshot = getCurrentPageSnapshot();
+        context.onEvent({
+            type: "page_leave",
+            occurredAtMs: Date.now(),
+            payload: {
+                viewId: context.getViewId(),
+                screenKey: snapshot.screenKey,
+                path: snapshot.path,
+                timeOnPageMs: Math.max(0, Date.now() - pageEnteredAtMs),
+            },
+        });
+        pageEnteredAtMs = Date.now();
+    };
+    try {
+        emitPageView();
+    }
+    catch (error) {
+        context.onInternalError("capture/page:initial_page_view", error);
+    }
+    const visibilityHandler = () => {
+        if (document.visibilityState !== "hidden") {
+            return;
+        }
+        try {
+            handlePageLeave();
+        }
+        catch (error) {
+            context.onInternalError("capture/page:visibilitychange", error);
+        }
+    };
+    const pageHideHandler = () => {
+        try {
+            handlePageLeave();
+        }
+        catch (error) {
+            context.onInternalError("capture/page:pagehide", error);
+        }
+    };
+    document.addEventListener("visibilitychange", visibilityHandler, true);
+    window.addEventListener("pagehide", pageHideHandler, true);
+    window.addEventListener("beforeunload", pageHideHandler, true);
+    return {
+        stop: () => {
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+            window.removeEventListener("pagehide", pageHideHandler, true);
+            window.removeEventListener("beforeunload", pageHideHandler, true);
+        },
+    };
+};

package/dist/capture/performance.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureModuleContext, CaptureStopHandle } from "../core/types";
+export declare const startPerformanceCapture: (context: CaptureModuleContext) => CaptureStopHandle;

package/dist/capture/performance.js

@@ -0,0 +1,268 @@
+import { FRONTEND_EVENT_NAME } from "../core/contracts";
+const SUMMARY_WINDOW_MS = 60000;
+const LONG_TASK_THRESHOLD_MS = 250;
+const INTERACTION_LONG_TASK_THRESHOLD_MS = 100;
+const INTERACTION_LONG_TASK_WINDOW_MS = 2000;
+const createInitialState = () => ({
+    windowStartedAtMs: Date.now(),
+    summaryCount: 0,
+    droppedCount: 0,
+    longTaskCount: 0,
+    resourceFailureCount: 0,
+    worstDurationMs: 0,
+    worstMetricName: null,
+    webVitals: {
+        lcp_ms: null,
+        cls: null,
+        fcp_ms: null,
+        ttfb_ms: null,
+        inp_ms: null,
+    },
+    loadDurationMs: null,
+    interactionReadyMs: null,
+    lastInteractionAtMs: null,
+});
+const durationBucket = (value) => {
+    if (value < 100) {
+        return "lt_100ms";
+    }
+    if (value < 250) {
+        return "100_249ms";
+    }
+    if (value < 1000) {
+        return "250_999ms";
+    }
+    if (value < 2500) {
+        return "1000_2499ms";
+    }
+    return "gte_2500ms";
+};
+const countBucket = (value) => {
+    if (value <= 0) {
+        return "0";
+    }
+    if (value === 1) {
+        return "1";
+    }
+    if (value <= 3) {
+        return "2_3";
+    }
+    if (value <= 10) {
+        return "4_10";
+    }
+    return "gt_10";
+};
+const optionalDurationBucket = (value) => value === null ? null : durationBucket(value);
+const ratingForSummary = (state) => {
+    const lcp = state.webVitals.lcp_ms;
+    const cls = state.webVitals.cls;
+    const inp = state.webVitals.inp_ms;
+    if ((lcp !== null && lcp > 4000) ||
+        (cls !== null && cls > 0.25) ||
+        (inp !== null && inp > 500) ||
+        state.worstDurationMs >= 2500) {
+        return "poor";
+    }
+    if ((lcp !== null && lcp > 2500) ||
+        (cls !== null && cls > 0.1) ||
+        (inp !== null && inp > 200) ||
+        state.worstDurationMs >= 1000) {
+        return "needs_improvement";
+    }
+    return "good";
+};
+const updateWorstDuration = (state, metricName, valueMs) => {
+    if (!Number.isFinite(valueMs) || valueMs < state.worstDurationMs) {
+        return;
+    }
+    state.worstDurationMs = Math.round(valueMs);
+    state.worstMetricName = metricName;
+};
+const observeEntryType = (observers, entryType, callback) => {
+    if (typeof PerformanceObserver === "undefined" ||
+        !PerformanceObserver.supportedEntryTypes?.includes(entryType)) {
+        return;
+    }
+    try {
+        const observer = new PerformanceObserver(callback);
+        observer.observe({ type: entryType, buffered: true });
+        observers.push(observer);
+    }
+    catch {
+        // Some browsers expose an entry type but still reject buffered observation.
+    }
+};
+export const startPerformanceCapture = (context) => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return { stop: () => undefined };
+    }
+    let state = createInitialState();
+    const observers = [];
+    const emitSummary = (flushReason) => {
+        if (context.getConsent() === "denied") {
+            state = createInitialState();
+            return;
+        }
+        const summaryCount = state.summaryCount;
+        if (summaryCount === 0 && state.droppedCount === 0) {
+            return;
+        }
+        const viewId = context.getViewId();
+        const summaryWindowMs = Math.max(0, Date.now() - state.windowStartedAtMs);
+        context.onEvent({
+            type: FRONTEND_EVENT_NAME.performanceSummaryObserved,
+            occurredAtMs: Date.now(),
+            payload: {
+                viewId,
+                pageUrl: window.location.href,
+                collectorName: "performance_rum",
+                aggregationKind: "per_view_window",
+                summaryWindowMs,
+                summaryCount,
+                droppedCount: state.droppedCount,
+                sampleRate: 1,
+                budgetWindowMs: SUMMARY_WINDOW_MS,
+                rateLimitKey: viewId
+                    ? `view:${viewId}:performance`
+                    : "view:unknown:performance",
+                performanceKind: "view",
+                rating: ratingForSummary(state),
+                metricName: state.worstMetricName ?? "performance_summary",
+                metricValueBucket: durationBucket(state.worstDurationMs),
+                loadDurationBucket: optionalDurationBucket(state.loadDurationMs),
+                interactionReadyMsBucket: optionalDurationBucket(state.interactionReadyMs),
+                longTaskCountBucket: countBucket(state.longTaskCount),
+                resourceFailureCountBucket: countBucket(state.resourceFailureCount),
+                longTaskCount: state.longTaskCount,
+                resourceFailureCount: state.resourceFailureCount,
+                slowResourceCount: 0,
+                worstDurationBucket: durationBucket(state.worstDurationMs),
+                flushReason,
+                webVitalBuckets: {
+                    lcp: optionalDurationBucket(state.webVitals.lcp_ms),
+                    fcp: optionalDurationBucket(state.webVitals.fcp_ms),
+                    ttfb: optionalDurationBucket(state.webVitals.ttfb_ms),
+                    inp: optionalDurationBucket(state.webVitals.inp_ms),
+                    cls: state.webVitals.cls === null
+                        ? null
+                        : state.webVitals.cls > 0.25
+                            ? "poor"
+                            : state.webVitals.cls > 0.1
+                                ? "needs_improvement"
+                                : "good",
+                },
+            },
+        });
+        state = createInitialState();
+    };
+    const intervalId = window.setInterval(() => {
+        emitSummary("interval");
+    }, SUMMARY_WINDOW_MS);
+    const pageHideHandler = () => {
+        emitSummary("pagehide");
+    };
+    const visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+            emitSummary("visibility_hidden");
+        }
+    };
+    const resourceErrorHandler = (event) => {
+        if (context.getConsent() === "denied") {
+            return;
+        }
+        if (!(event.target instanceof Element)) {
+            return;
+        }
+        state.resourceFailureCount += 1;
+        state.summaryCount += 1;
+    };
+    const interactionHandler = () => {
+        state.lastInteractionAtMs = Date.now();
+    };
+    window.addEventListener("error", resourceErrorHandler, true);
+    window.addEventListener("pointerdown", interactionHandler, true);
+    window.addEventListener("pagehide", pageHideHandler, true);
+    document.addEventListener("visibilitychange", visibilityHandler, true);
+    observeEntryType(observers, "navigation", (list) => {
+        for (const entry of list.getEntries()) {
+            const navigation = entry;
+            state.summaryCount += 1;
+            state.loadDurationMs = Math.max(0, Math.round(navigation.duration));
+            updateWorstDuration(state, "page_load", navigation.duration);
+            const ttfb = Math.max(0, navigation.responseStart - navigation.requestStart);
+            state.webVitals.ttfb_ms = Math.round(ttfb);
+            updateWorstDuration(state, "ttfb", ttfb);
+        }
+    });
+    observeEntryType(observers, "paint", (list) => {
+        for (const entry of list.getEntries()) {
+            if (entry.name !== "first-contentful-paint") {
+                continue;
+            }
+            state.summaryCount += 1;
+            state.webVitals.fcp_ms = Math.round(entry.startTime);
+            updateWorstDuration(state, "fcp", entry.startTime);
+        }
+    });
+    observeEntryType(observers, "largest-contentful-paint", (list) => {
+        for (const entry of list.getEntries()) {
+            const lcp = entry;
+            const value = lcp.renderTime || lcp.loadTime || lcp.startTime;
+            state.summaryCount += 1;
+            state.webVitals.lcp_ms = Math.round(value);
+            updateWorstDuration(state, "lcp", value);
+        }
+    });
+    observeEntryType(observers, "layout-shift", (list) => {
+        for (const entry of list.getEntries()) {
+            const shift = entry;
+            if (shift.hadRecentInput === true || typeof shift.value !== "number") {
+                continue;
+            }
+            state.summaryCount += 1;
+            state.webVitals.cls = Number(((state.webVitals.cls ?? 0) + shift.value).toFixed(4));
+        }
+    });
+    observeEntryType(observers, "event", (list) => {
+        for (const entry of list.getEntries()) {
+            const eventTiming = entry;
+            if (eventTiming.interactionId === undefined) {
+                continue;
+            }
+            state.summaryCount += 1;
+            const value = Math.max(0, eventTiming.duration);
+            state.webVitals.inp_ms = Math.max(state.webVitals.inp_ms ?? 0, Math.round(value));
+            state.interactionReadyMs = Math.max(state.interactionReadyMs ?? 0, Math.round(value));
+            updateWorstDuration(state, "inp", value);
+        }
+    });
+    observeEntryType(observers, "longtask", (list) => {
+        for (const entry of list.getEntries()) {
+            const nearInteraction = state.lastInteractionAtMs !== null &&
+                Date.now() - state.lastInteractionAtMs <=
+                    INTERACTION_LONG_TASK_WINDOW_MS;
+            const threshold = nearInteraction
+                ? INTERACTION_LONG_TASK_THRESHOLD_MS
+                : LONG_TASK_THRESHOLD_MS;
+            if (entry.duration < threshold) {
+                continue;
+            }
+            state.longTaskCount += 1;
+            state.summaryCount += 1;
+            updateWorstDuration(state, "long_task", entry.duration);
+        }
+    });
+    return {
+        stop: () => {
+            emitSummary("stop");
+            window.clearInterval(intervalId);
+            window.removeEventListener("error", resourceErrorHandler, true);
+            window.removeEventListener("pointerdown", interactionHandler, true);
+            window.removeEventListener("pagehide", pageHideHandler, true);
+            document.removeEventListener("visibilitychange", visibilityHandler, true);
+            for (const observer of observers) {
+                observer.disconnect();
+            }
+        },
+    };
+};

package/dist/context/account.d.ts

@@ -0,0 +1,12 @@
+import type { AccountContext } from "../core/types";
+type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export declare class AccountManager {
+    private readonly storage;
+    private state;
+    constructor(storage?: StorageLike);
+    getContext(): AccountContext;
+    setAccount(accountId: string, traits?: Record<string, unknown>): void;
+    reset(): void;
+    private loadState;
+}
+export {};

package/dist/context/account.js

@@ -0,0 +1,129 @@
+import { STORAGE_KEYS } from "../core/constants";
+const createMemoryStorage = () => {
+    const store = new Map();
+    return {
+        getItem: (key) => (store.has(key) ? store.get(key) : null),
+        setItem: (key, value) => {
+            store.set(key, value);
+        },
+        removeItem: (key) => {
+            store.delete(key);
+        },
+    };
+};
+const resolveStorage = () => {
+    try {
+        if (typeof globalThis.localStorage !== "undefined") {
+            const probeKey = "clue:account_probe";
+            globalThis.localStorage.setItem(probeKey, "1");
+            globalThis.localStorage.removeItem(probeKey);
+            return globalThis.localStorage;
+        }
+    }
+    catch {
+        // Ignore and fallback.
+    }
+    return createMemoryStorage();
+};
+const safeJsonParse = (value) => {
+    if (!value) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore and fallback.
+    }
+    return {};
+};
+const detectWorkspaceId = (traits) => {
+    const workspaceId = traits.workspace_id ?? traits.workspaceId;
+    if (typeof workspaceId === "string" && workspaceId.trim()) {
+        return workspaceId;
+    }
+    return null;
+};
+const detectOrganizationId = (traits) => {
+    const organizationId = traits.organization_id ?? traits.organizationId;
+    if (typeof organizationId === "string" && organizationId.trim()) {
+        return organizationId;
+    }
+    return null;
+};
+export class AccountManager {
+    constructor(storage) {
+        this.storage = storage ?? resolveStorage();
+        this.state = this.loadState();
+    }
+    getContext() {
+        return {
+            accountId: this.state.accountId,
+            organizationId: this.state.organizationId,
+            workspaceId: this.state.workspaceId,
+            traits: { ...this.state.traits },
+        };
+    }
+    setAccount(accountId, traits) {
+        const previousTraits = this.state.accountId === accountId ? this.state.traits : {};
+        this.state.accountId = accountId;
+        this.state.traits = {
+            ...previousTraits,
+            ...(traits ?? {}),
+        };
+        this.state.organizationId = detectOrganizationId(this.state.traits);
+        this.state.workspaceId = detectWorkspaceId(this.state.traits);
+        try {
+            this.storage.setItem(STORAGE_KEYS.accountId, accountId);
+            this.storage.setItem(STORAGE_KEYS.accountTraits, JSON.stringify(this.state.traits));
+            if (this.state.organizationId) {
+                this.storage.setItem(STORAGE_KEYS.organizationId, this.state.organizationId);
+            }
+            else {
+                this.storage.removeItem(STORAGE_KEYS.organizationId);
+            }
+            if (this.state.workspaceId) {
+                this.storage.setItem(STORAGE_KEYS.workspaceId, this.state.workspaceId);
+            }
+            else {
+                this.storage.removeItem(STORAGE_KEYS.workspaceId);
+            }
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    reset() {
+        this.state = {
+            accountId: null,
+            organizationId: null,
+            workspaceId: null,
+            traits: {},
+        };
+        try {
+            this.storage.removeItem(STORAGE_KEYS.accountId);
+            this.storage.removeItem(STORAGE_KEYS.organizationId);
+            this.storage.removeItem(STORAGE_KEYS.workspaceId);
+            this.storage.removeItem(STORAGE_KEYS.accountTraits);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    loadState() {
+        const accountId = this.storage.getItem(STORAGE_KEYS.accountId);
+        const traits = safeJsonParse(this.storage.getItem(STORAGE_KEYS.accountTraits));
+        const organizationId = this.storage.getItem(STORAGE_KEYS.organizationId) ??
+            detectOrganizationId(traits);
+        const workspaceId = this.storage.getItem(STORAGE_KEYS.workspaceId) ?? detectWorkspaceId(traits);
+        return {
+            accountId,
+            organizationId,
+            workspaceId,
+            traits,
+        };
+    }
+}

package/dist/context/environment.d.ts

@@ -0,0 +1,42 @@
+import type { ClueEnvironment } from "../core/types";
+type EnvironmentOptions = {
+    environment: ClueEnvironment;
+    frontendRelease: string | null;
+    featureFlagsProvider?: () => string[];
+    experimentVariantProvider?: () => string | null;
+};
+export type EnvironmentContextValue = {
+    environment: ClueEnvironment;
+    frontendRelease: string | null;
+    featureFlags: string[];
+    experimentVariant: string | null;
+    locale: string | null;
+    country: string | null;
+    deviceType: string | null;
+    browser: string | null;
+    os: string | null;
+    referrer: string | null;
+    browserFamily: string | null;
+    browserMajorVersion: string | null;
+    browserEngine: string | null;
+    osFamily: string | null;
+    osMajorVersion: string | null;
+    timezone: string | null;
+    pointerTypeCandidate: string | null;
+    touchCapable: boolean | null;
+    cookiesEnabled: boolean | null;
+    localStorageAvailable: boolean | null;
+    sessionStorageAvailable: boolean | null;
+    serviceWorkerSupported: boolean | null;
+    webglSupported: boolean | null;
+    reducedMotion: string | null;
+    colorScheme: string | null;
+};
+export declare class EnvironmentManager {
+    private readonly options;
+    constructor(options: EnvironmentOptions);
+    getContext(): EnvironmentContextValue;
+    private safeFeatureFlags;
+    private safeExperimentVariant;
+}
+export {};