mirror of
https://github.com/sstent/go-garth.git
synced 2025-12-05 23:51:42 +00:00
sync
This commit is contained in:
187
portingplan_3.md
Normal file
187
portingplan_3.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user