Finalize v0.4.0 release

CHANGELOG.md

@@ -11,6 +11,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+**Type-Safe Enums for Stats Parameters** - Added three new enums for improved type safety and IDE autocomplete:
+
+- `StatsRankType.OPEN` and `StatsRankType.WOMEN` for rank_type parameters (used in 8 endpoints)
+- `SystemCode.OPEN` and `SystemCode.WOMEN` for system_code parameter in overall() endpoint
+- `MajorTournament.YES` and `MajorTournament.NO` for major parameter in lucrative_tournaments() endpoint
+- All enums maintain full backwards compatibility with string parameters
+- Union types (`Enum | str`) ensure existing code continues to work without changes
+- Enums are exported from main package: `from ifpa_api import StatsRankType, SystemCode, MajorTournament`
+
+**Usage Example:**
+```python
+from ifpa_api import IfpaClient, StatsRankType, MajorTournament
+
+client = IfpaClient()
+
+# Use enums for type safety (recommended)
+stats = client.stats.country_players(rank_type=StatsRankType.WOMEN)
+tournaments = client.stats.lucrative_tournaments(
+    rank_type=StatsRankType.WOMEN,
+    major=MajorTournament.YES
+)
+
+# Strings still work (backwards compatible)
+stats = client.stats.country_players(rank_type="WOMEN")
+```
+
+**Benefits:**
+- ✅ Type safety: Catch typos at development time
+- ✅ IDE autocomplete: Discover available values
+- ✅ Self-documenting: Clear what values are valid
+- ✅ No breaking changes: Strings still work
+
 **Stats Resource (NEW)** - 10 operational endpoints for IFPA statistical data:
 
 The Stats API was documented in v0.1.0 as returning 404 errors from the live API. All endpoints are now operational and fully implemented with comprehensive testing.
@@ -48,6 +80,7 @@ The Stats API was documented in v0.1.0 as returning 404 errors from the live API
 ### Testing
 - 1333 lines of unit tests with inline mocked responses
 - 642 lines of integration tests against live API
+- 15 new tests specifically for enum type validation and backwards compatibility
 - Stats-specific test fixtures for date ranges and validation helpers
 - All tests passing
 - Maintained 99% code coverage

README.md

@@ -15,7 +15,7 @@ A typed Python client for the [IFPA (International Flipper Pinball Association)
 
 **Complete documentation**: https://johnsosoka.github.io/ifpa-api-python/
 
-## What's New in 0.3.0
+## What's New in 0.4.0
 
 **Quality of Life Improvements** - Enhanced debugging, pagination, and error handling:
 
@@ -25,6 +25,9 @@ from ifpa_api import (
     IfpaApiError,
     SeriesPlayerNotFoundError,
     TournamentNotLeagueError,
+    StatsRankType,
+    MajorTournament,
+    SystemCode,
 )
 
 # 1. Enhanced Error Messages - Full request context in exceptions
@@ -270,13 +273,18 @@ active_only = client.series.list(active=True)
 ### Stats
 
 ```python
+from ifpa_api import IfpaClient, StatsRankType, SystemCode, MajorTournament
+
+client = IfpaClient()
+
 # Get overall IFPA statistics
-stats = client.stats.overall()
+stats = client.stats.overall(system_code=SystemCode.OPEN)
 print(f"Active players: {stats.stats.active_player_count:,}")
 print(f"Tournaments this year: {stats.stats.tournament_count_this_year:,}")
 
 # Get top point earners for a time period
 points = client.stats.points_given_period(
+    rank_type=StatsRankType.OPEN,
     start_date="2024-01-01",
     end_date="2024-12-31",
     limit=25
@@ -285,24 +293,30 @@ for player in points.stats[:10]:
     print(f"{player.first_name} {player.last_name}: {player.wppr_points} pts")
 
 # Get largest tournaments
-tournaments = client.stats.largest_tournaments(country_code="US")
+tournaments = client.stats.largest_tournaments(
+    rank_type=StatsRankType.OPEN,
+    country_code="US"
+)
 for tourney in tournaments.stats[:10]:
     print(f"{tourney.tournament_name}: {tourney.player_count} players")
 
-# Get player counts by country
-country_stats = client.stats.country_players()
+# Get player counts by country (women's rankings)
+country_stats = client.stats.country_players(rank_type=StatsRankType.WOMEN)
 for country in country_stats.stats[:10]:
     print(f"{country.country_name}: {country.player_count:,} players")
 
 # Get most active players in a time period
 active_players = client.stats.events_attended_period(
+    rank_type=StatsRankType.OPEN,
     start_date="2024-01-01",
     end_date="2024-12-31",
     country_code="US",
     limit=25
 )
 ```
 
+**Type Safety**: Stats methods accept typed enums (e.g., `StatsRankType.WOMEN`) or strings for backwards compatibility.
+
 ### Reference Data
 
 ```python

docs/getting-started/installation.md

@@ -24,7 +24,7 @@ After installation, verify that the package is installed correctly:
 ```python
 import ifpa_api
 
-print(ifpa_api.__version__)  # Should print: 0.3.0
+print(ifpa_api.__version__)  # Should print: 0.4.0
 ```
 
 You can also check the installed version using pip: