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

data/lib/strava/models/mixins/estimated_moving_time.rb

@@ -3,14 +3,32 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides estimated moving time formatting methods.
+      #
+      # Estimated moving time is Strava's prediction of how long it will take
+      # to complete a route based on distance, elevation, and typical speeds.
+      # This is commonly used for routes.
+      #
+      # @example Using estimated moving time helpers
+      #   route = client.route(1234567)
+      #   puts route.estimated_moving_time              # => 5400 (seconds)
+      #   puts route.estimated_moving_time_in_hours_s   # => "1h30m"
+      #
       module EstimatedMovingTime
         extend ActiveSupport::Concern
         include TimeInHours
 
         included do
+          # @return [Integer] Estimated moving time in seconds
           property 'estimated_moving_time'
         end
 
+        #
+        # Returns formatted estimated moving time as hours, minutes, and seconds.
+        #
+        # @return [String, nil] Formatted time string (e.g., "1h23m45s", "45m30s", "30s")
+        #
         def estimated_moving_time_in_hours_s
           time_in_hours_s estimated_moving_time
         end

data/lib/strava/models/mixins/http_response.rb

@@ -3,17 +3,53 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides access to HTTP response data and rate limit information.
+      #
+      # This mixin is included in Response (the base class for most API models)
+      # and provides access to the underlying HTTP response, which contains
+      # important metadata like rate limit information.
+      #
+      # @example Checking rate limits
+      #   activity = client.activity(1234567890)
+      #   ratelimit = activity.http_response.ratelimit
+      #
+      #   puts "15-min limit: #{ratelimit.fifteen_minutes_limit}"
+      #   puts "15-min used: #{ratelimit.fifteen_minutes_usage}"
+      #   puts "15-min remaining: #{ratelimit.fifteen_minutes_remaining}"
+      #
+      #   puts "Daily limit: #{ratelimit.daily_limit}"
+      #   puts "Daily used: #{ratelimit.daily_usage}"
+      #   puts "Daily remaining: #{ratelimit.daily_remaining}"
+      #
+      # @see Strava::Web::ApiResponse
+      # @see Strava::Api::Ratelimit
+      #
       module HttpResponse
         extend ActiveSupport::Concern
 
         included do
+          # @return [Hash] Raw input data including HTTP response
+          # @api private
           attr_reader :input
 
+          #
+          # Initializes the model with input data.
+          #
+          # @param obj [Hash] Input data including 'http_response' key
+          #
+          # @api private
+          #
           def initialize(obj)
             @input = obj
             super
           end
 
+          #
+          # Returns the HTTP response wrapper with rate limit information.
+          #
+          # @return [Strava::Web::ApiResponse] API response wrapper
+          #
           def http_response
             @http_response ||= Strava::Web::ApiResponse.new(input['http_response'])
           end

data/lib/strava/models/mixins/moving_time.rb

@@ -3,14 +3,32 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides moving time formatting methods.
+      #
+      # Moving time is the time spent actually moving during an activity, excluding
+      # stopped time. This mixin adds the moving_time property and a helper method
+      # to format it as hours/minutes/seconds.
+      #
+      # @example Using moving time helpers
+      #   activity = client.activity(1234567890)
+      #   puts activity.moving_time              # => 3665 (seconds)
+      #   puts activity.moving_time_in_hours_s   # => "1h1m5s"
+      #
       module MovingTime
         extend ActiveSupport::Concern
         include TimeInHours
 
         included do
+          # @return [Integer] Moving time in seconds (excludes stopped time)
           property 'moving_time'
         end
 
+        #
+        # Returns formatted moving time as hours, minutes, and seconds.
+        #
+        # @return [String, nil] Formatted time string (e.g., "1h23m45s", "45m30s", "30s")
+        #
         def moving_time_in_hours_s
           time_in_hours_s moving_time
         end

data/lib/strava/models/mixins/sport_type.rb

@@ -3,14 +3,39 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides sport type handling and sport-specific formatting.
+      #
+      # This mixin adds the sport_type property and provides sport-aware formatting
+      # for distance and pace. For example, swimming activities display distance in
+      # meters and pace per 100m, while other activities use kilometers and pace per km.
+      #
+      # Also provides emoji representations for various sport types.
+      #
+      # @example Using sport type helpers
+      #   activity = client.activity(1234567890)
+      #   puts activity.sport_type           # => "Run"
+      #   puts activity.distance_s            # => "10.0km" (or "500m" for swim)
+      #   puts activity.pace_s                # => "4m30s/km" (or "1m20s/100m" for swim)
+      #   puts activity.sport_type_emoji      # => "🏃"
+      #
       module SportType
         extend ActiveSupport::Concern
 
         included do
-          # deprecated, property 'type'
+          # @return [String] Activity sport type (e.g., "Run", "Ride", "Swim", "Hike")
+          # @note This replaces the deprecated 'type' property
           property 'sport_type'
         end
 
+        #
+        # Returns distance formatted appropriately for the sport type.
+        #
+        # Swimming activities display distance in meters, while all other
+        # activities use kilometers.
+        #
+        # @return [String, nil] Formatted distance
+        #
         def distance_s
           if sport_type == 'Swim'
             distance_in_meters_s
@@ -19,6 +44,14 @@ module Strava
           end
         end
 
+        #
+        # Returns pace formatted appropriately for the sport type.
+        #
+        # Swimming activities display pace per 100 meters, while all other
+        # activities use pace per kilometer.
+        #
+        # @return [String, nil] Formatted pace
+        #
         def pace_s
           case sport_type
           when 'Swim'
@@ -28,6 +61,11 @@ module Strava
           end
         end
 
+        #
+        # Returns an emoji representing the sport type.
+        #
+        # @return [String, nil] Emoji character or nil if no emoji for this sport
+        #
         def sport_type_emoji
           case sport_type
           when 'AlpineSki' then '⛷️'

data/lib/strava/models/mixins/start_date_local.rb

@@ -3,16 +3,40 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides local start date/time with timezone handling.
+      #
+      # This mixin adds the start_date_local property and handles proper timezone
+      # conversion. The offset is calculated from the difference between start_date
+      # (UTC) and start_date_local, which correctly accounts for daylight saving
+      # time (unlike Strava's 'timezone' property, which only reflects the zone's
+      # standard GMT offset).
+      #
+      # This is particularly important for activities that cross timezone boundaries
+      # or for displaying times in the athlete's local timezone.
+      #
+      # @example Using local start date
+      #   activity = client.activity(1234567890)
+      #   puts activity.start_date        # => 2024-01-15 14:30:00 UTC
+      #   puts activity.start_date_local  # => 2024-01-15 09:30:00 -0500
+      #
       module StartDateLocal
         extend ActiveSupport::Concern
 
         included do
           property 'start_date_local', transform_with: ->(v) { ::Time.parse(v) }
 
+          #
+          # Returns the start date/time in the local timezone.
+          #
+          # Constructs a Time object with the offset calculated from the difference
+          # between start_date and start_date_local.
+          #
+          # @return [Time] Start date/time with local timezone
+          #
           def start_date_local
             extracted_datetime = self['start_date_local']
-            # some strava object do not contain a timezone property i.e. `Lap`
-            timezone_shift = conditional_timezone(extracted_datetime)
+            timezone_shift = calculate_timezone(extracted_datetime)
             ::Time.new(extracted_datetime.year,
                        extracted_datetime.month,
                        extracted_datetime.day,
@@ -24,37 +48,29 @@ module Strava
 
           private
 
-          def conditional_timezone(extracted_datetime)
-            if key?(:timezone)
-              if timezone.include?('+')
-                timezone_shift_string('+')
-              elsif timezone.include?('-')
-                timezone_shift_string('-')
-              else
-                raise ArgumentError 'No operator of timezone correction detectable!'
-              end
-            else
-              calculate_timezone(extracted_datetime)
-            end
-          end
-
+          #
+          # Determines the timezone offset for the start date.
+          #
+          # Calculates the offset from the difference between start_date (UTC)
+          # and start_date_local. This is used instead of Strava's 'timezone'
+          # property, which reflects the zone's standard GMT offset and does
+          # not account for daylight saving time.
+          #
+          # @param extracted_datetime [Time] The parsed start_date_local value
+          # @return [String] Timezone offset string (e.g., "-05:00")
+          #
+          # @api private
+          #
           def calculate_timezone(extracted_datetime)
             if start_date == extracted_datetime
               timezone_diff_shift_string(0, '-')
             elsif extracted_datetime < start_date
               timezone_diff_shift_string((extracted_datetime - start_date), '-')
-            elsif extracted_datetime > start_date
-              timezone_diff_shift_string((extracted_datetime - start_date), '+')
             else
-              raise ArgumentError 'No operator of timezone correction detectable!'
+              timezone_diff_shift_string((extracted_datetime - start_date), '+')
             end
           end
 
-          def timezone_shift_string(operator)
-            diff_hours = timezone.split(operator).last.to_i
-            "#{operator}#{format_int_leading_zero(diff_hours)}:00"
-          end
-
           def timezone_diff_shift_string(time_diff, operator)
             diff_hours = (time_diff.abs / 3600).to_i
             "#{operator}#{format_int_leading_zero(diff_hours)}:00"

data/lib/strava/models/mixins/time_in_hours.rb

@@ -3,11 +3,34 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides time formatting helper methods.
+      #
+      # This is a utility mixin used by other time-related mixins (MovingTime, ElapsedTime, etc.)
+      # to format seconds into a human-readable hours/minutes/seconds string.
+      #
+      # @example Time formatting
+      #   time_in_hours_s(3665)   # => "1h1m5s"
+      #   time_in_hours_s(125)    # => "2m5s"
+      #   time_in_hours_s(45)     # => "45s"
+      #   time_in_hours_s(7200)   # => "2h"
+      #
       module TimeInHours
         extend ActiveSupport::Concern
 
         private
 
+        #
+        # Converts time in seconds to formatted string with hours, minutes, and seconds.
+        #
+        # Only includes non-zero components. For example, if there are no hours,
+        # the result will be "23m45s" instead of "0h23m45s".
+        #
+        # @param time [Integer, nil] Time in seconds
+        # @return [String, nil] Formatted time string or nil if time is nil
+        #
+        # @api private
+        #
         def time_in_hours_s(time)
           return unless time
 

data/lib/strava/models/mixins/total_elevation_gain.rb

@@ -3,33 +3,75 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides total elevation gain conversion and formatting methods.
+      #
+      # Total elevation gain represents the cumulative upward elevation change
+      # during an activity. This is distinct from elevation_gain - this property
+      # is typically used for activities while elevation_gain is used for routes.
+      #
+      # This mixin adds the total_elevation_gain property and helper methods to
+      # convert and format it in meters or feet.
+      #
+      # @example Using total elevation gain helpers
+      #   activity = client.activity(1234567890)
+      #   puts activity.total_elevation_gain              # => 725.3 (meters)
+      #   puts activity.total_elevation_gain_s            # => "725.3m"
+      #   puts activity.total_elevation_gain_in_feet_s    # => "2379.6ft"
+      #
       module TotalElevationGain
         extend ActiveSupport::Concern
 
         included do
+          # @return [Float] Total elevation gain in meters
           property 'total_elevation_gain'
         end
 
+        #
+        # Returns total elevation gain in feet.
+        #
+        # @return [Float] Total elevation gain in feet
+        #
         def total_elevation_gain_in_feet
           total_elevation_gain * 3.28084
         end
 
+        #
+        # Returns total elevation gain in meters (same as total_elevation_gain).
+        #
+        # @return [Float] Total elevation gain in meters
+        #
         def total_elevation_gain_in_meters
           total_elevation_gain
         end
 
+        #
+        # Returns formatted total elevation gain in meters.
+        #
+        # @return [String, nil] Formatted elevation (e.g., "725.3m")
+        #
         def total_elevation_gain_in_meters_s
           return if total_elevation_gain.nil?
 
           format('%gm', format('%.1f', total_elevation_gain_in_meters))
         end
 
+        #
+        # Returns formatted total elevation gain in feet.
+        #
+        # @return [String, nil] Formatted elevation (e.g., "2379.6ft")
+        #
         def total_elevation_gain_in_feet_s
           return if total_elevation_gain.nil?
 
           format('%gft', format('%.1f', total_elevation_gain_in_feet))
         end
 
+        #
+        # Returns default formatted total elevation gain (meters).
+        #
+        # @return [String, nil] Formatted elevation (e.g., "725.3m")
+        #
         def total_elevation_gain_s
           total_elevation_gain_in_meters_s
         end

data/lib/strava/models/model.rb

@@ -1,6 +1,20 @@
 # frozen_string_literal: true
 
 module Strava
+  #
+  # Base model class for all Strava models.
+  #
+  # This class extends Hashie::Trash to provide a flexible data structure
+  # for Strava API responses. All model classes in the library inherit from this.
+  #
+  # Features:
+  # * Ignores undeclared properties from API responses
+  # * Provides hash-like access to properties
+  # * Supports property transformations
+  #
+  # @see Strava::Models::Response
+  # @see https://github.com/hashie/hashie
+  #
   class Model < Hashie::Trash
     include Hashie::Extensions::IgnoreUndeclared
   end

data/lib/strava/models/photos_summary.rb

@@ -2,10 +2,34 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-PhotosSummary
+    #
+    # Represents summary photo information for an activity.
+    #
+    # Contains basic information about photos attached to an activity,
+    # including the count and primary photo reference.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-PhotosSummary Strava API PhotosSummary reference
+    # @see Strava::Models::PhotosSummaryPrimary
+    # @see Strava::Models::SummaryActivity
+    #
+    # @example Accessing activity photo summary
+    #   activity = client.activity(1234567890)
+    #   if activity.photos && activity.photos.count > 0
+    #     puts "This activity has #{activity.photos.count} photo(s)"
+    #     if activity.photos.primary
+    #       puts "Primary photo: #{activity.photos.primary.urls}"
+    #     end
+    #   end
+    #
     class PhotosSummary < Strava::Models::Response
+      # @return [Integer] Total number of photos attached to the activity
       property 'count'
-      property 'use_primary_photo' # undocumented
+
+      # @return [Boolean, nil] Whether to use the primary photo for display
+      # @note Not documented by Strava API
+      property 'use_primary_photo'
+
+      # @return [PhotosSummaryPrimary, nil] The primary/featured photo reference
       property 'primary', transform_with: ->(v) { Strava::Models::PhotosSummaryPrimary.new(v) }
     end
   end

data/lib/strava/models/photos_summary_primary.rb

@@ -2,13 +2,39 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-PhotosSummary_primary
+    #
+    # Represents the primary photo reference in a photos summary.
+    #
+    # Contains identification and URL information for the primary photo
+    # of an activity.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-PhotosSummary_primary Strava API PhotosSummary_primary reference
+    # @see Strava::Models::PhotosSummary
+    #
+    # @example Accessing primary photo URLs
+    #   activity = client.activity(1234567890)
+    #   if activity.photos&.primary
+    #     photo = activity.photos.primary
+    #     puts "Photo ID: #{photo.id}"
+    #     puts "Source: #{photo.source}"
+    #     puts "URLs: #{photo.urls}"
+    #   end
+    #
     class PhotosSummaryPrimary < Strava::Models::Response
+      # @return [Integer, nil] Unique identifier for the photo
       property 'id'
+
+      # @return [Integer] Source of the photo (1=native Strava upload, 2=Instagram)
       property 'source'
+
+      # @return [String] Unique identifier string for the photo
       property 'unique_id'
+
+      # @return [Hash] Hash containing URLs to different sizes of the photo
       property 'urls'
-      # undocumented
+
+      # @return [Integer, nil] Type of media (1=photo, 2=video)
+      # @note Not documented by Strava API
       property 'media_type'
     end
   end

data/lib/strava/models/power_zone_ranges.rb

@@ -2,8 +2,30 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-PowerZoneRanges
+    #
+    # Represents an athlete's power zone configuration.
+    #
+    # Power zones define intensity levels based on watts output. These are
+    # typically used for cycling training and are often based on FTP
+    # (Functional Threshold Power).
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-PowerZoneRanges Strava API PowerZoneRanges reference
+    # @see Strava::Models::ZoneRange
+    # @see Strava::Models::Zones
+    #
+    # @example Accessing power zones
+    #   zones = client.athlete_zones
+    #
+    #   if zones.power
+    #     zones.power.zones.each_with_index do |zone, i|
+    #       puts "Power Zone #{i + 1}: #{zone.min}-#{zone.max}W"
+    #     end
+    #   else
+    #     puts "No power zones configured"
+    #   end
+    #
     class PowerZoneRanges < Strava::Models::Response
+      # @return [Array<ZoneRange>] Array of power zone ranges in watts
       property 'zones', transform_with: ->(v) { v.map { |r| Strava::Models::ZoneRange.new(r) } }
     end
   end

data/lib/strava/models/response.rb

@@ -2,6 +2,24 @@
 
 module Strava
   module Models
+    #
+    # Base response model for all API responses.
+    #
+    # This class serves as the parent for all model classes that represent API responses.
+    # It includes the HttpResponse mixin which provides access to HTTP response data
+    # including rate limit information.
+    #
+    # Most API models inherit from this class to gain access to the http_response method,
+    # which can be used to inspect rate limits and other response metadata.
+    #
+    # @example Accessing rate limit information
+    #   activity = client.activity(1234567890)
+    #   ratelimit = activity.http_response.ratelimit
+    #   puts "Remaining requests: #{ratelimit.fifteen_minutes_remaining}"
+    #
+    # @see Mixins::HttpResponse
+    # @see Strava::Api::Ratelimit
+    #
     class Response < Model
       include Mixins::HttpResponse
     end

data/lib/strava/models/route.rb

@@ -2,28 +2,89 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-Route
+    #
+    # Represents a Strava route.
+    #
+    # Routes are planned courses that athletes can follow for activities.
+    # They include map data, waypoints, and estimated moving time. Routes can
+    # be exported as GPX or TCX files for use with GPS devices.
+    #
+    # Includes helper mixins for formatting distance, elevation gain, and time.
+    #
+    # @example Get and display route information
+    #   route = client.route(1234567)
+    #   puts route.name
+    #   puts route.description
+    #   puts "Distance: #{route.distance_s}"
+    #   puts "Elevation gain: #{route.elevation_gain_s}"
+    #   puts "Estimated time: #{route.estimated_moving_time_in_hours_s}"
+    #
+    # @example Export route as GPX
+    #   gpx_data = client.export_route_gpx(route.id)
+    #   File.write('route.gpx', gpx_data)
+    #
+    # @see Strava::Api::Client#route
+    # @see Strava::Api::Client#export_route_gpx
+    # @see Strava::Api::Client#export_route_tcx
+    # @see https://developers.strava.com/docs/reference/#api-models-Route
+    #
     class Route < Strava::Models::Response
+      # @return [SummaryAthlete] The athlete who created this route
       property 'athlete', transform_with: ->(v) { Strava::Models::SummaryAthlete.new(v) }
+
+      # @return [String, nil] Route description
       property 'description'
+
       include Mixins::Distance
       include Mixins::ElevationGain
+
+      # @return [Integer] Route ID
       property 'id'
+
+      # @return [String] Route ID as a string
       property 'id_str'
+
+      # @return [Map] Route map with polyline data
       property 'map', transform_with: ->(v) { Strava::Models::Map.new(v) }
+
+      # @return [String] Route name
       property 'name'
+
+      # @return [Boolean] Whether this route is private
       property 'private'
+
+      # @return [Boolean] Whether this route has been starred by the authenticated athlete
       property 'starred'
+
+      # @return [Time] Timestamp for the route
       property 'timestamp', transform_with: ->(v) { Time.at(v) }
+
+      # @return [Integer] Route type (1 = Ride, 2 = Run)
       property 'type'
+
+      # @return [Integer] Route sub-type for additional categorization
       property 'sub_type'
+
+      # @return [Time] When the route was created
       property 'created_at', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Time] When the route was last updated
       property 'updated_at', transform_with: ->(v) { Time.parse(v) }
+
       include Mixins::EstimatedMovingTime
+
+      # @return [Array<SummarySegment>] Segments along this route
       property 'segments', transform_with: ->(v) { v.map { |r| Strava::Models::SummarySegment.new(r) } }
+
+      # @return [Array<Waypoint>] Waypoints along this route
       property 'waypoints', transform_with: ->(v) { v.map { |r| Strava::Models::Waypoint.new(r) } }
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [Hash, nil] URLs to map images at various sizes
       property 'map_urls'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Resource state indicator
       property 'resource_state'
     end
   end