@oneuptime/common 14.0.1 → 14.0.2

package/build/dist/Utils/Rum/UserFlow.js

@@ -0,0 +1,941 @@
+/*
+ * The User Flows engine: recorded session journeys in, everything the page
+ * draws out - the step-by-step flow map, the most common paths, per-page
+ * entry / exit / drop-off numbers, back-and-forth loops, and the few
+ * findings worth putting in front of someone first.
+ *
+ * Pure and synchronous on purpose. The endpoint returns journeys, not a
+ * graph (see Types/Rum/UserFlow.ts), so every control on the page is a call
+ * to analyzeUserFlow with different options over the same input; it runs
+ * in single-digit milliseconds for the endpoint's session cap.
+ *
+ * Vocabulary:
+ *  - page: a flow-map key. The scrubbed URL without origin, query or
+ *    trailing slash ("/cart"), optionally with id-shaped segments grouped
+ *    ("/product/:id"), and with the host kept only when the application
+ *    spans more than one ("shop.example.com/cart").
+ *  - journey: one session's pages in order, after grouping and hiding,
+ *    with back-to-back repeats collapsed.
+ *  - step: a column of the flow map. Step 0 is the session's first page,
+ *    or the anchor page when the map is anchored on one.
+ */
+export const OTHER_PAGES_KEY = "__other__";
+export const OTHER_PAGES_LABEL = "Other pages";
+export const USER_FLOW_MIN_STEPS = 2;
+export const USER_FLOW_MAX_STEPS = 10;
+export const USER_FLOW_DEFAULT_STEPS = 5;
+export const USER_FLOW_MIN_PAGES_PER_STEP = 2;
+export const USER_FLOW_MAX_PAGES_PER_STEP = 20;
+export const USER_FLOW_DEFAULT_PAGES_PER_STEP = 6;
+/* Sessions an entity keeps as "watch one of these" links. */
+export const USER_FLOW_SAMPLE_SESSIONS = 5;
+/* Pages shown in a path before it is cut with an ellipsis. */
+export const USER_FLOW_MAX_PATH_LENGTH = 8;
+export const USER_FLOW_MAX_PATHS = 25;
+export const USER_FLOW_MAX_NEIGHBOURS = 6;
+export const USER_FLOW_MAX_LOOPS = 10;
+/* Pages an "Other pages" node lists when it is opened. */
+export const USER_FLOW_MAX_OTHER_PAGES = 50;
+/*
+ * Findings need a floor, or "100% of sessions left from /legal" is a single
+ * visitor. The larger of an absolute count and a share of the sample.
+ */
+const INSIGHT_MIN_SESSIONS = 3;
+const INSIGHT_MIN_SHARE = 0.02;
+/* See the drop-off finding: below this, a page is a natural end. */
+const DROP_OFF_MIN_CONTINUE_SHARE = 0.1;
+export const DEFAULT_USER_FLOW_OPTIONS = {
+    anchorPage: null,
+    direction: "forward",
+    steps: USER_FLOW_DEFAULT_STEPS,
+    pagesPerStep: USER_FLOW_DEFAULT_PAGES_PER_STEP,
+    groupDynamicSegments: true,
+    hiddenPages: [],
+    sessionFilter: "all",
+    deviceType: "",
+};
+/* ------------------------------------------------------------------ */
+/* Page keys                                                           */
+/* ------------------------------------------------------------------ */
+const RELATIVE_BASE = "https://relative.invalid";
+const NUMERIC_SEGMENT = /^\d+$/;
+const HEX_ID_SEGMENT = /^(?=[0-9a-f]*\d)[0-9a-f]{8,}$/i;
+const UUID_SEGMENT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/* A long token mixing letters and digits: a slug id, an opaque key. */
+const MIXED_TOKEN_SEGMENT = /^(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{16,}$/;
+const REDACTED_SEGMENT = "[redacted]";
+const DYNAMIC_SEGMENT_LABEL = ":id";
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch (_a) {
+        return segment;
+    }
+}
+/*
+ * True for a path segment that names one record rather than a route: the
+ * recorder's own "[redacted]" marker (uuids, emails, long numbers, opaque
+ * tokens are already replaced before storage), plus the id shapes it keeps -
+ * short numbers, hex ids, long letter-digit tokens.
+ */
+export function isDynamicPathSegment(segment) {
+    const decoded = decodeSegment(segment);
+    return (decoded === REDACTED_SEGMENT ||
+        NUMERIC_SEGMENT.test(decoded) ||
+        UUID_SEGMENT.test(decoded) ||
+        HEX_ID_SEGMENT.test(decoded) ||
+        MIXED_TOKEN_SEGMENT.test(decoded));
+}
+function parsePageUrl(rawUrl) {
+    const trimmed = (rawUrl || "").trim();
+    if (!trimmed) {
+        return { host: "", path: "/" };
+    }
+    try {
+        const parsed = new URL(trimmed, RELATIVE_BASE);
+        const isRelative = parsed.origin === RELATIVE_BASE && !trimmed.startsWith(RELATIVE_BASE);
+        /*
+         * A hash router keeps its route in the fragment ("/#/orders"). The
+         * recorder stores such URLs with the fragment when it can; treat
+         * "#/..." as the path so those apps do not collapse onto "/".
+         */
+        let path = parsed.pathname || "/";
+        if (parsed.hash.startsWith("#/")) {
+            path = parsed.hash.slice(1);
+        }
+        return { host: isRelative ? "" : parsed.host, path: path };
+    }
+    catch (_a) {
+        return { host: "", path: trimmed };
+    }
+}
+function normalizePath(path, groupDynamicSegments) {
+    let segments = path.split("/");
+    if (groupDynamicSegments) {
+        segments = segments.map((segment) => {
+            if (!segment) {
+                return segment;
+            }
+            return isDynamicPathSegment(segment) ? DYNAMIC_SEGMENT_LABEL : segment;
+        });
+    }
+    let normalized = segments.join("/");
+    if (!normalized.startsWith("/")) {
+        normalized = `/${normalized}`;
+    }
+    /* "/cart/" and "/cart" are one page to a person; keep "/" itself. */
+    while (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+/*
+ * The flow-map key for one stored URL. Query strings are dropped (the
+ * scrubber keeps only redacted allowlisted parameters, which would split
+ * one page into two), and the host is kept only when asked.
+ */
+export function toUserFlowPageKey(rawUrl, options) {
+    const parsed = parsePageUrl(rawUrl);
+    const path = normalizePath(parsed.path, options.groupDynamicSegments);
+    if (options.includeHost && parsed.host) {
+        return `${parsed.host}${path}`;
+    }
+    return path;
+}
+/* True when the stored URLs span more than one host. */
+export function spansMultipleHosts(rawUrls) {
+    let firstHost = null;
+    for (const rawUrl of rawUrls) {
+        const host = parsePageUrl(rawUrl).host;
+        if (!host) {
+            continue;
+        }
+        if (firstHost === null) {
+            firstHost = host;
+        }
+        else if (host !== firstHost) {
+            return true;
+        }
+    }
+    return false;
+}
+/*
+ * The URL-path prefix that selects a page key in the session list's
+ * urlPrefix filter: "/product/:id" -> "/product/", host dropped. The list
+ * matches prefixes, so a grouped key is widened to its static head.
+ */
+export function toSessionListUrlPrefix(page) {
+    if (!page || page === OTHER_PAGES_KEY) {
+        return "";
+    }
+    const slash = page.indexOf("/");
+    const path = slash > 0 ? page.slice(slash) : page;
+    const dynamic = path.indexOf(`/${DYNAMIC_SEGMENT_LABEL}`);
+    if (dynamic >= 0) {
+        return path.slice(0, dynamic + 1);
+    }
+    return path;
+}
+export function getUserFlowPageLabel(page) {
+    return page === OTHER_PAGES_KEY ? OTHER_PAGES_LABEL : page;
+}
+/* ------------------------------------------------------------------ */
+/* Journeys                                                            */
+/* ------------------------------------------------------------------ */
+function collapseRepeats(pages) {
+    const collapsed = [];
+    for (const page of pages) {
+        if (collapsed[collapsed.length - 1] !== page) {
+            collapsed.push(page);
+        }
+    }
+    return collapsed;
+}
+/*
+ * Every session as a journey of page keys. Hiding runs BEFORE collapsing,
+ * so hiding a login interstitial turns "/cart -> /login -> /cart" into one
+ * visit to /cart rather than a self-loop.
+ */
+export function buildUserFlowJourneys(response, options) {
+    const includesHost = spansMultipleHosts(response.pages);
+    const keys = response.pages.map((rawUrl) => {
+        return toUserFlowPageKey(rawUrl, {
+            groupDynamicSegments: options.groupDynamicSegments,
+            includeHost: includesHost,
+        });
+    });
+    const hidden = new Set(options.hiddenPages);
+    const journeys = [];
+    for (const session of response.sessions) {
+        if (options.deviceType && session.deviceType !== options.deviceType) {
+            continue;
+        }
+        const hadErrors = session.errorCount > 0;
+        const hadFrustration = session.frustrationCount > 0;
+        if (options.sessionFilter === "errors" && !hadErrors) {
+            continue;
+        }
+        if (options.sessionFilter === "frustration" && !hadFrustration) {
+            continue;
+        }
+        const pages = collapseRepeats(session.pages
+            .map((index) => {
+            return keys[index];
+        })
+            .filter((page) => {
+            return typeof page === "string" && !hidden.has(page);
+        }));
+        if (pages.length === 0) {
+            continue;
+        }
+        const errorPages = new Set();
+        const frustrationPages = new Set();
+        for (const [index, errors, frustration] of session.pageSignals) {
+            const page = keys[index];
+            if (page === undefined) {
+                continue;
+            }
+            if (errors > 0) {
+                errorPages.add(page);
+            }
+            if (frustration > 0) {
+                frustrationPages.add(page);
+            }
+        }
+        journeys.push(toJourney(session, pages, errorPages, frustrationPages));
+    }
+    return { journeys: journeys, includesHost: includesHost };
+}
+function toJourney(session, pages, errorPages, frustrationPages) {
+    return {
+        sessionId: session.sessionId,
+        startUnixMs: session.startUnixMs,
+        durationMs: session.durationMs,
+        deviceType: session.deviceType,
+        pages: pages,
+        errorPages: errorPages,
+        frustrationPages: frustrationPages,
+        hadErrors: session.errorCount > 0 || errorPages.size > 0,
+        hadFrustration: session.frustrationCount > 0 || frustrationPages.size > 0,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Small counting helpers                                              */
+/* ------------------------------------------------------------------ */
+class Counter {
+    constructor() {
+        this.counts = new Map();
+    }
+    add(key, amount = 1) {
+        this.counts.set(key, (this.counts.get(key) || 0) + amount);
+    }
+    get(key) {
+        return this.counts.get(key) || 0;
+    }
+    top(limit) {
+        return sortCounts(Array.from(this.counts.entries()).map(([page, sessions]) => {
+            return { page: page, sessions: sessions };
+        })).slice(0, limit);
+    }
+    size() {
+        return this.counts.size;
+    }
+}
+/* Largest first; ties by key so the order never depends on input order. */
+function sortCounts(counts) {
+    return counts.sort((a, b) => {
+        if (b.sessions !== a.sessions) {
+            return b.sessions - a.sessions;
+        }
+        return a.page < b.page ? -1 : a.page > b.page ? 1 : 0;
+    });
+}
+function pushSample(samples, sessionId) {
+    if (samples.length < USER_FLOW_SAMPLE_SESSIONS) {
+        samples.push(sessionId);
+    }
+}
+function ratio(part, whole) {
+    return whole > 0 ? part / whole : 0;
+}
+function median(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((a, b) => {
+        return a - b;
+    });
+    const middle = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 1) {
+        return sorted[middle];
+    }
+    return (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value)) {
+        return min;
+    }
+    return Math.max(min, Math.min(max, Math.round(value)));
+}
+/* ------------------------------------------------------------------ */
+/* The flow map                                                        */
+/* ------------------------------------------------------------------ */
+function nodeId(step, page) {
+    return `${step}\u0000${page}`;
+}
+/*
+ * The slice of a journey the map draws, step 0 first.
+ *  - no anchor: the whole journey.
+ *  - forward: from the first arrival at the anchor onwards.
+ *  - backward: the anchor, then the page before it, and so on back to the
+ *    session start - reversed, so step 1 is "the page they came from".
+ * Null when the journey never reached the anchor.
+ */
+export function sliceJourneyForMap(pages, anchorPage, direction) {
+    if (!anchorPage) {
+        return pages;
+    }
+    const first = pages.indexOf(anchorPage);
+    if (first < 0) {
+        return null;
+    }
+    if (direction === "backward") {
+        return pages.slice(0, first + 1).reverse();
+    }
+    return pages.slice(first);
+}
+export function buildUserFlowGraph(journeys, options) {
+    const steps = clamp(options.steps, USER_FLOW_MIN_STEPS, USER_FLOW_MAX_STEPS);
+    const pagesPerStep = clamp(options.pagesPerStep, USER_FLOW_MIN_PAGES_PER_STEP, USER_FLOW_MAX_PAGES_PER_STEP);
+    const direction = options.anchorPage
+        ? options.direction
+        : "forward";
+    const slices = [];
+    for (const journey of journeys) {
+        const pages = sliceJourneyForMap(journey.pages, options.anchorPage, direction);
+        if (pages && pages.length > 0) {
+            slices.push({ journey: journey, pages: pages });
+        }
+    }
+    /* Which pages keep their own node at each step: the busiest few. */
+    const stepCounters = [];
+    for (let step = 0; step < steps; step++) {
+        stepCounters.push(new Counter());
+    }
+    for (const slice of slices) {
+        const limit = Math.min(slice.pages.length, steps);
+        for (let step = 0; step < limit; step++) {
+            stepCounters[step].add(slice.pages[step]);
+        }
+    }
+    const keptPages = stepCounters.map((counter) => {
+        /*
+         * Folding exactly one page into "Other pages" hides a name to save
+         * nothing, so a step is only folded when two or more pages overflow.
+         */
+        const limit = counter.size() === pagesPerStep + 1 ? pagesPerStep + 1 : pagesPerStep;
+        return new Set(counter.top(limit).map((entry) => {
+            return entry.page;
+        }));
+    });
+    const nodes = new Map();
+    const otherCounters = new Map();
+    const links = new Map();
+    let populatedSteps = 0;
+    const getNode = (step, page) => {
+        const isOther = !keptPages[step].has(page);
+        const key = isOther ? OTHER_PAGES_KEY : page;
+        const id = nodeId(step, key);
+        let node = nodes.get(id);
+        if (!node) {
+            node = {
+                id: id,
+                step: step,
+                page: key,
+                label: getUserFlowPageLabel(key),
+                isOther: isOther,
+                otherPages: [],
+                sessions: 0,
+                terminal: 0,
+                continued: 0,
+                errorSessions: 0,
+                frustrationSessions: 0,
+                sampleSessionIds: [],
+            };
+            nodes.set(id, node);
+        }
+        if (isOther) {
+            let counter = otherCounters.get(id);
+            if (!counter) {
+                counter = new Counter();
+                otherCounters.set(id, counter);
+            }
+            counter.add(page);
+        }
+        return node;
+    };
+    for (const slice of slices) {
+        const { journey, pages } = slice;
+        const limit = Math.min(pages.length, steps);
+        let previous = null;
+        /*
+         * Pages already behind the visitor at each step, in the order they
+         * lived them. For a backward slice that is everything FURTHER from the
+         * anchor, which sits later in the slice.
+         */
+        const seenBefore = new Set();
+        if (direction === "backward") {
+            for (let index = limit; index < pages.length; index++) {
+                seenBefore.add(pages[index]);
+            }
+        }
+        else if (options.anchorPage) {
+            /* Forward from an anchor: what came before the first arrival. */
+            const first = journey.pages.indexOf(options.anchorPage);
+            for (let index = 0; index < first; index++) {
+                seenBefore.add(journey.pages[index]);
+            }
+        }
+        populatedSteps = Math.max(populatedSteps, limit);
+        const order = [];
+        for (let step = 0; step < limit; step++) {
+            order.push(step);
+        }
+        /* Revisits are judged in the order the visitor lived the journey. */
+        const livedOrder = direction === "backward" ? [...order].reverse() : order;
+        const revisitAt = new Set();
+        for (const step of livedOrder) {
+            const page = pages[step];
+            if (seenBefore.has(page)) {
+                revisitAt.add(step);
+            }
+            seenBefore.add(page);
+        }
+        for (const step of order) {
+            const page = pages[step];
+            const node = getNode(step, page);
+            node.sessions += 1;
+            pushSample(node.sampleSessionIds, journey.sessionId);
+            if (journey.errorPages.has(page)) {
+                node.errorSessions += 1;
+            }
+            if (journey.frustrationPages.has(page)) {
+                node.frustrationSessions += 1;
+            }
+            if (step === limit - 1) {
+                if (pages.length > steps) {
+                    node.continued += 1;
+                }
+                else {
+                    node.terminal += 1;
+                }
+            }
+            if (previous) {
+                /* Links always run in the order the visitor lived them. */
+                const source = direction === "backward" ? node : previous;
+                const target = direction === "backward" ? previous : node;
+                const id = `${source.id}\u0001${target.id}`;
+                let link = links.get(id);
+                if (!link) {
+                    link = {
+                        id: id,
+                        sourceId: source.id,
+                        targetId: target.id,
+                        fromPage: source.page,
+                        toPage: target.page,
+                        sessions: 0,
+                        revisitSessions: 0,
+                        sampleSessionIds: [],
+                    };
+                    links.set(id, link);
+                }
+                link.sessions += 1;
+                pushSample(link.sampleSessionIds, journey.sessionId);
+                /*
+                 * The lived destination is `node` going forward and `previous`
+                 * (the step nearer the anchor) going backward.
+                 */
+                const livedTargetStep = direction === "backward" ? step - 1 : step;
+                if (revisitAt.has(livedTargetStep)) {
+                    link.revisitSessions += 1;
+                }
+            }
+            previous = node;
+        }
+    }
+    for (const [id, counter] of otherCounters.entries()) {
+        const node = nodes.get(id);
+        if (node) {
+            node.otherPages = counter.top(USER_FLOW_MAX_OTHER_PAGES);
+        }
+    }
+    const sortedNodes = Array.from(nodes.values()).sort((a, b) => {
+        if (a.step !== b.step) {
+            return a.step - b.step;
+        }
+        /* "Other pages" sits at the bottom of its column. */
+        if (a.isOther !== b.isOther) {
+            return a.isOther ? 1 : -1;
+        }
+        if (b.sessions !== a.sessions) {
+            return b.sessions - a.sessions;
+        }
+        return a.page < b.page ? -1 : a.page > b.page ? 1 : 0;
+    });
+    const sortedLinks = Array.from(links.values()).sort((a, b) => {
+        if (b.sessions !== a.sessions) {
+            return b.sessions - a.sessions;
+        }
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    return {
+        direction: direction,
+        anchorPage: options.anchorPage,
+        steps: populatedSteps,
+        nodes: sortedNodes,
+        links: sortedLinks,
+        sessions: slices.length,
+    };
+}
+export function buildUserFlowPageStats(journeys) {
+    const pages = new Map();
+    const get = (page) => {
+        let accumulator = pages.get(page);
+        if (!accumulator) {
+            accumulator = {
+                sessions: 0,
+                views: 0,
+                entries: 0,
+                exits: 0,
+                bounces: 0,
+                errorSessions: 0,
+                frustrationSessions: 0,
+                next: new Counter(),
+                previous: new Counter(),
+                sampleSessionIds: [],
+            };
+            pages.set(page, accumulator);
+        }
+        return accumulator;
+    };
+    for (const journey of journeys) {
+        const visited = new Set();
+        /* Next / previous count sessions, not transitions, like every column. */
+        const nextSeen = new Set();
+        const previousSeen = new Set();
+        journey.pages.forEach((page, index) => {
+            const accumulator = get(page);
+            accumulator.views += 1;
+            if (!visited.has(page)) {
+                visited.add(page);
+                accumulator.sessions += 1;
+                pushSample(accumulator.sampleSessionIds, journey.sessionId);
+                if (journey.errorPages.has(page)) {
+                    accumulator.errorSessions += 1;
+                }
+                if (journey.frustrationPages.has(page)) {
+                    accumulator.frustrationSessions += 1;
+                }
+            }
+            const next = journey.pages[index + 1];
+            if (next !== undefined && !nextSeen.has(`${page}\u0000${next}`)) {
+                nextSeen.add(`${page}\u0000${next}`);
+                accumulator.next.add(next);
+            }
+            const previous = journey.pages[index - 1];
+            if (previous !== undefined &&
+                !previousSeen.has(`${page}\u0000${previous}`)) {
+                previousSeen.add(`${page}\u0000${previous}`);
+                accumulator.previous.add(previous);
+            }
+        });
+        const entry = journey.pages[0];
+        const exit = journey.pages[journey.pages.length - 1];
+        get(entry).entries += 1;
+        get(exit).exits += 1;
+        if (journey.pages.length === 1) {
+            get(entry).bounces += 1;
+        }
+    }
+    const stats = Array.from(pages.entries()).map(([page, accumulator]) => {
+        return {
+            page: page,
+            sessions: accumulator.sessions,
+            views: accumulator.views,
+            entries: accumulator.entries,
+            exits: accumulator.exits,
+            bounces: accumulator.bounces,
+            exitRate: ratio(accumulator.exits, accumulator.sessions),
+            errorSessions: accumulator.errorSessions,
+            frustrationSessions: accumulator.frustrationSessions,
+            next: accumulator.next.top(USER_FLOW_MAX_NEIGHBOURS),
+            previous: accumulator.previous.top(USER_FLOW_MAX_NEIGHBOURS),
+            sampleSessionIds: accumulator.sampleSessionIds,
+        };
+    });
+    return stats.sort((a, b) => {
+        if (b.sessions !== a.sessions) {
+            return b.sessions - a.sessions;
+        }
+        return a.page < b.page ? -1 : a.page > b.page ? 1 : 0;
+    });
+}
+export function buildUserFlowPaths(journeys) {
+    const paths = new Map();
+    for (const journey of journeys) {
+        const isTruncated = journey.pages.length > USER_FLOW_MAX_PATH_LENGTH;
+        const pages = journey.pages.slice(0, USER_FLOW_MAX_PATH_LENGTH);
+        const key = `${pages.join("\u0000")}${isTruncated ? "\u0001" : ""}`;
+        let accumulator = paths.get(key);
+        if (!accumulator) {
+            accumulator = {
+                pages: pages,
+                isTruncated: isTruncated,
+                sessions: 0,
+                totalDurationMs: 0,
+                errorSessions: 0,
+                frustrationSessions: 0,
+                sampleSessionIds: [],
+            };
+            paths.set(key, accumulator);
+        }
+        accumulator.sessions += 1;
+        accumulator.totalDurationMs += Math.max(0, journey.durationMs);
+        if (journey.hadErrors) {
+            accumulator.errorSessions += 1;
+        }
+        if (journey.hadFrustration) {
+            accumulator.frustrationSessions += 1;
+        }
+        pushSample(accumulator.sampleSessionIds, journey.sessionId);
+    }
+    return Array.from(paths.values())
+        .sort((a, b) => {
+        if (b.sessions !== a.sessions) {
+            return b.sessions - a.sessions;
+        }
+        /* Longer journeys first among ties: they say more. */
+        if (b.pages.length !== a.pages.length) {
+            return b.pages.length - a.pages.length;
+        }
+        const aKey = a.pages.join("\u0000");
+        const bKey = b.pages.join("\u0000");
+        return aKey < bKey ? -1 : aKey > bKey ? 1 : 0;
+    })
+        .slice(0, USER_FLOW_MAX_PATHS)
+        .map((accumulator) => {
+        return {
+            pages: accumulator.pages,
+            isTruncated: accumulator.isTruncated,
+            sessions: accumulator.sessions,
+            share: ratio(accumulator.sessions, journeys.length),
+            avgDurationMs: ratio(accumulator.totalDurationMs, accumulator.sessions),
+            errorSessions: accumulator.errorSessions,
+            frustrationSessions: accumulator.frustrationSessions,
+            sampleSessionIds: accumulator.sampleSessionIds,
+        };
+    });
+}
+/*
+ * A -> B -> A, counted once per session and per unordered pair, so a
+ * visitor bouncing between a list and a detail page five times is one
+ * session with that loop - the question is how many PEOPLE go in circles.
+ */
+export function buildUserFlowLoops(journeys) {
+    const loops = new Map();
+    for (const journey of journeys) {
+        const seen = new Set();
+        for (let index = 0; index + 2 < journey.pages.length; index++) {
+            const first = journey.pages[index];
+            const middle = journey.pages[index + 1];
+            if (journey.pages[index + 2] !== first || middle === first) {
+                continue;
+            }
+            const [pageA, pageB] = first < middle ? [first, middle] : [middle, first];
+            const key = `${pageA}\u0000${pageB}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            let loop = loops.get(key);
+            if (!loop) {
+                loop = { pageA: pageA, pageB: pageB, sessions: 0, samples: [] };
+                loops.set(key, loop);
+            }
+            loop.sessions += 1;
+            pushSample(loop.samples, journey.sessionId);
+        }
+    }
+    return Array.from(loops.values())
+        .sort((a, b) => {
+        if (b.sessions !== a.sessions) {
+            return b.sessions - a.sessions;
+        }
+        const aKey = `${a.pageA}\u0000${a.pageB}`;
+        const bKey = `${b.pageA}\u0000${b.pageB}`;
+        return aKey < bKey ? -1 : aKey > bKey ? 1 : 0;
+    })
+        .slice(0, USER_FLOW_MAX_LOOPS)
+        .map((loop) => {
+        return {
+            pageA: loop.pageA,
+            pageB: loop.pageB,
+            sessions: loop.sessions,
+            share: ratio(loop.sessions, journeys.length),
+            sampleSessionIds: loop.samples,
+        };
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Summary and findings                                                */
+/* ------------------------------------------------------------------ */
+export function buildUserFlowSummary(journeys, pages) {
+    const lengths = journeys.map((journey) => {
+        return journey.pages.length;
+    });
+    const totalPages = lengths.reduce((sum, value) => {
+        return sum + value;
+    }, 0);
+    const bounces = lengths.filter((length) => {
+        return length === 1;
+    }).length;
+    const topBy = (pick) => {
+        const top = sortCounts(pages
+            .map((page) => {
+            return { page: page.page, sessions: pick(page) };
+        })
+            .filter((entry) => {
+            return entry.sessions > 0;
+        }));
+        return top[0] || null;
+    };
+    return {
+        sessions: journeys.length,
+        navigatingSessions: journeys.length - bounces,
+        bounceRate: ratio(bounces, journeys.length),
+        avgPagesPerSession: ratio(totalPages, journeys.length),
+        medianPagesPerSession: median(lengths),
+        uniquePages: pages.length,
+        topEntryPage: topBy((page) => {
+            return page.entries;
+        }),
+        topExitPage: topBy((page) => {
+            return page.exits;
+        }),
+    };
+}
+function formatShare(share) {
+    const percent = share * 100;
+    if (percent > 0 && percent < 1) {
+        return "<1%";
+    }
+    return `${Math.round(percent)}%`;
+}
+function sessionsNoun(count) {
+    return `${count} session${count === 1 ? "" : "s"}`;
+}
+/*
+ * At most one finding per kind, each over the sample floor, ordered by how
+ * much they should worry someone. Every number in the copy is one the page
+ * also shows, so a finding can always be checked against the map.
+ */
+export function buildUserFlowInsights(journeys, pages, loops) {
+    const total = journeys.length;
+    if (total === 0) {
+        return [];
+    }
+    const floor = Math.max(INSIGHT_MIN_SESSIONS, Math.ceil(total * INSIGHT_MIN_SHARE));
+    const qualifying = pages.filter((page) => {
+        return page.sessions >= floor;
+    });
+    const insights = [];
+    /*
+     * Error and frustration hotspots: the page where the largest SHARE of its
+     * visitors hit the problem, among pages with enough visitors.
+     */
+    const hotspot = (kind, pick) => {
+        const candidates = qualifying
+            .filter((page) => {
+            return pick(page) >= INSIGHT_MIN_SESSIONS;
+        })
+            .sort((a, b) => {
+            const difference = ratio(pick(b), b.sessions) - ratio(pick(a), a.sessions);
+            if (difference !== 0) {
+                return difference;
+            }
+            return pick(b) - pick(a);
+        });
+        const page = candidates[0];
+        if (!page) {
+            return;
+        }
+        const count = pick(page);
+        const share = ratio(count, page.sessions);
+        insights.push({
+            kind: kind,
+            tone: kind === "error-hotspot" ? "danger" : "warning",
+            title: kind === "error-hotspot"
+                ? `Errors concentrate on ${page.page}`
+                : `Frustration concentrates on ${page.page}`,
+            detail: kind === "error-hotspot"
+                ? `${formatShare(share)} of the sessions that visited ${page.page} hit an error there (${sessionsNoun(count)}).`
+                : `${formatShare(share)} of the sessions that visited ${page.page} rage-clicked, dead-clicked or reloaded in frustration there (${sessionsNoun(count)}).`,
+            page: page.page,
+            focusDirection: "forward",
+            sessions: count,
+            share: share,
+        });
+    };
+    hotspot("error-hotspot", (page) => {
+        return page.errorSessions;
+    });
+    /*
+     * Drop-off: the page that ends the most journeys that had somewhere else
+     * to go. Two kinds of page are left out, because they would win this
+     * every time and say nothing:
+     *  - bounces: a landing page everyone leaves is a marketing question;
+     *  - natural ends: a page almost nobody continues from ("order placed",
+     *    "signed out") is where journeys are MEANT to end. A page only counts
+     *    as a drop-off when a real share of its visitors do go on, which is
+     *    what makes the ones who left stand out. A page that is broken for
+     *    everyone is the error hotspot's finding, not this one.
+     */
+    const dropOff = qualifying
+        .filter((page) => {
+        return (page.exits - page.bounces >= INSIGHT_MIN_SESSIONS &&
+            ratio(page.sessions - page.exits, page.sessions) >=
+                DROP_OFF_MIN_CONTINUE_SHARE);
+    })
+        .sort((a, b) => {
+        const difference = ratio(b.exits - b.bounces, b.sessions - b.bounces) -
+            ratio(a.exits - a.bounces, a.sessions - a.bounces);
+        if (difference !== 0) {
+            return difference;
+        }
+        return b.exits - a.exits;
+    })[0];
+    if (dropOff) {
+        const leftAfterNavigating = dropOff.exits - dropOff.bounces;
+        const share = ratio(leftAfterNavigating, dropOff.sessions - dropOff.bounces);
+        insights.push({
+            kind: "drop-off",
+            tone: share >= 0.5 ? "danger" : "warning",
+            title: `Journeys end on ${dropOff.page}`,
+            detail: `${formatShare(share)} of the sessions that navigated to ${dropOff.page} left the application there (${sessionsNoun(leftAfterNavigating)}).`,
+            page: dropOff.page,
+            focusDirection: "backward",
+            sessions: leftAfterNavigating,
+            share: share,
+        });
+    }
+    hotspot("frustration-hotspot", (page) => {
+        return page.frustrationSessions;
+    });
+    const loop = loops[0];
+    if (loop && loop.sessions >= INSIGHT_MIN_SESSIONS) {
+        insights.push({
+            kind: "loop",
+            tone: "warning",
+            title: `Visitors go back and forth between ${loop.pageA} and ${loop.pageB}`,
+            detail: `${formatShare(loop.share)} of sessions (${sessionsNoun(loop.sessions)}) left one of these pages for the other and came straight back - often a sign that what they needed was not where they looked first.`,
+            page: loop.pageA,
+            secondaryPage: loop.pageB,
+            focusDirection: "forward",
+            sessions: loop.sessions,
+            share: loop.share,
+        });
+    }
+    const entry = [...pages].sort((a, b) => {
+        return b.entries - a.entries;
+    })[0];
+    if (entry && entry.entries > 0) {
+        const share = ratio(entry.entries, total);
+        insights.push({
+            kind: "top-entry",
+            tone: "neutral",
+            title: `Most sessions start on ${entry.page}`,
+            detail: `${formatShare(share)} of sessions (${sessionsNoun(entry.entries)}) landed on ${entry.page}; ${formatShare(ratio(entry.bounces, entry.entries))} of them saw no other page.`,
+            page: entry.page,
+            focusDirection: "forward",
+            sessions: entry.entries,
+            share: share,
+        });
+    }
+    return insights;
+}
+/* ------------------------------------------------------------------ */
+/* Entry point                                                         */
+/* ------------------------------------------------------------------ */
+export function normalizeUserFlowOptions(options) {
+    const merged = Object.assign(Object.assign({}, DEFAULT_USER_FLOW_OPTIONS), options);
+    return Object.assign(Object.assign({}, merged), { anchorPage: merged.anchorPage || null, direction: merged.direction === "backward" ? "backward" : "forward", steps: clamp(merged.steps, USER_FLOW_MIN_STEPS, USER_FLOW_MAX_STEPS), pagesPerStep: clamp(merged.pagesPerStep, USER_FLOW_MIN_PAGES_PER_STEP, USER_FLOW_MAX_PAGES_PER_STEP), hiddenPages: (merged.hiddenPages || []).filter((page) => {
+            /* The anchor cannot be hidden: the map would have nothing to draw. */
+            return Boolean(page) && page !== merged.anchorPage;
+        }) });
+}
+export function analyzeUserFlow(response, partialOptions = {}) {
+    const options = normalizeUserFlowOptions(partialOptions);
+    const { journeys, includesHost } = buildUserFlowJourneys(response, options);
+    const pages = buildUserFlowPageStats(journeys);
+    const loops = buildUserFlowLoops(journeys);
+    const deviceTypes = Array.from(new Set(response.sessions
+        .map((session) => {
+        return session.deviceType;
+    })
+        .filter(Boolean))).sort();
+    return {
+        summary: buildUserFlowSummary(journeys, pages),
+        graph: buildUserFlowGraph(journeys, options),
+        paths: buildUserFlowPaths(journeys),
+        pages: pages,
+        loops: loops,
+        insights: buildUserFlowInsights(journeys, pages, loops),
+        availablePages: pages.map((page) => {
+            return { page: page.page, sessions: page.sessions };
+        }),
+        deviceTypes: deviceTypes,
+        includesHost: includesHost,
+    };
+}
+//# sourceMappingURL=UserFlow.js.map