fitgem 0.3.6 → 0.4.0

data/.gitignore

@@ -2,4 +2,6 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc/*
 test*.rb
+*.dmp

data/.rvmrc

@@ -1 +1 @@
-rvm 1.9.2@fitbit --create
+rvm ruby-1.9.3-p0@fitbit --create

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - 1.9.2
+  - 1.9.3

data/.yardopts

@@ -0,0 +1,7 @@
+--no-private
+--protected
+--exclude /spec
+--exclude /pkg
+-
+changelog.md
+LICENSE

data/README.md

@@ -1,101 +1,39 @@
-# Fitgem #
+# Fitgem [![Build Status](https://secure.travis-ci.org/whazzmaster/fitgem.png)](http://travis-ci.org/whazzmaster/fitgem)
 
-Provides access to fitbit.com data through their OAuth/REST API.  Without user authentication, any data that the a fitbit.com user has denoted as 'public' can be gathered.  If a user logs in via OAuth then all exposed data can be gathered.
+Provides access to fitbit.com data through their OAuth/REST API.  Fitgem can pull data with or without user authentication. Without user authentication, any data that the a fitbit.com user has denoted as 'public' can be gathered.  If a user logs in via OAuth then all exposed data can be gathered.
 
-The fitbit.com API is currently (March 2011) in BETA and is under development to extend its reach.  Since it is early in the lifecycle of the API I expect this gem to go through a number of revisions as we attempt to match the functionality of their platform.
+The fitbit.com API is currently (Late 2011) in BETA and is under development to extend its reach.  Since it is early in the lifecycle of the API I expect this gem to go through a number of revisions as we attempt to match the functionality of their platform.
 
 # Usage #
 
-If you've ever done any oauth client programming then the model will appear familiar.  Your first step, if haven't already, is to visit [https://dev.fitbit.com/](https://dev.fitbit.com/) and register your application to get your __consumer key__ and __consumer secret__ and set your __callback URL__, if appropriate for your app.  There's more documentation at the site so I won't belabor it here.
+Install fitgem:
+```
+$ gem install fitgem
+```
 
-Below I've included two sample scripts that use Fitgem::Client to retrieve data.  One shows how to do the initial authorization _without_ doing the callback; the other shows how to use saved values from that initial authorization to reconnect with the API and get subsequent information.
-
-	require 'fitgem'
-
-	consumer_key = 'your-app-consumer-key'
-	consumer_secret = 'your-app-consumer-secret'
-
-	client = Fitgem::Client.new({:consumer_key => consumer_key, :consumer_secret => consumer_secret})
-
-	request_token = client.request_token
-	token = request_token.token
-	secret = request_token.secret
-
-	puts "Go to http://www.fitbit.com/oauth/authorize?oauth_token=#{token} and then enter the verifier code below and hit Enter"
-	verifier = gets.chomp
-
-	access_token = client.authorize(token, secret, { :oauth_verifier => verifier })
-
-	puts "Verifier is: "+verifier
-	puts "Token is:    "+access_token.token
-	puts "Secret is:   "+access_token.secret
-
-After running this and successfully connecting with verifier string that is displayed by the Fitgem site, you can reconnect using the script below.  To do so, take the token and secret that were printed out from the script above and paste them in where appropriate.  In this example we are using the client to get the
-
-	require 'fitgem'
-
-	consumer_key = 'your-app-consumer-key'
-	consumer_secret = 'your-app-consumer-secret'
-	token = 'token-received-in-above-script'
-	secret = 'secret-received-in-above-script'
-	user_id = 'your-user-id' # may be similar to '12345N'
-
-	client = Fitgem::Client.new({:consumer_key => consumer_key, :consumer_secret => consumer_secret, :token => token, :secret => secret, :user_id => user_id})
-	access_token = client.reconnect(token, secret)
- 	p client.user_info
-
-You can use this script to learn about the data structures that are returned from different API calls.  Since this library always retrieves JSON responses and then parses it into Ruby structures, you can interrogate the response data with simple calls to hashes.
+[The wiki has information](https://github.com/whazzmaster/fitgem/wiki/The-OAuth-Process) on how to use fitgem in the OAuth handshake with [fitbit.com](http://www.fitbit.com)
 
 ## Usage in a Rails Application ##
 
-We've started to develop an example app using the fitgem client.  See [https://github.com/whazzmaster/fitgem-client](https://github.com/whazzmaster/fitgem-client) for more information.
+We've started to develop an example app using the fitgem client.  See [https://github.com/whazzmaster/fitgem-client](https://github.com/whazzmaster/fitgem-client) for more information or check out [the hosted version](http://www.fitbit-client.com). The fitgem-client project is evolving more slowly than the library itself, but work continues.
 
 # Subscriptions #
 
 The Fitbit API allows for you to set up notification subscription so that when values change (via automatic syncs with the fitbit device) your applications can be notified automatically.  You can set up a default subscription callback URL via the [Fitbit dev site](https://dev.fitbit.com/ 'Fitbit Developer Site') and then use the Subscriptions API to add or remove subscriptions for individual users.
 
-__Currently, notification management is experimental in this gem__.  We've built up code to add and remove specific types of subscriptions (foods, activities, sleep, body) but there seems to be some server-side issues with creating general, all-purpose subscriptions.
-
-The docs are very fuzzy on subscription support at the moment; we definitely plan on extending this support once the backend has matured (or the online docs have improved).
-
-# FAQs #
-
-## What About ruby-fitbit? ##
+__Currently, notification management is experimental in this gem__.  There is currently code to add, remove, and list subscriptions (foods, activities, sleep, body, and all collections).  
 
-There is a good looking gem called [ruby-fitbit](https://github.com/danmayer/ruby-fitbit "ruby-fitbit") that
-also aims to collect data from the site.  It was created before they released their REST API and uses screen-scraping to gather the data rather than through their API.  I looked into forking it and refactoring
-to use the new API but after looking through the code I felt it would be more of a total rewrite and so decided
-to create a new gem that I could design from scratch.
 
-## Why the Name Change? ##
+# FAQs 
+## What About ruby-fitbit?
 
-It turns out that Fitbit.com does not want people to create libraries or applications that incorporate the name 'fitbit'.  So, on May 12th I changed the name of the project/gem from 'fitbit' to 'fitgem'.
+There is a good looking gem called [ruby-fitbit](https://github.com/danmayer/ruby-fitbit "ruby-fitbit") that also aims to collect data from the site.  It was created before they released their REST API and uses screen-scraping to gather the data rather than through their API.  I looked into forking it and refactoring to use the new API but after looking through the code I felt it would be more of a total rewrite and so decided to create a new gem that I could design from scratch.
 
-# Changelog #
+## Why the Name Change?
 
-* 12 July, 2011:
-  * Added friends support (get friends, friend leaderboard, create invites, accept/reject invites)
-  * Added water support (get water data per date)
-  * Added sleep support (get sleep data per date)
-  * Added ability to update user profile information
-* 12 May, 2011:
-	* Changed name and all references of this project from 'fitbit' to 'fitgem'
-* 11 April, 2011:
-  * Fixed an issue where blank user id's are used and an error is thrown.
-  * Added support for creating/removing subscriptions (this support is experimental for now, more tests coming)
-* 24 March, 2011:
-  * Added logging of activities and foods
-  * Added ability to add favorite activities and foods
-  * Added ability to delete logged activities and foods, and remove favorite activities and foods
-  * Refactored data_by_time_range for more testability
-  * Added ability to query devices
-* 19 March, 2011:
-  * Updated auth client to support first-time auth and reconnections (if you have previously been authorized and received token/secret).
-  * Added 'named' retrieval of activities and foods (recent_, favorite_, frequent_)
-  * Added ability to log weight back to the site using the API
-* 18 March, 2001: First revision. Supports the auth process via oauth, and retrieval of user info and activities.
+It turns out that Fitbit.com does not want people to create libraries or applications that incorporate the name 'fitbit'.  So, on May 12th, 2011 I changed the name of the project/gem from 'fitbit' to 'fitgem'.
 
-# Notice #
+# Notice
 
 To be clear: __I am not employed by fitbit.com__.  I created this library to assist other ruby developers in creating interesting applications on top of fitbit.com's data store and device data stream.
 
@@ -113,4 +51,4 @@ The Fitbit REST API is in BETA right now, and so it will quite likely change ove
 
 ### Copyright ###
 
-Copyright (c) 2011 Zachery Moneypenny. See LICENSE.txt for further details.
+Copyright (c) 2011 Zachery Moneypenny. See LICENSE for further details.

data/Rakefile

@@ -1,2 +1,13 @@
 require 'bundler'
+require 'rspec/core/rake_task'
+
 Bundler::GemHelper.install_tasks
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  # Put spec opts in a file named .rspec in root
+end

data/changelog.md

@@ -0,0 +1,65 @@
+# @markup markdown
+# @author Zachery Moneypenny
+
+# fitgem changelog
+
+## v0.4.0 
+
+#### 2011-11-29 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* Added YARD documentation to thoroughly document code
+* DEPRECATED: <tt>Fitgem::Client#log_weight</tt> method, use <tt>Fitgem::Client#log_body_measurements</tt> instead.  
+  The new method allows you to log more than weight (bicep size, body fat %, etc.)
+* Added <tt>Fitgem::FoodFormType</tt> to be used in calls to <tt>Fitgem::Client#create_food</tt>
+* Added <tt>Fitgem::Client#log_sleep</tt> to log sleep data to fitbit
+* Added <tt>Fitgem::Client#delete_sleep_log</tt> to delete previously logged sleep data
+* Added <tt>Fitgem::Client#activities</tt> method to get a list of all activities
+* Added <tt>Fitgem::Client#activity_statistics</tt> method to get statistics for all logged activities
+* Added to documentation of supported endpoints for <tt>Fitgem::Client#data_by_time_range</tt>
+* Added unit tests for parameter validation for many methods
+* Overhauled notifications methods, including extensive documentation,
+  unit tests, refactoring, and a couple of bug fixes.  These methods now
+  return both the HTTP status code and the JSON response body.  See https://wiki.fitbit.com/display/API/Subscriptions-API
+  for information on how to interpret each of the error codes.
+* Added fitgem to travis-ci for continuous integration (http://travis-ci.org/#!/whazzmaster/fitgem)
+* Added fitgem to rubydoc.info (http://rubydoc.info/github/whazzmaster/fitgem/master/frames)
+* Updated README
+* Moved OAuth documentation from the README to the [fitgem wiki](https://github.com/whazzmaster/fitgem/wiki/The-OAuth-Process)
+
+## v0.3.6
+
+#### 2011-07-12 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* Added friends support (get friends, friend leaderboard, create invites, accept/reject invites)
+* Added water support (get water data per date)
+* Added sleep support (get sleep data per date)
+* Added ability to update user profile information
+
+## Previous Releases
+
+#### 2011-05-11 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* Changed name and all references of this project from 'fitbit' to 'fitgem'
+
+#### 2011-04-11 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* Fixed an issue where blank user id's are used and an error is thrown.
+* Added support for creating/removing subscriptions (this support is experimental for now, more tests coming)
+
+#### 2011-03-24 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* Added logging of activities and foods
+* Added ability to add favorite activities and foods
+* Added ability to delete logged activities and foods, and remove favorite activities and foods
+* Refactored data_by_time_range for more testability
+* Added ability to query devices
+
+#### 2011-03-19 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* Updated auth client to support first-time auth and reconnections (if you have previously been authorized and received token/secret).
+* Added 'named' retrieval of activities and foods (recent_, favorite_, frequent_)
+* Added ability to log weight back to the site using the API
+
+#### 2011-03-18 Zachery Moneypenny <fitgem@whazzmaster.com>
+
+* First revision. Supports the auth process via oauth, and retrieval of user info and activities.

data/fitgem.gemspec

@@ -12,24 +12,31 @@ Gem::Specification.new do |s|
   s.email       = ["fitgem@whazzmaster.com"]
   s.homepage    = "http://github.com/whazzmaster/fitgem"
   s.summary     = %q{OAuth client library to the data on fitbit.com}
-  s.description = %q{A client library to send and retrieve workout/weight data from fitbit.com}
+  s.description = %q{A client library to send and retrieve workout, weight, and diet data from fitbit.com}
 
   s.rubyforge_project = "fitgem"
+
   s.add_dependency "oauth"
+  s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
   s.add_development_dependency "guard"
   s.add_development_dependency "guard-rspec"
   s.add_development_dependency "rb-fsevent"
   s.add_development_dependency "growl"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "rdiscount"
 
   s.files         = [
     '.gitignore',
     '.rvmrc',
+    '.yardopts',
+    '.travis.yml',
     'Gemfile',
     'Guardfile',
     'LICENSE',
     'README.md',
     'Rakefile',
+    'changelog.md',
     'fitgem.gemspec',
     'lib/fitgem.rb',
     'lib/fitgem/version.rb',
@@ -38,6 +45,7 @@ Gem::Specification.new do |s|
     'lib/fitgem/client.rb',
     'lib/fitgem/devices.rb',
     'lib/fitgem/errors.rb',
+    'lib/fitgem/food_form.rb',
     'lib/fitgem/foods.rb',
     'lib/fitgem/friends.rb',
     'lib/fitgem/helpers.rb',
@@ -48,11 +56,17 @@ Gem::Specification.new do |s|
     'lib/fitgem/users.rb',
     'lib/fitgem/water.rb',
     'spec/fitgem_spec.rb',
-    'spec/spec_helper.rb'
+    'spec/spec_helper.rb',
+    'spec/fitgem_notifications_spec.rb',
+    'spec/fitgem_helper_spec.rb',
+    'spec/fitgem_constructor_spec.rb'
   ]
   s.test_files   = [
     'spec/fitgem_spec.rb',
-    'spec/spec_helper.rb'
+    'spec/spec_helper.rb',
+    'spec/fitgem_notifications_spec.rb',
+    'spec/fitgem_helper_spec.rb',
+    'spec/fitgem_constructor_spec.rb'
   ]
   s.require_paths = ["lib"]
 end

data/lib/fitgem.rb

@@ -1,7 +1,9 @@
 require 'json'
 require 'oauth'
-
 require 'fitgem/client'
 
+# Read/write data with the {http://www.fitbit.com Fitbit.com} OAuth API.
+#
+# @author Zachery Moneypenny
 module Fitgem
 end

data/lib/fitgem/activities.rb

@@ -1,49 +1,109 @@
 module Fitgem
   class Client
-
     # ==========================================
     #         Activity Retrieval Methods
     # ==========================================
+
+    # Get a list of all activities
+    #
+    # The returned list includes all public activities plus any
+    # activities that the current user created and logged
+    #
+    # @return [Hash] Hash tree of all activities
+    def activities
+      get("/activities.json")
+    end
+
+    # Get all of the logged activities on the supplied date
+    #
+    # @param [Datetime] date the date to retrieve logged activities for
+    # @return [Hash] the activities logged on the supplied date
     def activities_on_date(date)
       get("/user/#{@user_id}/activities/date/#{format_date(date)}.json")
     end
 
+    # Get a list of the frequently logged activities
+    #
+    # @return [Array] list of frequently logged activities
     def frequent_activities()
       get("/user/#{@user_id}/activities/frequent.json")
     end
 
+    # Get a list of recently logged activities
+    #
+    # @return [Array] list of of recently-logged activities
     def recent_activities()
       get("/user/#{@user_id}/activities/recent.json")
     end
 
+    # Get a list of activities marked as favorite by the user
+    #
+    # @return [Array] list of user-defined favorite activities
     def favorite_activities()
       get("/user/#{@user_id}/activities/favorite.json")
     end
 
-    def activity(id, options ={})
+    # Get the detailed information for a single activity
+    #
+    # @param [Integer, String] id The ID of the activity.  This ID is
+    #   typcially retrieved by browsing or searching the list of all
+    #   available activities.  Must be a numerical ID in either Integer
+    #   or String format.
+    # @return [Hash] a hash structure containing detailed information
+    #   about the activity
+    def activity(id)
       get("/activities/#{id}.json")
     end
 
+    # Get the activity statistics for the current user
+    #
+    # @return [Hash] Hash containing statistics for the activities that
+    # the user has logged
+    def activity_statistics
+      get("/user/#{@user_id}/activities.json")
+    end
+
     # ==========================================
     #         Activity Update Methods
     # ==========================================
 
-    # The following values are REQUIRED when logging an activity:
-    #     options[:activityId]      =>  The id of the activity, directory activity or intensity level activity. See activity types at http://wiki.fitbit.com/display/API/API-Log-Activity for more information.
-    #     options[:durationMillis]  =>  Activity duration in milliseconds
-    #     options[:startTime]       =>  Activity start time hours and minutes in the format HH:mm
-    #     options[:date]            =>  Set to today's date when not provided
-    #
-    # The following value is REQUIRED when logging directory activity, OPTIONAL otherwise
-    #     options[:distance]
-    #
-    # The following values are OPTIONAL when logging an activity:
-    #     options[:distanceUnit]    => One of Fitgem::ApiDistanceUnit values
-    #     options[:manualCalories]  => Number of calories determined manually
-    def log_activity(options)
-      post("/user/#{@user_id}/activities.json", options)
+    # Log an activity to fitbit
+    #
+    # @param [Hash] opts The options used to log the activity for the
+    #   current user
+    #
+    # @option opts [String] :activityId The id of the activity, directory activity or intensity 
+    #   level activity. See activity types at {http://wiki.fitbit.com/display/API/API-Log-Activity} for more 
+    #   information. This value OR activityName is REQUIRED for all calls.
+    # @option opts [String] :activityName The name of the activity to log.  This value OR activityId 
+    #   is REQUIRED for alls.
+    #
+    # @option opts [String, Integer] :durationMillis Activity duration in milliseconds.
+    #   Must be a numeric value in Integer or String format. This value is REQUIRED for all calls.
+    # @option opts [String] :startTime Activity start time, in the format "HH:mm" using hours
+    #   and seconds. Thie value is REQUIRED for all calls.
+    # @option opts [String] :date Activity date, in "yyyy-MM-dd" format. This value is REQUIRED for all calls.
+    #
+    # @option opts [String] :distance Distance traveled, a string in the format "X.XX".  This value is 
+    #   REQUIRED when logging a directory activity, OPTIONAL otherwise.
+    # @option opts [String, Integer] :manualCalories The number of calories to log against the activity. This
+    #   value is REQUIRED if using the activityName, OPTIONAL otherwise.
+    #
+    # @option opts [String] :distanceUnit One of {Fitgem::ApiDistanceUnit}. The "steps" units are available 
+    #   only for "Walking" and "Running" directory activities and their intensity levels
+    #
+    # @return [Hash] A hash with a summary of the logged activity
+    def log_activity(opts)
+      post("/user/#{@user_id}/activities.json", opts)
     end
 
+    # Mark an activity as a favorite
+    #
+    # @param [String, Integer] :activity_id The ID of the activity.  This ID is
+    #   typcially retrieved by browsing or searching the list of all
+    #   available activities.  Must be a numerical ID in either Integer
+    #   or String format.
+    # @return [Hash] Empty hash if successfully marked as a favorite
     def add_favorite_activity(activity_id)
       post("/user/#{@user_id}/activities/log/favorite/#{activity_id}.json")
     end
@@ -52,13 +112,24 @@ module Fitgem
     #         Activity Removal Methods
     # ==========================================
 
+    # Delete a logged activity
+    #
+    # @param [String, Integer] :activity_log_id The ID of a previously
+    #   logged activity. Note that this is NOT the activity ID itself, but
+    #   the ID of the logging of the activity (returned when you call
+    #   {#log_activity}).
+    # @return [Hash]
     def delete_logged_activity(activity_log_id)
       delete("/user/#{@user_id}/activities/#{activity_log_id}.json")
     end
 
+    # Unmark an activity as a favorite
+    #
+    # @param [String, Integer] :activity_id The activity ID of the
+    #   activity to remove as a favorite.
+    # @return [Hash]
     def remove_favorite_activity(activity_id)
       delete("/user/#{@user_id}/activities/log/favorite/#{activity_id}.json")
-
     end
   end
-end
+end