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

data/lib/strava/models/similar_activities.rb

@@ -2,19 +2,75 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents statistics about similar activities.
+    #
+    # Provides comparative data about activities of the same type and route,
+    # including speed trends and performance metrics. 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::Trend
+    # @see Strava::Models::DetailedActivity
+    #
+    # @example Accessing similar activity statistics
+    #   activity = client.activity(1234567890)
+    #   if activity.similar_activities
+    #     similar = activity.similar_activities
+    #     puts "Average speed: #{similar.average_speed} m/s"
+    #     puts "Similar efforts: #{similar.effort_count}"
+    #     puts "PR rank: #{similar.pr_rank}"
+    #   end
+    #
     class SimilarActivities < Strava::Models::Response
+      # @return [Float, nil] Average speed across similar activities in meters per second
+      # @note Not documented by Strava API
       property 'average_speed'
+
+      # @return [Integer, nil] Resource state indicator
+      # @note Not documented by Strava API
       property 'resource_state'
+
+      # @return [Integer, nil] Number of similar efforts/activities
+      # @note Not documented by Strava API
       property 'effort_count'
+
+      # @return [Integer, nil] Milestone frequency indicator
+      # @note Not documented by Strava API
       property 'frequency_milestone'
+
+      # @return [Float, nil] Maximum average speed across similar activities in meters per second
+      # @note Not documented by Strava API
       property 'max_average_speed'
+
+      # @return [Float, nil] Median average speed across similar activities in meters per second
+      # @note Not documented by Strava API
       property 'mid_average_speed'
+
+      # @return [Float, nil] Minimum average speed across similar activities in meters per second
+      # @note Not documented by Strava API
       property 'min_average_speed'
+
+      # @return [Float, nil] Median speed value
+      # @note Not documented by Strava API
       property 'mid_speed'
+
+      # @return [Float, nil] Minimum speed value
+      # @note Not documented by Strava API
       property 'min_speed'
+
+      # @return [Array, nil] Array of speed values
+      # @note Not documented by Strava API
       property 'speeds'
+
+      # @return [Trend, nil] Trend data for similar activities
+      # @note Not documented by Strava API
       property 'trend', transform_with: ->(v) { Strava::Models::Trend.new(v) }
+
+      # @return [Integer, nil] Personal record rank among similar activities
+      # @note Not documented by Strava API
       property 'pr_rank'
     end
   end

data/lib/strava/models/split.rb

@@ -2,17 +2,42 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-Split
+    #
+    # Represents a split/interval within an activity.
+    #
+    # Splits divide an activity into equal distance segments (e.g., per mile or per kilometer)
+    # with metrics for each segment. Activities typically include both metric (km) and
+    # standard (mile) splits.
+    #
+    # Includes helper mixins for formatting distance, time, speed, and elevation.
+    #
+    # @example Access activity splits
+    #   activity = client.activity(1234567890)
+    #   activity.splits_metric.each_with_index do |split, i|
+    #     puts "KM #{i+1}: #{split.moving_time_in_hours_s} at #{split.pace_s}"
+    #     puts "Elevation: #{split.elevation_difference}m"
+    #   end
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-Split
+    #
     class Split < Strava::Models::Response
       include Mixins::AverageSpeed
       include Mixins::Distance
       include Mixins::ElapsedTime
       include Mixins::ElevationDifference
+
+      # @return [Integer] Pace zone for this split (0-5)
       property 'pace_zone'
+
       include Mixins::MovingTime
+
+      # @return [Integer] Split number (1-indexed)
       property 'split'
-      # undocumented
+
+      # @return [Float] Average speed adjusted for grade/incline (in meters per second)
       property 'average_grade_adjusted_speed'
+
+      # @return [Float] Average heart rate during this split (beats per minute)
       property 'average_heartrate'
     end
   end

data/lib/strava/models/stats_visibility.rb

@@ -2,9 +2,32 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents visibility settings for activity statistics.
+    #
+    # Controls which statistics are visible to others when viewing an activity.
+    # 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
+    #
+    # @example Accessing stats visibility
+    #   activity = client.activity(1234567890)
+    #   if activity.stats_visibility
+    #     activity.stats_visibility.each do |visibility|
+    #       puts "#{visibility.type}: #{visibility.visibility}"
+    #     end
+    #   end
+    #
     class StatsVisibility < Strava::Models::Response
+      # @return [String, nil] Type of statistic (e.g., "heartrate", "power")
+      # @note Not documented by Strava API
       property 'type'
+
+      # @return [String, nil] Visibility setting (e.g., "everyone", "followers_only", "only_me")
+      # @note Not documented by Strava API
       property 'visibility'
     end
   end

data/lib/strava/models/stream.rb

@@ -2,11 +2,118 @@
 
 module Strava
   module Models
+    #
+    # Represents a single stream of time-series data from the Strava API.
+    #
+    # A Stream contains both metadata about the data collection and the actual data array.
+    # Common stream types include: time, distance, latlng, altitude, velocity_smooth,
+    # heartrate, cadence, watts, temp, moving, and grade_smooth.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-Streams Strava API Streams reference
+    # @see Strava::Models::BaseStream
+    # @see Strava::Models::StreamSet
+    #
+    # @example Accessing heartrate stream data
+    #   streams = client.activity_streams(1234567890, keys: 'heartrate,watts')
+    #   hr_data = streams.heartrate.data
+    #   puts "Average HR: #{hr_data.sum / hr_data.size}"
+    #   puts "Max HR: #{hr_data.max}"
+    #
+    # @example Working with GPS coordinates
+    #   streams = client.activity_streams(1234567890, keys: 'latlng')
+    #   coords = streams.latlng.data  # Array of [lat, lng] pairs
+    #   coords.each do |lat, lng|
+    #     puts "#{lat}, #{lng}"
+    #   end
+    #
+    # @example Computing elevation gain and loss from an altitude stream
+    #   streams = client.activity_streams(1234567890, keys: 'altitude')
+    #   puts streams.altitude.total_elevation_gain_s  # => "725.3m"
+    #   puts streams.altitude.total_elevation_loss_s  # => "680.1m"
+    #
     class Stream < Strava::Models::Response
+      # @return [Integer] Total number of data points in the original stream before any resampling
       property 'original_size'
+
+      # @return [String] Resolution of the stream data ("low", "medium", or "high")
       property 'resolution'
+
+      # @return [String] Type of series - how data points are indexed ("time" or "distance")
       property 'series_type'
+
+      # @return [Array] Array of data points. The type of data depends on the stream:
+      #   - time: Array of integers (seconds from start)
+      #   - distance: Array of floats (meters from start)
+      #   - latlng: Array of [latitude, longitude] coordinate pairs
+      #   - altitude: Array of floats (meters)
+      #   - velocity_smooth: Array of floats (meters per second)
+      #   - heartrate: Array of integers (beats per minute)
+      #   - cadence: Array of integers (RPM for cycling, steps/min for running)
+      #   - watts: Array of integers (power in watts)
+      #   - temp: Array of integers (temperature in celsius)
+      #   - moving: Array of booleans (true if moving, false if stopped)
+      #   - grade_smooth: Array of floats (grade as percentage)
       property 'data'
+
+      #
+      # Returns the total elevation gain, calculated as the sum of all positive
+      # elevation increases between consecutive data points.
+      #
+      # This is only meaningful when the stream represents altitude data.
+      #
+      # @return [Float, nil] Total elevation gain in meters, or nil if data is not present
+      #
+      # @example
+      #   streams = client.activity_streams(1234567890, keys: 'altitude')
+      #   puts streams.altitude.total_elevation_gain # => 725.3
+      #
+      def total_elevation_gain
+        return if data.nil?
+
+        data.each_cons(2).sum { |a, b| b > a ? b - a : 0 }
+      end
+
+      #
+      # Returns the total elevation loss, calculated as the sum of all negative
+      # elevation decreases between consecutive data points.
+      #
+      # This is only meaningful when the stream represents altitude data.
+      #
+      # @return [Float, nil] Total elevation loss in meters, or nil if data is not present
+      #
+      # @example
+      #   streams = client.activity_streams(1234567890, keys: 'altitude')
+      #   puts streams.altitude.total_elevation_loss # => 680.1
+      #
+      def total_elevation_loss
+        return if data.nil?
+
+        data.each_cons(2).sum { |a, b| a > b ? a - b : 0 }
+      end
+
+      #
+      # Returns formatted total elevation gain in meters.
+      #
+      # @return [String, nil] Formatted elevation (e.g., "725.3m")
+      #
+      def total_elevation_gain_s
+        gain = total_elevation_gain
+        return if gain.nil?
+
+        format('%gm', format('%.1f', gain))
+      end
+
+      #
+      # Returns formatted total elevation loss in meters.
+      #
+      # @return [String, nil] Formatted elevation (e.g., "680.1m")
+      #
+      def total_elevation_loss_s
+        loss = total_elevation_loss
+        return if loss.nil?
+
+        format('%gm', format('%.1f', loss))
+      end
     end
   end
 end

data/lib/strava/models/stream_set.rb

@@ -2,18 +2,69 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-StreamSet
+    #
+    # Represents a collection of activity streams from the Strava API.
+    #
+    # A StreamSet is returned when requesting activity or segment effort streams
+    # and contains multiple synchronized time-series data streams. Each stream
+    # contains data points that correspond to the same moments in time or distance.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-StreamSet Strava API StreamSet reference
+    # @see Strava::Models::Stream
+    # @see Strava::Api::Client#activity_streams
+    # @see Strava::Api::Client#segment_effort_streams
+    #
+    # @example Fetching and analyzing multiple streams
+    #   streams = client.activity_streams(1234567890,
+    #     keys: 'time,distance,heartrate,watts',
+    #     key_by_type: true
+    #   )
+    #
+    #   # Access individual streams
+    #   time_data = streams.time.data           # Array of elapsed seconds
+    #   hr_data = streams.heartrate.data        # Array of heart rate values
+    #   power_data = streams.watts.data         # Array of power values
+    #
+    #   # Calculate average power for time above threshold HR
+    #   threshold_hr = 160
+    #   time_data.each_with_index do |time, i|
+    #     if hr_data[i] > threshold_hr
+    #       puts "At #{time}s: HR=#{hr_data[i]}, Power=#{power_data[i]}W"
+    #     end
+    #   end
+    #
     class StreamSet < Strava::Models::Response
+      # @return [Stream, nil] Time stream - elapsed seconds from activity start
       property 'time', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Distance stream - meters from activity start
       property 'distance', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] GPS coordinate stream - array of [latitude, longitude] pairs
       property 'latlng', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Altitude stream - elevation in meters
       property 'altitude', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Smoothed velocity stream - speed in meters per second
       property 'velocity_smooth', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Heart rate stream - beats per minute
       property 'heartrate', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Cadence stream - RPM for cycling, steps per minute for running
       property 'cadence', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Power stream - watts
       property 'watts', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Temperature stream - degrees celsius
       property 'temp', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Moving stream - boolean indicating whether athlete is moving
       property 'moving', transform_with: ->(v) { Strava::Models::Stream.new(v) }
+
+      # @return [Stream, nil] Smoothed grade stream - grade as percentage
       property 'grade_smooth', transform_with: ->(v) { Strava::Models::Stream.new(v) }
     end
   end

data/lib/strava/models/summary_activity.rb

@@ -2,67 +2,210 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummaryActivity
+    #
+    # Represents a summary view of a Strava activity.
+    #
+    # A summary activity contains the most important information about an activity
+    # without the detailed segments, splits, and other extended data found in
+    # {DetailedActivity}. This model is typically returned when listing activities
+    # or when full details are not needed.
+    #
+    # Includes helper mixins for formatting distance, time, elevation, speed, and sport type.
+    #
+    # @example List and display activities
+    #   activities = client.athlete_activities(per_page: 10)
+    #   activities.each do |activity|
+    #     puts "#{activity.name} - #{activity.distance_s} in #{activity.moving_time_in_hours_s}"
+    #     puts activity.strava_url
+    #   end
+    #
+    # @see DetailedActivity
+    # @see https://developers.strava.com/docs/reference/#api-models-SummaryActivity
+    #
     class SummaryActivity < Strava::Models::Response
+      # @return [Integer] Activity ID
       property 'id'
+
+      # @return [String, nil] External ID from the original upload source
       property 'external_id'
+
+      # @return [Integer, nil] Upload ID
       property 'upload_id'
+
+      # @return [MetaAthlete] The athlete who performed the activity
       property 'athlete', transform_with: ->(v) { Strava::Models::MetaAthlete.new(v) }
+
+      # @return [String] Activity name
       property 'name'
+
       include Mixins::Distance
       include Mixins::MovingTime
       include Mixins::ElapsedTime
       include Mixins::TotalElevationGain
+
+      # @return [Float, nil] Highest elevation in meters
       property 'elev_high'
+
+      # @return [Float, nil] Lowest elevation in meters
       property 'elev_low'
+
       include Mixins::SportType
+
+      # @return [Time] Start date and time (UTC)
       property 'start_date', transform_with: ->(v) { Time.parse(v) }
+
       include Mixins::StartDateLocal
+
+      # @return [String] Timezone in which the activity was recorded
       property 'timezone'
+
+      # @return [LatLng, nil] Starting coordinates [latitude, longitude]
       property 'start_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [LatLng, nil] Ending coordinates [latitude, longitude]
       property 'end_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [Integer] Number of achievements (segment PRs, CRs, etc.)
       property 'achievement_count'
+
+      # @return [Integer] Number of kudos received
       property 'kudos_count'
+
+      # @return [Integer] Number of comments
       property 'comment_count'
+
+      # @return [Integer] Number of athletes who participated (group activities)
       property 'athlete_count'
+
+      # @return [Integer] Number of photos attached
       property 'photo_count'
+
+      # @return [Integer] Total number of photos including Instagram
       property 'total_photo_count'
+
+      # @return [Map] Activity map with polyline data
       property 'map', transform_with: ->(v) { Strava::Models::Map.new(v) }
+
+      # @return [Boolean] Whether this activity was on a stationary trainer
       property 'trainer'
+
+      # @return [Boolean] Whether this activity was a commute
       property 'commute'
+
+      # @return [Boolean] Whether this activity was manually entered
       property 'manual'
+
+      # @return [Boolean] Whether this activity is set to private
       property 'private'
+
+      # @return [Boolean] Whether this activity has been flagged
       property 'flagged'
+
+      # @return [Integer, nil] Workout type (e.g., 10 = Race, 11 = Workout)
       property 'workout_type'
+
+      # @return [String, nil] Upload ID as a string
       property 'upload_id_str'
+
+      # @return [Float] Average speed in meters per second
       property 'average_speed'
+
+      # @return [Float] Maximum speed in meters per second
       property 'max_speed'
+
+      # @return [Boolean] Whether the authenticated athlete has kudoed this activity
       property 'has_kudoed'
+
+      # @return [Boolean] Whether to hide this activity from the home feed
       property 'hide_from_home'
+
+      # @return [String, nil] Gear (bike/shoes) ID used for this activity
       property 'gear_id'
+
+      # @return [Float, nil] Kilojoules of energy expended
       property 'kilojoules'
+
+      # @return [Float, nil] Average power in watts
       property 'average_watts'
+
+      # @return [Boolean, nil] Whether the watts are from a power meter (true) or estimated (false)
       property 'device_watts'
+
+      # @return [Integer, nil] Maximum power in watts
       property 'max_watts'
+
+      # @return [Integer, nil] Weighted average power in watts
       property 'weighted_average_watts'
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Resource state indicator
       property 'resource_state'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Activity visibility setting (e.g., 'everyone', 'followers_only')
       property 'visibility'
+
+      # @note Undocumented in official API
+      # @return [Float, nil] UTC offset in seconds
       property 'utc_offset'
+
+      # @note Undocumented in official API
+      # @return [String, nil] City where the activity took place
       property 'location_city'
+
+      # @note Undocumented in official API
+      # @return [String, nil] State/province where the activity took place
       property 'location_state'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Country where the activity took place
       property 'location_country'
+
+      # @note Undocumented in official API
+      # @return [Float, nil] Average cadence (RPM for cycling, steps/minute for running)
       property 'average_cadence'
+
+      # @note Undocumented in official API
+      # @return [Float, nil] Average temperature during the activity in Celsius
       property 'average_temp'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the activity has heart rate data
       property 'has_heartrate'
+
+      # @note Undocumented in official API
+      # @return [Float, nil] Average heart rate in beats per minute
       property 'average_heartrate'
+
+      # @note Undocumented in official API
+      # @return [Float, nil] Maximum heart rate in beats per minute
       property 'max_heartrate'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the athlete has opted out of heart rate display
       property 'heartrate_opt_out'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether to display the hide heart rate option
       property 'display_hide_heartrate_option'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the activity was created from an accepted tag
       property 'from_accepted_tag'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Number of personal records achieved in this activity
       property 'pr_count'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Relative effort score (suffer score)
       property 'suffer_score'
 
+      #
+      # Returns the Strava web URL for this activity.
+      #
+      # @return [String] Full URL to view the activity on Strava.com
+      #
       def strava_url
         "https://www.strava.com/activities/#{id}"
       end

data/lib/strava/models/summary_athlete.rb

@@ -2,27 +2,80 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummaryAthlete
+    #
+    # Represents summary information about a Strava athlete.
+    #
+    # Contains basic profile information about an athlete. This is typically returned
+    # when listing kudoers, commenters, or other athletes associated with activities,
+    # rather than the full {DetailedAthlete} information.
+    #
+    # @example Access athlete who kudoed an activity
+    #   kudoers = client.activity_kudos(1234567890)
+    #   kudoers.each do |athlete|
+    #     puts "#{athlete.name} from #{athlete.city}"
+    #     puts athlete.strava_url
+    #   end
+    #
+    # @see DetailedAthlete
+    # @see https://developers.strava.com/docs/reference/#api-models-SummaryAthlete
+    #
     class SummaryAthlete < Strava::Models::Response
+      # @return [Integer] Athlete ID
       property 'id'
+
+      # @return [Integer] Resource state indicator
       property 'resource_state'
+
+      # @return [String] First name
       property 'firstname'
+
+      # @return [String] Last name
       property 'lastname'
+
+      # @return [String, nil] URL to medium-sized profile picture
       property 'profile_medium'
+
+      # @return [String, nil] URL to full-sized profile picture
       property 'profile'
+
+      # @return [String, nil] City
       property 'city'
+
+      # @return [String, nil] State or province
       property 'state'
+
+      # @return [String, nil] Country
       property 'country'
+
+      # @return [String] Sex ('M' for male, 'F' for female)
       property 'sex'
+
+      # @return [Boolean] Whether the athlete has a premium subscription
       property 'premium'
+
+      # @return [Boolean] Whether the athlete has a Summit subscription
       property 'summit'
+
+      # @return [Time] When the athlete account was created
       property 'created_at', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Time] When the athlete account was last updated
       property 'updated_at', transform_with: ->(v) { Time.parse(v) }
 
+      #
+      # Returns the athlete's full name.
+      #
+      # @return [String, nil] Full name combining firstname and lastname, or nil if neither exists
+      #
       def name
         [firstname, lastname].compact.join(' ') if firstname || lastname
       end
 
+      #
+      # Returns the Strava web URL for this athlete's profile.
+      #
+      # @return [String] Full URL to view the athlete on Strava.com
+      #
       def strava_url
         "https://www.strava.com/athletes/#{id}"
       end