@sessionlens/sdk 0.2.1 → 0.3.0

package/dist/index.esm.js

@@ -1,5 +1,105 @@
 import { useEffect } from 'react';
 
+/** RFC 4122 v4 UUID: crypto.randomUUID() when available, else getRandomValues, else Math.random. */
+function uuidv4() {
+    const c = typeof crypto !== 'undefined' ? crypto : undefined;
+    if (c && typeof c.randomUUID === 'function') {
+        return c.randomUUID();
+    }
+    const bytes = new Uint8Array(16);
+    if (c && typeof c.getRandomValues === 'function') {
+        c.getRandomValues(bytes);
+    }
+    else {
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 10
+    const hex = [];
+    for (let i = 0; i < 16; i++)
+        hex.push((bytes[i] + 0x100).toString(16).substring(1));
+    return (hex.slice(0, 4).join('') + '-' + hex.slice(4, 6).join('') + '-' + hex.slice(6, 8).join('') + '-' +
+        hex.slice(8, 10).join('') + '-' + hex.slice(10, 16).join(''));
+}
+
+// Storage keys (localStorage). Deliberately not scoped per project: a device is one device.
+const DEVICE_ID_KEY = '_sl_device_id';
+const DISTINCT_ID_KEY = '_sl_distinct_id';
+const USER_ID_KEY = '_sl_user_id';
+const INITIAL_REFERRER_KEY = '_sl_initial_referrer';
+// Used when localStorage is unavailable (SSR, private mode, blocked storage).
+const memoryStore = {};
+function storageGet(key) {
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            return window.localStorage.getItem(key);
+        }
+    }
+    catch (_) {
+        // fall through to memory
+    }
+    return key in memoryStore ? memoryStore[key] : null;
+}
+function storageSet(key, value) {
+    memoryStore[key] = value;
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.setItem(key, value);
+        }
+    }
+    catch (_) {
+        // memory copy above keeps the identity stable for this page session
+    }
+}
+function storageRemove(key) {
+    delete memoryStore[key];
+    try {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            window.localStorage.removeItem(key);
+        }
+    }
+    catch (_) {
+        // ignore
+    }
+}
+function getDeviceId() {
+    let deviceId = storageGet(DEVICE_ID_KEY);
+    if (!deviceId) {
+        deviceId = uuidv4();
+        storageSet(DEVICE_ID_KEY, deviceId);
+    }
+    return deviceId;
+}
+/** Current identity. Anonymous visitors have distinct_id === device_id and no user_id. */
+function getIdentity() {
+    const device_id = getDeviceId();
+    const user_id = storageGet(USER_ID_KEY) || undefined;
+    const distinct_id = storageGet(DISTINCT_ID_KEY) || user_id || device_id;
+    return { device_id, distinct_id, user_id };
+}
+/** Persist a user identity. From now on events carry distinct_id = userId. */
+function setUser(userId) {
+    storageSet(USER_ID_KEY, userId);
+    storageSet(DISTINCT_ID_KEY, userId);
+}
+/** Forget the user and start a fresh anonymous identity on a new device id. */
+function resetIdentity() {
+    storageRemove(USER_ID_KEY);
+    storageRemove(DISTINCT_ID_KEY);
+    storageRemove(DEVICE_ID_KEY);
+    return getIdentity();
+}
+/** Referrer of the very first page load, persisted once ('$direct' when there was none). */
+function getInitialReferrer(currentReferrer) {
+    let value = storageGet(INITIAL_REFERRER_KEY);
+    if (value === null) {
+        value = currentReferrer || '$direct';
+        storageSet(INITIAL_REFERRER_KEY, value);
+    }
+    return value;
+}
+
 // Session timeout (30 minutes of inactivity)
 const SESSION_TIMEOUT = 30 * 60 * 1000;
 // Store the config and session info
@@ -57,7 +157,7 @@ const startNewSession = (config) => {
         client_id: getOrCreateClientId(config),
         org_id: config.org_id,
         project_id: project_id,
-        user_id: config.user_id,
+        user_id: getIdentity().user_id,
         started_at: now,
         last_activity: now
     };
@@ -75,6 +175,12 @@ const isSessionExpired = () => {
         return true;
     return Date.now() - currentSession.last_activity > SESSION_TIMEOUT;
 };
+// Begin a fresh session (used by reset())
+function restartSession() {
+    if (currentConfig) {
+        startNewSession(currentConfig);
+    }
+}
 // Update session activity timestamp
 const updateSessionActivity = () => {
     if (currentSession) {
@@ -102,14 +208,11 @@ const getEndpoint = (config, endpointType, defaultEndpoint) => {
     return ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a[endpointType]) || defaultEndpoint;
 };
 // `sessionLensInit()` sets the config and validates with backend
-async function sessionLensInit(config) {
+async function sessionLensInit$1(config) {
     // Validate required fields
     if (!config.sdk_key) {
         throw new Error('[SessionLens] sdk_key is required');
     }
-    if (!config.user_id) {
-        throw new Error('[SessionLens] user_id is required');
-    }
     if (!config.org_id) {
         throw new Error('[SessionLens] org_id is required');
     }
@@ -124,7 +227,9 @@ async function sessionLensInit(config) {
         // Use GET with query parameters for org_id and user_id validation
         const validationUrl = new URL(`${apiBaseUrl}${validateEndpoint}`);
         validationUrl.searchParams.set('org_id', config.org_id);
-        validationUrl.searchParams.set('user_id', config.user_id);
+        if (config.user_id) {
+            validationUrl.searchParams.set('user_id', config.user_id);
+        }
         const response = await fetch(validationUrl.toString(), {
             method: 'GET',
             headers: {
@@ -192,154 +297,260 @@ function getSessionLensApiBaseUrl() {
     return getApiBaseUrl(currentConfig || undefined);
 }
 
-function sessionLensTrack(event) {
-    const config = sessionLensGetConfig();
-    const sessionInfo = getSessionInfo(); // Get current session with activity update
-    // Add timestamp if not provided
-    const eventWithTimestamp = {
-        ...event,
-        timestamp: event.timestamp || Date.now()
+// Order matters: Edge/Opera/Samsung embed "Chrome", Chrome embeds "Safari".
+const BROWSERS = [
+    ['Edge', /(?:Edg|EdgA|EdgiOS|Edge)\/([\d.]+)/],
+    ['Opera', /(?:OPR|Opera)\/([\d.]+)/],
+    ['Samsung Internet', /SamsungBrowser\/([\d.]+)/],
+    ['Firefox', /(?:Firefox|FxiOS)\/([\d.]+)/],
+    ['Chrome', /(?:Chrome|CriOS)\/([\d.]+)/],
+    ['Internet Explorer', /(?:MSIE |Trident\/.*rv:)([\d.]+)/],
+    ['Safari', /Version\/([\d.]+).*Safari/],
+];
+const OSES = [
+    ['Windows', /Windows NT ([\d.]+)/],
+    ['iOS', /(?:iPhone|CPU) OS ([\d_]+)/],
+    ['Android', /Android ([\d.]+)/],
+    ['Mac OS X', /Mac OS X ([\d_.]+)/],
+    ['Chrome OS', /CrOS \S+ ([\d.]+)/],
+    ['Linux', /Linux()/],
+];
+function parseUserAgent(ua) {
+    const result = { browser: '', browser_version: '', os: '', os_version: '', device_type: '' };
+    if (!ua)
+        return result;
+    for (const [name, re] of BROWSERS) {
+        const m = ua.match(re);
+        if (m) {
+            result.browser = name;
+            result.browser_version = m[1];
+            break;
+        }
+    }
+    for (const [name, re] of OSES) {
+        const m = ua.match(re);
+        if (m) {
+            result.os = name;
+            result.os_version = (m[1] || '').replace(/_/g, '.');
+            break;
+        }
+    }
+    if (/iPad|Tablet|PlayBook|Silk/i.test(ua) || (/Android/i.test(ua) && !/Mobile/i.test(ua))) {
+        result.device_type = 'Tablet';
+    }
+    else if (/Mobi|iPhone|iPod|Android|Windows Phone/i.test(ua)) {
+        result.device_type = 'Mobile';
+    }
+    else if (result.os) {
+        result.device_type = 'Desktop';
+    }
+    return result;
+}
+
+// Hand-maintained (bundling package.json would need an extra rollup plugin).
+// Keep in sync with "version" in package.json when releasing.
+const SDK_VERSION = '0.3.0';
+const SDK_LIBRARY = 'sessionlens-js';
+
+const UTM_KEYS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];
+function hostOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch (_) {
+        return '';
+    }
+}
+/**
+ * System properties attached to every event. All browser access is guarded so this
+ * is safe to call during SSR (only identity/library fields are returned there).
+ * The server re-derives browser/os/geo authoritatively; the client UA fields are a fallback.
+ */
+function buildSystemProperties(clientTimestamp) {
+    const identity = getIdentity();
+    const props = {
+        $device_id: identity.device_id,
+        $distinct_id: identity.distinct_id,
+        $insert_id: uuidv4(),
+        $library: SDK_LIBRARY,
+        $library_version: SDK_VERSION,
+        $client_timestamp: clientTimestamp,
     };
-    if (config.debug) {
-        console.log('SessionLens Track:', eventWithTimestamp);
-        console.log('Session Context:', {
-            session_id: sessionInfo.session_id,
-            client_id: sessionInfo.client_id,
-            project_id: sessionInfo.project_id
-        });
+    if (identity.user_id)
+        props.$user_id = identity.user_id;
+    if (typeof window === 'undefined')
+        return props;
+    try {
+        const loc = window.location;
+        props.$current_url = loc.href;
+        props.$pathname = loc.pathname;
+        const referrer = typeof document !== 'undefined' ? document.referrer || '' : '';
+        props.$referrer = referrer || '$direct';
+        props.$referring_domain = referrer ? hostOf(referrer) : '$direct';
+        props.$initial_referrer = getInitialReferrer(referrer);
+        const params = new URLSearchParams(loc.search);
+        for (const key of UTM_KEYS) {
+            const value = params.get(key);
+            if (value)
+                props['$' + key] = value;
+        }
+        if (window.screen) {
+            props.$screen_width = window.screen.width;
+            props.$screen_height = window.screen.height;
+        }
+        if (typeof navigator !== 'undefined' && navigator.userAgent) {
+            const ua = parseUserAgent(navigator.userAgent);
+            if (ua.browser)
+                props.$browser = ua.browser;
+            if (ua.browser_version)
+                props.$browser_version = ua.browser_version;
+            if (ua.os)
+                props.$os = ua.os;
+            if (ua.os_version)
+                props.$os_version = ua.os_version;
+            if (ua.device_type)
+                props.$device_type = ua.device_type;
+        }
     }
-    // Send event to backend with session context
-    sendEventToBackend(eventWithTimestamp, config, sessionInfo);
+    catch (_) {
+        // enrichment must never break tracking
+    }
+    return props;
 }
-function sessionLensIdentify(user) {
-    const config = sessionLensGetConfig();
-    const sessionInfo = getSessionInfo(); // Get current session with activity update
-    if (config.debug) {
-        console.log('SessionLens Identify:', user);
-        console.log('Session Context:', {
-            session_id: sessionInfo.session_id,
-            client_id: sessionInfo.client_id,
-            project_id: sessionInfo.project_id
-        });
+
+/**
+ * Initialize the SDK. If `config.user_id` is supplied (pre-0.3 integrations) it is treated
+ * as an implicit identify() - sent only when it differs from the persisted identity.
+ */
+async function sessionLensInit(config) {
+    await sessionLensInit$1(config);
+    if (config.user_id && getIdentity().user_id !== config.user_id) {
+        identify(config.user_id);
     }
-    // Send identify event to backend with session context
-    sendIdentifyToBackend(user, config, sessionInfo);
 }
-function sessionLensReset() {
+function sessionLensTrack(event) {
     const config = sessionLensGetConfig();
     const sessionInfo = getSessionInfo(); // Get current session with activity update
+    const timestamp = event.timestamp || Date.now();
+    // Caller-supplied properties override auto-collected ones (e.g. to pass a stable $insert_id for retries).
+    const properties = { ...buildSystemProperties(timestamp), ...(event.properties || {}) };
+    const eventWithContext = { ...event, timestamp, properties };
     if (config.debug) {
-        console.log('SessionLens Reset');
+        console.log('SessionLens Track:', eventWithContext);
         console.log('Session Context:', {
             session_id: sessionInfo.session_id,
             client_id: sessionInfo.client_id,
             project_id: sessionInfo.project_id
         });
     }
-    // Clear any stored user data and send reset event to backend
-    sendResetToBackend(config, sessionInfo);
+    sendEventToBackend(eventWithContext, config, sessionInfo);
 }
-// Helper functions for backend communication with session context
-async function sendEventToBackend(event, config, sessionInfo) {
+/** Link the current device to `userId` (last identify wins) and optionally set traits. */
+function identify(userId, traits) {
     var _a;
-    const apiBaseUrl = getSessionLensApiBaseUrl();
-    const eventsEndpoint = ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.events) || '/events/ingest';
-    try {
-        const response = await fetch(`${apiBaseUrl}${eventsEndpoint}`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${config.sdk_key}`
-            },
-            body: JSON.stringify({
-                org_id: config.org_id,
-                project_id: sessionInfo.project_id,
-                user_id: config.user_id,
-                session_id: sessionInfo.session_id,
-                client_id: sessionInfo.client_id,
-                session_started_at: sessionInfo.started_at,
-                event: event
-            })
-        });
-        if (!response.ok && config.debug) {
-            console.warn('SessionLens: Failed to send event:', response.status);
-        }
-        else if (config.debug) {
-            console.log('SessionLens: Event sent successfully with session context');
-        }
+    const config = sessionLensGetConfig();
+    const sessionInfo = getSessionInfo();
+    if (!userId) {
+        if (config.debug)
+            console.warn('SessionLens: identify() requires a userId');
+        return;
     }
-    catch (error) {
-        if (config.debug) {
-            console.warn('SessionLens: Network error sending event:', error);
-        }
+    setUser(userId);
+    if (config.debug) {
+        console.log('SessionLens Identify:', { userId, traits });
     }
+    post(config, ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.identify) || '/identify', {
+        org_id: config.org_id,
+        project_id: sessionInfo.project_id,
+        app: config.app || 'unknown',
+        user_id: userId,
+        device_id: getIdentity().device_id,
+        session_id: sessionInfo.session_id,
+        client_id: sessionInfo.client_id,
+        session_started_at: sessionInfo.started_at,
+        traits: traits || {}
+    }, 'identify');
+}
+/** @deprecated Aliasing is subsumed by identify(); `oldId` is ignored (the device link is implicit). */
+function alias(newId, _oldId) {
+    identify(newId);
+}
+/** Set traits on the current profile (`name` and `email` map to core profile fields). */
+function setUserProperties(traits) {
+    var _a;
+    const config = sessionLensGetConfig();
+    const sessionInfo = getSessionInfo();
+    post(config, ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.userProperties) || '/user-properties', {
+        org_id: config.org_id,
+        project_id: sessionInfo.project_id,
+        distinct_id: getIdentity().distinct_id,
+        traits: traits || {}
+    }, 'user properties');
+}
+/** Legacy signature: sessionLensIdentify({ user_id, properties }). */
+function sessionLensIdentify(user) {
+    identify(user.user_id, user.properties);
 }
-async function sendIdentifyToBackend(user, config, sessionInfo) {
+/** Forget the user, start an anonymous identity on a new device id and a new session. */
+function reset() {
     var _a;
-    const apiBaseUrl = getSessionLensApiBaseUrl();
-    const identifyEndpoint = ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.identify) || '/identify';
+    const config = sessionLensGetConfig();
+    const sessionInfo = getSessionInfo();
+    if (config.debug) {
+        console.log('SessionLens Reset');
+    }
+    post(config, ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.reset) || '/reset', {
+        org_id: config.org_id,
+        project_id: sessionInfo.project_id,
+        session_id: sessionInfo.session_id,
+        client_id: sessionInfo.client_id,
+        session_started_at: sessionInfo.started_at
+    }, 'reset');
+    resetIdentity();
+    restartSession();
+}
+const sessionLensReset = reset;
+async function post(config, endpoint, body, label) {
     try {
-        const response = await fetch(`${apiBaseUrl}${identifyEndpoint}`, {
+        const response = await fetch(`${getSessionLensApiBaseUrl()}${endpoint}`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
                 'Authorization': `Bearer ${config.sdk_key}`
             },
-            body: JSON.stringify({
-                org_id: config.org_id,
-                project_id: sessionInfo.project_id,
-                user_id: user.user_id,
-                session_id: sessionInfo.session_id,
-                client_id: sessionInfo.client_id,
-                session_started_at: sessionInfo.started_at,
-                properties: user.properties
-            })
+            body: JSON.stringify(body)
         });
         if (!response.ok && config.debug) {
-            console.warn('SessionLens: Failed to send identify:', response.status);
+            console.warn(`SessionLens: Failed to send ${label}:`, response.status);
         }
         else if (config.debug) {
-            console.log('SessionLens: Identify sent successfully with session context');
+            console.log(`SessionLens: ${label} sent successfully`);
         }
     }
     catch (error) {
         if (config.debug) {
-            console.warn('SessionLens: Network error sending identify:', error);
+            console.warn(`SessionLens: Network error sending ${label}:`, error);
         }
     }
 }
-async function sendResetToBackend(config, sessionInfo) {
+function sendEventToBackend(event, config, sessionInfo) {
     var _a;
-    const apiBaseUrl = getSessionLensApiBaseUrl();
-    const resetEndpoint = ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.reset) || '/reset';
-    try {
-        const response = await fetch(`${apiBaseUrl}${resetEndpoint}`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${config.sdk_key}`
-            },
-            body: JSON.stringify({
-                org_id: config.org_id,
-                project_id: sessionInfo.project_id,
-                user_id: config.user_id,
-                session_id: sessionInfo.session_id,
-                client_id: sessionInfo.client_id,
-                session_started_at: sessionInfo.started_at
-            })
-        });
-        if (!response.ok && config.debug) {
-            console.warn('SessionLens: Failed to send reset:', response.status);
-        }
-        else if (config.debug) {
-            console.log('SessionLens: Reset sent successfully with session context');
-        }
-    }
-    catch (error) {
-        if (config.debug) {
-            console.warn('SessionLens: Network error sending reset:', error);
-        }
+    const identity = getIdentity();
+    const body = {
+        org_id: config.org_id,
+        project_id: sessionInfo.project_id,
+        app: event.app || config.app || 'unknown',
+        device_id: identity.device_id,
+        distinct_id: identity.distinct_id,
+        session_id: sessionInfo.session_id,
+        client_id: sessionInfo.client_id,
+        session_started_at: sessionInfo.started_at,
+        event: event
+    };
+    if (identity.user_id) {
+        body.user_id = identity.user_id;
     }
+    return post(config, ((_a = config.endpoints) === null || _a === void 0 ? void 0 : _a.events) || '/events/ingest', body, 'event');
 }
 
 const useSessionLens = (config) => {
@@ -354,10 +565,8 @@ const useSessionLens = (config) => {
             }
         };
         initializeSDK();
-        // Cleanup on unmount
-        return () => {
-            sessionLensReset();
-        };
+        // No cleanup reset: reset() now clears the persisted device/user identity, which must
+        // survive unmounts and re-renders. Call reset() explicitly on logout instead.
     }, [config]);
 };
 const useSessionLensTrack = () => {
@@ -394,9 +603,22 @@ class SessionLens {
     sessionLensReset() {
         sessionLensReset();
     }
+    identify(userId, traits) {
+        identify(userId, traits);
+    }
+    /** @deprecated Use identify(). */
+    alias(newId, oldId) {
+        alias(newId);
+    }
+    setUserProperties(traits) {
+        setUserProperties(traits);
+    }
+    reset() {
+        reset();
+    }
 }
 // Create and export singleton instance
 const sessionLens = new SessionLens();
 
-export { sessionLens as default, useSessionLens, useSessionLensIdentify, useSessionLensTrack };
+export { SDK_VERSION, sessionLens as default, useSessionLens, useSessionLensIdentify, useSessionLensTrack };
 //# sourceMappingURL=index.esm.js.map