fitgem 0.3.6 → 0.4.0

data/lib/fitgem/friends.rb

@@ -1,17 +1,27 @@
 module Fitgem
   class Client
-
     # ==========================================
     #          Friend Retrieval Methods
     # ==========================================
+
+    # Get a list of the current user's friends
+    #
+    # @return [Array] List of friends, each of which is a Hash
+    #   containing friend information
     def friends
       get("/user/#{@user_id}/friends.json")
     end
 
+    # Get the weekly leaderboard of friends' activities
+    #
+    # @return [Hash] Friends' information
     def weekly_leaderboard
       leaderboard('7d')
     end
 
+    # Get the monthly leaderboard of friends' activities
+    #
+    # @return [Hash] Friends' information
     def monthly_leaderboard
       leaderboard('30d')
     end
@@ -19,20 +29,41 @@ module Fitgem
     # ==========================================
     #       Invitation Management Methods
     # ==========================================
-    def invite_friend(options)
-      unless options[:email] || options[:user_id]
-        raise InvalidArgumentError.new "add_friend hash argument must include :email or :user_id"
+
+    # Create an invite for a user to connect with the current user as a friend
+    #
+    # In order to invite a user, either an :email or a valid :userId
+    # must be supplied in the +opts+ param hash.
+    #
+    # @param [Hash] opts The invite data
+    # @option opts [String] :email Email address of user to invite
+    # @option opts [String] :userId User ID of the user to invite
+    #
+    # @return [Hash]
+    def invite_friend(opts)
+      unless opts[:email] || opts[:user_id]
+        raise InvalidArgumentError.new "invite_friend hash argument must include :email or :user_id"
       end
       translated_options = {}
-      translated_options[:invitedUserEmail] = options[:email] if options[:email]
-      translated_options[:invitedUserId] = options[:user_id] if options[:user_id]
+      translated_options[:invitedUserEmail] = opts[:email] if opts[:email]
+      translated_options[:invitedUserId] = opts[:user_id] if opts[:user_id]
       post("/user/#{@user_id}/friends/invitations.json", translated_options)
     end
 
+    # Accept a friend invite
+    #
+    # @param [String] requestor_id The ID of the requestor that sent the
+    #   friend request
+    # @return [Hash]
     def accept_invite(requestor_id)
       respond_to_invite(requestor_id, true)
     end
 
+    # Decline a friend invite
+    #
+    # @param [String] requestor_id The ID of the requestor that sent the
+    #   friend request
+    # @return [Hash]
     def decline_invite(requestor_id)
       respond_to_invite(requestor_id, false)
     end
@@ -40,7 +71,7 @@ module Fitgem
     private
 
     def leaderboard(range)
-      get("/user/#{@user_id}/friends/leaderboard/#{range}.json")
+      get("/user/#{@user_id}/friends/leaders/#{range}.json")
     end
 
     def respond_to_invite(requestor_id, does_accept)
@@ -48,4 +79,4 @@ module Fitgem
       post("/user/#{@user_id}/friends/invitations/#{requestor_id}.json", options)
     end
   end
-end
+end

data/lib/fitgem/helpers.rb

@@ -1,7 +1,19 @@
 module Fitgem
   class Client
-
-    # Should return date as YYYY-MM-DD
+    # Format any of a variety of date types into the formatted string
+    # required when using the fitbit API.
+    #
+    # The date parameter can take several different kind of objects: a
+    # DateTime object, a Date object, a Time object or a String object.  Furthermore,
+    # the string object may be either the date in a preformatted string
+    # ("yyyy-MM-dd"), or it may be the string values "today" or
+    # "tomorrow".
+    #
+    # @param [DateTime, Date, Time, String] date The object to format into a
+    #   date string
+    # @raise [Fitgem::InvalidDateArgument] Raised when the object is
+    #   not a DateTime, Date, Time or a valid (yyyy-MM-dd) String object
+    # @return [String] Date in "yyyy-MM-dd" string format
     def format_date(date)
       if date.is_a? String
         case date
@@ -10,14 +22,16 @@ module Fitgem
           when 'yesterday'
             return (Date.today-1).strftime("%Y-%m-%d")
           else
+            unless date =~ /\d{4}\-\d{2}\-\d{2}/
+              raise Fitgem::InvalidDateArgument, "Invalid date (#{date}), must be in yyyy-MM-dd format"
+            end
             return date
         end
       elsif Date === date || Time === date || DateTime === date
         return date.strftime("%Y-%m-%d")
       else
-        raise Fitgem::InvalidArgumentError, "Date used must be a date/time object or a string in the format YYYY-MM-DD; current argument is a #{date.class}"
+        raise Fitgem::InvalidDateArgument, "Date used must be a date/time object or a string in the format YYYY-MM-DD; supplied argument is a #{date.class}"
       end
     end
-
   end
-end
+end

data/lib/fitgem/notifications.rb

@@ -1,47 +1,126 @@
 module Fitgem
   class Client
-    
-    def create_subscription(options={})
-      unless options[:type] && [:sleep,:body,:activities,:foods].include?(options[:type])
-        raise Error, 'Must include options[:type] (values are :activities, :foods, :sleep, and :body)'
-      end
-      base_url = "/user/#{@user_id}/#{options[:type].to_s}/apiSubscriptions"
-      post_subscription(base_url, options)
+    SUBSCRIBABLE_TYPES = [:sleep, :body, :activities, :foods, :all]
+
+    # Get a list of all subscriptions
+    #
+    # @param [Hash] opts Subscription query data
+    # @option opts [Integer, String] :type The type of subscription (valid
+    #   values are :activities, :foods, :sleep, :body, and :all). REQUIRED
+    #
+    # @return [Hash] Hash contain subscription information
+    # @since v0.4.0
+    def subscriptions(opts)
+      get make_subscription_url(opts), make_headers(opts)
     end
-    
-    def remove_subscription(options={})
-      unless options[:type] && [:sleep,:body,:activities,:foods].include?(options[:type])
-        raise Error, 'Must include options[:type] (values are :activities, :foods, :sleep, and :body)'
-      end
-      unless options[:subscription_id]
-        raise Error, "Must include options[:subscription_id] to delete a subscription"
-      end
-      base_url = "/user/#{@user_id}/#{options[:type].to_s}/apiSubscriptions"
-      url = finalize_subscription_url(base_url, options)
-      headers = {}
-      headers['X-Fitgem-Subscriber-Id'] = options[:subscriber_id] if options[:subscriber_id]
-      delete(url, headers)
+
+    # Creates a notification subscription
+    #
+    # @note You must check the HTTP response code to check the status of the request to add a subscription.  See {https://wiki.fitbit.com/display/API/Subscriptions-API} for information about what the codes mean.
+    #
+    # @param [Hash] opts The notification subscription data
+    # @option opts [Symbol] :type The type of subscription (valid
+    #   values are :activities, :foods, :sleep, :body, and :all). REQUIRED
+    # @option opts [Integer, String] :subscriptionId The subscription id 
+    #
+    # @return [Integer, Hash] An array containing the HTTP response code and
+    #   a hash containing confirmation information for the subscription.  
+    # @since v0.4.0
+    def create_subscription(opts)
+      resp = raw_post make_subscription_url(opts), EMPTY_BODY, make_headers(opts.merge({:use_subscription_id => true}))
+      [resp.code, extract_response_body(resp)]
     end
-    
+
+    # Removes a notification subscription
+    #
+    # @note You must check the HTTP response code to check the status of the request to remove a subscription.  See {https://wiki.fitbit.com/display/API/Subscriptions-API} for information about what the codes mean.
+    #
+    # @param [Hash] opts The notification subscription data
+    # @option opts [Symbol] :type The type of subscription to remove;
+    #   valid values are :activities, :foods, :sleep, :body, and :all).
+    #   REQUIRED
+    # @option opts [Integer, String] :subscription_id The id of the
+    #   subscription to remove.
+    # @option opts [Inteter, Stri)g] :subscriber_id The subscriber id of the client
+    #   application, created via {http://dev.fitbit.com}
+    #
+    # @return [Integer, Hash] An array containing the HTTP response code and
+    #   a hash containing confirmation information for the subscription.  
+    # @since v0.4.0
+    def remove_subscription(opts)
+      resp = raw_delete make_subscription_url(opts), make_headers(opts.merge({:use_subscription_id => true}))
+      [resp.code, extract_response_body(resp)]
+    end
+
     protected
-    
-    def finalize_subscription_url(base_url, options={})
-      url = base_url
-      if options[:subscription_id]
-        url += "/#{options[:subscription_id]}"
+
+    # Ensures that the type supplied is valid
+    #
+    # @param [Symbol] subscription_type The type of subscription;
+    #   valid values are (:sleep, :body, :activities, :foods, and
+    #   :all)
+    # @raise [Fitgem::InvalidArgumentError] Raised if the supplied type
+    #   is not valid
+    # @return [Boolean] 
+    def validate_subscription_type(subscription_type)
+      unless subscription_type && SUBSCRIBABLE_TYPES.include?(subscription_type)
+        raise Fitgem::InvalidArgumentError, "Invalid subscription type (valid values are #{SUBSCRIBABLE_TYPES.join(', ')})"
       end
-      if options[:subscription_response_format]
-        url += ".#{options[:subscription_response_format]}"
-      else
-        url += ".json"
+      true
+    end
+
+    # Create the headers hash for subscription management calls
+    #
+    # This method both adds approriate headers given what is in the
+    # options hash, as well as removes extraneous hash entries that are
+    # not needed in the headers of the request sent to the API.
+    #
+    # @param [Hash] opts The options for header creation
+    # @option opts [String] :subscriber_id The subscriber id of the client
+    #   application, created via {http://dev.fitbit.com}
+    # @return [Hash] The headers has to pass to the get/post/put/delete
+    #   methods
+    def make_headers(opts)
+      headers = opts.dup
+      if opts[:subscriber_id]
+        headers['X-Fitbit-Subscriber-Id'] = opts[:subscriber_id]
+        headers.delete :subscriber_id
       end
-      url
+
+      headers.delete :subscription_id if headers[:subscription_id]
+      headers.delete :type if headers[:type]
+      headers.delete :use_subscription_id if headers[:use_subscription_id]
+
+      headers
     end
-    
-    def post_subscription(base_url, options)
-      url = finalize_subscription_url(base_url, options)
-      post(url, options)
+
+    # Create the subscription management API url
+    #
+    # @param [Hash] opts The options on how to construct the
+    #   subscription API url
+    # @option opts [Symbol] :type The type of subscription;
+    #   valid values are (:sleep, :body, :activities, :foods, and
+    #   :all)
+    # @option opts [Symbol] :use_subscription_id If true, then
+    #   opts[:subscription_id] will be used in url construction
+    # @option opts [String] :subscription_id The id of the subscription
+    #   that the URL is for
+    # @return [String] The url to use for subscription management
+    def make_subscription_url(opts)
+      validate_subscription_type opts[:type]
+      path = if opts[:type] == :all
+               ""
+             else
+               "/"+opts[:type].to_s
+             end
+      url = "/user/#{@user_id}#{path}/apiSubscriptions"
+      if opts[:use_subscription_id]
+        unless opts[:subscription_id]
+          raise Fitgem::InvalidArgumentError, "Must include options[:subscription_id]"
+        end
+        url += "/#{opts[:subscription_id]}"
+      end
+      url += ".json"
     end
-    
   end
 end

data/lib/fitgem/sleep.rb

@@ -1,12 +1,50 @@
 module Fitgem
   class Client
-
     # ==========================================
     #          Sleep Retrieval Methods
     # ==========================================
+
+    # Get sleep data for specified date
+    #
+    # @param [DateTime, Date, String] date
+    # @return [Array] List of sleep items for the supplied date
     def sleep_on_date(date)
       get("/user/#{@user_id}/sleep/date/#{format_date(date)}.json")
     end
 
+    # ==========================================
+    #          Sleep Logging Methods
+    # ==========================================
+
+    # Log sleep data to fitbit for current user
+    #
+    # All aspects of the options hash are REQUIRED.
+    #
+    # @param [Hash] opts Sleep data to log
+    # @option opts [String] :startTime Hours and minutes in the format "HH:mm"
+    # @option opts [Integer, String] :duration Sleep duration, in miliseconds
+    # @option opts [DateTime, Date, String] :date Sleep log entry date;
+    #   if a string it must be in the yyyy-MM-dd format, or the values
+    #   'today' or 'tomorrow'
+    #
+    # @return [Hash] Summary of the logged sleep data
+    #
+    # @since v0.4.0
+    def log_sleep(opts)
+      post("/user/#{@user_id}/sleep.json", opts)
+    end
+
+    # Delete logged sleep data
+    #
+    # The sleep log id is the one returned when sleep data is recorded
+    # via {#log_sleep}.
+    #
+    # @param [Integer, String] Sleep log id
+    # @return [Hash] Empty hash denotes successful deletion
+    #
+    # @since v0.4.0
+    def delete_sleep_log(sleep_log_id)
+      delete("/user/#{@user_id}/sleep/#{sleep_log_id}.json")
+    end
   end
-end
+end

data/lib/fitgem/time_range.rb

@@ -5,47 +5,63 @@ module Fitgem
     # :base_date and :end_date OR by using :base_date and a :period
     # (supported periods are 1d, 7d, 30d, 1w, 1m, 3m, 6m, 1y, max)
     #
-    # Supported values for resource_path are:
+    # Supported values for +resource_path+ are:
+    #
     # Food:
-    # /foods/log/caloriesIn
+    #   /foods/log/caloriesIn
+    #   /foods/log/water
     # 
     # Activity:
-    # /activities/log/calories
-    # /activities/log/steps
-    # /activities/log/distance
-    # /activities/log/floors
-    # /activities/log/elevation
-    # /activities/log/minutesSedentary
-    # /activities/log/minutesLightlyActive
-    # /activities/log/minutesFairlyActive
-    # /activities/log/minutesVeryActive
-    # /activities/log/activeScore
-    # /activities/log/activityCalories
+    #   /activities/log/calories
+    #   /activities/log/steps
+    #   /activities/log/distance
+    #   /activities/log/floors
+    #   /activities/log/elevation
+    #   /activities/log/minutesSedentary
+    #   /activities/log/minutesLightlyActive
+    #   /activities/log/minutesFairlyActive
+    #   /activities/log/minutesVeryActive
+    #   /activities/log/activeScore
+    #   /activities/log/activityCalories
     # 
     # Sleep:
-    # /sleep/minutesAsleep
-    # /sleep/minutesAwake
-    # /sleep/awakeningsCount
-    # /sleep/timeInBed
+    #   /sleep/startTime
+    #   /sleep/timeInBed
+    #   /sleep/minutesAsleep
+    #   /sleep/awakeningsCount
+    #   /sleep/minutesAwake
+    #   /sleep/minutesToFallAsleep
+    #   /sleep/minutesAfterWakeup
+    #   /sleep/efficiency
     # 
     # Body:
-    # /body/weight
-    # /body/bmi
-    # /body/fat
+    #   /body/weight
+    #   /body/bmi
+    #   /body/fat
+    #
+    # @param [String] resource_path The resource path to get data for
+    #   (see note above)
+    # @param [Hash] opts The options to specify date ranges, etc.
+    # @option opts [DateTime, Date, String] :base_date The start date of the period
+    # @option opts [DateTime, Date, String] :end_date The end date of the period
+    # @option opts [String] :period The period (valid values: 1d, 7d, 30d, 1w, 1m, 3m, 6m, 1y, max)
     #
-    #  Examples
+    # @return [Hash] Hash containing an array of objects that match your
+    #   request
     #
-    #  * To get the floors traveled for the week of October 24th
-    #    data_by_time_range("/activities/log/floors", {:base_date => "2011-10-24", :period => "7d"})
+    # @example To get the floors traveled for the week of October 24th
+    #   data_by_time_range("/activities/log/floors", {:base_date => "2011-10-24", :period => "7d"})
     #
-    #  * To get all of the body weight logs from April 3rd until July 27th
-    #    data_by_time_range("/body/weight", {:base_date => "2011-03-03", :end_date => "2011-07-27"})
+    # @example To get all of the body weight logs from April 3rd until July 27th
+    #   data_by_time_range("/body/weight", {:base_date => "2011-03-03", :end_date => "2011-07-27"})
     #
-    def data_by_time_range(resource_path, options)
-      range_str = construct_date_range_fragment(options)
-      get("/user/#{@user_id}#{resource_path}/#{range_str}.json")
+    def data_by_time_range(resource_path, opts)
+      range = construct_date_range_fragment(opts)
+      get("/user/#{@user_id}#{resource_path}/#{range}.json")
     end
 
+    # protected
+
     def construct_date_range_fragment(options)
       range_str = "date/"
       if options[:base_date] && options[:period]
@@ -57,6 +73,6 @@ module Fitgem
       end
       range_str
     end
-    
+
   end
 end

data/lib/fitgem/units.rb

@@ -1,53 +1,90 @@
 module Fitgem
+  # Enumeration of valid unit systems that can be sent to fitbit
+  #
+  # Set the {Fitgem::Client#api_unit_system} property to one of
+  # these values to set the unit system used for all subsequent
+  # API calls.
+  #
+  # See {https://wiki.fitbit.com/display/API/API-Unit-System} for
+  # more information on how the various unit systems are used.
   class ApiUnitSystem
+    # US Units
+    #
+    # Used by default in fitgem
+    #
+    # @return [String]
     def self.US
       "en_US"
     end
 
+    # UK Units
+    #
+    # @return [String]
     def self.UK
-      "en_UK"
+      "en_GB"
     end
 
+    # Metric Units
+    #
+    # @return [String]
     def self.METRIC
       ""
     end
   end
 
+  # Enumeration of available distance units that may be used when
+  # logging measurements or activities that involve distance.
+  #
+  # See {https://wiki.fitbit.com/display/API/API-Distance-Unit} for
+  # more information about using distance units.
   class ApiDistanceUnit
+    # @return [String]
     def self.centimeters
       "Centimeter"
     end
 
+    # @return [String]
     def self.feet
       "Foot"
     end
 
+    # @return [String]
     def self.inches
       "Inch"
     end
 
+    # @return [String]
     def self.kilometers
       "Kilometer"
     end
 
+    # @return [String]
     def self.meters
       "Meter"
     end
 
+    # @return [String]
     def self.miles
       "Mile"
     end
 
+    # @return [String]
     def self.millimeters
       "Millimeter"
     end
 
+    # Steps are only valid distance units when logging walking or
+    # running activities.  The distance is computed from the stride
+    # length the user provides.
+    #
+    # @return [String]
     def self.steps
       "Steps"
     end
 
+    # @return [String]
     def self.yards
       "Yards"
     end
   end
-end
+end