strava-ruby-client 3.0.0 → 3.1.0

data/lib/strava/api/endpoints/routes.rb

@@ -3,12 +3,21 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava routes.
+      #
+      # Routes are manually-created paths on Strava that can be used for planning.
+      # Routes can be exported in GPX or TCX format and can include waypoints,
+      # elevation data, and other metadata.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Routes
+      #
       module Routes
         #
         # Returns a GPX file of the route.
         #
-        # @option options [String] :id
-        #   Route id.
+        # @param id_or_options [String, Integer, Hash] Either a route ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def export_route_gpx(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -16,10 +25,10 @@ module Strava
         end
 
         #
-        # Returns a TCS file of the route.
+        # Returns a TCX file of the route.
         #
-        # @option options [String] :id
-        #   Route id.
+        # @param id_or_options [String, Integer, Hash] Either a route ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def export_route_tcx(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -29,8 +38,8 @@ module Strava
         #
         # Returns a route using its identifier.
         #
-        # @option options [String] :id
-        #   Route id.
+        # @param id_or_options [String, Integer, Hash] Either a route ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def route(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -40,12 +49,10 @@ module Strava
         #
         # Returns a list of the routes created by the authenticated athlete using their athlete ID.
         #
-        # @option options [Integer] :id
-        #   The identifier of the athlete.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # @param id_or_options [String, Integer, Hash] Either an athlete ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page. Defaults to 30
         #
         def athlete_routes(id_or_options, options = {}, &block)
           id, options = parse_args(id_or_options, options)

data/lib/strava/api/endpoints/segment_efforts.rb

@@ -3,12 +3,21 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava segment efforts.
+      #
+      # Segment efforts represent an athlete's attempt on a specific segment during an
+      # activity. Each time an activity passes through a segment, a segment effort is
+      # created with details like elapsed time, distance, and ranking information.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-SegmentEfforts
+      #
       module SegmentEfforts
         #
         # Returns a segment effort from an activity that is owned by the authenticated athlete.
         #
-        # @option options [String] :id
-        #   The identifier of the segment effort.
+        # @param id_or_options [String, Integer, Hash] Either a segment effort ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def segment_effort(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -18,12 +27,10 @@ module Strava
         #
         # Returns a set of the authenticated athlete's segment efforts for a given segment.
         #
-        # @option options [Integer] :id
-        #   The identifier of the segment.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # @param id_or_options [String, Integer, Hash] Either a segment ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page. Defaults to 30
         #
         def segment_efforts(id_or_options, options = {}, &block)
           id, options = parse_args(id_or_options, options)

data/lib/strava/api/endpoints/segments.rb

@@ -3,21 +3,40 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava segments.
+      #
+      # Segments are specific sections of road or trail where athletes can compete for time.
+      # This module provides methods for exploring, retrieving, and starring segments.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Segments
+      #
       module Segments
         #
-        # Returns the top 10 segments matching a specified query.
+        # Explore segments in a geographic area.
         #
-        # @option options [Array[Float]] :bounds
-        #   The latitude and longitude for two points describing a rectangular boundary for the search: [southwest corner latitude, southwest corner longitude, northeast corner latitude, northeast corner longitude].
-        # @option options [String] :activity_type
-        #   Desired activity type. May take one of the following values: running, riding.
-        # @option options [Integer] :min_cat
-        #   The minimum climbing category.
-        # @option options [Integer] :max_cat
-        #   The maximum climbing category.
+        # Returns the top 10 segments matching a specified query within a rectangular
+        # geographic boundary. Useful for discovering popular segments in an area.
+        #
+        # @param [Hash] options Search parameters
+        # @option options [Array<Float>] :bounds Required. Rectangular boundary as [sw_lat, sw_lng, ne_lat, ne_lng]
+        # @option options [String] :activity_type Activity type: 'running' or 'riding'
+        # @option options [Integer] :min_cat Minimum climbing category (0-5)
+        # @option options [Integer] :max_cat Maximum climbing category (0-5)
+        #
+        # @return [Array<Strava::Models::ExplorerSegment>] Array of segments
+        #
+        # @example Explore segments in an area
+        #   segments = client.explore_segments(
+        #     bounds: [40.7,-74.0,40.8,-73.9],
+        #     activity_type: 'running'
+        #   )
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Segments-exploreSegments
         #
         def explore_segments(options = {})
-          throw ArgumentError.new('Required argument :bounds missing') if options[:bounds].nil?
+          raise ArgumentError, 'Required argument :bounds missing' if options[:bounds].nil?
+
           bounds = options[:bounds]
           bounds = bounds.map(&:to_s).join(',') if bounds.is_a?(Array)
           get('segments/explore', options.merge(bounds: bounds))['segments'].map do |row|
@@ -28,10 +47,21 @@ module Strava
         #
         # List of the authenticated athlete's starred segments.
         #
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # Returns a paginated list of segments that the authenticated athlete has starred.
+        # Starred segments are favorites that the athlete wants to track their performance on.
+        #
+        # @param options [Hash] Pagination options
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page. Defaults to 30
+        #
+        # @yield [SummarySegment] Yields each segment in the paginated results
+        # @return [Array<SummarySegment>, Cursor] Array of starred segments or Cursor for iteration
+        #
+        # @example List all starred segments
+        #   starred = client.starred_segments
+        #   starred.each do |segment|
+        #     puts "#{segment.name}: #{segment.distance_s}"
+        #   end
         #
         def starred_segments(options = {}, &block)
           paginate 'segments/starred', options, Strava::Models::SummarySegment, &block
@@ -40,8 +70,17 @@ module Strava
         #
         # Returns the specified segment.
         #
-        # @option options [String] :id
-        #   The identifier of the segment.
+        # Retrieves detailed information about a specific segment including location,
+        # elevation profile, and the athlete's personal records on that segment.
+        #
+        # @param id_or_options [String, Integer, Hash] Either a segment ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        #
+        # @return [DetailedSegment] The detailed segment information
+        #
+        # @example Get a segment by ID
+        #   segment = client.segment(229781)
+        #   puts "#{segment.name}: #{segment.distance_s} with #{segment.average_grade}% grade"
         #
         def segment(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -51,14 +90,28 @@ module Strava
         #
         # Stars/Unstars the given segment for the authenticated athlete.
         #
-        # @option options [String] :id
-        #   The identifier of the segment to star.
-        # @option options [Boolean] :starred
-        #   If true, star the segment; if false, unstar the segment.
+        # Adds or removes a segment from the athlete's starred/favorite segments.
+        # Starred segments appear in the athlete's starred segments list and can
+        # be used to track performance over time.
+        #
+        # @param id_or_options [String, Integer, Hash] Either a segment ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Boolean] :starred If true, star the segment; if false, unstar the segment (required)
+        #
+        # @return [DetailedSegment] The updated segment with new starred status
+        #
+        # @raise [ArgumentError] If :starred option is not provided
+        #
+        # @example Star a segment
+        #   segment = client.star_segment(229781, starred: true)
+        #
+        # @example Unstar a segment
+        #   segment = client.star_segment(229781, starred: false)
         #
         def star_segment(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
-          throw ArgumentError.new('Required argument :starred missing') if options[:starred].nil?
+          raise ArgumentError, 'Required argument :starred missing' if options[:starred].nil?
+
           Strava::Models::DetailedSegment.new(put("segments/#{id}/starred", options))
         end
       end

data/lib/strava/api/endpoints/streams.rb

@@ -3,16 +3,24 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava streams.
+      #
+      # Streams represent the raw data of uploaded activities. They can be thought of
+      # as a collection of time series data, where each data point is sampled at a
+      # specific time or distance. Available stream types include altitude, cadence,
+      # distance, heartrate, latlng, moving, power, temp, time, and velocity.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Streams
+      #
       module Streams
         #
         # Returns the given activity's streams.
         #
-        # @option options [String] :id
-        #   The identifier of the activity.
-        # @option options [Array[String]] :keys
-        #   Desired stream types.
-        # @option options [Boolean] :key_by_type
-        #   Must be true.
+        # @param id_or_options [String, Integer, Hash] Either an activity ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Array<String>] :keys Desired stream types (e.g., ['time', 'latlng', 'distance', 'altitude'])
+        # @option options [Boolean] :key_by_type Must be true
         #
         def activity_streams(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -25,12 +33,10 @@ module Strava
         #
         # Returns a set of streams for a segment effort completed by the authenticated athlete.
         #
-        # @option options [String] :id
-        #   The identifier of the segment effort.
-        # @option options [Array[String]] :keys
-        #   The types of streams to return.
-        # @option options [Boolean] :key_by_type
-        #   Must be true.
+        # @param id_or_options [String, Integer, Hash] Either a segment effort ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Array<String>] :keys The types of streams to return
+        # @option options [Boolean] :key_by_type Must be true
         #
         def segment_effort_streams(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -43,12 +49,10 @@ module Strava
         #
         # Returns the given segment's streams.
         #
-        # @option options [String] :id
-        #   The identifier of the segment.
-        # @option options [Array[String]] :keys
-        #   The types of streams to return.
-        # @option options [Boolean] :key_by_type
-        #   Must be true.
+        # @param id_or_options [String, Integer, Hash] Either a segment ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Array<String>] :keys The types of streams to return
+        # @option options [Boolean] :key_by_type Must be true
         #
         def segment_streams(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)

data/lib/strava/api/endpoints/uploads.rb

@@ -3,6 +3,16 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava uploads.
+      #
+      # Uploads allow you to create activities by uploading activity files in various
+      # formats such as FIT, TCX, and GPX. After uploading, the file is processed
+      # asynchronously and you can check the upload status to determine when the
+      # activity has been created.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Uploads
+      #
       module Uploads
         #
         # Uploads a new data file to create an activity from.
@@ -29,8 +39,8 @@ module Strava
         #
         # Returns an upload for a given identifier.
         #
-        # @option options [String] :id
-        #   The identifier of the upload.
+        # @param id_or_options [String, Integer, Hash] Either an upload ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def upload(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)

data/lib/strava/api/pagination.rb

@@ -41,16 +41,41 @@ module Strava
         @collection.size
       end
 
+      #
+      # Iterates over each item in the paginated collection.
+      #
+      # @yield [Object] Yields each item in the collection
+      # @return [void]
+      #
       def each
         @collection.each { |c| yield c if block_given? }
       end
 
       private
 
+      #
+      # Delegates missing methods to the underlying collection.
+      #
+      # Allows the Pagination object to respond to array methods by
+      # forwarding them to the internal collection array.
+      #
+      # @api private
+      # @param method_symbol [Symbol] The method name to forward
+      # @param args [Array] Arguments to pass to the method
+      # @return [Object] Result from the delegated method
+      #
       def method_missing(method_symbol, ...)
         @collection.send(method_symbol, ...)
       end
 
+      #
+      # Checks if the underlying collection responds to a method.
+      #
+      # @api private
+      # @param method_name [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] true if the collection responds to the method
+      #
       def respond_to_missing?(method_name, include_private = false)
         super
       end

data/lib/strava/api/ratelimit.rb

@@ -2,7 +2,41 @@
 
 module Strava
   module Api
+    #
+    # Handles Strava API rate limit information from HTTP responses.
+    #
+    # Strava enforces rate limits on API requests with two windows:
+    # - 15-minute window: 600 requests per 15 minutes (short-term limit)
+    # - Daily window: 30,000 requests per day (long-term limit)
+    #
+    # This class extracts and provides easy access to rate limit data from
+    # HTTP response headers.
+    #
+    # @see Strava::Web::ApiResponse
+    # @see https://developers.strava.com/docs/rate-limits/ Strava API Rate Limiting documentation
+    #
+    # @example Checking rate limits after an API call
+    #   activity = client.activity(1234567890)
+    #   ratelimit = activity.http_response.ratelimit
+    #
+    #   puts "15-minute limit: #{ratelimit.fifteen_minutes_limit}"
+    #   puts "15-minute usage: #{ratelimit.fifteen_minutes_usage}"
+    #   puts "15-minute remaining: #{ratelimit.fifteen_minutes_remaining}"
+    #
+    #   puts "Daily limit: #{ratelimit.total_day}"
+    #   puts "Daily usage: #{ratelimit.total_day_usage}"
+    #   puts "Daily remaining: #{ratelimit.total_day_remaining}"
+    #
+    #   if ratelimit.exceeded?
+    #     puts "Rate limit exceeded!"
+    #   end
+    #
     class Ratelimit
+      #
+      # Initialize a new Ratelimit instance from an HTTP response.
+      #
+      # @param response [Faraday::Response] HTTP response containing rate limit headers
+      #
       def initialize(response)
         @response = response
         @headers = response.headers

data/lib/strava/deep_copyable.rb

@@ -1,9 +1,28 @@
 # frozen_string_literal: true
 
 module Strava
+  #
+  # Mixin module for deep copying objects.
+  #
+  # This module provides a helper method for creating deep copies of objects
+  # using Ruby's Marshal serialization. Unlike shallow cloning (which only
+  # duplicates the top-level object), deep copying recursively duplicates all
+  # nested objects and collections.
+  #
+  # This is particularly useful when working with model objects that contain
+  # nested hashes or arrays, ensuring modifications to the copy don't affect
+  # the original object.
+  #
+  # @example Deep copying a nested hash
+  #   include Strava::DeepCopyable
+  #   original = {a: {b: [1, 2, 3]}}
+  #   copy = deep_copy(original)
+  #   copy[:a][:b] << 4
+  #   original[:a][:b]  # => [1, 2, 3] (unchanged)
+  #
   module DeepCopyable
     #
-    # Ruby's way of creating a true deep copy/clone
+    # Ruby's way of creating a true deep copy/clone.
     #
     # @param [Object] obj of any kind
     #

data/lib/strava/errors/fault.rb

@@ -2,15 +2,47 @@
 
 module Strava
   module Errors
+    #
+    # Base error class for Strava API client errors.
+    #
+    # This exception is raised when the Strava API returns an error response.
+    # It extends Faraday::ClientError and provides convenient access to the
+    # error message, response headers, and detailed error information from
+    # the API response body.
+    #
+    # @see Faraday::ClientError
+    #
     class Fault < ::Faraday::ClientError
+      #
+      # Returns the error message from the API response.
+      #
+      # Extracts the message from the response body if available,
+      # otherwise falls back to the parent class message.
+      #
+      # @return [String] The error message
+      #
       def message
         response[:body]['message'] || super
       end
 
+      #
+      # Returns the HTTP response headers.
+      #
+      # @return [Hash] The response headers hash
+      #
       def headers
         response[:headers]
       end
 
+      #
+      # Returns detailed error information from the API response.
+      #
+      # The Strava API may return an 'errors' array in the response body
+      # containing detailed information about validation errors or other
+      # specific error conditions.
+      #
+      # @return [Array, nil] Array of error details, or nil if not present
+      #
       def errors
         response[:body]['errors']
       end

data/lib/strava/errors/ratelimit_error.rb

@@ -2,22 +2,57 @@
 
 module Strava
   module Errors
+    #
+    # Exception raised when API rate limits are exceeded.
+    #
+    # Strava enforces rate limits on API requests to prevent abuse. When your
+    # application exceeds these limits (either per 15 minutes or per day), the
+    # API returns a 429 Too Many Requests response, which triggers this exception.
+    #
+    # This error includes rate limit information extracted from the response headers,
+    # allowing you to determine current usage and when limits will reset.
+    #
+    # @see Strava::Api::Ratelimit
+    # @see https://developers.strava.com/docs/rate-limits/
+    #
     class RatelimitError < ::Faraday::ClientError
+      # @return [Strava::Api::Ratelimit] Rate limit information from response headers
       attr_reader :ratelimit
 
+      #
+      # Initialize a new rate limit error.
+      #
+      # @param env [Faraday::Env] The Faraday request environment
+      # @param response [Hash] The HTTP response hash
+      #
       def initialize(env, response)
         @ratelimit = Strava::Api::Ratelimit.new(env.response)
         super(response)
       end
 
+      #
+      # Returns the error message from the API response.
+      #
+      # @return [String] The error message
+      #
       def message
         response[:body]['message'] || super
       end
 
+      #
+      # Returns the HTTP response headers.
+      #
+      # @return [Hash] The response headers hash
+      #
       def headers
         response[:headers]
       end
 
+      #
+      # Returns detailed error information from the API response.
+      #
+      # @return [Array, nil] Array of error details, or nil if not present
+      #
       def errors
         response[:body]['errors']
       end

data/lib/strava/errors/upload_error.rb

@@ -2,29 +2,84 @@
 
 module Strava
   module Errors
+    #
+    # Exception raised when an activity upload fails.
+    #
+    # When uploading activity files (FIT, TCX, GPX) to Strava, the API processes
+    # the file asynchronously and may encounter errors during processing. This
+    # exception is raised when the upload fails, and includes information about
+    # the upload status and error details.
+    #
+    # The error provides access to the upload model, which contains detailed
+    # information about what went wrong during the upload processing.
+    #
+    # @see Strava::Models::Upload
+    # @see https://developers.strava.com/docs/reference/#api-Uploads
+    #
     class UploadError < ::Faraday::ClientError
+      #
+      # Returns the HTTP response status code.
+      #
+      # @return [Integer] The HTTP status code
+      #
       def status
         response[:status]
       end
 
+      #
+      # Returns the HTTP response headers.
+      #
+      # @return [Hash] The response headers hash
+      #
       def headers
         response[:headers]
       end
 
+      #
+      # Returns the error message from the upload response.
+      #
+      # Extracts the error message from the response body's 'error' field,
+      # or falls back to the parent class message if not available.
+      #
+      # @return [String] The error message
+      #
       def message
         body[:error] || super
       end
 
+      #
+      # Returns the upload processing status from the response.
+      #
+      # The upload status indicates where in the processing pipeline the
+      # upload failed (e.g., 'error', 'processing', 'ready').
+      #
+      # @return [String] The upload status
+      #
       def error_status
         body[:status]
       end
 
+      #
+      # Returns the upload model containing detailed upload information.
+      #
+      # The upload model includes fields like id, external_id, error,
+      # status, and activity_id (if the upload succeeded before encountering
+      # an error).
+      #
+      # @return [Strava::Models::Upload] The upload model
+      #
       def upload
         @upload ||= Strava::Models::Upload.new(body)
       end
 
       private
 
+      #
+      # Returns the response body with indifferent access.
+      #
+      # @api private
+      # @return [HashWithIndifferentAccess] The response body hash
+      #
       def body
         (response[:body] || {}).with_indifferent_access
       end

data/lib/strava/logger.rb

@@ -3,7 +3,34 @@
 require 'logger'
 
 module Strava
+  #
+  # Default logger for the Strava client library.
+  #
+  # Extends the standard Ruby Logger class and provides a default logger
+  # instance configured to output warnings and errors to STDOUT. The logger
+  # can be customized via the Web configuration to control HTTP request/response
+  # logging.
+  #
+  # @example Using the default logger
+  #   Strava::Logger.logger.info('Making API request')
+  #
+  # @example Customizing the logger
+  #   Strava::Web.configure do |config|
+  #     config.logger = Logger.new('strava.log')
+  #   end
+  #
+  # @see Logger
+  #
   class Logger < ::Logger
+    #
+    # Returns the default logger instance.
+    #
+    # Creates a memoized logger that outputs to STDOUT with a default
+    # log level of WARN. This logger is used by default for HTTP request
+    # logging unless overridden in the configuration.
+    #
+    # @return [Strava::Logger] The default logger instance
+    #
     def self.logger
       @logger ||= begin
         logger = new $stdout