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

data/lib/strava/api/endpoints/activities.rb

@@ -3,19 +3,70 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava activities.
+      #
+      # Activities represent workouts, rides, runs, and other athletic pursuits recorded on Strava.
+      # This module provides methods for creating, retrieving, updating, and listing activities,
+      # as well as accessing related data like comments, kudos, laps, and zones.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Activities
+      #
       module Activities
         #
-        # Create an activity.
+        # Create a manual activity.
+        #
+        # Creates a new manual activity for an athlete. Requires write access.
+        #
+        # @param [Hash] options Activity attributes
+        # @option options [String] :name Activity name (required)
+        # @option options [String] :sport_type Activity type (required, e.g., 'Run', 'Ride', 'Swim')
+        # @option options [Time, String] :start_date_local Local start date and time (required)
+        # @option options [Integer] :elapsed_time Activity duration in seconds (required)
+        # @option options [String] :description Activity description
+        # @option options [Float] :distance Distance in meters
+        # @option options [Boolean] :trainer Whether activity was on a trainer
+        # @option options [Boolean] :commute Whether activity was a commute
+        #
+        # @return [Strava::Models::DetailedActivity] The created activity
+        #
+        # @example
+        #   activity = client.create_activity(
+        #     name: 'Morning Run',
+        #     sport_type: 'Run',
+        #     start_date_local: Time.now,
+        #     elapsed_time: 3600,
+        #     distance: 10000,
+        #     description: 'Easy recovery run'
+        #   )
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Activities-createActivity
         #
         def create_activity(options = {})
           Strava::Models::DetailedActivity.new(post('activities', options))
         end
 
         #
-        # Get activity.
+        # Get detailed information about a specific activity.
+        #
+        # Returns the given activity that is owned by the authenticated athlete.
+        # Includes all activity details such as splits, laps, segment efforts, and photos.
         #
-        # @option options [String] :id
-        #   Activity id.
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Additional options
+        # @option options [Boolean] :include_all_efforts Include all segment efforts
+        #
+        # @return [Strava::Models::DetailedActivity] The activity
+        #
+        # @example Get activity by ID
+        #   activity = client.activity(1234567890)
+        #   puts activity.name
+        #   puts activity.distance_s
+        #
+        # @example Get activity with options hash
+        #   activity = client.activity(id: 1234567890, include_all_efforts: true)
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Activities-getActivityById
         #
         def activity(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -23,17 +74,29 @@ module Strava
         end
 
         #
-        # List activity comments.
+        # List comments for an activity.
+        #
+        # Returns the comments on the given activity. Supports cursor-based pagination.
         #
-        # @option options [String] :id
-        #   Activity id.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :page_size
-        #   Number of items per page. Defaults to 30.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
-        #   @deprecated use {page_size}
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Pagination options
+        # @option options [Integer] :page_size Number of items per page (default: 30)
+        # @option options [String] :after_cursor Cursor for pagination
+        # @option options [Integer] :limit Maximum number of items to return
+        # @option options [Integer] :per_page (Deprecated) Use :page_size instead
+        #
+        # @yield [Strava::Models::Comment] Yields each comment if block given
+        # @return [Array<Strava::Models::Comment>] Array of comments
+        #
+        # @example Get all comments
+        #   comments = client.activity_comments(1234567890)
+        #
+        # @example Paginate through comments
+        #   client.activity_comments(1234567890, page_size: 50) do |comment|
+        #     puts "#{comment.athlete.username}: #{comment.text}"
+        #   end
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Activities-getCommentsByActivityId
         #
         def activity_comments(id_or_options, options = {}, &block)
           id, options = parse_args(id_or_options, options)
@@ -41,14 +104,26 @@ module Strava
         end
 
         #
-        # List activity photos.
+        # List photos for an activity.
+        #
+        # Returns the photos on the given activity. This is an undocumented Strava API endpoint.
+        # By default, retrieves full-size photos (5000px).
         #
-        # @option options [String] :id
-        #   Activity id.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Pagination options
+        # @option options [Integer] :size Photo size in pixels (default: 5000 for full size)
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page (default: 30)
+        #
+        # @yield [Strava::Models::DetailedPhoto] Yields each photo if block given
+        # @return [Array<Strava::Models::DetailedPhoto>] Array of photos
+        #
+        # @example Get all photos
+        #   photos = client.activity_photos(1234567890)
+        #   photos.each { |photo| puts photo.urls }
+        #
+        # @example Get specific size
+        #   photos = client.activity_photos(1234567890, size: 1920)
         #
         def activity_photos(id_or_options, options = {}, &block)
           id, options = parse_args(id_or_options, options)
@@ -57,14 +132,23 @@ module Strava
         end
 
         #
-        # List activity kudoers.
+        # List athletes who kudoed an activity.
+        #
+        # Returns the athletes who kudoed an activity identified by an identifier.
+        #
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Pagination options
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page (default: 30)
         #
-        # @option options [String] :id
-        #   Activity id.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # @yield [Strava::Models::SummaryAthlete] Yields each athlete if block given
+        # @return [Array<Strava::Models::SummaryAthlete>] Array of athletes
+        #
+        # @example Get all kudoers
+        #   kudoers = client.activity_kudos(1234567890)
+        #   kudoers.each { |athlete| puts athlete.username }
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Activities-getKudoersByActivityId
         #
         def activity_kudos(id_or_options, options = {}, &block)
           id, options = parse_args(id_or_options, options)
@@ -72,10 +156,21 @@ module Strava
         end
 
         #
-        # Get activity laps.
+        # List laps for an activity.
+        #
+        # Returns the laps of an activity identified by an identifier.
+        # Laps are split segments either created manually or auto-generated.
+        #
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Additional options
+        #
+        # @return [Array<Strava::Models::Lap>] Array of laps
+        #
+        # @example Get activity laps
+        #   laps = client.activity_laps(1234567890)
+        #   laps.each { |lap| puts "#{lap.name}: #{lap.distance_s}" }
         #
-        # @option options [String] :id
-        #   Activity id.
+        # @see https://developers.strava.com/docs/reference/#api-Activities-getLapsByActivityId
         #
         def activity_laps(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -85,16 +180,36 @@ module Strava
         end
 
         #
-        # List logged-in athlete activities.
+        # List activities for the authenticated athlete.
+        #
+        # Returns the currently logged-in athlete's activities. Supports pagination and time-based filtering.
+        # Activities are returned in descending order by start date.
+        #
+        # @param [Hash] options Pagination and filtering options
+        # @option options [Time, Integer] :before Epoch timestamp or Time object for filtering activities before this time
+        # @option options [Time, Integer] :after Epoch timestamp or Time object for filtering activities after this time
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page (default: 30)
+        # @option options [Integer] :limit Maximum number of items to return
+        #
+        # @yield [Strava::Models::SummaryActivity] Yields each activity if block given
+        # @return [Array<Strava::Models::SummaryActivity>] Array of activities
+        #
+        # @example Get recent activities
+        #   activities = client.athlete_activities(per_page: 10)
+        #
+        # @example Get activities with time filter
+        #   activities = client.athlete_activities(
+        #     after: Time.now - 7.days,
+        #     per_page: 50
+        #   )
         #
-        # @option options [Integer] :before
-        #   An epoch timestamp to use for filtering activities that have taken place before a certain time.
-        # @option options [Integer] :after
-        #   An epoch timestamp to use for filtering activities that have taken place after a certain time.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # @example Paginate through all activities
+        #   client.athlete_activities(per_page: 100) do |activity|
+        #     puts "#{activity.name}: #{activity.distance_s}"
+        #   end
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Activities-getLoggedInAthleteActivities
         #
         def athlete_activities(options = {}, &block)
           options = options.dup if options.key?(:after) || options.key?(:before)
@@ -104,10 +219,24 @@ module Strava
         end
 
         #
-        # Get activity zones.
+        # Get zones for an activity.
+        #
+        # Returns the zones of a given activity. Summit feature required.
+        # Zones include heart rate and power zones with distribution buckets.
+        #
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Additional options
+        #
+        # @return [Array<Strava::Models::ActivityZone>] Array of activity zones
+        #
+        # @example Get activity zones
+        #   zones = client.activity_zones(1234567890)
+        #   zones.each do |zone|
+        #     puts "Type: #{zone.type}"
+        #     zone.distribution_buckets.each { |bucket| puts "#{bucket.min}-#{bucket.max}: #{bucket.time}s" }
+        #   end
         #
-        # @option options [String] :id
-        #   Activity id.
+        # @see https://developers.strava.com/docs/reference/#api-Activities-getZonesByActivityId
         #
         def activity_zones(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -119,20 +248,31 @@ module Strava
         #
         # Update an activity.
         #
-        # @option options [String] :id
-        #   Activity id.
-        # @option options [Boolean] :commute
-        #   Whether this activity is a commute.
-        # @option options [Boolean] :trainer
-        #   Whether this activity was recorded on a training machine.
-        # @option options [String] :description
-        #   The description of the activity.
-        # @option options [String] :name
-        #   The name of the activity.
-        # @option options [String] :sport_type
-        #   Activity type.
-        # @option options [String] :gear_id
-        #   Identifier for the gear associated with the activity. Specifying "none" clears gear from activity.
+        # Updates the given activity that is owned by the authenticated athlete.
+        # Requires write access.
+        #
+        # @param [Integer, Hash] id_or_options Activity ID or options hash with :id key
+        # @param [Hash] options Activity attributes to update
+        # @option options [Boolean] :commute Whether this activity is a commute
+        # @option options [Boolean] :trainer Whether this activity was recorded on a training machine
+        # @option options [String] :description Activity description
+        # @option options [String] :name Activity name
+        # @option options [String] :sport_type Activity type (e.g., 'Run', 'Ride')
+        # @option options [String] :gear_id Equipment ID (specify "none" to clear gear)
+        #
+        # @return [Strava::Models::DetailedActivity] The updated activity
+        #
+        # @example Update activity name and description
+        #   activity = client.update_activity(
+        #     id: 1234567890,
+        #     name: 'Updated Activity Name',
+        #     description: 'New description'
+        #   )
+        #
+        # @example Mark as commute
+        #   activity = client.update_activity(1234567890, commute: true)
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Activities-updateActivityById
         #
         def update_activity(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)

data/lib/strava/api/endpoints/athletes.rb

@@ -3,26 +3,72 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava athletes.
+      #
+      # Athletes represent Strava users. This module provides methods for retrieving
+      # athlete profiles, stats, zones, and updating athlete information.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Athletes
+      #
       module Athletes
         #
-        # Returns the currently authenticated athlete.
+        # Get the authenticated athlete's profile.
+        #
+        # Returns the currently authenticated athlete with detailed information.
+        # Requires profile:read_all scope for full profile access.
+        #
+        # @return [Strava::Models::DetailedAthlete] The authenticated athlete
+        #
+        # @example Get athlete profile
+        #   athlete = client.athlete
+        #   puts "#{athlete.firstname} #{athlete.lastname}"
+        #   puts "Location: #{athlete.city}, #{athlete.state}"
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Athletes-getLoggedInAthlete
         #
         def athlete
           Strava::Models::DetailedAthlete.new(get('athlete'))
         end
 
         #
-        # Returns the the authenticated athlete's heart rate and power zones.
+        # Get the authenticated athlete's heart rate and power zones.
+        #
+        # Returns the athlete's configured training zones for heart rate and power.
+        # These zones are used for training analysis and activity classification.
+        #
+        # @param [Hash] options Additional options
+        #
+        # @return [Strava::Models::Zones] Athlete zones including heart rate and power
+        #
+        # @example Get athlete zones
+        #   zones = client.athlete_zones
+        #   heart_rate = zones.heart_rate
+        #   heart_rate.zones.each { |zone| puts "#{zone.min}-#{zone.max} bpm" }
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Athletes-getLoggedInAthleteZones
         #
         def athlete_zones(options = {})
           Strava::Models::Zones.new(get('athlete/zones', options))
         end
 
         #
-        # Returns the activity stats of an athlete.
+        # Get activity statistics for an athlete.
         #
-        # @option options [String] :id
-        #   Athlete id.
+        # Returns the activity stats of an athlete including recent totals, year-to-date totals,
+        # and all-time totals for different activity types.
+        #
+        # @param [Integer, Hash] id_or_options Athlete ID or options hash with :id key
+        # @param [Hash] options Additional options
+        #
+        # @return [Strava::Models::ActivityStats] Activity statistics
+        #
+        # @example Get athlete stats
+        #   stats = client.athlete_stats(12345)
+        #   recent_run = stats.recent_run_totals
+        #   puts "Recent runs: #{recent_run.count} totaling #{recent_run.distance_s}"
+        #
+        # @see https://developers.strava.com/docs/reference/#api-Athletes-getStats
         #
         def athlete_stats(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -30,10 +76,20 @@ module Strava
         end
 
         #
-        # Update the currently authenticated athlete.
+        # Update the authenticated athlete's profile.
+        #
+        # Updates the currently authenticated athlete. Only weight can be updated.
+        # Requires profile:write scope.
+        #
+        # @param [Hash] options Athlete attributes to update
+        # @option options [Float] :weight Athlete weight in kilograms
+        #
+        # @return [Strava::Models::DetailedAthlete] The updated athlete profile
+        #
+        # @example Update athlete weight
+        #   athlete = client.update_athlete(weight: 70.5)
         #
-        # @option options [Float] :weight
-        #   The weight of the athlete in kilograms.
+        # @see https://developers.strava.com/docs/reference/#api-Athletes-updateLoggedInAthlete
         #
         def update_athlete(options = {})
           Strava::Models::DetailedAthlete.new(put('athlete', options))

data/lib/strava/api/endpoints/clubs.rb

@@ -3,57 +3,36 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava clubs.
+      #
+      # Clubs represent groups of athletes on Strava. Club API endpoints allow
+      # you to retrieve club information and view recent club events.
+      #
+      # Note: the Club Activities, Club Members, and Club Admins endpoints were
+      # removed by Strava on September 1, 2026.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Clubs
+      # @see https://developers.strava.com/docs/changelog/
+      #
       module Clubs
         #
-        # List club activities.
-        #
-        # @option options [String] :id
-        #   Club id.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
-        #
-        def club_activities(id_or_options, options = {}, &block)
-          id, options = parse_args(id_or_options, options)
-          paginate "clubs/#{id}/activities", options, Strava::Models::ClubActivity, &block
-        end
-
-        #
-        # List club / group events.
-        #
-        # @option options [String] :id
-        #   Club id.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
-        #
-        def club_events(id_or_options, options = {}, &block)
-          id, options = parse_args(id_or_options, options)
-          paginate "clubs/#{id}/group_events", options, Strava::Models::ClubEvent, &block
-        end
-
-        #
-        # List club administrators.
+        # List logged-in athlete clubs.
         #
-        # @option options [String] :id
-        #   Club id.
         # @option options [Integer] :page
         #   Page number.
         # @option options [Integer] :per_page
         #   Number of items per page. Defaults to 30.
         #
-        def club_admins(id_or_options, options = {}, &block)
-          id, options = parse_args(id_or_options, options)
-          paginate "clubs/#{id}/admins", options, Strava::Models::ClubAthlete, &block
+        def athlete_clubs(options = {}, &block)
+          paginate 'athlete/clubs', options, Strava::Models::SummaryClub, &block
         end
 
         #
         # Get club.
         #
-        # @option options [String] :id
-        #   Club id.
+        # @param id_or_options [String, Integer, Hash] Either a club ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def club(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)
@@ -61,30 +40,16 @@ module Strava
         end
 
         #
-        # List club members.
+        # List club / group events.
         #
-        # @option options [String] :id
-        #   Club id.
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
+        # @param id_or_options [String, Integer, Hash] Either a club ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
+        # @option options [Integer] :page Page number
+        # @option options [Integer] :per_page Number of items per page. Defaults to 30
         #
-        def club_members(id_or_options, options = {}, &block)
+        def club_events(id_or_options, options = {}, &block)
           id, options = parse_args(id_or_options, options)
-          paginate "clubs/#{id}/members", options, Strava::Models::ClubAthlete, &block
-        end
-
-        #
-        # List logged-in athlete clubs.
-        #
-        # @option options [Integer] :page
-        #   Page number.
-        # @option options [Integer] :per_page
-        #   Number of items per page. Defaults to 30.
-        #
-        def athlete_clubs(options = {}, &block)
-          paginate 'athlete/clubs', options, Strava::Models::SummaryClub, &block
+          paginate "clubs/#{id}/group_events", options, Strava::Models::ClubEvent, &block
         end
       end
     end

data/lib/strava/api/endpoints/gears.rb

@@ -3,12 +3,21 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for Strava gears.
+      #
+      # Gears (also known as equipment) represent bikes and shoes used by athletes in
+      # their activities. Gears track usage statistics like total distance and can be
+      # associated with specific activities.
+      #
+      # @see https://developers.strava.com/docs/reference/#api-Gears
+      #
       module Gears
         #
         # Returns an equipment using its identifier.
         #
-        # @option options [String] :id
-        #   Gear id.
+        # @param id_or_options [String, Integer, Hash] Either a gear ID or a hash of options including :id
+        # @param options [Hash] Additional options (if first parameter is an ID)
         #
         def gear(id_or_options, options = {})
           id, options = parse_args(id_or_options, options)

data/lib/strava/api/endpoints/oauth.rb

@@ -3,10 +3,55 @@
 module Strava
   module Api
     module Endpoints
+      #
+      # API endpoints for OAuth operations.
+      #
+      # OAuth endpoints provide functionality for managing OAuth access tokens,
+      # including the ability to revoke an athlete's access token and deauthorize
+      # an application's access to their data.
+      #
+      # @see https://developers.strava.com/docs/authentication/
+      #
       module OAuth
         #
         # Revoke access to an athlete's data.
         #
+        # Revokes the athlete's access token. After calling this method, the
+        # access token will no longer be valid and the athlete will need to
+        # reauthorize the application.
+        #
+        # @param options [Hash] Additional options for the revocation request
+        #
+        # @return [Authorization] Authorization response with revocation confirmation
+        #
+        # @example Revoke access for the current athlete
+        #   client.revoke
+        #
+        # @see https://developers.strava.com/docs/authentication/#deauthorization
+        #
+        def revoke(options = {})
+          Strava::Models::Authorization.new(post('revoke', { endpoint: Strava::OAuth.config.endpoint }.merge(options)))
+        end
+
+        #
+        # Revoke access to an athlete's data.
+        #
+        # Deauthorizes the application and revokes the athlete's access token.
+        # After calling this method, the access token will no longer be valid
+        # and the athlete will need to reauthorize the application.
+        #
+        # @param options [Hash] Additional options for the deauthorization request
+        #
+        # @return [Authorization] Authorization response with revocation confirmation
+        #
+        # @example Deauthorize the current athlete
+        #   client.deauthorize
+        #
+        # @deprecated Use {#revoke} instead. The `oauth/deauthorize` endpoint will
+        #   be retired on June 1, 2027 in favor of the new `oauth/revoke` endpoint.
+        #
+        # @see https://developers.strava.com/docs/authentication/#deauthorization
+        #
         def deauthorize(options = {})
           Strava::Models::Authorization.new(post('deauthorize', { endpoint: Strava::OAuth.config.endpoint }.merge(options)))
         end