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

package/dist/tracking/testing.js

@@ -0,0 +1,140 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMemoryTracker = void 0;
+var storage_1 = require("./core/storage");
+var tracker_1 = require("./core/tracker");
+var types_1 = require("./core/types");
+var createMemoryTracker = function (options) {
+    var _a, _b;
+    if (options === void 0) { options = {}; }
+    var clock = (_a = options.start) !== null && _a !== void 0 ? _a : Date.UTC(2026, 8, 29, 10, 0, 0);
+    var offline = false;
+    var timers = new Map();
+    var nextTimer = 1;
+    var local = (0, storage_1.memoryStorage)();
+    var session = (0, storage_1.memoryStorage)();
+    var config = (0, types_1.resolveConfig)(__assign({ property: 'test', endpoint: '/collect', experimentsEndpoint: '/experiments' }, options.config));
+    var keys = (0, types_1.storageKeys)(config.storagePrefix);
+    if (options.consent) {
+        local.set(keys.consent, options.consent);
+        local.set(keys.consentVersion, String(config.consentVersion));
+    }
+    if (options.vid)
+        local.set(keys.vid, options.vid);
+    Object.entries((_b = options.seed) !== null && _b !== void 0 ? _b : {}).forEach(function (_a) {
+        var k = _a[0], v = _a[1];
+        return local.set(k, v);
+    });
+    var page = __assign({ origin: 'https://example.com', path: '/', search: '', title: 'Example', referrer: '', lang: 'en-US', viewport: [1440, 900], device: 'desktop' }, options.page);
+    var sent = [];
+    var tracker = new tracker_1.Tracker(config, {
+        local: local,
+        session: session,
+        now: function () { return clock; },
+        setTimer: function (fn, ms) {
+            var id = nextTimer++;
+            timers.set(id, { at: clock + ms, fn: fn });
+            return id;
+        },
+        clearTimer: function (h) { return void timers.delete(h); },
+        page: function () { return page; },
+        transport: {
+            send: function (body, mode) { return __awaiter(void 0, void 0, void 0, function () {
+                return __generator(this, function (_a) {
+                    if (offline)
+                        return [2 /*return*/, false];
+                    sent.push({ batch: JSON.parse(body), mode: mode });
+                    return [2 /*return*/, true];
+                });
+            }); },
+        },
+        fetchJson: function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                if (!options.experiments || options.experiments === 'fail')
+                    throw new Error('no experiments endpoint');
+                return [2 /*return*/, { experiments: typeof options.experiments === 'function' ? options.experiments() : options.experiments }];
+            });
+        }); },
+    });
+    var advance = function (ms) { return __awaiter(void 0, void 0, void 0, function () {
+        var until, due;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    until = clock + ms;
+                    _a.label = 1;
+                case 1:
+                    due = Array.from(timers.entries()).filter(function (_a) {
+                        var t = _a[1];
+                        return t.at <= until;
+                    }).sort(function (a, b) { return a[1].at - b[1].at; })[0];
+                    if (!due)
+                        return [3 /*break*/, 4];
+                    timers.delete(due[0]);
+                    clock = Math.max(clock, due[1].at);
+                    due[1].fn();
+                    return [4 /*yield*/, Promise.resolve()];
+                case 2:
+                    _a.sent();
+                    _a.label = 3;
+                case 3: return [3 /*break*/, 1];
+                case 4:
+                    clock = until;
+                    return [4 /*yield*/, new Promise(function (r) { return setTimeout(r, 0); })];
+                case 5:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); };
+    return { tracker: tracker, sent: sent, local: local, session: session, keys: keys, page: page, advance: advance, now: function () { return clock; }, setOffline: function (o) { return (offline = o); } };
+};
+exports.createMemoryTracker = createMemoryTracker;
+//# sourceMappingURL=testing.js.map

package/dist/tracking/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/tracking/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoretechnologies/reqraft",
-  "version": "0.10.56",
+  "version": "0.10.57-pr.127.ge03fd3a",
   "description": "ReQraft is a collection of React components and hooks that are used across Qore Technologies' products made using the ReQore component library from Qore.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.tsx

@@ -77,3 +77,6 @@ export * from './components/ticketThread';
 export * from './components/ticketReferences';
 export * from './components/searchFilterBar';
 export * from './components/codeSize';
+// First-party tracking, consent and A/B testing (design/TRACKING.md). Also importable
+// on its own, without the rest of Reqraft: `@qoretechnologies/reqraft/dist/tracking`.
+export * from './tracking';

package/src/tracking/browser/attach.ts

@@ -0,0 +1,186 @@
+import { effectiveRatio } from '../core/sections';
+import type { Tracker } from '../core/tracker';
+
+/**
+ * Connects a `Tracker` to the page: tab visibility, page leave, interactions,
+ * scroll depth, the heartbeat, section visibility (IntersectionObserver on every
+ * `[data-track-section]`) and clicks (one delegated listener for
+ * `[data-track-click]`). Returns a function that removes all of it.
+ *
+ * Markup contract (see design/TRACKING.md):
+ *   data-track-section="<id>"        a section: visible time, seen, exit section
+ *   data-track-click="<target>"      a tracked click (`get-started`, `contact`, …)
+ *   data-track-placement="<where>"   optional; defaults to the enclosing section id
+ *   data-track-label="<text>"        optional; defaults to the element's text
+ */
+
+const SECTION_SELECTOR = '[data-track-section]';
+const THRESHOLDS = Array.from({ length: 21 }, (_, i) => i / 20);
+const TICK_MS = 250;
+const ACTIVITY_EVENTS = ['pointerdown', 'keydown', 'wheel', 'touchstart', 'mousemove', 'scroll'] as const;
+
+export interface IAttached {
+  detach: () => void;
+  /** Observes an element under a synthetic id (an experiment's wrapped element); not in the page summary. */
+  observeElement: (el: Element, id: string) => () => void;
+}
+
+const clean = (s: string | null | undefined, max = 80) => {
+  const t = (s ?? '').replace(/\s+/g, ' ').trim();
+  return t ? t.slice(0, max) : null;
+};
+
+export const attachToPage = (tracker: Tracker, heartbeatMs: number): IAttached => {
+  const cleanup: (() => void)[] = [];
+  const on = (target: EventTarget, type: string, fn: EventListener, opts?: AddEventListenerOptions) => {
+    target.addEventListener(type, fn, opts);
+    cleanup.push(() => target.removeEventListener(type, fn, opts));
+  };
+  const safe = (fn: () => void) => () => {
+    try {
+      fn();
+    } catch {
+      /* never into the page */
+    }
+  };
+
+  // ── tab visibility and page leave
+  on(document, 'visibilitychange', safe(() => tracker.setTabVisible(document.visibilityState === 'visible')));
+  on(window, 'pagehide', safe(() => tracker.leave()));
+  if (document.visibilityState !== 'visible') tracker.setTabVisible(false);
+
+  // ── engagement (throttled to one signal per second)
+  let lastActivity = 0;
+  const activity = safe(() => {
+    const now = Date.now();
+    if (now - lastActivity < 1000) return;
+    lastActivity = now;
+    tracker.activity();
+  });
+  ACTIVITY_EVENTS.forEach((t) => on(window, t, activity, { passive: true, capture: true }));
+
+  // ── scroll depth (once per frame)
+  let scrollQueued = false;
+  const measureScroll = safe(() => {
+    scrollQueued = false;
+    const doc = document.documentElement;
+    const scrollable = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);
+    const seen = window.scrollY + window.innerHeight;
+    tracker.scrolled(scrollable > 0 ? (seen / scrollable) * 100 : 100);
+  });
+  on(window, 'scroll', () => {
+    if (scrollQueued) return;
+    scrollQueued = true;
+    requestAnimationFrame(measureScroll);
+  }, { passive: true });
+
+  // ── heartbeat while visible, and the section clock
+  const heartbeat = setInterval(safe(() => document.visibilityState === 'visible' && tracker.heartbeat()), heartbeatMs);
+  const tick = setInterval(safe(() => tracker.sections.tick(tracker.now())), TICK_MS);
+  cleanup.push(() => clearInterval(heartbeat), () => clearInterval(tick));
+
+  // ── sections
+  const ratios = new Map<Element, number>();
+  const ids = new Map<Element, string>();
+  const report = new Map<string, boolean>();
+  const apply = (id: string) => {
+    let best = 0;
+    ids.forEach((other, el) => other === id && (best = Math.max(best, ratios.get(el) ?? 0)));
+    tracker.sections.update(id, best, tracker.now());
+  };
+  const io =
+    typeof IntersectionObserver !== 'undefined'
+      ? new IntersectionObserver(
+          (entries) =>
+            safe(() => {
+              const vh = window.innerHeight || document.documentElement.clientHeight;
+              entries.forEach((e) => {
+                const id = ids.get(e.target);
+                if (!id) return;
+                ratios.set(e.target, effectiveRatio(e.intersectionRatio, e.intersectionRect.height, e.rootBounds?.height ?? vh));
+                apply(id);
+              });
+            })(),
+          { threshold: THRESHOLDS },
+        )
+      : null;
+
+  const track = (el: Element, id: string, inSummary: boolean) => {
+    if (ids.get(el) === id) return;
+    ids.set(el, id);
+    report.set(id, (report.get(id) ?? false) || inSummary);
+    tracker.sections.register(id, inSummary);
+    io?.observe(el);
+  };
+  const untrack = (el: Element) => {
+    const id = ids.get(el);
+    if (!id) return;
+    io?.unobserve(el);
+    ids.delete(el);
+    ratios.delete(el);
+    apply(id);
+  };
+
+  const scan = safe(() => {
+    const present = new Set<Element>(Array.from(document.querySelectorAll(SECTION_SELECTOR)));
+    ids.forEach((id, el) => report.get(id) && !present.has(el) && !el.isConnected && untrack(el));
+    present.forEach((el) => {
+      const id = (el as HTMLElement).dataset.trackSection;
+      if (id) track(el, id, true);
+    });
+  });
+
+  // Re-measure everything at a new page view: the section clock starts from zero,
+  // and re-observing makes the observer report every element's current state.
+  const remeasure = safe(() => {
+    scan();
+    ids.forEach((_id, el) => {
+      io?.unobserve(el);
+      io?.observe(el);
+    });
+  });
+  cleanup.push(tracker.pageViewId.subscribe(remeasure));
+
+  let scanTimer: ReturnType<typeof setTimeout> | null = null;
+  const mo =
+    typeof MutationObserver !== 'undefined'
+      ? new MutationObserver(() => {
+          if (scanTimer) return;
+          scanTimer = setTimeout(() => {
+            scanTimer = null;
+            scan();
+          }, 150);
+        })
+      : null;
+  mo?.observe(document.body, { childList: true, subtree: true });
+  scan();
+  cleanup.push(() => {
+    mo?.disconnect();
+    io?.disconnect();
+    if (scanTimer) clearTimeout(scanTimer);
+  });
+
+  // ── clicks: one delegated listener
+  const onClick = (e: Event) =>
+    safe(() => {
+      const el = (e.target as Element | null)?.closest?.('[data-track-click]') as HTMLElement | null;
+      if (!el) return;
+      const d = el.dataset;
+      const link = el.closest('a');
+      tracker.click({
+        target: d.trackClick || 'unknown',
+        placement: d.trackPlacement || (el.closest(SECTION_SELECTOR) as HTMLElement | null)?.dataset.trackSection || null,
+        label: clean(d.trackLabel) ?? clean(el.innerText) ?? clean(el.getAttribute('aria-label')),
+        href: d.trackHref || link?.href || null,
+      });
+    })();
+  on(document, 'click', onClick, { capture: true });
+
+  return {
+    detach: () => cleanup.forEach((fn) => fn()),
+    observeElement: (el, id) => {
+      track(el, id, false);
+      return () => untrack(el);
+    },
+  };
+};

package/src/tracking/browser/env.ts

@@ -0,0 +1,78 @@
+import type { ITransport } from '../core/queue';
+import { safeStorage } from '../core/storage';
+import type { IPageInfo, ITrackerEnv } from '../core/tracker';
+
+/**
+ * Sends a batch. `beacon` (page going away): `navigator.sendBeacon`, falling back
+ * to `fetch(…, { keepalive: true })` when the beacon is refused (too big, or the
+ * browser has none). Any HTTP answer counts as delivered — the collector always
+ * answers 204, and a 404 (collector not installed) must not turn into a retry loop;
+ * only a network error keeps the batch for the next flush.
+ */
+export const browserTransport = (endpoint: string): ITransport => ({
+  async send(body, mode) {
+    if (mode === 'beacon' && typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+      try {
+        if (navigator.sendBeacon(endpoint, new Blob([body], { type: 'application/json' }))) return true;
+      } catch {
+        /* fall through to fetch */
+      }
+    }
+    try {
+      await fetch(endpoint, {
+        method: 'POST',
+        body,
+        headers: { 'Content-Type': 'application/json' },
+        // Batches stay under 60 KB (queue.ts), inside keepalive's 64 KB budget.
+        keepalive: true,
+        credentials: 'same-origin',
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+});
+
+const fetchJson = async (url: string, timeoutMs: number): Promise<unknown> => {
+  const ctrl = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
+  const timer = setTimeout(() => ctrl?.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { headers: { Accept: 'application/json' }, signal: ctrl?.signal, credentials: 'same-origin' });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** desktop / tablet / mobile from the user agent (targeting only; the server classifies for reports). */
+export const deviceOf = (ua: string): IPageInfo['device'] => {
+  if (/iPad|Tablet|PlayBook|Silk|Android(?!.*Mobile)/i.test(ua)) return 'tablet';
+  if (/Mobi|iPhone|iPod|Android.*Mobile|Opera Mini|IEMobile/i.test(ua)) return 'mobile';
+  return 'desktop';
+};
+
+const readPage = (): IPageInfo => ({
+  origin: window.location.origin,
+  path: window.location.pathname,
+  search: window.location.search,
+  title: document.title,
+  referrer: document.referrer,
+  lang: navigator.language || 'en',
+  viewport: [window.innerWidth, window.innerHeight],
+  device: deviceOf(navigator.userAgent || ''),
+});
+
+export const browserEnv = (endpoint: string): ITrackerEnv => ({
+  local: safeStorage(() => window.localStorage),
+  session: safeStorage(() => window.sessionStorage),
+  transport: browserTransport(endpoint),
+  now: () => Date.now(),
+  setTimer: (fn, ms) => setTimeout(fn, ms),
+  clearTimer: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+  page: readPage,
+  fetchJson,
+  // eslint-disable-next-line no-console
+  log: (...args) => console.info(...args),
+});

package/src/tracking/core/consent.ts

@@ -0,0 +1,37 @@
+import type { IStorage } from './storage';
+import { Observable } from './observable';
+import { KEYS, type TConsentState, type TStorageKeys } from './types';
+
+/**
+ * The visitor's answer (§3 of the contract): `localStorage["<prefix>consent"]` is
+ * `granted` | `denied`, `<prefix>consent.v` the version of the text they answered
+ * (prefix `qa.` by default). An answer to an older version counts as no answer, so
+ * the consent prompt asks again.
+ */
+export class ConsentStore {
+  readonly state: Observable<TConsentState>;
+
+  constructor(
+    private readonly storage: IStorage,
+    private readonly version: number,
+    private readonly keys: TStorageKeys = KEYS,
+  ) {
+    this.state = new Observable<TConsentState>(this.read());
+  }
+
+  private read(): TConsentState {
+    const answer = this.storage.get(this.keys.consent);
+    const version = Number(this.storage.get(this.keys.consentVersion) ?? 0);
+    if ((answer === 'granted' || answer === 'denied') && version >= this.version) return answer;
+    return 'unknown';
+  }
+
+  get = (): TConsentState => this.state.get();
+  granted = (): boolean => this.state.get() === 'granted';
+
+  answer(state: 'granted' | 'denied') {
+    this.storage.set(this.keys.consent, state);
+    this.storage.set(this.keys.consentVersion, String(this.version));
+    this.state.set(state);
+  }
+}

package/src/tracking/core/engagement.ts

@@ -0,0 +1,47 @@
+/**
+ * Engaged time: the tab is visible AND the visitor did something (scroll, pointer,
+ * key, touch) within the last `windowMs`. Each interaction extends the engaged
+ * stretch to `interaction + windowMs`; hiding the tab ends it at once.
+ */
+export class EngagementClock {
+  private engagedMs = 0;
+  /** Start and end of the current engaged stretch (end is in the future while active). */
+  private from: number | null = null;
+  private until = 0;
+  private tabVisible = true;
+
+  constructor(private readonly windowMs: number) {}
+
+  reset() {
+    this.engagedMs = 0;
+    this.from = null;
+    this.until = 0;
+  }
+
+  activity(now: number) {
+    if (!this.tabVisible) return;
+    if (this.from != null && now <= this.until) {
+      this.until = now + this.windowMs;
+      return;
+    }
+    this.close(now);
+    this.from = now;
+    this.until = now + this.windowMs;
+  }
+
+  setTabVisible(visible: boolean, now: number) {
+    if (!visible) this.close(now);
+    this.tabVisible = visible;
+  }
+
+  private close(now: number) {
+    if (this.from == null) return;
+    this.engagedMs += Math.max(0, Math.min(now, this.until) - this.from);
+    this.from = null;
+  }
+
+  total(now: number): number {
+    const open = this.from != null ? Math.max(0, Math.min(now, this.until) - this.from) : 0;
+    return Math.round(this.engagedMs + open);
+  }
+}