@pitcher/cli-scripts 3.1.1 → 3.3.0

package/dist/src/core/dsr-engagement.d.ts

@@ -0,0 +1,152 @@
+import type { DsrSessionEvent, DsrVisit, DsrVisitItem } from './dsr-visits.js';
+/**
+ * DSR engagement view (PIT-10067) aggregation: pure functions over `summarizeVisits` output and the native
+ * `canvas-details/viewers` response. The visit rule stays in `dsr-visits.ts` (D8); this module only classifies
+ * items, sums them per file and page, ports the Sharing Analytics page-count rule and maps the viewers route.
+ */
+export type DsrUnavailable = 'overview' | 'engagement' | 'total_shared' | 'viewer_share_counts' | 'most_viewed' | 'viewer_count' | 'viewer_list';
+export interface DsrHeader {
+    canvasName: string;
+    totalSections: number;
+    totalFiles: number;
+    viewers: number;
+    visits: number;
+    engagedSeconds: number;
+    /** overview.total_shared: ALL viewers, the viewer filter does not apply to it (spec 3.1 fact 7). */
+    forwards: number;
+    mostViewedFile: {
+        id: string;
+        name: string;
+        seconds: number;
+    } | null;
+    mostViewedSection: {
+        name: string;
+        enters: number;
+    } | null;
+    /** viewers.items[0].last_active of a page 1 sorted by last_active desc (the only read toHeader serves). */
+    lastActivity: string | null;
+}
+export interface DsrViewerRow {
+    /** normalized_email ?? email, VERBATIM: the drill key. Never trimmed or lowercased. */
+    identity: string;
+    isExternal: boolean;
+    visits: number;
+    engagedSeconds: number;
+    /** The viewer's local wall-clock time, no offset (D12). */
+    lastActive: string | null;
+    sectionsViewed: number;
+    filesViewed: number;
+    /** share_count: forwards by this address, counted over all viewers. */
+    forwards: number;
+}
+export interface DsrPageStat {
+    page: number;
+    seconds: number;
+    views: number;
+    viewers?: number;
+    estimated: boolean;
+}
+export interface DsrFileAgg {
+    fileId: string;
+    name: string;
+    seconds: number;
+    views: number;
+    viewers?: number;
+    estimated: boolean;
+    observed: DsrPageStat[];
+}
+export interface DsrSectionAgg {
+    id: string;
+    name: string;
+    seconds: number;
+    views: number;
+    viewers?: number;
+}
+/** One viewer's timeline, keyed by the identity it was read with. `names` holds only real entity names. */
+export interface DsrTimeline {
+    key: string;
+    visits: DsrVisit[];
+    names?: Record<string, string>;
+}
+export interface DsrFileMeta {
+    thumbnailUrl: string | null;
+    contentType: string | null;
+    contentLength: number | null;
+    thumbCount: number;
+}
+export declare const PAGES_MAX = 300;
+/** A Pitcher file id. */
+export declare const ULID: RegExp;
+/**
+ * D9: a page of a ULID file, `<fileId>/page/<n>` or the older `<fileId>/<n>` (0-based). Stricter than the
+ * route's unanchored PAGE_INDEX_SUFFIX: it requires a ULID file id, so `CollectionPlayer-<uuid>/3` is no page.
+ */
+export declare const PAGE_ID: RegExp;
+export type ItemClass = {
+    kind: 'section';
+} | {
+    kind: 'file';
+    fileId: string;
+} | {
+    kind: 'page';
+    fileId: string;
+    page: number;
+};
+/**
+ * By id shape, never `type` alone: the sessions route types an old-shape page (`<fileId>/<n>`) as `File`
+ * (spec 3.1 fact 2), and `dsr-visits` then gives it no page number.
+ */
+export declare function classifyItem(it: Pick<DsrVisitItem, 'type' | 'id'>): ItemClass;
+/**
+ * Entity names worth showing. The sessions route names an entity `nameMap.get(id) || entity_type || entity_id`;
+ * only the id, or a type word coming from `entity_type`, counts as no name.
+ */
+export declare function realNames(events: DsrSessionEvent[]): Record<string, string>;
+export declare const fileFallbackName: (fileId: string) => string;
+/**
+ * Per file and page over every visit of every timeline (spec 7.2 rules 1 to 3). Page items add to their file's
+ * page; file items to the file's own seconds and views. A file's seconds are the sum of its page seconds when it
+ * has any page item, else its own (D10, the viewers route's rule). Its views are its own Entered count, or, when
+ * only its pages were tracked, the number of visits that opened one of them. `viewers` counts distinct timeline
+ * keys and is set only when `countViewers`.
+ */
+export declare function aggregateFiles(timelines: DsrTimeline[], opts?: {
+    countViewers?: boolean;
+}): {
+    files: DsrFileAgg[];
+    sections: DsrSectionAgg[];
+};
+/**
+ * D11, the Sharing Analytics `SessionTimeline` page-count rule (spec 3.1 fact 12): video and audio have no pages;
+ * `meta = contentLength ?? thumbCount`; no observed pages: `meta >= 2 ? meta : 0`; `meta >= 2`: the larger of meta
+ * and the highest observed page; else the observed pages only (`dense: false`, no "of N").
+ */
+export declare function pageCountFor(meta: DsrFileMeta | undefined, observed: DsrPageStat[]): {
+    pageCount: number;
+    dense: boolean;
+};
+/** Dense: pages 1..pageCount with zeros; else the observed pages ascending. Capped at PAGES_MAX. */
+export declare function densePages(observed: DsrPageStat[], pageCount: number, dense: boolean, max?: number): {
+    pages: DsrPageStat[];
+    pagesTruncated?: number;
+};
+/** `stripExternalMarker` of `@pitcher/analytics-shared` (case kept; a bare marker keeps the raw value). */
+export declare function stripExternalMarker(identity: string): string;
+/**
+ * Content sample keys (R1-09): the sessions route matches `{verbatim, stripped, stripped + marker}`, so a stripped
+ * key covers both forms of an address. First occurrence wins; at most `max` keys.
+ */
+export declare function dedupeIdentities(ids: string[], max: number): string[];
+export declare function toViewerRow(row: Record<string, unknown>): DsrViewerRow;
+/** The header of a native viewers response read as page 1 sorted by last_active desc. */
+export declare function toHeader(native: Record<string, unknown>): DsrHeader;
+export declare const DSR_UNAVAILABLE: readonly DsrUnavailable[];
+export declare function unavailableOf(native: Record<string, unknown>): DsrUnavailable[];
+/** "2026-11-08 14:05" from the viewer's naive wall-clock; "unknown-date" for null; anything else verbatim. */
+export declare function naiveMinute(ts: string | null | undefined): string;
+/** "2026-11-08", as naiveMinute. */
+export declare function naiveDate(ts: string | null | undefined): string;
+/** D20, Sharing Analytics `formatDuration`: "45s", "22m", "2h", "1h 12m" (floored). */
+export declare function fmtDuration(seconds: number): string;
+/** "3-6, 9, 12-14" from ascending or unsorted page numbers. */
+export declare function compressRanges(nums: number[]): string;

package/dist/src/core/dsr-engagement.js

@@ -0,0 +1,301 @@
+export const PAGES_MAX = 300;
+/** A Pitcher file id. */
+export const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+/**
+ * D9: a page of a ULID file, `<fileId>/page/<n>` or the older `<fileId>/<n>` (0-based). Stricter than the
+ * route's unanchored PAGE_INDEX_SUFFIX: it requires a ULID file id, so `CollectionPlayer-<uuid>/3` is no page.
+ */
+export const PAGE_ID = /^([0-9A-HJKMNP-TV-Z]{26})\/(?:page\/)?(\d+)$/i;
+/**
+ * By id shape, never `type` alone: the sessions route types an old-shape page (`<fileId>/<n>`) as `File`
+ * (spec 3.1 fact 2), and `dsr-visits` then gives it no page number.
+ */
+export function classifyItem(it) {
+    if (it.type === 'section')
+        return { kind: 'section' };
+    const m = PAGE_ID.exec(it.id);
+    return m ? { kind: 'page', fileId: m[1], page: Number(m[2]) + 1 } : { kind: 'file', fileId: it.id };
+}
+/**
+ * Event and component type words: the only `entity_type` values that are a fallback rather than a name. The
+ * sessions route selects `whatType AS entity_type`, and for DSR File, Page and Section events `whatType` is the
+ * item's tracked TITLE, so a name equal to `entity_type` is usually the real one (PR 6010 review). The component
+ * names are the route's `COMPONENT_TYPES_WITH_FILE_TRACKING` (`@pitcher/analytics-shared`'s
+ * COLLECTION_COMPONENT_EVENT_NAMES plus ContentPlayer); cli-scripts does not depend on that package. SectionList,
+ * Multimedia, Grid and Text are canvas component types also seen in `whatType` on EU DSR traffic.
+ */
+const TYPE_WORDS = new Set([
+    'File',
+    'Page',
+    'Section',
+    'Canvas',
+    'CollectionPlayer',
+    'Collection',
+    'ContentPlayer',
+    'SectionList',
+    'Multimedia',
+    'Grid',
+    'Text',
+]);
+/**
+ * Entity names worth showing. The sessions route names an entity `nameMap.get(id) || entity_type || entity_id`;
+ * only the id, or a type word coming from `entity_type`, counts as no name.
+ */
+export function realNames(events) {
+    const out = {};
+    for (const e of events) {
+        const n = e.entity_name;
+        if (!n || n === e.entity_id || (n === e.entity_type && TYPE_WORDS.has(n)) || e.entity_id in out)
+            continue;
+        out[e.entity_id] = n;
+    }
+    return out;
+}
+export const fileFallbackName = (fileId) => `File ${fileId.slice(0, 8)}`;
+/**
+ * Per file and page over every visit of every timeline (spec 7.2 rules 1 to 3). Page items add to their file's
+ * page; file items to the file's own seconds and views. A file's seconds are the sum of its page seconds when it
+ * has any page item, else its own (D10, the viewers route's rule). Its views are its own Entered count, or, when
+ * only its pages were tracked, the number of visits that opened one of them. `viewers` counts distinct timeline
+ * keys and is set only when `countViewers`.
+ */
+export function aggregateFiles(timelines, opts = {}) {
+    const files = new Map();
+    const sections = new Map();
+    const fileAcc = (fileId, names) => {
+        let f = files.get(fileId);
+        if (!f) {
+            f = {
+                fileId,
+                name: names[fileId] ?? null,
+                ownSeconds: 0,
+                ownViews: 0,
+                ownEstimated: false,
+                hasFileItem: false,
+                pages: new Map(),
+                keys: new Set(),
+                visitsTouching: 0,
+            };
+            files.set(fileId, f);
+        }
+        else if (!f.name && names[fileId]) {
+            f.name = names[fileId];
+        }
+        return f;
+    };
+    for (const t of timelines) {
+        const names = t.names ?? {};
+        for (const v of t.visits) {
+            const touched = new Set();
+            for (const it of v.items) {
+                const c = classifyItem(it);
+                if (c.kind === 'section') {
+                    let s = sections.get(it.id);
+                    if (!s) {
+                        s = { id: it.id, name: names[it.id] ?? it.name, seconds: 0, views: 0, keys: new Set() };
+                        sections.set(it.id, s);
+                    }
+                    s.seconds += it.seconds;
+                    s.views += it.views;
+                    s.keys.add(t.key);
+                    continue;
+                }
+                const f = fileAcc(c.fileId, names);
+                f.keys.add(t.key);
+                touched.add(c.fileId);
+                if (c.kind === 'file') {
+                    f.hasFileItem = true;
+                    f.ownSeconds += it.seconds;
+                    f.ownViews += it.views;
+                    f.ownEstimated || (f.ownEstimated = it.estimated);
+                }
+                else {
+                    let p = f.pages.get(c.page);
+                    if (!p) {
+                        p = { seconds: 0, views: 0, estimated: false, keys: new Set() };
+                        f.pages.set(c.page, p);
+                    }
+                    p.seconds += it.seconds;
+                    p.views += it.views;
+                    p.estimated || (p.estimated = it.estimated);
+                    p.keys.add(t.key);
+                }
+            }
+            for (const id of touched)
+                files.get(id).visitsTouching += 1;
+        }
+    }
+    const count = opts.countViewers === true;
+    const outFiles = Array.from(files.values()).map((f) => {
+        const observed = Array.from(f.pages.entries())
+            .sort(([a], [b]) => a - b)
+            .map(([page, p]) => ({
+            page,
+            seconds: p.seconds,
+            views: p.views,
+            ...(count ? { viewers: p.keys.size } : {}),
+            estimated: p.estimated,
+        }));
+        const paged = observed.length > 0;
+        return {
+            fileId: f.fileId,
+            name: f.name ?? fileFallbackName(f.fileId),
+            seconds: paged ? observed.reduce((n, p) => n + p.seconds, 0) : f.ownSeconds,
+            views: f.hasFileItem && f.ownViews > 0 ? f.ownViews : f.visitsTouching,
+            ...(count ? { viewers: f.keys.size } : {}),
+            estimated: paged ? observed.some((p) => p.estimated) : f.ownEstimated,
+            observed,
+        };
+    });
+    outFiles.sort((a, b) => b.seconds - a.seconds || a.name.localeCompare(b.name, 'en') || a.fileId.localeCompare(b.fileId));
+    const outSections = Array.from(sections.values())
+        .map(({ keys, ...s }) => (count ? { ...s, viewers: keys.size } : s))
+        .sort((a, b) => b.seconds - a.seconds || a.name.localeCompare(b.name, 'en'));
+    return { files: outFiles, sections: outSections };
+}
+/**
+ * D11, the Sharing Analytics `SessionTimeline` page-count rule (spec 3.1 fact 12): video and audio have no pages;
+ * `meta = contentLength ?? thumbCount`; no observed pages: `meta >= 2 ? meta : 0`; `meta >= 2`: the larger of meta
+ * and the highest observed page; else the observed pages only (`dense: false`, no "of N").
+ */
+export function pageCountFor(meta, observed) {
+    const type = (meta?.contentType ?? '').toLowerCase();
+    if (type.startsWith('video') || type.startsWith('audio'))
+        return { pageCount: 0, dense: false };
+    const m = meta ? (meta.contentLength ?? meta.thumbCount) : 0;
+    if (!observed.length)
+        return m >= 2 ? { pageCount: m, dense: true } : { pageCount: 0, dense: false };
+    if (m >= 2)
+        return { pageCount: Math.max(m, ...observed.map((p) => p.page)), dense: true };
+    return { pageCount: new Set(observed.map((p) => p.page)).size, dense: false };
+}
+/** Dense: pages 1..pageCount with zeros; else the observed pages ascending. Capped at PAGES_MAX. */
+export function densePages(observed, pageCount, dense, max = PAGES_MAX) {
+    if (pageCount === 0)
+        return { pages: [] };
+    let pages;
+    if (dense) {
+        const byPage = new Map(observed.map((p) => [p.page, p]));
+        const withViewers = observed.some((p) => p.viewers !== undefined);
+        // build only what is kept: pageCount comes from the file's metadata, unbounded
+        pages = Array.from({ length: Math.min(pageCount, max) }, (_, i) => byPage.get(i + 1) ?? { page: i + 1, seconds: 0, views: 0, ...(withViewers ? { viewers: 0 } : {}), estimated: false });
+        return pageCount > max ? { pages, pagesTruncated: pageCount - max } : { pages };
+    }
+    pages = [...observed].sort((a, b) => a.page - b.page);
+    return pages.length > max ? { pages: pages.slice(0, max), pagesTruncated: pages.length - max } : { pages };
+}
+const EXTERNAL_MARKER = ' (External)';
+/** `stripExternalMarker` of `@pitcher/analytics-shared` (case kept; a bare marker keeps the raw value). */
+export function stripExternalMarker(identity) {
+    if (!identity.endsWith(EXTERNAL_MARKER))
+        return identity;
+    return identity.slice(0, -EXTERNAL_MARKER.length) || identity;
+}
+/**
+ * Content sample keys (R1-09): the sessions route matches `{verbatim, stripped, stripped + marker}`, so a stripped
+ * key covers both forms of an address. First occurrence wins; at most `max` keys.
+ */
+export function dedupeIdentities(ids, max) {
+    const out = [];
+    const seen = new Set();
+    for (const id of ids) {
+        const key = stripExternalMarker(id);
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(key);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+const num = (x) => Number(x) || 0;
+const str = (x) => (typeof x === 'string' && x !== '' ? x : null);
+const obj = (x) => x && typeof x === 'object' ? x : {};
+export function toViewerRow(row) {
+    const identity = typeof row.normalized_email === 'string' ? row.normalized_email : typeof row.email === 'string' ? row.email : '';
+    return {
+        identity,
+        isExternal: row.is_external === true,
+        visits: num(row.session_count),
+        engagedSeconds: num(row.total_engagement_time),
+        lastActive: str(row.last_active),
+        sectionsViewed: num(row.sections_viewed),
+        filesViewed: num(row.files_viewed),
+        forwards: num(row.share_count),
+    };
+}
+/** The header of a native viewers response read as page 1 sorted by last_active desc. */
+export function toHeader(native) {
+    const o = obj(native.overview);
+    const val = (k) => num(obj(o[k]).value);
+    const file = o.most_viewed_file ? obj(o.most_viewed_file) : null;
+    const section = o.most_viewed_section ? obj(o.most_viewed_section) : null;
+    const items = obj(native.viewers).items;
+    const first = Array.isArray(items) && items.length ? obj(items[0]) : null;
+    return {
+        canvasName: typeof native.canvas_name === 'string' ? native.canvas_name : '',
+        totalSections: num(native.total_sections),
+        totalFiles: num(native.total_files),
+        viewers: val('total_viewers'),
+        visits: val('total_sessions'),
+        engagedSeconds: val('total_engagement_time'),
+        forwards: val('total_shared'),
+        mostViewedFile: file ? { id: String(file.id ?? ''), name: String(file.name ?? ''), seconds: num(file.value) } : null,
+        mostViewedSection: section ? { name: String(section.name ?? ''), enters: num(section.value) } : null,
+        lastActivity: first ? str(first.last_active) : null,
+    };
+}
+export const DSR_UNAVAILABLE = [
+    'overview',
+    'engagement',
+    'total_shared',
+    'viewer_share_counts',
+    'most_viewed',
+    'viewer_count',
+    'viewer_list',
+];
+export function unavailableOf(native) {
+    const u = obj(native._meta).unavailable;
+    return Array.isArray(u) ? u.filter((x) => DSR_UNAVAILABLE.includes(x)) : [];
+}
+// ── naive timestamps (D12) and durations (D20) ───────────────────────────────
+const NAIVE = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2})(?::\d{2})?$/;
+/** "2026-11-08 14:05" from the viewer's naive wall-clock; "unknown-date" for null; anything else verbatim. */
+export function naiveMinute(ts) {
+    if (!ts)
+        return 'unknown-date';
+    const m = NAIVE.exec(ts);
+    return m ? `${m[1]} ${m[2]}` : ts;
+}
+/** "2026-11-08", as naiveMinute. */
+export function naiveDate(ts) {
+    if (!ts)
+        return 'unknown-date';
+    const m = NAIVE.exec(ts);
+    return m ? m[1] : ts;
+}
+/** D20, Sharing Analytics `formatDuration`: "45s", "22m", "2h", "1h 12m" (floored). */
+export function fmtDuration(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m`;
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    return m ? `${h}h ${m}m` : `${h}h`;
+}
+/** "3-6, 9, 12-14" from ascending or unsorted page numbers. */
+export function compressRanges(nums) {
+    const xs = Array.from(new Set(nums)).sort((a, b) => a - b);
+    const parts = [];
+    for (let i = 0; i < xs.length;) {
+        let j = i;
+        while (j + 1 < xs.length && xs[j + 1] === xs[j] + 1)
+            j += 1;
+        parts.push(i === j ? String(xs[i]) : `${xs[i]}-${xs[j]}`);
+        i = j + 1;
+    }
+    return parts.join(', ');
+}

package/dist/src/core/dsr-visits.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One DSR viewer's event timeline (`/analytics/canvas-details/sessions`) → visits, and per visit the
+ * sections, files and pages viewed with their time (PIT-9589). The visit rule is the Sharing
+ * Analytics app's (`packages/apps/canvas-analytics/src/lib/reconstructSessions.ts`): a visit opens
+ * on an `Entered` of the canvas itself and is keyed by its `event_pair_id`; its engaged time is the
+ * sum of its focus segments (canvas Entered → Exited). Change them together.
+ *
+ * Item time: the sum of the item's `Exited` durations (`forhowlong`, seconds) in the visit. An
+ * `Entered` with no `Exited` (the unload beacon was dropped, PIT-5833) or an `Exited` reporting 0 is
+ * estimated from the gap to the next event of the visit, as the app's timeline does, and flagged
+ * `estimated`.
+ */
+export interface DsrSessionEvent {
+    timestamp: string;
+    action: string;
+    entity_id: string;
+    entity_type?: string;
+    entity_name?: string;
+    original_event_name: string;
+    duration?: number;
+    event_pair_id?: string;
+}
+export interface DsrVisitItem {
+    type: 'section' | 'file' | 'page';
+    id: string;
+    name: string;
+    page_number?: number;
+    views: number;
+    seconds: number;
+    estimated: boolean;
+}
+export interface DsrVisit {
+    visit: number;
+    started_at: string;
+    ended_at: string;
+    engaged_seconds: number;
+    items: DsrVisitItem[];
+}
+/** `reconstructSessions`' grouping: events from an anchor `Entered` until the next one, by pair key. */
+export declare function groupVisits(events: DsrSessionEvent[], anchorId: string): DsrSessionEvent[][];
+/** `computeEngagementDuration`: the wall-clock of each canvas focus segment, summed. */
+export declare function engagedSeconds(events: DsrSessionEvent[], anchorId: string): number;
+export declare function summarizeVisits(events: DsrSessionEvent[], canvasId: string): DsrVisit[];
+/** RFC 4180 cell; a leading = + - @ is prefixed with ' so a spreadsheet never runs it as a formula. */
+export declare function csvCell(v: unknown): string;
+export declare const VISITS_CSV_HEADER: string[];
+export declare function visitsToCsv(viewers: Array<{
+    viewer: string;
+    visits: DsrVisit[];
+}>): string;