foursquare 0.2.1 → 0.3.0

data/History

@@ -1,3 +1,10 @@
+== 0.3.0 March 5, 2010
+* oauth support
+* method_missing api mapping
+
+== 0.2.1 February 17th, 2010
+* added post_install_message
+
 == 0.2.0 February 7th, 2010
 * updated methods to reflect updates to Foursquare API
 * added validations

data/README.rdoc

@@ -1,51 +1,93 @@
 == foursquare
 
-A simple Ruby Gem wrapper for the Foursquare API.
+A simple Ruby Gem wrapper for the Foursquare API. With OAuth authentication.
 
 == install
-	
-	gem install foursquare
-		
+  
+  gem install foursquare
+    
 == example
-	
-	require 'rubygems'
-	require 'foursquare'
   
-  # foursquare's site uses email as the user name
-	fq = Foursquare.new('username_or_phone','password')
-
-	fq.test
-
-	fq.venues(geolat, geolong, {:limit=>10,:q=>'pizza'})
-	fq.tips(geolat,geolong,{:limit=>10})
-	fq.checkins({:geolat=>'',:geolong=>''})
-	fq.checkin(vid,venue,shout,{:private=>0,:twitter=>0,:facebook=>1,:geolat=>'12.03',:geolong=>'-123.33'})
-	fq.history({:limit=>10})
-	fq.user_details(user_id,{:badges=>0,:mayor=>0})
-	fq.friends({:uid=>99999})
-	fq.venue_details(venue_id)
-	fq.add_venue(name,address,cross_street,city,state,options)
-	fq.propose_edit(venue_id,name,address,cross_street,city,state,options)
-	fq.flag_venue_as_closed(venue_id)
-	fq.add_tip(venue_id,text,{:type=type})
-	fq.mark_tip_as_todo(tid)
-	fq.mark_tip_as_done(tid)
-	fq.friend_requests
-	fq.friend_approve(uid)
-	fq.friend_deny(uid)
-	fq.request_friend(uid)
-	fq.find_friends_by_name('Bugs Bunny')
-	fq.find_friends_by_phone('8675309')
-	fq.find_friends_by_twitter('github')
-	fq.set_pings('self','goodnight')
-
-
-  # Foursquare is moving the API to geolat/geolong and removing the concept of cities
-	fq.cities	
-	fq.check_city(geolat, geolong)
-	fq.switch_city(city_id)	
-	fq.friend_checkins({:geolat=>'',:geolong=>''})
-	
+  require 'rubygems'
+  require 'foursquare'
+  
+  oauth_key 'your_key'
+  oauth_secret = 'your_secret'
+  
+  oauth = Foursquare::OAuth.new(oauth_key, oauth_secret)
+  
+  request_token = oauth.request_token.token
+  request_secret = oauth.request_token.secret
+  
+  # redirecting user to foursquare to authorize
+  oauth.request_token.authorize_url
+  
+  # foursquare redirects back to your callback url, passing the verifier in the url params
+  
+  access_token, access_secret = oauth.authorize_from_request(request_token, request_secret, verifier)
+  
+  # save the user's access token and secret
+  
+  
+  oauth = Foursquare::OAuth.new(oauth_key, oauth_secret)
+  oauth.authorize_from_access(access_token, access_secret)
+  foursquare = Foursquare::Base.new(oauth)
+  
+  foursquare.test
+  
+  foursquare.venues :geolat => geolat, :geolong => geolong, :limit => 10, :q => 'pizza'
+  foursquare.tips :geolat => geolat, :geolong => geolong, :limit => 10
+  foursquare.checkins :geolat => geolat, :geolong => geolong
+  
+  checkin = {
+    :vid => vid,
+    :shout => "this is what i'm up to",
+    :venue => "Cohabitat",
+    :private => 0,
+    :twitter => 0,
+    :geolat => geolat,
+    :geolong => geolong
+  }
+  
+  # these all do the same thing
+  # the response is a hashie object built from the checkin json.  so you can do new_checkin.shout
+  new_checkin = foursquare.checkin(checkin)
+  new_checkin.class
+  => Hashie::Mash
+  new_checkin
+  => {...checkin hashie...}
+  new_checkin = foursquare.send('checkin=', checkin)
+  new_checkin.class
+  => Hash
+  new_checkin
+  => {'checkin' => {...}}
+  new_checkin = foursquare.api(:checkin=, checkin)
+  new_checkin.class
+  => Hashie::Mash
+  new_checkin
+  => {:checkin => {...}}
+  
+  foursquare.history :limit => 10
+  foursquare.api(:history, :limit => 10).checkins
+  foursquare.user :uid => user_id :badges => 0
+  foursquare.user # currently authenticated user
+  foursquare.friends :uid => 99999
+  foursquare.venue :vid => venue_id
+  foursquare.addvenue :name => name, :address => address, :city => city, ...
+  foursquare.venue_proposeedit :venue_id => venue_id, :name => name, :address => address, :city => ...
+  foursquare.venue_flagclosed :vid => venue_id
+  foursquare.addtip :vid => 12345, :tip => 'here is a tip'
+  foursquare.tip_marktodo :tid => tip_id
+  foursquare.tip_markdone :tid => tip_id
+  foursquare.friend_requests
+  foursquare.friend_approve :uid => friend_id
+  foursquare.friend_deny :uid => friend_id
+  foursquare.friend_sendrequest :uid => friend_id
+  foursquare.findfriends_byname :q => search_string
+  foursquare.findfriends_byphone :q => '555 123'
+  foursquare.findfriends_bytwitter :q => twitter_name
+  foursquare.settings_setping :uid => user_id, :self => global_ping_status
+  
 == license 
 
 (the MIT license)

data/Rakefile

@@ -6,12 +6,12 @@ require 'spec/rake/spectask'
 
 spec = Gem::Specification.new do |s|
   s.name = "foursquare"
-  s.version = "0.2.1"
-  s.authors = ['Jeremy Welch', 'Thomas Hanley']
+  s.version = "0.3.0"
+  s.authors = ['Jeremy Welch', 'Thomas Hanley', 'Elise Wood']
   s.email = "hello@jeremyrwelch.com"
   s.homepage = "http://foursquare.rubyforge.org"
   s.description = s.summary = "A simple Ruby wrapper for the Foursquare API"
-  s.post_install_message = "NOTE: This version of the Foursquare Gem has significant changes to the way methods are called. Please review the examples in the README"
+  s.post_install_message = "NOTE: This version of the Foursquare Gem has added OAuth support. Basic Auth has been deprecated. Also significant changes have bee made to the way methods are called. Please review the examples in the README."
   
   s.platform = Gem::Platform::RUBY
   s.has_rdoc = true

data/lib/foursquare.rb

@@ -1,197 +1,226 @@
 require 'rubygems'
 require 'httparty'
+require 'hashie'
+require 'oauth'
 
-class Foursquare
-  # Current Version of the Foursquare API: http://groups.google.com/group/foursquare-api/web/api-documentation
-  
-  include HTTParty
-  base_uri 'api.foursquare.com'
-  format :xml
-
-  # auth user
-  # TODO: add OAuth support (follow Twitter gem from jnunemaker http://github.com/jnunemaker/twitter)
-  def initialize(user="",pass="", options={})
-    self.class.basic_auth user, pass
-    self.class.headers(options[:headers]) if options.has_key?(:headers)
-  end
-
-  # =========================
-  # = No Auth Required Methods =
-  # =========================
-  # test for response from Foursquare
-  def test 
-      self.class.get("/v1/test") 
-  end
-
-  def venues(geolat, geolong, options={})
-      options.merge!({:geolat=>geolat, :geolong=>geolong})
-      self.class.get("/v1/venues", :query=>options)
-  end
+Hash.send :include, Hashie::HashExtensions
 
-  def tips(geolat,geolong,options={})
-      options.merge!({:geolat=>geolat, :geolong=>geolong})
-      self.class.get("/v1/tips", :query=>options)
-  end
 
-  # =========================
-  # = Auth Required Methods =
-  # =========================
-  def checkins(options={})
-    self.class.get("/v1/checkins",:query=>options)
-  end 
 
-  def checkin(vid=nil,venue=nil,shout=nil,options={})
-    unless vid || venue || shout
-      raise ArgumentError, "A vid or venue or shout is required to checkin", caller
+module Foursquare
+  class OAuth
+    def initialize(ctoken, csecret, options={})
+      @consumer_token, @consumer_secret = ctoken, csecret
     end
-    options.merge!({:vid=>vid, :venue=>venue, :shout=>shout})    
-    self.class.post("/v1/checkin", :body => options)       
-  end
   
-  def history(options={})
-    limit = options.delete(:limit) || 10
-    uri = "/v1/history?l=#{limit}"
-    sinceid = options.delete(:sinceid)
-    uri << "&sinceid=#{sinceid}" unless sinceid.nil?
-    self.class.get(uri)
-  end
+    def consumer
+      return @consumer if @consumer
+      @consumer = ::OAuth::Consumer.new(@consumer_token, @consumer_secret, {
+        :site               => "http://foursquare.com",
+        :scheme             => :header,
+        :http_method        => :post,
+        :request_token_path => "/oauth/request_token",
+        :access_token_path  => "/oauth/access_token",
+        :authorize_path     => "/oauth/authorize",
+        :proxy              => (ENV['HTTP_PROXY'] || ENV['http_proxy'])
+      })
+    end
   
-  def user_details(user_id,options={})
-    unless user_id
-      raise ArgumentError, "A user_id is required to get details about a user", caller
-    end    
-    self.class.get("/v1/user",:query=>options)
-  end
+    def set_callback_url(url)
+      clear_request_token
+      request_token(:oauth_callback => url)
+    end
+    
+    def request_token(options={})
+      @request_token ||= consumer.get_request_token(options)
+    end
   
-  def friends(options={})
-    self.class.get("/v1/friends",:query=>options)
-  end
+    def authorize_from_request(request_token, request_secret, verifier)
+      request_token = ::OAuth::RequestToken.new(consumer, request_token, request_secret)
+      access_token = request_token.get_access_token(:oauth_verifier => verifier)
+      @atoken, @asecret = access_token.token, access_token.secret
+    end
   
-  def venue_details(venue_id)                        
-    self.class.get("/v1/venue?vid=#{venue_id}")
-  end
-
-  # city_id has been removed from API
-  def add_venue(name,address,cross_street,city,state,options={})
-    unless name && address && cross_street && city && state
-      raise ArgumentError, "A venue's name, address, cross_street, city, state are required to add_venue", caller
-    end                            
-    options.merge!({:name=>name, :address=>address, :cross_street=>cross_street, :city=>city, :state=>state})
-    self.class.post("/v1/addvenue", :body => options)
-  end
+    def access_token
+      @access_token ||= ::OAuth::AccessToken.new(consumer, @atoken, @asecret)
+    end
   
-  def propose_edit(venue_id,name,address,cross_street,city,state,options={})
-    unless venue_id && name && address && cross_street && city && state
-      raise ArgumentError, "A venue's venue_id, name, address, cross_street, city, state are required to propose_edit", caller
+    def authorize_from_access(atoken, asecret)
+      @atoken, @asecret = atoken, asecret
     end
-    options.merge!({:venue_id=>venue_id,:name=>name, :address=>address, :cross_street=>cross_street, :city=>city, :state=>state})
-    self.class.post("/v1/venue/proposeedit", :body => options)
-  end
-     
-  def flag_venue_as_closed(venue_id)
-    unless venue_id
-      raise ArgumentError, "A venue's venue_id is required to flag as closed", caller
+    
+    private
+    
+    def clear_request_token
+      @request_token = nil
     end
-    self.class.post("/v1/venue/flagclosed?vid=#{venue_id}")
-  end
-  
-  # ===============
-  # = TIP methods =
-  # ===============
-  def add_tip(venue_id,text,options={})
-    unless venue_id && text
-      raise ArgumentError, "venue_id and text are required to add_tip", caller
-    end                      
-    options.merge!({:vid=>venue_id, :text=>text})
-    self.class.post("/v1/addtip", :body => options)
   end
   
-  def mark_tip_as_todo(tid)
-    unless tid 
-      raise ArgumentError, "tip_id is required to mark tip as todo", caller
-    end
-    self.class.post("/v1/tip/marktodo", :body => {:tip=>tip})
-  end 
-     
-  def mark_tip_as_done(tid)
-    unless tid 
-      raise ArgumentError, "tid is required to mark tip as done", caller
-    end
-    self.class.post("/v1/tip/markdone", :body => {:tip=>tip})
-  end
-
-  # ==================
-  # = FRIEND Methods =
-  # ==================
-  def friend_requests
-     self.class.get("/v1/friend/requests")
-  end
-
-  def friend_approve(uid)
-    unless uid 
-      raise ArgumentError, "uid is required to approve friend request", caller
+  class Base
+    BASE_URL = 'http://api.foursquare.com/v1'
+    FORMAT = 'json'
+    
+    attr_accessor :oauth
+    
+    def initialize(oauth)
+      @oauth = oauth
     end
-    self.class.post("/v1/friend/requests", :body => {:uid=>uid})
-  end
-     
-  def friend_deny(uid)
-    unless uid 
-      raise ArgumentError, "uid is required to deny friend request", caller
+    
+    #
+    # Foursquare API: http://groups.google.com/group/foursquare-api/web/api-documentation
+    #
+    # .test                                          # api test method
+    #  => {'response': 'ok'}
+    # .checkin = {:shout => 'At home. Writing code'} # post new check in
+    #  => {...checkin hash...}
+    # .history                                       # authenticated user's checkin history
+    # => [{...checkin hashie...}, {...another checkin hashie...}]
+    # .send('venue.flagclosed=', {:vid => 12345})     # flag venue 12345 as closed
+    # => {'response': 'ok'}
+    # .venue_flagclosed = {:vid => 12345}
+    # => {'response': 'ok'}
+    #
+    # Assignment methods(POSTs) always return a hash. Annoyingly Ruby always returns what's on
+    # the right side of the assignment operator. So there are some wrapper methods below
+    # for POSTs that make sure it gets turned into a hashie
+    #
+    def method_missing(method_symbol, params = {})
+      method_name = method_symbol.to_s.split(/\.|_/).join('/')
+      
+      if (method_name[-1,1]) == '='
+        method = method_name[0..-2]
+        result = post(api_url(method), params)
+        params.replace(result[method] || result)
+      else
+        result = get(api_url(method_name, params))
+        result[method_name] || result
+      end
     end
-    self.class.post("/v1/friend/deny", :body => {:uid=>uid})
-  end
-     
-  def request_friend(uid)
-    unless uid 
-      raise ArgumentError, "uid is required to request friend", caller
+    
+    def api(method_symbol, params = {})
+      Hashie::Mash.new(method_missing(method_symbol, params))
+    end
+    
+    def api_url(method_name, options = nil)
+      params = options.is_a?(Hash) ? to_query_params(options) : options
+      params = nil if params and params.blank?
+      url = BASE_URL + '/' + method_name.split('.').join('/')
+      url += ".#{FORMAT}"
+      url += "?#{params}" if params
+      url
+    end
+    
+    def parse_response(response)
+      raise_errors(response)
+      Crack::JSON.parse(response.body)
+    end
+    
+    def to_query_params(options)
+      options.collect { |key, value| "#{key}=#{value}" }.join('&')
+    end
+    
+    def get(url)
+      parse_response(@oauth.access_token.get(url))
+    end
+    
+    def post(url, body)
+      parse_response(@oauth.access_token.post(url, body))
+    end
+    
+    # API method wrappers
+    
+    def checkin(params = {})
+      api(:checkin=, params).checkin
+    end
+    
+    def history(params = {})
+      api(:history, params).checkins
+    end
+    
+    def addvenue(params = {})
+      api(:addvenue=, params).venue
+    end
+    
+    def venue_proposeedit(params = {})
+      api(:venue_proposeedit=, params)
+    end
+    
+    def venue_flagclosed(params = {})
+      api(:venue_flagclosed=, params)
+    end
+    
+    def addtip(params = {})
+      api(:addtip=, params).tip
+    end
+    
+    def tip_marktodo(params = {})
+      api(:tip_marktodo=, params).tip
+    end
+    
+    def tip_markdone(params = {})
+      api(:tip_markdone=, params).tip
+    end
+    
+    def friend_requests
+      api(:friend_requests).requests
+    end
+    
+    def friend_approve(params = {})
+      api(:friend_approve=, params).user
+    end
+    
+    def friend_deny(params = {})
+      api(:friend_deny=, params).user
     end
-    self.class.post("/v1/friend/sendrequest", :body => {:uid=>uid})
-  end
-  
-  # ================
-  # = FIND Methods =
-  # ================
-  def find_friends_by_name(q)
-    self.class.get("/v1/findfriends/byname", :query=>{:q=>q})
-  end 
-
-  def find_friends_by_phone(q)
-    self.class.get("/v1/findfriends/byphone", :query=>{:q=>q})
-  end 
-
-  def find_friends_by_twitter(q)
-    self.class.get("/v1/findfriends/bytwitter", :query=>{:q=>q})
-  end 
 
-  # ===============
-  # = SET methods =
-  # ===============
-  def set_pings(user_id=nil,ping=nil)
-    uid = user_id || "self"
-    self.class.post("/v1/settings/setpings?#{uid}=#{ping}")
+    def friend_sendrequest(params = {})
+      api(:friend_sendrequest=, params).user
+    end
+    
+    def findfriends_byname(params = {})
+      api(:findfriends_byname, params).users
+    end
+    
+    def findfriends_byphone(params = {})
+      api(:findfriends_byphone, params).users
+    end
+    
+    def findfriends_bytwitter(params = {})
+      api(:findfriends_bytwitter, params).users
+    end
+    
+    def settings_setpings(params = {})
+      api(:settings_setpings=, params).settings
+    end
+    
+    private
+    
+    
+    def raise_errors(response)
+      message = "(#{response.code}): #{response.message} - #{response.inspect} - #{response.body}"
+      
+      case response.code.to_i
+        when 400
+          raise BadRequest, message
+        when 401
+          raise Unauthorized, message
+        when 403
+          raise General, message
+        when 404
+          raise NotFound, message
+        when 500
+          raise InternalError, "Foursquare had an internal error. Please let them know in the group.\n#{message}"
+        when 502..503
+          raise Unavailable, message
+      end
+    end
   end
   
-  # From Foursquare API
-  # 20100108 - naveen - the concept of cities (cityid and all city-related methods) has now been removed
-  # Deprecated
-  def cities
-      self.class.get("/v1/cities")
-  end
-  # Deprecated
-    def check_city(geolat, geolong) 
-      $stderr.puts "`check_city` Deprecated: The idea of \"cityid\" is now deprecated from the API"
-      self.class.get("/v1/checkcity?geolat=#{geolat}&geolong=#{geolong}")
-    end
-  # Deprecated
-    def switch_city(city_id)
-      $stderr.puts "`switch_city` Deprecated: The idea of \"cityid\" is now deprecated from the API"
-      self.class.post("/v1/switchcity", :body => {:cityid => city_id})
-    end
-  # Method changed to call checkins to match API
-    def friend_checkins(options={})
-        $stderr.puts "`friend_checkins` now calls `checkins` to match the foursquare api method call"
-        $stderr.puts "http://groups.google.com/group/foursquare-api/web/api-documentation"
-        checkins(options)
-    end
   
-end
+  class BadRequest < StandardError; end
+  class Unauthorized      < StandardError; end
+  class General           < StandardError; end
+  class Unavailable       < StandardError; end
+  class InternalError     < StandardError; end
+  class NotFound          < StandardError; end
+end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification 
 name: foursquare
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors: 
 - Jeremy Welch
 - Thomas Hanley
+- Elise Wood
 autorequire: foursquare
 bindir: bin
 cert_chain: []
 
-date: 2010-02-17 00:00:00 -05:00
+date: 2010-03-13 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -45,7 +46,7 @@ has_rdoc: true
 homepage: http://foursquare.rubyforge.org
 licenses: []
 
-post_install_message: "NOTE: This version of the Foursquare Gem has significant changes to the way methods are called. Please review the examples in the README"
+post_install_message: "NOTE: This version of the Foursquare Gem has added OAuth support. Basic Auth has been deprecated. Also significant changes have bee made to the way methods are called. Please review the examples in the README."
 rdoc_options: []
 
 require_paths: