fitbit_api 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '099467bf4273b82b5a9cc9ad11d96b7e36bb856d9dbaf81735e7d5b913ff09eb'
-  data.tar.gz: fd5d0e33608dd71e071436e9619b57bc2ba9ccb27c92e67f2e1dd763ab6b2727
+  metadata.gz: 303b1eda2135541723313d505d4c34292e94b473c2a87cff32119bd8de97b0ea
+  data.tar.gz: c526445b8815cbe19ce92f6b762036aae9bbf57cfccea2cba9131ed63788307e
 SHA512:
-  metadata.gz: 7aeafc676dd87ad01dceed46fe7f4f741fdce3fea3f62852f3a0df7c4fbf8269f7d2d86471ea1b6866fbc9e2cb1af6be344fb42f8250289f25f4eef428df95c2
-  data.tar.gz: 47ea79fc3e1bd68d026622a8fe6404c134a635ca65b6cdeb740fdf5a1245722ec65b0d53a38579897a8dd8631ae75a1519bc96a302fa85e6648fece0e4e9a5af
+  metadata.gz: d7cc3ae62f509e40a0c58bc31f5ffc75865909d482e862401afa0737fc6138ea226c3a9909721903b86f00febd1a8eea46ac01b1d93d2c9dbd0d706b6c201938
+  data.tar.gz: d0d6328a931c8d3fe931f6e31b283681092b31d4b50d5186aeb1a7b8efe885dbf828d0c058a5296c4a4abe9b7e8b13b183482d1f6dc6102aac38a98284d9f3ec

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+0.10.0
+------
+- Add `auto_refresh_token` config to make token auto-refreshing configurable (defaults to true).
+- Add `on_token_refresh` config to specify callback to execute on token refresh (optional).
+- Bump `bundler` development dependency
+- Clean up documentation formatting
+
 0.9.1
 -----
 - Fix `sleep_time_series` endpoint

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/fitbit_api.svg)](https://badge.fury.io/rb/fitbit_api)
 [![Build Status](https://travis-ci.org/zokioki/fitbit_api.svg?branch=master)](https://travis-ci.org/zokioki/fitbit_api)
 
-FitbitAPI provides a Ruby interface to the [Fitbit Web API](https://dev.fitbit.com/reference/web-api/quickstart).
+FitbitAPI provides a Ruby interface to the [Fitbit Web API](https://dev.fitbit.com/reference/web-api).
 
 ## Installation
 
@@ -95,19 +95,18 @@ client.log_activity activity_id: 12345, durationMillis: '683300'
 
 When initializing a `FitbitAPI::Client` instance, you're given access to a handful of options:
 
-- `:api_version` - API version to be used when making requests (default: "1")
-
-- `:unit_system` - The measurement unit system to use for response values (default: "en_US" | available: "en_US", "en_GB", and "any" for metric)
-
-- `:locale` - The locale to use for response values (default: "en_US" | available: "en_US", "fr_FR", "de_DE", "es_ES", "en_GB", "en_AU", "en_NZ" and "ja_JP")
-
-- `:scope` - A space-delimited list of the permissions you are requesting (default: "activity nutrition profile settings sleep social weight heartrate" | available: "activity", "heartrate", "location", "nutrition", "profile", "settings" "sleep", "social" and "weight")
-
-- `:snake_case_keys` - Transform returned object's keys to snake case format (default: false)
-
-- `:symbolize_keys` - Transform returned object's keys to symbols (default: false)
-
-If using this library in Rails, you can configure your options using an initializer:
+| option             | description                  |
+| ------------------ | -----------------------------|
+| api_version        | API version to be used when making requests (default: "1") |
+| unit_system        | The measurement unit system to use for response values (default: "en_US") |
+| locale             | The locale to use for response values (default: "en_US") |
+| scope              | A space-delimited list of permissions being requested (default: "activity nutrition profile settings sleep social weight heartrate") |
+| snake_case_keys    | Transform response payload's keys to snake case format (default: false) |
+| symbolize_keys     | Transform response payload's keys to symbols (default: false) |
+| auto_refresh_token | Automatically refreshes the access token once expired (default: true) |
+| on_token_refresh   | A callback to be invoked whenever the access token is refreshed (default: nil) |
+
+If using this library in Rails, you can configure these options globally in an initializer:
 
 ```ruby
 # config/initializers/fitbit_api.rb

data/fitbit_api.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency     'oauth2', '~> 1.0'
 
   spec.add_development_dependency 'byebug'
-  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'bundler', '~> 2.3'
   spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rspec'
 end

data/lib/fitbit_api/activities.rb

@@ -14,15 +14,18 @@ module FitbitAPI
     # GET Activities
     # ==============
 
-    # Retrieves a summary and list of a user's activities and activity log entries for a given day
-    #   in the format requested using units in the unit system which corresponds to the Accept-Language header provided.
+    # Retrieves a summary and list of a user's activities and activity log entries
+    # for a given day in the format requested using units in the unit system which
+    # corresponds to the Accept-Language header provided.
+    #
+    # @param date [Date] The date for which to retrieve the activity data.
 
     def daily_activity_summary(date=Date.today, opts={})
       get("user/#{user_id}/activities/date/#{format_date(date)}.json", opts)
     end
 
-    # Retrieves a list of a user's frequent activities in the format requested using units
-    #   in the unit system which corresponds to the Accept-Language header provided.
+    # Retrieves a list of a user's frequent activities in the format requested using
+    # units in the unit system which corresponds to the Accept-Language header provided.
 
     def frequent_activities(opts={})
       get("user/#{user_id}/activities/frequent.json", opts)
@@ -38,22 +41,24 @@ module FitbitAPI
       get("user/#{user_id}/activities/favorite.json", opts)
     end
 
-    # Gets a tree of all valid Fitbit public activities from
-    #   the activities catalog as well as private custom activities the user created.
+    # Gets a tree of all valid Fitbit public activities from the activities catalog
+    # as well as private custom activities the user created.
 
     def all_activities(opts={})
       get('activities.json', opts)
     end
 
-    # Retrieves a list of a user's activity log entries before or after a given day with
-    #   offset and limit using units in the unit system which corresponds to the Accept-Language header provided.
-
-    # ==== URL Parameters
-    # * +:beforeDate+ - the date; formatted in yyyy-MM-ddTHH:mm:ss
-    # * +:afterDate+ - the date; formatted in yyyy-MM-ddTHH:mm:ss
-    # * +:sort+ - the sort order of entries by date (asc or desc)
-    # * +:offset+ - the offset number of entries. Must always be 0
-    # * +:limit+ - the max of the number of entries returned (max: 20)
+    # Retrieves a list of a user's activity log entries before or after a given day
+    # with offset and limit using units in the unit system which corresponds to the
+    # Accept-Language header provided.
+    #
+    #   activity_logs_list(before_date: Date.parse('2021-05-24'), limit: 5)
+    #
+    # @option before_date [Date] Specify when filtering entries that occured before the given date
+    # @option after_date [Date] Specify when filtering entries that occured after the given date
+    # @option sort [String] the Sort order of entries by date (asc or desc)
+    # @option offset [Integer] The offset number of entries. Must always be 0
+    # @option limit [Integer] The max of the number of entries returned (max: 20)
 
     def activity_logs_list(opts={})
       opts[:params] = {}
@@ -68,16 +73,18 @@ module FitbitAPI
     end
 
     # Returns the details of a specific activity in the Fitbit activities database in the format requested.
-    #   If activity has levels, also returns a list of activity level details.
+    # If activity has levels, also returns a list of activity level details.
+    #
+    # @param activity_id [Integer, String] The ID of the desired activity to retrieve
 
     def activity(activity_id)
       get("activities/#{activity_id}.json")
     end
 
     # Retrieves the user's activity statistics in the format requested using units
-    #   in the unit system which corresponds to the Accept-Language header provided.
-    #   Activity statistics includes Lifetime and Best achievement values from the
-    #   My Achievements tile on the website dashboard.
+    # in the unit system which corresponds to the Accept-Language header provided.
+    # Activity statistics includes Lifetime and Best achievement values from the
+    # My Achievements tile on the website dashboard.
 
     def lifetime_stats(opts={})
       get("user/#{user_id}/activities.json", opts)
@@ -142,23 +149,26 @@ module FitbitAPI
     # ===============
 
     # Creates log entry for an activity or user's private custom activity using units
-    #   in the unit system which corresponds to the Accept-Language header provided.
-
-    # ==== POST Parameters
-    # * +:activityId+ - activity id
-    # * +:activityName+ - custom activity name. Either activity ID or activityName must be provided
-    # * +:manualCalories+ - calories burned, specified manually. Required with activityName, otherwise optional
-    # * +:startTime+ - activity start time; formatted in HH:mm:ss
-    # * +:durationMillis+ - duration in milliseconds
-    # * +:date+ - log entry date; formatted in yyyy-MM-dd
-    # * +:distance+ - distance; required for logging directory activity; formatted in X.XX
-    # * +:distanceUnit+ - distance measurement unit
+    # in the unit system which corresponds to the Accept-Language header provided.
+    #
+    #   log_activity(body: { activity_id: 90013, manual_calories: 300, duration_millis: 6000000 })
+    #
+    # @option activity_id [Integer, String] The activity ID
+    # @option activity_name [String] Custom activity name. Either activity ID or activity_name must be provided
+    # @option manual_calories [Integer] Calories burned, specified manually. Required with activity_name, otherwise optional
+    # @option start_time [String] Activity start time; formatted in HH:mm:ss
+    # @option duration_millis [Integer] Duration in milliseconds
+    # @option date [String] Log entry date; formatted in yyyy-MM-dd
+    # @option distance [Integer] Distance; required for logging directory activity
+    # @option distance_unit [String] Distance measurement unit
 
     def log_activity(opts)
       post("user/#{user_id}/activities.json", opts)
     end
 
     # Adds the activity with the given ID to user's list of favorite activities.
+    #
+    # @param activity_id [Integer] The activity ID
 
     def add_favorite_activity(activity_id)
       post("user/#{user_id}/activities/favorite/#{activity_id}.json")
@@ -168,12 +178,16 @@ module FitbitAPI
     # =================
 
     # Deletes a user's activity log entry with the given ID.
+    #
+    # @param activity_log_id [Integer] The ID of the activity log entry
 
     def delete_activity(activity_log_id)
       delete("user/#{user_id}/activities/#{activity_log_id}.json")
     end
 
     # Removes the activity with the given ID from a user's list of favorite activities.
+    #
+    # @param activity_id [Integer] The ID of the activity to be removed
 
     def delete_favorite_activity(activity_id)
       delete("user/#{user_id}/activities/favorite/#{activity_id}.json")

data/lib/fitbit_api/alarms.rb

@@ -4,6 +4,8 @@ module FitbitAPI
     # ==========
 
     # Returns a list of the set alarms connected to a user's account.
+    #
+    # @params tracker_id [Integer] The ID of the tracker for which the data is returned
 
     def alarms(tracker_id, opts={})
       get("user/#{user_id}/devices/tracker/#{tracker_id}/alarms.json", opts)
@@ -13,28 +15,33 @@ module FitbitAPI
     # ===========
 
     # Adds the alarm settings to a given ID for a given device.
-
-    # ==== POST Parameters
-    # * +:time+ - time of day that the alarm vibrates with a UTC timezone offset, e.g. 07:15-08:00
-    # * +:enabled+ - boolean; if false, alarm does not vibrate until enabled is set to true
-    # * +:recurring+ - boolean; if false, the alarm is a single event
-    # * +:weekDays+ - comma separated list of days of the week on which the alarm vibrates (MONDAY,TUESDAY)
+    #
+    #   add_alarm(body: { time: "07:15-08:00", enabled: true, recurring: true, week_days: "MONDAY,FRIDAY,SATURDAY" })
+    #
+    # @param tracker_id [Integer] The ID of the tracker for which the alarm is created
+    #
+    # @option time [String] Time of day that the alarm vibrates with a UTC timezone offset, e.g. 07:15-08:00
+    # @option enabled [Boolean] If false, alarm does not vibrate until enabled is set to true
+    # @option recurring [Boolean] If false, the alarm is a single event
+    # @option week_days [String] Comma separated list of days of the week on which the alarm vibrates (MONDAY,TUESDAY)
 
     def add_alarm(tracker_id, opts={})
       post("user/#{user_id}/devices/tracker/#{tracker_id}/alarms.json", opts)
     end
 
     # Updates the alarm entry with a given ID for a given device.
-
-    # ==== POST Parameters
-    # * +:time+ - time of day that the alarm vibrates with a UTC timezone offset, e.g. 07:15-08:00
-    # * +:enabled+ - boolean; if false, alarm does not vibrate until enabled is set to true
-    # * +:recurring+ - boolean; if false, the alarm is a single event
-    # * +:weekDays+ - comma separated list of days of the week on which the alarm vibrates (MONDAY,TUESDAY)
-    # * +:snoozeLength+ - integer; minutes between alarms
-    # * +:snoozeCount+ - integer; maximum snooze count
-    # * +:label+ - string; label for alarm
-    # * +:vibe+ - vibe pattern; only one value for now (DEFAULT)
+    #
+    # @param tracker_id [Integer] The ID of the tracker for which the alarm is created
+    # @param alarm_id [Integer] The ID of the alarm to be updated
+    #
+    # @option time [String] Time of day that the alarm vibrates with a UTC timezone offset, e.g. 07:15-08:00
+    # @option enabled [Boolean] If false, alarm does not vibrate until enabled is set to true
+    # @option recurring [Boolean] If false, the alarm is a single event
+    # @option week_days [String] Comma separated list of days of the week on which the alarm vibrates (MONDAY,TUESDAY)
+    # @option snooze_length [Integer] Minutes between alarms
+    # @option snooze_count [Integer] Maximum snooze count
+    # @option label [String] Label for alarm
+    # @option vibe [String] Vibe pattern; only one value for now (DEFAULT)
 
     def update_alarm(tracker_id, alarm_id, opts={})
       post("user/#{user_id}/devices/tracker/#{tracker_id}/alarms/#{alarm_id}.json", opts)
@@ -44,6 +51,9 @@ module FitbitAPI
     # =============
 
     # Deletes the user's device alarm entry with the given ID for a given device.
+    #
+    # @param tracker_id [Integer] The ID of the tracker for which the alarm is to be deleted
+    # @param alarm_id [Integer] The ID of the alarm to be deleted
 
     def delete_alarm(tracker_id, alarm_id, opts={})
       delete("user/#{user_id}/devices/tracker/#{tracker_id}/alarms/#{alarm_id}.json", opts)

data/lib/fitbit_api/base.rb

@@ -21,4 +21,7 @@ module FitbitAPI
 
   define_setting :snake_case_keys, false
   define_setting :symbolize_keys,  false
+
+  define_setting :auto_refresh_token, true
+  define_setting :on_token_refresh
 end

data/lib/fitbit_api/client.rb

@@ -14,8 +14,8 @@ require 'fitbit_api/water'
 module FitbitAPI
   class Client
     attr_accessor :api_version, :unit_system, :locale, :scope,
-                  :snake_case_keys, :symbolize_keys
-    attr_reader   :user_id
+                  :snake_case_keys, :symbolize_keys, :auto_refresh_token, :on_token_refresh
+    attr_reader   :token, :user_id
 
     def initialize(opts={})
       validate_args(opts)
@@ -32,57 +32,30 @@ module FitbitAPI
       @token = @client.auth_code.get_token(
         auth_code,
         redirect_uri: @redirect_uri,
-        headers: auth_header
+        headers: auth_headers
       )
       @user_id = @token.params['user_id']
       @token
     end
 
-    def token
-      @token.expired? ? refresh_token! : @token
-    end
-
     def refresh_token!
-      @token = @token.refresh!(headers: auth_header)
+      @token = @token.refresh!(headers: auth_headers)
       @user_id ||= @token.params['user_id']
-      @token
-    end
-
-    def auth_header
-      { 'Authorization' => ('Basic ' + Base64.encode64(@client_id + ':' + @client_secret)) }
-    end
+      on_token_refresh.call(@token) if on_token_refresh.respond_to?(:call)
 
-    def request_headers
-      {
-        'User-Agent' => "fitbit_api gem (v#{FitbitAPI::VERSION})",
-        'Accept-Language' => @unit_system,
-        'Accept-Locale' => @locale
-      }
+      @token
     end
 
     def get(path, opts={})
-      params = opts.delete(:params) || {}
-      response = token.get(("#{@api_version}/" + path), params: deep_keys_to_camel_case!(params), headers: request_headers).response
-      object = MultiJson.load(response.body) unless response.status == 204
-      process_keys!(object, opts)
+      request(:get, path, opts)
     end
 
     def post(path, opts={})
-      response = token.post(("#{@api_version}/" + path), body: deep_keys_to_camel_case!(opts), headers: request_headers).response
-      object = MultiJson.load(response.body) unless response.status == 204
-      process_keys!(object, opts)
+      request(:post, path, opts)
     end
 
     def delete(path, opts={})
-      response = token.delete(("#{@api_version}/" + path), headers: request_headers).response
-      object = MultiJson.load(response.body) unless response.status == 204
-      process_keys!(object, opts)
-    end
-
-    def process_keys!(object, opts={})
-      deep_keys_to_snake_case!(object) if (opts[:snake_case_keys] || snake_case_keys)
-      deep_symbolize_keys!(object) if (opts[:symbolize_keys] || symbolize_keys)
-      return object
+      request(:delete, path, opts)
     end
 
     private
@@ -103,7 +76,8 @@ module FitbitAPI
     def assign_attrs(opts)
       attrs = %i[client_id client_secret redirect_uri site_url
                  authorize_url token_url unit_system locale scope
-                 api_version snake_case_keys symbolize_keys].freeze
+                 api_version snake_case_keys symbolize_keys
+                 auto_refresh_token on_token_refresh].freeze
 
       attrs.each do |attr|
         instance_variable_set("@#{attr}", (opts[attr] || FitbitAPI.send(attr)))
@@ -139,5 +113,38 @@ module FitbitAPI
 
       refresh_token! if @token.token.empty?
     end
+
+    def request(verb, path, opts={})
+      request_path = "#{@api_version}/#{path}"
+      request_options = opts.merge(headers: request_headers)
+
+      deep_keys_to_camel_case!(request_options[:params])
+      deep_keys_to_camel_case!(request_options[:body])
+
+      refresh_token! if auto_refresh_token && token.expired?
+
+      response = token.public_send(verb, request_path, request_options).response
+      object = MultiJson.load(response.body) unless response.status == 204
+
+      process_keys!(object, opts)
+    end
+
+    def auth_headers
+      { 'Authorization' => ('Basic ' + Base64.encode64(@client_id + ':' + @client_secret)) }
+    end
+
+    def request_headers
+      {
+        'User-Agent' => "fitbit_api gem (v#{FitbitAPI::VERSION})",
+        'Accept-Language' => @unit_system,
+        'Accept-Locale' => @locale
+      }
+    end
+
+    def process_keys!(object, opts={})
+      deep_keys_to_snake_case!(object) if (opts[:snake_case_keys] || snake_case_keys)
+      deep_symbolize_keys!(object) if (opts[:symbolize_keys] || symbolize_keys)
+      return object
+    end
   end
 end

data/lib/fitbit_api/goals.rb

@@ -31,28 +31,30 @@ module FitbitAPI
     # ==========
 
     # Creates or updates a user's daily activity goals and returns a response using units
-    #   in the unit system which corresponds to the Accept-Language header provided.
-
-    # ==== POST Parameters
-    # * +:caloriesOut+ - calories output goal value; integer
-    # * +:activeMinutes+ - active minutes goal value; integer
-    # * +:floors+ - floor goal value; integer
-    # * +:distance+ - distance goal value; X.XX or integer
-    # * +:steps+ - steps goal value; integer
+    # in the unit system which corresponds to the Accept-Language header provided.
+    #
+    #   create_or_update_daily_goals(body: {calories_out: 2000, active_minutes: 90, floors: 5})
+    #
+    # @option calories_out [Integer] Calories output goal value
+    # @option active_minutes [Integer] Active minutes goal value
+    # @option floors [Integer] Floor goal value
+    # @option distance [Integer, Float] Distance goal value
+    # @option steps [Integer] Steps goal value
 
     def create_or_update_daily_goals(opts={})
       post("user/#{user_id}/activities/goals/daily.json", opts)
     end
 
     # Creates or updates a user's weekly activity goals and returns a response using units
-    #   in the unit system which corresponds to the Accept-Language header provided.
-
-    # ==== POST Parameters
-    # * +:caloriesOut+ - calories output goal value; integer
-    # * +:activeMinutes+ - active minutes goal value; integer
-    # * +:floors+ - floor goal value; integer
-    # * +:distance+ - distance goal value; X.XX or integer
-    # * +:steps+ - steps goal value; integer
+    # in the unit system which corresponds to the Accept-Language header provided.
+    #
+    #   create_or_update_weekly_goals(body: { active_minutes: 300, floors: 20 })
+    #
+    # @option calories_out [Integer] Calories output goal value
+    # @option active_minutes [Integer] Active minutes goal value
+    # @option floors [Integer] Floor goal value
+    # @option distance [Integer, Float] Distance goal value
+    # @option steps [Integer] Steps goal value
 
     def create_or_update_weekly_goals(opts={})
       post("user/#{user_id}/activities/goals/weekly.json", opts)

data/lib/fitbit_api/helpers/configuration.rb

@@ -1,25 +1,27 @@
-module Configuration
-  def configure
-    yield self
-  end
+module FitbitAPI
+  module Configuration
+    def configure
+      yield self
+    end
 
-  def define_setting(name, default = nil)
-    class_variable_set("@@#{name}", default)
+    def define_setting(name, default = nil)
+      class_variable_set("@@#{name}", default)
 
-    define_class_method "#{name}=" do |value|
-      class_variable_set("@@#{name}", value)
-    end
+      define_class_method "#{name}=" do |value|
+        class_variable_set("@@#{name}", value)
+      end
 
-    define_class_method name do
-      class_variable_get("@@#{name}")
+      define_class_method name do
+        class_variable_get("@@#{name}")
+      end
     end
-  end
 
-  private
+    private
 
-  def define_class_method(name, &block)
-    (class << self; self; end).instance_eval do
-      define_method name, &block
+    def define_class_method(name, &block)
+      (class << self; self; end).instance_eval do
+        define_method name, &block
+      end
     end
   end
 end

data/lib/fitbit_api/version.rb

@@ -1,3 +1,3 @@
 module FitbitAPI
-  VERSION = '0.9.1'
+  VERSION = '0.10.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fitbit_api
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Zoran
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-04-05 00:00:00.000000000 Z
+date: 2022-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -132,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.13
 signing_key: 
 specification_version: 4
 summary: A Ruby interface to the Fitbit Web API.