strava-ruby-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd3998f1cfc79f2b07fc5ef6b9d25f8717e411c7d6a9066d6eb9e77154ea4cd1
-  data.tar.gz: 82adf5a179351b1d3b410c72710d5ce945bf5f303398e5c21e482b34ce294d95
+  metadata.gz: f8e9ff7032aba29792001ccf52b8b089cd567ad747d23ed91351e81d7c2042f7
+  data.tar.gz: d3585d62e08b3ed1217e9eb59ca0a8df476ea9a5b4bdec6834849ff3f26aef61
 SHA512:
-  metadata.gz: 05fe3b3d099ca87559a99d45b33c160a3cf378a094181b462d5a33e43dd871e451e91eba8ce3b119759206865185f28e51a24bed6be77729fc12e2d886132e1c
-  data.tar.gz: bb2b409a5e9d0f1b762f230959721c0efb23e2cfdded64a25df02a618b6f8083134854905d0a728e2f004d01ad3324c82749c75bd8c5082a2c520595afb9c672
+  metadata.gz: 9d3eae7d155dd7acfa59da08d61cde2ccc102afb4410835c3f4618aebf0652088ab67c8039ada51042d972d0a83d8096e27f61dc23bc4207a43acd2a9bee8628
+  data.tar.gz: 572b60ac371b105ff0912ad3643779e168bb44f838010e8ee70dd2cfa1d2855a137a6926b0cc6c67c14965cb8bb4ef85ace8156e0b8fb30ec56a443279f76d34

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+### 0.2.0 (2018/11/27)
+
+* Added `Strava::Api::Client#activity` with segments, photos, similar activities, trends, laps and gear - [@dblock](https://github.com/dblock).
+* Added `Activity#type_emoji` and `Activity#strava_url` - [@dblock](https://github.com/dblock).
+* Added `Athlete#name` and `Athlete#strava_url` - [@dblock](https://github.com/dblock).
+* Added `Strava::Api::Client#athlete_clubs` - [@dblock](https://github.com/dblock).
+* Added `Strava::Api::Client#club_activities` - [@dblock](https://github.com/dblock).
+* Added `Strava::Api::Client#create_activity` and `Strava::Api::Client#update_activity` - [@dblock](https://github.com/dblock).
+* Added `Strava::Api::Client#activity_comments`, `activity_kudos`, `activity_zones` and `activity_laps` - [@dblock](https://github.com/dblock).
+* Added support for converting and displaying activity distance, elevation, speed and pace - [@dblock](https://github.com/dblock).
+* [#5](https://github.com/dblock/strava-ruby-client/issues/5): Added support for pagination - [@dblock](https://github.com/dblock).
+* [#6](https://github.com/dblock/strava-ruby-client/issues/6): The `strava-oauth-token` tool has been renamed and will handle the redirect in the browser - [@dblock](https://github.com/dblock).
+
 ### 0.1.0 (2018/11/23)
 
 * Initial public release, OAuth, current Athlete and Athlete Activities - [@dblock](https://github.com/dblock).

data/README.md

@@ -6,7 +6,7 @@ Strava Ruby Client
 
 A newer Ruby client for the [Strava API v3](https://developers.strava.com).
 
-Unlike [strava-api-v3](https://github.com/jaredholdcroft/strava-api-v3) provides a first class interface to Strava models and more consistent error handling.
+Unlike [strava-api-v3](https://github.com/jaredholdcroft/strava-api-v3) provides complete OAuth refresh token flow support, a richer first class interface to Strava models, natively supports pagination and implements more consistent error handling.
 
 # Table of Contents
 
@@ -15,6 +15,16 @@ Unlike [strava-api-v3](https://github.com/jaredholdcroft/strava-api-v3) provides
   - [API](#api)
     - [Athlete](#athlete)
     - [Athlete Activities](#athlete-activities)
+    - [Athlete Clubs](#athlete-clubs)
+    - [Club Activities](#club-activities)
+    - [Create Activity](#create-activity)
+    - [Update Activity](#update-activity)
+    - [Get Activity](#get-activity)
+    - [Activity Comments](#activity-comments)
+    - [Activity Kudoers](#activity-kudoers)
+    - [Activity Laps](#activity-laps)
+    - [Activity Zones](#activity-zones)
+    - [Pagination](#pagination)
   - [OAuth](#oauth)
 - [Configuration](#configuration)
   - [Web Client Options](#web-client-options)
@@ -22,7 +32,7 @@ Unlike [strava-api-v3](https://github.com/jaredholdcroft/strava-api-v3) provides
   - [OAuth Client Options](#oauth-client-options)
 - [Errors](#errors)
 - [Tools](#tools)
-  - [OAuth Token](#oauth-token)
+  - [Strava OAuth Token](#strava-oauth-token)
 - [Contributing](#contributing)
 - [Copyright and License](#copyright-and-license)
 
@@ -40,7 +50,7 @@ Run `bundle install`.
 
 ### API
 
-Use an access token obtained from [My API Application](https://www.strava.com/settings/api) in the Strava UI, the [oauth-token tool](#oauth-token) or the [OAuth Workflow](#oauth) in your application.
+Use an access token obtained from [My API Application](https://www.strava.com/settings/api) in the Strava UI, the [strava-oauth-token tool](#strava-oauth-token) or the [OAuth Workflow](#oauth) in your application.
 
 ```ruby
 client = Strava::Api::Client.new(
@@ -63,10 +73,168 @@ See [Strava::Models::Athlete](lib/strava/models/athlete.rb) for all available pr
 Get currently logged-in athlete activities.
 
 ```ruby
-client.athlete_activities # => Array[Strava::Models::Activity]
+activities = client.athlete_activities # => Array[Strava::Models::Activity]
+
+activity = activities.first # => Strava::Models::Activity
+
+activity.name # => 'NYC TCS Marathon 2018'
+activity.strava_url # => 'https://www.strava.com/activities/1477353766'
+activity.type_emoji # => '🏃'
+activity.distance_s # => '42.2km'
+activity.moving_time_in_hours_s # => '3h38m5s'
+activity.elapsed_time_in_hours_s # => '3h42m13s'
+activity.pace_s # => '5m15s/km'
+activity.pace_per_mile_s # => '8m28s/mi'
+activity.speed_s # => '11.4km/h'
+activity.miles_per_hour_s # => '7.1mph'
+activity.total_elevation_gain_s # => '270.9m'
+activity.total_elevation_gain_in_feet_s # => '888.8ft'
 ```
 
-See [Strava::Models::Activity](lib/strava/models/activity.rb) for all available properties.
+See [Strava::Models::Activity](lib/strava/models/activity.rb), [Strava::Models::Mixins::Distance](lib/strava/models/mixins/distance.rb), [Strava::Models::Mixins::Elevation](lib/strava/models/mixins/elevation.rb) and [Strava::Models::Mixins::Time](lib/strava/models/mixins/time.rb) for all available properties.
+
+#### Athlete Clubs
+
+Get currently logged-in athlete clubs.
+
+```ruby
+clubs = client.athlete_clubs # => Array[Strava::Models::Club]
+
+club = clubs.first # => Strava::Models::Activity
+
+activity.name # => 'NYRR'
+activity.strava_url # => 'https://www.strava.com/clubs/nyrr'
+```
+
+See [Strava::Models::Club](lib/strava/models/club.rb) for all available properties.
+
+#### Club Activities
+
+Get club activities.
+
+```ruby
+activities = client.club_activities(id: 108605) # => Array[Strava::Models::Activity]
+
+activity = activities.first # => Strava::Models::Activity
+
+activity.name # => 'Afternoon Run'
+```
+
+See [Strava::Models::Activity](lib/strava/models/activity.rb) for all available properties. Note that Strava does not return activity or athlete ID via this API.
+
+#### Create Activity
+
+Create an activity.
+
+```ruby
+activity = client.create_activity(
+  name: 'Afternoon Run',
+  type: 'Run',
+  start_date_local: Time.now,
+  elapsed_time: 1234, # in seconds
+  description: 'Test run.',
+  distance: 1000 # in meters
+)
+
+activity.name # => 'Afternoon Run'
+activity.strava_url # => 'https://www.strava.com/activities/1982980795'
+```
+
+#### Update Activity
+
+Update an activity.
+
+```ruby
+activity = client.update_activity(
+  id: 1982980795,
+  name: 'Afternoon Run (Updated)',
+  type: 'Run',
+  description: 'It was cold.'
+)
+
+activity.name # => 'Afternoon Run (Updated)'
+activity.strava_url # => 'https://www.strava.com/activities/1982980795'
+```
+
+#### Get Activity
+
+Get a detailed activity by ID, including description, photos, gear, splits, segments and laps.
+
+```ruby
+activity = client.activity(id: 1982980795)
+
+activity.name # => 'Afternoon Run'
+activity.strava_url # => 'https://www.strava.com/activities/1982980795'
+```
+
+#### Activity Comments
+
+Get activity comments.
+
+```ruby
+comments = client.activity_comments(id: 1982980795) # => Array[Strava::Models::Comment]
+
+comment = comments.first # => Strava::Models::Comment
+
+comment.text # => 'Молодчина!'
+comment.athlete.username # => 'zolotov'
+```
+
+See [Strava::Models::Comment](lib/strava/models/comment.rb) for all available properties.
+
+#### Activity Kudoers
+
+Get activity kodoers.
+
+```ruby
+kudoers = client.activity_kudos(id: 1982980795) # => Array[Strava::Models::Athlete]
+
+kodoer = kudoers.first # => Strava::Models::Athlete
+
+kudoer.username # => 'zolotov'
+```
+
+#### Activity Laps
+
+Get activity laps.
+
+```ruby
+laps = client.activity_laps(id: 1982980795) # => Array[Strava::Models::Lap]
+
+lap = laps.first # => Strava::Models::Lap
+
+lap.name # => 'Lap 1'
+```
+
+See [Strava::Models::Lap](lib/strava/models/lap.rb) for all available properties.
+
+#### Activity Zones
+
+Get activity zones.
+
+```ruby
+zones = client.activity_zones(id: 1982980795) # => Array[Strava::Models::ActivityZone]
+
+zone = zones.first # => Strava::Models::ActivityZone
+zones.type # => 'heartrate'
+
+distribution_bucket = activity_zone.distribution_buckets.first # => Strava::Models::TimedZoneRange
+distribution_bucket.min # => 0
+distribution_bucket.max # => 123
+distribution_bucket.time # => 20
+```
+
+See [Strava::Models::ActivityZone](lib/strava/models/activity_zone.rb) and [Strava::Models::TimedZoneRange](lib/strava/models/timed_zone_range.rb) for all available properties.
+
+#### Pagination
+
+Some Strava APIs, including [athlete_activities](#athlete-activities) support pagination when supplying an optional `page` and `per_page` parameter. By default the client retrieves one page of data, which Strava currently defaults to 30 items. You can paginate through more data by supplying a block and an optional `per_page` parameter. The underlying implementation makes page-sized calls and increments the `page` argument.
+
+```ruby
+client.athlete_activities(per_page: 30) do |activity|
+  activity # => Strava::Models::Activity
+end
+```
 
 ### OAuth
 
@@ -205,19 +373,12 @@ end
 
 ## Tools
 
-### OAuth Token
+### Strava OAuth Token
 
-Use [bin/oauth-token](bin/outh-token) to obtain a token from the command-line.
+Use [strava-oauth-token](bin/strava-outh-token.rb) to obtain a token from the command-line. This will open a new browser window, navigate to Strava, request the appropriate permissions, then handle OAuth in a local redirect. The token type, refresh token, access token and token expiration will be displayed in the browser.
 
 ```bash
-$ STRAVA_CLIENT_ID=... STRAVA_CLIENT_SECRET=... bundle exec bin/oauth-token.rb
-
-Opening browser at https://www.strava.com/oauth/authorize?...
-Copy paste the code from the redirect URL: 1234556789901234567890
-token_type: Bearer
-refresh_token: 013612374123716234842346234
-access_token: 7348562936591928461923619823
-expires_at: 2018-11-23 16:25:52 -0500
+$ STRAVA_CLIENT_ID=... STRAVA_CLIENT_SECRET=... strava-oauth-token
 ```
 
 ## Contributing

data/bin/strava-oauth-token.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+require 'dotenv/load'
+require 'strava-ruby-client'
+require 'webrick'
+
+server = WEBrick::HTTPServer.new(Port: 4242)
+
+trap 'INT' do
+  server.shutdown
+end
+
+client = Strava::OAuth::Client.new(
+  client_id: ENV['STRAVA_CLIENT_ID'],
+  client_secret: ENV['STRAVA_CLIENT_SECRET']
+)
+
+server.mount_proc '/' do |req, res|
+  code = req.query['code']
+  response = client.oauth_token(code: code)
+
+  res.body = %(
+<html>
+  <body>
+    <ul>
+      <li>token_type: #{response.token_type}</li>
+      <li>refresh_token: #{response.refresh_token}</li>
+      <li>access_token: #{response.access_token}</li>
+      <li>expires_at: #{response.expires_at}</li>
+    </ul>
+  <body>
+</html>
+  )
+
+  server.shutdown
+end
+
+redirect_url = client.authorize_url(
+  redirect_uri: 'http://localhost:4242/',
+  response_type: 'code',
+  scope: 'read_all,activity:read_all,profile:read_all,profile:write,activity:write'
+)
+
+server.logger.info "opening browser at #{redirect_url}\n"
+system 'open', redirect_url
+
+server.start

data/lib/strava-ruby-client.rb

@@ -3,19 +3,39 @@ require 'faraday_middleware'
 require 'json'
 require 'logger'
 require 'hashie'
-require 'active_support/core_ext/object/to_query'
 require 'time'
 
+require 'active_support/core_ext/object/to_query'
+require 'active_support/core_ext/hash'
+require 'active_support/concern'
+
 require_relative 'strava/version'
 require_relative 'strava/logger'
 
 require_relative 'strava/errors/fault'
 
+require_relative 'strava/models/mixins/distance'
+require_relative 'strava/models/mixins/elevation'
+require_relative 'strava/models/mixins/time'
+
 require_relative 'strava/models/model'
 require_relative 'strava/models/token'
 require_relative 'strava/models/athlete'
 require_relative 'strava/models/map'
 require_relative 'strava/models/activity'
+require_relative 'strava/models/club'
+require_relative 'strava/models/segment_effort'
+require_relative 'strava/models/photos'
+require_relative 'strava/models/photo'
+require_relative 'strava/models/similar_activities'
+require_relative 'strava/models/trend'
+require_relative 'strava/models/split'
+require_relative 'strava/models/lap'
+require_relative 'strava/models/gear'
+require_relative 'strava/models/segment'
+require_relative 'strava/models/activity_zone'
+require_relative 'strava/models/timed_zone_range'
+require_relative 'strava/models/comment'
 
 require_relative 'strava/web/raise_error'
 require_relative 'strava/web/connection'
@@ -27,4 +47,5 @@ require_relative 'strava/oauth/config'
 require_relative 'strava/oauth/client'
 
 require_relative 'strava/api/config'
+require_relative 'strava/api/cursor'
 require_relative 'strava/api/client'

data/lib/strava/api/client.rb

@@ -14,13 +14,144 @@ module Strava
         { 'Authorization' => "Bearer #{access_token}" }
       end
 
+      #
+      # Get logged-in athlete.
+      #
       def athlete
         Strava::Models::Athlete.new(get('athlete'))
       end
 
-      def athlete_activities(options = {})
-        get('athlete/activities', options).map do |activity|
-          Strava::Models::Activity.new(activity)
+      #
+      # Get logged-in athlete.
+      #
+      def activity(options = {})
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        Strava::Models::Activity.new(get("activities/#{options[:id]}", options.except(:id)))
+      end
+
+      #
+      # List logged-in athlete activities.
+      #
+      # @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.
+      #
+      def athlete_activities(options = {}, &block)
+        paginate 'athlete/activities', options, Strava::Models::Activity, &block
+      end
+
+      #
+      # Create an activity.
+      #
+      def create_activity(options = {})
+        Strava::Models::Activity.new(post('activities', options))
+      end
+
+      #
+      # Update an activity.
+      # @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] :type
+      #   Activity type.
+      # @option options [String] :gear_id
+      #   Identifier for the gear associated with the activity. Specifying "none" clears gear from activity.
+      #
+      def update_activity(options = {})
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        Strava::Models::Activity.new(put("activities/#{options[:id]}", options.except(:id)))
+      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::Club, &block
+      end
+
+      #
+      # 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(options = {}, &block)
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        paginate "clubs/#{options[:id]}/activities", options.except(:id), Strava::Models::Activity, &block
+      end
+
+      #
+      # List activity comments.
+      #
+      # @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.
+      #
+      def activity_comments(options = {}, &block)
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        paginate "activities/#{options[:id]}/comments", options.except(:id), Strava::Models::Comment, &block
+      end
+
+      #
+      # List activity kudoers.
+      #
+      # @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.
+      #
+      def activity_kudos(options = {}, &block)
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        paginate "activities/#{options[:id]}/kudos", options.except(:id), Strava::Models::Athlete, &block
+      end
+
+      #
+      # Get activity zones.
+      #
+      # @option options [String] :id
+      #   Activity id.
+      #
+      def activity_zones(options = {})
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        get("activities/#{options[:id]}/zones", options).map do |row|
+          Strava::Models::ActivityZone.new(row)
+        end
+      end
+
+      #
+      # Get activity laps.
+      #
+      # @option options [String] :id
+      #   Activity id.
+      #
+      def activity_laps(options = {})
+        throw ArgumentError.new('Required argument :id missing') if options[:id].nil?
+        get("activities/#{options[:id]}/laps", options).map do |row|
+          Strava::Models::Lap.new(row)
         end
       end
 
@@ -33,6 +164,22 @@ module Strava
           Config
         end
       end
+
+      private
+
+      def paginate(path, options, model)
+        if block_given?
+          Cursor.new(self, path, options).each do |page|
+            page.each do |row|
+              yield model.new(row)
+            end
+          end
+        else
+          get(path, options).map do |row|
+            model.new(row)
+          end
+        end
+      end
     end
   end
 end