ruby_garmin_connect 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08c6d390104bc4f19e46f95d0726171890e2c0f3c41e165b1afca94031c0f243'
+  data.tar.gz: 8225469c95d81af76180c1e6e1c4229f3caaa27cef9eb675e1c514ec208b1145
+SHA512:
+  metadata.gz: e3f740b9dda27508940450bacfe50f7ad74e060f2c9f97100500fcb1b200424cfb425efd0a187d61f5d55e03af04e3ada0b2029284a6542adbefb70f971c0ede
+  data.tar.gz: 2609e8c7e033db637fa8358c409cda7d5d31c8018b6d43a7506a309140febaa90c7ce271a79600cdeea40b0a5f278304f7511ccb045cfe6b7b2ac706ada4e6e1

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 (2026-02-11)
+
+- Initial release
+- Full Garmin Connect OAuth authentication (SSO + OAuth1 + OAuth2)
+- MFA support
+- Token persistence (file and string-based, garth-compatible)
+- Automatic token refresh
+- 108 API methods across 9 categories:
+  - User & Profile
+  - Daily Health (steps, HR, HRV, sleep, stress, body battery, SpO2, respiration)
+  - Activities (list, details, CRUD, download in 5 formats, upload)
+  - Body Composition & Weight (weigh-ins, hydration, blood pressure)
+  - Advanced Metrics (VO2 max, training readiness, endurance/hill score, race predictions, lactate threshold)
+  - Devices & Gear (device settings, gear management, gear-activity linking)
+  - Badges, Challenges & Goals (earned/available badges, challenges, personal records, goals)
+  - Workouts & Training Plans
+  - Wellness (menstrual cycle, pregnancy, lifestyle logging, GraphQL)
+- Retry with exponential backoff on server errors
+- Typed error hierarchy

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DRBragg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,295 @@
+# GarminConnect
+
+A Ruby client for the Garmin Connect API. Provides access to health, fitness, activity, and device data from your Garmin account.
+
+Inspired by [python-garminconnect](https://github.com/cyberjunky/python-garminconnect), rebuilt idiomatically for Ruby.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "garmin_connect"
+```
+
+Or install directly:
+
+```
+gem install garmin_connect
+```
+
+## Quick Start
+
+```ruby
+require "garmin_connect"
+
+# Login with credentials (tokens are saved to ~/.garminconnect automatically)
+client = GarminConnect.login(email: "you@example.com", password: "your-password")
+
+# Subsequent sessions resume from saved tokens (no re-login for ~1 year)
+client = GarminConnect.login
+
+# Get today's stats
+puts client.daily_summary
+puts client.heart_rates
+puts client.sleep_data
+puts client.stress
+```
+
+## Authentication
+
+The gem uses the same OAuth flow as the Garmin Connect mobile app:
+
+1. SSO login with your email/password
+2. Exchange for an OAuth1 token (~1 year lifetime)
+3. Exchange OAuth1 for an OAuth2 Bearer token (~20 hours)
+4. Auto-refresh when the OAuth2 token expires
+
+### MFA Support
+
+If your account has MFA enabled, the gem prompts via `$stdin` by default. You can provide a custom handler:
+
+```ruby
+client = GarminConnect::Client.new(
+  email: "you@example.com",
+  password: "your-password",
+  mfa_handler: -> { print "MFA code: "; gets.chomp }
+)
+client.login
+```
+
+### Token Storage
+
+Tokens are saved to `~/.garminconnect` by default. You can customize this:
+
+```ruby
+# Custom directory
+client = GarminConnect::Client.new(token_dir: "/path/to/tokens")
+
+# Base64-encoded string (useful for environment variables)
+encoded = client.dump_tokens
+client = GarminConnect::Client.new(token_string: encoded, token_dir: nil)
+
+# Disable persistence entirely
+client = GarminConnect::Client.new(token_dir: nil)
+```
+
+### Token Interoperability
+
+Token files are compatible with [garth](https://github.com/matin/garth) (the Python auth library). If you have existing tokens from the Python library, point `token_dir` at the same directory.
+
+## API Reference
+
+### User & Profile
+
+```ruby
+client.user_settings           # Measurement system, sleep settings, etc.
+client.user_profile            # Profile configuration
+client.personal_information    # Age, gender, email, biometric profile
+client.display_name            # "YourDisplayName"
+client.full_name               # "Your Full Name"
+client.unit_system             # "statute_us" or "metric"
+```
+
+### Daily Health
+
+```ruby
+client.daily_summary(date)      # Steps, calories, distance, active minutes
+client.heart_rates(date)        # Heart rate data with resting HR
+client.resting_heart_rate(start_date, end_date)
+client.hrv(date)                # Heart rate variability
+client.sleep_data(date)         # Sleep stages, duration, scores
+client.stress(date)             # All-day stress levels
+client.body_battery(start, end) # Body battery reports
+client.body_battery_events(date)
+client.steps_data(date)         # Steps chart data
+client.floors(date)             # Floors climbed
+client.respiration(date)        # Respiration rate
+client.spo2(date)               # Blood oxygen
+client.intensity_minutes(date)  # Intensity minutes
+client.daily_events(date)       # Auto-detected activities
+client.request_reload(date)     # Request data reload from device
+```
+
+### Activities
+
+```ruby
+# Listing
+client.activities(start: 0, limit: 20)
+client.activities_by_date("2026-01-01", "2026-01-31")
+client.activity_count
+client.last_activity
+
+# Details
+client.activity(activity_id)
+client.activity_details(activity_id)
+client.activity_splits(activity_id)
+client.activity_typed_splits(activity_id)
+client.activity_split_summaries(activity_id)
+client.activity_weather(activity_id)
+client.activity_hr_zones(activity_id)
+client.activity_power_zones(activity_id)
+client.activity_exercise_sets(activity_id)
+client.activity_types
+
+# CRUD
+client.create_activity(payload_hash)
+client.rename_activity(activity_id, "Morning Run")
+client.update_activity_type(activity_id, type_dto)
+client.delete_activity(activity_id)
+
+# Download & Upload
+client.download_activity(activity_id, format: :original) # :tcx, :gpx, :kml, :csv
+client.upload_activity("/path/to/file.fit")
+
+# Progress
+client.progress_summary("2026-01-01", "2026-12-31", metric: "distance")
+```
+
+### Body Composition & Weight
+
+```ruby
+client.body_composition(start_date, end_date)
+client.weigh_ins(start_date, end_date)
+client.daily_weigh_ins(date)
+client.add_weigh_in(84.5, date: "2026-02-11", unit_key: "kg")
+client.delete_weigh_in(date, weight_pk)
+```
+
+### Hydration
+
+```ruby
+client.hydration(date)
+client.log_hydration(250, date: "2026-02-11")   # 250 ml
+client.log_hydration(-250, date: "2026-02-11")  # Subtract
+```
+
+### Blood Pressure
+
+```ruby
+client.blood_pressure(start_date, end_date)
+client.log_blood_pressure(systolic: 120, diastolic: 80, pulse: 65)
+client.delete_blood_pressure(date, version)
+```
+
+### Advanced Metrics
+
+```ruby
+client.max_metrics(date)                # VO2 Max
+client.training_readiness(date)         # Training readiness score
+client.training_status(date)            # Aggregated training status
+client.endurance_score(date)            # Single day
+client.endurance_score(start_date: s, end_date: e) # Date range
+client.hill_score(date)
+client.race_predictions                 # 5k, 10k, half, full marathon
+client.fitness_age(date)
+client.lactate_threshold                # Latest
+client.lactate_threshold_history(start_date, end_date)
+client.cycling_ftp                      # Functional Threshold Power
+```
+
+### Historical Data
+
+```ruby
+client.daily_steps(start_date, end_date)       # Auto-chunked at 28 days
+client.weekly_steps(end_date, weeks: 52)
+client.weekly_stress(end_date, weeks: 52)
+client.weekly_intensity_minutes(start_date, end_date)
+```
+
+### Devices & Gear
+
+```ruby
+# Devices
+client.devices
+client.device_settings(device_id)
+client.last_used_device
+client.primary_training_device
+client.device_solar_data(device_id, start_date, end_date)
+client.device_alarms                     # Alarms across all devices
+
+# Gear
+client.gear
+client.activity_gear(activity_id)
+client.gear_stats(gear_uuid)
+client.gear_defaults
+client.set_gear_default(gear_uuid, activity_type)
+client.link_gear(gear_uuid, activity_id)
+client.unlink_gear(gear_uuid, activity_id)
+client.gear_activities(gear_uuid)
+```
+
+### Badges, Challenges & Goals
+
+```ruby
+client.earned_badges
+client.available_badges
+client.in_progress_badges
+client.adhoc_challenges
+client.badge_challenges
+client.available_badge_challenges
+client.non_completed_badge_challenges
+client.virtual_challenges
+client.personal_records
+client.goals(status: "active")
+```
+
+### Workouts & Training Plans
+
+```ruby
+client.workouts(start: 0, limit: 20)
+client.workout(workout_id)
+client.download_workout(workout_id)
+client.create_workout(payload_hash)
+client.scheduled_workout(id)
+client.training_plans
+client.training_plan(plan_id)
+client.adaptive_training_plan(plan_id)
+```
+
+### Wellness & Misc
+
+```ruby
+client.menstrual_data(date)
+client.menstrual_calendar(start_date, end_date)
+client.pregnancy_summary
+client.lifestyle_logging(date)
+client.graphql(query_string, variables: {})
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.daily_summary
+rescue GarminConnect::UnauthorizedError
+  # Token expired or invalid
+rescue GarminConnect::TooManyRequestsError
+  # Rate limited, back off
+rescue GarminConnect::NotFoundError
+  # Resource doesn't exist
+rescue GarminConnect::ServerError
+  # Garmin's servers are having issues
+rescue GarminConnect::HTTPError => e
+  # Any other HTTP error
+  puts e.status
+  puts e.body
+rescue GarminConnect::AuthenticationError
+  # Login/token issues
+rescue GarminConnect::Error
+  # Catch-all for gem errors
+end
+```
+
+## Development
+
+```
+git clone https://github.com/drbragg/garmin_connect.git
+cd garmin_connect
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

data/lib/garmin_connect/api/activities.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module GarminConnect
+  module API
+    # Activity listing, details, CRUD, and download/upload endpoints.
+    module Activities
+      DOWNLOAD_FORMATS = {
+        original: "/download-service/files/activity/%s",
+        tcx: "/download-service/export/tcx/activity/%s",
+        gpx: "/download-service/export/gpx/activity/%s",
+        kml: "/download-service/export/kml/activity/%s",
+        csv: "/download-service/export/csv/activity/%s"
+      }.freeze
+
+      # List activities with optional filters.
+      # @param start [Integer] pagination offset
+      # @param limit [Integer] max results
+      # @param activity_type [String, nil] filter by activity type
+      # @param sort_order [String] "asc" or "desc"
+      def activities(start: 0, limit: 20, activity_type: nil, sort_order: "desc")
+        params = { "start" => start, "limit" => limit }
+        params["activityType"] = activity_type if activity_type
+        params["sortOrder"] = sort_order
+
+        connection.get("/activitylist-service/activities/search/activities", params: params)
+      end
+
+      # Get activities within a date range.
+      # @param start_date [Date, String]
+      # @param end_date [Date, String]
+      # @param activity_type [String, nil]
+      def activities_by_date(start_date, end_date, activity_type: nil)
+        params = {
+          "startDate" => format_date(start_date),
+          "endDate" => format_date(end_date),
+          "start" => 0,
+          "limit" => 100
+        }
+        params["activityType"] = activity_type if activity_type
+
+        connection.get("/activitylist-service/activities/search/activities", params: params)
+      end
+
+      # Get the total activity count.
+      def activity_count
+        connection.get("/activitylist-service/activities/count")
+      end
+
+      # Get the most recent activity.
+      def last_activity
+        results = activities(start: 0, limit: 1)
+        results&.first
+      end
+
+      # Get a single activity's summary.
+      # @param activity_id [String, Integer]
+      def activity(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}")
+      end
+
+      # Get detailed activity data (charts, polylines).
+      # @param activity_id [String, Integer]
+      # @param max_chart_size [Integer]
+      # @param max_polyline_size [Integer]
+      def activity_details(activity_id, max_chart_size: 2000, max_polyline_size: 4000)
+        connection.get(
+          "/activity-service/activity/#{activity_id}/details",
+          params: { "maxChartSize" => max_chart_size, "maxPolylineSize" => max_polyline_size }
+        )
+      end
+
+      # Get activity splits.
+      def activity_splits(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/splits")
+      end
+
+      # Get typed activity splits.
+      def activity_typed_splits(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/typedsplits")
+      end
+
+      # Get activity split summaries.
+      def activity_split_summaries(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/split_summaries")
+      end
+
+      # Get weather data for an activity.
+      def activity_weather(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/weather")
+      end
+
+      # Get heart rate time-in-zones for an activity.
+      def activity_hr_zones(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/hrTimeInZones")
+      end
+
+      # Get power time-in-zones for an activity.
+      def activity_power_zones(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/powerTimeInZones")
+      end
+
+      # Get exercise sets for an activity.
+      def activity_exercise_sets(activity_id)
+        connection.get("/activity-service/activity/#{activity_id}/exerciseSets")
+      end
+
+      # Get all available activity types.
+      def activity_types
+        connection.get("/activity-service/activity/activityTypes")
+      end
+
+      # Get heart rate activities for a specific date.
+      def heart_rate_activities(date = today)
+        connection.get("/mobile-gateway/heartRate/forDate/#{format_date(date)}")
+      end
+
+      # --- CRUD ---
+
+      # Create a manual activity from a hash/JSON payload.
+      # @param payload [Hash] the activity data
+      def create_activity(payload)
+        connection.post("/activity-service/activity", body: payload)
+      end
+
+      # Rename an activity.
+      # @param activity_id [String, Integer]
+      # @param name [String]
+      def rename_activity(activity_id, name)
+        connection.put(
+          "/activity-service/activity/#{activity_id}",
+          body: { "activityId" => activity_id, "activityName" => name }
+        )
+      end
+
+      # Change an activity's type.
+      # @param activity_id [String, Integer]
+      # @param activity_type [Hash] the activityTypeDTO
+      def update_activity_type(activity_id, activity_type)
+        connection.put(
+          "/activity-service/activity/#{activity_id}",
+          body: { "activityId" => activity_id, "activityTypeDTO" => activity_type }
+        )
+      end
+
+      # Delete an activity.
+      def delete_activity(activity_id)
+        connection.delete("/activity-service/activity/#{activity_id}")
+      end
+
+      # --- Download / Upload ---
+
+      # Download an activity file.
+      # @param activity_id [String, Integer]
+      # @param format [Symbol] :original, :tcx, :gpx, :kml, or :csv
+      # @return [String] raw file bytes
+      def download_activity(activity_id, format: :original)
+        path = DOWNLOAD_FORMATS.fetch(format) do
+          raise ArgumentError, "Unknown format: #{format}. Use: #{DOWNLOAD_FORMATS.keys.join(", ")}"
+        end
+
+        connection.download(path % activity_id)
+      end
+
+      # Upload an activity file (FIT, GPX, or TCX).
+      # @param file_path [String] path to the file
+      def upload_activity(file_path)
+        connection.upload("/upload-service/upload", file_path: file_path)
+      end
+
+      # --- Progress ---
+
+      # Get progress summary between dates.
+      # @param start_date [Date, String]
+      # @param end_date [Date, String]
+      # @param metric [String] e.g., "distance", "duration", "elevationGain"
+      def progress_summary(start_date, end_date, metric: "distance")
+        connection.get(
+          "/fitnessstats-service/activity",
+          params: {
+            "startDate" => format_date(start_date),
+            "endDate" => format_date(end_date),
+            "aggregation" => "lifetime",
+            "groupByParentActivityType" => true,
+            "metric" => metric
+          }
+        )
+      end
+    end
+  end
+end

data/lib/garmin_connect/api/badges.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module GarminConnect
+  module API
+    # Badges, challenges, personal records, and goals endpoints.
+    module Badges
+      # Get all earned badges.
+      def earned_badges
+        connection.get("/badge-service/badge/earned")
+      end
+
+      # Get all available badges.
+      def available_badges
+        connection.get(
+          "/badge-service/badge/available",
+          params: { "showExclusiveBadge" => true }
+        )
+      end
+
+      # Get badges currently in progress.
+      def in_progress_badges
+        earned = earned_badges
+        available = available_badges
+        return [] unless earned.is_a?(Array) && available.is_a?(Array)
+
+        earned_ids = earned.map { |b| b["badgeId"] }.compact.to_set
+        available.reject { |b| earned_ids.include?(b["badgeId"]) }
+      end
+
+      # Get historical ad-hoc challenges.
+      # @param start [Integer] pagination offset
+      # @param limit [Integer]
+      def adhoc_challenges(start: 0, limit: 20)
+        connection.get(
+          "/adhocchallenge-service/adHocChallenge/historical",
+          params: { "start" => start, "limit" => limit }
+        )
+      end
+
+      # Get completed badge challenges.
+      def badge_challenges(start: 0, limit: 20)
+        connection.get(
+          "/badgechallenge-service/badgeChallenge/completed",
+          params: { "start" => start, "limit" => limit }
+        )
+      end
+
+      # Get available badge challenges.
+      def available_badge_challenges(start: 0, limit: 20)
+        connection.get(
+          "/badgechallenge-service/badgeChallenge/available",
+          params: { "start" => start, "limit" => limit }
+        )
+      end
+
+      # Get non-completed badge challenges.
+      def non_completed_badge_challenges(start: 0, limit: 20)
+        connection.get(
+          "/badgechallenge-service/badgeChallenge/non-completed",
+          params: { "start" => start, "limit" => limit }
+        )
+      end
+
+      # Get in-progress virtual challenges.
+      def virtual_challenges(start: 0, limit: 20)
+        connection.get(
+          "/badgechallenge-service/virtualChallenge/inProgress",
+          params: { "start" => start, "limit" => limit }
+        )
+      end
+
+      # --- Personal Records ---
+
+      # Get personal records.
+      # @param display_name [String] defaults to the logged-in user
+      def personal_records(display_name = self.display_name)
+        connection.get("/personalrecord-service/personalrecord/prs/#{display_name}")
+      end
+
+      # --- Goals ---
+
+      # Get goals by status.
+      # @param status [String] "active", "future", or "past"
+      # @param start [Integer] pagination offset
+      # @param limit [Integer]
+      def goals(status: "active", start: 0, limit: 20)
+        connection.get(
+          "/goal-service/goal/goals",
+          params: { "status" => status, "start" => start, "limit" => limit, "sortOrder" => "asc" }
+        )
+      end
+    end
+  end
+end