ruby_garmin_connect 0.1.0

data/lib/garmin_connect/client.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "date"
+
+module GarminConnect
+  # The main entry point for interacting with the Garmin Connect API.
+  #
+  # @example Basic usage
+  #   client = GarminConnect::Client.new(email: "user@example.com", password: "secret")
+  #   client.login
+  #   puts client.daily_summary
+  #
+  # @example Resume from saved tokens
+  #   client = GarminConnect::Client.new(token_dir: "~/.garminconnect")
+  #   client.login
+  #   puts client.heart_rates
+  #
+  # @example With MFA handler
+  #   client = GarminConnect::Client.new(
+  #     email: "user@example.com",
+  #     password: "secret",
+  #     mfa_handler: -> { print "MFA code: "; gets.chomp }
+  #   )
+  #   client.login
+  class Client
+    include API::User
+    include API::Health
+    include API::Activities
+    include API::BodyComposition
+    include API::Metrics
+    include API::Devices
+    include API::Badges
+    include API::Workouts
+    include API::Wellness
+
+    DEFAULT_TOKEN_DIR = File.expand_path("~/.garminconnect")
+
+    attr_reader :connection
+
+    # @param email [String, nil] Garmin account email
+    # @param password [String, nil] Garmin account password
+    # @param domain [String] "garmin.com" or "garmin.cn"
+    # @param token_dir [String, nil] directory for token persistence (default: ~/.garminconnect)
+    # @param token_string [String, nil] base64-encoded token string (alternative to token_dir)
+    # @param mfa_handler [Proc, nil] called when MFA is needed; must return the code
+    def initialize(email: nil, password: nil, domain: "garmin.com",
+                   token_dir: DEFAULT_TOKEN_DIR, token_string: nil,
+                   mfa_handler: nil)
+      @email = email
+      @password = password
+      @domain = domain
+      @token_dir = token_dir ? File.expand_path(token_dir) : nil
+      @token_string = token_string
+      @mfa_handler = mfa_handler
+
+      @display_name = nil
+      @full_name = nil
+      @unit_system = nil
+      @user_profile_pk = nil
+    end
+
+    # Authenticate with Garmin Connect.
+    # Attempts to resume from saved tokens first, falling back to a fresh login.
+    #
+    # @return [self]
+    def login
+      if resume_from_tokens
+        setup_user_info
+      elsif @email && @password
+        fresh_login
+      else
+        raise AuthenticationError, "No credentials or saved tokens available"
+      end
+
+      self
+    end
+
+    # Check if the client is authenticated with valid tokens.
+    def authenticated?
+      @connection && !@oauth2_token.nil?
+    end
+
+    # Save the current tokens to the configured token directory.
+    # @param directory [String, nil] override the default token directory
+    def save_tokens(directory = @token_dir)
+      raise Error, "No tokens to save" unless @oauth1_token && @oauth2_token
+
+      Auth::TokenStore.save(
+        directory || DEFAULT_TOKEN_DIR,
+        oauth1_token: @oauth1_token,
+        oauth2_token: @oauth2_token
+      )
+    end
+
+    # Serialize tokens to a base64-encoded string.
+    # @return [String]
+    def dump_tokens
+      raise Error, "No tokens to dump" unless @oauth1_token && @oauth2_token
+
+      Auth::TokenStore.dumps(oauth1_token: @oauth1_token, oauth2_token: @oauth2_token)
+    end
+
+    # Log out (clears in-memory tokens).
+    def logout
+      @oauth1_token = nil
+      @oauth2_token = nil
+      @connection = nil
+      @display_name = nil
+      @full_name = nil
+      @unit_system = nil
+      @user_profile_pk = nil
+    end
+
+    private
+
+    def resume_from_tokens
+      oauth1, oauth2 = load_tokens
+      return false unless oauth1 && oauth2
+
+      @oauth1_token = oauth1
+      @oauth2_token = oauth2
+      @domain = oauth1.domain || @domain
+      build_connection
+
+      true
+    rescue GarminConnect::Error
+      false
+    end
+
+    def load_tokens
+      if @token_string
+        Auth::TokenStore.loads(@token_string)
+      elsif @token_dir && Dir.exist?(@token_dir)
+        Auth::TokenStore.load(@token_dir)
+      end
+    end
+
+    def fresh_login
+      @oauth1_token, @oauth2_token = Auth::SSO.login(
+        email: @email,
+        password: @password,
+        domain: @domain,
+        mfa_handler: @mfa_handler
+      )
+
+      build_connection
+      save_tokens if @token_dir
+      setup_user_info
+    end
+
+    def build_connection
+      @connection = Connection.new(
+        oauth1_token: @oauth1_token,
+        oauth2_token: @oauth2_token,
+        domain: @domain,
+        token_dir: @token_dir
+      )
+    end
+
+    def setup_user_info
+      settings = user_settings
+      @unit_system = settings&.dig("userData", "measurementSystem")
+
+      profile = connection.get("/userprofile-service/userprofile/profile")
+      @display_name = profile&.dig("displayName")
+      @full_name = profile&.dig("fullName")
+      @user_profile_pk = profile&.dig("profileId") || settings&.dig("id")
+    rescue HTTPError
+      # Non-fatal: display_name may not be available
+    end
+
+    # Exposed for API modules that need it.
+    def user_profile_pk
+      @user_profile_pk
+    end
+
+    # --- Date helpers ---
+
+    def today
+      Date.today.strftime("%Y-%m-%d")
+    end
+
+    def format_date(date)
+      case date
+      when Date, Time, DateTime
+        date.strftime("%Y-%m-%d")
+      when String
+        date
+      else
+        date.to_s
+      end
+    end
+
+    # Auto-chunk large date ranges into smaller windows.
+    # @param start_date [Date, String]
+    # @param end_date [Date, String]
+    # @param max_days [Integer] maximum days per chunk
+    def chunked_request(start_date, end_date, max_days)
+      start_d = start_date.is_a?(Date) ? start_date : Date.parse(start_date.to_s)
+      end_d = end_date.is_a?(Date) ? end_date : Date.parse(end_date.to_s)
+      results = []
+
+      while start_d <= end_d
+        chunk_end = [start_d + max_days - 1, end_d].min
+        chunk = yield(start_d, chunk_end)
+        results.concat(Array(chunk))
+        start_d = chunk_end + 1
+      end
+
+      results
+    end
+  end
+end

data/lib/garmin_connect/connection.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module GarminConnect
+  # Handles authenticated HTTP requests to the Garmin Connect API.
+  # Automatically refreshes expired OAuth2 tokens using the OAuth1 token.
+  class Connection
+    API_BASE = "https://connectapi.garmin.com"
+    USER_AGENT = "GCM-iOS-5.19.1.2"
+
+    RETRY_OPTIONS = {
+      max: 3,
+      interval: 0.5,
+      backoff_factor: 2,
+      retry_statuses: [408, 500, 502, 503, 504]
+    }.freeze
+
+    attr_reader :domain
+
+    def initialize(oauth1_token:, oauth2_token:, domain: "garmin.com", token_dir: nil)
+      @oauth1_token = oauth1_token
+      @oauth2_token = oauth2_token
+      @domain = domain || "garmin.com"
+      @token_dir = token_dir
+    end
+
+    # Make an authenticated GET request.
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    # Make an authenticated POST request with a JSON body.
+    def post(path, body: nil, params: {})
+      request(:post, path, body: body, params: params)
+    end
+
+    # Make an authenticated PUT request with a JSON body.
+    def put(path, body: nil, params: {})
+      request(:put, path, body: body, params: params)
+    end
+
+    # Make an authenticated DELETE request.
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    # Download raw bytes (for FIT/GPX/TCX file downloads).
+    def download(path, params: {})
+      ensure_valid_token!
+      resp = connection.get(path) do |req|
+        req.headers["Authorization"] = @oauth2_token.authorization_header
+        req.params = params unless params.empty?
+      end
+      handle_errors!(resp)
+      resp.body
+    end
+
+    # Upload a file (multipart form).
+    def upload(path, file_path:, file_name: nil)
+      ensure_valid_token!
+      name = file_name || File.basename(file_path)
+      payload = { file: Faraday::Multipart::FilePart.new(file_path, nil, name) }
+
+      resp = upload_connection.post(path) do |req|
+        req.headers["Authorization"] = @oauth2_token.authorization_header
+        req.body = payload
+      end
+      handle_errors!(resp)
+      parse_response(resp)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: {})
+      ensure_valid_token!
+
+      resp = connection.public_send(method, path) do |req|
+        req.headers["Authorization"] = @oauth2_token.authorization_header
+        req.params = params unless params.empty?
+
+        if body && %i[post put].include?(method)
+          req.headers["Content-Type"] = "application/json"
+          req.body = body.is_a?(String) ? body : JSON.generate(body)
+        end
+      end
+
+      handle_errors!(resp)
+      parse_response(resp)
+    end
+
+    def ensure_valid_token!
+      return unless @oauth2_token.expired?
+
+      @oauth2_token = Auth::SSO.refresh(@oauth1_token, domain: @domain)
+      Auth::TokenStore.save_oauth2(@token_dir, oauth2_token: @oauth2_token) if @token_dir
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: api_base) do |f|
+        f.request :retry, **RETRY_OPTIONS
+        f.adapter Faraday.default_adapter
+      end.tap do |conn|
+        conn.headers["User-Agent"] = USER_AGENT
+        conn.headers["Accept"] = "application/json"
+      end
+    end
+
+    def upload_connection
+      @upload_connection ||= Faraday.new(url: api_base) do |f|
+        f.request :multipart
+        f.request :retry, **RETRY_OPTIONS
+        f.adapter Faraday.default_adapter
+      end.tap do |conn|
+        conn.headers["User-Agent"] = USER_AGENT
+      end
+    end
+
+    def api_base
+      "https://connectapi.#{@domain}"
+    end
+
+    def parse_response(resp)
+      return nil if resp.status == 204
+      return resp.body if resp.body.nil? || resp.body.empty?
+
+      JSON.parse(resp.body)
+    rescue JSON::ParserError
+      resp.body
+    end
+
+    def handle_errors!(resp)
+      return if resp.success?
+
+      error_class = HTTP_ERRORS.fetch(resp.status) do
+        resp.status >= 500 ? ServerError : HTTPError
+      end
+
+      raise error_class.new(
+        "Garmin API error: HTTP #{resp.status}",
+        status: resp.status,
+        body: resp.body
+      )
+    end
+  end
+end

data/lib/garmin_connect/errors.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GarminConnect
+  class Error < StandardError; end
+
+  # Authentication & login errors
+  class AuthenticationError < Error; end
+  class LoginError < AuthenticationError; end
+  class MFARequiredError < AuthenticationError
+    attr_reader :mfa_html
+
+    def initialize(message = "MFA code required", mfa_html: nil)
+      @mfa_html = mfa_html
+      super(message)
+    end
+  end
+
+  class TokenExpiredError < AuthenticationError; end
+
+  # HTTP response errors
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message || "HTTP #{status}")
+    end
+  end
+
+  class BadRequestError < HTTPError; end
+  class UnauthorizedError < HTTPError; end
+  class ForbiddenError < HTTPError; end
+  class NotFoundError < HTTPError; end
+  class TooManyRequestsError < HTTPError; end
+  class ServerError < HTTPError; end
+
+  # Maps HTTP status codes to error classes
+  HTTP_ERRORS = {
+    400 => BadRequestError,
+    401 => UnauthorizedError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    429 => TooManyRequestsError
+  }.freeze
+end

data/lib/garmin_connect/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GarminConnect
+  VERSION = "0.1.0"
+end

data/lib/garmin_connect.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "garmin_connect/version"
+require_relative "garmin_connect/errors"
+require_relative "garmin_connect/auth/oauth1_token"
+require_relative "garmin_connect/auth/oauth2_token"
+require_relative "garmin_connect/auth/token_store"
+require_relative "garmin_connect/auth/sso"
+require_relative "garmin_connect/connection"
+require_relative "garmin_connect/api/user"
+require_relative "garmin_connect/api/health"
+require_relative "garmin_connect/api/activities"
+require_relative "garmin_connect/api/body_composition"
+require_relative "garmin_connect/api/metrics"
+require_relative "garmin_connect/api/devices"
+require_relative "garmin_connect/api/badges"
+require_relative "garmin_connect/api/workouts"
+require_relative "garmin_connect/api/wellness"
+require_relative "garmin_connect/client"
+
+module GarminConnect
+  class << self
+    # Convenience method to create and login a client in one step.
+    #
+    # @example
+    #   client = GarminConnect.login(email: "user@example.com", password: "secret")
+    #   client.daily_summary
+    #
+    # @example Resume from tokens
+    #   client = GarminConnect.login(token_dir: "~/.garminconnect")
+    def login(**options)
+      Client.new(**options).login
+    end
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: ruby_garmin_connect
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DRBragg
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-cookie_jar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.7
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: oauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: A comprehensive Ruby wrapper for the Garmin Connect API, providing access
+  to health, fitness, activity, and device data.
+email:
+- drbragg@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/garmin_connect.rb
+- lib/garmin_connect/api/activities.rb
+- lib/garmin_connect/api/badges.rb
+- lib/garmin_connect/api/body_composition.rb
+- lib/garmin_connect/api/devices.rb
+- lib/garmin_connect/api/health.rb
+- lib/garmin_connect/api/metrics.rb
+- lib/garmin_connect/api/user.rb
+- lib/garmin_connect/api/wellness.rb
+- lib/garmin_connect/api/workouts.rb
+- lib/garmin_connect/auth/oauth1_token.rb
+- lib/garmin_connect/auth/oauth2_token.rb
+- lib/garmin_connect/auth/sso.rb
+- lib/garmin_connect/auth/token_store.rb
+- lib/garmin_connect/client.rb
+- lib/garmin_connect/connection.rb
+- lib/garmin_connect/errors.rb
+- lib/garmin_connect/version.rb
+homepage: https://github.com/drbragg/garmin_connect
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/drbragg/garmin_connect
+  source_code_uri: https://github.com/drbragg/garmin_connect
+  changelog_uri: https://github.com/drbragg/garmin_connect/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Garmin Connect API
+test_files: []