@brunyee-studio/onus-sdk 0.1.0 → 1.0.0

package/dist/{replay-D7ejwI0s.d.ts → replay-BElhLiw8.d.ts}

@@ -1,5 +1,5 @@
 /**
- * DSN parsing for @onus/sdk (ONUS-68).
+ * DSN parsing for @brunyee-studio/onus-sdk (ONUS-68).
  *
  * Mirrors `src/lib/ingest/dsn.ts` semantics (the server side of the same
  * protocol): `{PROTOCOL}://{PUBLIC_KEY}@{HOST}/{NUMERIC_PROJECT_ID}` with no
@@ -26,7 +26,34 @@ declare function parseDsn(raw: string | undefined | null): ParsedDsn | null;
 declare function buildSentryAuthHeader(dsn: ParsedDsn, clientVersion: string): string;
 
 /**
- * Sentry-compatible envelope building for @onus/sdk (ONUS-68).
+ * Replay privacy resolution (capture-safety spec): rrweb's own defaults only
+ * mask password inputs, so the SDK forces safer defaults BEFORE serialization
+ * and lets integrators opt down deliberately through `ReplayPrivacyOptions`.
+ * Keys in PRIVACY_CONTROLLED_KEYS are stripped from a bare `recordOptions`
+ * passthrough so it can never defeat masking, un-reviewed pixel/iframe
+ * capture, replace the SDK's `emit` callback, or pre-pack events through
+ * rrweb `packFn`/`plugins` (which run BEFORE emit and could bypass the SDK's
+ * Meta href sanitization).
+ */
+interface ReplayPrivacyOptions {
+    /** Mask every input value (default true). Passwords are always masked. */
+    maskAllInputs?: boolean;
+    /** Selector whose text nodes are masked (default '*' — all text). */
+    maskTextSelector?: string;
+    /** Per-input-type mask map; `password: true` is forced. */
+    maskInputOptions?: Record<string, unknown>;
+    /** Custom masking transform for text nodes. */
+    maskTextFn?: (text: string) => string;
+    /** ADDITIVE extra block selectors appended to the built-in block list
+     * ('[data-onus-private]', 'input[type="hidden"]', 'input[type="radio"]',
+     * 'input[type="checkbox"]'); invalid extras are ignored. */
+    blockSelector?: string;
+    /** Elements to skip without blocking their subtree. */
+    ignoreSelector?: string;
+}
+
+/**
+ * Sentry-compatible envelope building for @brunyee-studio/onus-sdk (ONUS-68).
  *
  * Wire contract (`src/app/api/[projectId]/envelope/route.ts`):
  * - first line: JSON envelope header (event_id, sent_at, sdk)
@@ -73,13 +100,16 @@ interface ReplayOptions {
     environment?: string;
     release?: string;
     /**
-     * @onus/analytics session id (or getter) attached to each replay_event so
+     * @brunyee-studio/onus-analytics session id (or getter) attached to each replay_event so
      * the sessions surface can link playback (ONUS-155). A getter is evaluated
      * per segment flush so rotated session ids stay fresh.
      */
     sessionId?: string | (() => string | null | undefined);
-    /** rrweb record options (eventsPerSecond caps, etc.); kept passthrough. */
+    /** Non-privacy rrweb record tuning (sampling caps, etc.); privacy-controlled
+     * keys (masking, emit, packFn/plugins, canvas/iframe) are stripped. */
     recordOptions?: Record<string, unknown>;
+    /** Deliberate privacy opt-downs; safe defaults apply when omitted. */
+    privacy?: ReplayPrivacyOptions;
     /**
      * How long buffered rrweb events wait before flushing as one segment
      * envelope (ms, default 5000 — Sentry's segment cadence). Batching keeps a
@@ -91,6 +121,8 @@ interface ReplayOptions {
     /** Test seam: recorder + fetch injection (defaults to lazy rrweb import). */
     recorderFactory?: () => Promise<Recorder | null>;
     fetchImpl?: typeof fetch;
+    /** Internal guard: reject an auto-start invalidated during an async boundary. */
+    shouldProceed?: () => boolean;
 }
 /** Minimal structural subset of rrweb's record function used here. */
 interface Recorder {
@@ -101,26 +133,32 @@ interface Recorder {
      */
     wire?: (opts: unknown) => void;
 }
-interface ReplayState {
-    replayId: string;
-    stop: (() => void) | null;
-    /** Buffered rrweb events awaiting the next segment flush. */
-    buffer: unknown[];
-    /** Pending interval flush (one envelope per flush, not per event). */
-    timer: ReturnType<typeof setTimeout> | null;
-}
+/** rrweb Meta events (type 4) carry the page href; strip query, fragment, and
+ * credentials before recording. */
+declare function stripUrlQueryAndFragment(raw: string): string;
+/** One recorded rrweb event as delivered by the recorder's emit callback. */
+type RecordedEvent = Record<string, unknown>;
+/** Minimize recorded URL metadata before buffering (Meta href only). */
+declare function sanitizeRecordedEvent(event: unknown): RecordedEvent;
 /**
  * Start session replay. No-op (returns null) when replay is already running,
  * the DSN is invalid, the recorder factory fails, or rrweb cannot be loaded.
  */
 declare function startSessionReplay(options?: ReplayOptions): Promise<string | null>;
+/** Internal SDK auto-start seam; direct host calls use startSessionReplay instead. */
+declare function startAutoSessionReplay(options: ReplayOptions, generation: number): Promise<string | null>;
 /** Stop replay. No-op when not running. Flushes any buffered tail. */
 declare function stopSessionReplay(): void;
+/** Hard revoke on denial: also abort all retained stopped-session tails. */
+declare function revokeActiveReplay(): void;
 /** Currently active replay id (null when off). */
 declare function activeReplayId(): string | null;
 /** Test seam. */
 declare function resetReplayForTest(): void;
 /** Build + send one segment envelope (replay_event + replay_recording pair). */
-declare function emitSegment(dsn: NonNullable<ReturnType<typeof parseDsn>>, options: ReplayOptions, state: ReplayState, event: unknown, segmentId: number, timestamp: string): Promise<boolean>;
+declare function emitSegment(dsn: NonNullable<ReturnType<typeof parseDsn>>, options: ReplayOptions, state: {
+    replayId: string;
+    abort: AbortController | null;
+}, event: unknown, segmentId: number, timestamp: string): Promise<boolean>;
 
-export { type EnvelopeItem as E, MAX_ENVELOPE_BYTES as M, type ParsedDsn as P, type Recorder as R, REPLAY_ID_RE as a, buildEnvelope as b, buildSentryAuthHeader as c, type ReplayOptions as d, eventId as e, activeReplayId as f, emitSegment as g, stopSessionReplay as h, parseDsn as p, resetReplayForTest as r, startSessionReplay as s };
+export { type EnvelopeItem as E, MAX_ENVELOPE_BYTES as M, type ParsedDsn as P, type ReplayPrivacyOptions as R, type Recorder as a, REPLAY_ID_RE as b, buildEnvelope as c, buildSentryAuthHeader as d, eventId as e, type RecordedEvent as f, type ReplayOptions as g, activeReplayId as h, emitSegment as i, revokeActiveReplay as j, startAutoSessionReplay as k, startSessionReplay as l, stopSessionReplay as m, stripUrlQueryAndFragment as n, parseDsn as p, resetReplayForTest as r, sanitizeRecordedEvent as s };

package/dist/replay.d.ts

@@ -1 +1 @@
-export { a as REPLAY_ID_RE, R as Recorder, d as ReplayOptions, f as activeReplayId, g as emitSegment, p as parseDsn, r as resetReplayForTest, s as startSessionReplay, h as stopSessionReplay } from './replay-D7ejwI0s.js';
+export { b as REPLAY_ID_RE, f as RecordedEvent, a as Recorder, g as ReplayOptions, h as activeReplayId, i as emitSegment, p as parseDsn, r as resetReplayForTest, j as revokeActiveReplay, s as sanitizeRecordedEvent, k as startAutoSessionReplay, l as startSessionReplay, m as stopSessionReplay, n as stripUrlQueryAndFragment } from './replay-BElhLiw8.js';

package/dist/replay.js

@@ -3,30 +3,168 @@ import {
   SDK_NAME,
   buildEnvelope,
   eventId,
+  getActiveReplayId,
+  isReplayCaptureAllowed,
   parseDsn,
-  sendEnvelope
-} from "./chunk-SLWBPQ6C.js";
+  registerReplayStop,
+  registerStaleAutoReplayRelease,
+  resetCaptureGateForTest,
+  sendEnvelope,
+  setActiveReplayId
+} from "./chunk-YPQXIZ4X.js";
+
+// src/replay-privacy.ts
+var PRIVACY_CONTROLLED_KEYS = /* @__PURE__ */ new Set([
+  "emit",
+  "maskAllInputs",
+  "maskTextSelector",
+  "maskTextClass",
+  "maskInputOptions",
+  "maskInputFn",
+  "maskTextFn",
+  "blockSelector",
+  "blockClass",
+  "ignoreClass",
+  "ignoreSelector",
+  // rrweb runs packers/plugins BEFORE the emit callback, so an allowed
+  // passthrough could serialize events that never pass through the SDK's
+  // Meta href sanitization. They are SDK-controlled, never passthrough.
+  "packFn",
+  "plugins",
+  "recordCanvas",
+  "recordCrossOriginIframes",
+  "inlineImages"
+]);
+var PRIVACY_DEFAULTS = {
+  maskAllInputs: true,
+  maskTextSelector: "*",
+  blockSelector: '[data-onus-private], input[type="hidden"], input[type="radio"], input[type="checkbox"]'
+};
+function isValidCssSelector(raw) {
+  if (typeof document === "undefined") return false;
+  try {
+    document.querySelector(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validSelectorExtra(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) return "";
+  return isValidCssSelector(raw) ? raw : "";
+}
+function maskTextSelectorOrFallback(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) return PRIVACY_DEFAULTS.maskTextSelector;
+  return isValidCssSelector(raw) ? raw : PRIVACY_DEFAULTS.maskTextSelector;
+}
+function blockSelectorWithExtra(extra) {
+  const extra_ = validSelectorExtra(extra);
+  return extra_ ? `${PRIVACY_DEFAULTS.blockSelector}, ${extra_}` : PRIVACY_DEFAULTS.blockSelector;
+}
+function resolveRecordPrivacy(recordOptions, privacy) {
+  const passthrough = {};
+  for (const [key, value] of Object.entries(recordOptions ?? {})) {
+    if (!PRIVACY_CONTROLLED_KEYS.has(key)) passthrough[key] = value;
+  }
+  const effective = {
+    ...passthrough,
+    maskAllInputs: privacy?.maskAllInputs ?? PRIVACY_DEFAULTS.maskAllInputs,
+    maskTextSelector: maskTextSelectorOrFallback(privacy?.maskTextSelector),
+    blockSelector: blockSelectorWithExtra(privacy?.blockSelector),
+    recordCanvas: false,
+    recordCrossOriginIframes: false,
+    inlineImages: false,
+    // Password masking is non-negotiable, regardless of opt-downs above.
+    maskInputOptions: {
+      ...privacy?.maskInputOptions ?? {},
+      password: true
+    }
+  };
+  if (privacy?.maskTextFn) effective["maskTextFn"] = privacy.maskTextFn;
+  if (privacy?.ignoreSelector) effective["ignoreSelector"] = privacy.ignoreSelector;
+  return effective;
+}
 
 // src/replay.ts
+function stripUrlQueryAndFragment(raw) {
+  try {
+    const url = new URL(raw);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  } catch {
+    const noHash = raw.split("#")[0] ?? raw;
+    return noHash.split("?")[0] ?? noHash;
+  }
+}
+function sanitizeRecordedEvent(event) {
+  const candidate = event;
+  if (!candidate || typeof candidate !== "object" || candidate.type !== 4 || !candidate.data || typeof candidate.data !== "object") {
+    return event;
+  }
+  const data = { ...candidate.data };
+  if (typeof data["href"] === "string") data["href"] = stripUrlQueryAndFragment(data["href"]);
+  return { ...candidate, data };
+}
 var active = null;
-async function startSessionReplay(options = {}) {
+var pendingTails = /* @__PURE__ */ new Set();
+var MAX_PENDING_TAILS = 8;
+function retainPendingTail(state) {
+  pendingTails.add(state);
+  if (pendingTails.size <= MAX_PENDING_TAILS) return;
+  const oldest = pendingTails.values().next().value;
+  if (!oldest) return;
+  pendingTails.delete(oldest);
+  oldest.abort?.abort();
+  oldest.buffer.length = 0;
+}
+function clearFailedClaim(state) {
+  if (active === state) active = null;
+  if (getActiveReplayId() === state.replayId) setActiveReplayId(null);
+}
+function releaseStaleAutoReplay(generation) {
+  if (active?.origin.kind === "auto" && active.origin.generation !== generation) {
+    dropActiveReplay();
+  }
+}
+function startSessionReplay(options = {}) {
+  return startRecording(options, { kind: "manual" });
+}
+function startAutoSessionReplay(options, generation) {
+  return startRecording(options, { kind: "auto", generation });
+}
+async function startRecording(options, origin) {
+  if (!isReplayCaptureAllowed() || options.shouldProceed?.() === false) return null;
+  registerStaleAutoReplayRelease(releaseStaleAutoReplay);
   if (active) return active.replayId;
   const dsn = parseDsn(options.dsn);
   if (!dsn) return null;
   const replayId = eventId().replace(/-/g, "");
-  const state = { replayId, stop: null, buffer: [], timer: null };
+  const state = {
+    replayId,
+    origin,
+    stop: null,
+    rawStop: null,
+    abort: new AbortController(),
+    pendingSends: 0,
+    buffer: [],
+    timer: null
+  };
   active = state;
+  registerReplayStop(revokeActiveReplay);
   let record = null;
   if (options.recorderFactory) {
     let recorder;
     try {
       recorder = await options.recorderFactory();
     } catch {
-      active = null;
+      clearFailedClaim(state);
       return null;
     }
     if (!recorder) {
-      active = null;
+      clearFailedClaim(state);
       return null;
     }
     record = (_opts) => {
@@ -38,15 +176,19 @@ async function startSessionReplay(options = {}) {
       const mod = await import("rrweb");
       const fn = mod.record;
       if (typeof fn !== "function") {
-        active = null;
+        clearFailedClaim(state);
         return null;
       }
       record = fn;
     } catch {
-      active = null;
+      clearFailedClaim(state);
       return null;
     }
   }
+  if (active !== state || !isReplayCaptureAllowed() || options.shouldProceed?.() === false) {
+    clearFailedClaim(state);
+    return null;
+  }
   const segmentIntervalMs = options.segmentIntervalMs ?? 5e3;
   const maxEventsPerSegment = options.maxEventsPerSegment ?? 100;
   const narrowedDsn = dsn;
@@ -55,21 +197,36 @@ async function startSessionReplay(options = {}) {
       clearTimeout(state.timer);
       state.timer = null;
     }
+    if (state.abort?.signal.aborted || options.shouldProceed?.() === false) {
+      state.buffer.length = 0;
+      return;
+    }
     if (state.buffer.length === 0) return;
     const events = state.buffer;
     state.buffer = [];
-    await emitSegment(
-      narrowedDsn,
-      options,
-      state,
-      events,
-      ++segmentCounter,
-      (/* @__PURE__ */ new Date()).toISOString()
-    );
+    state.pendingSends++;
+    try {
+      await emitSegment(
+        narrowedDsn,
+        options,
+        state,
+        events,
+        ++segmentCounter,
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+    } finally {
+      state.pendingSends--;
+      if (state.pendingSends === 0 && active !== state) pendingTails.delete(state);
+    }
   }
+  const effectiveRecordOptions = resolveRecordPrivacy(options.recordOptions, options.privacy);
   const stop = record({
+    ...effectiveRecordOptions,
     emit: (event) => {
-      state.buffer.push(event);
+      if (active !== state || !isReplayCaptureAllowed() || options.shouldProceed?.() === false) {
+        return;
+      }
+      state.buffer.push(sanitizeRecordedEvent(event));
       if (state.buffer.length >= maxEventsPerSegment) {
         void flushBuffer();
         return;
@@ -80,9 +237,16 @@ async function startSessionReplay(options = {}) {
           void flushBuffer();
         }, segmentIntervalMs);
       }
-    },
-    ...options.recordOptions
+    }
   });
+  if (active !== state || !isReplayCaptureAllowed() || options.shouldProceed?.() === false) {
+    stop?.();
+    state.abort?.abort();
+    state.buffer.length = 0;
+    clearFailedClaim(state);
+    return null;
+  }
+  state.rawStop = typeof stop === "function" ? stop : null;
   state.stop = typeof stop === "function" ? () => {
     stop();
     void flushBuffer();
@@ -103,19 +267,48 @@ function stopSessionReplay() {
   const stopping = active;
   active = null;
   if (!stopping) return;
+  retainPendingTail(stopping);
   stopping.stop?.();
   if (stopping.timer !== null) {
     clearTimeout(stopping.timer);
     stopping.timer = null;
   }
   stopping.buffer.length = 0;
+  stopping.rawStop = null;
+  if (stopping.pendingSends === 0) pendingTails.delete(stopping);
+  setActiveReplayId(null);
+}
+function dropActiveReplay() {
+  const stopping = active;
+  active = null;
+  if (!stopping) return;
+  try {
+    stopping.rawStop?.();
+  } catch {
+  }
+  if (stopping.timer !== null) {
+    clearTimeout(stopping.timer);
+    stopping.timer = null;
+  }
+  stopping.abort?.abort();
+  stopping.buffer.length = 0;
+  setActiveReplayId(null);
+}
+function revokeActiveReplay() {
+  dropActiveReplay();
+  for (const tail of pendingTails) {
+    tail.abort?.abort();
+    tail.buffer.length = 0;
+  }
+  pendingTails.clear();
+  setActiveReplayId(null);
 }
 function activeReplayId() {
   return active?.replayId ?? null;
 }
 function resetReplayForTest() {
-  active?.stop?.();
-  active = null;
+  revokeActiveReplay();
+  resetCaptureGateForTest();
   segmentCounter = 0;
 }
 function resolveSessionId(options) {
@@ -159,7 +352,8 @@ ${JSON.stringify(event ?? [])}`;
     url: dsn.envelopeUrl,
     authHeader: `Sentry sentry_key=${dsn.key}, sentry_version=7, sentry_client=onus.javascript/0.1.0`,
     body: serialized,
-    fetchImpl: options.fetchImpl
+    fetchImpl: options.fetchImpl,
+    signal: state.abort?.signal
   });
   return result.ok;
 }
@@ -169,6 +363,10 @@ export {
   emitSegment,
   parseDsn,
   resetReplayForTest,
+  revokeActiveReplay,
+  sanitizeRecordedEvent,
+  startAutoSessionReplay,
   startSessionReplay,
-  stopSessionReplay
+  stopSessionReplay,
+  stripUrlQueryAndFragment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunyee-studio/onus-sdk",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Official Onus browser SDK: errors, session replay, and custom events via the Sentry-compatible envelope protocol",
   "license": "MIT",
   "author": "Brunyee Studio",