EyeWall Poller — Cloudflare Worker

Cloudflare Worker backend for EyeWall Analytics. Handles NHL/PWHL/AHL/ECHL polling and data serving, push notifications, and AI-generated content.

Architecture

src/
├── worker.js    # Thin router + scheduled entry point
├── nhl.js       # NHL poll loop and push notifications; the catch-all for every route worker.js doesn't answer itself or hand to a league prefix, dispatching /nhl/edge, /nhl/goal-replay and /live-activity to their modules
├── pwhl.js      # /pwhl/* endpoints and pollPWHL (playoff-odds/power-rankings live in leagueOddsRankings.js)
├── hockeytech.js # Shared AHL/ECHL implementation: poll loop, push notifications, all /ahl/* and /echl/* endpoints (2026-09)
├── hockeytechGameDetail.js # goal_on_ice/penalty_shots/game_win_probs for the PWHL/AHL/ECHL game-box and schedule routes (2026-10)
├── ahl.js       # AHL config for hockeytech.js: team codes, news sources, HockeyTech client (added 2026-08)
├── echl.js      # ECHL config for hockeytech.js (added 2026-08)
├── liveActivity.js # iOS Live Activities for all four leagues: push-to-start, updates, the HockeyTech ContentState, /live-activity/* (2026-10)
├── ops.js       # Owner ops alerts: /ops/notify, /ops/subscribe, per-league cron health + self-alert (2026-10)
├── dispatch.js  # Starts the pipeline's daily GitHub workflows and social posts on time (workflow_dispatch, 2026-10)
├── milestones.js # Which `milestones` rows belong to nhl/pwhl/ahl/echl, for /milestones and /milestones/latest (2026-10)
├── callupWatch.js       # /nhl/callup-watch ranking (pure; nhl.js gathers inputs) (2026-10)
├── edge.js              # /nhl/edge/{skater,goalie,team,leaders} — NHL EDGE tracking stats (2026-10)
├── goalReplay.js        # /nhl/goal-replay/:gameId/:eventId — one goal's player/puck tracking (2026-09)
├── hockeytechBracket.js # Calder/Kelly Cup bracket builders + PLAYOFF_FORMATS (C11, 2026-10)
├── hockeytechGame.js    # Per-game helpers for PWHL/AHL/ECHL: who dressed, by name; isExtraAttackerPull() (2026-10)
├── hockeytechPrediction.js # /pwhl,/ahl,/echl prediction body: Elo + AI prompt (2026-09)
├── hockeytechSeasonRows.js # Combines traded AHL/ECHL players' season rows (2026-10)
├── injuryImpact.js / playoffOdds.js / probableStarters.js / projectedLines.js / scorecard.js / scratches.js
│                        # Pure shape helpers for the NHL routes of the same names (2026-09)
├── leagueOddsRankings.js # /{pwhl,ahl,echl}/playoff-odds and /power-rankings (C10/C12, 2026-10)
├── penaltyText.js       # Readable NHL penalty text for pushes and the Live Activity (2026-10)
├── trades.js            # /trades/tree breadth-first trade tree (2026-09)
├── transactions.js      # /transactions trade-half pairing (2026-09)
├── contracts.js         # /contracts, /contracts/player/:id, /contracts/players, /contracts/summary, /config/cap builders (2026-10)
├── seasons.js   # Live NHL/PWHL/AHL/ECHL season resolution (NHL/PWHL added 2026-07, AHL/ECHL 2026-08), cached in KV
└── shared.js    # KV helpers, response utilities, shared constants

Wrangler bundles all modules on deploy. The scheduled trigger (* * * * *) runs poll(), pollPWHL(), pollAHL(), pollECHL(), refreshPPUnits(), refreshSeasonsCache() and maybeDispatchWorkflows() (see Pipeline scheduling) every 60 seconds during the season to keep NHL/PWHL/AHL/ECHL data and the resolved season fresh in KV. Each league's poll is tracked on its own (ops.js's trackCron(), writing health:cron:<league>), so one league throwing can't skip the others or the alert-log flush; after the polls, any league in season with no successful tick for 15 minutes raises a worker-cron-<league> ops alert (see Ops alerts).

Bindings: CACHE (KV), AI_ROUTE_LIMITER (Rate Limit — guards the unauthenticated AI-calling routes from public-cost abuse), PUBLIC_WRITE_LIMITER (Rate Limit — guards the unauthenticated write routes: /push/subscribe, /push/unsubscribe, /live-activity/register, /live-activity/start-token). AI generation (all narrative/scouting endpoints) went through a [ai] Workers AI binding until 2026-08; it's now a plain fetch() to OpenRouter (OPENROUTER_API_KEY secret) instead — see Model provider below.

HTTP caching (2026-10)

Every GET JSON response carries Cache-Control: public, max-age=N and a weak ETag (a SHA-1 of the body). A request whose If-None-Match matches gets a bodiless 304, so the browser re-downloads a response only when it changed. shared.js's withHttpCache() wraps handleRequest and sets these centrally; routes only say how long (json(val, { maxAge }), which cachedJson() fills in from its KV TTL).

Responses	Cache-Control
A KV-cached route (cachedJson(), or a hand-rolled kvGet/kvPut passing maxAge)	max-age = the route's KV TTL (300 s, 1800 s, 3600 s; data-dependent TTLs such as /{ahl,echl}/shots' 300/3600 follow the data), capped at 3600 s (MAX_MAX_AGE): a KV hit is served with the full TTL even when the entry expires a minute later, so a longer max-age could leave a device a day behind a /cache/bust or a nightly run
Live-game routes (LIVE_PATHS): /nhl/today, /{pwhl,ahl,echl}/today, /{pwhl,ahl,echl}/live/:id, /{ahl,echl}/schedule (live scores laid over it), /cache/pbp:*, /cache/boxscore:*, /cache/schedule:*; plus /schedule for the current/next season (re-stamped with live states every poll)	max-age=5 (LIVE_MAX_AGE), whatever the KV TTL: the app polls a live game every 10 s, and half that interval leaves no window for the browser to answer a poll from cache
A GET with no KV cache of its own (/health, /cache/standings, /news/latest, a build that is deliberately not cached such as an empty /scorecard)	max-age=30 (DEFAULT_MAX_AGE)
An empty answer whose cache is being filled in the background (/news, /pwhl/news, /{ahl,echl}/news, /news/latest, a failed /schedule fetch)	max-age=0
/alerts/recent	its own public, max-age=30, unchanged
POST/DELETE, any 4xx/5xx, a request with secret= or force=, or with an Authorization, X-Poll-Secret or x-ingest-secret header (/admin/health, any owner call)	no-store, no ETag

The CORS preflight (OPTIONS) is untouched. Cloudflare's edge does not cache Worker responses, so these headers only reach the browser (and any proxy in between).

Live Season Resolution

Added 2026-07, replacing what used to be a yearly manual flip of NHL_SEASON/PWHL_CURRENT_SEASON across this repo, the frontend, and the pipeline. seasons.js is the single source of truth for "what season is it right now" — everything else (this repo's own nhl.js/pwhl.js, the frontend's teamConfig.js/pwhlConfig.js, the pipeline's season_lookup.py) reads from it rather than resolving independently.

resolveNHLSeason(env) — calls api-web.nhle.com/v1/standings/now, rejects the candidate if gamesPlayed is 0, falls back to a hardcoded seed otherwise. This alone is too late a signal for schedule/roster-facing UI — gamesPlayed only ever flips once real games have actually been played, but the app needs to show the new season's schedule/roster once training camp is genuinely imminent, weeks before that. nextSeasonHasImminentSchedule(seasonId) covers that gap: after computing the gamesPlayed-based candidate (or the fallback, if rejected), it separately checks whether the season after that already has a published schedule with its first game (preseason counts) within SCHEDULE_LOOKAHEAD_DAYS (21) — if so, resolution flips forward to it. Verified live 2026-09-11: with no override set, this correctly auto-resolves to 20262027 (CAR's real preseason opener 9 days out) even though standings/now still only has real 20252026 data (no 20262027 games played yet) — the actual real-world boundary case this was built for, not a hypothetical.

Anchored on the standings candidate, not the seed (2026-10, audit Worker F3). When standings/now already names the new season with 0 games played, the look-ahead checks that season's schedule. If it is imminent, the candidate becomes current. If not, the season before it is current, cached for 1 hour (source: 'live-prior'). The look-ahead used to run from FALLBACK_NHL_SEASON in that case, so in Sept 2027 (standings 20272028, seed 20252026) it would have looked at 20262027 and never considered 20272028 until regular-season games were played. nextSeasonHasImminentSchedule() also rejects a season whose first game is more than 60 days in the past (SCHEDULE_LOOKBACK_DAYS): a season already played is not "next". The 60 days still cover a preseason that started weeks before standings shows any games.

resolvePWHLSeason(env) — calls HockeyTech's bootstrap view (feed=statviewfeed&view=bootstrap, not feed=modulekit — the latter returns a 200 OK with no real payload and silently masqueraded as working for a while before being caught), rejects current_season_id if it's hide_in_standings: true, and — important — prefers the most recent regular season over the most recent season of any type. This isn't optional: almost every /pwhl/* endpoint filters season_type=eq.regular downstream in Supabase, so resolving to a playoffs-type season_id broke every PWHL view in production for a stretch (caught via Cypress, not by this logic itself) before this preference was added.

The PWHL season after the current one — pickPWHLSeasonContext() reads two more answers out of the same bootstrap list: next, the earliest non-hidden regular season that starts after the current one (the one the 14-day lookahead is still holding back — on 2026-10-01, season 11, 2026-27, first game 2026-12-05, with season 8 current), and the preseason that leads into each regular season (its own season_id, usually hidden: 10 = 2026-27 Pre-Season, games Nov 22–30). next is relative to the current season, not the clock, so it always agrees with whatever resolvePWHLSeason() returned (cached or overridden); it's null once season 11 is current until HockeyTech lists 2027-28. GET /config/seasons's pwhl entry carries both as next: {seasonId, seasonType, startYear, startDate, preseason} and preseason (the current season's), each null when there isn't one or the bootstrap is unavailable. The pipeline ingests their schedules nightly; the app offers the next season's schedule once it has games. getPWHLScheduleSeasonIds() turns the same answer into the season_ids /pwhl/today reads.

Both are cached in KV (config:season:nhl, config:season:pwhl, 6hr TTL) and exposed at GET /config/seasons. The scheduled() handler calls both on every tick, but since they check the cache first, this is a cheap no-op except right after the TTL lapses — it does not hit the NHL/HockeyTech APIs every 60 seconds.

Manual override, for if live resolution ever misjudges the real season boundary (this has happened once already, and the true Sept/Oct transition boundary has never been directly observed):

wrangler kv key put --binding=CACHE "config:season:nhl:override" '"20262027"' --remote
wrangler kv key put --binding=CACHE "config:season:pwhl:override" '{"seasonId":9,"seasonType":"regular","startYear":2026}' --remote

Note the --remote flag — wrangler kv key delete/put/get without it operates on the local/preview namespace, not the one this Worker actually reads in production. This cost real debugging time once already; don't repeat it. Delete the override key(s) once live resolution is confirmed correct again — they take priority over everything else, including the cache.

Known gap: nhl.js's 32 TEAM_CONFIGS entries and pwhl.js's per-endpoint season handling were updated to read from seasons.js — but this was a deliberate, careful pass through every call site (not a blind find-and-replace), since getTeamConfig() had to become async and every caller needed updating. If a new endpoint or team-config consumer gets added later, make sure it reads the live value rather than reintroducing a hardcoded season.

Also found and fixed in nhl.js while doing this pass: a second, separate hardcoded MP_SEASON constant driving the MoneyPuck CSV fetch URL — the same decoupled-season bug shape as the one already known about in the pipeline's moneypuck.py, just duplicated a second time on the Worker side. Both are now derived from the live-resolved season instead of two independent hardcoded copies.

AHL and ECHL (added 2026-08) follow the same live-resolution pattern via resolveAHLSeason(env)/resolveECHLSeason(env) (seasons.js), but against a different vendor call shape than PWHL's: feed=modulekit&view=seasons (not statviewfeed&view=bootstrap), a different HockeyTech client per league (client_code=ahl, key=ccb91f29d6744675, site_id=3 vs. client_code=echl, key=2c2b89ea7345cae8, site_id=0, league_id=1), and no hide_in_standings flag to filter on. Instead, "is this candidate season real" is decided by career === '1' (skips All-Star Challenge entries) and start_date not being in the future (skips an already-announced-but-not-started upcoming season) — mirrors eyewall-pipeline's own ahl_stats.py/echl_stats.py resolve_current_season() logic exactly, including the reasoning behind it: a naive "max season_id with career=1" picked a season with zero games in testing (AHL's 2026-27, which starts October) instead of the actually-current one.

ECHL's HockeyTech key is not recoverable the way AHL's/PWHL's are. echl.com was rebuilt on Laravel/Livewire and renders stats server-side, so the usual "open the network tab" recovery path doesn't work there. The key currently in seasons.js (ECHL_HT_KEY) was recovered from sportsdataverse-py's league registry (hockeytech/_leagues.py) and independently re-verified live against the real feed. If it ever stops working, re-check that registry first — a network-tab hunt on echl.com will fail for the same reason it did during the original investigation.

Cached in KV: config:season:ahl / config:season:echl (6hr TTL, same TTL_SECONDS constant as NHL/PWHL), with fallback seeds {seasonId: 90, seasonType: 'regular'} / {seasonId: 73, seasonType: 'regular'} for a total cold start. Manual override keys, same escape-hatch pattern as NHL/PWHL above:

wrangler kv key put --binding=CACHE "config:season:ahl:override" '{"seasonId":90,"seasonType":"regular"}' --remote
wrangler kv key put --binding=CACHE "config:season:echl:override" '{"seasonId":73,"seasonType":"regular"}' --remote

getAllAHLSeasonTypes()/getAllAHLSeasons() and their ECHL equivalents mirror PWHL's getAllPWHLSeasonTypes()/getAllPWHLSeasons() — an id → season_type map for arbitrary/historical seasons, and full per-season metadata, respectively. The AHL/ECHL lists ({seasonId, seasonName, seasonType, startYear, startDate, endDate}) back both the season-comparison picker and GET /config/seasons/ahl-seasons / /echl-seasons, which eyewall-pipeline reads for any season's type and its date window instead of calling HockeyTech's seasons feed itself. Real bug found and fixed while building ECHL's own Compare-Seasons feature (2026-08-30): worker.js's /config/seasons/comparison never actually built an ahl key, despite a frontend comment (AHLTeamView.jsx) claiming it had since AHL/PWHL parity Phase 4 — the route only ever built nhl/pwhl keys, so AHL's own "Compare Seasons" picker had been silently showing its "no seasons available" empty state in production since that phase shipped. Fixed by adding getAllAHLSeasons()/getAllECHLSeasons() (mirroring the already-correct getAllPWHLSeasons()) and building real ahl/echl entries alongside nhl/pwhl in that route — fixing AHL's picker live and giving ECHL's brand-new one working season labels from day one, instead of reproducing the same gap a third time. See Config Endpoints below.

French/English localization

Track B Phase B2 (2026-08) — serving layer for eyewall-pipeline's locale-aware AI narrative content (Phase B0 schema, Phase B1 generation, both already shipped). game_summaries, player_scouting, and player_narratives (Supabase) each carry a locale column (en/fr) as of Phase B0, widening their upsert conflict keys — a row can now exist in both languages for the same game/player/season.

Four routes accept a ?locale=en/?locale=fr query param, defaulting to en for any missing or unrecognized value (same defensive posture as this file's existing team/season param handling) — /game-summary, /player-scouting, /player-results-vs-process (nhl.js) and /trivia/today (worker.js). Each filters its Supabase query on locale=eq.<value> and appends :<locale> to its KV cache key, so English and French responses cache independently rather than one clobbering the other.

Pre-game predictions (2026-09) — /game-predictions also filters on locale (game_predictions got its locale column in eyewall-pipeline's docs/sql/session_locale_predictions.sql; its KV key gets a :fr suffix for French only). The on-demand AI prediction routes — /prediction/analyze (both the in-season branch and buildPreseasonFallback()), /pwhl/prediction, /ahl/prediction and /echl/prediction — take ?locale=fr too: shared.js's localizePrompt() appends FRENCH_INSTRUCTION (a copy of the pipeline's STICKS_SYSTEM_PROMPT_FR_ADDENDUM — keep the two in step) and localeKeySuffix() gives French its own :fr KV key. English keys are unchanged, so existing caches and the frontend's /cache/prediction:{gameId}:{team} lookups keep working. /ahl/summary/narrative and /echl/summary/narrative (2026-10) take ?locale=fr the same way. The other on-demand AI routes (/summary/narrative, /pwhl/scout, the head-to-head narratives, /draft/analyze) are still English-only.

Known gap: trivia_questions's hard tier is hand-curated with no admin UI (see trivia_questions.py's docstring in eyewall-pipeline) and every existing hard row defaults to locale='en' — there is no French hard-tier content yet. A locale=fr request's hard tier will legitimately come back empty (same "not published yet" empty state this route already falls back to for other gaps) until French hard rows are added by hand.

The frontend (eyewallanalytics) passes locale on every route above (the app's i18n language), so Track B Phase B2 is complete.

AHL & ECHL

Added 2026-08 as the 3rd and 4th leagues (ahl.js/echl.js), following NHL/PWHL's exact patterns: same Supabase-REST-direct query shape, same KV caching shape, same push-notification/live-tracking structure. Both leagues sit on the same HockeyTech/LeagueStat vendor as PWHL — same endpoint shapes, just a different client per league (see Live Season Resolution above for the exact config values and the ECHL-key-recovery caveat).

One implementation, two configs (2026-09). The two leagues were built as ~1,750-line near-copies; they now share hockeytech.js's createHockeyTechLeague(), and ahl.js/echl.js hold only each league's config — team codes, news sources, headshot size, and HockeyTech client. The merge was pinned by hockeytech-leagues.characterization.test.js (see Testing): every route's requests, KV writes and responses stayed identical, except that ECHL gained /echl/player-game-log.

Both leagues share a real, permanent data-shape ceiling below PWHL — confirmed live against production data across multiple real games for each league (not assumed from one sample), documented in hockeytech.js's module docstring:

• No shift data at all. HockeyTech's modulekit/gameshifts view returns an empty {home: [], visitor: []} shape for every AHL/ECHL game tested, confirmed against a PWHL control game that does return populated shifts through the identical request shape. Consequence: no TOI, no on-ice Corsi/Fenwick, no shift-based WAR/RAPM — a harder limit than PWHL's own goal-scoped on-ice data, which is at least a coarse fallback.
• No hit/faceoff/blocked_shot event types in the PBP. Only goal, shot, penalty, goalie_change, penaltyshot plus shootout (confirmed real for AHL in game 1029078, 2026-10-02, and for ECHL — see echl_penalty_shots.py; its details carry shooterTeam and no period/time) exist. The box-score schema even carries hits/faceoffAttempts/faceoffWins/faceoffWinPercentage fields per player and per team, but they're hardcoded "0" in every real game checked for both leagues — confirming it's not charted anywhere, not merely absent from the PBP. /ahl/summary and /echl/summary strip these fields from HockeyTech's raw response rather than passing along a fabricated "0 hits" line the frontend would have to know not to trust.
• No Corsi/Fenwick/PDO anywhere in either file, on purpose — there's no shot-attempts data source beyond shots-on-goal for either league. /ahl/prediction and /echl/prediction started as ports of /pwhl/prediction's heuristic without the Corsi term; since 2026-09 their win % is Elo instead (see the /ahl/prediction row below).
• ahl_game_log.ended_in/echl_game_log.ended_in ('OT' | 'SO' | null) say how a final ended, so standings L10/streaks and /prediction streaks split OT/SO losses ('OT', counted in l10OTL) from regulation losses ('L') — since 2026-10; before that every non-win counted as 'L'. ahl_team_seasons/echl_team_seasons carry ot_losses and shootout_losses as two separate columns rather than one non-reg-losses-derived field the way PWHL combines them.
• ahl_player_seasons/echl_player_seasons have no shot_pct/// columns — confirmed absent from both leagues' HockeyTech feeds entirely, not just occasionally null.

AHL was built first, ECHL as a fast-follow, per the original investigation's recommendation (eyewall-poller#69 through #74) — both shipped the same 6-phase progression:

1. Foundation — /ahl/standings, /schedule, /roster, /players, /league-players, /shots, /team-season-summary (#69). ECHL's own foundation pass (#75) shipped the identical 7 routes.
2. Player detail — /player/landing, /player/career, /player-shots (AHL #70, ECHL #76).
3. Game/schedule detail — /lastgame, /summary, /preview, /game-box, /prediction, plus AHL's /player-game-log (AHL #71, ECHL #77). /player-game-log shipped for AHL only at first; ECHL got it in 2026-09 when the two leagues merged into hockeytech.js. It's the data for the player popup's Compare-tab trend chart (same role as /pwhl/player-game-log).
4. Team comparison / head-to-head — /team-seasons/compare, /compare-teams, /head-to-head, /head-to-head/narrative, plus /config/seasons/comparison's league entry (AHL #72, ECHL #79 — see Live Season Resolution above for the real AHL bug this phase found and fixed).
5. News feed — /news, /news/ingest, /news/bust, plus a sport=ahl/sport=echl entry in (AHL , ECHL ).

News sources differ in count, not structure. AHL has 3 (theahl.com/feed — the official league site, no PWHL equivalent since pwhl.com has no news RSS at all; thehockeywriters.com/category/ahl/feed/; OurSportsCentral's AHL feed, league id 17). ECHL has only 2 — confirmed live that echl.com has no discoverable RSS feed at all (/feed and /rss both 404, the same Laravel/Livewire rebuild that keeps its HockeyTech key off the network tab too) — just thehockeywriters.com/category/echl/feed/ and OurSportsCentral's ECHL feed, league id 18, not 17 (searched for it live rather than assumed sequential-by-launch-date IDs on that site). All 5 sources across both leagues are scoped to their own league by construction, so unlike PWHL_NEWS_SOURCES, none need keyword filtering.

Team ID → abbreviation maps (AHL_TEAM_CODES in ahl.js, 32 current teams; ECHL_TEAM_CODES in echl.js, 30 current teams plus two 2025-26 ids, ECHL_HISTORICAL_TEAM_IDS: Iowa, Utah) are hardcoded snapshots, same convention as PWHL_TEAM_CODES — no ahl_teams/echl_teams table exists; team display metadata is a frontend concern. AHL_TEAM_CODES also carries one historical entry (317: 'BRI') for the Bridgeport Islanders, who relocated to become the Hamilton Hammers (457) for 2026-27 — needed so historical-season queries against the old franchise still resolve correctly. If a future realignment or expansion changes either league's team IDs, add the new id here — the same "multiple independent per-league team-ID maps across repos" gotcha PWHL's own October Season Prep note below already documents applies to AHL/ECHL too.

Real bugs found and fixed along the way (beyond the AHL comparison-seasons config gap covered under Live Season Resolution above):

• Cloudflare KV's minimum expiration_ttl is 60 seconds, not 30. /ahl/live/:gameId and /echl/live/:gameId both use a 60s TTL for a non-final game (not PWHL's original 30s) — confirmed live against a real completed game that a 30s value throws KV PUT failed: 400 Invalid expiration_ttl. The same bug existed in /pwhl/live/:gameId and was fixed there in the same pass, since it had apparently never been exercised against a real non-final game before.
• shared.js's safeId(sourceId, link) truncated its hash to a fixed-length prefix of the article URL, which collides whenever two articles' URLs share a long common prefix — confirmed live while building AHL's news feed: theahl.com's own RSS feed republishes NHL.com's "32 in 32" prospect series, and every article in that series produced the identical id and collapsed to one row after dedup. Fixed by hashing the full link string instead of a truncated prefix. This is shared code (used by every league's news parser, not just AHL's) — production PWHL/NHL news had zero actual duplicate ids at the time of the check, but it was the same latent risk for any future source whose URLs share long prefixes.
• shared.js's encryptPushPayload() (RFC 8291 Web Push) had 3 string literals with a NUL byte where a mandated trailing space belonged ('WebPush: info\0', 'Content-Encoding: aes128gcm\0', 'Content-Encoding: nonce\0'), broken since 2026-06-22 and found while building ECHL's game/prediction routes (eyewall-poller#78, merged). This function backs every push notification across every league — broadcastAHL/broadcastECHL included — so every push before this fix silently degraded to a generic fallback notification rather than showing real content, because the browser fails to decrypt the payload before the service worker ever sees it. Fixed via a byte-level replace and proven with a from-scratch RFC 8291 round-trip test (encrypt → independently decrypt with the receiver's own private key → confirm the plaintext matches), re-run against the pre-fix code to confirm it throws an auth-tag mismatch.
• No league-scoped /ahl/cache/bust or /echl/cache/bust route exists, unlike PWHL's POST /pwhl/cache/bust, which clears one team's whole set of caches in a single call. The generic POST /cache/bust?key= (2026-09) covers the same ground one key at a time, so a stale AHL/ECHL entry no longer needs wrangler kv key delete by hand — what's still missing is only the convenience of clearing a team's several keys at once.

Test coverage. src/__tests__/hockeytech-leagues.characterization.test.js (added 2026-09) covers every AHL and ECHL route, the live-game poll, and the news fetch for both leagues with snapshot ("golden master") tests — see Testing below. src/__tests__/ahl-routes.test.js still holds the original hand-written assertions for AHL's 7 foundation routes.

Prerequisites

• Node.js 22+ (the installed Wrangler 4's engines requires it; CI and deploy use 22)
• Wrangler (installed via npm install)
• Cloudflare account with a Worker and KV namespace

Setup

npm install
wrangler login

Local Development

npm run dev

Runs the Worker locally via wrangler dev. Binds to your real KV namespace by default — use a preview namespace for isolation if needed.

Testing

Added 2026-07 — this repo had no test infrastructure before then. Session 47 added an HTTP-route-level test harness and covered a first slice of routes; Session 48 filled in the rest of the previously-untested HTTP surface (110 tests total as of Session 48). As of 2026-10-24: 2,029 tests in 55 files (npx vitest run).

npm install
npm run test    # or: npx vitest run

vitest.config.js runs under plain Node (environment: 'node'), not @cloudflare/vitest-pool-workers — deliberately. Route handlers only touch Workers-specific APIs via env.CACHE/env.AI_ROUTE_LIMITER/env.PUBLIC_WRITE_LIMITER, all of which mock cleanly without a real Workers runtime (see src/__tests__/route-harness.js). AI generation is a plain fetch() call (OpenRouter, since 2026-08) rather than a Workers binding, so it's mocked the same way as every other external call — mockFetchWithAI()/aiCalls()/aiPrompt() in the same harness file.

Test files:

• src/__tests__/seasons.test.js — seasons.js's own resolution logic. Covers: the manual override, KV cache hits, the "reject a zero-games-played candidate" fallback, the "reject a hidden current_season_id" fallback, and — the two tests that actually matter most — a regression test asserting feed=statviewfeed (not feed=modulekit) gets called, and a fixture built from the real 2026-07-05 production bootstrap payload confirming resolution picks season 8 (regular) over season 9 (playoffs) even though 9 is more recent by date. Both of those fixtures exist because they're exactly the two real bugs that shipped to production before being caught.
• src/__tests__/worker-routes.test.js — the dispatcher (/config/seasons, /config/seasons/pwhl-types, /config/seasons/ahl-seasons / /echl-seasons, /pwhl/* vs. everything-else routing) and /cache/bust (including the protected-key deny list and the X-Poll-Secret header).
• src/__tests__/nhl-routes.test.js — handleNHL's routes: a representative slice of read-proxy routes, all POLL_SECRET-gated mutating/ingest routes (asserting actual KV mutations/merge logic, not just status codes), and the AI-calling routes (/prediction/analyze, /summary/narrative, /team-seasons/head-to-head/narrative). /atom/ingest is covered for both real Atom and plain-RSS-format sources (Session: news ingestion investigation — the route used to assume every source was true Atom, silently parsing 0 items out of any RSS-format feed).
• src/__tests__/pwhl-routes.test.js — handlePWHL's equivalent: /pwhl/standings's enrichment logic, the POLL_SECRET-gated cache-bust/ingest routes, the AI-calling routes (/pwhl/scout, /pwhl/summary/narrative, /pwhl/prediction, /pwhl/team-seasons/head-to-head/narrative), /pwhl/preview's gameCenterPreview normalization, /pwhl/summary's gameSummary normalization (venue, officials, Head-Coach-only coach filtering, goalie stints), /pwhl/player/career's profile fields (bio HTML-to-plain-text extraction, is_primary photo selection, display_drafts-gated draft data, most-recent-first game log), and /pwhl/transactions's normalization (flat list, ignores the num_results section).
• src/__tests__/ahl-routes.test.js (added 2026-08, AHL Phase 1) — 's 32-team-plus-historical--entry shape, and through (the 7 foundation routes): cache-hit short-circuit, the L10/streak enrichment, graceful degradation when only the game-log fetch fails, and 's deliberate absence of a hits/faceoff/penalties section. Every AHL and ECHL route is also covered by the characterization suite below.

Every NHL, PWHL, AHL and ECHL route is now covered by a characterization suite above. A new route should get a row in its league's suite (ROUTES), then npx vitest run -u for that file to record its snapshots.

Deploy

npm run deploy

Or push to main: .github/workflows/deploy.yml runs lint and the test suite, then wrangler deploy (repo secrets CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID). PRs run ci.yml: npm audit on shipped deps, lint, tests and a dependency review.

Request parameters

Every query param that reaches a Supabase (PostgREST) URL is read through shared.js's sbParam(value, { type, name }), which validates and URL-encodes it first. This dates from 2026-10, when audit Worker F5 found that ?playerId=8478427%26select%3Dplayer_id replaced /player-shots' column list. The types are int (ids, seasons, game types, limits), abbr (2-4 letter team abbreviations) and id (letters, digits, _ . : -, e.g. the PWHL salaries label 2025-26). Comma lists use sbParamList. A value that doesn't fit answers 400 {"error": "invalid <name>"} before any upstream read. POLL_SECRET is compared in constant time (secretMatches()).

Sending POLL_SECRET

Every POLL_SECRET-gated route (/poll, /cache/bust, /ops/notify, /news/refresh, /social/test, /moneypuck/*, /pp-units/refresh, /summary/generate, /push/test, the */news/ingest, /atom/ingest and /moneypuck/ingest routes, /draft/analyze, /pwhl/cache/bust, /{pwhl,ahl,echl}/news/bust, and force=1 on the prediction routes) reads it through shared.js's readPollSecret(request, url), which checks, in order:

1. an X-Poll-Secret header — the preferred form;
2. an x-ingest-secret header (what the pipeline's ingest calls already send);
3. the ?secret= query param — deprecated (security audit 2026-10-13): Cloudflare's observability logs record the full URL, so a secret in the query string ends up in the logs. It still works because the pipeline's /ops/notify calls use it; it will be removed once nothing sends it.

The first one present wins, so a wrong header isn't rescued by a right ?secret=. /draft/analyze never took the query form and still doesn't (readPollSecret(request, url, { allowQuery: false })). Both headers are in the CORS Access-Control-Allow-Headers. Where a route below is written ?secret=, send the header instead:

curl -X POST -H "X-Poll-Secret: $POLL_SECRET" "$WORKER_URL/cache/bust?key=players-search-index"

Secrets

Set via wrangler secret put <NAME>. Never commit values.

Secret	Description
OPENROUTER_API_KEY	AI generation for every narrative/scouting/prediction route (shared.js's generateText()) — see Model provider below
POLL_SECRET	Protects POST /poll manual trigger and the other secret-gated routes, including POST /ops/notify (the pipeline's failure reports). Send it as an X-Poll-Secret header; ?secret= is deprecated — see Sending POLL_SECRET
ADMIN_EMAILS	Comma-separated allowlist for GET /admin/health (news-feed source health). Optional — falls back to a single hardcoded default ([email protected]) if unset. See shared.js's verifyAdminUser().
GITHUB_DISPATCH_TOKEN	Fine-grained GitHub PAT with Actions: write on ehlersio/eyewall-pipeline and ehlersio/nhl-contracts, used by dispatch.js to start the pipeline's daily workflows, the social posts and the contracts collector (2026-10). Optional: without it the Worker logs once a day and the workflows run on GitHub's own (late) schedule. See Pipeline scheduling
SUPABASE_SERVICE_KEY	Supabase service-role key (the pipeline's SUPABASE_SERVICE_KEY), used only by shared.js's patchGameLog() to write puck drop and finals into pwhl_game_log/ahl_game_log/echl_game_log (2026-10). Every read still uses the public anon key. Optional: without it the pollers log once per game and skip the write
VAPID_PRIVATE_KEY	Web Push VAPID private key
VAPID_PUBLIC_KEY	Web Push VAPID public key
VAPID_SUBJECT	Web Push contact ()

Bindings (wrangler.toml):

Binding	Type	Description
CACHE	KV Namespace	All KV read/write operations
AI_ROUTE_LIMITER	Rate Limit	Per-IP, per-route limit (10 req/60s) on the AI-calling routes with no secret check (counted only on a KV cache miss since 2026-10: a cached answer costs no AI call, and counting it used to 429 a user browsing cached results; force=1 on the four prediction routes needs POLL_SECRET, see Sending POLL_SECRET) — /prediction/analyze, /summary/narrative, /pwhl/summary/narrative, /pwhl/scout, /pwhl/prediction, /team-seasons/head-to-head/narrative, /pwhl/team-seasons/head-to-head/narrative, and (added 2026-08) /ahl/prediction, /ahl/team-seasons/head-to-head/narrative, /echl/prediction, /echl/team-seasons/head-to-head/narrative, and (2026-10, contract C8) /ahl/summary/narrative, /echl/summary/narrative. A single shared binding — checkAiRateLimit(env, request, routeName) (shared.js) keys each check as ${routeName}:${ip}, so one binding covers every league's AI routes without a per-league namespace_id. Provisioned automatically from wrangler.toml at deploy time, no dashboard setup needed. Unrelated to which AI provider those routes call — unaffected by the OpenRouter migration below.
PUBLIC_WRITE_LIMITER	Rate Limit	Per-IP, per-route limit (30 req/60s, namespace_id 1002) on the public write routes the app calls without a secret: /push/subscribe, /push/unsubscribe, /live-activity/register, /live-activity/start-token (security audit 2026-10-13). checkPublicWriteRateLimit(env, request, routeName) (shared.js), keyed ${routeName}:${ip}; 429 {error: 'Too many requests'} past it. Without the binding (a local wrangler dev that drops it) the routes run unlimited and log one warning per isolate. Provisioned from wrangler.toml like AI_ROUTE_LIMITER.

Model provider: OpenRouter

AI generation (/summary/narrative, /pwhl/summary/narrative, /pwhl/scout, /prediction/analyze, /draft/analyze, /pwhl/prediction, /team-seasons/head-to-head/narrative, /pwhl/team-seasons/head-to-head/narrative, plus the internal generateGameSummary()/buildPreseasonFallback() helpers — 11 call sites total) went through a Cloudflare Workers AI [ai] binding (env.AI.run('@cf/meta/llama-3.1-8b-instruct-fp8-fast', ...)) until 2026-08. All 11 now call shared.js's generateText(env, {messages, max_tokens}), a plain fetch() to OpenRouter's google/gemma-4-26b-a4b-it — the [ai] binding was removed from wrangler.toml since nothing reads env.AI anymore. /ahl/prediction, /ahl/team-seasons/head-to-head/narrative, /echl/prediction, and /echl/team-seasons/head-to-head/narrative (added 2026-08, after the OpenRouter migration) call generateText() directly — they never went through the old [ai] binding at all. As of 2026-10 there are 13 generateText() calls in src/ (nhl.js 7, pwhl.js 3, hockeytech.js 2, hockeytechPrediction.js 1; the last two each serve more than one league). Since 2026-10 the OpenRouter call has a 25 s AbortSignal.timeout (AI_TIMEOUT_MS), so a slow upstream fails the request (502, as for any AI error) instead of holding it, or the cron tick, open.

Same model swap and reasoning as eyewall-pipeline's ai_client.py was originally — see that repo's README for the full writeup: real accuracy problems found in the old model via side-by-side testing, and why OpenRouter rather than Cloudflare's own hosting of the same new model — its default "thinking" mode burns the whole completion budget and returns empty content, with no working way found to disable it via Cloudflare's endpoint; OpenRouter's own reasoning: {enabled: false} works correctly against the same model. No longer in sync as of 2026-09: ai_client.py switched again, to deepseek/deepseek-v4.1-flash, after a second side-by-side test found more real accuracy problems in Gemma. This repo's shared.js still calls google/gemma-4-26b-a4b-it directly (generateText()) — not yet re-evaluated against this repo's own prompts, which differ from the pipeline's (game summaries, scouting, draft analysis vs. the pipeline's narrative styles). Don't assume parity between the two repos' model choices without checking shared.js directly.

Prediction win probability: Elo (2026-09)

/prediction/analyze's two branches (in-season, and the true-preseason fallback in buildPreseasonFallback()) both read team_elo_ratings (a eyewall-pipeline table, updated nightly by elo_ratings.py) via fetchEloRatings()/eloWinProb(), replacing a hand-tuned scorecard (in-season, with a separately fitted isotonic-calibration patch) and a roster-continuity-dampened variant of the same scorecard (preseason) — see eyewall-pipeline/docs/elo_prediction_model_results.md for the backtest this is based on (Elo beat both prior systems on every metric, in both regimes). One model now serves both regimes; the preseason branch no longer needs roster/continuity data at all, since Elo's own season-boundary regression-to-mean (applied pipeline-side, nightly) already does that job from real outcomes.

The stats in /prediction/analyze's AI prompt (2026-09): record and goals come from the NHL standings; PP%, PK%, shots per game and Corsi come from team_seasons (the standings feed has no special-teams or shot fields, which is how every in-season prompt used to say "PK%: 0.0%"). The preseason fallback runs until both teams have played. After that, each stat is blended with the same team's last-season number while this season's sample is small — (gp × thisSeason + k × lastSeason) / (gp + k), with k = 10 games for shot volume/share, 20 for goal rates, 30 for PP%/PK% (EARLY_SEASON_K). From k games on, this season's number stands alone. The prompt labels each blended number as an early-season estimate. A missing stat reads "not available" and is never replaced with a made-up default. The league-average PP%/PK% line is the mean of every team's team_seasons value (last season's until every team has 30 GP, and only when at least 24 teams have the stat). Head-to-head excludes preseason games.

/pwhl/prediction, /ahl/prediction and /echl/prediction (2026-09) follow the same rules, in one shared implementation (src/hockeytechPrediction.js, buildHockeyTechPrediction(); the blending/formatting helpers above moved from nhl.js to shared.js so all four routes share them). They used to print (pp_pct ?? 0) * 100 and goals_for / (gp || 1), so a team at 0 GP (the pipeline writes 0-GP rows with pp_pct = pk_pct = 0.0) or a missing stat reached the AI as "PP%: 0.0% · PK%: 0.0%" / "GF/GA 0.00", with a Pythagorean score computed from zeros. Now:

• Last season is the previous regular season: the latest regular season that started before the game's season — for PWHL from getAllPWHLSeasons() (every season, hidden ones included, with startDate; its preseason is its own id), for AHL/ECHL the latest regular season that started before the game's season (getAllAHLSeasons()/getAllECHLSeasons()). During the playoffs that's the regular season just played.
• Each stat — GF/GA per game, PP%, PK% and (PWHL only) 5v5/all-situations shot-attempt share — is blended with the same team's last-season number by the row's gp, same k values as the NHL, and labeled; a team with no prior season (expansion: PWHL DET/HAM/LV/SJS in 2026-27) shows this season's number flagged "small sample". PP%/PK% also count as missing when the row has no power plays / times shorthanded (the pipeline's 0.0 there isn't a real 0%).
• Neither team has played yet (or the game is a preseason game): a preseason-style prompt built from last regular season's numbers. A preseason game never reads its own season's results, so preseason games never count toward streaks or head-to-head. If neither team has any numbers this season or last, the route 404s rather than ask the AI to write about nothing.
• expHome/expAway are null when either team's goal rates are unavailable (the frontend's share card already skips itself then; the preview popups show that row blank). corsiForPct values are rounded to one decimal.
• League-average PP%/PK%: the mean of real {league}_team_seasons values — last regular season's until every team has 30 GP of a regular season — labeled with season and team count, only when at least 3/4 of the league has the stat (3/4 of that season's rows, and never fewer than 6 teams for PWHL, 24 for AHL, 21 for ECHL).
• Units: {pwhl,ahl,echl}_team_seasons store pp_pct/pk_pct as 0-1 fractions (checked against production 2026-09-29), PWHL's corsi_for_pct[_5v5] as percentages.

generateText() deliberately mirrors env.AI.run()'s exact call/return shape ({messages, max_tokens} in, {response: string} out) so every call site only needed a one-line swap, not a rewrite of prompt-building or response-handling code.

View current secrets:

wrangler secret list

Environment Variables

wrangler.toml has no [vars] block. These three settings are read like vars but are set with wrangler secret put (a plain-text dashboard var would be removed by the next wrangler deploy, which runs on every push to main):

Variable	Description
VAPID_PUBLIC_KEY	Web Push VAPID public key (a secret, also listed under Secrets)
APNS_ENV	Native iOS push (a secret): production or sandbox (default when unset). Set to production as of 2026-09-14 — TestFlight and App Store builds register production APNs tokens (Xcode signs archives with the production aps-environment, even though App.entitlements says development), and those tokens only work against api.push.apple.com. Side effect: debug builds run straight from Xcode get sandbox tokens and won't receive pushes while this is production.
APNS_BUNDLE_ID	Native iOS push: defaults to com.eyewallanalytics.app (the app's bundle ID) if unset. Not set in production; the default applies.

KV Namespace

Binding: CACHE (08c4ef455c584c83a811a96aa3c620ed)

Key patterns:

Key	TTL	Description
schedule:{ABBR}:{season}	10min current/next season, 60 days past	NHL team schedule. Re-stamped in place with each game's live state and score from scoreboard:states whenever it changes (the app reads a game as live from here). A /cache/ miss on the older 2-part schedule:{ABBR} shape background-fetches the current season's key (the 2-part key itself is never written)
roster:{ABBR}	1hr	NHL team roster (/v1/roster/{team}/current proxy — added 2026-09 alongside the KV caching fix below)
nhl:injuries:{ABBR}	1hr	NHL team injury report (Supabase player_injuries, nightly-ingested from ESPN by eyewall-pipeline's injuries.py)
nhl:callup-watch:{ABBR}:{ahlTeamId}	1hr	Call-up watch (/nhl/callup-watch)
nhl:prospects:{ABBR}	6hr	The NHL's /prospects/{abbr} list, which the call-up watch matches affiliate players against
nhl:transactions:team:{ABBR} / nhl:transactions:league	1hr	NHL transactions feed with trade halves paired (Supabase nhl_transactions, nightly-ingested from ESPN by eyewall-pipeline's transactions.py). A failed Supabase read is not cached
nhl:trades:tree:{txId}	1hr	One trade's tree (/trades/tree, Supabase trades / trade_assets from eyewall-pipeline's trade_trees.py). Not-found and failed reads are not cached
nhl:contracts:{ABBR}:{season} / nhl:contracts:player:{id}:{season} / nhl:contracts:players:{season} / nhl:contracts:summary:{season} / nhl:contracts:summary:roster:{season}	1hr	NHL contracts (Supabase nhl_contracts / nhl_contract_seasons / nhl_contract_clauses / nhl_contract_gaps, mirrored nightly from the open nhl-contracts dataset by eyewall-pipeline's nhl_contracts.py). An empty answer (), a team whose roster could not be fetched, and a failed read are not cached

Config Endpoints

Method	Path	Description
GET	/config/seasons	Live-resolved current NHL + PWHL + AHL + ECHL season ({nhl: {seasonId}, pwhl, ahl, echl} — see Live Season Resolution). pwhl also carries startDate, next (the upcoming regular season, with its own preseason) and preseason (the current season's), each {seasonId, seasonType, startYear, startDate} or null. Consumed by the frontend at app boot and by the pipeline's season_lookup.py.
GET	/config/seasons/ahl-seasons, /config/seasons/echl-seasons	Every season the league's HockeyTech feed knows about, current and historical: [{seasonId, seasonName, seasonType, startYear, startDate, endDate}], from the same 6hr KV-cached feed as /config/seasons (config:season:{ahl,echl}:seasons). Read by the pipeline's season_lookup.py for a season's type and its game-log date window. 502 when the feed is unavailable (never a guess), same as /config/seasons/pwhl-types.
GET	/config/seasons/pwhl-types	{seasonId: seasonType} for every PWHL season the HockeyTech bootstrap lists, hidden ones included (getAllPWHLSeasonTypes()), for the pipeline's PWHL scripts to look up an arbitrary season's real type. 502 when the bootstrap is unavailable
GET	/config/seasons/comparison	Every season with team_seasons/pwhl_team_seasons/ahl_team_seasons/echl_team_seasons rows, per league, with a team count and a comparable flag (strictly more than half of the league's current active team count has a row). Backs the season-over-season comparison feature (Session 64; AHL/ECHL entries added 2026-08 — see Live Season Resolution for the real AHL bug this fixed) — distinct from /config/seasons, which only ever answers "what's current." 1hr KV cache (). PWHL rows also carry ("2025-26", "2025-26 Playoffs", "2023-24 Preseason"), and their is the hockey season's, not the start date's calendar year — see in seasons.js.

NHL Endpoints

Method	Path	Description
GET	/cache/:key	Read one of the KV entries the app consumes (primary NHL data path): schedule:*, standings, pbp:*, boxscore:*, landing:*, summary:*, narrative:*, pwhl:narrative:*, ahl:narrative:*, echl:narrative:*, prediction:* (CACHE_ROUTE_READABLE in nhl.js). Any other key is refused (403) — the namespace also holds every push subscription, Live Activity tokens and the APNs JWT, which were readable here until 2026-10-06. 404 on a miss, except standings, which is fetched from the NHL, stored and returned (still 404 if that fetch fails); a schedule:* miss is filled in the background. A key with a malformed % escape is a 400 {error: 'Invalid key'}
POST	/cache/bust?key=	Delete one KV entry so the next request rebuilds it from live code. POLL_SECRET-gated; GET is refused (405) so a stray link or prefetch can't delete anything. Returns { key, busted } — busted: false means the key wasn't cached, not that the call failed. Refuses ops:*, la:*, health:*, alerts:*, apns:*, push:* and any *:override (403, worker.js's PROTECTED_KV_PREFIXES/isProtectedKvKey()): those hold real data — owner ops devices and dispatch markers, Live Activity tokens and start lists, poller/ops/news health records, the recent-alerts log, the APNs JWT, every push subscription, and deliberately-pinned season overrides — so busting them would destroy data rather than refresh it. (Before 2026-10-13 only push:* and *:override were refused.) Added 2026-09 after the /players-search-index paging fix deployed correctly but stayed invisible for its 6-hour TTL.
GET	/news?team=	Team news feed
GET	/schedule?team=	Team schedule
GET	/roster?team=

poll() (nhl.js, not an HTTP route) runs every cron tick: it refreshes CAR's schedule, reads the league-wide score/now (live:gameIds, plus CAR's own live:gameId), stamps each changed game's state onto both teams' cached schedules (scoreboard:states), and for each live game writes pbp:/boxscore: (180 s) and pushes to the teams' followers. The pushes are game start, period start, period end (at the intermission), goals (scorer, strength and shot type; the other side gets lead-aware copy), hat tricks, one power-play alert per power play (none when a stoppage's penalties offset; readable penalty text from penaltyText.js), a pulled goalie (third period on, by the trailing team), and the final/win. End-of-period and final pushes link to that team's summary. It also starts and updates Live Activities (liveActivity.js) and records every alert for the bell (alerts:recent:NHL). Each finished game gets its final PBP/boxscore and one game-over push (push:gameover:{gameId}). Only for CAR's own games does it also generate summary:{gameId} (30 days) and try the X post. Standings are refetched once the stored copy is 5 minutes old.

PWHL Endpoints

Method	Path	Description
GET	/pwhl/standings?season=	League standings + L10/streak from pwhl_game_log.ot/.shootout: l10W/l10L/l10OTL, and streakType 'W', 'L' (regulation) or 'OT' (OT/SO losses) — since 2026-10; before that OT/SO losses extended an 'L' streak. season may be any season id: its own type is read (getAllPWHLSeasonTypes()), so a playoff id (9) serves the playoff teams' rows — until 2026-10-08 it filtered season_type=regular and answered []
GET	/pwhl/players?teamId=&season=	Roster, skater + goalie stats. The Roster tab list leaves out players the pipeline marked off the team's roster (on_roster=not.is.false, sbRosterRows(); reads unfiltered until eyewall-pipeline's docs/sql/2026-10-06_on_roster.sql has added the column)
GET	/pwhl/shots?teamId=&season=	Shot events for team heat map
GET	/pwhl/team-season-summary?teamId=&season=	Season-aggregate SOG/blocks/hits/penalties/faceoffs (car vs. opp) + PP%/PK% for the Shot Map's "All N" summary cards (Session 80). Counts only, aggregated server-side against pwhl_shot_events/pwhl_pbp_events for the team's own completed games — not raw rows like /pwhl/shots
GET	/pwhl/schedule?teamId=&season=	Team schedule. A game with an Elo probability in pwhl_game_win_probs (eyewall-pipeline's hockeytech_elo.py) carries winProb: { home, away, source: 'elo' } (2026-10)
GET	/pwhl/roster?teamId=	Bare roster (name + jersey)
GET	/pwhl/game-box?gameId=	Per-player box score (skaters + goalies) for a completed game — box-score popup (Session 50). Every row carries player_name, from the game's own HockeyTech gameSummary lineup (so a player who has since changed teams is still named), then by id; null when neither knows the player Also and (2026-10, ): is — every goal in the game's , in order, with the skaters on the ice from and //// — and until that table has rows for the game (the AHL/ECHL tables arrive with eyewall-pipeline's goal-on-ice migration; a missing table or failed read never fails the box score). is from ; is or — the feed records only whether it scored, never a save versus a miss. KV key .

AHL Endpoints

Added 2026-08 across 6 phases (eyewall-poller#69–#74) — see AHL & ECHL above for the phase breakdown, the data-shape ceiling relative to PWHL, and the real bugs found while building these.

Method	Path	Description
GET	/ahl/standings?season=	League standings + L10/streak from ahl_game_log.ended_in: l10W/l10L/l10OTL, and streakType 'W', 'L' (regulation) or 'OT' (OT/SO losses)
GET	/ahl/bracket?season=<playoff id>	Playoff bracket (contract C11) from HockeyTech's own bracket feed (feed=modulekit&view=brackets, found by the 2026-10-07 probe; statviewfeed has no bracket view): { season, format: {label, bestOf[], source} | null, rounds: [{ name, bestOf, series: [{ id, name, top: {teamId, seed, wins}, bottom, status: 'scheduled'|'live'|'final', winnerTeamId, games[] }] }], source: 'feed' }. Seeds are the final division ranks of the regular season before (HockeyTech view=teams&groupTeamsBy=division); the feed has none, and leaves winner blank even for finished series, so a series is final when a side reaches the round's wins, 4 wins, or plays in a later round. Without season, the latest playoff season that has started. A season with no rounds yet is rounds: [], uncached; 502 when the feed fails. 1 h KV. Formats (series lengths, qualifiers, byes) live in hockeytechBracket.js PLAYOFF_FORMATS, only as verified from the league's own rules (AHL: 2026)
GET	/ahl/bracket/projected?season=<regular id>	"If the playoffs started today": the live division standings cut and paired by the verified format for that season's playoffs — { season, format, rounds: [{ name, bestOf, series }], byes: [{teamId, seed, division}], source: 'standings' }, seeds and matchups only (0-0, scheduled). Without season, the latest regular season. rounds: [] with reason: 'format-unverified' (no PLAYOFF_FORMATS entry: the AHL hasn't published its 2027 qualification rules, and 2026-27's realignment changes the per-division counts) or 'no-games', uncached. 1 h KV
GET	/ahl/schedule?teamId=&season=	Team schedule. A game with an Elo probability in ahl_game_win_probs (hockeytech_elo.py, written for today's and tomorrow's games) carries winProb: { home, away, source: 'elo' } (2026-10); none when the table has no row or can't be read

pollAHL (built by hockeytech.js, not an HTTP route) runs from worker.js's per-minute scheduled() alongside NHL/PWHL/ECHL's own poll functions — today's slate is game_log plus any game today only the scorebar has (2026-10; the ECHL preseason got no pushes before) — push notifications for game start, period start, goals (with hat-trick detection), power plays, pulled goalies (only an extra-attacker pull: 3rd period, last 10 minutes, by the trailing team, goalie not already back — not the delayed-penalty trips to the bench HockeyTech logs the same way; isExtraAttackerPull() in hockeytechGame.js, shared with pollPWHL) and the final score, gated on env.VAPID_PRIVATE_KEY existing. There is no calendar gate (2026-10): the Oct–June month window used to skip the poll entirely, which hid the late-September preseason, and out of season the poll costs one empty game_log read and one cached scorebar read a minute. On a day with games it also reads the live scorebar fresh from HockeyTech each minute (since 2026-10-19), refilling the {league}:scorebar KV copy the routes read. At puck drop and again at the final, once each, it also writes the game's live state back into {league}_game_log (see Finals written by the Worker). The final-score push goes out once, and only for a game the poll followed live — a game that had already ended the first time it's seen (e.g. right after a deploy) gets none. (Before 2026-09 it never fired at all, for PWHL either: the poll only handed live games to the per-game handler.)

ECHL Endpoints

Added 2026-08 across the same 6 phases as AHL (eyewall-poller#75–#81) — see AHL & ECHL above. Every route below is a direct port of its AHL equivalent (same query shapes, same KV caching shape) except where noted.

Method	Path	Description
GET	/echl/standings?season=	League standings + L10/streak, OT/SO losses split out the same way as /ahl/standings
GET	/echl/bracket?season=<playoff id>	Same as /ahl/bracket (ECHL rounds come named by the feed, e.g. "Division Semifinals"); Kelly Cup format: top 4 per division, 1v4 / 2v3, every round best-of-7 (2026 and 2027 entries)
GET	/echl/bracket/projected?season=<regular id>	Same as /ahl/bracket/projected; empty (no-games) until 2026-27 opening night
GET	/echl/schedule?teamId=&season=	Team schedule, with winProb from echl_game_win_probs the same way as /ahl/schedule
GET	/echl/roster?teamId=	Bare roster (name + jersey)
GET	/echl/players?teamId=&season=	Roster + skater/goalie season stats, name-enriched. No row cap, same as /ahl/players
GET	/echl/league-players?season=	All teams' skater + goalie season stats (Leaders tab) Traded players combined, same as /ahl/league-players.
GET	/echl/shots?teamId=&season=	Shot events for team heat map. Only shot/goal event_type rows exist
GET	/echl/game-shots?gameId=	Both teams' shot events in one game, in game order, for the shot map's single-game view (/echl/shots holds one team's shots only)
GET	/echl/team-season-summary?teamId=&season=	Season-aggregate SOG + PP%/PK%. Same deliberate omission of hits/blocked/faceoff/penalties as /ahl/team-season-summary — no echl_pbp_events table, no blocked_shot event type
GET	/echl/player/landing?id=&season=

pollECHL (built by hockeytech.js) runs from the same per-minute scheduled() as AHL's, with identical push-notification event coverage.

Ops alerts

Added 2026-10 (audit 2026-10-06 §4/§7): failures used to go nowhere — pipeline "Notify on failure" steps were echos, and a cron tick that threw every minute left /health saying ok: true. (/health now shows each league's lastOk; the error text is on /admin/health.)

• Pipeline workflows report a failed run with curl -fsS -X POST "$WORKER_URL/ops/notify" -H "X-Poll-Secret: $POLL_SECRET" -H 'content-type: application/json' -d '{"source":"<workflow-file>","status":"failure","title":"<Workflow> failed","body":"<run url>","url":"<run url>"}'. (They send ?secret=$POLL_SECRET until the pipeline switches to the header; the Worker accepts both.)
• The Worker reports itself: after each tick's polls, a league in season (ops.js's leagueInSeason(), from the league's own season dates) whose health:cron:<league>.lastOkAt is more than 15 minutes old raises worker-cron-<league>, and records an ok once it recovers.
• Delivery: every device in ops:subs, registered from the app's hidden /admin/health page ("Send ops alerts to this device"). Separate from push:subs, so ops alerts never reach users. One push per source per 30 minutes; every report is still recorded.

Pipeline scheduling

GitHub's on: schedule starts the pipeline's workflows 3-7 hours late, and the morning AI predictions landed after afternoon puck drops (audit 2026-10-06 §4). Since 2026-10 the Worker's own cron, which runs on time every minute, starts them with a workflow_dispatch (src/dispatch.js):

Workflow (eyewall-pipeline)	Dispatched at (UTC)
nightly.yml	07:00
pwhl-nightly.yml	07:20
ahl-nightly.yml	07:40
echl-nightly.yml	08:00
moneypuck-ingest.yml	10:00
ai_pipeline.yml	14:00

• Once the UTC clock passes a slot, the first tick with no ops:dispatched:<workflow>:<date> marker POSTs https://api.github.com/repos/ehlersio/eyewall-pipeline/actions/workflows/<workflow>/dispatches with {ref: 'main'}. A 204 writes the marker (36h), so the workflow is dispatched at most once per UTC day. A failure is retried 10 minutes later.
• Each attempt is recorded in health:ops:dispatch-<workflow> (status ok/failure), shown on /admin/health.
• The workflows keep on: schedule as a fallback. A scheduled run skips itself if a run of that workflow already succeeded that UTC day, and a dispatched run never skips.
• Needs the GITHUB_DISPATCH_TOKEN secret. Without it nothing is dispatched (logged once a day) and the GitHub schedule carries on as before. The first day the token is set, every slot already past that day is dispatched on the next tick.

Social posts

Since 2026-10-15 the Instagram + Facebook posts (social-posts.yml) are dispatched the same way, and its GitHub cron list stays as the late fallback. GitHub had been starting them 4-5 hours late (the 15:30 UTC winners card went out near 19:30 UTC on 2026-10-14).

• One entry per post kind per slot. SOCIAL_SLOTS in dispatch.js mirrors the schedule comment at the top of social-posts.yml: 18 kinds, each with a first slot and a backup an hour later, some only on certain UTC weekdays (days, 0 = Sunday, as cron). Keep the two in sync when a post is added or moved.
• Inputs. Each dispatch sends {ref: 'main', inputs: {kind, dry_run: 'false'}}. The workflow's dry_run defaults to true on a dispatch, so leaving it out would render without posting.
• Per-slot markers. Each slot has its own marker, ops:dispatched:social-posts.yml:<kind>:<HH:MM>:<date>, so the backup is dispatched even though the first slot was. That keeps the workflow's design: a backup run retries a first run that exited 1 on stale data, and does nothing if the post is already in social_posts.
• Window. A slot is only dispatched within 45 minutes of its time. A slot missed for longer, after a Worker outage or around a deploy, is left to its backup and to the GitHub fallback rather than posted hours late.
• Spacing. After a post is dispatched, the next waits 5 minutes (ops:dispatch:spacing:social-posts.yml). The workflow's concurrency group keeps one run pending and cancels it when another queues, so slots that come due together go out a few minutes apart, earliest first. Runs take under 3 minutes and scheduled slots are at least 15 minutes apart.
• Health. Each kind's latest attempt is in health:ops:dispatch-social-posts.yml:<kind>, so one post's status never overwrites another's on /admin/health.
• Fallback. A scheduled run of social-posts.yml hours later finds the post already published and exits ("Already published everywhere -- nothing to do"). It needs no skip step of its own.

nhl-contracts collector

Since 2026-10-23 the Worker also starts update-contracts.yml in ehlersio/nhl-contracts, the open contracts dataset's collector (NHL.com Forge, ESPN, PuckPedia's Bluesky feed, then a publish to the contracts release).

• Slots. Hourly at :05 UTC all year (kind: 'hourly', 30-minute window), plus :20, :35 and :50 from July 1 to 15 UTC (kind: 'july', 10-minute window, dates: ['07-01', '07-15']): free agency opens July 1 and NHL.com's Forge lists hold only 25 items, so a busy hour can overflow one.
• Repository. Schedule entries carry a repo; these go to https://api.github.com/repos/ehlersio/nhl-contracts/actions/workflows/update-contracts.yml/dispatches with {ref: 'main'}. GITHUB_DISPATCH_TOKEN needs Actions: write on that repository as well (a fine-grained PAT lists its repositories explicitly).
• Markers and health. Each slot has its own marker (ops:dispatched:update-contracts.yml:<kind>:<HH:MM>:<date>); the latest attempt per kind is in health:ops:dispatch-update-contracts.yml:<kind>.
• Fallback. The workflow keeps a daily GitHub cron. Its runs are idempotent, so a dispatch landing next to a cron run only costs a few requests.

Finals written by the Worker

Since 2026-10 the HockeyTech pollers (pollPWHL, pollAHL, pollECHL) write a game's live state into {league}_game_log themselves, instead of waiting for the pipeline's live-score-refresh.yml, which GitHub ran 3-4 times a day rather than every 5 minutes. Two writes per game, never one per tick, each from the same gate that sends that push:

• Puck drop (with the "Game Starting" push): PATCH {league}_game_log?game_id=eq.<id> {home_score, away_score, game_state: 'Live', game_status_code}.
• Final (with the game-over push, before it is sent): {home_score, away_score, game_state: 'Final', game_status_code: 4} plus ended_in ('OT'/'SO'/null) for AHL/ECHL, or ot/shootout booleans for the PWHL. Since 2026-10-19 this happens at GameStatus 3 'Unofficial Final', minutes before 4; 3's status text doesn't say OT/SO, so that comes from the play-by-play then (shootout attempts, or play in an overtime period). The move from 3 to 4 sends and writes nothing more. These are the same columns each league's live refresh in eyewall-pipeline writes.

So /standings' L10/streak, /lastgame and every other game_state=eq.Final read see a final within a minute. It uses the SUPABASE_SERVICE_KEY secret with Prefer: return=minimal. Without the secret it logs once per game and skips. A failed write is logged and never costs the push. The NHL side needs nothing like this, because its finals come from the NHL's own API.

October Season Prep

Most of this is now automatic (2026-07) — see Live Season Resolution. What's left:

• NHL_SEASON secret → new season string — no longer read anywhere in this repo
• PWHL_CURRENT_SEASON in pwhl.js — removed entirely; resolved live via seasons.js
• Add PWHL expansion team IDs — done 2026-07 (PWHL_TEAM_CODES in pwhl.js includes DET=10, HAM=11, LV=12, SJS=13)
• Narrative KV keys include the team (carAbbr/teamId): stale keys from a prior season expire on their own (NHL 30 days, PWHL 24 hr, AHL/ECHL 30 days). No change needed.
• If a future expansion wave adds a new team_id again: add it to pwhl.js's PWHL_TEAM_CODES map. Also worth checking the pipeline's pwhl_stats.py/pwhl_salaries.py for their own separate team-ID maps — those don't share this file's map and need the same addition independently (found the hard way in 2026-07: three separate places across two repos enumerate PWHL team IDs).
• If live season resolution ever misjudges the real season boundary: use the KV override documented above rather than an emergency redeploy. The 2026 rollover was the first one this logic saw (Sept 2026: schedule look-ahead to 20262027 verified 2026-09-11; fixes in #144, #151, #152). Each fall, compare /config/seasons (or /health's seasons) with each league's real schedule as soon as league pages look empty.
• If a future realignment or expansion changes AHL/ECHL team IDs: add the new id to ahl.js's AHL_TEAM_CODES or echl.js's ECHL_TEAM_CODES — same "multiple independent per-league team-ID maps, no shared table" situation as PWHL's bullet above, not yet hit for either league but worth remembering when it is.
• ECHL's 2026-27 regular season opens 2026-10-17 (HockeyTech's season start date is 2026-10-15); /echl/bracket/projected stays no-games until then.

Related Repos

• eyewallanalytics — React/Vite web app (Cloudflare Pages) and the Capacitor iOS app (ios/: native push, the Live Activity widget's GameActivityAttributes.swift)
• eyewall-pipeline — Python data pipeline (GitHub Actions; its daily workflows and social posts are dispatched on time by this Worker — see Pipeline scheduling)
• react-hockey-rink — the rink/shot-map library (its SHOT_AREAS/shotArea define the NHL shot areas the app bins /pwhl/league-goalie-shots into, and name the areas /nhl/edge/goalie returns)

---

Disclaimer

EyeWall Analytics is an independent, fan-built analytics project and is not affiliated with, endorsed by, or sponsored by the National Hockey League (NHL), the Professional Women's Hockey League (PWHL), or any of their member teams. All team names, logos, and related marks are the property of their respective owners and are used here for informational and editorial purposes only.