skittles 0.1.0

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Sticksnleaves LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,55 @@
+= Skittles
+
+Foursquare v2 REST API client library for Ruby
+
+== Documentation
+
+http://rdoc.info/github/anthonator/skittles/
+
+== Example
+
+  require 'rubygems'
+  require 'skittles'
+  
+  Skittles.configure do |config|
+    config.client_id     = '...'
+    config.client_secret = '...'
+    config.access_token  = '...'
+  end
+  
+  Skittles.venue('211152')
+
+== Contributing to Skittles
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Sticksnleaves LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+

data/lib/skittles.rb

@@ -0,0 +1,28 @@
+require File.expand_path('../skittles/version', __FILE__)
+require File.expand_path('../skittles/configuration', __FILE__)
+require File.expand_path('../skittles/api', __FILE__)
+require File.expand_path('../skittles/client', __FILE__)
+
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Skittles
+	extend Configuration
+	
+	# Alias for Skittles::Client.new
+	#
+	# @return {Skittles::Client}
+	def self.client(options = {})
+		Skittles::Client.new(options)
+	end
+	
+	# Delegate to Skittles::Client
+	def self.method_missing(method, *args, &block)
+		return super unless client.respond_to?(method)
+		client.send(method, *args, &block)
+	end
+	
+	# Delegate to Skittles::Client
+	def self.respond_to?(method)
+		return client.respond_to?(method) || super
+	end
+end

data/lib/skittles/api.rb

@@ -0,0 +1,23 @@
+require File.expand_path('../connection', __FILE__)
+require File.expand_path('../request', __FILE__)
+
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Skittles
+	# @private
+	class API
+		# @private
+		attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+		
+		# Creates a new API
+		def initialize(options = {})
+			options = Skittles.options.merge(options)
+			Configuration::VALID_OPTIONS_KEYS.each do |key|
+				send("#{key}=", options[key])
+			end
+		end
+		
+		include Connection
+		include Request
+	end
+end

data/lib/skittles/client.rb

@@ -0,0 +1,19 @@
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Skittles
+	# Wrapper for the Foursquare v2 REST API
+	#
+	# @note All methods have been separated into modules and follow the same grouping used in {http://developer.foursquare.com/docs/}.
+	# @see http://developer.foursquare.com/docs/index_docs.html
+	class Client < API
+		Dir[File.expand_path('../client/*.rb', __FILE__)].each { |f| require f }
+		
+		include Skittles::Client::Venue
+		include Skittles::Client::User
+		include Skittles::Client::Checkin
+		include Skittles::Client::Tip
+		include Skittles::Client::Photo
+		include Skittles::Client::Setting
+		include Skittles::Client::Special
+	end
+end

data/lib/skittles/client/checkin.rb

@@ -0,0 +1,71 @@
+module Skittles
+  class Client
+    # Define methods related to checkins.
+    # @see http://developer.foursquare.com/docs/checkins/checkins.html
+    module Checkin
+      # Allows a user to checkin to a place.
+      #
+      # @param broadcast [String] How much to broadcast this check-in, ranging from private (off-the-grid) to public,faceboook,twitter.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] venueId The venue where the user is checking in.
+      # @option options [String] venue Name of the venue.
+      # @option options [String] shout A message about a check-in. (140 character max.)
+      # @option options [String] ll Latitude and longitude of the user's location.
+      # @option options [Decimal] llAcc Accuracy of the user's latitude and longitude, in meters.
+      # @option options [Decimal] alt Altitude of the user's location, in meters.
+      # @option options [Decimal] altAcc Vertical accuracy of the user's location, in meters.
+      # @return [Hashie::Mash] A checkin object.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/checkins/add.html
+      def add_checkin(broadcast = 'private', options = {})
+        post("checkins/add", { :broadcast => broadcast }.merge(options)).checkin
+      end
+      
+      # Get details of a checkin.
+      #
+      # @param id [String] The ID of the checkin to retrieve additional information for.
+      # @return [Hashie::Mash] A complete checkin object.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/checkins/checkins.html
+      def checkin(id)
+        get("checkins/#{id}").checkin
+      end
+      
+      # Comment on a check-in.
+      #
+      # @param id [String] The id of the checkin to add a comment to.
+      # @param text [String] The text of the comment, up to 200 characters.
+      # @return [Hashie::Mash] The newly-created comment.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/checkins/addcomment.html
+      def checkin_addcomment(id, text)
+        post("checkins/#{id}/addcomment", { :text => text }).comment
+      end
+      
+      # Remove a comment from a checkin, if the acting user is the author or
+      # the owner of the checkin.
+      #
+      # @param checkin_id [String] The id of the checkin to remove a comment from.
+      # @param comment_id [String] The id of the comment to remove.
+      # @return [Hashie::Mash] The checkin, minus this comment.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/checkins/deletecomment.html
+      def checkin_deletecomment(checkin_id, comment_id)
+        post("checkins/#{checkin_id}/deletecomment", { :commentId => comment_id }).checkin
+      end
+      
+      # Returns a list of recent checkins from friends.
+      #
+      # @param ll [String] Latitude and longitude of the user's location, so response can include distance.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] Number of results to return, up to 100.
+      # @option options [Integer] Seconds after which to look for checkins.
+      # @return [Hashie::Mash] An array of checkin objects with user details present.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/checkins/recent.html
+      def recent_checkins(ll, options = {})
+        get("checkins/recent", { :ll => ll }.merge(options)).recent
+      end
+    end
+  end
+end

data/lib/skittles/client/photo.rb

@@ -0,0 +1,65 @@
+require 'uri'
+require 'net/http/post/multipart'
+
+module Skittles
+  class Client
+    # Define methods related to photos.
+    # @see http://developer.foursquare.com/docs/photos/photos.html
+    module Photo
+      # Get details of a photo.
+      #
+      # @param id [String] The id of the photo to retrieve additional information for.
+      # @return A complete photo object.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/photos/photos.html
+      def photo(id)
+        get("photos/#{id}").photo
+      end
+      
+      # Allows users to add a new photo to a checkin, tip, or a venue in
+      # general.
+      #
+      # @param file [String] Path to the file to upload.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] checkinId The id of a checkin owned by the user.
+      # @option options [String] tipId The ID of a tip owned by the user.
+      # @option options [String] venueId The ID of a venue, provided only when adding a public photo of the venue in general, rather than a private checkin or tip photo using the parameters above.
+      # @option options [String] broadcast Whether to broadcast this photo to twitter, facebook or both.
+      # @option options [String] ll Latitude and longitude of the user's location.
+      # @option options [Decimal] llAcc Accuracy of the user's latitude and longitude, in meters.
+      # @option options [Decimal] alt Altitude of the user's location, in meters.
+      # @option options [Decimal] altAcc Vertical accuracy of the user's location, in meters.
+      # @return The photo that was just created.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/photos/add.html
+      def add_photo(file, options = {})
+        resp = nil
+        options.merge!({
+          :file => UploadIO.new(file, 'image/jpeg', 'image.jpg'),
+          :oauth_token => access_token
+        })
+        uri = URI.parse("#{endpoint}/photos/add")
+        File.open(file) do |file|
+          req = Net::HTTP::Post::Multipart.new(uri.path, options)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true if uri.scheme == 'https'
+          resp = http.start do |http|
+            http.request(req)
+          end
+        end
+        case resp.code.to_i
+        when 200..299
+          return Hashie::Mash.new(Yajl::Parser.new.parse(resp.body)).response.photo
+        when 401
+          e = OAuth2::AccessDenied.new("Received HTTP 401 during request.")
+          e.response = resp
+          raise e
+        else
+          e = OAuth2::HTTPError.new("Received HTTP #{resp.code} during request.")
+          e.response = resp
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/skittles/client/setting.rb

@@ -0,0 +1,36 @@
+module Skittles
+  class Client
+    # Define methods related to settings.
+    # @see http://developer.foursquare.com/docs/settings/settings.html
+    module Setting
+      # Returns all settings of the active user.
+      #
+      # @return [Hashie::Mash] A setting object for the acting user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/settings/all.html
+      def all_settings
+        get('settings/all').settings
+      end
+      
+      # Change a setting for the given user.
+      #
+      # @param id [String] Name of setting to change, sendToTwitter, sendToFacebook, receivePings, receiveCommentPings.
+      # @param value [Integer] 1 for true, and 0 for false.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/settings/set.html
+      def set_setting(id, value)
+        post("settings/#{id}/set", { :value => value }).settings
+      end
+      
+      # Returns a setting for the acting user.
+      #
+      # @param id [String] The name of a setting.
+      # @return [Hashie::Mash] The value for this setting for the acting user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/settings/settings.html
+      def setting(id)
+        get("settings/#{id}").value
+      end
+    end
+  end
+end

data/lib/skittles/client/special.rb

@@ -0,0 +1,33 @@
+module Skittles
+  class Client
+    # Define methods related to specials.
+    # @see http://developer.foursquare.com/docs/specials/specials.html
+    module Special
+      # Gives details about a special, including text and unlock rules.
+      #
+      # @param id [String] Id of special to retrieve.
+      # @return [Hashie::Mash] A complete special.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/specials/specials.html
+      def special(id)
+        get("specials/#{id}")
+      end
+      
+      # Returns a list of specials near the current location.
+      #
+      # @note This is an experimental API.
+      # @param ll [String] Latitude and longitude to search near.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Decimal] llAcc Accuracy of latitude and longitude, in meters.
+      # @option options [Decimal] alt Altitude of the user's location, in meters.
+      # @option options [Decimal] altAcc Accuracy of the user's altitude, in meters.
+      # @option options [Integer] limit Number of results to return, up to 50.
+      # @return [Hashie::Mash] An array of specials being run at nearby venues.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/specials/search.html
+      def special_search(ll, options = {})
+        get('specials/search', { :ll => ll }.merge(options))
+      end
+    end
+  end
+end

data/lib/skittles/client/tip.rb

@@ -0,0 +1,79 @@
+module Skittles
+  class Client
+    # Define methods related to tips.
+    # @see http://developer.foursquare.com/docs/tips/tips.html
+    module Tip
+      # Allows a user to add a new tip at a venue.
+      #
+      # @param id [String] The venue where you want to add this tip.
+      # @param text [String] The text of the tip.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] url A URL related to this tip.
+      # @return [Hashie::Mash] The newly-added tip.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/tips/add.html
+      def add_tip(id, text, options = {})
+        post("tips/add", {
+          :venueId => id,
+          :text => text
+        }.merge(options)).tip
+      end
+      
+      # Gives details about a tip, including which users (especially friends)
+      # have marked the tip to-do or done.
+      #
+      # @param id [String] Id of tip to retrieve.
+      # @return [Hashie::Mash] A complete tip.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/tips/tips.html
+      def tip(id)
+        get("tips/#{id}").tip
+      end
+      
+      # Allows the acting user to mark a tip done.
+      #
+      # @param id [String] The tip you want to mark done.
+      # @return [Hashie::Mash] The marked to-do.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/tips/markdone.html
+      def tip_markdone(id)
+        post("tips/#{id}/markdone").todo
+      end
+      
+      # Allows you to mark a tip to-do.
+      #
+      # @param id [String] The tip you want to mark to-do.
+      # @return [Hashie::Mash] The newly-added to-do.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/tips/marktodo.html
+      def tip_marktodo(id)
+        post("tips/#{id}/marktodo").todo
+      end
+      
+      # Returns a list of tips near the area specified. 
+      #
+      # @param ll [String] Latitude and longitude of the user's location.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] limit Number of results to return, up to 500.
+      # @option options [Integer] offset Used to page through results.
+      # @option options [String] filter If set to friends, only show nearby tips from friends.
+      # @option options [String] query Only find tips matching the given term, cannot be used in conjunction with friends filter.
+      # @return [Hashie::Mash] An array of tips, each of which contain a user and venue.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/tips/search.html
+      def tip_search(ll, options = {})
+        get("tips/search", { :ll => ll }.merge(options)).tips
+      end
+      
+      # Allows you to remove a tip from your to-do list or done list.
+      #
+      # @param id [String] The tip you want to unmark.
+      # @return The tip being acted on.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/tips/unmark.html
+      def tip_unmark(id)
+        post("tips/#{id}/unmark")
+      end
+    end
+  end
+end

data/lib/skittles/client/user.rb

@@ -0,0 +1,179 @@
+module Skittles
+  class Client
+    # Define methods related to users.
+    # @see http://developer.foursquare.com/docs/users/users.html
+    module User
+      # Approve a pending friend request from another user.
+      #
+      # @param id [String] The user ID of a pending friend.
+      # @return [Hashie::Mash] A user object for the approved user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/approve.html
+      def approve_user(id)
+        post("users/#{id}/approve").user
+      end
+      # Returns badges for a given user.
+      #
+      # @param id [String] Id for user to view badges for.
+      # @return [Hashie::Mash] Hierarchical groups of badge ids or, for unlocked badges, badge unlock ids, as they are intended for display.
+      # @return [Hashie::Mash] A map of badge ids or badge unlock ids to a badge.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/badges.html
+      def badges(id)
+        get("users/#{id}/badges")
+      end
+      
+      # Returns a history of checkins for the authenticated user.
+      #
+      # @param id [String] For now, only "self" is supported.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] limit Number of results to return, up to 500.
+      # @option options [Integer] offset Used to page through results.
+      # @option options [Integer] afterTimestamp Retrieve the first results to follow these seconds since epoch.
+      # @option options [Integer] beforeTimestamp Retrieve the first results prior to these seconds since epoch.
+      # @return [Hashie::Mash] A count of items in check-ins.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/checkins.html 
+      def checkins(id = 'self', options = {})
+        get("users/#{id}/checkins").checkins
+      end
+      
+      # Denies a pending friend request from another user.
+      #
+      # @param id [String] The user ID of a pending friend.
+      # @return [Hashie::Mash] A user object for the denied user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/deny.html
+      def deny_user(id)
+        post("users/#{id}/deny").user
+      end
+      
+      # Sends a friend request to another user.
+      #
+      # @param id [String] The user ID to which a request will be sent.
+      # @return [Hashie::Mash] A user object for the pending user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/request.html
+      def friend_request(id)
+        get("users/#{id}").user
+      end
+      
+      # Shows a user the list of users with whom they have a pending friend
+      # request.
+      #
+      # @return [Hashie::Mash] An array of compact user objects.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/requests.html
+      def friend_requests
+        get("users/requests").requests
+      end
+      
+      # Returns an array of user's friends.
+      #
+      # @param id [String] Identity of the user to get friends of. Pass self to
+      # get friends of the acting user.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] limit Number of results to return, up to 500.
+      # @option options [Integer] offset Used to page through results.
+      # @return [Hashie::Mash] A count and items of compact user objects.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/friends.html
+      def friends(id, options = {})
+        get("users/#{id}/friends").friends
+      end
+      
+      # Changes whether the acting user will receive pings (phone
+      # notifications) when the specified user checks in. 
+      #
+      # @param id [String] The user ID of a friend.
+      # @param value [Boolean] True of false.
+      # @return [Hashie::Mash] A user object for the user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/setpings.html
+      def setpings(id, value = false)
+        post("users/#{id}/setpings", { :value => value }).user
+      end
+      
+      # Returns todos from a user.
+      #
+      # @param id Identity of the user to get todos for. Pass self to get todos of the acting user.
+      # @param sort One of recent or popular. Nearby requires geolat and geolong to be provided.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] ll Latitude and longitude of the user's location.
+      # @return [Hashie::Mash] A count and items of todos.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/todos.html
+      def todos(id, sort = 'recent', options = {})
+        get("users/#{id}/todos", { :sort => sort }.merge(options)).todos
+      end
+      
+      # Returns profile information for a given user, including selected badges
+      # and mayorships.
+      #
+      # @param id [String] Identity of the user to get details for. Pass self to get details of the acting user.
+      # @return [Hashie::Mash] Profile information for a given user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/users.html
+      def user(id)
+        get("users/#{id}").user
+      end
+      
+      # Cancels any relationship between the acting user and the specified
+      # user.
+      #
+      # @param id [String] Identity of the user to unfriend.
+      # @return [Hashie::Mash] A user.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/unfriend.html
+      def unfriend(id)
+        post("users/#{id}/unfriend").user
+      end
+      
+      # Helps a user locate friends.
+      #
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] phone A comma-delimited list of phone numbers to look for.
+      # @option options [String] email A comma-delimited list of email addresses to look for.
+      # @option options [String] twitter A comma-delimited list of Twitter handles to look for.
+      # @option options [String] twitterSource A single Twitter handle. Results will be friends of this user who use Foursquare.
+      # @option options [String] fbid A comma-delimited list of Facebook id's to look for.
+      # @option options [String] name A single string to search for in users' names.
+      # @return [Hashie::Mash] An array of compact user objects with Twitter or Facebook information and friend status.
+      # @requires_acing_user Yes
+      # @see http://developer.foursquare.com/docs/users/search.html
+      def user_search(options = {})
+        get('users/search', options).results
+      end
+      
+      # Returns tips from a user.
+      #
+      # @param id [String] Identity of the user to get tips from. Pass self to get tips of the acting user.
+      # @option options [Hash] A customizable set of options.
+      # @option options [String] sort One of recent, nearby, or popular. Nearby requires geolat and geolong to be provided.
+      # @option options [String] ll Latitude and longitude of the user's location.
+      # @option options [String] limit Number of results to return, up to 500.
+      # @option options [String] offset Used to page through results.
+      # @return [Hashie::Mash] A count and items of tips.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/tips.html
+      def user_tips(id, options = {})
+        get("users/#{id}/tips").tips
+      end
+      
+      # Returns a list of all venues visited by the specified user, along with
+      # how many visits and when they were last there.
+      #
+      # @note This is an experimental API.
+      # @param id [String] For now, only "self" is supported.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] beforeTimestamp Seconds since epoch.
+      # @option options [Integer] Seconds after epoch.
+      # @return [Hashie::Mash] A count and items of objects containing a beenHere count, lastHereAt timestamp, and venue compact venues.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/users/venuehistory.html
+      def venuehistory(id = 'self', options = {})
+        get("users/#{id}/venuehistory", options).venues
+      end
+    end
+  end
+end

data/lib/skittles/client/venue.rb

@@ -0,0 +1,186 @@
+module Skittles
+	class Client
+		# Defines methods related to venues.
+		# @see http://developer.foursquare.com/docs/venues/venues.html
+		module Venue
+		  # Adds a new venue.
+      #
+      # All fields are optional, but one of either a valid address or a
+      # geolat/geolong pair must be provided. It is recommended that a
+      # geolat/geolong pair is provided in every case.
+      #
+      # Optionally, a category(primarycategoryid) may be passed in to which
+      # this venue is to be assigned. A full list of categories using the
+      # {http://developer.foursquare.com/docs/venues/categories.html /categories}
+      # method.
+      #
+      # @param name [String] The name of the venue.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] address The address of the venue.
+      # @option options [String] crossStreen The nearest intersecting street or streets.
+      # @option options [String] city The city name where this venue is.
+      # @option options [String] state The nearest state or province to the venue.
+      # @option options [String] zip The zip or postal code for the venue.
+      # @option options [String] phone The phone number of the venue.
+      # @option options [String] ll Latitude and longitude of the venue, as accurate as is known.
+      # @option options [String] primaryCategoryId The id of the category to which you want to assign this venue.
+      # @return [Hashie::Mash] Details about the venue that was just added.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/venues/add.html
+      def add_venue(name, options = {})
+        post('venues/add', { :name => name }.merge(options)).venue
+      end
+      
+		  # Returns a hierarchical list of categories applied to venues. Note
+      # that top-level categories do not have ids because they cannot be
+      # assigned to a venue.
+      #
+      # Category images that come down through the API are available in three
+      # sizes:
+      # * 32 x 32 (default)
+      # * 64 x 64
+      # * 256 x 256
+      # @return [Hashie::Mash] A heirarchical list of categories applied to venues.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/venues/categories.html
+      def categories
+        get('venues/categories').categories
+      end
+      
+      # Allows a user to indicated a venue is incorrect in some way.
+      #
+      # @param id [String] The venue id for which an edit is being proposed.
+      # @param problem [String] One of mislocated, closed, duplicate.
+      # @require_acting_user Yes
+      # @see http://developer.foursquare.com/docs/venues/flag.html
+      def flag_venue(id, problem)
+        post("venues/#{id}/flag", { :problem => problem })
+        nil
+      end
+      
+			# Provides a count of how many people are at a given venue, plus the
+			# first page of the users there, friends-first, and if the current user
+			# is authenticated.
+			#
+			# @note This is an experimental API.
+			# @param id [String] Id of a venue to retrieve.
+			# @param options [Hash] A customizable set of options.
+			# @option options [Integer] limit Number of results to return, up to 500.
+			# @option options [Integer] offset Used to page through results.
+			# @option options [Integer] afterTimestamp Retrieve the first results to follow these seconds since epoch.
+			# @return [Hashie::Mash] A count of items where items are checkins.
+			# @requires_acting_user No
+			# @see http://developer.foursquare.com/docs/venues/herenow.html 
+			def herenow(id, options = {})
+			  get("venues/#{id}/herenow", options).hereNow
+			end
+			
+			# Returns photos for a venue.
+      #
+      # @param id [String] The venue you want photos for.
+      # @param group [String] One of checkin, venue or multi (for both).
+      # @param  options [Hash] A customizable set of options.
+      # @option options [Integer] limit Number of results to return, up to 500.
+      # @option options [Integer] offset Used to page through results.
+      # @return [Hashie::Mash] A count of items of photo.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/venues/photos.html
+      def photos(id, group = 'checkin', options = {})
+        get("venues/#{id}/photos", {:group => group }.merge(options)).photos
+      end
+      
+      # Allows you to propose a change to a venue.
+      #
+      # @param id [String] The venue id for which an edit is being proposed.
+      # @param name [String] The name of the venue.
+      # @param address [String] The address of the venue.
+      # @param city [String] The city name where the venue is.
+      # @param state [String] The nearest state or province to the venue.
+      # @param zip [String] The zip or postal code for the venue.
+      # @param ll [String] Latitude and longitude of the venue's location, as accurate as is known.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] crossStreet The nearest intersecting street or streets.
+      # @option options [String] phone The phone number of the venue.
+      # @option options [String] primaryCategoryId The id of the category to which you want to assign this venue.
+      # @return nil
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/venues/proposeedit.html
+      def proposeedit(id, name, address, city, state, zip, ll, options = {})
+        post("venues/#{id}/proposeedit", {
+          :name => name,
+          :address => address,
+          :city => city,
+          :state => state,
+          :zip => zip,
+          :ll => ll
+        }.merge(options))
+        nil
+      end
+			
+			# Gives details about a venue, including location, mayorship, tags, tips,
+      # specials and category.
+      #
+      # Authenticated users will also receive information about who is here now.
+      #
+      # If the venue id given is one that has been merged into another "master"
+      # venue, the response will show data about the "master" instead of giving
+      # you an error.
+      #
+      # @param id [String] Id of a venue to retrieve.
+      # @return [Hashie::Mash] Details about a venue, including location, mayorship, tags, tips, specials, and category.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/venues/venues.html 
+      def venue(id)
+        get("venues/#{id}").venue
+      end
+      
+      # Allows a user to mark a venue to-do, with optional text.
+      #
+      # @param id The venue you want to mark to-do.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] text The text of the tip.
+      # @return [Hashie::Mash] The newly-added to-do, which contains a tip created implicitly.
+      # @requires_acting_user Yes
+      # @see http://developer.foursquare.com/docs/venues/marktodo.html
+      def venue_marktodo(id, options = {})
+        post("venues/#{id}/marktodo").todo
+      end
+			
+			# Returns a list of venues near the current location, optionally matching
+			# the search term.
+			#
+			# If lat and long is provided, each venue includes a distance. If
+			# authenticated, the method will return venue metadata related to you and
+			# your friends. If you do not authenticate, you will not get this data. 
+			#
+			# @param ll [String] Latitude and longitude of the user's location, so response can include distance.
+			# @param options [Hash] A customizable set of options.
+			# @option options [Decimal] llAcc Accuracy of latitude and longitude, in meters.
+			# @option options [Decimal] alt Altitude of the user's location, in meters.
+			# @option options [Decimal] altAcc Accuracy of the user's altitude, in meters.
+			# @option options [String] query A search term to be applied against titles.
+			# @option options [Integer] limit Number of results to return, up to 50.
+			# @option options [String] intent Indicates your intent in performing the search.
+			# @return [Hashie::Mash] An array of objects representing groups of venues.
+			# @requires_acting_user No
+			# @see http://developer.foursquare.com/docs/venues/search.html 
+			def venue_search(ll, options = {})
+			  get('venues/search', { :ll => ll }.merge(options)).groups
+			end
+			
+			# Returns tips for a venue.
+      #
+      # @param id [String] The venue you want tips for.
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] sort One of recent or popular.
+      # @option options [Integer] limit Number of results to return, up to 500.
+      # @option options [Integer] offset Used to page through results.
+      # @return [Hashie::Mash] A count of items of tips.
+      # @requires_acting_user No
+      # @see http://developer.foursquare.com/docs/venues/tips.html
+      def venue_tips(id, options = {})
+        get("venues/#{id}/tips", options).tips
+      end
+		end
+	end
+end

data/lib/skittles/configuration.rb

@@ -0,0 +1,69 @@
+# Adapted from the Ruby Twitter gem.
+# @see https://github.com/jnunemaker/twitter
+module Skittles
+	# Defines constants and methods related to configuration.
+	module Configuration
+		# An array of valid keys in the options hash when configuring a {Flixated::API}.
+		VALID_OPTIONS_KEYS = [
+			:access_token,
+			:authorization_endpoint,
+			:client_id,
+			:client_secret,
+			:endpoint,
+			:proxy,
+			:user_agent
+		].freeze
+	
+		# By default, don't set a user access token.
+		DEFAULT_ACCESS_TOKEN = nil.freeze
+		
+		# The endpoint that will be used to authorize a user if none is set.
+		DEFAULT_AUTHORIZATION_ENDPOINT = 'https://foursquare.com/oauth2/authenticate'.freeze
+		
+		# By default, don't set a client id.
+		DEFAULT_CLIENT_ID = nil.freeze
+		
+		# By default, don't set a cliet secret.
+		DEFAULT_CLIENT_SECRET = nil.freeze
+		
+		# The endpoint that will be used to connect if none is set.
+		DEFAULT_ENDPOINT = 'https://api.foursquare.com/v2'.freeze
+		
+		# By default, don't set a proxy server.
+		DEFAULT_PROXY = nil.freeze
+		
+		# The user agent that will be setn to the API endpoint if none is set.
+		DEFAULT_USER_AGENT = "skittles gem v#{Skittles::VERSION}".freeze
+		
+		# @private
+		attr_accessor(*VALID_OPTIONS_KEYS)
+		
+		# When this module is extended, set all configuration options to their default values.
+		def self.extended(base)
+			base.reset
+		end
+		
+		# Convenience method to allow configuration options to be set in a block.
+		def configure
+			yield self
+		end
+		
+		# Create a hash of options and their values.
+		def options
+			VALID_OPTIONS_KEYS.inject({}) do |option,key|
+				option.merge!(key => send(key))
+			end
+		end
+		
+		# Reset all configuration options to default.
+		def reset
+			self.access_token           = DEFAULT_ACCESS_TOKEN
+			self.authorization_endpoint = DEFAULT_AUTHORIZATION_ENDPOINT
+			self.client_id              = DEFAULT_CLIENT_ID
+			self.client_secret          = DEFAULT_CLIENT_SECRET
+			self.endpoint               = DEFAULT_ENDPOINT
+			self.proxy                  = DEFAULT_PROXY
+			self.user_agent             = DEFAULT_USER_AGENT
+		end
+	end
+end

data/lib/skittles/connection.rb

@@ -0,0 +1,19 @@
+require 'oauth2'
+
+module Skittles
+	# @private
+	module Connection
+		private
+		  def connection
+		  	options = {
+		  		:site => endpoint
+		  	}
+		  	puts
+		  	client = OAuth2::Client.new(client_id, client_secret, options)
+		  	oauth_token = OAuth2::AccessToken.new(client, access_token)
+		  	
+		  	oauth_token.token_param = 'oauth_token'
+		  	oauth_token
+		  end
+	end
+end

data/lib/skittles/request.rb

@@ -0,0 +1,52 @@
+require 'uri'
+require 'yajl'
+require 'hashie'
+
+module Skittles
+	module Request
+		# Perform an HTTP GET request
+		def get(path, options = {}, raw = false)
+			request(:get, path, options, raw)
+		end
+		
+		# Performs an HTTP POST request
+		def post(path, options = {}, raw = false)
+			request(:post, path, options, raw)
+		end
+		
+		# Performs an HTTP PUT request
+		def put(path, options = {}, raw = false)
+		  request(:put, path, options, raw)
+		end
+		
+		# Performs an HTTP DELETE request
+		def delete(path, options = {}, raw = false)
+		  request(:delete, path, options, raw)
+		end
+		
+		private
+		  #Perform an HTTP request
+		  def request(method, path, options, raw)
+		  	headers = {
+		  		'User-Agent' => user_agent
+		  	}
+		  	
+		  	options.merge!({
+		  		:client_id     => client_id,
+		  		:client_secret => client_secret
+		  	})
+		  	response = connection.request(method, paramify(path, options), headers)
+		  	
+		  	unless raw
+		  		result = Yajl::Parser.new.parse(response)
+		  	end
+		  	
+		  	raw ? response : Hashie::Mash.new(result).response
+		  end
+		  
+		  # Encode path and turn params into HTTP query.
+      def paramify(path, params)
+        URI.encode("#{path}?#{params.map { |k,v| "#{k}=#{v}" }.join('&')}")
+      end
+	end
+end

data/lib/skittles/version.rb

@@ -0,0 +1,3 @@
+module Skittles
+	VERSION = '0.1.0'
+end

data/spec/skittles_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Skittles" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'skittles'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,253 @@
+--- !ruby/object:Gem::Specification 
+name: skittles
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Anthony Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-22 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: oauth2
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yajl-ruby
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: hashie
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.10
+  type: :development
+  prerelease: false
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.6.4
+  type: :development
+  prerelease: false
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  name: oauth2
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *id009
+- !ruby/object:Gem::Dependency 
+  name: yajl-ruby
+  requirement: &id010 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *id010
+- !ruby/object:Gem::Dependency 
+  name: hashie
+  requirement: &id011 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *id011
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id012 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.5.0
+  type: :development
+  prerelease: false
+  version_requirements: *id012
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id013 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.10
+  type: :development
+  prerelease: false
+  version_requirements: *id013
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id014 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id014
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  requirement: &id015 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id015
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id016 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.6.4
+  type: :development
+  prerelease: false
+  version_requirements: *id016
+description: Foursquare v2 REST API client library for Ruby
+email: anthony@sticksnleaves.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- lib/skittles.rb
+- lib/skittles/api.rb
+- lib/skittles/client.rb
+- lib/skittles/client/checkin.rb
+- lib/skittles/client/photo.rb
+- lib/skittles/client/setting.rb
+- lib/skittles/client/special.rb
+- lib/skittles/client/tip.rb
+- lib/skittles/client/user.rb
+- lib/skittles/client/venue.rb
+- lib/skittles/configuration.rb
+- lib/skittles/connection.rb
+- lib/skittles/request.rb
+- lib/skittles/version.rb
+- LICENSE.txt
+- README.rdoc
+- spec/skittles_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/anthonator/skittles
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3194088974280100972
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Foursquare v2 REST API client library for Ruby
+test_files: 
+- spec/skittles_spec.rb
+- spec/spec_helper.rb