Skip to main content
Breaking in 4.0.0
  • Integer id columns are decimal strings — Every id column of integers (id, *_id, game_pk, playerId, …) comes back as exact decimal strings on every surface — parsers, producers, loaders, HockeyTech analytics. Compare and join ids as strings; Number(row.game_id) for a safe number back. (changelog)
  • 400 / 422 raise InvalidParameterError — For every family (it was AssetFetchError), never retried; the message names host, path and status with a redacted excerpt of the body. (changelog)
  • Typed returns — generated row types for parsed: true — TypeScript only. A wrapper's raw payload resolves to unknown (was any); verified endpoints resolve to their row interfaces; the summary dispatchers to ParsedTables. Narrow or cast a raw payload. (changelog)
  • Wrapper failures raise NoDataError / AssetFetchError — Instead of raw axios errors. NoDataError = the fetch worked and there is nothing there (404, ESPN { code: 404 }); AssetFetchError = the fetch failed (403 / 429 / 5xx after retries, network). Retries follow DEFAULT_RETRY_STATUSES with backoff. (changelog)

HTTP core

Not data functions

These utilities never fetch a provider payload by themselves — they transform, classify, configure or look things up. The data surface (every espn* / native wrapper and load* loader) is under ESPN Reference.

Request pipeline, transports, auth providers, family auth helpers and the wrapper / loader type vocabulary.

Exportkindmodule
requestfunctionsrc/core/request.ts
requestResponsefunctionsrc/core/request.ts
retryDelayMsfunctionsrc/core/request.ts
jsonBodyfunctionsrc/core/request.ts
axiosTransportconstsrc/core/transport.ts
createImpersonatingTransportfunctionsrc/core/transport.ts
encodeQueryfunctionsrc/core/transport.ts
Transporttypesrc/core/transport.ts
TransportRequesttypesrc/core/transport.ts
TransportResponsetypesrc/core/transport.ts
bearerAuthfunctionsrc/core/auth.ts
headerAuthfunctionsrc/core/auth.ts
queryAuthfunctionsrc/core/auth.ts
tokenAuthfunctionsrc/core/auth.ts
sessionAuthfunctionsrc/core/auth.ts
AuthProvidertypesrc/core/auth.ts
AuthContexttypesrc/core/auth.ts
RELEASES_FAMILYconstsrc/core/releases.ts
ReleaseRowtypesrc/core/releases.ts
ReleaseColumnstypesrc/core/releases.ts
ReleaseLoaderOptionstypesrc/core/releases.ts
SeasonLoaderOptionstypesrc/core/releases.ts
SeasonLoadertypesrc/core/releases.ts
AssetLoadertypesrc/core/releases.ts
LeagueConfigtypesrc/core/types.ts
EspnFamilytypesrc/core/types.ts
Scopetypesrc/core/types.ts
WrapperFntypesrc/core/types.ts
WrapperDeftypesrc/core/types.ts
QueryParamtypesrc/core/types.ts
PathParamtypesrc/core/types.ts
Rowtypesrc/core/types.ts
ParserRowtypesrc/core/types.ts
Wrappertypesrc/core/types.ts
SectionedWrappertypesrc/core/types.ts
WrapperParamstypesrc/core/types.ts
NoParamstypesrc/core/types.ts
OptionalParamstypesrc/core/types.ts
RequiredParamtypesrc/core/types.ts
LeagueParamtypesrc/core/types.ts
ParamsArgtypesrc/core/types.ts
SnakeToCameltypesrc/core/types.ts
FLAT_HOSTSconstsrc/core/client.ts
resolveFlatfunctionsrc/core/client.ts
makeLeagueModulefunctionsrc/core/client.ts
makeFlatModulefunctionsrc/core/client.ts
nflTokenGenfunctionsrc/core/nfl_auth.ts
nflHeadersGenfunctionsrc/core/nfl_auth.ts
nflClearTokenCachefunctionsrc/core/nfl_auth.ts
jwtExpfunctionsrc/core/nfl_auth.ts
NFL_API_HOSTconstsrc/core/nfl_auth.ts
NflTokenOptionstypesrc/core/nfl_auth.ts
resolvePffApiKeyfunctionsrc/core/pff_api_runtime.ts
hasKenpomLoginfunctionsrc/core/pff_api_runtime.ts
kenpomLoginfunctionsrc/core/pff_api_runtime.ts
kenpomClearSessionCachefunctionsrc/core/pff_api_runtime.ts
nflProTokenfunctionsrc/core/pff_api_runtime.ts
nflProBrowserLoginfunctionsrc/core/pff_api_runtime.ts
nflProClearTokenCachefunctionsrc/core/pff_api_runtime.ts
NflProAuthErrorclasssrc/core/pff_api_runtime.ts
PlaywrightLiketypesrc/core/pff_api_runtime.ts
sports247ClearTokenCachefunctionsrc/core/pff_api_runtime.ts

src/core/request.ts​

The one request pipeline every wrapper and loader goes through: family config -> auth -> transport -> retry / backoff -> error classification.

Import: import { … } from 'sportsdataverse/dist/core/request.js'

request​

Fetch through the family's transport + auth and return the body; a non-2xx after retries throws the family's error.

export async function request(family: string, req: TransportRequest): Promise<unknown>

requestResponse​

Like request but resolves with the whole response (status, headers, data).

export async function requestResponse( family: string, req: TransportRequest ): Promise<TransportResponse>

retryDelayMs​

The wait before retry attempt + 1 — Retry-After (capped at 120s) or exponential backoff (0.5s doubling, capped at 4s, jittered).

export function retryDelayMs(attempt: number, retryAfter?: string): number

jsonBody​

Decode a JSON-labelled body (sdv-py _json_body) — a body that does not decode is a failed fetch.

export function jsonBody(family: string, res: TransportResponse, url: string): unknown

src/core/transport.ts​

Transports — the axios default and the browser-impersonating one — plus the query serialiser.

Import: import { … } from 'sportsdataverse'

axiosTransport​

The default transport (axios); never throws on an HTTP status, only on a network failure.

export const axiosTransport: Transport

createImpersonatingTransport​

A transport that impersonates a browser's TLS / HTTP-2 fingerprint (optional peer impit) for hosts that stall non-browser clients (stats.nba.com).

export function createImpersonatingTransport( opts: { browser?: string; proxyUrl?: string }

Example:

import { configure, createImpersonatingTransport } from 'sportsdataverse';
configure({ transport: { nba_stats: createImpersonatingTransport() } });

encodeQuery​

Serialise a query map — null / undefined dropped, arrays as repeated keys, a Date as ISO-8601 UTC.

export function encodeQuery(query?: Record<string, unknown>): string

Transport​

(req: TransportRequest) =\> Promise\<TransportResponse\>.

export type Transport

TransportRequest​

What a transport receives — method, url, query, headers, body, timeout.

export interface TransportRequest

TransportResponse​

What a transport resolves — status, headers, data.

export interface TransportResponse

src/core/auth.ts​

Auth providers that decorate a request with credentials — static headers / query, a minted token, a logged-in session.

Import: import { … } from 'sportsdataverse'

bearerAuth​

Authorization: Bearer \<token\>; token may be an (async) getter.

export function bearerAuth( token: string | undefined | (()

headerAuth​

Fixed headers on every request.

export function headerAuth(headers: Record<string, string | undefined>): AuthProvider

queryAuth​

Fixed query params on every request (e.g. an apiKey).

export function queryAuth(params: Record<string, unknown>): AuthProvider

tokenAuth​

A minted token, cached in-process and re-minted before expiresAt; concurrent requests share one mint.

export function tokenAuth(opts:

sessionAuth​

A logged-in session whose headers and cookies ride on every request; refresh logs in again.

export function sessionAuth(opts:

AuthProvider​

apply decorates a request, refresh re-authenticates after a 401; both throw on failure.

export interface AuthProvider

AuthContext​

What a provider sees — the family, the request and the previous response.

export interface AuthContext

src/core/releases.ts​

The release-asset loader core behind every generated load* — parquet download, size guard, decode, the integer-id policy.

Import: import { … } from 'sportsdataverse'

RELEASES_FAMILY​

The transport family of release downloads ("releases").

export const RELEASES_FAMILY

ReleaseRow​

A loaded row — Record\<string, unknown\>.

export type ReleaseRow

ReleaseColumns​

A dataset in column form (format: "columns") for rows of type R.

export type ReleaseColumns<R extends object

ReleaseLoaderOptions​

columns, format, maxCells, timeoutMs.

export interface ReleaseLoaderOptions

SeasonLoaderOptions​

The options of a per-season loader — seasons plus ReleaseLoaderOptions.

export interface SeasonLoaderOptions extends ReleaseLoaderOptions

SeasonLoader​

A per-season loader of rows R (rows by default, column arrays with format: "columns").

export interface SeasonLoader<R extends object

AssetLoader​

A single-asset loader of rows R.

export interface AssetLoader<R extends object

src/core/types.ts​

The wrapper type vocabulary — league / wrapper defs, the Wrapper / SectionedWrapper call signatures, params helpers and row types.

Import: import { … } from 'sportsdataverse'

LeagueConfig​

One ESPN league's config — sport / league slugs, prefix, scopes, public shorts.

export interface LeagueConfig

EspnFamily​

The ESPN host families — site_v2 | site_v2_alt | web_v3 | core_v2 | fitt_v3 | cdn.

export type EspnFamily

Scope​

An endpoint's league scope — universal | ncaa | football | mlb.

export type Scope

WrapperFn​

Any wrapper — (params?) =\> Promise\<any\>.

export type WrapperFn

WrapperDef​

A generated endpoint definition — family / host / path / params / parser.

export interface WrapperDef

QueryParam​

A query param def — name, query key, default, transform.

export interface QueryParam

PathParam​

A path param def — name, required, default.

export interface PathParam

Row​

A parsed row — Record\<string, unknown\>.

export type Row

ParserRow​

Alias of Row (what every parser returns).

export type ParserRow

Wrapper​

A one-table wrapper — the raw payload, or P with parsed: true.

export interface Wrapper<P

SectionedWrapper​

A multi-table wrapper — the raw payload, P with parsed: true, or one table with section.

export interface SectionedWrapper<P

WrapperParams​

The untyped params bag.

export type WrapperParams

NoParams​

An endpoint with no params.

export type NoParams

OptionalParams​

Optional params, each also under its camelCase alias.

export type OptionalParams<T>

RequiredParam​

One required param, under its snake or camelCase name.

export type RequiredParam<K extends string, V>

LeagueParam​

\{ league?: string | null \} — the soccer / cricket league override.

export type LeagueParam

ParamsArg​

The params argument tuple — optional when every param is.

export type ParamsArg<A>

SnakeToCamel​

"team_id" -> "teamId" at the type level.

export type SnakeToCamel<S extends string>

src/core/client.ts​

ESPN host roots and the flat-family base URLs.

Import: import { … } from 'sportsdataverse'

FLAT_HOSTS​

Flat family api stem -> host root.

export const FLAT_HOSTS: Record<string, string> =

resolveFlat​

Resolve a flat wrapper def + params to the URL and query it sends.

export function resolveFlat( def: WrapperDef, params: Record<string, any>

makeLeagueModule​

Build an ESPN league's wrapper module from a LeagueConfig at runtime (the written modules under src/generated/espn/ replace this for the shipped leagues).

export function makeLeagueModule( cfg: LeagueConfig ): Record<string, WrapperFn>

makeFlatModule​

Build a flat family's wrapper module from its defs at runtime.

export function makeFlatModule(defs: WrapperDef[]): Record<string, WrapperFn>

src/core/nfl_auth.ts​

NFL.com Shield API auth — the token mint behind the nfl_api family.

Import: import { … } from 'sportsdataverse'

nflTokenGen​

Mint (or reuse) an NFL.com access token.

export async function nflTokenGen(opts: NflTokenOptions

nflHeadersGen​

The authenticated request headers for the NFL.com Shield API.

export async function nflHeadersGen( token?: string ): Promise<Record<string, string>>

nflClearTokenCache​

Forget the cached NFL.com token.

export function nflClearTokenCache(): void

jwtExp​

The exp claim of a JWT (unix seconds), or undefined.

export function jwtExp(token: string): number | null

NFL_API_HOST​

The NFL.com Shield API host.

export const NFL_API_HOST

NflTokenOptions​

Options of nflTokenGen.

export interface NflTokenOptions

src/core/pff_api_runtime.ts​

Subscription-family helpers beyond the generated wrappers — PFF Developer API, KenPom, NFL Pro, 247Sports.

Import: import { … } from 'sportsdataverse'

resolvePffApiKey​

The PFF API key a call will use — api_key, an Authorization header, SDV_PFF_API_KEY, PFF_API_KEY.

export function resolvePffApiKey(apiKey?: string): string | undefined

hasKenpomLogin​

Whether KenPom credentials are available (call args or environment).

export function hasKenpomLogin(): boolean

kenpomLogin​

Log in to kenpom.com once and cache the session.

export async function kenpomLogin(opts: { email?: string; password?: string }

kenpomClearSessionCache​

Forget the cached KenPom session.

export function kenpomClearSessionCache(): void

nflProToken​

The NFL Pro bearer token a call will use (argument, NFLPRO_TOKEN, or a browser login).

export async function nflProToken(opts: { token?: string; email?: string; password?: string }

nflProBrowserLogin​

Log in to NFL Pro with a headless browser (optional playwright) and return the token.

export async function nflProBrowserLogin( email: string, password: string, opts: { playwright?: PlaywrightLike; timeoutMs?: number; deadlineMs?: number }

nflProClearTokenCache​

Forget the cached NFL Pro token.

export function nflProClearTokenCache(): void

NflProAuthError​

NFL Pro could not authenticate (no token, no plan, a failed browser login).

export class NflProAuthError extends SdvError {}

PlaywrightLike​

The minimal playwright surface nflProBrowserLogin needs.

export interface PlaywrightLike

sports247ClearTokenCache​

Forget the cached 247Sports guest token.

export function sports247ClearTokenCache(): void

Generated by tools/codegen/generate.mjs from tools/codegen/utilities.yaml — see How this library is built.