strava-ruby-client 3.0.0.pre.2 → 3.1.0

data/lib/strava/models/xoms.rb

@@ -2,11 +2,45 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents segment leaderboard achievements (KOM/QOM).
+    #
+    # Contains information about King of the Mountain (KOM), Queen of the Mountain (QOM),
+    # and overall segment records. This model is not documented in the official Strava
+    # API reference.
+    #
+    # @note This model is not documented by Strava API documentation. Properties
+    #   are inferred from API responses.
+    #
+    # @see Strava::Models::DetailedActivity
+    # @see Strava::Models::Destination
+    #
+    # @example Accessing XOM (KOM/QOM) information
+    #   activity = client.activity(1234567890)
+    #   if activity.xoms
+    #     puts "KOM: #{activity.xoms.kom}"
+    #     puts "QOM: #{activity.xoms.qom}"
+    #     puts "Overall: #{activity.xoms.overall}"
+    #     if activity.xoms.destination
+    #       puts "Segment: #{activity.xoms.destination.name}"
+    #     end
+    #   end
+    #
     class Xoms < Strava::Models::Response
+      # @return [String, Integer, nil] King of the Mountain achievement data
+      # @note Not documented by Strava API
       property 'kom'
+
+      # @return [String, Integer, nil] Queen of the Mountain achievement data
+      # @note Not documented by Strava API
       property 'qom'
+
+      # @return [String, Integer, nil] Overall segment record data
+      # @note Not documented by Strava API
       property 'overall'
+
+      # @return [Destination, nil] Link to the segment where this achievement was earned
+      # @note Not documented by Strava API
       property 'destination', transform_with: ->(v) { Strava::Models::Destination.new(v) }
     end
   end

data/lib/strava/models/zone_range.rb

@@ -2,9 +2,28 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-ZoneRange
+    #
+    # Represents a single training zone range.
+    #
+    # Training zones define intensity levels for heart rate or power. Each zone
+    # has a minimum and maximum value that defines the range for that intensity level.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-ZoneRange Strava API ZoneRange reference
+    # @see Strava::Models::HeartRateZoneRanges
+    # @see Strava::Models::PowerZoneRanges
+    # @see Strava::Models::TimedZoneRange
+    #
+    # @example Accessing zone ranges
+    #   zones = client.athlete_zones
+    #   zones.heart_rate.zones.each_with_index do |zone, i|
+    #     puts "Zone #{i + 1}: #{zone.min}-#{zone.max} bpm"
+    #   end
+    #
     class ZoneRange < Strava::Models::Response
+      # @return [Integer] Maximum value for this zone (e.g., maximum heart rate or power)
       property 'max'
+
+      # @return [Integer] Minimum value for this zone (e.g., minimum heart rate or power)
       property 'min'
     end
   end

data/lib/strava/models/zones.rb

@@ -2,9 +2,40 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-Zones
+    #
+    # Represents an athlete's training zones configuration.
+    #
+    # Training zones are used to define intensity levels for heart rate and power.
+    # These zones help athletes train at specific intensities and track time spent
+    # in each zone during activities.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-Zones Strava API Zones reference
+    # @see Strava::Models::HeartRateZoneRanges
+    # @see Strava::Models::PowerZoneRanges
+    # @see Strava::Api::Client#athlete_zones
+    #
+    # @example Accessing athlete's training zones
+    #   zones = client.athlete_zones
+    #
+    #   # Heart rate zones
+    #   if zones.heart_rate
+    #     zones.heart_rate.zones.each_with_index do |zone, i|
+    #       puts "HR Zone #{i + 1}: #{zone.min}-#{zone.max} bpm"
+    #     end
+    #   end
+    #
+    #   # Power zones
+    #   if zones.power
+    #     zones.power.zones.each_with_index do |zone, i|
+    #       puts "Power Zone #{i + 1}: #{zone.min}-#{zone.max}W"
+    #     end
+    #   end
+    #
     class Zones < Strava::Models::Response
+      # @return [HeartRateZoneRanges, nil] Heart rate zone configuration with zone ranges
       property 'heart_rate', transform_with: ->(v) { Strava::Models::HeartRateZoneRanges.new(v) }
+
+      # @return [PowerZoneRanges, nil] Power zone configuration with zone ranges (for cyclists)
       property 'power', transform_with: ->(v) { Strava::Models::PowerZoneRanges.new(v) }
     end
   end

data/lib/strava/oauth/client.rb

@@ -2,9 +2,50 @@
 
 module Strava
   module OAuth
+    #
+    # OAuth client for Strava authentication.
+    #
+    # This client handles the OAuth 2.0 authentication flow with Strava, including:
+    # * Generating authorization URLs
+    # * Exchanging authorization codes for access tokens
+    # * Refreshing expired access tokens
+    #
+    # @example Basic OAuth flow
+    #   client = Strava::OAuth::Client.new(
+    #     client_id: "your_client_id",
+    #     client_secret: "your_client_secret"
+    #   )
+    #
+    #   # Step 1: Get authorization URL
+    #   url = client.authorize_url(
+    #     redirect_uri: 'http://localhost:3000/callback',
+    #     scope: 'read,activity:read_all'
+    #   )
+    #   # Redirect user to this URL
+    #
+    #   # Step 2: Exchange code for token
+    #   token = client.oauth_token(code: params[:code])
+    #   # Store token.access_token and token.refresh_token
+    #
+    #   # Step 3: Refresh token when expired
+    #   new_token = client.oauth_token(
+    #     refresh_token: saved_refresh_token,
+    #     grant_type: 'refresh_token'
+    #   )
+    #
+    # @see https://developers.strava.com/docs/authentication/
+    #
     class Client < Strava::Web::Client
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Initialize a new OAuth client.
+      #
+      # @param [Hash] options Configuration options
+      # @option options [String] :client_id Strava application client ID (required)
+      # @option options [String] :client_secret Strava application client secret (required)
+      # @option options [String] :endpoint OAuth endpoint URL (defaults to https://www.strava.com/oauth)
+      #
       def initialize(options = {})
         Strava::OAuth::Config::ATTRIBUTES.each do |key|
           send("#{key}=", options[key] || Strava::OAuth.config.send(key))
@@ -13,20 +54,31 @@ module Strava
       end
 
       #
-      # Obtain the request access URL.
-      #
-      # @option options [Object] :redirect_uri
-      #   URL to which the user will be redirected after authentication.
-      # @option options [Object] :response_type
-      #   Must be code.
-      # @option options [Object] :approval_prompt
-      #   Prompt behavior, force or auto.
-      # @option options [Object] :scope
-      #   Requested scopes, as a comma delimited string.
-      # @option options [Object] :state
-      #   Returned in the redirect URI.
+      # Generate the authorization URL for OAuth flow.
+      #
+      # Creates a URL to redirect users to for Strava authorization. After the user
+      # authorizes your application, they will be redirected back to your redirect_uri
+      # with an authorization code.
+      #
+      # @param [Hash] options Authorization parameters
+      # @option options [String] :redirect_uri URL where user is redirected after authorization (default: http://localhost)
+      # @option options [String] :response_type Must be 'code' (default: 'code')
+      # @option options [String] :approval_prompt 'force' to always show approval page, 'auto' to auto-approve (default: 'auto')
+      # @option options [String] :scope Comma-delimited string of permissions (default: 'read')
+      #   Available scopes: read, read_all, profile:read_all, profile:write, activity:read, activity:read_all, activity:write
+      # @option options [String] :state Optional value returned in redirect URI for CSRF protection
+      #
+      # @return [String] Full authorization URL
+      #
+      # @example Generate authorization URL
+      #   url = client.authorize_url(
+      #     redirect_uri: 'https://myapp.com/callback',
+      #     scope: 'read,activity:read_all,activity:write',
+      #     state: 'random_state_value'
+      #   )
+      #
       # @see https://developers.strava.com/docs/authentication/
-      # @return [String] URL to redirect the user to.
+      #
       def authorize_url(options = {})
         query = options.merge(
           client_id: client_id || raise(ArgumentError, 'Missing Strava client id.'),
@@ -40,14 +92,33 @@ module Strava
       end
 
       #
-      # Complete the authentication process.
+      # Exchange authorization code for access token or refresh an expired token.
+      #
+      # This method handles two OAuth flows:
+      # 1. Initial token exchange: Exchange authorization code for access/refresh tokens
+      # 2. Token refresh: Use refresh_token to get new access/refresh tokens
+      #
+      # @param [Hash] options Token request parameters
+      # @option options [String] :code Authorization code from redirect (for initial exchange)
+      # @option options [String] :refresh_token Refresh token (for token refresh)
+      # @option options [String] :grant_type Grant type: 'authorization_code' (default) or 'refresh_token'
+      #
+      # @return [Strava::Models::Token] Token object with access_token, refresh_token, expires_at, and athlete
+      #
+      # @example Exchange authorization code for token
+      #   token = client.oauth_token(code: 'authorization_code_from_redirect')
+      #   access_token = token.access_token
+      #   refresh_token = token.refresh_token
+      #   expires_at = token.expires_at
+      #
+      # @example Refresh an expired token
+      #   new_token = client.oauth_token(
+      #     refresh_token: 'saved_refresh_token',
+      #     grant_type: 'refresh_token'
+      #   )
       #
-      # @option options [Object] :code
-      #   The code parameter obtained in the redirect.
-      # @option options [Object] :grant_type
-      #   The grant type for the request.
       # @see https://developers.strava.com/docs/authentication/
-      # @return [Hash] Token information.
+      #
       def oauth_token(options = {})
         query = options.merge(
           client_id: client_id || raise(ArgumentError, 'Missing Strava client id.'),
@@ -59,10 +130,27 @@ module Strava
       end
 
       class << self
+        #
+        # Configure the OAuth client with a block.
+        #
+        # @yield [Config] Yields the configuration module for setup
+        # @return [Module] The Config module
+        #
+        # @example
+        #   Strava::OAuth::Client.configure do |config|
+        #     config.client_id = ENV['STRAVA_CLIENT_ID']
+        #     config.client_secret = ENV['STRAVA_CLIENT_SECRET']
+        #   end
+        #
         def configure
           block_given? ? yield(Config) : Config
         end
 
+        #
+        # Returns the current OAuth client configuration.
+        #
+        # @return [Module] The Config module
+        #
         def config
           Config
         end

data/lib/strava/oauth/config.rb

@@ -2,9 +2,25 @@
 
 module Strava
   module OAuth
+    #
+    # Configuration module for the OAuth client.
+    #
+    # This module manages OAuth-specific configuration settings including the
+    # OAuth endpoint URL and application credentials (client ID and secret)
+    # required for token exchange and refresh operations.
+    #
+    # @example Configure OAuth client
+    #   Strava::OAuth.configure do |config|
+    #     config.client_id = ENV['STRAVA_CLIENT_ID']
+    #     config.client_secret = ENV['STRAVA_CLIENT_SECRET']
+    #   end
+    #
+    # @see https://developers.strava.com/docs/authentication/
+    #
     module Config
       extend self
 
+      # @return [Array<Symbol>] List of configurable OAuth attributes
       ATTRIBUTES = %i[
         endpoint
         client_id
@@ -13,6 +29,14 @@ module Strava
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Reset configuration to default values.
+      #
+      # Sets the endpoint to the default Strava OAuth URL and clears
+      # the client credentials.
+      #
+      # @return [void]
+      #
       def reset
         self.endpoint = 'https://www.strava.com/oauth'
         self.client_id = nil
@@ -21,10 +45,27 @@ module Strava
     end
 
     class << self
+      #
+      # Configure the OAuth client with a block.
+      #
+      # @yield [Config] Yields the configuration module for setup
+      # @return [Module] The Config module
+      #
+      # @example
+      #   Strava::OAuth.configure do |config|
+      #     config.client_id = '12345'
+      #     config.client_secret = 'your_client_secret'
+      #   end
+      #
       def configure
         block_given? ? yield(Config) : Config
       end
 
+      #
+      # Returns the current OAuth configuration.
+      #
+      # @return [Module] The Config module
+      #
       def config
         Config
       end

data/lib/strava/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Strava
-  VERSION = '3.0.0.pre.2'
+  VERSION = '3.1.0'
 end

data/lib/strava/web/api_response.rb

@@ -2,11 +2,37 @@
 
 module Strava
   module Web
+    #
+    # Wraps an HTTP response with rate limit information.
+    #
+    # This class provides access to both the raw HTTP response and
+    # parsed rate limit data from the response headers.
+    #
+    # @see Strava::Api::Ratelimit
+    # @see Strava::Models::Mixins::HttpResponse
+    #
+    # @example Accessing response data
+    #   activity = client.activity(1234567890)
+    #   api_response = activity.http_response
+    #
+    #   # Access raw HTTP response
+    #   status = api_response.response.status
+    #   headers = api_response.response.headers
+    #
+    #   # Access rate limit information
+    #   puts "Requests remaining: #{api_response.ratelimit.fifteen_minutes_remaining}"
+    #
     class ApiResponse
-      attr_accessor :response, :ratelimit
+      # @return [Faraday::Response] The raw HTTP response
+      attr_accessor :response
 
+      # @return [Strava::Api::Ratelimit] Rate limit information extracted from response headers
+      attr_accessor :ratelimit
+
+      #
+      # Initialize a new ApiResponse with an HTTP response.
       #
-      # @param [Faraday::Response] http_response
+      # @param http_response [Faraday::Response] HTTP response from the Strava API
       #
       def initialize(http_response)
         @response = http_response

data/lib/strava/web/client.rb

@@ -2,12 +2,35 @@
 
 module Strava
   module Web
+    #
+    # Base web client class for making HTTP requests to Strava APIs.
+    #
+    # This class provides the foundation for all Strava client implementations
+    # (API, OAuth, and Webhooks clients). It handles HTTP connection management,
+    # request execution, and configuration management.
+    #
+    # The client includes mixins for connection handling and HTTP request methods,
+    # and manages configuration attributes like endpoint URLs, user agents, and
+    # authentication tokens.
+    #
+    # @see Strava::Web::Connection
+    # @see Strava::Web::Request
+    #
     class Client
       include Strava::Web::Connection
       include Strava::Web::Request
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Initialize a new client instance.
+      #
+      # @param options [Hash] Configuration options for the client
+      # @option options [String] :endpoint The API endpoint URL
+      # @option options [String] :user_agent The user agent string
+      # @option options [String] :token The access token for authentication
+      # @option options [Logger] :logger Custom logger instance
+      #
       def initialize(options = {})
         Strava::Web::Config::ATTRIBUTES.each do |key|
           send("#{key}=", options[key] || Strava::Web.config.send(key))
@@ -15,26 +38,73 @@ module Strava
         @logger ||= Strava::Logger.logger
       end
 
+      #
+      # Returns the API endpoint URL for this client.
+      #
+      # @note This method must be implemented by subclasses
+      # @raise [NotImplementedError] if not implemented by subclass
+      # @return [String] The API endpoint URL
+      #
       def endpoint
         raise NotImplementedError
       end
 
       class << self
+        #
+        # Configure the client with a block or return the configuration.
+        #
+        # @yield [Config] Yields the configuration module for setup
+        # @return [Module] The Config module
+        #
+        # @example Configure the client
+        #   Strava::Web::Client.configure do |config|
+        #     config.endpoint = 'https://www.strava.com/api/v3'
+        #   end
+        #
         def configure
           block_given? ? yield(Config) : Config
         end
 
+        #
+        # Returns the current configuration.
+        #
+        # @return [Module] The Config module
+        #
         def config
           Config
         end
       end
 
+      #
+      # Parse method arguments that can be either (id, options) or (options).
+      #
+      # This helper method standardizes the common pattern where Strava API methods
+      # accept either a resource ID as the first parameter followed by an options hash,
+      # or just an options hash containing an :id key.
+      #
+      # @param id_or_options [String, Integer, Hash] Either a resource ID or options hash
+      # @param options [Hash] Options hash (when first param is an ID)
+      #
+      # @raise [ArgumentError] if the :id is missing from the options hash
+      #
+      # @return [Array<(String, Hash)>] Tuple of [id, options]
+      #
+      # @example With separate ID and options
+      #   parse_args('12345', {per_page: 10})
+      #   # => ['12345', {per_page: 10}]
+      #
+      # @example With ID in options hash
+      #   parse_args({id: '12345', per_page: 10})
+      #   # => ['12345', {per_page: 10}]
+      #
       def parse_args(id_or_options, options = {})
         if id_or_options.is_a?(Hash)
-          throw ArgumentError.new('Required argument :id missing') if id_or_options[:id].nil?
+          raise ArgumentError, 'Required argument :id missing' if id_or_options[:id].nil?
+
           [id_or_options[:id], id_or_options.except(:id)]
         else
-          throw ArgumentError.new('Required argument :id missing') if id_or_options.nil?
+          raise ArgumentError, 'Required argument :id missing' if id_or_options.nil?
+
           [id_or_options, options]
         end
       end

data/lib/strava/web/config.rb

@@ -2,9 +2,24 @@
 
 module Strava
   module Web
+    #
+    # Configuration module for web client HTTP settings.
+    #
+    # This module manages HTTP-related configuration settings shared across
+    # all Strava web clients (API, OAuth, Webhooks), including proxy settings,
+    # SSL certificate validation, timeouts, and logging.
+    #
+    # @example Configure web client settings
+    #   Strava::Web.configure do |config|
+    #     config.user_agent = 'MyApp/1.0'
+    #     config.timeout = 30
+    #     config.logger = Logger.new(STDOUT)
+    #   end
+    #
     module Config
       extend self
 
+      # @return [Array<Symbol>] List of configurable HTTP attributes
       ATTRIBUTES = %i[
         proxy
         user_agent
@@ -17,6 +32,14 @@ module Strava
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Reset configuration to default values.
+      #
+      # Sets the user agent to the default client identifier and clears
+      # all optional settings (proxy, SSL certificates, timeouts, logger).
+      #
+      # @return [void]
+      #
       def reset
         self.user_agent = "Strava Ruby Client/#{Strava::VERSION}"
         self.ca_path = nil
@@ -29,10 +52,27 @@ module Strava
     end
 
     class << self
+      #
+      # Configure the web client with a block.
+      #
+      # @yield [Config] Yields the configuration module for setup
+      # @return [Module] The Config module
+      #
+      # @example
+      #   Strava::Web.configure do |config|
+      #     config.proxy = 'http://proxy.example.com:8080'
+      #     config.ca_file = '/path/to/ca-bundle.crt'
+      #   end
+      #
       def configure
         block_given? ? yield(Config) : Config
       end
 
+      #
+      # Returns the current web client configuration.
+      #
+      # @return [Module] The Config module
+      #
       def config
         Config
       end

data/lib/strava/web/connection.rb

@@ -2,13 +2,52 @@
 
 module Strava
   module Web
+    #
+    # HTTP connection management for Strava web clients.
+    #
+    # This module provides connection handling and configuration for making HTTP
+    # requests to Strava APIs. It sets up a Faraday connection with proper headers,
+    # middleware, SSL configuration, and timeout settings.
+    #
+    # The connection is configured with:
+    # - JSON request and response handling
+    # - Automatic error raising for failed responses
+    # - Optional logging
+    # - SSL certificate validation
+    # - Request timeouts
+    #
+    # @api private
+    #
     module Connection
       private
 
+      #
+      # Returns HTTP headers to be included in requests.
+      #
+      # This method can be overridden in including classes to provide
+      # custom headers (e.g., authentication headers).
+      #
+      # @api private
+      # @return [Hash] HTTP headers hash
+      #
       def headers
         {}
       end
 
+      #
+      # Establishes and returns a Faraday HTTP connection.
+      #
+      # Creates a memoized Faraday connection configured with:
+      # - Base endpoint URL
+      # - Custom headers including Accept and User-Agent
+      # - Proxy settings if configured
+      # - SSL certificate paths
+      # - Request timeouts
+      # - Middleware stack for multipart, URL encoding, error handling, and JSON parsing
+      #
+      # @api private
+      # @return [Faraday::Connection] Configured Faraday connection instance
+      #
       def connection
         @connection ||= begin
           options = {