go-garth/portingplan_3.md

# Implementation Plan for Garmin Connect Go Client - Feature Parity

## Phase 1: Complete Core Data Types (Priority: High)

### 1.1 Complete HRV Data Implementation
**File**: `garth/data/hrv.go`
**Reference**: Python `garth/hrv.py` and API examples in README

**Tasks**:
- Implement `Get()` method calling `/wellness-service/wellness/dailyHrvData/{username}?date={date}`
- Complete `ParseHRVReadings()` function based on Python parsing logic
- Add missing fields to `HRVSummary` struct (reference Python HRVSummary dataclass)
- Implement `List()` method using BaseData pattern

### 1.2 Complete Weight Data Implementation  
**File**: `garth/data/weight.go`
**Reference**: Python `garth/weight.py`

**Tasks**:
- Implement `Get()` method calling `/weight-service/weight/dateRange?startDate={date}&endDate={date}`
- Add all missing fields from Python WeightData dataclass
- Implement proper unit conversions (grams vs kg)
- Add `List()` method for date ranges

### 1.3 Complete Sleep Data Implementation
**File**: `garth/data/sleep.go` 
**Reference**: Python `garth/sleep.py`

**Tasks**:
- Fix `Get()` method to properly parse nested sleep data structures
- Add missing `SleepScores` fields from Python implementation
- Implement sleep quality calculations and derived properties
- Add proper timezone handling for sleep timestamps

## Phase 2: Add Missing Core API Methods (Priority: High)

### 2.1 Add ConnectAPI Method
**File**: `garth/client/client.go`
**Reference**: Python `garth/client.py` `connectapi()` method

**Tasks**:
- Add `ConnectAPI(path, params, method)` method to Client struct
- Support GET/POST with query parameters and JSON body
- Return raw JSON response for flexible endpoint access
- Add proper error handling and authentication headers

### 2.2 Add File Operations
**File**: `garth/client/client.go`
**Reference**: Python `garth/client.py` upload/download methods

**Tasks**:
- Complete `Upload()` method for FIT file uploads to `/upload-service/upload`
- Add `Download()` method for activity exports
- Handle multipart form uploads properly
- Add progress callbacks for large files

## Phase 3: Complete Stats Implementation (Priority: Medium)

### 3.1 Fix Stats Pagination
**File**: `garth/stats/base.go`
**Reference**: Python `garth/stats.py` pagination logic

**Tasks**:
- Fix recursive pagination in `BaseStats.List()` method
- Ensure proper date range handling for >28 day requests
- Add proper error handling for missing data pages
- Test with large date ranges (>365 days)

### 3.2 Add Missing Stats Types
**Files**: `garth/stats/` directory
**Reference**: Python `garth/stats/` directory

**Tasks**:
- Add `WeeklySteps`, `WeeklyStress`, `WeeklyHRV` types
- Implement monthly and yearly aggregation types if present in Python
- Add any missing daily stats types by comparing Python vs Go stats files

## Phase 4: Add Advanced Features (Priority: Medium)

### 4.1 Add Data Validation
**Files**: All data types
**Reference**: Python Pydantic dataclass validators

**Tasks**:
- Add `Validate()` methods to all data structures
- Implement field validation rules from Python Pydantic models
- Add data sanitization for API responses
- Handle missing/null fields gracefully

### 4.2 Add Derived Properties
**Files**: `garth/data/` directory
**Reference**: Python dataclass `@property` methods

**Tasks**:
- Add calculated fields to BodyBattery (current_level, max_level, min_level, battery_change)
- Add sleep duration calculations and sleep efficiency
- Add stress level aggregations and summaries
- Implement timezone-aware timestamp helpers

## Phase 5: Enhanced Error Handling & Logging (Priority: Low)

### 5.1 Improve Error Types
**File**: `garth/errors/errors.go`
**Reference**: Python `garth/exc.py`

**Tasks**:
- Add specific error types for rate limiting, MFA required, etc.
- Implement error retry logic with exponential backoff
- Add request/response logging for debugging
- Handle partial failures in List() operations

### 5.2 Add Configuration Options
**File**: `garth/client/client.go`
**Reference**: Python `garth/configure.py`

**Tasks**:
- Add proxy support configuration
- Add custom timeout settings
- Add SSL verification options
- Add custom user agent configuration

## Phase 6: Testing & Documentation (Priority: Medium)

### 6.1 Add Integration Tests
**File**: `garth/integration_test.go`
**Reference**: Python test files

**Tasks**:
- Add real API tests with saved session files
- Test all data types with real Garmin data
- Add benchmark comparisons with Python timings
- Test error scenarios and edge cases

### 6.2 Add Usage Examples
**Files**: `examples/` directory (create new)
**Reference**: Python README examples

**Tasks**:
- Port all Python README examples to Go
- Add Jupyter notebook equivalent examples
- Create data export utilities matching Python functionality
- Add data visualization examples using Go libraries

## Implementation Guidelines

### Code Standards
- Follow existing Go package structure
- Use existing error handling patterns
- Maintain interface compatibility where possible
- Add comprehensive godoc comments

### Testing Strategy
- Add unit tests for each new method
- Use table-driven tests for data parsing
- Mock HTTP responses for reliable testing
- Test timezone handling thoroughly

### Data Structure Mapping
- Compare Python dataclass fields to Go struct fields
- Ensure JSON tag mapping matches API responses
- Handle optional fields with pointers (`*int`, `*string`)
- Use proper Go time.Time for timestamps

### API Endpoint Discovery
- Check Python source for endpoint URLs
- Verify parameter names and formats
- Test with actual API calls using saved sessions
- Document any API differences found

## Completion Criteria

Each phase is complete when:
1. All methods have working implementations (no `return nil, nil`)
2. Unit tests pass with >80% coverage
3. Integration tests pass with real API data
4. Documentation includes usage examples
5. Benchmarks show performance is maintained or improved

## Estimated Timeline
- Phase 1: 2-3 weeks
- Phase 2: 1-2 weeks  
- Phase 3: 1 week
- Phase 4: 2 weeks
- Phase 5: 1 week
- Phase 6: 1 week

**Total**: 8-10 weeks for complete feature parity