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