Audit current MLB statTypes and add missing stat models #329

Why

The live MLB Stats API currently exposes a broad set of values through:

https://statsapi.mlb.com/api/v1/statTypes

The package maps returned stat payloads to concrete Pydantic split models by matching each MLB stat type against model classes with a _stat declaration.

As MLB adds or changes stat types, unsupported values may not fail loudly. A stat type with no matching model can result in an outer Stat object with empty parsed splits, which makes unsupported coverage harder to detect.

This issue should audit the current MLB statTypes surface against the models implemented in mlbstatsapi.models.stats.

Goals

• Inventory the current stat types exposed by MLB
• Map each stat type to the package model(s) that support it
• Identify stat types with no matching model
• Live-test questionable or modern stat types against the MLB API
• Verify that supported stat types deserialize into the expected Pydantic split objects
• Identify response shapes that need new models or parser behavior
• Add deterministic regression coverage for any newly supported stat types

Initial audit candidates

The following currently exposed types do not appear to have obvious mappings in the package and should be investigated first:

projected_Zips
projected_ZipsRos
projected_Zips2YR
projected_Zips3YR
metricLog
metricAverages
availableStats
sabermetricsMultiTeam
gameTypeStats
firstYearStats
lastYearStats
atGameStart
vsOpponents
tracking

This list is a starting point, not the authoritative set of unsupported types.

Suggested audit matrix

Track the investigation with something similar to:

Parser behavior to review

create_split_data() / return_splits() currently locate split model classes by inspecting the stat-group module and checking whether the returned stat_type exists in a model class's _stat list.

The audit should verify what happens when MLB returns a valid stat type for which the library has no matching class. Unsupported types should not silently look like successfully parsed empty data.

Do not change this behavior as part of the audit unless the desired compatibility behavior is understood and separately tested.

Acceptance criteria

• Current MLB statTypes inventory is captured
• Every current stat type is classified as supported, unsupported, obsolete/unusable, or needing further investigation
• Existing model _stat declarations are mapped to the MLB inventory
• Suspected unsupported types are tested against the live MLB API where possible
• New model requirements are documented before implementation
• Newly supported models receive deterministic parser/model tests
• Existing stat parsing behavior remains backward compatible unless a separate behavior change is explicitly justified
• Stats documentation is updated when new stat types become supported

Scope

This is primarily a stats-model and parser audit. It is separate from the v1.1.0 async endpoint rollout unless the investigation uncovers a regression that affects the existing public stats methods.