@qoretechnologies/reqraft 0.10.56 → 0.10.57-pr.127.g0a792ea

package/src/tracking/core/queue.ts

@@ -0,0 +1,131 @@
+import type { IBatch, ITrackedEvent } from './types';
+
+/**
+ * How a batch leaves the page. `beacon` is used when the page is going away
+ * (`pagehide`, tab hidden): the browser delivers it after the page is gone.
+ * Resolves to `true` when the batch was handed over, `false` to keep it for later
+ * (network error), and never rejects.
+ */
+export interface ITransport {
+  send(body: string, mode: 'fetch' | 'beacon'): Promise<boolean>;
+}
+
+/** Collector limits (§4): at most 100 events and 64 KB per batch. We stay under both. */
+export const MAX_EVENTS_PER_BATCH = 100;
+export const MAX_BATCH_BYTES = 60 * 1024;
+/** Events kept while the collector is unreachable; the oldest are dropped past this. */
+export const MAX_BACKLOG = 500;
+
+export interface IQueueOptions {
+  flushIntervalMs: number;
+  maxQueued: number;
+  transport: ITransport;
+  /** The envelope for a batch; null → nothing may be sent (no consent) and the queue is dropped. */
+  envelope: () => Omit<IBatch, 'events' | 'sent_at'> | null;
+  now: () => number;
+  /** Timers are injected so tests can drive them. */
+  setTimer: (fn: () => void, ms: number) => unknown;
+  clearTimer: (handle: unknown) => void;
+  debug?: (batch: IBatch) => void;
+}
+
+const size = (s: string) => (typeof TextEncoder !== 'undefined' ? new TextEncoder().encode(s).length : s.length * 2);
+
+/**
+ * Batches events: sends every `flushIntervalMs`, as soon as `maxQueued` are waiting,
+ * and immediately (as a beacon) when the page is going away.
+ */
+export class EventQueue {
+  private events: ITrackedEvent[] = [];
+  private timer: unknown = null;
+  private sending = false;
+
+  constructor(private readonly o: IQueueOptions) {}
+
+  get length() {
+    return this.events.length;
+  }
+
+  push(event: ITrackedEvent) {
+    this.events.push(event);
+    if (this.events.length > MAX_BACKLOG) this.events.splice(0, this.events.length - MAX_BACKLOG);
+    if (this.events.length >= this.o.maxQueued) void this.flush('fetch');
+    else this.schedule();
+  }
+
+  /** Forget everything unsent (consent withdrawn). */
+  clear() {
+    this.events = [];
+    if (this.timer != null) this.o.clearTimer(this.timer);
+    this.timer = null;
+  }
+
+  private schedule() {
+    if (this.timer != null) return;
+    this.timer = this.o.setTimer(() => {
+      this.timer = null;
+      void this.flush('fetch');
+    }, this.o.flushIntervalMs);
+  }
+
+  /** Splits `events` into batches that fit the collector's limits. */
+  static chunk(events: ITrackedEvent[], envelope: Omit<IBatch, 'events' | 'sent_at'>, sentAt: string): IBatch[] {
+    const batches: IBatch[] = [];
+    let current: ITrackedEvent[] = [];
+    const bodyOf = (evts: ITrackedEvent[]) => JSON.stringify({ ...envelope, sent_at: sentAt, events: evts });
+    for (const e of events) {
+      const next = [...current, e];
+      if (current.length && (next.length > MAX_EVENTS_PER_BATCH || size(bodyOf(next)) > MAX_BATCH_BYTES)) {
+        batches.push({ ...envelope, sent_at: sentAt, events: current });
+        current = [e];
+      } else {
+        current = next;
+      }
+    }
+    if (current.length) batches.push({ ...envelope, sent_at: sentAt, events: current });
+    // A single event larger than the limit is dropped rather than rejected forever.
+    return batches.filter((b) => b.events.length > 1 || size(JSON.stringify(b)) <= MAX_BATCH_BYTES);
+  }
+
+  async flush(mode: 'fetch' | 'beacon' = 'fetch'): Promise<void> {
+    if (this.timer != null) {
+      this.o.clearTimer(this.timer);
+      this.timer = null;
+    }
+    if (!this.events.length) return;
+    // A fetch in flight owns the queue; a beacon (page going away) sends what is left now.
+    if (this.sending && mode === 'fetch') {
+      this.schedule();
+      return;
+    }
+    const envelope = this.o.envelope();
+    if (!envelope) {
+      this.events = [];
+      return;
+    }
+    const pending = this.events;
+    this.events = [];
+    const batches = EventQueue.chunk(pending, envelope, new Date(this.o.now()).toISOString());
+    this.sending = true;
+    const failed: ITrackedEvent[] = [];
+    try {
+      for (const batch of batches) {
+        this.o.debug?.(batch);
+        let ok = false;
+        try {
+          ok = await this.o.transport.send(JSON.stringify(batch), mode);
+        } catch {
+          ok = false;
+        }
+        if (!ok) failed.push(...batch.events);
+      }
+    } finally {
+      this.sending = false;
+    }
+    if (failed.length) {
+      // Kept for the next flush, which the next event schedules (no retry loop against a
+      // collector that is down); event ids make a double delivery harmless.
+      this.events = [...failed, ...this.events].slice(-MAX_BACKLOG);
+    }
+  }
+}

package/src/tracking/core/sections.ts

@@ -0,0 +1,166 @@
+/**
+ * Attention per section, as plain arithmetic over time (no DOM): the browser layer
+ * feeds it visibility changes from an IntersectionObserver and tab visibility, and
+ * asks it for the page summary.
+ *
+ * - `visible_ms`: time any part of the section was on screen while the tab was visible.
+ * - `seen`: the section was at least 50% visible for at least 1 s in one stretch — the
+ *   attention definition the contract uses everywhere (§4). "50% visible" is 50% of
+ *   the section *or* 50% of the viewport covered by it: a section taller than two
+ *   screens can never show half of itself, and it would otherwise never count.
+ * - `first_seen_ms`: when that stretch began, measured from the start of the page view.
+ */
+
+export const SEEN_RATIO = 0.5;
+export const SEEN_MS = 1000;
+
+export interface ISectionSummary {
+  id: string;
+  visible_ms: number;
+  seen: boolean;
+  first_seen_ms: number | null;
+}
+
+interface ISectionState {
+  id: string;
+  /** Effective visibility 0..1 (see above). */
+  ratio: number;
+  visibleMs: number;
+  visibleSince: number | null;
+  halfSince: number | null;
+  seenAt: number | null;
+  firstSeenMs: number | null;
+  /** Reported in the page summary (false for synthetic experiment triggers). */
+  report: boolean;
+}
+
+export class SectionClock {
+  private sections = new Map<string, ISectionState>();
+  private tabVisible = true;
+  private seenListeners = new Set<(id: string) => void>();
+
+  constructor(private start: number) {}
+
+  /** A new page view: everything starts from zero at `now`. */
+  reset(now: number) {
+    this.start = now;
+    const ids = Array.from(this.sections.values()).map((s) => [s.id, s.report] as const);
+    this.sections.clear();
+    ids.forEach(([id, report]) => this.ensure(id, report));
+  }
+
+  onSeen(listener: (id: string) => void) {
+    this.seenListeners.add(listener);
+    return () => void this.seenListeners.delete(listener);
+  }
+
+  isSeen = (id: string) => this.sections.get(id)?.seenAt != null;
+
+  private ensure(id: string, report = true): ISectionState {
+    let s = this.sections.get(id);
+    if (!s) {
+      s = { id, ratio: 0, visibleMs: 0, visibleSince: null, halfSince: null, seenAt: null, firstSeenMs: null, report };
+      this.sections.set(id, s);
+    }
+    return s;
+  }
+
+  /** Registers a section so it shows up in the summary even if it is never on screen. */
+  register(id: string, report = true) {
+    this.ensure(id, report).report ||= report;
+  }
+
+  /** The section's effective visibility changed. */
+  update(id: string, ratio: number, now: number) {
+    const s = this.ensure(id);
+    if (this.tabVisible) {
+      const wasVisible = s.ratio > 0;
+      const isVisible = ratio > 0;
+      if (wasVisible && !isVisible && s.visibleSince != null) {
+        s.visibleMs += Math.max(0, now - s.visibleSince);
+        s.visibleSince = null;
+      }
+      if (!wasVisible && isVisible) s.visibleSince = now;
+      // A stretch at >= 50% continues through ratio changes above the line.
+      const wasHalf = s.ratio >= SEEN_RATIO;
+      const isHalf = ratio >= SEEN_RATIO;
+      if (wasHalf && !isHalf) {
+        this.tickOne(s, now);
+        s.halfSince = null;
+      }
+      if (!wasHalf && isHalf) s.halfSince = now;
+    }
+    s.ratio = ratio;
+  }
+
+  /** The tab became visible or hidden: time stops counting while hidden. */
+  setTabVisible(visible: boolean, now: number) {
+    if (visible === this.tabVisible) return;
+    this.sections.forEach((s) => this.settle(s, now));
+    this.tabVisible = visible;
+    this.sections.forEach((s) => this.arm(s, now));
+  }
+
+  /** Promotes stretches that have lasted long enough to `seen`. Call ~every second. */
+  tick(now: number) {
+    this.sections.forEach((s) => this.tickOne(s, now));
+  }
+
+  /** Closes the open stretches up to `now` (visible time, seen). */
+  private settle(s: ISectionState, now: number) {
+    if (s.visibleSince != null) s.visibleMs += Math.max(0, now - s.visibleSince);
+    s.visibleSince = null;
+    this.tickOne(s, now);
+    s.halfSince = null;
+  }
+
+  private tickOne(s: ISectionState, now: number) {
+    if (s.seenAt == null && s.halfSince != null && now - s.halfSince >= SEEN_MS) {
+      s.seenAt = now;
+      s.firstSeenMs = Math.max(0, s.halfSince - this.start);
+      this.seenListeners.forEach((l) => l(s.id));
+    }
+  }
+
+  /** Opens stretches for the current state. */
+  private arm(s: ISectionState, now: number) {
+    if (!this.tabVisible) return;
+    if (s.ratio > 0) s.visibleSince = now;
+    if (s.ratio >= SEEN_RATIO) s.halfSince = now;
+  }
+
+  /** The section most on screen now (ties: the lower one on the page, i.e. the later registered). */
+  current(): string | null {
+    let best: ISectionState | null = null;
+    for (const s of Array.from(this.sections.values())) {
+      if (s.report && s.ratio > 0 && (!best || s.ratio >= best.ratio)) best = s;
+    }
+    return best?.id ?? null;
+  }
+
+  summary(now: number): ISectionSummary[] {
+    this.tick(now);
+    return Array.from(this.sections.values())
+      .filter((s) => s.report)
+      .map((s) => ({
+        id: s.id,
+        visible_ms: Math.round(s.visibleMs + (s.visibleSince != null ? Math.max(0, now - s.visibleSince) : 0)),
+        seen: s.seenAt != null,
+        first_seen_ms: s.firstSeenMs,
+      }));
+  }
+}
+
+/**
+ * Effective visibility from an IntersectionObserver entry: the larger of the share
+ * of the section on screen and the share of the viewport the section fills.
+ */
+export const effectiveRatio = (
+  intersectionRatio: number,
+  intersectionHeight: number,
+  viewportHeight: number,
+): number => {
+  if (intersectionRatio <= 0) return 0;
+  const cover = viewportHeight > 0 ? intersectionHeight / viewportHeight : 0;
+  return Math.min(1, Math.max(intersectionRatio, cover));
+};

package/src/tracking/core/storage.ts

@@ -0,0 +1,69 @@
+/**
+ * Storage that never throws: private windows, blocked site data and sandboxed
+ * iframes make `localStorage` throw on access. The tracker then keeps its state in
+ * memory for the page's lifetime and the site behaves exactly as without consent.
+ */
+export interface IStorage {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+}
+
+export const memoryStorage = (): IStorage => {
+  const data = new Map<string, string>();
+  return {
+    get: (k) => data.get(k) ?? null,
+    set: (k, v) => void data.set(k, v),
+    remove: (k) => void data.delete(k),
+  };
+};
+
+export const safeStorage = (pick: () => Storage | undefined): IStorage => {
+  const fallback = memoryStorage();
+  const store = (): Storage | undefined => {
+    try {
+      return pick();
+    } catch {
+      return undefined;
+    }
+  };
+  return {
+    get: (k) => {
+      try {
+        const s = store();
+        return s ? s.getItem(k) : fallback.get(k);
+      } catch {
+        return fallback.get(k);
+      }
+    },
+    set: (k, v) => {
+      try {
+        const s = store();
+        if (s) s.setItem(k, v);
+        else fallback.set(k, v);
+      } catch {
+        fallback.set(k, v);
+      }
+    },
+    remove: (k) => {
+      fallback.remove(k);
+      try {
+        store()?.removeItem(k);
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+};
+
+export const readJson = <T>(storage: IStorage, key: string): T | null => {
+  const raw = storage.get(key);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+};
+
+export const writeJson = (storage: IStorage, key: string, value: unknown) => storage.set(key, JSON.stringify(value));