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

data/lib/strava/models/detailed_photo.rb

@@ -2,28 +2,88 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents a photo or video attached to an activity.
+    #
+    # Photos can be uploaded directly to Strava or linked from Instagram.
+    # This model contains URLs to various sizes of the media, timestamps,
+    # and metadata about the photo or video.
+    #
+    # Note: This is an undocumented Strava API endpoint.
+    #
+    # @example List activity photos
+    #   photos = client.activity_photos(1234567890)
+    #   photos.each do |photo|
+    #     puts photo.caption if photo.caption
+    #     puts "Uploaded: #{photo.uploaded_at}"
+    #     puts "URL: #{photo.urls['0']}" if photo.urls
+    #     puts "Video: #{photo.video_url}" if photo.video_url
+    #   end
+    #
+    # @see Strava::Api::Client#activity_photos
+    #
     class DetailedPhoto < Strava::Models::Response
+      # @return [String] Unique identifier for the photo/video
       property 'unique_id'
+
+      # @return [Integer] ID of the athlete who uploaded the photo
       property 'athlete_id'
+
+      # @return [Integer] ID of the activity this photo is attached to
       property 'activity_id'
+
+      # @return [String] Name of the activity
       property 'activity_name'
+
+      # @return [Integer, nil] Post identifier if photo is from a social post
       property 'post_id'
+
+      # @return [Integer] Resource state indicator
       property 'resource_state'
+
+      # @return [String, nil] Photo caption/description
       property 'caption'
+
+      # @return [Integer] Type of media (1=photo, 2=video)
       property 'type'
+
+      # @return [Integer] Source of the photo (1=native Strava upload, 2=Instagram)
       property 'source'
+
+      # @return [String] Processing status
       property 'status'
+
+      # @return [Time] When the photo was uploaded to Strava
       property 'uploaded_at', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Time] When the photo was created/taken
       property 'created_at', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Time] Local time when photo was created
       property 'created_at_local', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Hash] Map of size keys to photo URLs (e.g., {"0" => "https://...", "1000" => "https://..."})
       property 'urls'
+
+      # @return [String, nil] URL to placeholder/thumbnail image
       property 'placeholder_image'
+
+      # @return [Hash] Map of size keys to dimensions [width, height]
       property 'sizes'
+
+      # @return [Boolean] Whether this is the default/cover photo for the activity
       property 'default_photo'
+
+      # @return [String, nil] Pagination cursor for photo listing
       property 'cursor'
+
+      # @return [Float, nil] Duration in seconds (for videos)
       property 'duration'
+
+      # @return [String, nil] Direct URL to video file
       property 'video_url'
+
+      # @return [Array<Float>, nil] Geographic location [latitude, longitude] where photo was taken
       property 'location'
     end
   end

data/lib/strava/models/detailed_photos.rb

@@ -2,10 +2,38 @@
 
 module Strava
   module Models
-    # undocumented
+    #
+    # Represents detailed photo information for an activity.
+    #
+    # Contains the primary photo and total photo count for 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
+    # @see Strava::Models::DetailedPhoto
+    #
+    # @example Accessing activity photos
+    #   activity = client.activity(1234567890)
+    #   if activity.photos
+    #     puts "Total photos: #{activity.photos.count}"
+    #     if activity.photos.primary
+    #       puts "Primary photo ID: #{activity.photos.primary.id}"
+    #     end
+    #   end
+    #
     class DetailedPhotos < Strava::Models::Response
+      # @return [Photo, nil] The primary/featured photo for the activity
+      # @note Not documented by Strava API
       property 'primary', transform_with: ->(v) { Strava::Models::Photo.new(v) }
+
+      # @return [Boolean, nil] Whether to use the primary photo for display
+      # @note Not documented by Strava API
       property 'use_primary_photo'
+
+      # @return [Integer, nil] Total number of photos attached to the activity
+      # @note Not documented by Strava API
       property 'count'
     end
   end

data/lib/strava/models/detailed_segment.rb

@@ -2,39 +2,126 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-DetailedSegment
+    #
+    # Represents detailed information about a Strava segment.
+    #
+    # Segments are specific sections of road or trail where athletes can compete
+    # for best times. This model contains comprehensive segment information including
+    # location, elevation profile, statistics, and the athlete's personal records.
+    #
+    # Includes helper mixins for formatting distance and elevation.
+    #
+    # @example Get segment details
+    #   segment = client.segment(229781)
+    #   puts segment.name
+    #   puts "#{segment.distance_s} with #{segment.average_grade}% average grade"
+    #   puts "Location: #{segment.city}, #{segment.state}"
+    #   puts "#{segment.athlete_count} athletes have ridden this segment"
+    #
+    #   if segment.athlete_segment_stats
+    #     pr = segment.athlete_segment_stats
+    #     puts "Your PR: #{pr.elapsed_time_in_hours_s}"
+    #   end
+    #
+    # @see SummarySegment
+    # @see https://developers.strava.com/docs/reference/#api-models-DetailedSegment
+    #
     class DetailedSegment < Strava::Models::Response
+      # @return [Integer] Segment ID
       property 'id'
+
+      # @return [String] Segment name
       property 'name'
+
+      # @return [String] Activity type ('Ride' or 'Run')
       property 'activity_type'
+
       include Mixins::Distance
+
+      # @return [Float] Average grade as a percentage
       property 'average_grade'
+
+      # @return [Float] Maximum grade as a percentage
       property 'maximum_grade'
+
+      # @return [Float] Highest elevation point in meters
       property 'elevation_high'
+
+      # @return [Float] Lowest elevation point in meters
       property 'elevation_low'
+
+      # @return [LatLng] Starting coordinates [latitude, longitude]
       property 'start_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [LatLng] Ending coordinates [latitude, longitude]
       property 'end_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [Integer] Climb category (0 = uncategorized, 1-5 = category climbs, HC = hors catégorie)
       property 'climb_category'
+
+      # @return [String, nil] City where the segment is located
       property 'city'
+
+      # @return [String, nil] State/province where the segment is located
       property 'state'
+
+      # @return [String, nil] Country where the segment is located
       property 'country'
+
+      # @return [Boolean] Whether this segment is private
       property 'private'
+
+      # @return [SummaryPRSegmentEffort, nil] The authenticated athlete's PR on this segment
       property 'athlete_pr_effort', transform_with: ->(v) { Strava::Models::SummaryPRSegmentEffort.new(v) }
+
+      # @return [SummarySegmentEffort, nil] The authenticated athlete's statistics on this segment
       property 'athlete_segment_stats', transform_with: ->(v) { Strava::Models::SummarySegmentEffort.new(v) }
+
+      # @return [Time] When the segment was created
       property 'created_at', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Time] When the segment was last updated
       property 'updated_at', transform_with: ->(v) { Time.parse(v) }
+
       include Mixins::TotalElevationGain
+
+      # @return [Map] Segment map with polyline data
       property 'map', transform_with: ->(v) { Strava::Models::Map.new(v) }
+
+      # @return [Integer] Total number of efforts on this segment
       property 'effort_count'
+
+      # @return [Integer] Total number of unique athletes who have attempted this segment
       property 'athlete_count'
+
+      # @return [Boolean] Whether this segment has been flagged as hazardous
       property 'hazardous'
+
+      # @return [Integer] Number of athletes who have starred this segment
       property 'star_count'
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Resource state indicator
       property 'resource_state'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Elevation profile data (deprecated, use elevation_profiles)
       property 'elevation_profile'
+
+      # @note Undocumented in official API
+      # @return [Array, nil] Collection of elevation profile data points
       property 'elevation_profiles'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the authenticated athlete has starred this segment
       property 'starred'
+
+      # @note Undocumented in official API
+      # @return [Xoms, nil] QOM/KOM information for this segment
       property 'xoms', transform_with: ->(v) { Strava::Models::Xoms.new(v) }
+
+      # @note Undocumented in official API
+      # @return [LocalLegend, nil] Current Local Legend holder for this segment
       property 'local_legend', transform_with: ->(v) { Strava::Models::LocalLegend.new(v) }
     end
   end

data/lib/strava/models/detailed_segment_effort.rb

@@ -2,35 +2,124 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-DetailedSegmentEffort
+    #
+    # Represents detailed information about a segment effort within an activity.
+    #
+    # A segment effort is an attempt at a defined segment (a portion of road or trail).
+    # The detailed version includes comprehensive statistics, rankings, achievements,
+    # and sensor data for the effort.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-DetailedSegmentEffort Strava API DetailedSegmentEffort reference
+    # @see Strava::Models::SummarySegmentEffort
+    # @see Strava::Models::SummarySegment
+    # @see Strava::Models::Achievement
+    #
+    # @example Accessing detailed segment effort
+    #   effort = client.segment_effort(1234567890)
+    #
+    #   puts "Segment: #{effort.name}"
+    #   puts "Time: #{effort.elapsed_time_in_hours_s}"
+    #   puts "Moving time: #{effort.moving_time_in_hours_s}"
+    #   puts "Distance: #{effort.distance_s}"
+    #
+    #   if effort.average_watts
+    #     puts "Avg Power: #{effort.average_watts}W"
+    #   end
+    #
+    #   if effort.average_heartrate
+    #     puts "Avg HR: #{effort.average_heartrate} bpm (max: #{effort.max_heartrate})"
+    #   end
+    #
+    #   # Check rankings
+    #   puts "KOM Rank: #{effort.kom_rank}" if effort.kom_rank
+    #   puts "PR Rank: #{effort.pr_rank}" if effort.pr_rank
+    #
+    #   # View achievements
+    #   effort.achievements.each do |achievement|
+    #     puts "Achievement: #{achievement.type} - Rank #{achievement.rank}"
+    #   end
+    #
     class DetailedSegmentEffort < Strava::Models::Response
+      # @return [Integer] Unique identifier for this segment effort
       property 'id'
+
+      # @return [Integer] ID of the activity containing this segment effort
       property 'activity_id'
+
+      # Includes elapsed_time (total time including stops) and helper methods
       include Mixins::ElapsedTime
+
+      # @return [Time] Start time of the segment effort in UTC
       property 'start_date', transform_with: ->(v) { Time.parse(v) }
+
+      # Includes start_date_local with timezone handling
       include Mixins::StartDateLocal
+
+      # Includes distance in meters and conversion helper methods
       include Mixins::Distance
+
+      # @return [Boolean] Whether this effort achieved KOM (King/Queen of the Mountain)
       property 'is_kom'
+
+      # @return [String] Name of the segment
       property 'name'
-      # documented as MetaActivity and MetaAthlete
+
+      # @return [MetaActivity] Reference to the parent activity
       property 'activity', transform_with: ->(v) { Strava::Models::MetaActivity.new(v) }
+
+      # @return [MetaAthlete] Reference to the athlete who performed this effort
       property 'athlete', transform_with: ->(v) { Strava::Models::MetaAthlete.new(v) }
+
+      # Includes moving_time (time excluding stops) and helper methods
       include Mixins::MovingTime
+
+      # @return [Integer] Index in the activity stream where this effort starts
       property 'start_index'
+
+      # @return [Integer] Index in the activity stream where this effort ends
       property 'end_index'
+
+      # @return [Float, nil] Average cadence during the effort (RPM for cycling, steps/min for running)
       property 'average_cadence'
+
+      # @return [Float, nil] Average power output during the effort in watts
       property 'average_watts'
+
+      # @return [Boolean, nil] Whether power data comes from a power meter device
       property 'device_watts'
+
+      # @return [Float, nil] Average heart rate during the effort in beats per minute
       property 'average_heartrate'
+
+      # @return [Integer, nil] Maximum heart rate during the effort in beats per minute
       property 'max_heartrate'
+
+      # @return [SummarySegment] The segment that was attempted
       property 'segment', transform_with: ->(v) { Strava::Models::SummarySegment.new(v) }
+
+      # @return [Integer, nil] Overall rank on this segment (null if not in top 10)
       property 'kom_rank'
+
+      # @return [Integer, nil] Personal record rank for this segment (1 for PR, 2 for 2nd best, etc.)
       property 'pr_rank'
+
+      # @return [Boolean] Whether this effort is hidden from public segment leaderboards
       property 'hidden'
-      # undocumented
+
+      # @return [Integer] Resource state indicator
+      # @note Not documented by Strava API
       property 'resource_state'
+
+      # @return [Array<Achievement>] Achievements earned during this effort (PR, yearly records, etc.)
+      # @note Not documented by Strava API
       property 'achievements', transform_with: ->(v) { v.map { |r| Strava::Models::Achievement.new(r) } }
+
+      # @return [String, nil] Visibility setting for this effort
+      # @note Not documented by Strava API
       property 'visibility'
+
+      # @return [SummaryPRSegmentEffort, nil] Athlete's personal statistics for this segment
+      # @note Not documented by Strava API
       property 'athlete_segment_stats', transform_with: ->(v) { Strava::Models::SummaryPRSegmentEffort.new(v) }
     end
   end

data/lib/strava/models/explorer_segment.rb

@@ -2,22 +2,75 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-ExplorerSegment
+    #
+    # Represents a segment found via segment exploration.
+    #
+    # Used when searching for segments in a geographic area. Contains basic segment
+    # information including location, elevation, and difficulty category.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-ExplorerSegment Strava API ExplorerSegment reference
+    # @see Strava::Api::Client#explore_segments
+    # @see Strava::Models::SummarySegment
+    #
+    # @example Exploring segments near a location
+    #   segments = client.explore_segments(
+    #     bounds: [37.7, -122.5, 37.8, -122.4],  # [sw_lat, sw_lng, ne_lat, ne_lng]
+    #     activity_type: 'running'
+    #   )
+    #
+    #   segments.each do |segment|
+    #     puts "#{segment.name} (#{segment.distance_s})"
+    #     puts "  Climb: #{segment.climb_category_desc}"
+    #     puts "  Grade: #{segment.avg_grade}%"
+    #     puts "  Elevation: #{segment.elev_difference}m"
+    #     puts "  Starred: #{segment.starred}"
+    #   end
+    #
     class ExplorerSegment < Strava::Models::Response
+      # @return [Integer] Unique identifier for this segment
       property 'id'
+
+      # @return [String] Name of the segment
       property 'name'
+
+      # @return [Integer] Climb category (0=uncategorized, 5=easiest, 1=hardest, HC=hors catégorie)
       property 'climb_category'
+
+      # @return [String] Human-readable description of climb category (e.g., "NC", "4", "3", "2", "1", "HC")
       property 'climb_category_desc'
+
+      # @return [Float] Average grade/incline as a percentage
       property 'avg_grade'
+
+      # @return [LatLng] GPS coordinates of segment start point
       property 'start_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [LatLng] GPS coordinates of segment end point
       property 'end_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [Float] Net elevation difference in meters (positive for climbs, negative for descents)
       property 'elev_difference'
+
+      # Includes distance in meters and conversion helper methods
       include Mixins::Distance
+
+      # @return [String, nil] Encoded polyline of the segment path
       property 'points'
-      # undocumented
+
+      # @return [Integer] Resource state indicator
+      # @note Not documented by Strava API
       property 'resource_state'
+
+      # @return [Boolean, nil] Whether the current athlete has starred this segment
+      # @note Not documented by Strava API
       property 'starred'
+
+      # @return [String, nil] URL or path to elevation profile visualization
+      # @note Not documented by Strava API
       property 'elevation_profile'
+
+      # @return [Boolean, nil] Whether local legend feature is enabled for this segment
+      # @note Not documented by Strava API
       property 'local_legend_enabled'
     end
   end

data/lib/strava/models/heart_rate_zone_ranges.rb

@@ -2,9 +2,37 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-HeartRateZoneRanges
+    #
+    # Represents an athlete's heart rate zone configuration.
+    #
+    # Heart rate zones define intensity levels based on beats per minute.
+    # Athletes can use default zones or configure custom zones based on
+    # their fitness level and training goals.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-HeartRateZoneRanges Strava API HeartRateZoneRanges reference
+    # @see Strava::Models::ZoneRange
+    # @see Strava::Models::Zones
+    #
+    # @example Accessing heart rate zones
+    #   zones = client.athlete_zones
+    #
+    #   if zones.heart_rate
+    #     if zones.heart_rate.custom_zones
+    #       puts "Using custom heart rate zones"
+    #     else
+    #       puts "Using default heart rate zones"
+    #     end
+    #
+    #     zones.heart_rate.zones.each_with_index do |zone, i|
+    #       puts "Zone #{i + 1}: #{zone.min}-#{zone.max} bpm"
+    #     end
+    #   end
+    #
     class HeartRateZoneRanges < Strava::Models::Response
+      # @return [Boolean] Whether the athlete is using custom heart rate zones
       property 'custom_zones'
+
+      # @return [Array<ZoneRange>] Array of heart rate zone ranges
       property 'zones', transform_with: ->(v) { v.map { |r| Strava::Models::ZoneRange.new(r) } }
     end
   end

data/lib/strava/models/kudoser.rb

@@ -2,11 +2,39 @@
 
 module Strava
   module Models
-    # undocumented
+    #
+    # Represents a user who gave kudos to an activity.
+    #
+    # Kudos are a way for athletes to show appreciation for each other's activities.
+    # 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::Api::Client#activity_kudos
+    #
+    # @example Listing kudos for an activity
+    #   kudos = client.activity_kudos(1234567890)
+    #   kudos.each do |kudoser|
+    #     puts "#{kudoser.display_name} gave kudos"
+    #     puts "  Avatar: #{kudoser.avatar_url}"
+    #   end
+    #
     class Kudoser < Strava::Models::Response
+      # @return [String, nil] URL to the athlete's profile page
+      # @note Not documented by Strava API
       property 'destination_url'
+
+      # @return [String, nil] Display name of the athlete who gave kudos
+      # @note Not documented by Strava API
       property 'display_name'
+
+      # @return [String, nil] URL to the athlete's avatar image
+      # @note Not documented by Strava API
       property 'avatar_url'
+
+      # @return [Boolean, nil] Whether to show the athlete's name
+      # @note Not documented by Strava API
       property 'show_name'
     end
   end

data/lib/strava/models/lap.rb

@@ -2,31 +2,91 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-Lap
+    #
+    # Represents a lap within an activity.
+    #
+    # Laps are splits within an activity, either created manually by the athlete
+    # or auto-generated by the recording device. Each lap contains metrics like
+    # distance, time, speed, and elevation for that specific segment of the activity.
+    #
+    # Includes helper mixins for formatting distance, time, and elevation.
+    #
+    # @example List activity laps
+    #   laps = client.activity_laps(1234567890)
+    #   laps.each_with_index do |lap, i|
+    #     puts "Lap #{i+1}: #{lap.name}"
+    #     puts "Distance: #{lap.distance_s}"
+    #     puts "Time: #{lap.moving_time_in_hours_s}"
+    #     puts "Elevation: #{lap.total_elevation_gain_s}"
+    #   end
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-Lap
+    #
     class Lap < Strava::Models::Response
+      # @return [Integer] Lap ID
       property 'id'
+
+      # @return [MetaActivity] The activity this lap belongs to
       property 'activity', transform_with: ->(v) { Strava::Models::MetaActivity.new(v) }
+
+      # @return [MetaAthlete] The athlete who recorded this lap
       property 'athlete', transform_with: ->(v) { Strava::Models::MetaAthlete.new(v) }
+
+      # @return [Float, nil] Average cadence (RPM for cycling, steps/minute for running)
       property 'average_cadence'
+
+      # @return [Float] Average speed in meters per second
       property 'average_speed'
+
       include Mixins::Distance
       include Mixins::MovingTime
       include Mixins::ElapsedTime
+
+      # @return [Integer] Starting index in the activity's data stream
       property 'start_index'
+
+      # @return [Integer] Ending index in the activity's data stream
       property 'end_index'
+
+      # @return [Integer] The lap number (1-indexed)
       property 'lap_index'
+
+      # @return [Float] Maximum speed in meters per second
       property 'max_speed'
+
+      # @return [String] Lap name (e.g., 'Lap 1', 'Manual Lap')
       property 'name'
+
+      # @return [Integer, nil] Pace zone indicator
       property 'pace_zone'
+
+      # @return [Integer, nil] Split number within the lap
       property 'split'
+
+      # @return [Time] Start date and time (UTC)
       property 'start_date', transform_with: ->(v) { Time.parse(v) }
+
       include Mixins::StartDateLocal
       include Mixins::TotalElevationGain
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Resource state indicator
       property 'resource_state'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the watts are from a power meter (true) or estimated (false)
       property 'device_watts'
+
+      # @note Undocumented in official API
+      # @return [Float, nil] Average power in watts
       property 'average_watts'
+
+      # @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'
     end
   end