FFHL Stats API

FFHL Stats API serves FFHL fantasy-hockey data as JSON from a Turso/SQLite database. Fantrax CSV exports and FFHL forum draft history are import sources; runtime responses come from the database and, for some read-mostly routes, generated JSON snapshots.

Angular UI written for this API

Hosted UI showcase

Quick Start

• Node.js >=24 <25
• npm >=10

git clone https://github.com/maestor/node-fantrax-stats-parser.git
cd node-fantrax-stats-parser
npm install
cp .env.example .env
npm run db:migrate

# Choose one data source:
# 1) Download CSV backup from R2 (requires R2 credentials in .env)
npm run r2:download

# 2) Or use existing files already present under csv/

npm run db:import:stats
npm run dev

Open http://localhost:3000/api-docs for the local Swagger UI.

If you need to scrape fresh Fantrax or FFHL forum data instead of using existing CSV/JSON inputs, use docs/importing.md.

API Docs

• Hosted Swagger UI: https://ffhl-stats-api.vercel.app/api-docs
• Hosted OpenAPI JSON: https://ffhl-stats-api.vercel.app/openapi.json
• Local docs: start the dev server and open http://localhost:3000/api-docs

The hosted demo supports both root-style URLs and /api/* URLs. Health routes stay public, while most data routes require an API key via x-api-key or Authorization: Bearer <key>.

Players and Goalies

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/players/combined/regular?teamId=1"

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/goalies/combined/playoffs?teamId=1"

Career

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/career/players"

 curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/career/highlights/most-teams-owned"

Leaderboard

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/leaderboard/regular"

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/leaderboard/transactions"

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/leaderboard/finals"

Draft

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/draft/original"

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/draft/entry"

/draft/entry includes per-pick playedInLeague and playedForDraftingTeam flags plus matching team-summary counts and percentages.

Meta

curl https://ffhl-stats-api.vercel.app/health

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/teams"

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/seasons?startFrom=2020"

curl -H "x-api-key: <your-key>" \
  "https://ffhl-stats-api.vercel.app/last-modified"

/teams returns each configured team's current teamAbbr, and /leaderboard/finals includes teamAbbr on both awayTeam and homeTeam.

OpenAPI is the source of truth for route parameters and response schemas.

Common Commands

npm run dev
npm run verify
npm run db:migrate
npm run db:import:stats
npm run playwright:sync:playoffs
npm run db:import:finals-results
npm run playwright:sync:finals
npm run test:integration
npm run snapshot:generate

Agent Workflow

Codex work in this repository defaults to the backend/basic skill set from maestor/agent-skills: intelligence-testing, api-contract-sync, and local-first-verification. Those skills live in this repo under .agents/skills/. mutation-testing is intentionally not part of this project.

Documentation

• docs/development.md - development workflow, code standards, project structure, OpenAPI maintenance
• docs/testing.md - test strategy, coverage expectations, integration testing rules
• docs/importing.md - Fantrax sync/import workflows, FFHL draft sync, draft entity linking/backfill, CSV normalization
• docs/deployment.md - Vercel, Turso, R2, API auth, caching, operational commands
• docs/snapshots.md - snapshot-backed endpoints, generation rules, R2 snapshot storage
• docs/season-change.md - ordered checklist for moving the repo to a new active FFHL season
• docs/scoring.md - player and goalie scoring model details
• docs/rating.md - finals leaderboard rate model details

Technology

Written in TypeScript on Node.js. The API uses lightweight local HTTP helpers, rou3 for route matching, Turso/libSQL for the database layer, and local import tooling around Playwright plus csv-parse.