League format: team count, scoring rules, starting lineup, draft type.

Call this once at the start of a session -- every other tool's numbers are relative to this league's shape.

Live draft state: picks made so far, who is on the clock, your next picks.

Never cached. Safe to poll every few seconds during a live draft.

Undrafted players, ranked.

Args: position: QB, RB, WR, TE, K or D/ST. Omit for all positions. limit: how many to return. sort_by: "vorp" (value over replacement, the default and usually right), "projected_points" (ignores scarcity), or "espn_adp" (what your leaguemates are likely to do).

Replacement levels and tier structure for the league.

Explains why the rankings look the way they do: how many players at each position are startable league-wide, and what the last startable player at each position projects for.

A team's current roster and which starting slots are still unfilled.

Defaults to your team (ESPN_TEAM_ID).

Full detail on one player: projection, VORP, tier, ADP, injury status.

Search by name (partial match) or exact player_id.

One-call snapshot for when you are on the clock.

Bundles draft state, your roster needs, the best available at each position with tier depth, recent-pick position runs, and the biggest ADP fallers -- everything needed to make a pick inside a 60-90 second clock.

Manually record a pick when ESPN is not reporting the draft.

Use this if picks stop appearing in get_draft_state during a live draft, or for a draft held outside ESPN's draft room. Recorded picks merge with anything ESPN does report, so the available pool stays correct either way.

Args: player: Player name, full or partial ("Gibbs", "jahmyr gibbs"). player_id: Exact id, if you have it instead of a name. team_id: Who made the pick. Defaults to whoever is on the clock.

Ambiguous names are not guessed -- the candidates come back instead.

Record several picks at once, in draft order, by name.

The fast path during a live draft: ESPN does not publish picks until the draft ends, so these ARE the draft. Recorded picks persist, so you only ever send the picks made since your last call -- never the whole board.

Re-sending the entire pick history is fine and is the intended way to sync -- players already recorded are counted and ignored, and only the new names are appended, in the order given. Unrecognised or ambiguous names are reported without blocking the rest.

The single call to make when you are on the clock.

Returns only what a pick decision needs: the best available players that fill an actual roster hole, the tier cliff behind each, and how long until your next turn. Deliberately small -- a draft clock is 60 seconds.

Clear all manually recorded picks. Use before a new draft.

Remove the most recently manually recorded pick.

Re-read the draft order and your slot.

Call this after a randomized draft order is drawn (many leagues randomize shortly before the draft starts). League settings are otherwise cached, so a session opened before the draw would keep the old order.

Force a re-fetch of the player pool, projections and value math.

The pool is cached for ESPN_POOL_TTL seconds. Call this if projections changed (injury news, depth chart move) or the cache looks stale.