@appright/funnelshift 0.0.0-stage → 0.16.0

package/dist/signals.js

@@ -0,0 +1,300 @@
+// What the kit watches on a step by itself (kit 0.13.0, see autotrack.ts for the switches). One object per mounted funnel; the
+// funnel calls newView() when a step comes on screen and activeMs() when it leaves one.
+//
+//   $scroll {depth, ms}        depth 25, 50, 75 or 100: the share of the page that has been in the window at the deepest. Each depth
+//                              once per step view; a jump over several quarters sends each of them. Only on a page taller than the
+//                              window, and only once the visitor scrolls (no scrolling, no event). ms: since the step came on screen.
+//   $section_view {section, ms} an element with data-section="<name>" was at least half in view (or fills half of the window, for a
+//                              section taller than it) for one second without a break, in a visible tab. Once per section and view.
+//   $field_error {field, code} a field turned invalid: the browser's `invalid` event (a native validation) or aria-invalid going to
+//                              "true" (a funnel's own). The field is its name; the code a short word (required, email_invalid, …).
+//                              The typed value is never read. Not more than 3 per field and code, 20 per step view.
+//   active_ms                  the time this step was on screen with the tab visible and the window focused (activeMs()).
+//
+// All of it is passive: listeners never stop or change anything, and nothing here may throw into the page.
+const QUARTERS = [25, 50, 75, 100];
+const SCROLL_DELAY = 120;
+const MIN_SCROLL = 50; // a page taller than the window by less than this does not scroll
+const SECTION_DWELL = 1000;
+const SECTION_SELECTOR = '[data-section]';
+const SECTION_NAME = /[^a-z0-9_-]+/g;
+const MAX_NAME = 64;
+const MAX_PER_FIELD = 3;
+const MAX_PER_VIEW = 20;
+const MAX_SECTIONS_PER_VIEW = 20; // sections named in one step view; a page with more is marked with too many data-section
+const CODE = /^[a-z][a-z0-9_]{0,31}$/;
+const FIELD_TYPES_WITH_CODE = new Set(['email', 'tel', 'url', 'number', 'date']);
+const THRESHOLDS = Array.from({ length: 21 }, (_, i) => i / 20);
+// The name of a section as it is sent: lower case, anything but [a-z0-9_-] turned into _, at most 64 characters; '' for none.
+export function sectionName(raw) {
+    const n = (raw ?? '').trim().toLowerCase().replace(SECTION_NAME, '_').replace(/^_+|_+$/g, '').slice(0, MAX_NAME);
+    return n;
+}
+// The key of a field: its name, else data-track, data-field, a plain id, else its type. Lower case, [a-z0-9_-].
+export function fieldKey(el) {
+    const id = el.getAttribute('id') ?? '';
+    const raw = el.getAttribute('name') || el.getAttribute('data-track') || el.getAttribute('data-field') || (id && !id.startsWith(':') ? id : '')
+        || el.getAttribute('type') || el.tagName.toLowerCase();
+    return sectionName(raw) || 'field';
+}
+// The error code of a field that is invalid: data-error-code, else the browser's validity state, else a guess from the field
+// without ever looking at what was typed (only whether it is empty).
+export function errorCode(el) {
+    const own = el.getAttribute('data-error-code') ?? '';
+    if (CODE.test(own))
+        return own;
+    const type = (el.getAttribute('type') ?? 'text').toLowerCase();
+    const v = el.validity;
+    if (v && !v.valid) {
+        if (v.valueMissing)
+            return 'required';
+        if (v.typeMismatch)
+            return FIELD_TYPES_WITH_CODE.has(type) ? `${type}_invalid` : 'invalid';
+        if (v.patternMismatch)
+            return FIELD_TYPES_WITH_CODE.has(type) ? `${type}_invalid` : 'pattern';
+        if (v.tooShort)
+            return 'too_short';
+        if (v.tooLong)
+            return 'too_long';
+        if (v.rangeUnderflow)
+            return 'too_small';
+        if (v.rangeOverflow)
+            return 'too_large';
+        if (v.stepMismatch)
+            return 'step_mismatch';
+        if (v.badInput)
+            return 'bad_input';
+    }
+    const value = el.value;
+    if (typeof value === 'string' && value === '' && el.matches('input, textarea, select'))
+        return 'required';
+    return FIELD_TYPES_WITH_CODE.has(type) ? `${type}_invalid` : 'invalid';
+}
+// The time the tab was visible and the window focused. Focus is taken for granted until a blur says otherwise (a webview may never
+// report it), and a blur into an iframe (a card form) is not a leave.
+class ActiveClock {
+    now;
+    acc = 0;
+    since;
+    focused = true;
+    listeners = [];
+    constructor(now) {
+        this.now = now;
+        this.since = this.active() ? now() : null;
+        const on = (t, type, fn) => { t.addEventListener(type, fn); this.listeners.push([t, type, fn]); };
+        on(document, 'visibilitychange', () => this.sync());
+        on(window, 'blur', () => { if (document.activeElement?.tagName === 'IFRAME')
+            return; this.focused = false; this.sync(); });
+        on(window, 'focus', () => { this.focused = true; this.sync(); });
+        on(window, 'pageshow', () => { this.focused = true; this.sync(); });
+    }
+    active() { return document.visibilityState !== 'hidden' && this.focused; }
+    sync() {
+        const a = this.active(), t = this.now();
+        if (a && this.since === null)
+            this.since = t;
+        else if (!a && this.since !== null) {
+            this.acc += t - this.since;
+            this.since = null;
+        }
+    }
+    reset() { this.acc = 0; this.since = this.active() ? this.now() : null; }
+    read() { return Math.max(0, Math.round(this.acc + (this.since !== null ? this.now() - this.since : 0))); }
+    off() { for (const [t, type, fn] of this.listeners)
+        t.removeEventListener(type, fn); this.listeners = []; }
+}
+export function installStepSignals(root, o) {
+    const now = o.now ?? Date.now;
+    const safe = (fn) => () => { try {
+        fn();
+    }
+    catch { /* analytics must never break the page */ } };
+    const clock = o.activeTime ? new ActiveClock(now) : null;
+    let viewStart = now();
+    let alive = true;
+    // ---- scroll depth ------------------------------------------------------------------------------------------------------------
+    let reached = 0;
+    let scrollTimer;
+    const measure = safe(() => {
+        scrollTimer = undefined;
+        const doc = document.documentElement;
+        const total = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);
+        const view = window.innerHeight || doc.clientHeight;
+        if (!(view > 0) || !(total > view + MIN_SCROLL))
+            return;
+        const pct = ((window.scrollY || doc.scrollTop || 0) + view) / total * 100;
+        for (const q of QUARTERS) {
+            if (q > reached && pct >= q - 1) {
+                reached = q;
+                o.track('$scroll', { depth: q, ms: Math.max(0, now() - viewStart) }, o.stepId());
+            }
+        }
+    });
+    const onScroll = () => { if (alive && scrollTimer === undefined)
+        scrollTimer = setTimeout(measure, SCROLL_DELAY); };
+    if (o.scroll)
+        window.addEventListener('scroll', onScroll, { passive: true });
+    // ---- sections ----------------------------------------------------------------------------------------------------------------
+    let io;
+    let mo;
+    const seen = new Set();
+    let sectionsSent = 0;
+    const inView = new Set(); // half in view now, whatever the tab does
+    const timers = new Map();
+    const tabVisible = () => document.visibilityState !== 'hidden';
+    const clearTimer = (el) => { const t = timers.get(el); if (t !== undefined) {
+        clearTimeout(t);
+        timers.delete(el);
+    } };
+    const arm = (el) => {
+        if (timers.has(el) || !tabVisible())
+            return;
+        const name = sectionName(el.getAttribute('data-section'));
+        if (!name || seen.has(name))
+            return;
+        timers.set(el, setTimeout(safe(() => {
+            timers.delete(el);
+            if (!alive || seen.has(name) || !inView.has(el) || !tabVisible() || sectionsSent >= MAX_SECTIONS_PER_VIEW)
+                return;
+            seen.add(name);
+            sectionsSent++;
+            inView.delete(el);
+            io?.unobserve(el);
+            o.track('$section_view', { section: name, ms: Math.max(0, now() - viewStart) }, o.stepId());
+        }), SECTION_DWELL));
+    };
+    const watched = new Set();
+    const watch = (el) => {
+        if (io && !watched.has(el)) {
+            watched.add(el);
+            io.observe(el);
+        }
+    };
+    const scan = (from) => {
+        if (from instanceof Element && from.matches(SECTION_SELECTOR))
+            watch(from);
+        from.querySelectorAll(SECTION_SELECTOR).forEach(watch);
+    };
+    const startSections = () => {
+        if (!o.sections || typeof IntersectionObserver === 'undefined')
+            return;
+        io = new IntersectionObserver(entries => {
+            try {
+                for (const e of entries) {
+                    const h = e.rootBounds?.height || window.innerHeight;
+                    const half = e.isIntersecting && (e.intersectionRatio >= 0.5 || (h > 0 && e.intersectionRect.height >= h * 0.5));
+                    if (half) {
+                        inView.add(e.target);
+                        arm(e.target);
+                    }
+                    else {
+                        inView.delete(e.target);
+                        clearTimer(e.target);
+                    }
+                }
+            }
+            catch { /* analytics must never break the page */ }
+        }, { threshold: THRESHOLDS });
+        scan(root);
+        if (typeof MutationObserver !== 'undefined') {
+            mo = new MutationObserver(records => { try {
+                for (const r of records)
+                    r.addedNodes.forEach(n => { if (n instanceof Element)
+                        scan(n); });
+            }
+            catch { /* ignore */ } });
+            mo.observe(root, { childList: true, subtree: true });
+        }
+    };
+    const stopSections = () => {
+        io?.disconnect();
+        mo?.disconnect();
+        io = undefined;
+        mo = undefined;
+        for (const t of timers.values())
+            clearTimeout(t);
+        timers.clear();
+        inView.clear();
+        watched.clear();
+    };
+    const onVisibility = () => {
+        if (document.visibilityState === 'hidden') {
+            for (const t of timers.values())
+                clearTimeout(t);
+            timers.clear();
+        }
+        else
+            for (const el of inView)
+                arm(el);
+    };
+    if (o.sections)
+        document.addEventListener('visibilitychange', onVisibility);
+    // ---- field errors ------------------------------------------------------------------------------------------------------------
+    const counts = new Map();
+    const lastAt = new Map();
+    let total = 0;
+    const reportField = (el) => {
+        if (!alive || el.matches('[type=hidden], :disabled'))
+            return;
+        const field = fieldKey(el), code = errorCode(el), key = field + '\u0000' + code;
+        const t = now(), n = counts.get(key) ?? 0;
+        if (total >= MAX_PER_VIEW || n >= MAX_PER_FIELD || t - (lastAt.get(key) ?? -1e9) < 1000)
+            return;
+        counts.set(key, n + 1);
+        lastAt.set(key, t);
+        total++;
+        o.track('$field_error', { field, code }, o.stepId());
+    };
+    const onInvalid = (e) => { try {
+        if (e.target instanceof Element)
+            reportField(e.target);
+    }
+    catch { /* ignore */ } };
+    let ariaObserver;
+    if (o.fieldErrors) {
+        root.addEventListener('invalid', onInvalid, true);
+        if (typeof MutationObserver !== 'undefined') {
+            ariaObserver = new MutationObserver(records => {
+                try {
+                    for (const r of records) {
+                        const el = r.target;
+                        if (r.type === 'attributes' && el instanceof Element && el.getAttribute('aria-invalid') === 'true' && r.oldValue !== 'true')
+                            reportField(el);
+                    }
+                }
+                catch { /* ignore */ }
+            });
+            ariaObserver.observe(root, { attributes: true, attributeFilter: ['aria-invalid'], attributeOldValue: true, subtree: true });
+        }
+    }
+    return {
+        newView() {
+            viewStart = now();
+            reached = 0;
+            if (scrollTimer !== undefined) {
+                clearTimeout(scrollTimer);
+                scrollTimer = undefined;
+            }
+            stopSections();
+            seen.clear();
+            sectionsSent = 0;
+            startSections();
+            counts.clear();
+            lastAt.clear();
+            total = 0;
+            clock?.reset();
+        },
+        activeMs: () => clock?.read(),
+        off() {
+            alive = false;
+            if (scrollTimer !== undefined)
+                clearTimeout(scrollTimer);
+            window.removeEventListener('scroll', onScroll);
+            document.removeEventListener('visibilitychange', onVisibility);
+            stopSections();
+            root.removeEventListener('invalid', onInvalid, true);
+            ariaObserver?.disconnect();
+            clock?.off();
+        },
+    };
+}

package/dist/tracker.d.ts

@@ -0,0 +1,80 @@
+import type { Env } from './bootstrap.js';
+import { type Attribution } from './attribution.js';
+import { type BatchContext } from './context.js';
+export type Base = {
+    funnel_id: string;
+    build_id: string;
+    release_id: string;
+    env: Env;
+    visitor_id: string;
+    url_path: string;
+};
+export type TrackerOptions = {
+    ingestUrl: string | null;
+    key: string;
+    base: Base;
+    attribution?: Partial<Attribution>;
+    fallbackUrl?: string | null;
+    project?: string;
+    primaryTimeoutMs?: number;
+    variants?: Record<string, string>;
+    context?: () => BatchContext;
+    geo?: string;
+    storage?: Storage;
+    session?: Storage;
+    fetchImpl?: typeof fetch;
+    beacon?: (url: string, body: string) => boolean;
+    maxBatch?: number;
+    intervalMs?: number;
+    now?: () => number;
+};
+export declare const MAX_USER_ID = 128;
+export declare function validUserId(u: unknown): u is string;
+export type FinalEvent = {
+    name: string;
+    props?: Record<string, unknown>;
+};
+export type StopScope = 'tab' | 'project';
+export declare function safeProps(p?: Record<string, unknown>): Record<string, string>;
+export declare class Tracker {
+    private o;
+    private qkey;
+    private stopKey;
+    private projectStopKey;
+    private userKey;
+    private memUser;
+    private halted;
+    private isDegraded;
+    private nextProbe;
+    private lastFallback;
+    private fallbackSends;
+    private timer?;
+    private inflight;
+    private failures;
+    private retryAt;
+    private onHide;
+    private onVisibility;
+    constructor(o: TrackerOptions);
+    private sharedDegradedUntil;
+    private shareDegraded;
+    private projectStopped;
+    stopped(): boolean;
+    user(): string;
+    setUser(id: string): void;
+    clearUser(): void;
+    degraded(): boolean;
+    halt(final?: FinalEvent, scope?: StopScope): Promise<void>;
+    private context;
+    private post;
+    private queue;
+    private save;
+    private sessionId;
+    session(): string;
+    track(name: string, props?: Record<string, unknown>, stepId?: string, variants?: Record<string, string>): string;
+    flushSoon(): void;
+    private takeBatch;
+    flush(useBeacon?: boolean): Promise<void>;
+    idle(): Promise<void>;
+    start(): void;
+    stop(): void;
+}