@scoperat/tracker 0.2.0 → 0.3.0

package/dist/widget/index.js

@@ -1204,6 +1204,9 @@ var MAX_BATCH_SIZE = 100;
 var ANON_ID_KEY = "__scoperat_anon_id";
 var SESSION_ID_KEY = "__scoperat_session_id";
 var LAST_ACTIVITY_KEY = "__scoperat_last_activity";
+var USER_ID_KEY = "__scoperat_user_id";
+var SESSION_START_EVENT = "$session_start";
+var SESSION_END_EVENT = "$session_end";
 var TICKET_SESSION_KEY = "__scoperat_ticket_session";
 function generateAnonId() {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
@@ -1245,6 +1248,7 @@ var TrackerImpl = class {
   traits = {};
   userHash;
   anonymousId;
+  sessionId;
   sessionTimeout = DEFAULT_SESSION_TIMEOUT;
   ticketSessionFetch = null;
   _flagClient = null;
@@ -1307,6 +1311,7 @@ var TrackerImpl = class {
     return this._flagClient;
   }
   identify(userId, traits, options) {
+    const previousUserId = this.userId ?? this.readStoredUserId();
     this.userId = userId;
     if (traits) {
       this.traits = { ...traits };
@@ -1317,17 +1322,88 @@ var TrackerImpl = class {
       if (!evt.user_id) evt.user_id = userId;
       if (!evt.org_id && this.orgId) evt.org_id = this.orgId;
     }
+    if (userId !== previousUserId) {
+      this.writeStoredUserId(userId);
+      this.startSession("login");
+    }
     this._flagClient?.refresh();
   }
   reset() {
+    this.endSession("logout", true);
     this.userId = void 0;
     this.orgId = void 0;
     this.traits = {};
     this.userHash = void 0;
     this.anonymousId = getOrCreateAnonId();
-    this.clearSession();
+    this.clearStoredUserId();
     this.clearTicketSession();
   }
+  /**
+   * Begin a new analytics session, ending the current one first if it
+   * exists. Emits `$session_end` (for the old session) and
+   * `$session_start` (for the new). Called automatically on login via
+   * {@link identify}; also exposed for explicit control.
+   */
+  startSession(reason = "login") {
+    if (typeof window === "undefined") return this.sessionId;
+    const now = Date.now();
+    const existingId = this.readStoredSession();
+    if (existingId) {
+      this.emitSessionEvent(SESSION_END_EVENT, existingId, reason);
+    }
+    const newId = generateAnonId();
+    this.persistSession(newId, now);
+    this.emitSessionEvent(SESSION_START_EVENT, newId, reason);
+    return newId;
+  }
+  /**
+   * End the current analytics session (if any), emitting `$session_end`,
+   * and clear the stored session. The next tracked event will lazily
+   * start a fresh session. Called automatically on logout via
+   * {@link reset}; also exposed for explicit control.
+   *
+   * @param immediate - flush buffered events synchronously (via
+   *   `sendBeacon`) so the end event isn't lost if the page unloads.
+   */
+  endSession(reason = "logout", immediate = false) {
+    if (typeof window === "undefined") return;
+    const existingId = this.readStoredSession();
+    if (existingId) {
+      this.emitSessionEvent(SESSION_END_EVENT, existingId, reason);
+    }
+    this.sessionId = void 0;
+    this.clearSession();
+    if (immediate) {
+      if (typeof navigator === "undefined" || !navigator.sendBeacon) {
+        this.flush().catch(() => {
+        });
+      } else {
+        this.flushSync();
+      }
+    }
+  }
+  readStoredUserId() {
+    if (typeof localStorage === "undefined") return void 0;
+    try {
+      return localStorage.getItem(USER_ID_KEY) ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  writeStoredUserId(userId) {
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(USER_ID_KEY, userId);
+    } catch {
+    }
+  }
+  clearStoredUserId() {
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.removeItem(USER_ID_KEY);
+    } catch {
+    }
+  }
   clearTicketSession() {
     this.ticketSessionFetch = null;
     if (typeof localStorage === "undefined") return;
@@ -1392,25 +1468,96 @@ var TrackerImpl = class {
     })();
     return this.ticketSessionFetch;
   }
-  getOrCreateSessionId() {
-    if (typeof window === "undefined") return void 0;
+  /**
+   * Return the id of the current session, rotating it when the previous
+   * session has expired through inactivity. On rotation it emits a
+   * `$session_end` for the timed-out session (backdated to the last
+   * recorded activity) and a `$session_start` for the new one. Called on
+   * every tracked event so sessions advance with real user activity.
+   */
+  ensureSession(now) {
+    if (typeof window === "undefined") return this.sessionId;
     try {
-      const now = Date.now();
-      const lastActivity = localStorage.getItem(LAST_ACTIVITY_KEY);
-      const existingId = sessionStorage.getItem(SESSION_ID_KEY);
-      const expired = !lastActivity || now - Number(lastActivity) > this.sessionTimeout;
+      const lastActivity = this.readLastActivity();
+      const existingId = this.readStoredSession();
+      const expired = lastActivity === void 0 || now - lastActivity > this.sessionTimeout;
       if (existingId && !expired) {
-        localStorage.setItem(LAST_ACTIVITY_KEY, String(now));
+        this.sessionId = existingId;
+        try {
+          localStorage.setItem(LAST_ACTIVITY_KEY, String(now));
+        } catch {
+        }
         return existingId;
       }
+      if (existingId) {
+        this.emitSessionEvent(
+          SESSION_END_EVENT,
+          existingId,
+          "timeout",
+          lastActivity !== void 0 ? new Date(lastActivity).toISOString() : void 0
+        );
+      }
       const newId = generateAnonId();
-      sessionStorage.setItem(SESSION_ID_KEY, newId);
-      localStorage.setItem(LAST_ACTIVITY_KEY, String(now));
+      this.persistSession(newId, now);
+      this.emitSessionEvent(
+        SESSION_START_EVENT,
+        newId,
+        existingId ? "timeout" : "initial"
+      );
       return newId;
     } catch {
-      return generateAnonId();
+      return this.sessionId ?? generateAnonId();
+    }
+  }
+  readStoredSession() {
+    if (this.sessionId) return this.sessionId;
+    if (typeof sessionStorage === "undefined") return void 0;
+    try {
+      return sessionStorage.getItem(SESSION_ID_KEY) ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  readLastActivity() {
+    if (typeof localStorage === "undefined") return void 0;
+    try {
+      const raw = localStorage.getItem(LAST_ACTIVITY_KEY);
+      return raw ? Number(raw) : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  persistSession(id, now) {
+    this.sessionId = id;
+    if (typeof window === "undefined") return;
+    try {
+      sessionStorage.setItem(SESSION_ID_KEY, id);
+      localStorage.setItem(LAST_ACTIVITY_KEY, String(now));
+    } catch {
     }
   }
+  /**
+   * Enqueue a session lifecycle event already stamped with its session id
+   * (so it never re-enters {@link ensureSession} and risks recursion).
+   */
+  emitSessionEvent(event, sessionId, reason, occurredAt) {
+    if (!this.writeKey) return;
+    const traitsContext = Object.keys(this.traits).length > 0 ? { traits: this.traits } : {};
+    this.buffer.push({
+      event,
+      properties: { reason },
+      occurred_at: occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      source: "browser",
+      org_id: this.orgId,
+      user_id: this.userId,
+      anonymous_id: this.anonymousId,
+      session_id: sessionId,
+      context: {
+        ...getBrowserContext(),
+        ...traitsContext
+      }
+    });
+  }
   clearSession() {
     if (typeof window === "undefined") return;
     try {
@@ -1420,7 +1567,7 @@ var TrackerImpl = class {
     }
   }
   getSessionId() {
-    return this.getOrCreateSessionId();
+    return this.ensureSession(Date.now());
   }
   /** @internal Used by the widget to read tracker config. */
   _getEndpoint() {
@@ -1474,7 +1621,7 @@ var TrackerImpl = class {
       org_id: evt.org_id ?? this.orgId,
       user_id: evt.user_id ?? this.userId,
       anonymous_id: evt.anonymous_id ?? this.anonymousId,
-      session_id: evt.session_id ?? this.getOrCreateSessionId(),
+      session_id: evt.session_id ?? this.ensureSession(Date.now()),
       context: {
         ...getBrowserContext(),
         ...traitsContext,