strava-ruby-client 3.0.0 → 3.1.0

data/lib/strava/models/detailed_activity.rb

@@ -2,87 +2,288 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-DetailedActivity
+    #
+    # Represents a detailed Strava activity.
+    #
+    # A detailed activity contains all information about a single workout, ride, run,
+    # or other athletic pursuit recorded on Strava. This includes basic information
+    # (name, type, date), metrics (distance, time, elevation), maps, segments, photos,
+    # and social interactions (kudos, comments).
+    #
+    # This model includes several mixins that provide helper methods for formatting data:
+    # * {Mixins::Distance} - distance_s, distance_in_miles, etc.
+    # * {Mixins::MovingTime} - moving_time_in_hours_s, etc.
+    # * {Mixins::ElapsedTime} - elapsed_time_in_hours_s, etc.
+    # * {Mixins::AverageSpeed} - average_speed_s, pace_s, etc.
+    # * {Mixins::TotalElevationGain} - total_elevation_gain_s, etc.
+    # * {Mixins::SportType} - sport_type_emoji
+    #
+    # @example Get and display activity details
+    #   activity = client.activity(1234567890)
+    #   puts activity.name
+    #   puts "Distance: #{activity.distance_s}"
+    #   puts "Time: #{activity.moving_time_in_hours_s}"
+    #   puts "Pace: #{activity.pace_s}"
+    #   puts "Elevation: #{activity.total_elevation_gain_s}"
+    #   puts "URL: #{activity.strava_url}"
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-DetailedActivity
+    #
     class DetailedActivity < 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::AverageSpeed
       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 (e.g., '(GMT-08:00) America/Los_Angeles')
       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'
+
+      # @return [String, nil] Activity description
       property 'description'
+
+      # @return [PhotosSummary, nil] Summary of activity photos
       property 'photos', transform_with: ->(v) { Strava::Models::PhotosSummary.new(v) }
+
+      # @return [SummaryGear, nil] The gear (bike/shoes) used for this activity
       property 'gear', transform_with: ->(v) { Strava::Models::SummaryGear.new(v) }
+
+      # @return [Float, nil] Estimated calories burned
       property 'calories'
+
+      # @return [Array<DetailedSegmentEffort>] All segment efforts for this activity
       property 'segment_efforts', transform_with: ->(v) { v.map { |r| Strava::Models::DetailedSegmentEffort.new(r) } }
+
+      # @return [String, nil] Name of the device used to record the activity
       property 'device_name'
+
+      # @return [String, nil] Embed token for the activity
       property 'embed_token'
+
+      # @return [Array<Split>] Metric splits (per kilometer)
       property 'splits_metric', transform_with: ->(v) { v.map { |r| Strava::Models::Split.new(r) } }
+
+      # @return [Array<Split>] Standard/imperial splits (per mile)
       property 'splits_standard', transform_with: ->(v) { v.map { |r| Strava::Models::Split.new(r) } }
+
+      # @return [Array<Lap>] Laps for the activity
       property 'laps', transform_with: ->(v) { v.map { |r| Strava::Models::Lap.new(r) } }
+
+      # @return [Array<DetailedSegmentEffort>] Best efforts (e.g., 400m, 1/2 mile, 1k, etc.)
       property 'best_efforts', transform_with: ->(v) { v.map { |r| Strava::Models::DetailedSegmentEffort.new(r) } }
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Resource state indicator
       property 'resource_state'
+
+      # @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 [String, nil] Activity visibility setting (e.g., 'everyone', 'followers_only')
       property 'visibility'
+
+      # @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'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Athlete's perceived exertion rating
       property 'perceived_exertion'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether to prefer perceived exertion over calculated metrics
       property 'prefer_perceived_exertion'
+
+      # @note Undocumented in official API
+      # @return [Array<StatsVisibility>, nil] Stats visibility settings
       property 'stats_visibility', transform_with: ->(v) { v.map { |r| Strava::Models::StatsVisibility.new(r) } }
+
+      # @note Undocumented in official API
+      # @return [Array<String>, nil] List of available zone types for this activity
       property 'available_zones'
+
+      # @note Undocumented in official API
+      # @return [SimilarActivities, nil] Information about similar activities
       property 'similar_activities', transform_with: ->(v) { Strava::Models::SimilarActivities.new(v) }
+
+      # @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 [Array, nil] List of highlighted athletes who gave kudos
       property 'highlighted_kudosers'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the athlete has opted out of segment leaderboards
       property 'segment_leaderboard_opt_out'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the athlete has opted out of all leaderboards
       property 'leaderboard_opt_out'
 
+      #
+      # Returns the Strava web URL for this activity.
+      #
+      # @return [String] Full URL to view the activity on Strava.com
+      #
+      # @example
+      #   activity = client.activity(1234567890)
+      #   puts activity.strava_url
+      #   # => "https://www.strava.com/activities/1234567890"
+      #
       def strava_url
         "https://www.strava.com/activities/#{id}"
       end

data/lib/strava/models/detailed_athlete.rb

@@ -2,47 +2,149 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-DetailedAthlete
+    #
+    # Represents detailed information about a Strava athlete.
+    #
+    # Contains comprehensive profile information including personal details,
+    # preferences, gear, clubs, and social connections. This model is typically
+    # returned when accessing the authenticated athlete's own profile.
+    #
+    # @example Get athlete profile
+    #   athlete = client.athlete
+    #   puts athlete.name
+    #   puts "Location: #{athlete.city}, #{athlete.state}, #{athlete.country}"
+    #   puts "Premium: #{athlete.premium}"
+    #   puts "Weight: #{athlete.weight}kg"
+    #   puts athlete.strava_url
+    #
+    # @see SummaryAthlete
+    # @see https://developers.strava.com/docs/reference/#api-models-DetailedAthlete
+    #
     class DetailedAthlete < 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) }
+
+      # @return [Integer] Number of followers
       property 'follower_count'
+
+      # @return [Integer] Number of friends (mutual follows)
       property 'friend_count'
+
+      # @return [String] Preferred measurement system ('feet' or 'meters')
       property 'measurement_preference'
+
+      # @return [Integer, nil] Functional Threshold Power in watts
       property 'ftp'
+
+      # @return [Float, nil] Weight in kilograms
       property 'weight'
+
+      # @return [Array<SummaryClub>] Clubs the athlete belongs to
       property 'clubs', transform_with: ->(v) { v.map { |r| Strava::Models::SummaryClub.new(r) } }
+
+      # @return [Array<SummaryGear>] Bikes registered to this athlete
       property 'bikes', transform_with: ->(v) { v.map { |r| Strava::Models::SummaryGear.new(r) } }
+
+      # @return [Array<SummaryGear>] Shoes registered to this athlete
       property 'shoes', transform_with: ->(v) { v.map { |r| Strava::Models::SummaryGear.new(r) } }
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [String, nil] Username/vanity URL
       property 'username'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Athlete bio/description
       property 'bio'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Badge type identifier
       property 'badge_type_id'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Relationship status with authenticated athlete ('pending', 'accepted', 'blocked', or nil)
       property 'friend'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Follower relationship status
       property 'follower'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether this athlete is blocked by the authenticated athlete
       property 'blocked'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the authenticated athlete can follow this athlete
       property 'can_follow'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Number of mutual friends with the authenticated athlete
       property 'mutual_friend_count'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Athlete type identifier (0 = Cyclist, 1 = Runner)
       property 'athlete_type'
+
+      # @note Undocumented in official API
+      # @return [String, nil] Preferred date format
       property 'date_preference'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Number of clubs where athlete can post
       property 'postable_clubs_count'
 
+      #
+      # 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/#{username || id}"
       end

data/lib/strava/models/detailed_club.rb

@@ -2,37 +2,111 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-DetailedClub
+    #
+    # Represents detailed information about a Strava club.
+    #
+    # Clubs are groups of athletes on Strava. This model contains comprehensive
+    # club information including member counts, location, sport type, and membership
+    # status for the authenticated athlete.
+    #
+    # @example Get club details
+    #   club = client.club(12345)
+    #   puts club.name
+    #   puts "#{club.member_count} members in #{club.city}, #{club.country}"
+    #   puts "Sport type: #{club.sport_type}"
+    #   puts "Private: #{club.private}"
+    #   puts club.strava_url
+    #
+    # @see SummaryClub
+    # @see https://developers.strava.com/docs/reference/#api-models-DetailedClub
+    #
     class DetailedClub < Strava::Models::Response
+      # @return [Integer] Club identifier
       property 'id'
+
+      # @return [Integer] Resource state indicator (1=meta, 2=summary, 3=detailed)
       property 'resource_state'
+
+      # @return [String] Club name
       property 'name'
+
+      # @return [String] URL to medium-sized profile picture
       property 'profile_medium'
+
+      # @return [String] URL to club cover photo
       property 'cover_photo'
+
+      # @return [String] URL to smaller club cover photo
       property 'cover_photo_small'
+
+      # @return [String] Primary sport type (e.g., "cycling", "running", "other")
       property 'sport_type'
+
+      # @return [Array<String>] List of activity types the club supports
       property 'activity_types'
+
+      # @return [String] City where club is located
       property 'city'
+
+      # @return [String] State/province where club is located
       property 'state'
+
+      # @return [String] Country where club is located
       property 'country'
+
+      # @return [Boolean] Whether club is private
       property 'private'
+
+      # @return [Integer] Number of club members
       property 'member_count'
+
+      # @return [Boolean] Whether club is featured by Strava
       property 'featured'
+
+      # @return [Boolean] Whether club is verified by Strava
       property 'verified'
+
+      # @return [String] Club URL slug
       property 'url'
+
+      # @return [String] Authenticated athlete's membership status (e.g., "member", "pending")
       property 'membership'
+
+      # @return [Boolean] Whether authenticated athlete is a club administrator
       property 'admin'
+
+      # @return [Boolean] Whether authenticated athlete is the club owner
       property 'owner'
+
+      # @return [String] Type of club (e.g., "casual_club", "racing_team", "shop", "company", "other")
       property 'club_type'
+
+      # @return [Integer] Number of athletes following this club
       property 'following_count'
-      # undocumented
+
+      # @return [String] URL to full-sized profile picture
       property 'profile'
+
+      # @return [String] Icon representing the activity types
       property 'activity_types_icon'
+
+      # @return [Array<Integer>] Dimensions of cover photo [width, height]
       property 'dimensions'
+
+      # @return [String] Localized sport type string
       property 'localized_sport_type'
+
+      # @return [String] Club description text
       property 'description'
+
+      # @return [String] Club website URL
       property 'website'
 
+      #
+      # Returns the Strava web URL for this club.
+      #
+      # @return [String] Full URL to view the club on Strava.com
+      #
       def strava_url
         "https://www.strava.com/clubs/#{url || id}"
       end

data/lib/strava/models/detailed_gear.rb

@@ -2,22 +2,65 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-DetailedGear
+    #
+    # Represents detailed information about an athlete's equipment/gear.
+    #
+    # Gear includes bikes, shoes, and other equipment that athletes track mileage on.
+    # Each piece of gear has a name, brand, model, and accumulated distance.
+    #
+    # Includes the Distance mixin for formatting accumulated distance.
+    #
+    # @example Get gear details
+    #   gear = client.gear('b12345')
+    #   puts gear.name
+    #   puts "#{gear.brand_name} #{gear.model_name}"
+    #   puts "Total distance: #{gear.distance_s}"
+    #   puts "Weight: #{gear.weight}g" if gear.weight
+    #   puts "Retired" if gear.retired
+    #
+    # @see SummaryGear
+    # @see https://developers.strava.com/docs/reference/#api-models-DetailedGear
+    #
     class DetailedGear < Strava::Models::Response
+      # @return [String] Gear identifier (e.g., "b12345" for bike, "g12345" for shoes)
       property 'id'
+
+      # @return [Integer] Resource state indicator
       property 'resource_state'
+
+      # @return [Boolean] Whether this is the athlete's primary gear for this type
       property 'primary'
+
+      # @return [String] Gear name/title
       property 'name'
+
       include Mixins::Distance
+
+      # @return [String] Brand/manufacturer name
       property 'brand_name'
+
+      # @return [String] Model name
       property 'model_name'
+
+      # @return [Integer] Frame type identifier (for bikes)
       property 'frame_type'
+
+      # @return [String] Gear description/notes
       property 'description'
-      # undocumented
+
+      # @return [String] Nickname for the gear
       property 'nickname'
+
+      # @return [Boolean] Whether gear has been retired/is no longer in use
       property 'retired'
+
+      # @return [Float] Distance in meters after conversion (likely for imperial users)
       property 'converted_distance'
+
+      # @return [Float] Distance threshold for maintenance notifications (in meters)
       property 'notification_distance'
+
+      # @return [Float] Weight of the gear in grams
       property 'weight'
     end
   end