@clue-ai/browser-sdk 0.0.1

package/dist/context/environment.js

@@ -0,0 +1,208 @@
+const firstMatch = (userAgent, pattern) => {
+    const match = pattern.exec(userAgent);
+    return match?.[1] ?? null;
+};
+const detectBrowserInfo = (userAgent) => {
+    if (/Edg\//.test(userAgent)) {
+        return {
+            family: "edge",
+            majorVersion: firstMatch(userAgent, /Edg\/(\d+)/),
+            engine: "blink",
+        };
+    }
+    if (/Chrome\//.test(userAgent)) {
+        return {
+            family: "chrome",
+            majorVersion: firstMatch(userAgent, /Chrome\/(\d+)/),
+            engine: "blink",
+        };
+    }
+    if (/Safari\//.test(userAgent) && /Version\//.test(userAgent)) {
+        return {
+            family: "safari",
+            majorVersion: firstMatch(userAgent, /Version\/(\d+)/),
+            engine: "webkit",
+        };
+    }
+    if (/Firefox\//.test(userAgent)) {
+        return {
+            family: "firefox",
+            majorVersion: firstMatch(userAgent, /Firefox\/(\d+)/),
+            engine: "gecko",
+        };
+    }
+    return {
+        family: null,
+        majorVersion: null,
+        engine: null,
+    };
+};
+const detectOsInfo = (userAgent) => {
+    if (/Windows/.test(userAgent)) {
+        return {
+            family: "windows",
+            majorVersion: firstMatch(userAgent, /Windows NT (\d+)/),
+        };
+    }
+    if (/Mac OS X/.test(userAgent)) {
+        return {
+            family: "macos",
+            majorVersion: firstMatch(userAgent, /Mac OS X (\d+)[_.]/),
+        };
+    }
+    if (/Android/.test(userAgent)) {
+        return {
+            family: "android",
+            majorVersion: firstMatch(userAgent, /Android (\d+)/),
+        };
+    }
+    if (/(iPhone|iPad|iPod)/.test(userAgent)) {
+        return {
+            family: "ios",
+            majorVersion: firstMatch(userAgent, /OS (\d+)[_.]/),
+        };
+    }
+    if (/Linux/.test(userAgent)) {
+        return {
+            family: "linux",
+            majorVersion: null,
+        };
+    }
+    return {
+        family: null,
+        majorVersion: null,
+    };
+};
+const detectDeviceType = (userAgent) => {
+    if (/Tablet|iPad/.test(userAgent)) {
+        return "tablet";
+    }
+    if (/Mobile|Android|iPhone|iPod/.test(userAgent)) {
+        return "mobile";
+    }
+    return "desktop";
+};
+const detectTimezone = () => {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || null;
+    }
+    catch {
+        return null;
+    }
+};
+const storageAvailable = (storageName) => {
+    try {
+        const storage = globalThis[storageName];
+        if (!storage) {
+            return false;
+        }
+        const key = "__clue_storage_probe__";
+        storage.setItem(key, "1");
+        storage.removeItem(key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const detectPointerType = () => {
+    if (typeof globalThis.matchMedia !== "function") {
+        return null;
+    }
+    if (globalThis.matchMedia("(pointer: coarse)").matches) {
+        return "coarse";
+    }
+    if (globalThis.matchMedia("(pointer: fine)").matches) {
+        return "fine";
+    }
+    return "unknown";
+};
+const detectMediaPreference = (query, matchesValue, fallbackValue) => {
+    if (typeof globalThis.matchMedia !== "function") {
+        return null;
+    }
+    return globalThis.matchMedia(query).matches ? matchesValue : fallbackValue;
+};
+const detectWebglSupport = () => {
+    try {
+        if (typeof globalThis.document === "undefined") {
+            return null;
+        }
+        if (!("WebGLRenderingContext" in globalThis) &&
+            !("WebGL2RenderingContext" in globalThis)) {
+            return false;
+        }
+        const canvas = globalThis.document.createElement("canvas");
+        return Boolean(canvas.getContext("webgl"));
+    }
+    catch {
+        return false;
+    }
+};
+export class EnvironmentManager {
+    constructor(options) {
+        this.options = options;
+    }
+    getContext() {
+        const userAgent = typeof globalThis.navigator !== "undefined"
+            ? globalThis.navigator.userAgent
+            : "";
+        const locale = typeof globalThis.navigator !== "undefined"
+            ? globalThis.navigator.language || null
+            : null;
+        const referrer = typeof globalThis.document !== "undefined"
+            ? globalThis.document.referrer || null
+            : null;
+        const browserInfo = detectBrowserInfo(userAgent);
+        const osInfo = detectOsInfo(userAgent);
+        return {
+            environment: this.options.environment,
+            frontendRelease: this.options.frontendRelease,
+            featureFlags: this.safeFeatureFlags(),
+            experimentVariant: this.safeExperimentVariant(),
+            locale,
+            country: null,
+            deviceType: detectDeviceType(userAgent),
+            browser: browserInfo.family,
+            os: osInfo.family,
+            referrer,
+            browserFamily: browserInfo.family,
+            browserMajorVersion: browserInfo.majorVersion,
+            browserEngine: browserInfo.engine,
+            osFamily: osInfo.family,
+            osMajorVersion: osInfo.majorVersion,
+            timezone: detectTimezone(),
+            pointerTypeCandidate: detectPointerType(),
+            touchCapable: typeof globalThis.navigator !== "undefined"
+                ? globalThis.navigator.maxTouchPoints > 0
+                : null,
+            cookiesEnabled: typeof globalThis.navigator !== "undefined"
+                ? globalThis.navigator.cookieEnabled
+                : null,
+            localStorageAvailable: storageAvailable("localStorage"),
+            sessionStorageAvailable: storageAvailable("sessionStorage"),
+            serviceWorkerSupported: typeof globalThis.navigator !== "undefined"
+                ? "serviceWorker" in globalThis.navigator
+                : null,
+            webglSupported: detectWebglSupport(),
+            reducedMotion: detectMediaPreference("(prefers-reduced-motion: reduce)", "reduce", "no-preference"),
+            colorScheme: detectMediaPreference("(prefers-color-scheme: dark)", "dark", "light"),
+        };
+    }
+    safeFeatureFlags() {
+        try {
+            return this.options.featureFlagsProvider?.() ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    safeExperimentVariant() {
+        try {
+            return this.options.experimentVariantProvider?.() ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/context/identity.d.ts

@@ -0,0 +1,14 @@
+import type { IdentityContext } from "../core/types";
+type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export declare class IdentityManager {
+    private readonly storage;
+    private state;
+    constructor(storage?: StorageLike);
+    getContext(): IdentityContext;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    clearUser(): void;
+    rotateAnonymousId(): string;
+    reset(): void;
+    private loadState;
+}
+export {};

package/dist/context/identity.js

@@ -0,0 +1,123 @@
+import { STORAGE_KEYS } from "../core/constants";
+import { generateAnonymousId } from "../normalize/event-id";
+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: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 broken stored value.
+    }
+    return {};
+};
+const saveJson = (storage, key, value) => {
+    try {
+        storage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // Swallow to keep SDK non-blocking.
+    }
+};
+export class IdentityManager {
+    constructor(storage) {
+        this.storage = storage ?? resolveStorage();
+        this.state = this.loadState();
+    }
+    getContext() {
+        return {
+            anonymousId: this.state.anonymousId,
+            userId: this.state.userId,
+            traits: { ...this.state.traits },
+        };
+    }
+    identify(userId, traits) {
+        this.state.userId = userId;
+        this.state.traits = {
+            ...this.state.traits,
+            ...(traits ?? {}),
+        };
+        try {
+            this.storage.setItem(STORAGE_KEYS.userId, userId);
+            saveJson(this.storage, STORAGE_KEYS.userTraits, this.state.traits);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    clearUser() {
+        this.state.userId = null;
+        this.state.traits = {};
+        try {
+            this.storage.removeItem(STORAGE_KEYS.userId);
+            this.storage.removeItem(STORAGE_KEYS.userTraits);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    rotateAnonymousId() {
+        const anonymousId = generateAnonymousId();
+        this.state.anonymousId = anonymousId;
+        try {
+            this.storage.setItem(STORAGE_KEYS.anonymousId, anonymousId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return anonymousId;
+    }
+    reset() {
+        this.clearUser();
+        this.rotateAnonymousId();
+    }
+    loadState() {
+        const storedAnonymousId = this.storage.getItem(STORAGE_KEYS.anonymousId);
+        const anonymousId = storedAnonymousId || generateAnonymousId();
+        if (!storedAnonymousId) {
+            try {
+                this.storage.setItem(STORAGE_KEYS.anonymousId, anonymousId);
+            }
+            catch {
+                // Swallow to keep SDK non-blocking.
+            }
+        }
+        const userId = this.storage.getItem(STORAGE_KEYS.userId);
+        const traits = safeJsonParse(this.storage.getItem(STORAGE_KEYS.userTraits));
+        return {
+            anonymousId,
+            userId,
+            traits,
+        };
+    }
+}

package/dist/context/session.d.ts

@@ -0,0 +1,28 @@
+import type { SessionContext } from "../core/types";
+type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+type SessionLifecycleResult = {
+    sessionId: string;
+    started: boolean;
+    ended: {
+        sessionId: string;
+        durationMs: number;
+    } | null;
+};
+export declare class SessionManager {
+    private readonly storage;
+    private readonly timeoutMs;
+    private context;
+    constructor(timeoutMs?: number, storage?: StorageLike);
+    getContext(): SessionContext;
+    ensureActiveSession(nowMs?: number): SessionLifecycleResult;
+    touch(nowMs?: number): void;
+    endSession(nowMs?: number): {
+        sessionId: string;
+        durationMs: number;
+    } | null;
+    reset(nowMs?: number): string;
+    private startSession;
+    private clear;
+    private loadState;
+}
+export {};

package/dist/context/session.js

@@ -0,0 +1,155 @@
+import { DEFAULT_SESSION_TIMEOUT_MS, STORAGE_KEYS } from "../core/constants";
+import { generateSessionId } from "../normalize/event-id";
+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.sessionStorage !== "undefined") {
+            const probeKey = "clue:session_probe";
+            globalThis.sessionStorage.setItem(probeKey, "1");
+            globalThis.sessionStorage.removeItem(probeKey);
+            return globalThis.sessionStorage;
+        }
+    }
+    catch {
+        // Ignore and fallback.
+    }
+    return createMemoryStorage();
+};
+const parseMs = (value) => {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+        return parsed;
+    }
+    return null;
+};
+export class SessionManager {
+    constructor(timeoutMs = DEFAULT_SESSION_TIMEOUT_MS, storage) {
+        this.timeoutMs = timeoutMs;
+        this.storage = storage ?? resolveStorage();
+        this.context = this.loadState();
+    }
+    getContext() {
+        return { ...this.context };
+    }
+    ensureActiveSession(nowMs = Date.now()) {
+        const currentSessionId = this.context.sessionId;
+        const currentStartedAt = this.context.startedAtMs;
+        const lastActivityAt = this.context.lastActivityAtMs;
+        if (!currentSessionId || !currentStartedAt || !lastActivityAt) {
+            const started = this.startSession(nowMs);
+            return {
+                sessionId: started,
+                started: true,
+                ended: null,
+            };
+        }
+        const idleMs = nowMs - lastActivityAt;
+        if (idleMs > this.timeoutMs) {
+            const endedDuration = Math.max(0, nowMs - currentStartedAt);
+            const ended = {
+                sessionId: currentSessionId,
+                durationMs: endedDuration,
+            };
+            const newSessionId = this.startSession(nowMs);
+            return {
+                sessionId: newSessionId,
+                started: true,
+                ended,
+            };
+        }
+        this.touch(nowMs);
+        return {
+            sessionId: currentSessionId,
+            started: false,
+            ended: null,
+        };
+    }
+    touch(nowMs = Date.now()) {
+        this.context.lastActivityAtMs = nowMs;
+        try {
+            this.storage.setItem(STORAGE_KEYS.sessionLastActivityAt, String(nowMs));
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    endSession(nowMs = Date.now()) {
+        if (!this.context.sessionId || !this.context.startedAtMs) {
+            this.clear();
+            return null;
+        }
+        const ended = {
+            sessionId: this.context.sessionId,
+            durationMs: Math.max(0, nowMs - this.context.startedAtMs),
+        };
+        this.clear();
+        return ended;
+    }
+    reset(nowMs = Date.now()) {
+        this.clear();
+        return this.startSession(nowMs);
+    }
+    startSession(nowMs) {
+        const sessionId = generateSessionId();
+        this.context = {
+            sessionId,
+            startedAtMs: nowMs,
+            lastActivityAtMs: nowMs,
+        };
+        try {
+            this.storage.setItem(STORAGE_KEYS.sessionId, sessionId);
+            this.storage.setItem(STORAGE_KEYS.sessionStartedAt, String(nowMs));
+            this.storage.setItem(STORAGE_KEYS.sessionLastActivityAt, String(nowMs));
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return sessionId;
+    }
+    clear() {
+        this.context = {
+            sessionId: null,
+            startedAtMs: null,
+            lastActivityAtMs: null,
+        };
+        try {
+            this.storage.removeItem(STORAGE_KEYS.sessionId);
+            this.storage.removeItem(STORAGE_KEYS.sessionStartedAt);
+            this.storage.removeItem(STORAGE_KEYS.sessionLastActivityAt);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    loadState() {
+        const sessionId = this.storage.getItem(STORAGE_KEYS.sessionId);
+        const startedAtMs = parseMs(this.storage.getItem(STORAGE_KEYS.sessionStartedAt));
+        const lastActivityAtMs = parseMs(this.storage.getItem(STORAGE_KEYS.sessionLastActivityAt));
+        if (!sessionId || !startedAtMs || !lastActivityAtMs) {
+            return {
+                sessionId: null,
+                startedAtMs: null,
+                lastActivityAtMs: null,
+            };
+        }
+        return {
+            sessionId,
+            startedAtMs,
+            lastActivityAtMs,
+        };
+    }
+}

package/dist/context/tab.d.ts

@@ -0,0 +1,22 @@
+type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+type TabManagerOptions = {
+    claimStorage?: StorageLike | null;
+    documentClaimId?: string;
+    now?: () => number;
+    bindLifecycleEvents?: boolean;
+};
+export declare class TabManager {
+    private readonly storage;
+    private readonly claimStorage;
+    private readonly documentClaimId;
+    private readonly now;
+    private readonly bindLifecycleEvents;
+    private readonly tabId;
+    constructor(storage?: StorageLike, options?: TabManagerOptions);
+    getTabId(): string;
+    private loadOrCreateTabId;
+    private isClaimedByAnotherDocument;
+    private claimTabId;
+    private installLifecycleCleanup;
+}
+export {};

package/dist/context/tab.js

@@ -0,0 +1,142 @@
+import { STORAGE_KEYS } from "../core/constants";
+import { generateEventId, generateTabId } from "../normalize/event-id";
+const TAB_CLAIM_KEY_PREFIX = "clue:tab_claim:";
+const TAB_CLAIM_TTL_MS = 5 * 60 * 1000;
+const DOCUMENT_CLAIM_ID = `doc_${generateEventId()}`;
+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.sessionStorage !== "undefined") {
+            const probeKey = "clue:tab_probe";
+            globalThis.sessionStorage.setItem(probeKey, "1");
+            globalThis.sessionStorage.removeItem(probeKey);
+            return globalThis.sessionStorage;
+        }
+    }
+    catch {
+        // Ignore and fallback.
+    }
+    return createMemoryStorage();
+};
+const resolveClaimStorage = () => {
+    try {
+        if (typeof globalThis.localStorage !== "undefined") {
+            const probeKey = "clue:tab_claim_probe";
+            globalThis.localStorage.setItem(probeKey, "1");
+            globalThis.localStorage.removeItem(probeKey);
+            return globalThis.localStorage;
+        }
+    }
+    catch {
+        // Ignore and continue without duplicate-tab coordination.
+    }
+    return null;
+};
+const parseTabClaim = (value) => {
+    if (!value) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed.claimId === "string" &&
+            typeof parsed.expiresAt === "number") {
+            return {
+                claimId: parsed.claimId,
+                expiresAt: parsed.expiresAt,
+            };
+        }
+    }
+    catch {
+        // Ignore invalid claim records and let the current document reclaim it.
+    }
+    return null;
+};
+export class TabManager {
+    constructor(storage, options) {
+        this.storage = storage ?? resolveStorage();
+        this.claimStorage =
+            options && "claimStorage" in options
+                ? (options.claimStorage ?? null)
+                : resolveClaimStorage();
+        this.documentClaimId = options?.documentClaimId ?? DOCUMENT_CLAIM_ID;
+        this.now = options?.now ?? Date.now;
+        this.bindLifecycleEvents = options?.bindLifecycleEvents ?? true;
+        this.tabId = this.loadOrCreateTabId();
+        this.claimTabId(this.tabId);
+        this.installLifecycleCleanup();
+    }
+    getTabId() {
+        return this.tabId;
+    }
+    loadOrCreateTabId() {
+        const stored = this.storage.getItem(STORAGE_KEYS.tabId);
+        if (stored && !this.isClaimedByAnotherDocument(stored)) {
+            return stored;
+        }
+        const tabId = generateTabId();
+        try {
+            this.storage.setItem(STORAGE_KEYS.tabId, tabId);
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+        return tabId;
+    }
+    isClaimedByAnotherDocument(tabId) {
+        if (!this.claimStorage) {
+            return false;
+        }
+        const claim = parseTabClaim(this.claimStorage.getItem(`${TAB_CLAIM_KEY_PREFIX}${tabId}`));
+        if (!claim || claim.expiresAt <= this.now()) {
+            return false;
+        }
+        return claim.claimId !== this.documentClaimId;
+    }
+    claimTabId(tabId) {
+        if (!this.claimStorage) {
+            return;
+        }
+        try {
+            this.claimStorage.setItem(`${TAB_CLAIM_KEY_PREFIX}${tabId}`, JSON.stringify({
+                claimId: this.documentClaimId,
+                expiresAt: this.now() + TAB_CLAIM_TTL_MS,
+            }));
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+    installLifecycleCleanup() {
+        if (!this.bindLifecycleEvents || !this.claimStorage) {
+            return;
+        }
+        try {
+            if (typeof globalThis.addEventListener !== "function") {
+                return;
+            }
+            const cleanup = () => {
+                const claimKey = `${TAB_CLAIM_KEY_PREFIX}${this.tabId}`;
+                const claim = parseTabClaim(this.claimStorage?.getItem(claimKey) ?? null);
+                if (claim?.claimId === this.documentClaimId) {
+                    this.claimStorage?.removeItem(claimKey);
+                }
+            };
+            globalThis.addEventListener("pagehide", cleanup, { once: true });
+            globalThis.addEventListener("beforeunload", cleanup, { once: true });
+        }
+        catch {
+            // Swallow to keep SDK non-blocking.
+        }
+    }
+}