fitgem 0.3.6 → 0.4.0

data/lib/fitgem/body_measurements.rb

@@ -1,20 +1,67 @@
 module Fitgem
   class Client
+    # ==========================================
+    #      Body Measurements Update Methods
+    # ==========================================
 
-   # ==========================================
-   #      Body Measurements Update Methods
-   # ==========================================
-   def body_measurements_on_date(date)
-     get("/user/#{@user_id}/body/date/#{format_date(date)}.json")
-   end
+    # Get the body measurements logged on a specified date
+    #
+    # @param [DateTime, String] date The date to retrieve body
+    #   measurements for.  May be a DateTime object or a String
+    #   in "yyyy-MM-dd" format.
+    # @return [Hash] A hash containing the logged body measurements
+    #   along with any goals set for the current user.
+    def body_measurements_on_date(date)
+      get("/user/#{@user_id}/body/date/#{format_date(date)}.json")
+    end
 
-   # ==========================================
-   #      Body Measurements Update Methods
-   # ==========================================
+    # ==========================================
+    #      Body Measurements Update Methods
+    # ==========================================
 
-   def log_weight(weight, date, options={})
-     post("/user/#{@user_id}/body/weight.json", options.merge(:weight => weight, :date => format_date(date)))
-   end
+    # Log weight to fitbit for the current user
+    #
+    # @param [Integer, String] weight The weight to log, as either
+    #   an integer or a string in "X.XX'" format
+    # @param [DateTime, String] date The date the weight should be
+    #   logged, as either a DateTime or a String in "yyyy-MM-dd" format
+    # @return [Hash] 
+    #
+    # @deprecated {#log_body_measurements} should be used instead of
+    #   log_weight
+    def log_weight(weight, date, options={})
+      post("/user/#{@user_id}/body/weight.json", options.merge(:weight => weight, :date => format_date(date)))
+    end
 
+    # Log body measurements to fitbit for the current user
+    #
+    # At least ONE measurement item is REQUIRED in the call, as well as the 
+    # date. All measurement values to be logged for the user must be either an
+    # Integer, a Decimal value, or a String in "X.XX" format. The
+    # measurement units used for the supplied measurements are based on
+    # which {Fitgem::ApiUnitSystem} is set in {Fitgem::Client#api_unit_system}.
+    #
+    # @param [Hash] opts The options including data to log for the user
+    # @option opts [Integer, Decimal, String] :weight Weight measurement
+    # @option opts [Integer, Decimal, String] :waist Waist measurement
+    # @option opts [Integer, Decimal, String] :thigh Thigh measurement
+    # @option opts [Integer, Decimal, String] :neck Neck measurement
+    # @option opts [Integer, Decimal, String] :hips Hips measurement
+    # @option opts [Integer, Decimal, String] :forearm Forearm measurement
+    # @option opts [Integer, Decimal, String] :fat Body fat percentage measurement
+    # @option opts [Integer, Decimal, String] :chest Chest measurement
+    # @option opts [Integer, Decimal, String] :calf Calf measurement
+    # @option opts [Integer, Decimal, String] :bicep Bicep measurement
+    # @option opts [DateTime, Date, String] :date Date to log measurements
+    #   for; provided either as a DateTime, Date, or a String in
+    #   "yyyy-MM-dd" format 
+    #
+    # @return [Hash] Hash containing the key +:body+ with an inner hash
+    #   of all of the logged measurements
+    #
+    # @since v0.4.0
+    def log_body_measurements(opts)
+      post("/user/#{@user_id}/body.json", opts)
+    end
   end
-end
+end

data/lib/fitgem/client.rb

@@ -17,55 +17,161 @@ require 'uri'
 
 module Fitgem
   class Client
+    API_VERSION = "1"
+    EMPTY_BODY = ""
 
+    # Sets or gets the api_version to be used in API calls
+    #"
+    # @return [String]
     attr_accessor :api_version
+
+    # Sets or gets the api unit system to be used in API calls
+    #
+    # @return [String]
+    #
+    # @example Set this using the {Fitgem::ApiUnitSystem}
+    #   client.api_unit_system = Fitgem::ApiUnitSystem.UK
+    # @example May also be set in the constructor call
+    #   client = Fitgem::Client { 
+    #     :consumer_key => my_key,
+    #     :consumer_secret => my_secret,
+    #     :token => fitbit_oauth_token,
+    #     :secret => :fitbit_oauth_secret,
+    #     :unit_system => Fitgem::ApiUnitSystem.METRIC
+    #   }
     attr_accessor :api_unit_system
+
+    # Sets or gets the user id to be used in API calls
+    #
+    # @return [String]
     attr_accessor :user_id
 
-    def initialize(options = {})
-      @consumer_key = options[:consumer_key]
-      @consumer_secret = options[:consumer_secret]
-      @token = options[:token]
-      @secret = options[:secret]
-      @proxy = options[:proxy]
-      @user_id = options[:user_id] || "-"
-      @api_unit_system = Fitgem::ApiUnitSystem.US
-      @api_version = "1"
+    # Creates a client object to communicate with the fitbit API
+    #
+    # There are two primary ways to create a client: one if the current
+    # fitbit user has not authenticated through fitbit.com, and another
+    # if they have already authenticated and you have a stored
+    # token/secret returned by fitbit after the user authenticated and
+    # authorized your application.
+    #
+    # @param [Hash] opts The constructor options
+    # @option opts [String] :consumer_key The consumer key (required for
+    #   OAuth)
+    # @option opts [String] :consumer_secret The consumer secret (required
+    #   for OAuth)
+    # @option opts [String] :token The token generated by fitbit during the OAuth
+    #   handshake; stored and re-passed to the constructor to create a
+    #   'logged-in' client
+    # @option opts [String] :secret The secret generated by fitbit during the
+    #   OAuth handshake; stored and re-passed to the constructor to
+    #   create a 'logged-in' client
+    # @option opts [String] :proxy A proxy URL to use for API calls
+    # @option opts [String] :user_id The Fitbit user id of the logged-in
+    #   user
+    # @option opts [Symbol] :unit_system The unit system to use for API
+    #   calls; use {Fitgem::ApiUnitSystem} to set during initialization.
+    #   DEFAULT: {Fitgem::ApiUnitSystem.US}
+    #
+    # @example User has not yet authorized with fitbit
+    #   client = Fitgem::Client.new { :consumer_key => my_key, :consumer_secret => my_secret }
+    #
+    # @example User has already authorized with fitbit, and we have a stored token/secret
+    #   client = Fitgem::Client.new { 
+    #     :consumer_key => my_key, 
+    #     :consumer_secret => my_secret, 
+    #     :token => fitbit_oauth_token, 
+    #     :secret => fitbit_oauth_secret 
+    #   }
+    #
+    # @return [Client] A Fitgem::Client; may be in a logged-in state or
+    #   ready-to-login state
+    def initialize(opts)
+      missing = [:consumer_key, :consumer_secret] - opts.keys
+      if missing.size > 0
+        raise Fitgem::InvalidArgumentError, "Missing required options: #{missing.join(',')}"
+      end
+      @consumer_key = opts[:consumer_key]
+      @consumer_secret = opts[:consumer_secret]
+
+
+      @token = opts[:token]
+      @secret = opts[:secret]
+
+      @proxy = opts[:proxy] if opts[:proxy]
+      @user_id = opts[:user_id] || "-"
+
+      @api_unit_system = opts[:unit_system] || Fitgem::ApiUnitSystem.US
+      @api_version = API_VERSION
     end
 
-    def authorize(token, secret, options = {})
-      request_token = OAuth::RequestToken.new(
-        consumer, token, secret
-      )
-      @access_token = request_token.get_access_token(options)
+    # Finalize authentication and retrieve an oauth access token
+    #
+    # @param [String] token The OAuth token
+    # @param [String] secret The OAuth secret
+    # @param [Hash] opts Additional data
+    # @option opts [String] :oauth_verifier The verifier token sent by
+    #   fitbit after user has logged in and authorized the application.
+    #   Is included in the body of the callback request, if there was
+    #   one.  Otherwise is shown onscreen for the user to copy/paste
+    #   back into your application.  See {https://wiki.fitbit.com/display/API/OAuth-Authentication-API} for more information.
+    #
+    # @return [OAuth::AccessToken] An oauth access token; this is not
+    #   needed to make API calls, since it is stored internally.  It is
+    #   returned so that you may make general OAuth calls if need be.
+    def authorize(token, secret, opts={})
+      request_token = OAuth::RequestToken.new(consumer, token, secret)
+      @access_token = request_token.get_access_token(opts)
       @token = @access_token.token
       @secret = @access_token.secret
       @access_token
     end
 
+    # Reconnect to the fitbit API with a stored oauth token and oauth
+    # secret
+    #
+    # This method should be used if you have previously directed a user
+    # through the OAuth process and received a token and secret that
+    # were stored for later use.  Using +reconnect+ you can
+    # 'reconstitute' the access_token required for API calls without
+    # needing the user to go through the OAuth process again.
+    #
+    # @param [String] token The stored OAuth token
+    # @param [String] secret The stored OAuth secret
+    #
+    # @return [OAuth::AccessToken] An oauth access token; this is not
+    #   needed to make API calls, since it is stored internally.  It is
+    #   returned so that you may make general OAuth calls if need be.
     def reconnect(token, secret)
       @token = token
       @secret = secret
       access_token
     end
 
-    def request_token(options={})
-      consumer.get_request_token(options)
+    # Get an oauth request token
+    #
+    # @param [Hash] opts Request token request data; can be used to
+    #   override default endpoint information for the oauth process
+    # @return [OAuth::RequestToken]
+    def request_token(opts={})
+      consumer.get_request_token(opts)
     end
 
-    def authentication_request_token(options={})
+    # Get an authentication request token
+    #
+    # @param [Hash] opts Additional request token request data
+    # @return [OAuth::RequestToken]
+    def authentication_request_token(opts={})
       consumer.options[:authorize_path] = '/oauth/authenticate'
-      request_token(options)
+      request_token(opts)
     end
 
     private
 
       def consumer
-        @consumer ||= OAuth::Consumer.new(
-          @consumer_key,
-          @consumer_secret,
-          { :site => 'http://api.fitbit.com', :request_endpoint => @proxy }
-        )
+        @consumer ||= OAuth::Consumer.new(@consumer_key, @consumer_secret, { 
+          :site => 'http://api.fitbit.com', 
+          :proxy => @proxy
+        })
       end
 
       def access_token
@@ -73,27 +179,36 @@ module Fitgem
       end
 
       def get(path, headers={})
+        extract_response_body raw_get(path, headers)
+      end
+
+      def raw_get(path, headers={})
         headers.merge!("User-Agent" => "fitgem gem v#{Fitgem::VERSION}", "Accept-Language" => @api_unit_system)
         uri = "/#{@api_version}#{path}"
-        oauth_response = access_token.get(uri, headers)
-        process_response oauth_response
+        access_token.get(uri, headers)
       end
 
       def post(path, body='', headers={})
+        extract_response_body raw_post(path, body, headers)
+      end
+
+      def raw_post(path, body='', headers={})
         headers.merge!("User-Agent" => "fitgem gem v#{Fitgem::VERSION}", "Accept-Language" => @api_unit_system)
         uri = "/#{@api_version}#{path}"
-        oauth_response = access_token.post(uri, body, headers)
-        process_response oauth_response
+        access_token.post(uri, body, headers)
       end
 
       def delete(path, headers={})
+        extract_response_body raw_delete(path, headers)
+      end
+
+      def raw_delete(path, headers={})
         headers.merge!("User-Agent" => "fitgem gem v#{Fitgem::VERSION}", "Accept-Language" => @api_unit_system)
         uri = "/#{@api_version}#{path}"
-        oauth_response = access_token.delete(uri, headers)
-        process_response oauth_response
+        access_token.delete(uri, headers)
       end
 
-      def process_response(resp)
+      def extract_response_body(resp)
         resp.nil? || resp.body.nil? ? {} : JSON.parse(resp.body)
       end
   end

data/lib/fitgem/devices.rb

@@ -1,17 +1,27 @@
 module Fitgem
   class Client
-    
     # ==========================================
     #          Device Retrieval Methods
     # ==========================================
-   
+
+    # Get a list of devices for the current account
+    #
+    # @return [Array] An array of hashes, each of which describes
+    #   a device attaached to the current account
     def devices
       get("/user/#{@user_id}/devices.json")
     end
-    
+
+    # Get the details about a specific device
+    #
+    # The ID required for this call could be found by getting the list
+    # of devices with a call to {#devices}.
+    #
+    # @param [Integer, String] device_id The ID of the device to get
+    #   details for
+    # @return [Hash] Hash containing device information
     def device_info(device_id)
       get("/user/#{@user_id}/devices/#{device_id}.json")
     end
-    
   end
-end
+end

data/lib/fitgem/errors.rb

@@ -1,10 +1,13 @@
 module Fitgem
   class InvalidArgumentError < ArgumentError
   end
-  
+
   class UserIdError < Exception
   end
-  
-  class InvalidTimeRange < ArgumentError
+
+  class InvalidDateArgument < InvalidArgumentError
   end
-end
+
+  class InvalidTimeRange < InvalidArgumentError
+  end
+end

data/lib/fitgem/food_form.rb

@@ -0,0 +1,18 @@
+module Fitgem
+  # Enumeration of food form types
+  #
+  # Primarily used in calls to {#create_food}.
+  class FoodFormType
+    # Food in liquid form
+    # @return [String]
+    def self.LIQUID
+      "LIQUID"
+    end
+
+    # Food in dry form
+    # @return [String]
+    def self.DRY
+      "DRY"
+    end
+  end
+end

data/lib/fitgem/foods.rb

@@ -1,26 +1,45 @@
 module Fitgem
   class Client
-
     # ==========================================
     #          Food Retrieval Methods
     # ==========================================
 
+    # Get all foods logged on the supplied date
+    #
+    # @param [DateTime, Date, String] date
+    # @return [Array] A list of the foods, each of which is a
+    #   Hash containing the food details
     def foods_on_date(date)
       get("/user/#{@user_id}/foods/log/date/#{format_date(date)}.json")
     end
 
+    # Get a list of the recently logged foods
+    #
+    # @return [Array] A list of foods, each of which is a Hash
+    #   containing the food details
     def recent_foods()
       get("/user/#{@user_id}/foods/log/recent.json")
     end
 
+    # Get a list of the frequently logged foods
+    #
+    # @return [Array] A list of foods, each of which is a Hash
+    #   containing the food details
     def frequent_foods()
       get("/user/#{@user_id}/foods/log/frequent.json")
     end
 
+    # Get a list of the favorite logged foods
+    #
+    # @return [Array] A list of foods, each of which is a Hash
+    #   containing the food details
     def favorite_foods()
       get("/user/#{@user_id}/foods/log/favorite.json")
     end
 
+    # Get a list of all of the available food units
+    #
+    # @return [Array] List of food units
     def foods_units()
       get("/foods/units.json")
     end
@@ -30,12 +49,18 @@ module Fitgem
     # ==========================================
 
     # Search the foods database
-    def find_food(query_string)
-      get("/foods/search.json?query=#{URI.escape(query_string)}")
+    #
+    # @param [String] query The query parameters for the food search
+    # @return [Array] A list of foods, each of which is a Hash
+    #   containing detailed food information
+    def find_food(query)
+      get("/foods/search.json?query=#{URI.escape(query)}")
     end
 
-    # Using the foodId field from the results of find_food(), query
-    # the details of a specific food
+    # Get detailed information for a food
+    #
+    # @param [Integer, String] food_id
+    # @return [Hash] Hash containing detailed food information
     def food_info(food_id)
       get("/foods/#{food_id}.json")
     end
@@ -44,17 +69,38 @@ module Fitgem
     #           Food Update Methods
     # ==========================================
 
-    # Send the following required ID's in the options hash:
-    #   options[:foodId]      => ID of the food to log
-    #   options[:mealTypeId]  => ID of the meal to log the food for
-    #   options[:unitId]      => ID of the unit to log with the food
-    #      (typically retrieved via a previous call to get Foods (all, recent, frequent, favorite) or Food Units. )
-    #   options[:amount]      => Amount consumed of the selected unit; a floating point number
-    #   options[:date]        => Log date in the format yyyy-MM-dd
-    def log_food(options)
-      post("/user/#{@user_id}/foods/log.json", options)
+    # Log food to fitbit for the current user
+    #
+    # To log a food, either a +foodId+ or +foodName+ is REQUIRED.
+    #
+    # @param [Hash] opts Food log options
+    # @option opts [Integer, String] :foodId Food id
+    # @option opts [String] :foodName Food entry name
+    # @option opts [String] :brandName Brand name, valid only with foodName
+    # @option opts [Integer, String] :calories Calories for this serving size, 
+    #   valid only with foodName
+    # @option opts [Integer, String] :mealTypeId Meal type id; (1 -
+    #   Breakfast, 2 - Morning Snack, 3 - Lunch, 4 - Afternoon Snack, 5 - Dinner, 7 - Anytime)
+    # @option opts [Integer, String] :unitId Unit id; typically
+    #   retrieved via previous calls to {#foods_on_date},
+    #   {#recent_foods}, {#favorite_foods}, {#frequent_foods},
+    #   {#find_food}, or {#foods_units}
+    # @option opts [Integer, Decimal, String] :amount Amount consumed;
+    #   if a String, must be in the format "X.XX"
+    # @option opts [DateTime, Date, String] :date Log entry date; in the
+    #   format "yyyy-MM-dd" if a String
+    # @option opts [Boolean] :favorite Add food to favorites after
+    #   creating the log
+    #
+    # @return [Hash] Hash containing confirmation of the logged food
+    def log_food(opts)
+      post("/user/#{@user_id}/foods/log.json", opts)
     end
 
+    # Mark a food as a favorite
+    #
+    # @param [Integer, String] food_id Food id
+    # @return [Hash] Empty denotes success
     def add_favorite_food(food_id)
       post("/user/#{@user_id}/foods/log/favorite/#{food_id}.json")
     end
@@ -63,10 +109,19 @@ module Fitgem
     #           Food Removal Methods
     # ==========================================
 
+    # Remove a logged food entry
+    #
+    # @param [Integer, String] food_log_id The ID of the food log, which
+    #   is the ID returned in the response when {#log_food} is called.
+    # @return [Hash] Empty hash denotes success
     def delete_logged_food(food_log_id)
       delete("/user/#{@user_id}/foods/log/#{food_log_id}.json")
     end
 
+    # Unmark a food as a favorite
+    #
+    # @param [Integer, String] food_id Food id
+    # @return [Hash] Empty hash denotes success
     def remove_favorite_food(food_id)
       delete("/user/#{@user_id}/foods/favorite/#{food_id}.json")
     end
@@ -75,15 +130,26 @@ module Fitgem
     #           Food Creation Methods
     # ==========================================
 
-    # Create a food defined by the following items in the options hash:
-    #   options[:name] (required) => Food name
-    #   options[:defaultFoodMeasurementUnitId] (required) => Unit id; default measurement unit; full list of units could be retrieved via a previous calls to Get Food Units
-    #   options[:defaultServingSize] (required) => Size of the default serving; nutritional values should be provided for this serving size
-    #   options[:calories] (required) => Calories in the default serving size
-    #   options[:formType] (optional) => Form type; (LIQUID or DRY)
-    #   options[:description] (optional) => Description
-    def create_food(options)
-      post("/foods.json", options)
+    # Create a new food and add it to fitbit
+    #
+    # @param [Hash] opts The data used to create the food
+    # @option opts [String] :name Food name
+    # @option opts [Integer, String] :defaultFoodMeasurementUnitId Unit id; typically
+    #   retrieved via previous calls to {#foods_on_date},
+    #   {#recent_foods}, {#favorite_foods}, {#frequent_foods},
+    #   {#find_food}, or {#foods_units}
+    # @option opts [Integer, String] :defaultServingSize The default
+    #   serving size of the food
+    # @option opts [Integer, String] :calories The number of calories in
+    #   the default serving size
+    # @option opts [String] :formType Form type; LIQUID or DRY - use
+    #   {Fitgem::FoodFormType#LIQUID} or {Fitgem::FoodFormType#DRY}
+    # @option opts [String] :description Food description
+    #
+    # @return [Hash] If successful, returns a hash containing
+    #   confirmation of the food that was added
+    def create_food(opts)
+      post("/foods.json", opts)
     end
   end
 end