Session 45: Snapshot pipeline + GameCard swap + live ticker (2100 tests)
The on-demand "Read" grade model is RETIRED. A scheduled pipeline pre-grades the
slate, locks grades to the line, tracks movement; the dashboard shows them already
there. Orchestrates existing services — nothing rebuilt.
- snapshotService.runSnapshot(sport): getOdds → gradeAndCacheSlate → classify
archetype per player → lock gradedAt → line deltas vs previous snapshot → write
snapshot:{sport}:latest/previous + grades:{sport} → ticker events. Fully
injectable, zero-network unit tests. runAllSnapshots = cron entrypoint.
- Internal trigger POST /api/internal/snapshot/:sport + /all (requireInternalAuth).
In-process cron (SNAPSHOT_CRON=1, UTC 14,19,22,1,3) in server.js, no new dep.
- Public reads: GET /api/snapshot/:sport (cache-only) + GET /api/ticker (merges
TICKER_MANUAL pins) + Next proxies.
- GameCard swap: live Slate renders vyndr/GameCard (legacy kept for types only),
overlays locked grades onto game props → player name once + archetype badge +
"Graded Xh ago at -115 · Current 2.5 · ▲ TOWARD +1.0". Ungraded → "Awaiting next
scan", NO Read button. On-demand onGrade flow deleted.
- Ticker polls /api/ticker every 30s, graceful fallback to hardcoded items.
- NBA/WNBA: espnStatsAdapter free fallback (defensive parse → found:false on shape
mismatch) wired into resolvePlayerStats after the offline Python service.
Env: PROPLINE_API_KEY_1/2/3, VYNDR_INTERNAL_KEY, SNAPSHOT_CRON=1, TICKER_MANUAL.
Backend 2061 -> 2100 tests (+39), 173 suites. Web build clean (exit 0).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,111 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* espnStatsAdapter — best-effort NBA/WNBA season averages from ESPN (Session 45).
|
||||
*
|
||||
* The primary NBA/WNBA stats source (`nbaStatsClient`) depends on a Python
|
||||
* nba_api service that is frequently offline in prod. This adapter is a FREE,
|
||||
* no-auth fallback off ESPN's public site API. It is intentionally DEFENSIVE:
|
||||
* any shape it doesn't recognize → null (the caller degrades to found:false),
|
||||
* never a throw and never a wrong-but-confident number.
|
||||
*
|
||||
* Parsing is tolerant by design (ESPN's athlete-stats JSON varies by sport and
|
||||
* season), so `parseAthleteStats` is a pure, unit-tested function.
|
||||
*/
|
||||
|
||||
const axios = require('axios');
|
||||
const { cacheGet, cacheSet } = require('../../utils/redis');
|
||||
|
||||
const SEARCH = 'https://site.web.api.espn.com/apis/common/v3/search';
|
||||
const SPORT_PATH = { nba: 'basketball/nba', wnba: 'basketball/wnba' };
|
||||
const TTL = 6 * 3600;
|
||||
const TIMEOUT = 10_000;
|
||||
|
||||
// ESPN stat label → our classifier-input key. Lowercased, punctuation-stripped.
|
||||
const STAT_MAP = {
|
||||
pointspergame: 'ppg', avgpoints: 'ppg', points: 'ppg', ppg: 'ppg',
|
||||
reboundspergame: 'rpg', avgrebounds: 'rpg', rebounds: 'rpg', rpg: 'rpg', totalrebounds: 'rpg',
|
||||
assistspergame: 'apg', avgassists: 'apg', assists: 'apg', apg: 'apg',
|
||||
blockspergame: 'bpg', avgblocks: 'bpg', blocks: 'bpg', bpg: 'bpg',
|
||||
stealspergame: 'spg', avgsteals: 'spg', steals: 'spg', spg: 'spg',
|
||||
threepointfieldgoalsmade: 'threes', threepointfieldgoalspergame: 'threes', avg3pointfieldgoalsmade: 'threes',
|
||||
};
|
||||
|
||||
const keyify = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]/g, '');
|
||||
|
||||
/**
|
||||
* Walk an ESPN athlete-stats payload and pull out per-game averages we can
|
||||
* classify. Returns a classifier-input object (possibly partial) or null when
|
||||
* nothing usable is found.
|
||||
*/
|
||||
function parseAthleteStats(payload) {
|
||||
if (!payload || typeof payload !== 'object') return null;
|
||||
const out = {};
|
||||
// ESPN nests stats under categories[].stats[] with { name|abbreviation, value|displayValue }.
|
||||
const categories = payload?.statistics?.splits?.categories
|
||||
|| payload?.splits?.categories
|
||||
|| payload?.categories
|
||||
|| [];
|
||||
const visit = (statArr) => {
|
||||
for (const st of statArr || []) {
|
||||
const label = keyify(st.name || st.abbreviation || st.label);
|
||||
const mapped = STAT_MAP[label];
|
||||
if (!mapped) continue;
|
||||
const val = Number(st.value != null ? st.value : st.displayValue);
|
||||
if (Number.isFinite(val) && out[mapped] == null) out[mapped] = val;
|
||||
}
|
||||
};
|
||||
for (const cat of categories) visit(cat.stats);
|
||||
if (Array.isArray(payload.stats)) visit(payload.stats); // flat fallback
|
||||
return Object.keys(out).length > 0 ? out : null;
|
||||
}
|
||||
|
||||
async function fetchJson(url, http) {
|
||||
const client = http || axios;
|
||||
const res = await client.get(url, { timeout: TIMEOUT });
|
||||
return res && res.data;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a player's NBA/WNBA season averages from ESPN. Returns
|
||||
* { found, team, position, classifierInput } or { found:false }. Never throws.
|
||||
* opts.http injectable for tests.
|
||||
*/
|
||||
async function getSeasonAverages(name, sport, opts = {}) {
|
||||
const sp = String(sport || '').toLowerCase();
|
||||
const path = SPORT_PATH[sp];
|
||||
if (!path || !name) return { found: false };
|
||||
const cacheKey = `espnstats:${sp}:${keyify(name)}`;
|
||||
try {
|
||||
const cached = await cacheGet(cacheKey);
|
||||
if (cached) return cached;
|
||||
} catch { /* ignore */ }
|
||||
|
||||
try {
|
||||
// 1. Resolve the athlete id via ESPN search.
|
||||
const search = await fetchJson(`${SEARCH}?query=${encodeURIComponent(name)}&limit=5&sport=${encodeURIComponent(path)}`, opts.http);
|
||||
const items = (search && (search.items || search.results)) || [];
|
||||
const athlete = items.find((it) => keyify(it.displayName || it.name) === keyify(name)) || items[0];
|
||||
const id = athlete && (athlete.id || athlete.uid || (athlete.athlete && athlete.athlete.id));
|
||||
if (!id) return { found: false };
|
||||
|
||||
// 2. Fetch that athlete's stats overview.
|
||||
const stats = await fetchJson(`https://site.web.api.espn.com/apis/common/v3/sports/${path}/athletes/${id}/stats`, opts.http);
|
||||
const classifierInput = parseAthleteStats(stats);
|
||||
if (!classifierInput) return { found: false };
|
||||
|
||||
const result = {
|
||||
found: true,
|
||||
team: (athlete.team && (athlete.team.abbreviation || athlete.team.displayName)) || '',
|
||||
position: (athlete.position && athlete.position.abbreviation) || '',
|
||||
classifierInput,
|
||||
};
|
||||
try { await cacheSet(cacheKey, result, TTL); } catch { /* ignore */ }
|
||||
return result;
|
||||
} catch (err) {
|
||||
console.warn('[espnStats] season averages failed:', name, sp, err.message);
|
||||
return { found: false };
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = { getSeasonAverages, parseAthleteStats, __internals: { STAT_MAP, keyify, SPORT_PATH } };
|
||||
@@ -124,15 +124,26 @@ async function resolvePlayerStats(name, sport, opts = {}) {
|
||||
};
|
||||
}
|
||||
if (sp === 'nba' || sp === 'wnba') {
|
||||
// NBA/WNBA stats come from the Python nba_api service (nbaStatsClient).
|
||||
// It's frequently offline in prod (localhost service) — degrade quietly.
|
||||
// PRIMARY: the Python nba_api service (nbaStatsClient) — often offline in
|
||||
// prod. FALLBACK: ESPN's free public stats (espnStatsAdapter). Either way,
|
||||
// a miss degrades quietly to found:false (no badge, never a crash).
|
||||
const nba = opts.nbaClient || require('./nbaStatsClient');
|
||||
const data = await nba.getSeasonAvg(name).catch(() => null);
|
||||
if (!data || typeof data !== 'object') return { found: false };
|
||||
const ppg = toNum(data.ppg ?? data.points);
|
||||
if (!ppg) return { found: false };
|
||||
let data = await nba.getSeasonAvg(name).catch(() => null);
|
||||
if (!data || typeof data !== 'object' || !toNum(data.ppg ?? data.points)) {
|
||||
const espn = opts.espnStats || require('./adapters/espnStatsAdapter');
|
||||
const e = await espn.getSeasonAverages(name, sp).catch(() => ({ found: false }));
|
||||
if (e && e.found && e.classifierInput) {
|
||||
const ci = e.classifierInput;
|
||||
const season = [
|
||||
{ k: 'PPG', v: String(ci.ppg ?? '—') }, { k: 'RPG', v: String(ci.rpg ?? '—') },
|
||||
{ k: 'APG', v: String(ci.apg ?? '—') }, { k: 'BLK', v: String(ci.bpg ?? '—') },
|
||||
];
|
||||
return { found: true, team: e.team || '', classifierInput: { ...ci, pos: e.position }, season, last10: [], splits: [] };
|
||||
}
|
||||
return { found: false };
|
||||
}
|
||||
const classifierInput = {
|
||||
ppg, rpg: toNum(data.rpg ?? data.rebounds), apg: toNum(data.apg ?? data.assists),
|
||||
ppg: toNum(data.ppg ?? data.points), rpg: toNum(data.rpg ?? data.rebounds), apg: toNum(data.apg ?? data.assists),
|
||||
bpg: toNum(data.bpg ?? data.blocks), spg: toNum(data.spg ?? data.steals),
|
||||
threes: toNum(data.threes ?? data.fg3m), usg: toNum(data.usg ?? data.usage), pos: data.pos || data.position,
|
||||
};
|
||||
|
||||
@@ -0,0 +1,250 @@
|
||||
/**
|
||||
* snapshotService — scheduled grade pipeline (Session 45).
|
||||
*
|
||||
* Orchestrates ONE snapshot cycle for one sport. The on-demand "Read" model is
|
||||
* retired: a snapshot pre-grades the full slate, LOCKS each grade to the line at
|
||||
* snapshot time (`gradedAt`), classifies each player's archetype, computes line
|
||||
* deltas vs the previous snapshot, and emits ticker events.
|
||||
*
|
||||
* Everything is orchestration of EXISTING services (oddsService,
|
||||
* gradeSlateService, archetypeService, playerIntelService). All I/O is injectable
|
||||
* so the whole cycle is unit-testable with zero network.
|
||||
*
|
||||
* Redis keys written:
|
||||
* snapshot:{sport}:latest — current locked snapshot { sport, updated_at, grades, deltas }
|
||||
* snapshot:{sport}:previous — prior snapshot (for the next delta computation)
|
||||
* grades:{sport} — { grades, updated_at, source } (GameCard / Explore / leaders)
|
||||
* ticker:items — capped array of ticker events (newest first)
|
||||
*/
|
||||
|
||||
const SNAP_TTL = 6 * 3600; // 6h — a snapshot is valid until the next run
|
||||
const GRADES_TTL = 2 * 3600; // matches gradeSlateService
|
||||
const TICKER_TTL = 24 * 3600;
|
||||
const TICKER_CAP = 50;
|
||||
const DELTA_NOISE = 0.5; // ignore movements smaller than this
|
||||
const DELTA_MOVE = 1.0; // ticker MOVE threshold
|
||||
const STATS_CONCURRENCY = 5;
|
||||
|
||||
const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/[^a-z0-9]/g, '');
|
||||
const lastName = (full) => {
|
||||
const parts = String(full || '').trim().split(/\s+/);
|
||||
return parts.length > 1 ? parts[parts.length - 1] : (parts[0] || '');
|
||||
};
|
||||
const sideChar = (dir) => (String(dir || 'over').toLowerCase() === 'under' ? 'U' : 'O');
|
||||
const propKey = (g) => `${norm(g.player || g.player_name)}|${String(g.stat_type || g.stat || '').toLowerCase()}|${String(g.direction || '').toLowerCase()}`;
|
||||
|
||||
async function mapLimit(items, concurrency, fn) {
|
||||
const out = new Array(items.length);
|
||||
let i = 0;
|
||||
async function worker() {
|
||||
while (i < items.length) {
|
||||
const idx = i++;
|
||||
out[idx] = await fn(items[idx], idx);
|
||||
}
|
||||
}
|
||||
await Promise.all(Array.from({ length: Math.min(concurrency, items.length || 1) }, worker));
|
||||
return out;
|
||||
}
|
||||
|
||||
/** Index original odds props by propKey-ish (player|stat) for odds lookup. */
|
||||
function indexOdds(props) {
|
||||
const map = {};
|
||||
for (const p of props || []) {
|
||||
const k = `${norm(p.player)}|${String(p.stat_type || '').toLowerCase()}`;
|
||||
map[k] = p;
|
||||
}
|
||||
return map;
|
||||
}
|
||||
|
||||
function gradedAtFor(g, oddsByKey, ts) {
|
||||
const k = `${norm(g.player || g.player_name)}|${String(g.stat_type || g.stat || '').toLowerCase()}`;
|
||||
const o = oddsByKey[k];
|
||||
let odds = null;
|
||||
if (o) {
|
||||
odds = String(g.direction || '').toLowerCase() === 'under'
|
||||
? (o.under_odds ?? o.under ?? o.odds ?? null)
|
||||
: (o.over_odds ?? o.over ?? o.odds ?? null);
|
||||
}
|
||||
return { line: g.line, odds, timestamp: ts };
|
||||
}
|
||||
|
||||
/**
|
||||
* Compare current grades to the previous snapshot's locked lines. A delta is
|
||||
* emitted only when |movement| >= DELTA_NOISE. `direction`:
|
||||
* 'toward' = market moving in the direction of our graded side (confirming)
|
||||
* 'away' = market moving against it.
|
||||
* For an OVER, a rising line confirms (toward); for an UNDER, a falling line.
|
||||
*/
|
||||
function computeLineDeltas(current, previous) {
|
||||
const prevMap = {};
|
||||
for (const p of previous || []) prevMap[propKey(p)] = p;
|
||||
const out = [];
|
||||
for (const c of current || []) {
|
||||
const prev = prevMap[propKey(c)];
|
||||
if (!prev) continue;
|
||||
const gradedLine = prev.gradedAt ? prev.gradedAt.line : prev.line;
|
||||
const currentLine = c.line;
|
||||
if (gradedLine == null || currentLine == null) continue;
|
||||
const delta = +(Number(currentLine) - Number(gradedLine)).toFixed(2);
|
||||
if (Math.abs(delta) < DELTA_NOISE) continue;
|
||||
const side = String(c.direction || 'over').toLowerCase();
|
||||
const toward = side === 'over' ? delta > 0 : delta < 0;
|
||||
out.push({
|
||||
player: c.player || c.player_name,
|
||||
stat: c.stat_type || c.stat,
|
||||
side: sideChar(side),
|
||||
gradedLine: Number(gradedLine),
|
||||
currentLine: Number(currentLine),
|
||||
delta,
|
||||
direction: toward ? 'toward' : 'away',
|
||||
grade: c.grade,
|
||||
});
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
const isTopGrade = (g) => g === 'A+' || g === 'A';
|
||||
|
||||
/**
|
||||
* Build ticker events from a snapshot: a SCAN summary, GRADE events for the top
|
||||
* grades, and MOVE events for significant deltas. Newest-relevant first.
|
||||
*/
|
||||
function generateTickerEvents(sport, grades, deltas, ts) {
|
||||
const events = [];
|
||||
events.push({
|
||||
tag: 'SCAN', color: 'var(--g-a)', ts,
|
||||
text: `${sport.toUpperCase()} slate scanned · ${grades.length} props graded`,
|
||||
});
|
||||
for (const g of grades.filter((x) => isTopGrade(x.grade)).slice(0, 6)) {
|
||||
const arch = g.archetype ? `${g.archetype} ` : '';
|
||||
events.push({
|
||||
tag: g.grade, color: g.grade === 'A+' ? 'var(--g-ap)' : 'var(--g-a)', ts,
|
||||
text: `${arch}${lastName(g.player || g.player_name)} ${g.stat_type || g.stat} ${sideChar(g.direction)}${g.line} graded ${g.grade}`,
|
||||
});
|
||||
}
|
||||
for (const d of deltas.filter((x) => Math.abs(x.delta) >= DELTA_MOVE).slice(0, 6)) {
|
||||
const arrow = d.delta > 0 ? '▲' : '▼';
|
||||
const s = d.side === 'U' ? 'u' : 'o';
|
||||
events.push({
|
||||
tag: 'MOVE', color: 'var(--amber)', ts,
|
||||
text: `${lastName(d.player)} ${s}${d.gradedLine} → ${s}${d.currentLine} ${arrow}${d.delta > 0 ? '+' : ''}${d.delta}`,
|
||||
});
|
||||
}
|
||||
return events;
|
||||
}
|
||||
|
||||
async function pushTickerItems(events, deps) {
|
||||
if (!events || events.length === 0) return;
|
||||
const existing = await deps.cacheGet('ticker:items');
|
||||
const arr = Array.isArray(existing) ? existing : [];
|
||||
const merged = [...events, ...arr].slice(0, TICKER_CAP);
|
||||
await deps.cacheSet('ticker:items', merged, TICKER_TTL);
|
||||
}
|
||||
|
||||
const ACTIVE_SPORTS = ['mlb', 'nba', 'wnba', 'soccer'];
|
||||
|
||||
/**
|
||||
* Run one snapshot cycle for `sport`. Returns a summary; never throws.
|
||||
* opts (all injectable): getOdds, gradeAndCacheSlate, resolveStats, classify,
|
||||
* cacheGet, cacheSet, now, nowMs.
|
||||
*/
|
||||
async function runSnapshot(sport, opts = {}) {
|
||||
const sp = String(sport || '').toLowerCase();
|
||||
const deps = {
|
||||
getOdds: opts.getOdds || require('./oddsService').getOdds,
|
||||
gradeAndCacheSlate: opts.gradeAndCacheSlate || require('./gradeSlateService').gradeAndCacheSlate,
|
||||
resolveStats: opts.resolveStats || require('./playerIntelService').resolvePlayerStats,
|
||||
classify: opts.classify || require('./archetypeService').classify,
|
||||
cacheGet: opts.cacheGet || require('../utils/redis').cacheGet,
|
||||
cacheSet: opts.cacheSet || require('../utils/redis').cacheSet,
|
||||
now: opts.now || (() => new Date().toISOString()),
|
||||
nowMs: opts.nowMs || (() => Date.now()),
|
||||
};
|
||||
const start = deps.nowMs();
|
||||
const ts = deps.now();
|
||||
|
||||
let odds;
|
||||
try {
|
||||
odds = await deps.getOdds(sp);
|
||||
} catch (e) {
|
||||
return { sport: sp, status: 'error', reason: e.message, gradeCount: 0 };
|
||||
}
|
||||
const props = (odds && Array.isArray(odds.props)) ? odds.props : [];
|
||||
if (props.length === 0) return { sport: sp, status: 'skipped', reason: 'no props', gradeCount: 0 };
|
||||
|
||||
// Grade the slate via the existing service; capture the envelope instead of
|
||||
// letting it write (we re-write an ENRICHED version below).
|
||||
let envelope = null;
|
||||
await deps.gradeAndCacheSlate(sp, props, {
|
||||
source: (odds && odds.provider) || 'odds-api',
|
||||
now: deps.now,
|
||||
cacheSet: async (_k, v) => { envelope = v; },
|
||||
});
|
||||
const graded = (envelope && Array.isArray(envelope.grades)) ? envelope.grades : [];
|
||||
if (graded.length === 0) return { sport: sp, status: 'skipped', reason: 'no grades', gradeCount: 0 };
|
||||
|
||||
// Archetype per unique player (pure math once we have stats). Best-effort —
|
||||
// a missing stat line → no badge (not a fallback archetype).
|
||||
const oddsByKey = indexOdds(props);
|
||||
const players = [...new Set(graded.map((g) => g.player || g.player_name).filter(Boolean))];
|
||||
const archByPlayer = {};
|
||||
await mapLimit(players, STATS_CONCURRENCY, async (player) => {
|
||||
try {
|
||||
const stats = await deps.resolveStats(player, sp);
|
||||
if (stats && stats.found) {
|
||||
const c = deps.classify(sp, stats.classifierInput || {});
|
||||
archByPlayer[player] = c.primary ? c.primary.name : null;
|
||||
}
|
||||
} catch { /* graceful — no badge */ }
|
||||
});
|
||||
|
||||
const enriched = graded.map((g) => ({
|
||||
...g,
|
||||
gradedAt: gradedAtFor(g, oddsByKey, ts),
|
||||
archetype: archByPlayer[g.player || g.player_name] || null,
|
||||
}));
|
||||
|
||||
// Line deltas vs the previous snapshot's locked lines.
|
||||
const prev = await deps.cacheGet(`snapshot:${sp}:latest`);
|
||||
const deltas = computeLineDeltas(enriched, prev && prev.grades);
|
||||
|
||||
// Lock: previous = old latest, latest = new, grades = enriched.
|
||||
if (prev) await deps.cacheSet(`snapshot:${sp}:previous`, prev, SNAP_TTL);
|
||||
const snapshot = { sport: sp, updated_at: ts, grades: enriched, deltas, gradeCount: enriched.length };
|
||||
await deps.cacheSet(`snapshot:${sp}:latest`, snapshot, SNAP_TTL);
|
||||
await deps.cacheSet(`grades:${sp}`, { grades: enriched, updated_at: ts, source: (odds && odds.provider) || 'odds-api' }, GRADES_TTL);
|
||||
|
||||
// Ticker exhaust.
|
||||
const events = generateTickerEvents(sp, enriched, deltas, ts);
|
||||
await pushTickerItems(events, deps);
|
||||
|
||||
return {
|
||||
sport: sp,
|
||||
status: 'ok',
|
||||
gradeCount: enriched.length,
|
||||
topGrades: enriched.filter((g) => isTopGrade(g.grade)).slice(0, 5).map((g) => ({
|
||||
player: g.player || g.player_name, stat: g.stat_type || g.stat, grade: g.grade, archetype: g.archetype,
|
||||
})),
|
||||
deltas: deltas.length,
|
||||
duration: deps.nowMs() - start,
|
||||
};
|
||||
}
|
||||
|
||||
/** Run snapshots for every active sport sequentially (cron entrypoint). */
|
||||
async function runAllSnapshots(opts = {}) {
|
||||
const results = [];
|
||||
for (const sp of ACTIVE_SPORTS) {
|
||||
results.push(await runSnapshot(sp, opts));
|
||||
}
|
||||
return results;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
runSnapshot,
|
||||
runAllSnapshots,
|
||||
computeLineDeltas,
|
||||
generateTickerEvents,
|
||||
pushTickerItems,
|
||||
ACTIVE_SPORTS,
|
||||
__internals: { propKey, gradedAtFor, indexOdds, lastName, isTopGrade, DELTA_NOISE, DELTA_MOVE, TICKER_CAP },
|
||||
};
|
||||
Reference in New Issue
Block a user