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

data/lib/strava/models/summary_club.rb

@@ -2,30 +2,89 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummaryClub
+    #
+    # Represents summary information about a Strava club.
+    #
+    # Contains basic club information without detailed membership data.
+    # This is typically returned when listing athlete's clubs or as a
+    # reference within other models.
+    #
+    # @example List athlete's clubs
+    #   clubs = client.athlete_clubs
+    #   clubs.each do |club|
+    #     puts "#{club.name} - #{club.member_count} members"
+    #     puts club.strava_url
+    #   end
+    #
+    # @see DetailedClub
+    # @see https://developers.strava.com/docs/reference/#api-models-SummaryClub
+    #
     class SummaryClub < 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'
-      # 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'
 
+      #
+      # 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/summary_gear.rb

@@ -2,16 +2,45 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummaryGear
+    #
+    # Represents summary information about athlete's equipment/gear.
+    #
+    # Contains basic gear information without detailed specifications.
+    # Typically returned as part of athlete profile or activity data.
+    #
+    # Includes the Distance mixin for formatting accumulated distance.
+    #
+    # @example Access gear from athlete profile
+    #   athlete = client.athlete
+    #   athlete.bikes.each do |bike|
+    #     puts "#{bike.name}: #{bike.distance_s}"
+    #   end
+    #
+    # @see DetailedGear
+    # @see https://developers.strava.com/docs/reference/#api-models-SummaryGear
+    #
     class SummaryGear < 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
-      # 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'
     end
   end

data/lib/strava/models/summary_pr_segment_effort.rb

@@ -2,14 +2,44 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummaryPRSegmentEffort
+    #
+    # Represents an athlete's personal record (PR) on a segment.
+    #
+    # Contains information about the athlete's best effort on a particular segment,
+    # including when it was achieved and how many times they've attempted the segment.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-SummaryPRSegmentEffort Strava API SummaryPRSegmentEffort reference
+    # @see Strava::Models::SummarySegment
+    # @see Strava::Models::DetailedSegmentEffort
+    #
+    # @example Accessing PR information from a segment
+    #   segment = client.segment(1234567)
+    #   if segment.athlete_pr_effort
+    #     pr = segment.athlete_pr_effort
+    #     puts "Your PR: #{pr.pr_elapsed_time} seconds"
+    #     puts "Set on: #{pr.pr_date}"
+    #     puts "Total attempts: #{pr.effort_count}"
+    #   end
+    #
     class SummaryPRSegmentEffort < Strava::Models::Response
+      # @return [Integer, nil] Activity ID where the PR was achieved
       property 'pr_activity_id'
+
+      # @return [Integer, nil] Elapsed time for the PR effort in seconds
       property 'pr_elapsed_time'
+
+      # @return [Date, nil] Date when the PR was set
       property 'pr_date', transform_with: ->(v) { Date.parse(v) }
+
+      # @return [Integer] Total number of times the athlete has attempted this segment
       property 'effort_count'
-      # undocumented
+
+      # @return [String, nil] Visibility setting for the PR effort
+      # @note Not documented by Strava API
       property 'pr_visibility'
+
+      # @return [String, nil] Visibility setting for the activity containing the PR
+      # @note Not documented by Strava API
       property 'pr_activity_visibility'
     end
   end

data/lib/strava/models/summary_segment.rb

@@ -2,32 +2,110 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummarySegment
+    #
+    # Represents summary information about a segment.
+    #
+    # A segment is a specific section of road or trail that athletes can compete on.
+    # This summary version contains key information about the segment including
+    # location, elevation, and the athlete's personal stats on it.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-SummarySegment Strava API SummarySegment reference
+    # @see Strava::Models::DetailedSegment
+    # @see Strava::Models::ExplorerSegment
+    # @see Strava::Models::SummaryPRSegmentEffort
+    #
+    # @example Accessing segment information from an effort
+    #   activity = client.activity(1234567890)
+    #   activity.segment_efforts.each do |effort|
+    #     segment = effort.segment
+    #     puts "#{segment.name} (#{segment.distance_s})"
+    #     puts "  Location: #{segment.city}, #{segment.state}, #{segment.country}"
+    #     puts "  Grade: #{segment.average_grade}% (max: #{segment.maximum_grade}%)"
+    #     puts "  Elevation: #{segment.elevation_low}m - #{segment.elevation_high}m"
+    #
+    #     if segment.athlete_pr_effort
+    #       puts "  Your PR: #{segment.athlete_pr_effort.pr_elapsed_time}s"
+    #     end
+    #   end
+    #
     class SummarySegment < Strava::Models::Response
+      # @return [Integer] Unique identifier for this segment
       property 'id'
+
+      # @return [String] Name of the segment
       property 'name'
+
+      # @return [String] Activity type this segment is for ("Ride" or "Run")
       property 'activity_type'
+
+      # Includes distance in meters and conversion helper methods
       include Mixins::Distance
+
+      # @return [Float] Average grade/incline as a percentage
       property 'average_grade'
+
+      # @return [Float] Maximum grade/incline as a percentage
       property 'maximum_grade'
+
+      # @return [Float] Highest elevation point on the segment in meters
       property 'elevation_high'
+
+      # @return [Float] Lowest elevation point on the segment in meters
       property 'elevation_low'
+
+      # @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 [Integer] Climb category (0=uncategorized, 5=easiest, 1=hardest, 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 is a private segment
       property 'private'
+
+      # @return [SummaryPRSegmentEffort, nil] Athlete's personal record on this segment
       property 'athlete_pr_effort', transform_with: ->(v) { Strava::Models::SummaryPRSegmentEffort.new(v) }
+
+      # @return [SummarySegmentEffort, nil] Athlete's statistics for this segment
       property 'athlete_segment_stats', transform_with: ->(v) { Strava::Models::SummarySegmentEffort.new(v) }
-      # undocumented
+
+      # @return [Integer] Resource state indicator
+      # @note Not documented by Strava API
       property 'resource_state'
+
+      # @return [String, nil] URL or path to elevation profile visualization
+      # @note Not documented by Strava API
       property 'elevation_profile'
+
+      # @return [Array, nil] Array of elevation profile data
+      # @note Not documented by Strava API
       property 'elevation_profiles'
+
+      # @return [Boolean, nil] Whether this segment has been flagged as hazardous
+      # @note Not documented by Strava API
       property 'hazardous'
+
+      # @return [Boolean, nil] Whether the current athlete has starred this segment
+      # @note Not documented by Strava API
       property 'starred'
+
+      # @return [Time, nil] Date when the athlete starred this segment
+      # @note Not documented by Strava API
       property 'starred_date', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [Integer, nil] Athlete's PR time on this segment in seconds
+      # @note Not documented by Strava API
       property 'pr_time'
     end
   end

data/lib/strava/models/summary_segment_effort.rb

@@ -2,14 +2,45 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-SummarySegmentEffort
+    #
+    # Represents a summary of a segment effort within an activity.
+    #
+    # A segment effort is an attempt at a defined segment (a portion of road or trail).
+    # This summary version contains basic information about the effort without
+    # detailed statistics.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-SummarySegmentEffort Strava API SummarySegmentEffort reference
+    # @see Strava::Models::DetailedSegmentEffort
+    # @see Strava::Models::DetailedActivity#segment_efforts
+    #
+    # @example Accessing segment efforts from an activity
+    #   activity = client.activity(1234567890)
+    #   activity.segment_efforts.each do |effort|
+    #     puts "#{effort.name}: #{effort.elapsed_time_in_hours_s}"
+    #     puts "  KOM: #{effort.is_kom}"
+    #     puts "  Distance: #{effort.distance_s}"
+    #   end
+    #
     class SummarySegmentEffort < 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'
     end
   end

data/lib/strava/models/timed_zone_range.rb

@@ -2,10 +2,33 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-TimedZoneRange
+    #
+    # Represents a training zone range with time spent in that zone.
+    #
+    # Used in activity zone distributions to show how much time was spent
+    # at different intensity levels during an activity.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-TimedZoneRange Strava API TimedZoneRange reference
+    # @see Strava::Models::ZoneRange
+    # @see Strava::Models::ActivityZone
+    #
+    # @example Viewing time distribution across zones
+    #   zones = client.activity_zones(1234567890)
+    #   hr_zone = zones.find { |z| z.type == 'heartrate' }
+    #
+    #   hr_zone.distribution_buckets.each_with_index do |bucket, i|
+    #     minutes = bucket.time / 60
+    #     puts "Zone #{i + 1} (#{bucket.min}-#{bucket.max} bpm): #{minutes} minutes"
+    #   end
+    #
     class TimedZoneRange < Strava::Models::Response
+      # @return [Integer] Maximum value for this zone (e.g., maximum heart rate or power)
       property 'max'
+
+      # @return [Integer] Minimum value for this zone (e.g., minimum heart rate or power)
       property 'min'
+
+      # @return [Integer] Time spent in this zone in seconds
       property 'time'
     end
   end

data/lib/strava/models/token.rb

@@ -2,12 +2,43 @@
 
 module Strava
   module Models
+    #
+    # Represents an OAuth token response from Strava.
+    #
+    # This model is returned when exchanging an authorization code for an access token
+    # or when refreshing an expired token. It contains the access token, refresh token,
+    # expiration time, and basic athlete information.
+    #
+    # Tokens expire after a period of time (typically 6 hours). When a token expires,
+    # use the refresh_token to obtain a new access_token via the OAuth flow.
+    #
+    # @example Inspecting token information
+    #   token = client.oauth_token(code: 'auth_code')
+    #   puts "Access Token: #{token.access_token}"
+    #   puts "Refresh Token: #{token.refresh_token}"
+    #   puts "Expires at: #{token.expires_at}"
+    #   puts "Athlete: #{token.athlete.firstname} #{token.athlete.lastname}"
+    #
+    # @see Strava::OAuth::Client#oauth_token
+    # @see https://developers.strava.com/docs/authentication/
+    #
     class Token < Strava::Models::Response
+      # @return [String] Type of token, typically "Bearer"
       property 'token_type'
+
+      # @return [String] OAuth access token for API authentication
       property 'access_token'
+
+      # @return [String] Refresh token for obtaining new access tokens
       property 'refresh_token'
+
+      # @return [Integer] Number of seconds until token expires
       property 'expires_in'
+
+      # @return [Time] Expiration time of the access token
       property 'expires_at', transform_with: ->(v) { Time.at(v) }
+
+      # @return [Strava::Models::SummaryAthlete] Summary of the authenticated athlete
       property 'athlete', transform_with: ->(v) { Strava::Models::SummaryAthlete.new(v) }
     end
   end

data/lib/strava/models/trend.rb

@@ -2,13 +2,50 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents performance trend data.
+    #
+    # Contains trend information about speed and performance over time,
+    # showing whether performance is improving, declining, or staying consistent.
+    # 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::SimilarActivities
+    #
+    # @example Accessing trend data
+    #   activity = client.activity(1234567890)
+    #   if activity.similar_activities&.trend
+    #     trend = activity.similar_activities.trend
+    #     puts "Trend direction: #{trend.direction}"
+    #     puts "Speed range: #{trend.min_speed} - #{trend.max_speed} m/s"
+    #     puts "Current activity index: #{trend.current_activity_index}"
+    #   end
+    #
     class Trend < Strava::Models::Response
+      # @return [Array, nil] Array of speed values showing the trend
+      # @note Not documented by Strava API
       property 'speeds'
+
+      # @return [Integer, nil] Index of current activity in the trend series
+      # @note Not documented by Strava API
       property 'current_activity_index'
+
+      # @return [Float, nil] Minimum speed in the trend in meters per second
+      # @note Not documented by Strava API
       property 'min_speed'
+
+      # @return [Float, nil] Median speed in the trend in meters per second
+      # @note Not documented by Strava API
       property 'mid_speed'
+
+      # @return [Float, nil] Maximum speed in the trend in meters per second
+      # @note Not documented by Strava API
       property 'max_speed'
+
+      # @return [Integer, nil] Trend direction indicator (e.g., -1=declining, 0=stable, 1=improving)
+      # @note Not documented by Strava API
       property 'direction'
     end
   end

data/lib/strava/models/updatable_activity.rb

@@ -2,14 +2,49 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-UpdatableActivity
+    #
+    # Represents the response from updating an activity.
+    #
+    # When you update an activity using the update_activity endpoint, Strava returns
+    # this model containing the fields that were successfully updated. This is a subset
+    # of the full activity data.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-UpdatableActivity Strava API UpdatableActivity reference
+    # @see Strava::Api::Client#update_activity
+    # @see Strava::Models::DetailedActivity
+    #
+    # @example Updating activity properties
+    #   updated = client.update_activity(1234567890,
+    #     name: "Morning Run",
+    #     description: "Great weather today!",
+    #     commute: false,
+    #     trainer: false,
+    #     gear_id: "g12345"
+    #   )
+    #
+    #   puts "Activity renamed to: #{updated.name}"
+    #   puts "Gear ID: #{updated.gear_id}"
+    #
     class UpdatableActivity < Strava::Models::Response
+      # @return [Boolean, nil] Whether this activity is a commute
       property 'commute'
+
+      # @return [Boolean, nil] Whether this activity was done on a trainer/treadmill
       property 'trainer'
+
+      # @return [Boolean, nil] Whether to hide this activity from the home feed
       property 'hide_from_home'
+
+      # @return [String, nil] Description of the activity
       property 'description'
+
+      # @return [String, nil] Name/title of the activity
       property 'name'
+
+      # @return [String, nil] Sport type (e.g., "Run", "Ride", "Swim")
       property 'sport_type'
+
+      # @return [String, nil] ID of the gear (shoes/bike) used for this activity
       property 'gear_id'
     end
   end

data/lib/strava/models/upload.rb

@@ -2,20 +2,69 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-Upload
+    #
+    # Represents an activity file upload status.
+    #
+    # When uploading activity files (GPX, TCX, FIT) to Strava, the upload is processed
+    # asynchronously. This model tracks the upload status and provides helper methods
+    # to check if processing is complete.
+    #
+    # @example Upload and poll for completion
+    #   upload = client.create_upload(
+    #     file: Faraday::UploadIO.new('activity.gpx', 'application/gpx+xml'),
+    #     data_type: 'gpx'
+    #   )
+    #
+    #   while upload.processing?
+    #     sleep 2
+    #     upload = client.upload(upload.id)
+    #   end
+    #
+    #   if upload.error
+    #     puts "Upload failed: #{upload.error}"
+    #   else
+    #     puts "Activity created: #{upload.activity_id}"
+    #   end
+    #
+    # @see Strava::Api::Client#create_upload
+    # @see Strava::Api::Client#upload
+    # @see https://developers.strava.com/docs/reference/#api-models-Upload
+    #
     class Upload < Strava::Models::Response
+      # @return [Integer] Upload ID
       property 'id'
+
+      # @return [String] Upload ID as string
       property 'id_str'
+
+      # @return [String] External identifier for the upload
       property 'external_id'
+
+      # @return [String, nil] Error message if upload failed
       property 'error'
+
+      # @return [String] Status message (e.g., "Your activity is ready.", "Your activity is still being processed.")
       property 'status'
+
+      # @return [Integer, nil] Activity ID once processing is complete
       property 'activity_id'
 
+      #
+      # Checks if the upload is still processing.
+      #
+      # @return [Boolean] true if upload is still being processed
+      # @raise [Strava::Errors::UploadError] if upload failed with an error
+      #
       def processing?
         validate!
         activity_id.nil?
       end
 
+      #
+      # Checks if the upload has completed processing.
+      #
+      # @return [Boolean] true if upload processing is complete
+      #
       def processed?
         !processing?
       end

data/lib/strava/models/waypoint.rb

@@ -2,13 +2,43 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-Waypoint
+    #
+    # Represents a waypoint on a route.
+    #
+    # Waypoints are markers along a route that can indicate points of interest,
+    # turns, or other significant locations. They include GPS coordinates and
+    # descriptive information.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-Waypoint Strava API Waypoint reference
+    # @see Strava::Models::Route
+    # @see Strava::Models::LatLng
+    #
+    # @example Accessing route waypoints
+    #   route = client.route(1234567)
+    #   route.waypoints.each do |waypoint|
+    #     puts "#{waypoint.title}: #{waypoint.description}"
+    #     puts "  Location: #{waypoint.latlng.lat}, #{waypoint.latlng.lng}"
+    #     puts "  Distance into route: #{waypoint.distance_into_route}m"
+    #     puts "  Categories: #{waypoint.categories.join(', ')}"
+    #   end
+    #
     class Waypoint < Strava::Models::Response
+      # @return [LatLng] GPS coordinates of the waypoint
       property 'latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [LatLng, nil] Target GPS coordinates (may differ from latlng for snapped waypoints)
       property 'target_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
+
+      # @return [Array<String>] Categories or types for this waypoint (e.g., ["water", "rest"])
       property 'categories'
+
+      # @return [String] Title or name of the waypoint
       property 'title'
+
+      # @return [String, nil] Detailed description of the waypoint
       property 'description'
+
+      # @return [Float] Distance from the start of the route to this waypoint in meters
       property 'distance_into_route'
     end
   end