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

data/lib/strava/web/raise_response_error.rb

@@ -2,10 +2,41 @@
 
 module Strava
   module Web
+    #
+    # Faraday middleware that raises exceptions for HTTP error responses.
+    #
+    # This middleware intercepts HTTP responses and raises appropriate exceptions
+    # based on the status code. It handles common HTTP error statuses and maps them
+    # to specific Strava error classes, including special handling for rate limiting
+    # (429) and resource not found (404) responses.
+    #
+    # @see Faraday::Middleware
+    # @see Strava::Errors::Fault
+    # @see Strava::Errors::RatelimitError
+    #
     class RaiseResponseError < ::Faraday::Middleware
+      # @return [Hash] Default options inherited from Faraday's RaiseError middleware
       DEFAULT_OPTIONS = Faraday::Response::RaiseError::DEFAULT_OPTIONS
+
+      # @return [Range] HTTP status codes that are considered client errors (400-599)
       CLIENT_ERROR_STATUSES = (400...600)
 
+      #
+      # Callback invoked when an HTTP response is complete.
+      #
+      # Examines the HTTP status code and raises appropriate exceptions:
+      # - 404: Faraday::ResourceNotFound
+      # - 407: Faraday::ConnectionFailed (proxy authentication required)
+      # - 429: Strava::Errors::RatelimitError (rate limit exceeded)
+      # - 400-599: Strava::Errors::Fault (general client/server errors)
+      #
+      # @param env [Faraday::Env] The Faraday request/response environment
+      # @raise [Faraday::ResourceNotFound] When resource is not found (404)
+      # @raise [Faraday::ConnectionFailed] When proxy authentication fails (407)
+      # @raise [Strava::Errors::RatelimitError] When rate limit is exceeded (429)
+      # @raise [Strava::Errors::Fault] For other client/server errors (400-599)
+      # @return [void]
+      #
       def on_complete(env)
         case env[:status]
         when 404
@@ -20,6 +51,16 @@ module Strava
         end
       end
 
+      #
+      # Extracts response values from the Faraday environment.
+      #
+      # Builds a hash containing response information (status, headers, body)
+      # and optionally includes request details if the middleware is configured
+      # with `include_request: true`.
+      #
+      # @param env [Faraday::Env] The Faraday request/response environment
+      # @return [Hash] Response values including status, headers, body, and optionally request details
+      #
       def response_values(env)
         response = {
           status: env.status,
@@ -43,6 +84,12 @@ module Strava
         )
       end
 
+      #
+      # Extracts and decodes query parameters from the request URL.
+      #
+      # @param env [Faraday::Env] The Faraday request/response environment
+      # @return [Hash] Decoded query parameters
+      #
       def query_params(env)
         env.request.params_encoder ||= Faraday::Utils.default_params_encoder
         env.params_encoder.decode(env.url.query)

data/lib/strava/web/request.rb

@@ -2,25 +2,81 @@
 
 module Strava
   module Web
+    #
+    # HTTP request methods for Strava web clients.
+    #
+    # This module provides GET, POST, PUT, and DELETE HTTP methods for making
+    # requests to Strava APIs. All methods return a wrapped response object
+    # that provides easy access to response data and metadata.
+    #
+    # @api private
+    #
     module Request
+      #
+      # Perform an HTTP GET request.
+      #
+      # @param path [String] The API path (relative to endpoint)
+      # @param options [Hash] Query parameters and options
+      #
+      # @return [Strava::Web::Response] Wrapped HTTP response
+      #
       def get(path, options = {})
         request(:get, path, options)
       end
 
+      #
+      # Perform an HTTP POST request.
+      #
+      # @param path [String] The API path (relative to endpoint)
+      # @param options [Hash] Request body parameters and options
+      #
+      # @return [Strava::Web::Response] Wrapped HTTP response
+      #
       def post(path, options = {})
         request(:post, path, options)
       end
 
+      #
+      # Perform an HTTP PUT request.
+      #
+      # @param path [String] The API path (relative to endpoint)
+      # @param options [Hash] Request body parameters and options
+      #
+      # @return [Strava::Web::Response] Wrapped HTTP response
+      #
       def put(path, options = {})
         request(:put, path, options)
       end
 
+      #
+      # Perform an HTTP DELETE request.
+      #
+      # @param path [String] The API path (relative to endpoint)
+      # @param options [Hash] Query parameters and options
+      #
+      # @return [Strava::Web::Response] Wrapped HTTP response
+      #
       def delete(path, options = {})
         request(:delete, path, options)
       end
 
       private
 
+      #
+      # Executes an HTTP request with the specified method.
+      #
+      # Constructs the full URL from the endpoint and path, sends the request
+      # using Faraday, and wraps the response in a Strava::Web::Response object.
+      #
+      # @api private
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+      # @param path [String] The API path (relative to endpoint)
+      # @param options [Hash] Request parameters and options
+      # @option options [String] :endpoint Override the default endpoint URL
+      # @option options [Hash] :request Faraday request options (timeouts, etc.)
+      #
+      # @return [Strava::Web::Response] Wrapped HTTP response
+      #
       def request(method, path, options)
         options = options.dup if options.key?(:request) || options.key?(:endpoint)
         root = options.delete(:endpoint) || endpoint

data/lib/strava/web/response.rb

@@ -75,6 +75,17 @@ module Strava
         end
       end
 
+      #
+      # Delegates missing methods to the response body or array.
+      #
+      # If the response is an array, delegates methods to the array.
+      # Otherwise, delegates to the response body hash, allowing access
+      # to response fields as if they were methods.
+      #
+      # @param method_symbol [Symbol] The method name to forward
+      # @param args [Array] Arguments to pass to the method
+      # @return [Object] Result from the delegated method
+      #
       def method_missing(method_symbol, ...)
         case @response
         when Array
@@ -84,6 +95,13 @@ module Strava
         end
       end
 
+      #
+      # Checks if the response body or array responds to a method.
+      #
+      # @param method_name [Symbol] The method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] true if the response responds to the method
+      #
       def respond_to_missing?(method_name, include_private = false)
         super
       end

data/lib/strava/webhooks/client.rb

@@ -2,9 +2,49 @@
 
 module Strava
   module Webhooks
+    #
+    # Webhooks client for Strava push subscriptions.
+    #
+    # Strava provides webhooks for receiving real-time updates about athlete activities
+    # and other events. This client manages webhook subscriptions (create, list, delete).
+    #
+    # Before creating a subscription, you must implement an HTTP endpoint that:
+    # 1. Handles GET requests for subscription validation (Challenge)
+    # 2. Handles POST requests for webhook events (Event)
+    #
+    # @example Create and manage a webhook subscription
+    #   client = Strava::Webhooks::Client.new(
+    #     client_id: "your_client_id",
+    #     client_secret: "your_client_secret"
+    #   )
+    #
+    #   # Create subscription
+    #   subscription = client.create_push_subscription(
+    #     callback_url: 'https://myapp.com/strava/webhook',
+    #     verify_token: 'my_verify_token'
+    #   )
+    #
+    #   # List subscriptions
+    #   subscriptions = client.push_subscriptions
+    #
+    #   # Delete subscription
+    #   client.delete_push_subscription(subscription.id)
+    #
+    # @see https://developers.strava.com/docs/webhooks/
+    # @see Strava::Webhooks::Models::Challenge
+    # @see Strava::Webhooks::Models::Event
+    #
     class Client < Strava::Web::Client
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Initialize a new Webhooks client.
+      #
+      # @param [Hash] options Configuration options
+      # @option options [String] :client_id Strava application client ID (required)
+      # @option options [String] :client_secret Strava application client secret (required)
+      # @option options [String] :endpoint API endpoint URL (defaults to https://www.strava.com/api/v3)
+      #
       def initialize(options = {})
         Strava::Webhooks::Config::ATTRIBUTES.each do |key|
           send("#{key}=", options[key] || Strava::Webhooks.config.send(key))
@@ -17,7 +57,20 @@ module Strava
       end
 
       #
-      # Get existing push subscriptions.
+      # List existing push subscriptions.
+      #
+      # Returns all active webhook subscriptions for your application.
+      # Typically, Strava only allows one subscription per application.
+      #
+      # @param [Hash] options Additional options
+      #
+      # @return [Array<Strava::Webhooks::Models::Subscription>] Array of subscriptions
+      #
+      # @example List subscriptions
+      #   subscriptions = client.push_subscriptions
+      #   subscriptions.each { |sub| puts "ID: #{sub.id}, URL: #{sub.callback_url}" }
+      #
+      # @see https://developers.strava.com/docs/webhooks/
       #
       def push_subscriptions(options = {})
         get('push_subscriptions', options).map do |row|
@@ -26,7 +79,20 @@ module Strava
       end
 
       #
-      # Delete an existing push subscription.
+      # Delete a push subscription.
+      #
+      # Removes an existing webhook subscription by ID. After deletion,
+      # your application will no longer receive webhook events.
+      #
+      # @param [Integer, Hash] id_or_options Subscription ID or options hash with :id key
+      # @param [Hash] options Additional options
+      #
+      # @return [nil]
+      #
+      # @example Delete subscription
+      #   client.delete_push_subscription(12345)
+      #
+      # @see https://developers.strava.com/docs/webhooks/
       #
       def delete_push_subscription(id_or_options, options = {})
         id, options = parse_args(id_or_options, options)
@@ -35,22 +101,57 @@ module Strava
       end
 
       #
-      # Create a subscription.
+      # Create a new push subscription.
+      #
+      # Creates a webhook subscription for receiving real-time activity updates.
+      # Your callback URL must be publicly accessible and handle both GET (for validation)
+      # and POST (for events) requests.
+      #
+      # Strava will send a GET request to validate your callback URL before creating
+      # the subscription. Your endpoint must respond with the challenge token.
+      #
+      # @param [Hash] options Subscription parameters
+      # @option options [String] :callback_url Public HTTPS URL where webhook events will be sent (required)
+      # @option options [String] :verify_token Token for validating webhook challenges (required)
+      #
+      # @return [Strava::Webhooks::Models::Subscription] The created subscription
+      #
+      # @example Create subscription
+      #   subscription = client.create_push_subscription(
+      #     callback_url: 'https://myapp.com/strava/webhook',
+      #     verify_token: 'my_secret_token_123'
+      #   )
+      #   puts "Subscription ID: #{subscription.id}"
       #
-      # @option options [String] :callback_url
-      #   Address where webhook events will be sent.
-      # @option options [String] :verify_token
-      #   String chosen by the application owner for client security. An identical string should be returned by Strava's subscription service.
+      # @see https://developers.strava.com/docs/webhooks/
+      # @see Strava::Webhooks::Models::Challenge
       #
       def create_push_subscription(options = {})
         Strava::Webhooks::Models::Subscription.new(post('push_subscriptions', options))
       end
 
       class << self
+        #
+        # Configure the Webhooks client with a block.
+        #
+        # @yield [Config] Yields the configuration module for setup
+        # @return [Module] The Config module
+        #
+        # @example
+        #   Strava::Webhooks::Client.configure do |config|
+        #     config.client_id = ENV['STRAVA_CLIENT_ID']
+        #     config.client_secret = ENV['STRAVA_CLIENT_SECRET']
+        #   end
+        #
         def configure
           block_given? ? yield(Config) : Config
         end
 
+        #
+        # Returns the current Webhooks client configuration.
+        #
+        # @return [Module] The Config module
+        #
         def config
           Config
         end

data/lib/strava/webhooks/config.rb

@@ -2,9 +2,28 @@
 
 module Strava
   module Webhooks
+    #
+    # Configuration module for the Webhooks client.
+    #
+    # This module manages webhook-specific configuration settings including the
+    # API endpoint URL and application credentials (client ID and secret) required
+    # for managing webhook subscriptions.
+    #
+    # Webhooks allow your application to receive real-time notifications when
+    # athletes create new activities or update their profile information.
+    #
+    # @example Configure Webhooks client
+    #   Strava::Webhooks.configure do |config|
+    #     config.client_id = ENV['STRAVA_CLIENT_ID']
+    #     config.client_secret = ENV['STRAVA_CLIENT_SECRET']
+    #   end
+    #
+    # @see https://developers.strava.com/docs/webhooks/
+    #
     module Config
       extend self
 
+      # @return [Array<Symbol>] List of configurable webhook attributes
       ATTRIBUTES = %i[
         endpoint
         client_id
@@ -13,6 +32,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 client credentials.
+      #
+      # @return [void]
+      #
       def reset
         self.endpoint = 'https://www.strava.com/api/v3'
         self.client_id = nil
@@ -21,10 +48,27 @@ module Strava
     end
 
     class << self
+      #
+      # Configure the Webhooks client with a block.
+      #
+      # @yield [Config] Yields the configuration module for setup
+      # @return [Module] The Config module
+      #
+      # @example
+      #   Strava::Webhooks.configure do |config|
+      #     config.client_id = '12345'
+      #     config.client_secret = 'your_client_secret'
+      #   end
+      #
       def configure
         block_given? ? yield(Config) : Config
       end
 
+      #
+      # Returns the current Webhooks configuration.
+      #
+      # @return [Module] The Config module
+      #
       def config
         Config
       end

data/lib/strava/webhooks/models/challenge.rb

@@ -3,11 +3,51 @@
 module Strava
   module Webhooks
     module Models
+      #
+      # Represents a webhook subscription validation challenge.
+      #
+      # When creating a webhook subscription, Strava sends a GET request to your
+      # callback URL with challenge parameters. Your application must validate the
+      # verify_token and respond with the challenge value.
+      #
+      # @example Handle webhook challenge in Rails
+      #   def webhook
+      #     if request.get?
+      #       challenge = Strava::Webhooks::Models::Challenge.new(request.query_parameters)
+      #       if challenge.verify_token == ENV['STRAVA_VERIFY_TOKEN']
+      #         render json: challenge.response
+      #       else
+      #         head :forbidden
+      #       end
+      #     end
+      #   end
+      #
+      # @example Handle challenge in Sinatra
+      #   get '/webhook' do
+      #     challenge = Strava::Webhooks::Models::Challenge.new(params)
+      #     halt 403 unless challenge.verify_token == ENV['STRAVA_VERIFY_TOKEN']
+      #     content_type :json
+      #     challenge.response.to_json
+      #   end
+      #
+      # @see Strava::Webhooks::Client#create_push_subscription
+      # @see https://developers.strava.com/docs/webhooks/
+      #
       class Challenge < Hashie::Trash
+        # @return [String] Subscription mode, typically "subscribe"
         property 'mode', from: 'hub.mode'
+
+        # @return [String] Verification token to validate the request
         property 'verify_token', from: 'hub.verify_token'
+
+        # @return [String] Challenge value that must be echoed back
         property 'challenge', from: 'hub.challenge'
 
+        #
+        # Returns the response hash that should be sent back to Strava.
+        #
+        # @return [Hash] Response containing the challenge value
+        #
         def response
           { 'hub.challenge' => challenge }
         end

data/lib/strava/webhooks/models/event.rb

@@ -3,13 +3,63 @@
 module Strava
   module Webhooks
     module Models
+      #
+      # Represents a webhook event from Strava.
+      #
+      # After successfully creating a webhook subscription, Strava will send POST
+      # requests to your callback URL when activity events occur. Events include
+      # activity creation, updates, and deletions.
+      #
+      # @example Handle webhook event in Rails
+      #   def webhook
+      #     if request.post?
+      #       event = Strava::Webhooks::Models::Event.new(JSON.parse(request.body.read))
+      #
+      #       case event.object_type
+      #       when 'activity'
+      #         case event.aspect_type
+      #         when 'create'
+      #           # Fetch and process the new activity
+      #           activity = client.activity(event.id)
+      #           process_new_activity(activity)
+      #         when 'update'
+      #           # Handle activity update
+      #           puts "Activity #{event.id} updated: #{event.updates.inspect}"
+      #         when 'delete'
+      #           # Handle activity deletion
+      #           delete_activity(event.id)
+      #         end
+      #       when 'athlete'
+      #         # Handle athlete updates (authorization revoked, etc.)
+      #       end
+      #
+      #       head :ok
+      #     end
+      #   end
+      #
+      # @see Strava::Webhooks::Client#create_push_subscription
+      # @see https://developers.strava.com/docs/webhooks/
+      #
       class Event < Hashie::Trash
+        # @return [String] Type of object (e.g., "activity", "athlete")
         property 'object_type'
+
+        # @return [Integer] ID of the object (activity ID, athlete ID, etc.)
         property 'id', from: 'object_id'
+
+        # @return [String] Type of event: "create", "update", or "delete"
         property 'aspect_type'
+
+        # @return [Hash] Map of updated properties (only for update events)
         property 'updates'
+
+        # @return [Integer] Athlete ID who owns the object
         property 'owner_id'
+
+        # @return [Integer] ID of the webhook subscription
         property 'subscription_id'
+
+        # @return [Time] Timestamp when the event occurred
         property 'event_time', transform_with: ->(v) { Time.at(v) }
       end
     end

data/lib/strava/webhooks/models/subscription.rb

@@ -3,12 +3,39 @@
 module Strava
   module Webhooks
     module Models
+      #
+      # Represents a webhook subscription.
+      #
+      # Webhook subscriptions allow your application to receive real-time notifications
+      # when athletes create or update activities, or update their profile information.
+      # Each subscription is associated with a callback URL where events will be posted.
+      #
+      # @example List subscriptions
+      #   subscriptions = client.subscriptions
+      #   subscriptions.each do |sub|
+      #     puts "Subscription #{sub.id}: #{sub.callback_url}"
+      #   end
+      #
+      # @see Strava::Webhooks::Client
+      # @see https://developers.strava.com/docs/webhooks/
+      #
       class Subscription < Strava::Models::Response
+        # @return [Integer] The subscription ID
         property 'id'
+
+        # @return [Integer] The ID of the application that created the subscription
         property 'application_id'
+
+        # @return [String] The callback URL where webhook events will be posted
         property 'callback_url'
+
+        # @return [Integer] Resource state indicator
         property 'resource_state'
+
+        # @return [Time] When the subscription was created
         property 'created_at', transform_with: ->(v) { Time.parse(v) }
+
+        # @return [Time] When the subscription was last updated
         property 'updated_at', transform_with: ->(v) { Time.parse(v) }
       end
     end

data/lib/strava-ruby-client.rb

@@ -44,8 +44,6 @@ require_relative 'strava/models/activity_stats'
 require_relative 'strava/models/activity_total'
 require_relative 'strava/models/activity_zone'
 require_relative 'strava/models/base_stream'
-require_relative 'strava/models/club_activity'
-require_relative 'strava/models/club_athlete'
 require_relative 'strava/models/club_event'
 require_relative 'strava/models/comment'
 require_relative 'strava/models/destination'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strava-ruby-client
 version: !ruby/object:Gem::Version
-  version: 3.0.0.pre.2
+  version: 3.1.0
 platform: ruby
 authors:
 - Daniel Doubrovkine
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-22 00:00:00.000000000 Z
+date: 2026-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -108,8 +108,6 @@ files:
 - lib/strava/models/activity_zone.rb
 - lib/strava/models/authorization.rb
 - lib/strava/models/base_stream.rb
-- lib/strava/models/club_activity.rb
-- lib/strava/models/club_athlete.rb
 - lib/strava/models/club_event.rb
 - lib/strava/models/comment.rb
 - lib/strava/models/destination.rb

data/lib/strava/models/club_activity.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Strava
-  module Models
-    # https://developers.strava.com/docs/reference/#api-models-ClubActivity
-    class ClubActivity < Strava::Models::Response
-      include Mixins::ElevationGain
-      include Mixins::SportType
-
-      property 'athlete', transform_with: ->(v) { Strava::Models::MetaAthlete.new(v) }
-      property 'name'
-      include Mixins::Distance
-      include Mixins::MovingTime
-      include Mixins::ElapsedTime
-      include Mixins::TotalElevationGain
-      include Mixins::SportType
-      property 'workout_type'
-      # undocumented
-      property 'resource_state'
-    end
-  end
-end

data/lib/strava/models/club_athlete.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Strava
-  module Models
-    # https://developers.strava.com/docs/reference/#api-models-ClubAthlete
-    class ClubAthlete < Strava::Models::Response
-      property 'resource_state'
-      property 'firstname'
-      property 'lastname'
-      property 'member'
-      property 'admin'
-      property 'owner'
-      # undocumented
-      property 'membership'
-
-      def name
-        [firstname, lastname].compact.join(' ') if firstname || lastname
-      end
-    end
-  end
-end