@active-reach/web-sdk 1.3.1 → 1.4.0

package/dist/{analytics-B0JfoAJs.mjs → analytics-D9BAnJAu.mjs}

@@ -1761,6 +1761,191 @@ class RateLimiter {
     this.firstDroppedName = null;
   }
 }
+const C1 = 3432918353;
+const C2 = 461845907;
+function murmurhash3_x86_32(input, seed = 0) {
+  const bytes = new TextEncoder().encode(input);
+  return murmurhash3_bytes(bytes, seed);
+}
+function murmurhash3_bytes(bytes, seed = 0) {
+  const len = bytes.length;
+  const nBlocks = Math.floor(len / 4);
+  let h1 = seed >>> 0;
+  for (let i = 0; i < nBlocks; i++) {
+    const offset = i * 4;
+    let k12 = bytes[offset] | bytes[offset + 1] << 8 | bytes[offset + 2] << 16 | bytes[offset + 3] << 24;
+    k12 = Math.imul(k12, C1);
+    k12 = k12 << 15 | k12 >>> 17;
+    k12 = Math.imul(k12, C2);
+    h1 ^= k12;
+    h1 = h1 << 13 | h1 >>> 19;
+    h1 = Math.imul(h1, 5) + 3864292196 >>> 0;
+  }
+  const tailStart = nBlocks * 4;
+  let k1 = 0;
+  const tailLen = len - tailStart;
+  if (tailLen === 3) k1 ^= bytes[tailStart + 2] << 16;
+  if (tailLen >= 2) k1 ^= bytes[tailStart + 1] << 8;
+  if (tailLen >= 1) {
+    k1 ^= bytes[tailStart];
+    k1 = Math.imul(k1, C1);
+    k1 = k1 << 15 | k1 >>> 17;
+    k1 = Math.imul(k1, C2);
+    h1 ^= k1;
+  }
+  h1 ^= len;
+  h1 ^= h1 >>> 16;
+  h1 = Math.imul(h1, 2246822507);
+  h1 ^= h1 >>> 13;
+  h1 = Math.imul(h1, 3266489909);
+  h1 ^= h1 >>> 16;
+  return h1 >>> 0;
+}
+function base64ToBytes(b64) {
+  if (typeof atob !== "undefined") {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+  const B = globalThis.Buffer;
+  if (B && typeof B.from === "function") {
+    const buf = B.from(b64, "base64");
+    return new Uint8Array(buf);
+  }
+  throw new Error("No base64 decoder available (neither atob nor Buffer)");
+}
+class BloomFilter {
+  constructor(buf, params) {
+    this.params = params;
+    if ((params.m & params.m - 1) !== 0) {
+      throw new Error(`Bloom filter m must be a power of 2, got ${params.m}`);
+    }
+    if (buf.length !== params.m >> 3) {
+      throw new Error(
+        `Bloom filter buffer size mismatch: expected ${params.m >> 3} bytes, got ${buf.length}`
+      );
+    }
+    this.buf = buf;
+    this.mask = params.m - 1;
+  }
+  /** Build from the wire format (base64 bytes + explicit params). */
+  static fromBase64(bloomB64, params) {
+    const bytes = base64ToBytes(bloomB64);
+    return new BloomFilter(bytes, params);
+  }
+  /**
+   * Returns true if `name` is probably in the set — possibly with the
+   * filter's configured false-positive rate. FALSE is always authoritative.
+   *
+   * FP here means: SDK thinks a name is already registered when it isn't.
+   * That costs one wasted server round-trip (gateway does the exact check
+   * and catches it) — strictly safer than a false-negative, which could
+   * leak a novel name past the SDK.
+   */
+  has(name) {
+    const h1 = murmurhash3_x86_32(name, this.params.seedA);
+    const h2 = murmurhash3_x86_32(name, this.params.seedB);
+    for (let i = 0; i < this.params.k; i++) {
+      const combined = h1 + Math.imul(i, h2) >>> 0;
+      const idx = combined & this.mask;
+      const bit = this.buf[idx >> 3] & 1 << (idx & 7);
+      if (bit === 0) return false;
+    }
+    return true;
+  }
+}
+const SUPPORTED_ALGO = "mmh3_x86_32_km";
+function warnOncePerSession(message) {
+  if (typeof console === "undefined" || typeof console.warn !== "function") return;
+  console.warn(message);
+}
+class NameGovernor {
+  constructor() {
+    this.bloom = null;
+    this.remainingNewNames = Infinity;
+    this.localNovelNames = /* @__PURE__ */ new Set();
+    this.droppedSinceLastReport = /* @__PURE__ */ new Map();
+    this.reportWindowStart = Date.now();
+    this.hasWarnedThisSession = false;
+  }
+  /**
+   * Ingest a freshly-bootstrapped hint. Call on every successful bootstrap.
+   * Passing `null` disables governance (fail-open).
+   */
+  ingestHint(hint) {
+    if (!hint || hint.bloom_algo !== SUPPORTED_ALGO) {
+      this.bloom = null;
+      this.remainingNewNames = Infinity;
+      this.localNovelNames.clear();
+      return;
+    }
+    try {
+      this.bloom = BloomFilter.fromBase64(hint.bloom_b64, {
+        m: hint.m,
+        k: hint.k,
+        seedA: hint.seed_a,
+        seedB: hint.seed_b
+      });
+    } catch {
+      this.bloom = null;
+    }
+    this.remainingNewNames = hint.remaining_new_names ?? Infinity;
+    this.localNovelNames.clear();
+  }
+  /**
+   * Decide whether a `track()` call should proceed.
+   *
+   * Returns true  = send to network (rate-limiter still runs after).
+   * Returns false = drop locally; caller should return early.
+   */
+  shouldSend(eventName) {
+    if (!this.bloom) return true;
+    if (this.bloom.has(eventName)) return true;
+    if (this.localNovelNames.has(eventName)) return true;
+    if (this.remainingNewNames > 0) {
+      this.localNovelNames.add(eventName);
+      this.remainingNewNames -= 1;
+      return true;
+    }
+    const prev = this.droppedSinceLastReport.get(eventName) ?? 0;
+    this.droppedSinceLastReport.set(eventName, prev + 1);
+    if (!this.hasWarnedThisSession) {
+      this.hasWarnedThisSession = true;
+      warnOncePerSession(
+        `[aegis] Event-name cap reached — "${eventName}" dropped locally. Upgrade your plan or remove dynamically-generated event names.`
+      );
+    }
+    return false;
+  }
+  /**
+   * Snapshot + reset the dropped-names counter. Called by the telemetry
+   * beacon on batch flush so the gateway gets visibility into client-side
+   * drops for ops dashboards.
+   */
+  drainDropReport() {
+    if (this.droppedSinceLastReport.size === 0) return null;
+    const events = {};
+    let total = 0;
+    for (const [name, count] of this.droppedSinceLastReport) {
+      events[name] = count;
+      total += count;
+    }
+    const since = this.reportWindowStart;
+    this.droppedSinceLastReport.clear();
+    this.reportWindowStart = Date.now();
+    return { events, total, since };
+  }
+  // Test-only accessors — not part of public API but easier than reflection.
+  /** @internal */
+  _debugState() {
+    return {
+      hasBloom: this.bloom !== null,
+      remaining: this.remainingNewNames,
+      localNovel: this.localNovelNames.size
+    };
+  }
+}
 class Aegis {
   constructor() {
     this.config = null;
@@ -1772,6 +1957,7 @@ class Aegis {
     this.consent = null;
     this._ecommerce = null;
     this.rateLimiter = null;
+    this.nameGovernor = new NameGovernor();
     this._lastPageUrl = null;
     this._popstateHandler = null;
     this._originalPushState = null;
@@ -2031,6 +2217,13 @@ class Aegis {
         }
       }
     }
+    if (event.type === "track") {
+      const trackEvent = event;
+      const isMetaEvent = typeof trackEvent.event === "string" && trackEvent.event.startsWith("aegis.client.");
+      if (!isMetaEvent && !this.nameGovernor.shouldSend(trackEvent.event)) {
+        return;
+      }
+    }
     if (this.rateLimiter) {
       const eventLabel = event.type === "track" && event.event ? event.event : event.type;
       const isMetaEvent = event.type === "track" && typeof event.event === "string" && event.event.startsWith("aegis.client.");
@@ -2038,6 +2231,21 @@ class Aegis {
         return;
       }
     }
+    const ctx = event.context;
+    const props = event.properties;
+    if ((ctx == null ? void 0 : ctx.campaign) && props && !props.campaign_id) {
+      const utm = ctx.campaign;
+      if (utm.campaign) props.campaign_id = utm.campaign;
+      if (utm.source) props.campaign_source = utm.source;
+      if (utm.medium) props.campaign_medium = utm.medium;
+      if (utm.content) props.campaign_content = utm.content;
+      if (utm.term) props.campaign_term = utm.term;
+    }
+    if ((ctx == null ? void 0 : ctx.adClickIDs) && props) {
+      const clicks = ctx.adClickIDs;
+      const clickId = clicks.gclid || clicks.fbclid || clicks.ctwa_clid || clicks.msclkid || clicks.ttclid;
+      if (clickId && !props.campaign_click_id) props.campaign_click_id = clickId;
+    }
     logger.debug("Capturing event:", event);
     const transformedEvent = await this.plugins.executeHookChain(
       "beforeEventCapture",
@@ -2081,8 +2289,59 @@ class Aegis {
     this.identity.reset();
     logger.info("User identity reset");
   }
+  /**
+   * Ingest the event-governance hint returned from `/v1/sdk/bootstrap`.
+   *
+   * Callers (Shopify pixel, snippet, react integration) run `bootstrap()`
+   * themselves and pass the resulting `eventGovernance` field here so the
+   * SDK can self-throttle novel event names before they hit the gateway.
+   *
+   * Passing null/undefined disables governance (Enterprise plan / outage
+   * fail-open). Safe to call before `init()` — the hint is stored and
+   * applied as soon as init completes.
+   */
+  ingestGovernanceHint(hint) {
+    this.nameGovernor.ingestHint(hint ?? null);
+    logger.debug("Governance hint ingested", hint ? {
+      k: hint.k,
+      m: hint.m,
+      remaining: hint.remaining_new_names
+    } : "disabled");
+  }
+  /**
+   * Drain the client-side drop counter and emit a meta-event. Called
+   * periodically by the queue flush path so ops dashboards see novel-name
+   * amplification patterns in near-real-time.
+   */
+  emitGovernanceDropMeta() {
+    var _a, _b;
+    if (!((_a = this.config) == null ? void 0 : _a.initialized) || !this.session || !this.identity) return;
+    const report = this.nameGovernor.drainDropReport();
+    if (!report) return;
+    const event = {
+      type: "track",
+      event: "aegis.client.name_governor_dropped",
+      properties: {
+        dropped_count: report.total,
+        distinct_names: Object.keys(report.events).length,
+        // Cap the payload — a runaway loop could produce thousands of names;
+        // we ship the top 10 for diagnostics and the total for counting.
+        sample_names: Object.entries(report.events).sort((a, b) => b[1] - a[1]).slice(0, 10).map(([name, count]) => ({ name, count })),
+        window_start: report.since,
+        window_end: Date.now()
+      },
+      messageId: generateMessageId(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      anonymousId: this.identity.getAnonymousId(),
+      userId: this.identity.getUserId() || void 0,
+      sessionId: this.session.getSessionId(),
+      context: buildContext(this.config, this.session)
+    };
+    (_b = this.queue) == null ? void 0 : _b.push(event);
+  }
   async flush() {
     if (!this.assertInitialized()) return;
+    this.emitGovernanceDropMeta();
     await this.queue.flush();
   }
   getAnonymousId() {
@@ -2214,8 +2473,11 @@ class Aegis {
 }
 export {
   Aegis as A,
+  BloomFilter as B,
   EcommerceTracker as E,
+  NameGovernor as N,
   RateLimiter as R,
-  logger as l
+  logger as l,
+  murmurhash3_x86_32 as m
 };
-//# sourceMappingURL=analytics-B0JfoAJs.mjs.map
+//# sourceMappingURL=analytics-D9BAnJAu.mjs.map