@pitcher/cli-scripts 3.2.0 → 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/envelope.d.ts

@@ -6,6 +6,7 @@ export interface Envelope<T> {
         code: ErrorCodeName;
         exitCode: number;
         message: string;
+        backendStatus?: number;
     };
     warnings?: string[];
 }

package/dist/src/core/envelope.js

@@ -4,7 +4,12 @@ export function ok(data, warnings) {
 export function fail(error, warnings) {
     return {
         ok: false,
-        error: { code: error.code, exitCode: error.exitCode, message: error.message },
+        error: {
+            code: error.code,
+            exitCode: error.exitCode,
+            message: error.message,
+            ...(error.backendStatus ? { backendStatus: error.backendStatus } : {}),
+        },
         ...(warnings?.length ? { warnings } : {}),
     };
 }

package/dist/src/core/errors.d.ts

@@ -13,6 +13,8 @@ export interface CliError {
     code: ErrorCodeName;
     exitCode: number;
     message: string;
+    /** HTTP status of the backend's error answer, when the failure came from a backend response (PIT-10114 audit). */
+    backendStatus?: number;
 }
-export declare function createCliError(code: ErrorCodeName, message: string): CliError;
+export declare function createCliError(code: ErrorCodeName, message: string, backendStatus?: number): CliError;
 export declare function isCliError(e: unknown): e is CliError;

package/dist/src/core/errors.js

@@ -7,8 +7,8 @@ export const ERROR_CODES = {
     NOT_FOUND: 5,
     CONFLICT: 6,
 };
-export function createCliError(code, message) {
-    return { __cliError: true, code, exitCode: ERROR_CODES[code], message };
+export function createCliError(code, message, backendStatus) {
+    return { __cliError: true, code, exitCode: ERROR_CODES[code], message, ...(backendStatus ? { backendStatus } : {}) };
 }
 export function isCliError(e) {
     if (typeof e !== 'object' || e === null)

package/dist/src/core/http.js

@@ -242,15 +242,17 @@ export function toCliError(e) {
     const apiMessage = extractApiMessage(data, err.message || 'Request failed');
     const status = err.response?.status;
     if (typeof status === 'number') {
+        // backendStatus: the backend answered (PIT-10114). A backend 4xx also maps to VALIDATION, so the code alone
+        // cannot tell a local check from a backend answer.
         if (status === 401 || status === 403)
-            return createCliError('AUTH', apiMessage);
+            return createCliError('AUTH', apiMessage, status);
         if (status === 404)
-            return createCliError('NOT_FOUND', apiMessage);
+            return createCliError('NOT_FOUND', apiMessage, status);
         if (status === 409)
-            return createCliError('CONFLICT', apiMessage);
+            return createCliError('CONFLICT', apiMessage, status);
         if (status >= 400 && status < 500)
-            return createCliError('VALIDATION', apiMessage);
-        return createCliError('NETWORK', apiMessage);
+            return createCliError('VALIDATION', apiMessage, status);
+        return createCliError('NETWORK', apiMessage, status);
     }
     if (err.isAxiosError)
         return createCliError('NETWORK', apiMessage);

package/dist/src/core/ld.js

@@ -423,7 +423,8 @@ export function toLdCliError(e) {
                     : s && s >= 400 && s < 500
                         ? 'VALIDATION'
                         : 'NETWORK';
-        return createCliError(code, msg);
+        // the L&D backend answered: keep its status for the PIT-10114 audit (`backendStatus`)
+        return createCliError(code, msg, typeof s === 'number' ? s : undefined);
     }
     return toCliError(e);
 }

package/dist/src/core/me.d.ts

@@ -0,0 +1,3 @@
+import type { AxiosInstance } from 'axios';
+/** The caller's Pitcher user id (Django `GET /api/v1/users/me/`), as a string. PIT-10113: the actor of a confirmed write. */
+export declare function getMeId(client: AxiosInstance): Promise<string>;

package/dist/src/core/me.js

@@ -0,0 +1,10 @@
+import { createCliError } from './errors.js';
+/** The caller's Pitcher user id (Django `GET /api/v1/users/me/`), as a string. PIT-10113: the actor of a confirmed write. */
+export async function getMeId(client) {
+    const res = await client.get('/api/v1/users/me/');
+    const id = res.data?.id;
+    const s = typeof id === 'number' ? String(id) : typeof id === 'string' ? id : '';
+    if (!/^[0-9]{1,9}$/.test(s))
+        throw createCliError('AUTH', 'could not read your Pitcher user id');
+    return s;
+}

package/dist/src/core/roleplay-stats.d.ts

@@ -2,8 +2,11 @@
  * The AI Roleplay manager-app's per-rep rules, ported 1:1 so the MCP team tool and the manager
  * app give the same answer on the same data (PIT-9200). Sources, in ng-production-apps
  * `pitcher-coach/manager-app/src/`: `lib/session-score.ts` (reading a score), `lib/stats.ts`
- * (best, mean, trend), `lib/status.ts` (`deriveStatus`) and `hooks/useManagerData.ts`
- * (`getAssignmentSessions`, `getRepStats`). Change them together.
+ * (best, mean, trend, `normalizeScore`), `lib/status.ts` (`deriveStatus`),
+ * `hooks/useManagerData.ts` (`getAssignmentSessions`, `getRepStats`),
+ * `components/SkillBreakdown.tsx` (`latestSkills`) and `lib/api.ts` (`loadAssignmentProgress`,
+ * ported as `loadTeamModel` in `commands/roleplay.ts`). Since PIT-9971 status, session count, best
+ * score and last session come from the server's pass progress when it is known. Change them together.
  *
  * The one rule every aggregate here obeys: a session is unscored iff `overallScore` is not a
  * finite number. An unscored session is never read as 0.
@@ -15,11 +18,13 @@ export interface RoleplaySessionLike {
     overallScore?: number | null;
     durationMs?: number | null;
     evaluation?: {
+        grading_scale?: number | string | null;
         category_scores?: Array<{
             id?: string;
             skillId?: string;
             title?: string;
             score?: number;
+            max_score?: number | string | null;
         }>;
     } | null;
 }
@@ -32,6 +37,14 @@ export interface RoleplayAssignmentLike {
     resolvedUserIds: string[];
 }
 export type RepStatus = 'passed' | 'in_progress' | 'not_started' | 'overdue' | 'needs_coaching';
+/** next-core's pass progress for one (assignment, rep) pair over ALL its sessions (PIT-9971). */
+export interface AssignmentProgressLike {
+    passed: boolean;
+    passSource: 'stored' | 'live' | null;
+    attempts: number;
+    bestScore: number | null;
+    latestAt: string | null;
+}
 /** The session's score, or null when it has none (`toFiniteOrNull`). */
 export declare function sessionScore(session: RoleplaySessionLike): number | null;
 /** Mean of the finite values, rounded, or null when none are finite (`meanOfFinite`). */
@@ -46,10 +59,13 @@ export declare const scoredCount: (sessions: RoleplaySessionLike[]) => number;
 /** Up to 3 sessions per end, capped at half the scored series (`calcTrend`). */
 export declare function calcTrend(sessions: RoleplaySessionLike[]): number | null;
 /**
- * `deriveStatus`: the raw best score is compared with `passingScore` as stored (legacy
- * evaluations may grade on a 5-point scale; the manager app does not normalise either).
+ * `deriveStatus`: the raw best score is compared with `passingScore` as stored, as the manager app
+ * does. `overallScore` is 0..100 on every evaluation, legacy ones included (their `grading_scale` of 5
+ * applies to the category scores only), so never normalise it here.
+ * With `progress`, passed and started come from the server; only `needs_coaching` (a judgement
+ * on the recent trend) reads the capped list. Without it, everything comes from the list.
  */
-export declare function deriveStatus(sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date): RepStatus;
+export declare function deriveStatus(sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date, progress?: AssignmentProgressLike | null): RepStatus;
 /** `getAssignmentSessions`: same scenario, a rep of the assignment, on or after it was created. */
 export declare function assignmentSessions<T extends RoleplaySessionLike>(sessions: T[], assignment: RoleplayAssignmentLike): T[];
 export interface RepStats {
@@ -62,9 +78,34 @@ export interface RepStats {
     status: RepStatus;
     last_session_at: string | null;
     total_duration_ms: number;
+    /** Progress counts more attempts than the list holds: avg_score, scored_sessions and trend cover recent sessions only. */
+    recent_only: boolean;
+    pass_source: 'stored' | 'live' | null;
 }
-/** `getRepStats` for one rep of one assignment, without the raw sessions. */
-export declare function repStats(userId: string, sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date): RepStats;
+/**
+ * `getRepStats` for one rep of one assignment, without the raw sessions. With `progress`, sessions,
+ * best score and last session come from the server; average, scored count and trend stay on the list.
+ */
+export declare function repStats(userId: string, sessions: RoleplaySessionLike[], assignment: RoleplayAssignmentLike, now?: Date, progress?: AssignmentProgressLike | null): RepStats;
+/** A grading scale: a finite positive number, or a string `Number()` turns into one; else null (D28). */
+export declare function scaleOrNull(v: unknown): number | null;
+/** `normalizeScore` (manager-app `lib/stats.ts`): a score on `max` as 0..100; no usable max = as is. */
+export declare function normalizeScore(score: number, max?: number | null): number;
+export interface LatestSkill {
+    skillId: string;
+    title: string;
+    score: number;
+}
+/**
+ * The Rep panel's skills (`SkillBreakdown`): the NEWEST session with at least one category score,
+ * scored or not, its categories normalised on `max_score ?? grading_scale ?? 100`, weakest first.
+ * Categories without a finite score are skipped; null when none remain. Never averaged across
+ * sessions, so 5-point and 100-point evaluations are never mixed.
+ */
+export declare function latestSkills<T extends RoleplaySessionLike>(sessions: T[]): {
+    session: T;
+    skills: LatestSkill[];
+} | null;
 export interface SkillAverage {
     skill_id: string;
     title: string;