vlr-stats-scraper 1.5.0 → 3.1.0

package/scripts/db.mjs

@@ -1,210 +1,373 @@
 import Database from 'better-sqlite3'
 import path from 'path'
+import { migrate, SCHEMA_VERSION } from './migrate.mjs'
+import { normalizeAgentRow, careerKd, vlrIdFromUrl, AGENT_STAT_COLUMNS } from './stats.mjs'
 
-const db = new Database(path.join(process.cwd(), 'players.db'))
-
-db.exec(`
-  CREATE TABLE IF NOT EXISTS players (
-    name TEXT PRIMARY KEY,
-    team TEXT,
-    past_teams TEXT,
-    winnings TEXT,
-    most_played_agents TEXT,
-    avg_kda REAL,
-    nationality TEXT,
-    region TEXT,
-    stats TEXT
-  )
-`)
-
-const existingPlayerColumns = db.prepare('PRAGMA table_info(players)').all().map(col => col.name)
-if (!existingPlayerColumns.includes('stats')) {
-  db.exec('ALTER TABLE players ADD COLUMN stats TEXT')
-}
-
-const existingTableNames = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(t => t.name)
-if (existingTableNames.includes('tournaments') && !existingTableNames.includes('events')) {
-  db.exec('ALTER TABLE tournaments RENAME TO events')
-}
-if (existingTableNames.includes('tournament_players') && !existingTableNames.includes('event_players')) {
-  db.exec('ALTER TABLE tournament_players RENAME TO event_players')
-  db.exec('ALTER TABLE event_players RENAME COLUMN tournament_id TO event_id')
-}
-
-db.exec(`
-  CREATE TABLE IF NOT EXISTS events (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT UNIQUE NOT NULL,
-    url TEXT,
-    region TEXT,
-    year INTEGER,
-    stage INTEGER
-  )
-`)
-
-const existingEventColumns = db.prepare('PRAGMA table_info(events)').all().map(col => col.name)
-if (!existingEventColumns.includes('year')) {
-  db.exec('ALTER TABLE events ADD COLUMN year INTEGER')
-}
-if (!existingEventColumns.includes('stage')) {
-  db.exec('ALTER TABLE events ADD COLUMN stage INTEGER')
-}
-
-db.exec(`
-  CREATE TABLE IF NOT EXISTS event_players (
-    event_id INTEGER NOT NULL REFERENCES events(id),
-    player_name TEXT NOT NULL REFERENCES players(name),
-    PRIMARY KEY (event_id, player_name)
-  )
-`)
-
-const upsertPlayerStmt = db.prepare(`
-  INSERT INTO players (name, team, past_teams, winnings, most_played_agents, avg_kda, nationality, region, stats)
-  VALUES (@name, @team, @past_teams, @winnings, @most_played_agents, @avg_kda, @nationality, @region, @stats)
-  ON CONFLICT(name) DO UPDATE SET
-    team = excluded.team,
-    past_teams = excluded.past_teams,
-    winnings = excluded.winnings,
-    most_played_agents = excluded.most_played_agents,
-    avg_kda = excluded.avg_kda,
-    nationality = excluded.nationality,
-    region = excluded.region,
-    stats = excluded.stats
-`)
-
-const upsertEventStmt = db.prepare(`
-  INSERT INTO events (name, url, region, year, stage)
-  VALUES (@name, @url, @region, @year, @stage)
-  ON CONFLICT(name) DO UPDATE SET
-    url = excluded.url,
-    region = excluded.region,
-    year = excluded.year,
-    stage = excluded.stage
-`)
-
-const linkPlayerToEventStmt = db.prepare(`
-  INSERT OR IGNORE INTO event_players (event_id, player_name)
-  VALUES (@eventId, @playerName)
-`)
-
-function rowToPlayer(row) {
-  if (!row) return null
-  return {
+// ---------------------------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------------------------
+
+let db = null
+let statements = new Map()
+const defaultSettings = () => ({
+  path: process.env.VLR_DB_PATH || path.join(process.cwd(), 'players.db'),
+  readonly: false,
+})
+let settings = defaultSettings()
+
+// Opens (or reopens) the database. Call it before anything else to choose where players.db lives
+// or to open it read-only, e.g. from a web server: openDatabase({ path: '/data/players.db', readonly: true }).
+// Without a call, the first query opens $VLR_DB_PATH, or players.db in the current directory, for writing.
+function openDatabase(options = {}) {
+  closeDatabase()
+  settings = { ...defaultSettings(), ...options }
+  return getDb()
+}
+
+function closeDatabase() {
+  db?.close()
+  db = null
+  statements = new Map()
+}
+
+function getDb() {
+  if (db) return db
+  const { path: file, readonly } = settings
+  db = new Database(file, { readonly, fileMustExist: readonly })
+  db.pragma('foreign_keys = ON')
+  if (readonly) {
+    const version = db.pragma('user_version', { simple: true })
+    if (version < SCHEMA_VERSION) {
+      closeDatabase()
+      throw new Error(`${file} is schema version ${version}, expected ${SCHEMA_VERSION}. Open it once without readonly (e.g. run valstats) to migrate it.`)
+    }
+  } else {
+    // WAL lets a web server keep reading while the scraper writes.
+    db.pragma('journal_mode = WAL')
+    migrate(db)
+  }
+  return db
+}
+
+// Prepared statements are cached per connection.
+function stmt(sql) {
+  if (!statements.has(sql)) statements.set(sql, getDb().prepare(sql))
+  return statements.get(sql)
+}
+
+const transaction = fn => (...args) => getDb().transaction(fn)(...args)
+
+// ---------------------------------------------------------------------------------------------
+// Reading players
+// ---------------------------------------------------------------------------------------------
+
+// Every player query also pulls in the event's name and year.
+const SELECT_PLAYERS = `
+  SELECT players.*, events.name AS event_name, events.year AS event_year FROM players
+  JOIN events ON events.id = players.event_id
+`
+const NEWEST_FIRST = 'ORDER BY events.year DESC, players.scraped_at DESC, players.id DESC'
+
+const EVENT_STAT_COLUMNS = [
+  'team', 'agents', 'maps', 'rounds', 'rating', 'acs', 'kd', 'kast', 'adr', 'kpr', 'apr', 'fk_fd',
+  'fk_pct', 'fd_pct', 'hs_pct', 'clutch_pct', 'clutches_won', 'clutches_played', 'kills_max',
+  'kills', 'deaths', 'assists', 'first_kills', 'first_deaths',
+]
+
+// Turns database rows into player objects: JSON columns parsed, plus `stats` (career stats on their
+// top agents) and `event_stats` (their stats in this row's event, or null). Loads both in two queries.
+function hydrate(rows) {
+  if (!rows.length) return []
+  const ids = JSON.stringify(rows.map(row => row.id))
+
+  const agentRows = stmt(`
+    SELECT * FROM agent_stats WHERE player_id IN (SELECT value FROM json_each(?))
+    ORDER BY player_id, position
+  `).all(ids)
+  const agentsByPlayer = new Map()
+  for (const { player_id, position, ...row } of agentRows) {
+    if (!agentsByPlayer.has(player_id)) agentsByPlayer.set(player_id, [])
+    agentsByPlayer.get(player_id).push(row)
+  }
+
+  const eventRows = stmt('SELECT * FROM event_stats WHERE player_id IN (SELECT value FROM json_each(?))').all(ids)
+  const eventByPlayer = new Map(eventRows.map(({ player_id, ...row }) => [player_id, { ...row, agents: JSON.parse(row.agents) }]))
+
+  return rows.map(row => ({
     ...row,
     past_teams: JSON.parse(row.past_teams),
     most_played_agents: JSON.parse(row.most_played_agents),
-    stats: JSON.parse(row.stats),
-  }
+    stats: agentsByPlayer.get(row.id) ?? [],
+    event_stats: eventByPlayer.get(row.id) ?? null,
+  }))
+}
+const hydrateOne = row => (row ? hydrate([row])[0] : null)
+
+// Players can be looked up by name ('tenz') or by vlr.gg id (9).
+const playerKey = nameOrVlrId => (typeof nameOrVlrId === 'number' ? 'players.vlr_id = ?' : 'players.name = ?')
+
+function getPlayerById(id) {
+  return hydrateOne(stmt(`${SELECT_PLAYERS} WHERE players.id = ?`).get(id))
 }
 
-function savePlayer(player) {
-  upsertPlayerStmt.run({
-    ...player,
-    past_teams: JSON.stringify(player.past_teams),
-    most_played_agents: JSON.stringify(player.most_played_agents),
-    stats: JSON.stringify(player.stats),
-  })
+// The player as they were in their most recent event.
+function getPlayer(nameOrVlrId) {
+  return hydrateOne(stmt(`${SELECT_PLAYERS} WHERE ${playerKey(nameOrVlrId)} ${NEWEST_FIRST} LIMIT 1`).get(nameOrVlrId))
 }
 
-function getPlayer(name) {
-  return rowToPlayer(db.prepare('SELECT * FROM players WHERE name = ?').get(name))
+// Every saved version of a player, one per event, newest first.
+function getPlayerHistory(nameOrVlrId) {
+  return hydrate(stmt(`${SELECT_PLAYERS} WHERE ${playerKey(nameOrVlrId)} ${NEWEST_FIRST}`).all(nameOrVlrId))
 }
 
-// Case-insensitive partial match, e.g. "ten" finds "tenz" and "tenten".
+// Case-insensitive prefix match, e.g. "nat" finds "nats" but not "gnat". Returns one row per event.
 function searchPlayers(query) {
-  return db.prepare("SELECT * FROM players WHERE name LIKE ? ESCAPE '\\' ORDER BY name")
-    .all(`%${query.replace(/[\\%_]/g, '\\$&')}%`)
-    .map(rowToPlayer)
+  return hydrate(stmt(`
+    ${SELECT_PLAYERS} WHERE players.name LIKE ? ESCAPE '\\'
+    ORDER BY players.name, events.year DESC, players.id DESC
+  `).all(`${query.replace(/[\\%_]/g, '\\$&')}%`))
 }
 
 function getAllPlayers() {
-  return db.prepare('SELECT * FROM players').all().map(rowToPlayer)
+  return hydrate(stmt(`${SELECT_PLAYERS} ORDER BY players.id`).all())
 }
 
 function getRandomPlayer() {
-  return rowToPlayer(db.prepare('SELECT * FROM players ORDER BY RANDOM() LIMIT 1').get())
+  return hydrateOne(stmt(`${SELECT_PLAYERS} ORDER BY RANDOM() LIMIT 1`).get())
+}
+
+// The id of each player's most recent row (by event year, then scrape time).
+const LATEST_ROW_PER_PLAYER = `
+  SELECT id FROM (
+    SELECT players.id, ROW_NUMBER() OVER (
+      PARTITION BY COALESCE(players.vlr_id, players.name)
+      ORDER BY events.year DESC, players.scraped_at DESC, players.id DESC
+    ) AS n
+    FROM players JOIN events ON events.id = players.event_id
+  ) WHERE n = 1
+`
+
+// Players whose current team matches, plus anyone who used to play for it when includePast is set.
+// Each player is returned once, from their most recent event.
+function getPlayersByTeam(team, { includePast = false } = {}) {
+  return hydrate(stmt(`
+    ${SELECT_PLAYERS}
+    WHERE players.id IN (${LATEST_ROW_PER_PLAYER})
+      AND (players.team = @team COLLATE NOCASE
+        OR (@includePast AND EXISTS (SELECT 1 FROM json_each(players.past_teams) WHERE value = @team COLLATE NOCASE)))
+    ORDER BY players.name
+  `).all({ team, includePast: includePast ? 1 : 0 }))
+}
+
+// ---------------------------------------------------------------------------------------------
+// Leaderboards
+// ---------------------------------------------------------------------------------------------
+
+const EVENT_SORTABLE = ['rating', 'acs', 'kd', 'kast', 'adr', 'kpr', 'apr', 'fk_fd', 'fk_pct', 'fd_pct',
+  'hs_pct', 'clutch_pct', 'clutches_won', 'kills_max', 'kills', 'deaths', 'assists', 'first_kills', 'first_deaths', 'rounds', 'maps']
+const AGENT_SORTABLE = AGENT_STAT_COLUMNS
+
+function checkStat(stat, allowed) {
+  if (!allowed.includes(stat)) throw new Error(`Can't sort by "${stat}". Pick one of: ${allowed.join(', ')}`)
+}
+
+// Best players in one event by an event stat, e.g. getEventLeaderboard('Stage 2', 2026, { stat: 'acs' }).
+function getEventLeaderboard(eventName, year, { stat = 'rating', minRounds = 0, limit = 20, ascending = false } = {}) {
+  checkStat(stat, EVENT_SORTABLE)
+  const event = getEvent(eventName, year)
+  if (!event) return []
+  return hydrate(stmt(`
+    ${SELECT_PLAYERS} JOIN event_stats ON event_stats.player_id = players.id
+    WHERE players.event_id = ? AND COALESCE(event_stats.rounds, 0) >= ? AND event_stats.${stat} IS NOT NULL
+    ORDER BY event_stats.${stat} ${ascending ? 'ASC' : 'DESC'} LIMIT ?
+  `).all(event.id, minRounds, limit))
+}
+
+// Best players on one agent by a career stat, using each player's latest scrape,
+// e.g. getAgentLeaderboard('jett', { stat: 'kd', minRounds: 500 }).
+function getAgentLeaderboard(agent, { stat = 'rating', minRounds = 0, limit = 20, ascending = false } = {}) {
+  checkStat(stat, AGENT_SORTABLE)
+  return hydrate(stmt(`
+    ${SELECT_PLAYERS} JOIN agent_stats ON agent_stats.player_id = players.id
+    WHERE agent_stats.agent = ? COLLATE NOCASE AND players.id IN (${LATEST_ROW_PER_PLAYER})
+      AND COALESCE(agent_stats.rounds, 0) >= ? AND agent_stats.${stat} IS NOT NULL
+    ORDER BY agent_stats.${stat} ${ascending ? 'ASC' : 'DESC'} LIMIT ?
+  `).all(agent, minRounds, limit))
 }
 
-// Creates the event (tournament, stage, etc.) if it doesn't exist yet, and returns its id either way.
-function saveEvent({ name, url, region, year, stage }) {
-  upsertEventStmt.run({
+// ---------------------------------------------------------------------------------------------
+// Saving players
+// ---------------------------------------------------------------------------------------------
+
+const PLAYER_COLUMNS = ['vlr_id', 'name', 'url', 'team', 'past_teams', 'winnings', 'most_played_agents',
+  'avg_kda', 'nationality', 'region', 'scraped_at']
+
+// Saves a player's stats for one event, replacing any earlier save of them in that same event.
+// A player is matched by vlr_id (taken from `url` if missing), or by name for rows saved before
+// vlr ids were stored. Returns the player row's id.
+const savePlayer = transaction((eventId, player) => {
+  const vlrId = player.vlr_id ?? vlrIdFromUrl(player.url, 'player')
+  const agentRows = (player.stats ?? []).map(normalizeAgentRow).filter(row => row.agent)
+  const values = {
+    vlr_id: vlrId,
+    name: player.name,
+    url: player.url ?? null,
+    team: player.team ?? null,
+    past_teams: JSON.stringify(player.past_teams ?? []),
+    winnings: player.winnings ?? null,
+    most_played_agents: JSON.stringify(player.most_played_agents ?? agentRows.map(row => row.agent)),
+    avg_kda: player.avg_kda ?? careerKd(agentRows),
+    nationality: player.nationality ?? null,
+    region: player.region ?? null,
+    scraped_at: player.scraped_at ?? new Date().toISOString(),
+  }
+
+  const existing = stmt(`
+    SELECT id FROM players WHERE event_id = @eventId
+      AND (vlr_id = @vlrId OR (vlr_id IS NULL AND name = @name))
+    ORDER BY vlr_id IS NULL LIMIT 1
+  `).get({ eventId, vlrId, name: player.name })
+
+  let id
+  if (existing) {
+    id = existing.id
+    stmt(`UPDATE players SET ${PLAYER_COLUMNS.map(c => `${c} = @${c}`).join(', ')} WHERE id = @id`).run({ ...values, id })
+  } else {
+    id = Number(stmt(`
+      INSERT INTO players (event_id, ${PLAYER_COLUMNS.join(', ')})
+      VALUES (@event_id, ${PLAYER_COLUMNS.map(c => `@${c}`).join(', ')})
+    `).run({ ...values, event_id: eventId }).lastInsertRowid)
+  }
+
+  stmt('DELETE FROM agent_stats WHERE player_id = ?').run(id)
+  const insertAgent = stmt(`
+    INSERT OR IGNORE INTO agent_stats (player_id, position, agent, ${AGENT_STAT_COLUMNS.join(', ')})
+    VALUES (@player_id, @position, @agent, ${AGENT_STAT_COLUMNS.map(c => `@${c}`).join(', ')})
+  `)
+  agentRows.forEach((row, position) => insertAgent.run({ ...row, player_id: id, position }))
+
+  // Leaving event_stats out keeps what's saved; passing null removes it.
+  if (player.event_stats !== undefined) {
+    stmt('DELETE FROM event_stats WHERE player_id = ?').run(id)
+    if (player.event_stats) {
+      const eventValues = Object.fromEntries(EVENT_STAT_COLUMNS.map(c => [c, player.event_stats[c] ?? null]))
+      eventValues.agents = JSON.stringify(player.event_stats.agents ?? [])
+      stmt(`
+        INSERT INTO event_stats (player_id, ${EVENT_STAT_COLUMNS.join(', ')})
+        VALUES (@player_id, ${EVENT_STAT_COLUMNS.map(c => `@${c}`).join(', ')})
+      `).run({ ...eventValues, player_id: id })
+    }
+  }
+
+  return id
+})
+
+// ---------------------------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------------------------
+
+// Creates the event (tournament, stage, etc.) if no event has this name and year yet, updates it
+// otherwise, and returns its id either way.
+const saveEvent = transaction(({ name, url, year, stage }) => {
+  const values = {
     name,
-    url: url ?? null,
-    region: region ?? null,
     year: year ?? null,
+    url: url ?? null,
+    vlr_event_id: vlrIdFromUrl(url, 'event'),
     stage: stage ?? null,
-  })
-  return db.prepare('SELECT id FROM events WHERE name = ?').get(name).id
-}
+  }
+  const existing = stmt('SELECT id FROM events WHERE name = @name AND year IS @year').get(values)
+  if (existing) {
+    stmt('UPDATE events SET url = @url, vlr_event_id = @vlr_event_id, stage = @stage WHERE id = @id').run({ ...values, id: existing.id })
+    return existing.id
+  }
+  return Number(stmt(`
+    INSERT INTO events (name, year, url, vlr_event_id, stage) VALUES (@name, @year, @url, @vlr_event_id, @stage)
+  `).run(values).lastInsertRowid)
+})
 
-function addPlayerToEvent(eventId, playerName) {
-  linkPlayerToEventStmt.run({ eventId, playerName })
+function getEvents() {
+  return stmt('SELECT * FROM events ORDER BY year DESC, name').all()
 }
 
-function getEvents() {
-  return db.prepare('SELECT * FROM events').all()
+// The event with this name and year. Without a year, the only event with that name; if several
+// years share the name, the newest one. Returns undefined if there's none.
+function getEvent(name, year) {
+  if (year !== undefined && year !== null) {
+    return stmt('SELECT * FROM events WHERE name = ? AND year = ?').get(name, Number(year))
+  }
+  return stmt('SELECT * FROM events WHERE name = ? ORDER BY year DESC LIMIT 1').get(name)
 }
 
-function getEventByName(name) {
-  return db.prepare('SELECT * FROM events WHERE name = ?').get(name)
+// Kept for 2.x callers. Same as getEvent.
+const getEventByName = getEvent
+
+function getEventId(name, year) {
+  return getEvent(name, year)?.id
 }
 
-function getPlayersByEvent(eventName) {
-  return db.prepare(`
-    SELECT players.* FROM players
-    JOIN event_players ON event_players.player_name = players.name
-    JOIN events ON events.id = event_players.event_id
-    WHERE events.name = ?
-  `).all(eventName).map(rowToPlayer)
+// Like getEvent, but for deletes: refuses to guess which year was meant.
+function getEventForChange(name, year) {
+  if (year !== undefined && year !== null) return getEvent(name, year)
+  const matches = stmt('SELECT * FROM events WHERE name = ?').all(name)
+  if (matches.length > 1) {
+    throw new Error(`There are ${matches.length} events named "${name}" (${matches.map(e => e.year).join(', ')}). Say which year.`)
+  }
+  return matches[0]
 }
 
-function getRandomPlayerFromEvent(eventName) {
-  return rowToPlayer(db.prepare(`
-    SELECT players.* FROM players
-    JOIN event_players ON event_players.player_name = players.name
-    JOIN events ON events.id = event_players.event_id
-    WHERE events.name = ?
-    ORDER BY RANDOM() LIMIT 1
-  `).get(eventName))
+function getPlayersByEvent(eventName, year) {
+  const event = getEvent(eventName, year)
+  if (!event) return []
+  return hydrate(stmt(`${SELECT_PLAYERS} WHERE players.event_id = ? ORDER BY players.name`).all(event.id))
 }
 
-// Deletes players that no longer belong to any event.
-function deleteOrphanedPlayers() {
-  db.prepare('DELETE FROM players WHERE name NOT IN (SELECT player_name FROM event_players)').run()
+function getRandomPlayerFromEvent(eventName, year) {
+  const event = getEvent(eventName, year)
+  if (!event) return null
+  return hydrateOne(stmt(`${SELECT_PLAYERS} WHERE players.event_id = ? ORDER BY RANDOM() LIMIT 1`).get(event.id))
 }
 
 // Removes every player from an event but keeps the event itself, so it can be re-scraped.
-// Players that are still in other events are kept.
-const emptyEvent = db.transaction((eventName) => {
-  const event = getEventByName(eventName)
+function emptyEvent(eventName, year) {
+  const event = getEventForChange(eventName, year)
   if (!event) return false
-  db.prepare('DELETE FROM event_players WHERE event_id = ?').run(event.id)
-  deleteOrphanedPlayers()
+  stmt('DELETE FROM players WHERE event_id = ?').run(event.id)
   return true
-})
+}
 
-// Removes an event and its players. Players that are still in other events are kept.
-const clearEvent = db.transaction((eventName) => {
-  if (!emptyEvent(eventName)) return false
-  db.prepare('DELETE FROM events WHERE name = ?').run(eventName)
+// Removes an event and its players.
+function clearEvent(eventName, year) {
+  const event = getEventForChange(eventName, year)
+  if (!event) return false
+  // The event's players and their stats are deleted along with it (ON DELETE CASCADE).
+  stmt('DELETE FROM events WHERE id = ?').run(event.id)
   return true
-})
+}
 
 // Wipes every event and player from the database.
-const clearDatabase = db.transaction(() => {
-  db.exec('DELETE FROM event_players DELETE FROM events DELETE FROM players')
+const clearDatabase = transaction(() => {
+  getDb().exec('DELETE FROM events')
 })
 
 export {
+  openDatabase,
+  closeDatabase,
   savePlayer,
+  getPlayerById,
   getPlayer,
+  getPlayerHistory,
   searchPlayers,
   getAllPlayers,
   getRandomPlayer,
+  getPlayersByTeam,
+  getEventLeaderboard,
+  getAgentLeaderboard,
   saveEvent,
-  addPlayerToEvent,
   getEvents,
+  getEvent,
   getEventByName,
+  getEventId,
   getPlayersByEvent,
   getRandomPlayerFromEvent,
   emptyEvent,

package/scripts/event-stats-scraper.mjs

@@ -0,0 +1,77 @@
+import * as cheerio from 'cheerio'
+import { fetchHtml } from './client.mjs'
+import { toNumber, toInteger, vlrIdFromUrl } from './stats.mjs'
+
+// https://www.vlr.gg/event/2977/vct-2026-americas-stage-2/group-stage
+//   -> https://www.vlr.gg/event/stats/2977/vct-2026-americas-stage-2
+function eventStatsUrl(eventUrl) {
+  const match = String(eventUrl ?? '').match(/\/event\/(?:stats\/)?(\d+)(?:\/([^/?#]+))?/)
+  if (!match) return null
+  return `https://www.vlr.gg/event/stats/${match[1]}${match[2] ? `/${match[2]}` : ''}`
+}
+
+// vlr.gg's data-col name -> our column name and how to parse it.
+const EVENT_COLUMNS = {
+  maps: ['maps', toInteger],
+  rnd: ['rounds', toInteger],
+  rating: ['rating', toNumber],
+  acs: ['acs', toNumber],
+  kd: ['kd', toNumber],
+  kast: ['kast', toNumber],
+  adr: ['adr', toNumber],
+  kpr: ['kpr', toNumber],
+  apr: ['apr', toNumber],
+  fkfd: ['fk_fd', toNumber],
+  fkpr: ['fk_pct', toNumber],
+  fdpr: ['fd_pct', toNumber],
+  hsp: ['hs_pct', toNumber],
+  clp: ['clutch_pct', toNumber],
+  kmax: ['kills_max', toInteger],
+  k: ['kills', toInteger],
+  d: ['deaths', toInteger],
+  a: ['assists', toInteger],
+  fk: ['first_kills', toInteger],
+  fd: ['first_deaths', toInteger],
+}
+
+// Scrapes the stats page of the event the URL points at: every player's stats in that event only.
+// Returns a Map of vlr player id -> event stats, or undefined if the scrape fails.
+async function scrapeEventStats(eventUrl) {
+  const url = eventStatsUrl(eventUrl)
+  if (!url) {
+    console.error(`Couldn't work out the stats page for ${eventUrl}`)
+    return undefined
+  }
+  try {
+    const $ = cheerio.load(await fetchHtml(url))
+    const statsByPlayer = new Map()
+
+    $('table tbody tr').each((i, row) => {
+      row = $(row)
+      const link = row.find('td.mod-player a').attr('href')
+      const vlrId = vlrIdFromUrl(link, 'player')
+      if (!vlrId) return
+
+      const stats = {
+        team: row.find('.st-pl-country').first().text().trim() || null,
+        agents: row.find('.st-agent').map((j, el) => ({
+          agent: $(el).find('img').attr('src')?.match(/agents\/([^./]+)\./)?.[1] ?? null,
+          use_pct: toNumber($(el).find('.st-agent-n').text()),
+        })).get(),
+        clutches_won: toInteger(row.find('.st-cl-x').text()),
+        clutches_played: toInteger(row.find('.st-cl-y').text()),
+      }
+      for (const [dataCol, [column, parse]] of Object.entries(EVENT_COLUMNS)) {
+        stats[column] = parse(row.find(`td[data-col="${dataCol}"]`).first().text().trim())
+      }
+      statsByPlayer.set(vlrId, stats)
+    })
+
+    return statsByPlayer
+  }
+  catch (error) {
+    console.error('Error scraping event stats:', error)
+  }
+}
+
+export { scrapeEventStats, eventStatsUrl }