strava-ruby-client 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac773d592190518ab62b3e5d9065493c6809bc5013e04a7fb93a659d040776ca
-  data.tar.gz: 19b6778e3e80bde45c38b67ce40296788d9a347dc90728a2c75f0a1cc7a85f2b
+  metadata.gz: bf4db074212670b76d6bd8045add5f2bfa1232ba0cf81fdf7ba66b8f0bb20f94
+  data.tar.gz: 78f72488ee23a2add7d9167b455eae14fd908cba008dc3fa7ee4cfcf2380c12a
 SHA512:
-  metadata.gz: 5103a4e4c8cf34590ce701ab6cdc2586e4869f4b72e5dce68c8270c2c54e2beacaed12dcbfee5f9640e8b88b8ee2e9acca5342e1d45b07103f4daa82273d1f57
-  data.tar.gz: e33ff02a4ce9fc464a647778c4c724f71574838d5a3d81a961f87dea8da545de5dd980cb78c1a301bf179bc92b521f9f2183af8b2dbf97f5718afb335c1adda9
+  metadata.gz: 7af3b537e12f45ddd344ee1d059a43f667372481fb1c5e781510fb07f9bd6ab2443ea74bdc1e1f24a3a79467da8743aed973fc7c757f72f0c37b2e9347d74635
+  data.tar.gz: a925ee0ea3e3e056b4ae08d39e46fa6209a7279a4124c7b9a4184fa55ae59b808ce592271eeff11608dec0cb9ef81e9d85947880cf124a8b72bdc2a139b1b5b3

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+### 3.1.0 (2026/08/29)
+
+* [#110](https://github.com/dblock/strava-ruby-client/pull/110): Removes `club_activities`, `club_members`, and `club_admins`, which Strava retired on September 1, 2026 - [@dblock](https://github.com/dblock), [@Copilot](https://github.com/apps/copilot-swe-agent).
+* [#100](https://github.com/dblock/strava-ruby-client/pull/100): Adds comprehensive rdoc documentation - [@dblock](https://github.com/dblock).
+* [#103](https://github.com/dblock/strava-ruby-client/pull/103): Migrate Danger to use the `danger-pr-comment` reusable workflow - [@dblock](https://github.com/dblock), [@Copilot](https://github.com/apps/copilot-swe-agent).
+* [#104](https://github.com/dblock/strava-ruby-client/pull/104): Fixes `Danger Comment` workflow failing with a `contents: none` permissions error - [@dblock](https://github.com/dblock).
+* [#102](https://github.com/dblock/strava-ruby-client/pull/102): Adds `revoke`, deprecating `deauthorize`, per Strava's June 2026/2027 developer program changes - [@dblock](https://github.com/dblock).
+* [#105](https://github.com/dblock/strava-ruby-client/pull/105): Adds `total_elevation_gain`, `total_elevation_loss` and formatted helpers to `Strava::Models::Stream`, computed from altitude stream data - [@dblock](https://github.com/dblock).
+* [#106](https://github.com/dblock/strava-ruby-client/pull/106): Adds test coverage reporting with [coveralls.io](https://coveralls.io) - [@dblock](https://github.com/dblock).
+* [#108](https://github.com/dblock/strava-ruby-client/pull/108): Adds an integration test that verifies the real Strava API endpoint is reachable, run in CI on every push and pull request via `rake spec:integration` - [@dblock](https://github.com/dblock).
+* [#107](https://github.com/dblock/strava-ruby-client/pull/107): Fixes `explore_segments` and `star_segment` raising `UncaughtThrowError` instead of `ArgumentError` for missing required arguments - [@dblock](https://github.com/dblock).
+* [#107](https://github.com/dblock/strava-ruby-client/pull/107): Fixes `start_date_local` to always derive the timezone offset from the difference between `start_date` and `start_date_local`, since Strava's `timezone` property does not account for daylight saving time - [@dblock](https://github.com/dblock).
+* [#109](https://github.com/dblock/strava-ruby-client/pull/109): Fixed coverage reporting to Coveralls not running on pull requests, and to report coverage from every Ruby/JRuby test matrix job merged into a single build, by switching from `coveralls_reborn`/`COVERALLS_REPO_TOKEN` to `coverallsapp/github-action`/`GITHUB_TOKEN` - [@dblock](https://github.com/dblock).
+
 ### 3.0.0 (2025/10/24)
 
 * [#96](https://github.com/dblock/strava-ruby-client/pull/96): Updates and refactors models to spec - [@dblock](https://github.com/dblock).

data/README.md

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/strava-ruby-client.svg)](https://badge.fury.io/rb/strava-ruby-client)
 [![Test](https://github.com/dblock/strava-ruby-client/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/dblock/strava-ruby-client/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/github/dblock/strava-ruby-client/badge.svg?branch=master)](https://coveralls.io/github/dblock/strava-ruby-client?branch=master)
 
 A complete Ruby client for the [Strava API v3](https://developers.strava.com).
 
@@ -27,12 +28,9 @@ Unlike other clients, including [strava-api-v3](https://github.com/jaredholdcrof
     - [Get Athlete Stats](#get-athlete-stats)
     - [Update Athlete](#update-athlete)
   - [Clubs](#clubs)
-    - [List Club Activities](#list-club-activities)
-    - [List Club Events](#list-club-events)
-    - [List Club Administrators](#list-club-administrators)
-    - [Get Club](#get-club)
-    - [List Club Members](#list-club-members)
     - [List Athlete Clubs](#list-athlete-clubs)
+    - [Get Club](#get-club)
+    - [List Club Events](#list-club-events)
   - [Gears](#gears)
     - [Get Equipment](#get-equipment)
   - [Routes](#routes)
@@ -58,6 +56,7 @@ Unlike other clients, including [strava-api-v3](https://github.com/jaredholdcrof
   - [Pagination](#pagination)
   - [OAuth](#oauth)
     - [OAuth Workflow](#oauth-workflow)
+    - [Revoke](#revoke)
     - [Deauthorize](#deauthorize)
     - [Command Line OAuth Workflow](#command-line-oauth-workflow)
   - [Webhooks](#webhooks)
@@ -381,46 +380,22 @@ See [Strava::Models::DetailedAthlete](lib/strava/models/detailed_athlete.rb) for
 
 ### Clubs
 
-#### List Club Activities
-
-Retrieve recent activities from members of a specific club.
+Strava removed the Club Activities, Club Members, and Club Admins endpoints on September 1, 2026 (see the [Strava API changelog](https://developers.strava.com/docs/changelog/)). The corresponding `club_activities`, `club_members`, and `club_admins` methods have been removed from this gem.
 
-```ruby
-activities = client.club_activities(108605) # => Array[Strava::Models::ClubActivity]
-
-activity = activities.first # => Strava::Models::ClubActivity
-
-activity.name # => 'Afternoon Run'
-```
-
-See [Strava::Models::ClubActivity](lib/strava/models/club_activity.rb) for all available properties. Note that Strava does not return activity or athlete ID via this API.
-
-#### List Club Events
+#### List Athlete Clubs
 
-Retrieve recent Events from a specific club.
+Returns a list of the clubs whose membership includes the authenticated athlete.
 
 ```ruby
-events = client.club_events(108605) # => Array[Strava::Models::ClubEvent]
-
-event = events.first # => Strava::Models::ClubEvent
-
-event.title # => 'First Group Event Ever! Yippieh!'
-```
-
-See [Strava::Models::ClubEvent](lib/strava/models/club_event.rb) for all available properties.
-
-#### List Club Administrators
-
-Returns a list of the administrators of a given club.
+clubs = client.athlete_clubs # => Array[Strava::Models::SummaryClub]
 
-```ruby
-admins = client.club_admins(108605) # => Array[Strava::Models::ClubAthlete]
+club = clubs.first # => Strava::Models::SummaryClub
 
-admin = admins.first # => Strava::Models::ClubAthlete
-admin.name # => 'Peter Ciaccia'
+activity.name # => 'NYRR'
+activity.strava_url # => 'https://www.strava.com/clubs/nyrr'
 ```
 
-See [Strava::Models::ClubAthlete](lib/strava/models/club_athlete.rb) for all available properties.
+See [Strava::Models::SummaryClub](lib/strava/models/summary_club.rb) for all available properties.
 
 #### Get Club
 
@@ -434,33 +409,19 @@ club.name # => 'NYRR'
 
 See [Strava::Models::DetailedClub](lib/strava/models/detailed_club.rb) for all available properties.
 
-#### List Club Members
-
-Returns a list of the members of a given club.
-
-```ruby
-members = client.club_members(108605) # => Array[Strava::Models::ClubAthlete]
-
-member = members.first # => Strava::Models::ClubAthlete
-member.name # => 'Peter Ciaccia'
-```
-
-See [Strava::Models::ClubAthlete](lib/strava/models/club_athlete.rb) for all available properties.
-
-#### List Athlete Clubs
+#### List Club Events
 
-Returns a list of the clubs whose membership includes the authenticated athlete.
+Retrieve recent Events from a specific club.
 
 ```ruby
-clubs = client.athlete_clubs # => Array[Strava::Models::SummaryClub]
+events = client.club_events(108605) # => Array[Strava::Models::ClubEvent]
 
-club = clubs.first # => Strava::Models::SummaryClub
+event = events.first # => Strava::Models::ClubEvent
 
-activity.name # => 'NYRR'
-activity.strava_url # => 'https://www.strava.com/clubs/nyrr'
+event.title # => 'First Group Event Ever! Yippieh!'
 ```
 
-See [Strava::Models::SummaryClub](lib/strava/models/summary_club.rb) for all available properties.
+See [Strava::Models::ClubEvent](lib/strava/models/club_event.rb) for all available properties.
 
 ### Gears
 
@@ -683,6 +644,17 @@ streams.latlng # => Strava::Models::Stream
 streams.altitude # => Strava::Models::Stream
 ```
 
+The Strava API doesn't return a total elevation loss (descent) property for streams, but it can be computed from an altitude stream's data.
+
+```ruby
+streams = client.activity_streams(1946417534, keys: %w[altitude]) # => Strava::Models::StreamSet
+
+streams.altitude.total_elevation_gain # => 725.3
+streams.altitude.total_elevation_loss # => 680.1
+streams.altitude.total_elevation_gain_s # => "725.3m"
+streams.altitude.total_elevation_loss_s # => "680.1m"
+```
+
 #### Get Activity Streams
 
 Returns the given activity's streams.
@@ -871,6 +843,16 @@ response.refresh_token # => String, new refresh token
 response.expires_at # => Time, new timestamp when the access token expires
 ```
 
+#### Revoke
+
+Revoke access to an athlete's data using an instance of `Strava::API::Client`.
+
+```ruby
+authorization = client.revoke
+
+authorization.access_token # => String, access token being revoked
+```
+
 #### Deauthorize
 
 Revoke access to an athlete's data using an instance of `Strava::API::Client`.
@@ -881,6 +863,8 @@ authorization = client.deauthorize
 authorization.access_token # => String, access token being revoked
 ```
 
+_Deprecated: use [`revoke`](#revoke) instead. The `oauth/deauthorize` endpoint will be retired on June 1, 2027 in favor of `oauth/revoke`._
+
 #### Command Line OAuth Workflow
 
 The OAuth process is web-based and you cannot obtain a token from a Strava client ID and secret without user intervention. You can, however, start a local web server to handle the OAuth redirect and open a browser from the command-line.

data/lib/strava/api/client.rb

@@ -2,6 +2,33 @@
 
 module Strava
   module Api
+    #
+    # Main API client for interacting with the Strava API v3.
+    #
+    # This class provides a complete Ruby interface to the Strava API, including support for:
+    # * Activities (create, read, update, list)
+    # * Athletes (profile, stats, zones)
+    # * Clubs (details, members, activities)
+    # * Gear (equipment details)
+    # * Routes (details, GPX/TCX export)
+    # * Segments and Segment Efforts
+    # * Streams (activity, route, segment data)
+    # * Uploads (activity file uploads)
+    # * OAuth (token refresh, deauthorization)
+    #
+    # @example Create a client with an access token
+    #   client = Strava::Api::Client.new(access_token: "your_access_token")
+    #   athlete = client.athlete
+    #   activities = client.athlete_activities(per_page: 10)
+    #
+    # @example Configure globally
+    #   Strava::Api::Client.configure do |config|
+    #     config.access_token = "your_access_token"
+    #   end
+    #   client = Strava::Api::Client.new
+    #
+    # @see https://developers.strava.com/docs/reference/ Strava API Documentation
+    #
     class Client < Strava::Web::Client
       include Endpoints::Activities
       include Endpoints::Athletes
@@ -16,6 +43,26 @@ module Strava
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Initialize a new API client.
+      #
+      # @param [Hash] options Configuration options for the client
+      # @option options [String] :access_token OAuth access token for API authentication (required)
+      # @option options [String] :endpoint API endpoint URL (defaults to https://www.strava.com/api/v3)
+      # @option options [String] :user_agent User agent string for HTTP requests
+      # @option options [Logger] :logger Logger instance for request/response logging
+      # @option options [Integer] :timeout HTTP request timeout in seconds
+      # @option options [Integer] :open_timeout HTTP connection timeout in seconds
+      # @option options [String] :proxy HTTP proxy URL
+      # @option options [String] :ca_path Path to SSL CA certificates
+      # @option options [String] :ca_file Path to SSL CA certificate file
+      #
+      # @example
+      #   client = Strava::Api::Client.new(
+      #     access_token: "your_access_token",
+      #     user_agent: "My Strava App/1.0"
+      #   )
+      #
       def initialize(options = {})
         Config::ATTRIBUTES.each do |key|
           send("#{key}=", options[key] || Strava::Api.config.send(key))
@@ -23,15 +70,37 @@ module Strava
         super
       end
 
+      #
+      # Returns HTTP headers for API requests.
+      #
+      # @return [Hash] Headers including OAuth bearer token authorization
+      # @api private
+      #
       def headers
         { 'Authorization' => "Bearer #{access_token}" }
       end
 
       class << self
+        #
+        # Configure the API client globally.
+        #
+        # @yield [Config] Configuration object
+        # @return [Strava::Api::Config] Configuration object
+        #
+        # @example
+        #   Strava::Api::Client.configure do |config|
+        #     config.access_token = "your_access_token"
+        #   end
+        #
         def configure
           block_given? ? yield(Config) : Config
         end
 
+        #
+        # Returns the configuration object.
+        #
+        # @return [Strava::Api::Config] Configuration object
+        #
         def config
           Config
         end

data/lib/strava/api/config.rb

@@ -2,9 +2,25 @@
 
 module Strava
   module Api
+    #
+    # Configuration module for the Strava API client.
+    #
+    # This module manages configuration settings for the API client, including
+    # the API endpoint URL and access token for authentication.
+    #
+    # @example Configure the API client
+    #   Strava::Api.configure do |config|
+    #     config.access_token = 'your_access_token_here'
+    #   end
+    #
+    # @example Access current configuration
+    #   Strava::Api.config.endpoint
+    #   # => 'https://www.strava.com/api/v3'
+    #
     module Config
       extend self
 
+      # @return [Array<Symbol>] List of configurable attributes
       ATTRIBUTES = %i[
         endpoint
         access_token
@@ -12,6 +28,14 @@ module Strava
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Reset configuration to default values.
+      #
+      # Sets the endpoint to the default Strava API v3 URL and
+      # clears the access token.
+      #
+      # @return [void]
+      #
       def reset
         self.endpoint = 'https://www.strava.com/api/v3'
         self.access_token = nil
@@ -19,10 +43,26 @@ module Strava
     end
 
     class << self
+      #
+      # Configure the API client with a block.
+      #
+      # @yield [Config] Yields the configuration module for setup
+      # @return [Module] The Config module
+      #
+      # @example
+      #   Strava::Api.configure do |config|
+      #     config.access_token = ENV['STRAVA_ACCESS_TOKEN']
+      #   end
+      #
       def configure
         block_given? ? yield(Config) : Config
       end
 
+      #
+      # Returns the current API configuration.
+      #
+      # @return [Module] The Config module
+      #
       def config
         Config
       end

data/lib/strava/api/cursor.rb

@@ -2,11 +2,42 @@
 
 module Strava
   module Api
+    #
+    # Handles paginated iteration through API endpoints.
+    #
+    # This class provides an Enumerable interface for iterating through
+    # paginated API responses. It supports both traditional page-based
+    # pagination and cursor-based pagination.
+    #
+    # @see Strava::Api::Pagination
+    #
+    # @example Iterating through pages
+    #   cursor = Strava::Api::Cursor.new(client, 'athlete/activities', per_page: 30)
+    #   cursor.each do |page|
+    #     page.each do |activity|
+    #       puts activity.name
+    #     end
+    #   end
+    #
     class Cursor
       include Enumerable
 
-      attr_reader :client, :path, :params
+      # @return [Strava::Api::Client] API client instance
+      attr_reader :client
 
+      # @return [String] API endpoint path
+      attr_reader :path
+
+      # @return [Hash] Query parameters for the request
+      attr_reader :params
+
+      #
+      # Initialize a new Cursor for paginated iteration.
+      #
+      # @param client [Strava::Api::Client] API client to use for requests
+      # @param path [String] API endpoint path to paginate
+      # @param params [Hash] Query parameters (excluding :limit which is removed)
+      #
       def initialize(client, path, params = {})
         @client = client
         @path = path