@usero/sdk 0.3.1 → 0.3.4

package/dist/plugins/session-replay.d.cts

@@ -19,6 +19,8 @@ interface FeedbackSubmission {
     screenshots?: ScreenshotData[];
     metadata?: Record<string, unknown>;
     replayEvents?: string;
+    sessionReplayId?: string;
+    replayOffsetMs?: number;
 }
 
 interface PluginLogger {
@@ -48,7 +50,6 @@ interface ReplaySampling {
     input?: number | 'last';
 }
 interface SessionReplayOptions {
-    bufferSeconds?: number;
     startAfterMs?: number;
     sampleRate?: number;
     sampling?: ReplaySampling;
@@ -56,20 +57,41 @@ interface SessionReplayOptions {
     maskTextSelector?: string;
     inlineStylesheet?: boolean;
     blockSelector?: string;
+    chunkSeconds?: number;
+    chunkMaxEvents?: number;
+    chunkMaxAttempts?: number;
+    apiUrl?: string;
 }
-interface RrwebEvent {
-    type: number;
-    data: unknown;
-    timestamp: number;
-}
-declare function evictOldEvents(events: RrwebEvent[], bufferSeconds: number, now: number): void;
 declare function uint8ToBase64(bytes: Uint8Array): string;
-declare function gzipString(input: string): Promise<string>;
+declare function gzipBytes(input: string): Promise<Uint8Array>;
+declare function mintSdkSessionId(): string;
+declare function joinUrl(apiUrl: string, path: string): string;
+interface CreateSessionResult {
+    accepted: boolean;
+    sessionReplayId?: string;
+    dropReason?: string;
+}
+declare function createSession(apiUrl: string, clientId: string, sdkSessionId: string): Promise<CreateSessionResult | null>;
+interface ChunkUploadResult {
+    ok: boolean;
+    stopSession: boolean;
+}
+declare function uploadChunk(apiUrl: string, sessionReplayId: string, clientId: string, seq: number, bytes: Uint8Array, eventCount: number, durationMs: number, logger: PluginContext['logger'], maxAttempts: number): Promise<ChunkUploadResult>;
+interface CurrentSessionHandle {
+    id: string;
+    offsetMs: number;
+}
 declare function sessionReplay(options?: SessionReplayOptions): UseroPlugin;
+declare function getCurrentSession(ctx: PluginContext): CurrentSessionHandle | null;
 declare const __test__: {
-    evictOldEvents: typeof evictOldEvents;
-    gzipString: typeof gzipString;
     uint8ToBase64: typeof uint8ToBase64;
+    gzipBytes: typeof gzipBytes;
+    mintSdkSessionId: typeof mintSdkSessionId;
+    uploadChunk: typeof uploadChunk;
+    createSession: typeof createSession;
+    joinUrl: typeof joinUrl;
+    HARD_CHUNK_BYTE_CAP: number;
+    SDK_SESSION_STORAGE_KEY: string;
 };
 
-export { type ReplaySampling, type SessionReplayOptions, __test__, sessionReplay };
+export { type CurrentSessionHandle, type ReplaySampling, type SessionReplayOptions, __test__, getCurrentSession, sessionReplay };

package/dist/plugins/session-replay.d.ts

@@ -19,6 +19,8 @@ interface FeedbackSubmission {
     screenshots?: ScreenshotData[];
     metadata?: Record<string, unknown>;
     replayEvents?: string;
+    sessionReplayId?: string;
+    replayOffsetMs?: number;
 }
 
 interface PluginLogger {
@@ -48,7 +50,6 @@ interface ReplaySampling {
     input?: number | 'last';
 }
 interface SessionReplayOptions {
-    bufferSeconds?: number;
     startAfterMs?: number;
     sampleRate?: number;
     sampling?: ReplaySampling;
@@ -56,20 +57,41 @@ interface SessionReplayOptions {
     maskTextSelector?: string;
     inlineStylesheet?: boolean;
     blockSelector?: string;
+    chunkSeconds?: number;
+    chunkMaxEvents?: number;
+    chunkMaxAttempts?: number;
+    apiUrl?: string;
 }
-interface RrwebEvent {
-    type: number;
-    data: unknown;
-    timestamp: number;
-}
-declare function evictOldEvents(events: RrwebEvent[], bufferSeconds: number, now: number): void;
 declare function uint8ToBase64(bytes: Uint8Array): string;
-declare function gzipString(input: string): Promise<string>;
+declare function gzipBytes(input: string): Promise<Uint8Array>;
+declare function mintSdkSessionId(): string;
+declare function joinUrl(apiUrl: string, path: string): string;
+interface CreateSessionResult {
+    accepted: boolean;
+    sessionReplayId?: string;
+    dropReason?: string;
+}
+declare function createSession(apiUrl: string, clientId: string, sdkSessionId: string): Promise<CreateSessionResult | null>;
+interface ChunkUploadResult {
+    ok: boolean;
+    stopSession: boolean;
+}
+declare function uploadChunk(apiUrl: string, sessionReplayId: string, clientId: string, seq: number, bytes: Uint8Array, eventCount: number, durationMs: number, logger: PluginContext['logger'], maxAttempts: number): Promise<ChunkUploadResult>;
+interface CurrentSessionHandle {
+    id: string;
+    offsetMs: number;
+}
 declare function sessionReplay(options?: SessionReplayOptions): UseroPlugin;
+declare function getCurrentSession(ctx: PluginContext): CurrentSessionHandle | null;
 declare const __test__: {
-    evictOldEvents: typeof evictOldEvents;
-    gzipString: typeof gzipString;
     uint8ToBase64: typeof uint8ToBase64;
+    gzipBytes: typeof gzipBytes;
+    mintSdkSessionId: typeof mintSdkSessionId;
+    uploadChunk: typeof uploadChunk;
+    createSession: typeof createSession;
+    joinUrl: typeof joinUrl;
+    HARD_CHUNK_BYTE_CAP: number;
+    SDK_SESSION_STORAGE_KEY: string;
 };
 
-export { type ReplaySampling, type SessionReplayOptions, __test__, sessionReplay };
+export { type CurrentSessionHandle, type ReplaySampling, type SessionReplayOptions, __test__, getCurrentSession, sessionReplay };

package/dist/plugins/session-replay.js

@@ -1,41 +1,133 @@
 // src/plugins/session-replay.ts
-var DEFAULT_OPTIONS = {
-  bufferSeconds: 30,
+var DEFAULTS = {
   startAfterMs: 0,
   sampleRate: 1,
   sampling: { mousemove: 50, scroll: 100 },
   maskAllInputs: true,
   maskTextSelector: "[data-usero-mask]",
   inlineStylesheet: true,
-  blockSelector: "[data-usero-block]"
+  blockSelector: "[data-usero-block]",
+  chunkSeconds: 10,
+  chunkMaxEvents: 5e3,
+  chunkMaxAttempts: 5,
+  apiUrl: ""
 };
-function evictOldEvents(events, bufferSeconds, now) {
-  if (events.length === 0) return;
-  const cutoff = now - bufferSeconds * 1e3;
-  let dropCount = 0;
-  for (const e of events) {
-    if (e.timestamp >= cutoff) break;
-    dropCount++;
-  }
-  if (dropCount > 0) events.splice(0, dropCount);
-}
+var SDK_SESSION_STORAGE_KEY = "usero:session-replay:sdk-session-id";
+var HARD_CHUNK_BYTE_CAP = 4 * 1024 * 1024;
 function uint8ToBase64(bytes) {
   let binary = "";
   const chunkSize = 32768;
   for (let i = 0; i < bytes.length; i += chunkSize) {
-    const chunk = bytes.subarray(i, i + chunkSize);
-    binary += String.fromCharCode.apply(null, Array.from(chunk));
+    const slice = bytes.subarray(i, i + chunkSize);
+    binary += String.fromCharCode.apply(null, Array.from(slice));
   }
   return typeof btoa === "function" ? btoa(binary) : "";
 }
-async function gzipString(input) {
+async function gzipBytes(input) {
   if (typeof CompressionStream === "undefined") {
-    const bytes = new TextEncoder().encode(input);
-    return uint8ToBase64(bytes);
+    return new TextEncoder().encode(input);
   }
   const stream = new Blob([input]).stream().pipeThrough(new CompressionStream("gzip"));
-  const compressed = await new Response(stream).arrayBuffer();
-  return uint8ToBase64(new Uint8Array(compressed));
+  const buf = await new Response(stream).arrayBuffer();
+  return new Uint8Array(buf);
+}
+function generateRandomId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  let out = "";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function mintSdkSessionId() {
+  try {
+    const existing = window.sessionStorage?.getItem(SDK_SESSION_STORAGE_KEY);
+    if (existing && /^[a-z0-9-]{8,}$/i.test(existing)) return existing;
+  } catch {
+  }
+  const id = generateRandomId();
+  try {
+    window.sessionStorage?.setItem(SDK_SESSION_STORAGE_KEY, id);
+  } catch {
+  }
+  return id;
+}
+function joinUrl(apiUrl, path) {
+  return `${apiUrl.replace(/\/$/, "")}${path}`;
+}
+async function createSession(apiUrl, clientId, sdkSessionId) {
+  try {
+    const startUrl = typeof window !== "undefined" && window.location ? window.location.href : void 0;
+    const userAgent = typeof navigator !== "undefined" && navigator.userAgent ? navigator.userAgent : void 0;
+    const res = await fetch(joinUrl(apiUrl, "/api/replay-sessions"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        clientId,
+        sdkSessionId,
+        startUrl,
+        userAgent,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    if (typeof json.accepted !== "boolean") return null;
+    const result = { accepted: json.accepted };
+    if (typeof json.sessionReplayId === "string") result.sessionReplayId = json.sessionReplayId;
+    if (typeof json.dropReason === "string") result.dropReason = json.dropReason;
+    return result;
+  } catch {
+    return null;
+  }
+}
+async function uploadChunk(apiUrl, sessionReplayId, clientId, seq, bytes, eventCount, durationMs, logger, maxAttempts) {
+  const url = joinUrl(
+    apiUrl,
+    `/api/replay-sessions/${encodeURIComponent(sessionReplayId)}/chunks/${seq}`
+  );
+  let attempt = 0;
+  while (attempt < maxAttempts) {
+    try {
+      const buffer = bytes.buffer.slice(
+        bytes.byteOffset,
+        bytes.byteOffset + bytes.byteLength
+      );
+      const blob = new Blob([buffer], { type: "application/octet-stream" });
+      const res = await fetch(url, {
+        method: "PUT",
+        body: blob,
+        headers: {
+          "Content-Type": "application/octet-stream",
+          "X-Usero-Client-Id": clientId,
+          "X-Usero-Event-Count": String(eventCount),
+          "X-Usero-Duration-Ms": String(Math.max(0, Math.round(durationMs)))
+        }
+      });
+      if (res.ok) return { ok: true, stopSession: false };
+      if (res.status === 409) {
+        logger.warn(`chunk ${seq} rejected with 409, stopping session`);
+        return { ok: false, stopSession: true };
+      }
+      if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+        logger.error(`chunk ${seq} rejected with ${res.status}`);
+        return { ok: false, stopSession: false };
+      }
+    } catch (err) {
+      logger.warn(`chunk ${seq} attempt ${attempt + 1} failed`, err);
+    }
+    attempt += 1;
+    const backoff = Math.min(15e3, 500 * 2 ** attempt) + Math.floor(Math.random() * 250);
+    await new Promise((resolve) => setTimeout(resolve, backoff));
+  }
+  logger.error(`chunk ${seq} dropped after ${maxAttempts} attempts`);
+  return { ok: false, stopSession: false };
 }
 async function loadRrwebRecord() {
   try {
@@ -51,20 +143,95 @@ async function loadRrwebRecord() {
     return null;
   }
 }
+function scheduleChunkUpload(store, ctx) {
+  if (!store.sessionReplayId) return;
+  if (store.pendingEvents.length === 0) return;
+  const events = store.pendingEvents;
+  const eventCount = events.length;
+  const firstTs = store.pendingFirstTs ?? 0;
+  const lastTs = store.pendingLastTs ?? firstTs;
+  const durationMs = Math.max(0, lastTs - firstTs);
+  const seq = store.nextChunkSeq;
+  store.nextChunkSeq += 1;
+  store.pendingEvents = [];
+  store.pendingFirstTs = null;
+  store.pendingLastTs = null;
+  const sessionReplayId = store.sessionReplayId;
+  const apiUrl = store.options.apiUrl;
+  const clientId = store.clientId;
+  const maxAttempts = store.options.chunkMaxAttempts;
+  store.pendingUploads += 1;
+  store.uploadQueue = store.uploadQueue.then(async () => {
+    try {
+      if (store.cancelled) return;
+      const json = JSON.stringify(events);
+      const bytes = await gzipBytes(json);
+      if (bytes.byteLength > HARD_CHUNK_BYTE_CAP) {
+        ctx.logger.error(
+          `chunk ${seq} exceeds 4MB hard cap (${bytes.byteLength} bytes), dropping`
+        );
+        return;
+      }
+      const result = await uploadChunk(
+        apiUrl,
+        sessionReplayId,
+        clientId,
+        seq,
+        bytes,
+        eventCount,
+        durationMs,
+        ctx.logger,
+        maxAttempts
+      );
+      if (result.stopSession) {
+        store.stopped = true;
+        stopRrweb(store);
+      }
+    } catch (err) {
+      ctx.logger.error(`chunk ${seq} encode failed`, err);
+    } finally {
+      store.pendingUploads -= 1;
+    }
+  });
+}
+function flushPendingChunk(store, ctx) {
+  if (store.stopped || store.cancelled) return;
+  if (store.pendingEvents.length === 0) return;
+  scheduleChunkUpload(store, ctx);
+}
+function stopRrweb(store) {
+  if (store.stopRecording) {
+    try {
+      store.stopRecording();
+    } catch {
+    }
+    store.stopRecording = null;
+  }
+  if (store.chunkFlushTimer) {
+    clearInterval(store.chunkFlushTimer);
+    store.chunkFlushTimer = null;
+  }
+}
 function startRecording(store, ctx) {
-  if (store.cancelled || store.stopRecording || store.loadInProgress) return;
+  if (store.cancelled || store.stopped || store.stopRecording || store.loadInProgress) return;
   store.loadInProgress = true;
   void loadRrwebRecord().then((record) => {
     store.loadInProgress = false;
-    if (store.cancelled || !record) {
+    if (store.cancelled || store.stopped || !record) {
       if (!record) ctx.logger.warn("rrweb failed to load, replay disabled");
       return;
     }
     try {
       const stop = record({
         emit: (event) => {
-          store.events.push(event);
-          evictOldEvents(store.events, store.options.bufferSeconds, event.timestamp);
+          if (store.stopped || store.cancelled) return;
+          if (store.recordingStartedAt === null) store.recordingStartedAt = event.timestamp;
+          store.pendingEvents.push(event);
+          if (store.pendingFirstTs === null) store.pendingFirstTs = event.timestamp;
+          store.pendingLastTs = event.timestamp;
+          if (store.pendingEvents.length >= store.options.chunkMaxEvents) {
+            scheduleChunkUpload(store, ctx);
+          }
         },
         maskAllInputs: store.options.maskAllInputs,
         maskTextSelector: store.options.maskTextSelector || void 0,
@@ -73,45 +240,124 @@ function startRecording(store, ctx) {
         sampling: store.options.sampling
       });
       store.stopRecording = stop;
+      store.record = record;
+      scheduleShadowSnapshot(store, ctx);
+      store.chunkFlushTimer = setInterval(
+        () => flushPendingChunk(store, ctx),
+        store.options.chunkSeconds * 1e3
+      );
     } catch (err) {
       ctx.logger.error("rrweb record() threw", err);
     }
   });
 }
+function scheduleShadowSnapshot(store, ctx) {
+  if (store.cancelled || store.stopped || !store.record || !store.stopRecording) return;
+  const fn = store.record.takeFullSnapshot;
+  if (typeof fn !== "function") return;
+  try {
+    fn(true);
+  } catch (err) {
+    ctx.logger.warn("takeFullSnapshot threw", err);
+  }
+}
+function finalise(store, ctx, opts) {
+  if (!store.sessionReplayId) return;
+  if (store.pendingEvents.length > 0) flushPendingChunk(store, ctx);
+  const url = joinUrl(
+    store.options.apiUrl,
+    `/api/replay-sessions/${encodeURIComponent(store.sessionReplayId)}/finalise`
+  );
+  const body = JSON.stringify({ clientId: store.clientId, endedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  if (opts.useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+    try {
+      const blob = new Blob([body], { type: "application/json" });
+      navigator.sendBeacon(url, blob);
+      return;
+    } catch (err) {
+      ctx.logger.warn("finalise sendBeacon threw", err);
+    }
+  }
+  void fetch(url, {
+    method: "POST",
+    body,
+    headers: { "Content-Type": "application/json" },
+    keepalive: true
+  }).catch((err) => ctx.logger.warn("finalise fetch failed", err));
+}
 function sessionReplay(options = {}) {
   const merged = {
-    ...DEFAULT_OPTIONS,
+    ...DEFAULTS,
     ...options,
-    sampling: { ...DEFAULT_OPTIONS.sampling, ...options.sampling ?? {} }
+    sampling: { ...DEFAULTS.sampling, ...options.sampling ?? {} }
   };
   return {
     name: "session-replay",
     onInit(ctx) {
+      if (typeof window === "undefined") return;
       if (merged.sampleRate < 1 && Math.random() >= merged.sampleRate) {
         ctx.logger.debug("skipped by sampleRate");
         return;
       }
-      if (typeof window === "undefined") return;
+      const apiUrl = merged.apiUrl || ctx.baseUrl;
+      if (!apiUrl) {
+        ctx.logger.error("session-replay needs an apiUrl (via options or PluginContext)");
+        return;
+      }
+      const sdkSessionId = mintSdkSessionId();
       const store = {
-        events: [],
-        stopRecording: null,
+        options: { ...merged, apiUrl },
+        clientId: ctx.clientId,
+        sdkSessionId,
+        sessionReplayId: null,
+        recordingStartedAt: null,
+        pendingEvents: [],
+        pendingFirstTs: null,
+        pendingLastTs: null,
+        nextChunkSeq: 0,
+        uploadQueue: Promise.resolve(),
+        pendingUploads: 0,
+        chunkFlushTimer: null,
         startTimer: null,
         pageHideHandler: null,
+        shadowUpdateHandler: null,
+        record: null,
+        stopRecording: null,
         loadInProgress: false,
         cancelled: false,
-        options: merged
+        stopped: false
       };
       ctx.setStore(store);
-      const begin = () => {
-        if (store.startTimer) {
-          clearTimeout(store.startTimer);
-          store.startTimer = null;
+      const onShadowUpdate = () => scheduleShadowSnapshot(store, ctx);
+      store.shadowUpdateHandler = onShadowUpdate;
+      window.addEventListener("usero:shadow-update", onShadowUpdate);
+      const onPageHide = () => {
+        finalise(store, ctx, { useBeacon: true });
+        store.stopped = true;
+        stopRrweb(store);
+      };
+      store.pageHideHandler = onPageHide;
+      window.addEventListener("pagehide", onPageHide);
+      const begin = async () => {
+        if (store.cancelled) return;
+        const created = await createSession(apiUrl, ctx.clientId, sdkSessionId);
+        if (!created) {
+          ctx.logger.warn("session create failed, replay disabled");
+          store.stopped = true;
+          return;
         }
-        if (store.pageHideHandler) {
-          window.removeEventListener("pagehide", store.pageHideHandler);
-          window.removeEventListener("beforeunload", store.pageHideHandler);
-          store.pageHideHandler = null;
+        if (!created.accepted) {
+          ctx.logger.info(`session-replay declined: ${created.dropReason ?? "unknown"}`);
+          store.stopped = true;
+          return;
         }
+        if (!created.sessionReplayId) {
+          ctx.logger.error("server accepted but returned no sessionReplayId");
+          store.stopped = true;
+          return;
+        }
+        store.sessionReplayId = created.sessionReplayId;
+        store.recordingStartedAt = Date.now();
         startRecording(store, ctx);
       };
       if (merged.startAfterMs > 0) {
@@ -121,55 +367,65 @@ function sessionReplay(options = {}) {
             clearTimeout(store.startTimer);
             store.startTimer = null;
           }
-          if (store.pageHideHandler) {
-            window.removeEventListener("pagehide", store.pageHideHandler);
-            window.removeEventListener("beforeunload", store.pageHideHandler);
-            store.pageHideHandler = null;
-          }
         };
-        store.pageHideHandler = cancelOnExit;
         window.addEventListener("pagehide", cancelOnExit, { once: true });
         window.addEventListener("beforeunload", cancelOnExit, { once: true });
-        store.startTimer = setTimeout(begin, merged.startAfterMs);
+        store.startTimer = setTimeout(() => {
+          void begin();
+        }, merged.startAfterMs);
       } else {
-        begin();
+        void begin();
       }
     },
-    async onFeedbackSubmit(ctx) {
+    onFeedbackSubmit(ctx) {
       const store = ctx.getStore();
-      if (!store || store.cancelled || store.events.length === 0) return void 0;
-      const snapshot = store.events.slice();
-      try {
-        const json = JSON.stringify(snapshot);
-        const replayEvents = await gzipString(json);
-        return { replayEvents };
-      } catch (err) {
-        ctx.logger.error("failed to encode replay buffer", err);
-        return void 0;
-      }
+      if (!store || store.cancelled || store.stopped) return void 0;
+      if (!store.sessionReplayId) return void 0;
+      const offsetMs = store.recordingStartedAt !== null ? Math.max(0, Date.now() - store.recordingStartedAt) : 0;
+      return { sessionReplayId: store.sessionReplayId, replayOffsetMs: offsetMs };
     },
     onDestroy(ctx) {
       const store = ctx.getStore();
       if (!store) return;
       store.cancelled = true;
-      if (store.startTimer) clearTimeout(store.startTimer);
+      if (store.startTimer) {
+        clearTimeout(store.startTimer);
+        store.startTimer = null;
+      }
       if (store.pageHideHandler) {
         window.removeEventListener("pagehide", store.pageHideHandler);
-        window.removeEventListener("beforeunload", store.pageHideHandler);
+        store.pageHideHandler = null;
       }
-      if (store.stopRecording) {
-        try {
-          store.stopRecording();
-        } catch (err) {
-          ctx.logger.warn("rrweb stop threw", err);
-        }
+      if (store.shadowUpdateHandler) {
+        window.removeEventListener("usero:shadow-update", store.shadowUpdateHandler);
+        store.shadowUpdateHandler = null;
+      }
+      if (store.sessionReplayId && !store.stopped) {
+        finalise(store, ctx, { useBeacon: false });
       }
-      store.events.length = 0;
+      store.stopped = true;
+      stopRrweb(store);
+      store.pendingEvents.length = 0;
     }
   };
 }
-var __test__ = { evictOldEvents, gzipString, uint8ToBase64 };
+function getCurrentSession(ctx) {
+  const store = ctx.getStore();
+  if (!store || store.cancelled || store.stopped || !store.sessionReplayId) return null;
+  const offsetMs = store.recordingStartedAt !== null ? Math.max(0, Date.now() - store.recordingStartedAt) : 0;
+  return { id: store.sessionReplayId, offsetMs };
+}
+var __test__ = {
+  uint8ToBase64,
+  gzipBytes,
+  mintSdkSessionId,
+  uploadChunk,
+  createSession,
+  joinUrl,
+  HARD_CHUNK_BYTE_CAP,
+  SDK_SESSION_STORAGE_KEY
+};
 
-export { __test__, sessionReplay };
+export { __test__, getCurrentSession, sessionReplay };
 //# sourceMappingURL=session-replay.js.map
 //# sourceMappingURL=session-replay.js.map