@anyreplay/browser 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -40,14 +40,15 @@ declare class ConfigError extends Error {
 declare function resolveOptions(input: AnyReplayOptions): ResolvedOptions;
 
 type RecorderStatus = 'idle' | 'awaiting-consent' | 'recording' | 'sampled-out' | 'stopped';
+interface IdentifyTraits {
+    userId?: string;
+    email?: string;
+}
 interface RecorderHandle {
     status: () => RecorderStatus;
     sessionId: () => string | null;
     consent: (granted: boolean) => void;
-    identify: (traits: {
-        userId?: string;
-        email?: string;
-    }) => void;
+    identify: (traits: IdentifyTraits) => void;
     /**
      * Tags this moment of the recording so it shows on the player's timeline.
      *
@@ -199,6 +200,18 @@ interface Identity {
  * id resets after a period of inactivity.
  */
 declare function resolveIdentity(local: Storage, session: Storage, now?: number): Identity;
+/**
+ * Removes everything the recorder has stored in this browser.
+ *
+ * Called when consent is refused. A refusal has to undo an earlier acceptance,
+ * not merely stop the current page: the visitor id written last week is
+ * exactly what the visitor is now saying no to, and leaving it in place would
+ * make "we store nothing without consent" untrue for as long as it sat there.
+ * The cool-down goes too — it is a fact about a session that no longer exists.
+ * Removing a key that is not there creates nothing, so this is safe to call
+ * before anything was ever written.
+ */
+declare function forgetVisitor(local: Storage, session: Storage): void;
 
 /**
  * Custom events: the moments a page tags with `track()`.
@@ -225,4 +238,4 @@ interface TrackPayload {
  */
 declare function validateTrack(name: unknown, properties: unknown): TrackPayload | string;
 
-export { type AnyReplayOptions, ConfigError, DEFAULTS, EVENT_NAME_PATTERN, MAX_PROPERTIES_BYTES, NAVIGATE_TAG, type RecordedEvent, type RecorderHandle, type RecorderStatus, type ResolvedOptions, type SessionMeta, TRACK_TAG, type TrackPayload, Transport, createRecorder, hashToUnitInterval, isSampledIn, resolveIdentity, resolveOptions, safeStorage, uuidv4, validateTrack };
+export { type AnyReplayOptions, ConfigError, DEFAULTS, EVENT_NAME_PATTERN, MAX_PROPERTIES_BYTES, NAVIGATE_TAG, type RecordedEvent, type RecorderHandle, type RecorderStatus, type ResolvedOptions, type SessionMeta, TRACK_TAG, type TrackPayload, Transport, createRecorder, forgetVisitor, hashToUnitInterval, isSampledIn, resolveIdentity, resolveOptions, safeStorage, uuidv4, validateTrack };

package/dist/index.d.ts

@@ -40,14 +40,15 @@ declare class ConfigError extends Error {
 declare function resolveOptions(input: AnyReplayOptions): ResolvedOptions;
 
 type RecorderStatus = 'idle' | 'awaiting-consent' | 'recording' | 'sampled-out' | 'stopped';
+interface IdentifyTraits {
+    userId?: string;
+    email?: string;
+}
 interface RecorderHandle {
     status: () => RecorderStatus;
     sessionId: () => string | null;
     consent: (granted: boolean) => void;
-    identify: (traits: {
-        userId?: string;
-        email?: string;
-    }) => void;
+    identify: (traits: IdentifyTraits) => void;
     /**
      * Tags this moment of the recording so it shows on the player's timeline.
      *
@@ -199,6 +200,18 @@ interface Identity {
  * id resets after a period of inactivity.
  */
 declare function resolveIdentity(local: Storage, session: Storage, now?: number): Identity;
+/**
+ * Removes everything the recorder has stored in this browser.
+ *
+ * Called when consent is refused. A refusal has to undo an earlier acceptance,
+ * not merely stop the current page: the visitor id written last week is
+ * exactly what the visitor is now saying no to, and leaving it in place would
+ * make "we store nothing without consent" untrue for as long as it sat there.
+ * The cool-down goes too — it is a fact about a session that no longer exists.
+ * Removing a key that is not there creates nothing, so this is safe to call
+ * before anything was ever written.
+ */
+declare function forgetVisitor(local: Storage, session: Storage): void;
 
 /**
  * Custom events: the moments a page tags with `track()`.
@@ -225,4 +238,4 @@ interface TrackPayload {
  */
 declare function validateTrack(name: unknown, properties: unknown): TrackPayload | string;
 
-export { type AnyReplayOptions, ConfigError, DEFAULTS, EVENT_NAME_PATTERN, MAX_PROPERTIES_BYTES, NAVIGATE_TAG, type RecordedEvent, type RecorderHandle, type RecorderStatus, type ResolvedOptions, type SessionMeta, TRACK_TAG, type TrackPayload, Transport, createRecorder, hashToUnitInterval, isSampledIn, resolveIdentity, resolveOptions, safeStorage, uuidv4, validateTrack };
+export { type AnyReplayOptions, ConfigError, DEFAULTS, EVENT_NAME_PATTERN, MAX_PROPERTIES_BYTES, NAVIGATE_TAG, type RecordedEvent, type RecorderHandle, type RecorderStatus, type ResolvedOptions, type SessionMeta, TRACK_TAG, type TrackPayload, Transport, createRecorder, forgetVisitor, hashToUnitInterval, isSampledIn, resolveIdentity, resolveOptions, safeStorage, uuidv4, validateTrack };

package/dist/index.js

@@ -4007,6 +4007,10 @@ function reserveSeq(session, next) {
 function touchSession(session, now = Date.now()) {
   session.set(SESSION_TS_KEY, String(now));
 }
+function forgetVisitor(local, session) {
+  local.remove(VISITOR_KEY);
+  for (const key of [SESSION_KEY, SESSION_TS_KEY, SEQ_KEY, PAGE_KEY, COOLDOWN_KEY]) session.remove(key);
+}
 
 // src/recorder.ts
 var RAGE_CLICK_COUNT = 3;
@@ -4017,37 +4021,22 @@ function createRecorder(rawOptions) {
   const options = resolveOptions(rawOptions);
   const local = safeStorage(() => globalThis.localStorage);
   const session = safeStorage(() => globalThis.sessionStorage);
-  const identity = resolveIdentity(local, session);
   let status = "idle";
+  let identity;
+  let transport;
   let stopRecording;
-  let pageCount = identity.pageCount;
-  if (!isSampledIn(identity.visitorId, options.sampleRate)) {
-    return inertHandle("sampled-out", identity.sessionId);
-  }
-  if (inCooldown(session)) {
-    if (options.debug) console.warn("[anyreplay] not recording: ingest refused a new session recently");
-    return inertHandle("stopped", identity.sessionId);
-  }
-  const transport = new Transport(
-    options,
-    {
-      projectKey: options.projectKey,
-      sessionId: identity.sessionId,
-      visitorId: identity.visitorId,
-      initialSeq: identity.nextSeq
-    },
-    {
-      onSeqReserved: (next) => reserveSeq(session, next),
-      onStopped: (reason) => {
-        status = "stopped";
-        stopRecording == null ? void 0 : stopRecording();
-        stopRecording = void 0;
-        if (reason === "rejected_402") startCooldown(session);
-        if (options.debug) console.warn(`[anyreplay] recording stopped: ${reason}`);
-      }
-    }
-  );
-  const collectMeta = () => ({
+  let pageCount = 0;
+  let pendingTraits;
+  const sendIdentity = (who, traits) => {
+    void fetch(`${options.ingestUrl}/v1/ingest/identify`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      credentials: "omit",
+      body: JSON.stringify({ projectKey: options.projectKey, sessionId: who.sessionId, ...traits })
+    }).catch(() => {
+    });
+  };
+  const collectMeta = (who) => ({
     startedAt: Date.now(),
     url: safeLocation(),
     lang: typeof navigator !== "undefined" ? navigator.language : void 0,
@@ -4057,10 +4046,10 @@ function createRecorder(rawOptions) {
     referrer: typeof document !== "undefined" ? document.referrer || void 0 : void 0,
     // The cap is a decision about starting a session, so it goes only where
     // ingest makes that decision: chunk 0. A resumed page starts later.
-    ...options.maxSessionsPerMonth !== void 0 && identity.nextSeq === 0 ? { sessionCap: options.maxSessionsPerMonth } : {}
+    ...options.maxSessionsPerMonth !== void 0 && who.nextSeq === 0 ? { sessionCap: options.maxSessionsPerMonth } : {}
   });
   const recentClicks = [];
-  const noteInteraction = (event) => {
+  const noteInteraction = (event, channel) => {
     var _a;
     const data = event.data;
     if (event.type !== 3 || (data == null ? void 0 : data.source) !== 2 || typeof data.x !== "number") return;
@@ -4072,7 +4061,7 @@ function createRecorder(rawOptions) {
       const clustered = recentClicks.every(
         (c) => Math.abs(c.x - first.x) < RAGE_CLICK_RADIUS_PX && Math.abs(c.y - first.y) < RAGE_CLICK_RADIUS_PX
       );
-      if (clustered) transport.mergeFlags({ hasRageClick: true });
+      if (clustered) channel.mergeFlags({ hasRageClick: true });
     }
   };
   const pending = [];
@@ -4100,7 +4089,7 @@ function createRecorder(rawOptions) {
     }
   };
   const emitCustom = (tag, payload) => {
-    if (status === "stopped") return;
+    if (status === "stopped" || status === "sampled-out") return;
     if (status === "recording") {
       try {
         record.addCustomEvent(tag, payload);
@@ -4114,28 +4103,61 @@ function createRecorder(rawOptions) {
     }
     pending.push({ tag, payload });
   };
-  let lastUrl = safeLocation();
-  const noteNavigation = () => {
+  let lastUrl;
+  const noteNavigation = (channel) => {
     const url = safeLocation();
     if (!url || url === lastUrl) return;
     lastUrl = url;
     pageCount += 1;
     notePageCount(session, pageCount);
-    transport.mergeFlags({ pageCount });
+    channel.mergeFlags({ pageCount });
     emitCustom(NAVIGATE_TAG, { url, title: typeof document !== "undefined" ? document.title : "" });
   };
   const begin = () => {
-    if (status === "recording" || status === "stopped") return;
+    if (status !== "idle" && status !== "awaiting-consent") return;
+    const who = resolveIdentity(local, session);
+    identity = who;
+    pageCount = who.pageCount;
+    if (!isSampledIn(who.visitorId, options.sampleRate)) {
+      status = "sampled-out";
+      return;
+    }
+    if (inCooldown(session)) {
+      status = "stopped";
+      if (options.debug) console.warn("[anyreplay] not recording: ingest refused a new session recently");
+      return;
+    }
+    const channel = new Transport(
+      options,
+      {
+        projectKey: options.projectKey,
+        sessionId: who.sessionId,
+        visitorId: who.visitorId,
+        initialSeq: who.nextSeq
+      },
+      {
+        onSeqReserved: (next) => reserveSeq(session, next),
+        onStopped: (reason) => {
+          status = "stopped";
+          stopRecording == null ? void 0 : stopRecording();
+          stopRecording = void 0;
+          if (reason === "rejected_402") startCooldown(session);
+          if (options.debug) console.warn(`[anyreplay] recording stopped: ${reason}`);
+        }
+      }
+    );
+    transport = channel;
     status = "recording";
-    transport.setMeta(collectMeta());
-    transport.mergeFlags({ pageCount });
-    transport.start();
+    lastUrl = safeLocation();
+    channel.setMeta(collectMeta(who));
+    channel.mergeFlags({ pageCount });
+    channel.start();
     stopRecording = record({
       emit: (event) => {
         const typed = event;
-        noteInteraction(typed);
+        noteInteraction(typed, channel);
         touchSession(session, typed.timestamp);
-        transport.push(typed);
+        channel.push(typed);
         drainPending();
       },
       maskAllInputs: options.maskAllInputs,
@@ -4148,29 +4170,33 @@ function createRecorder(rawOptions) {
       collectFonts: false
     });
     drainPending();
-    attachLifecycleHooks();
+    if (pendingTraits) {
+      sendIdentity(who, pendingTraits);
+      pendingTraits = void 0;
+    }
+    attachLifecycleHooks(channel);
   };
-  const attachLifecycleHooks = () => {
+  const attachLifecycleHooks = (channel) => {
     if (typeof window === "undefined") return;
     window.addEventListener("pagehide", () => {
-      transport.flushWithBeacon();
+      channel.flushWithBeacon();
     }, { capture: true });
     document.addEventListener("visibilitychange", () => {
-      if (document.visibilityState === "hidden") transport.flushWithBeacon();
+      if (document.visibilityState === "hidden") channel.flushWithBeacon();
     });
-    window.addEventListener("error", () => transport.mergeFlags({ hasError: true }));
-    window.addEventListener("unhandledrejection", () => transport.mergeFlags({ hasError: true }));
+    window.addEventListener("error", () => channel.mergeFlags({ hasError: true }));
+    window.addEventListener("unhandledrejection", () => channel.mergeFlags({ hasError: true }));
     const patch2 = (method) => {
       const original = history[method].bind(history);
       history[method] = function patched(...args) {
         const result = original(...args);
-        noteNavigation();
+        noteNavigation(channel);
         return result;
       };
     };
     patch2("pushState");
     patch2("replaceState");
-    window.addEventListener("popstate", noteNavigation);
+    window.addEventListener("popstate", () => noteNavigation(channel));
   };
   if (options.requireConsent) {
     status = "awaiting-consent";
@@ -4179,24 +4205,28 @@ function createRecorder(rawOptions) {
   }
   return {
     status: () => status,
-    sessionId: () => identity.sessionId,
+    sessionId: () => {
+      var _a;
+      return (_a = identity == null ? void 0 : identity.sessionId) != null ? _a : null;
+    },
     consent: (granted) => {
-      if (granted) begin();
-      else transport.stop("consent_withdrawn");
+      if (granted) {
+        begin();
+        return;
+      }
+      transport == null ? void 0 : transport.stop("consent_withdrawn");
+      if (status === "idle" || status === "awaiting-consent") status = "stopped";
+      pendingTraits = void 0;
+      forgetVisitor(local, session);
     },
     identify: (traits) => {
       if (!traits.userId && !traits.email) return;
-      void fetch(`${options.ingestUrl}/v1/ingest/identify`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        credentials: "omit",
-        body: JSON.stringify({
-          projectKey: options.projectKey,
-          sessionId: identity.sessionId,
-          ...traits
-        })
-      }).catch(() => {
-      });
+      if (identity && transport) {
+        sendIdentity(identity, traits);
+        return;
+      }
+      if (status === "idle" || status === "awaiting-consent") pendingTraits = traits;
+      else if (options.debug) console.warn("[anyreplay] identify() ignored: not recording");
     },
     track: (name, properties) => {
       const payload = validateTrack(name, properties);
@@ -4206,8 +4236,15 @@ function createRecorder(rawOptions) {
       }
       emitCustom(TRACK_TAG, payload);
     },
-    stop: () => transport.stop("stopped_by_page"),
-    flush: () => transport.flush()
+    stop: () => {
+      transport == null ? void 0 : transport.stop("stopped_by_page");
+      if (status === "idle" || status === "awaiting-consent") status = "stopped";
+      pendingTraits = void 0;
+    },
+    flush: () => {
+      var _a;
+      return (_a = transport == null ? void 0 : transport.flush()) != null ? _a : Promise.resolve();
+    }
   };
 }
 function safeLocation() {
@@ -4217,22 +4254,6 @@ function safeLocation() {
     return void 0;
   }
 }
-function inertHandle(status, sessionId) {
-  return {
-    status: () => status,
-    sessionId: () => sessionId,
-    consent: () => {
-    },
-    identify: () => {
-    },
-    track: () => {
-    },
-    stop: () => {
-    },
-    flush: async () => {
-    }
-  };
-}
 export {
   ConfigError,
   DEFAULTS,
@@ -4242,6 +4263,7 @@ export {
   TRACK_TAG,
   Transport,
   createRecorder,
+  forgetVisitor,
   hashToUnitInterval,
   isSampledIn,
   resolveIdentity,