gowalla 0.1.4 → 0.2.0

data/lib/gowalla.rb

@@ -1,5 +1,7 @@
 require 'hashie'
-require 'httparty'
+require 'faraday'
+require 'multi_json'
+require 'oauth2'
 
 directory = File.expand_path(File.dirname(__FILE__))
 
@@ -7,6 +9,8 @@ Hash.send :include, Hashie::HashExtensions
 
 module Gowalla
   
+  VERSION = "0.2.0".freeze
+  
   # config/initializers/gowalla.rb (for instance)
   # 
   # Gowalla.configure do |config|
@@ -27,6 +31,7 @@ module Gowalla
     attr_accessor :api_key
     attr_accessor :username
     attr_accessor :password
+    attr_accessor :api_secret
   end
   
 end

data/lib/gowalla/client.rb

@@ -1,134 +1,181 @@
+require 'forwardable'
+
 module Gowalla
-  
   class Client
-    include HTTParty
-    format :json
-    base_uri "http://api.gowalla.com"
-    headers({'Accept' => 'application/json', "User-Agent" => 'Ruby gem'})
+    extend Forwardable
+    
+    attr_reader :username, :api_key, :api_secret
     
-    attr_reader :username
+    def_delegators :oauth_client, :web_server, :authorize_url, :access_token_url
     
     def initialize(options={})
-      api_key = options[:api_key] || Gowalla.api_key
+      @api_key = options[:api_key] || Gowalla.api_key
+      @api_secret = options[:api_secret] || Gowalla.api_secret
       @username = options[:username] || Gowalla.username
+      @access_token = options[:access_token]
       password = options[:password] || Gowalla.password
-      self.class.basic_auth(@username, password) unless @username.nil?
-      self.class.headers({'X-Gowalla-API-Key' => api_key }) unless api_key.nil?
-    end
-    
-    def user(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}"))
-    end
-    
-    def events(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/events")).activity
-    end
-    
-    def friends_events
-      mashup(self.class.get("/visits/recent")).activity
-    end
-    
-    def friend_requests(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/friend_requests")).friends_needing_approval
-    end
-    
-    def friends(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/friends")).friends
-    end
-    
-    def items(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/items")).items
-    end
-    
-    def missing_items(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/items/missing")).items
-    end
-    
-    def vaulted_items(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/items/vault")).items
-    end
-    
+      connection.basic_auth(@username, password) unless @api_secret
+    end
+    
+    # Retrieve information about a specific user
+    #
+    # @param [String] user_id (authenticated basic auth user) User ID (screen name)
+    # @return [Hashie::Mash] User info
+    def user(user_id=nil)
+      user_id ||= username
+      handle_response(connection.get("/users/#{user_id}"))
+    end
+
+    # Retrieve information about a specific item
+    #
+    # @param [Integer] id Item ID
+    # @return [Hashie::Mash] item info
     def item(id)
-      mashup(self.class.get("/items/#{id}"))
-    end
-    
-    def pins(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/pins"))
-    end
-    
+      handle_response(connection.get("/items/#{id}"))
+    end
+
+    # Retrieve a list of the stamps the user has collected
+    #
+    # @param [String] user_id (authenticated basic auth user) User ID (screen name)
+    # @param [Integer] limit (20) limit per page
+    # @return [Hashie::Mash] stamps info
     def stamps(user_id=self.username, limit=20)
-      mashup(self.class.get("/users/#{user_id}/stamps", :query => {:limit => limit})).stamps
+      response = connection.get do |req|
+        req.url "/users/#{user_id}/stamps", :limit => limit
+      end
+      handle_response(response).stamps
     end
-    
+
+    # Retrieve a list of spots the user has visited most often
+    #
+    # @param [String] user_id (authenticated basic auth user) User ID (screen name)
+    # @return [Hashie::Mash] item info
     def top_spots(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/top_spots")).top_spots
+      handle_response(connection.get("/users/#{user_id}/top_spots")).top_spots
     end
-    
-    def visited_spots(user_id=self.username)
-      mashup(self.class.get("/users/#{user_id}/visited_spots"))
-    end
-    
+
+    # Retrieve information about a specific trip
+    #
+    # @param [Integer] trip_id Trip ID
+    # @return [Hashie::Mash] trip info
     def trip(trip_id)
-      mashup(self.class.get("/trips/#{trip_id}"))
+      handle_response(connection.get("/trips/#{trip_id}"))
     end
     
+    # Retrieve information about a specific spot
+    #
+    # @param [Integer] spot_id Spot ID
+    # @return [Hashie::Mash] Spot info
     def spot(spot_id)
-      mashup(self.class.get("/spots/#{spot_id}"))
+      handle_response(connection.get("/spots/#{spot_id}"))
     end
     
+    # Retrieve a list of check-ins at a particular spot. Shows only the activity that is visible to a given user.
+    #
+    # @param [Integer] spot_id Spot ID
+    # @return [Hashie::Mash] Spot info
     def spot_events(spot_id)
-      mashup(self.class.get("/spots/#{spot_id}/events")).activity
+      handle_response(connection.get("/spots/#{spot_id}/events")).activity
     end
     
+    # Retrieve a list of items available at a particular spot
+    #
+    # @param [Integer] spot_id Spot ID
+    # @return [Hashie::Mash] Spot info
     def spot_items(spot_id)
-      mashup(self.class.get("/spots/#{spot_id}/items")).items
+      handle_response(connection.get("/spots/#{spot_id}/items")).items
     end
     
+    # Retrieve a list of spots within a specified distance of a location
+    #
+    # @option options [Float] :latitude Latitude of search location
+    # @option options [Float] :longitude Longitude of search location
+    # @option options [Integer] :radius Search radius (in meters)
+    # @return [Hashie::Mash] spots info
     def list_spots(options={})
       query = format_geo_options(options)
-      mashup(self.class.get("/spots", :query => query)).spots
-    end
-    
-    def featured_spots(options={})
-      list_spots(options.merge(:featured => 1))
-    end
-    
-    def bookmarked_spots(options={})
-      list_spots(options.merge(:bookmarked => 1))
+      response = connection.get do |req|
+        req.url "/spots", query
+      end
+      handle_response(response).spots
     end
     
+    # List of trips
+    #
+    # @return [<Hashie::Mash>] trip info
     def trips(options={})
       if user_id = options.delete(:user_id)
         options[:user_url] = "/users/#{user_id}"
       end
       query = format_geo_options(options)
-      mashup(self.class.get("/trips", :query => query)).trips
-    end
-    
-    def featured_trips(options={})
-      trips(options.merge(:context => 'featured'))
-    end
-    
-    def friends_trips(options={})
-      trips(options.merge(:context => 'friends'))
+      response = connection.get do |req|
+        req.url "/trips", query
+      end
+      handle_response(response).trips
     end
-    
+
+    # Lists all spot categories
+    #
+    # @return [<Hashie::Mash>] category info
     def categories
-      mashup(self.class.get("/categories")).spot_categories
+      handle_response(connection.get("/categories")).spot_categories
     end
     
+    # Retrieve information about a specific category
+    #
+    # @param [Integer] id Category ID
+    # @return [Hashie::Mash] category info
     def category(id)
-      mashup(self.class.get("/categories/#{id}"))
+      handle_response(connection.get("/categories/#{id}"))
     end
     
-    def checkin(spot_id, options = {})
-      query = format_geo_options(options)
+    # Check for missing access token
+    #
+    # @return [Boolean] whether or not to redirect to get an access token
+    def needs_access?
+      @api_secret and @access_token.to_s == ''
+    end
+    
+    # Raw HTTP connection, either Faraday::Connection or OAuth2::AccessToken
+    #
+    # @return [OAuth2::Client]
+    def connection
       
-      mashup(self.class.post("/checkins", :body => options, :query => { :spot_id => spot_id }))
+      if api_secret
+        @connection ||= OAuth2::AccessToken.new(oauth_client, @access_token)
+      else
+        headers = default_headers
+        headers['X-Gowalla-API-Key'] = api_key if api_key
+        @connection ||= Faraday::Connection.new \
+          :url => "http://api.gowalla.com", 
+          :headers => headers
+      end
     end
     
+    # Provides raw access to the OAuth2 Client
+    #
+    # @return [OAuth2::Client] 
+    def oauth_client
+      if @oauth_client
+        @oauth_client
+      else
+        conn ||= Faraday::Connection.new \
+          :url => "https://api.gowalla.com", 
+          :headers => default_headers
+
+        oauth= OAuth2::Client.new(api_key, api_secret, oauth_options = {
+          :site => 'https://api.gowalla.com',
+          :authorize_url => 'https://gowalla.com/api/oauth/new',
+          :access_token_url => 'https://gowalla.com/api/oauth/token'
+        })
+        oauth.connection = conn
+        oauth
+      end
+    end
+
     private
     
+      # @private
       def format_geo_options(options={})
         options[:lat] = "+#{options[:lat]}" if options[:lat].to_i > 0
         options[:lng] = "+#{options[:lng]}" if options[:lng].to_i > 0
@@ -137,21 +184,33 @@ module Gowalla
         end
         options
       end
-    
-      def mashup(response)
-        case response.code
+      
+      # @private
+      def default_headers
+        headers = {
+          :accept =>  'application/json', 
+          :user_agent => 'Ruby gem'
+        }
+      end
+      
+      # @private
+      def handle_response(response)
+        case response.status
         when 200
-          if response.is_a?(Hash)
-            Hashie::Mash.new(response)
+          body = response.respond_to?(:body) ? response.body : response
+          data = MultiJson.decode(body)
+          if data.is_a?(Hash)
+            Hashie::Mash.new(data)
           else
-            if response.first.is_a?(Hash)
-              response.map{|item| Hashie::Mash.new(item)}
+            if data.first.is_a?(Hash)
+              data.map{|item| Hashie::Mash.new(item)}
             else
-              response
+              data
             end
           end
         end
       end
+      
     
   end
   

data/test/gowalla_test.rb

@@ -0,0 +1,168 @@
+require 'helper'
+
+class GowallaTest < Test::Unit::TestCase
+
+  context "When using the Gowalla API" do
+    setup do
+      @client = Gowalla::Client.new(:username => 'pengwynn', :password => '0U812', :api_key => 'gowallawallabingbang')
+    end
+    
+    context "and working with Spots" do
+      should "Retrieve a list of spots within a specified distance of a location" do
+        stub_get("http://pengwynn:0U812@api.gowalla.com/spots?lat=%2B33.237593417&lng=-96.960559033&radius=50", "spots.json")
+        spots = @client.list_spots(:lat => 33.237593417, :lng => -96.960559033, :radius => 50)
+        spots.first.name.should == 'Gnomb Bar'
+        spots.first.radius_meters.should == 50
+      end
+      
+      should "Retrieve a list of spots within a specified bounds" do
+        stub_get("http://pengwynn:0U812@api.gowalla.com/spots?sw=%2839.25565142103586%2C%20-8.717308044433594%29&nw=%2839.31411296530539%2C%20-8.490715026855469%29", "spots.json")
+        spots = @client.list_spots(:sw => "(39.25565142103586, -8.717308044433594)", :nw => "(39.31411296530539, -8.490715026855469)")
+        spots.first.name.should == 'Gnomb Bar'
+      end
+
+      should "Retrieve information about a specific spot" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/spots/18568', 'spot.json')
+        spot = @client.spot(18568)
+        spot.name.should == "Wahoo's"
+        spot.twitter_username.should == 'Wahoos512'
+        spot.spot_categories.first.name.should == 'Mexican'
+      end
+
+      should "retrieve a list of check-ins at a particular spot. Shows only the activity that is visible to a given user" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/spots/452593/events', 'events.json')
+        events = @client.spot_events(452593)
+        events.first[:type].should == 'checkin'
+        events.first.user.last_name.should == 'Mack'
+      end
+
+      should "retrieve a list of items available at a particular spot" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/spots/18568/items', 'items.json')
+        items = @client.spot_items(18568)
+        items.first.issue_number.should == 27868
+        items.first.name.should == 'Bowl of Noodles'
+      end
+
+      should "lists all spot categories" do
+        stub_get("http://pengwynn:0U812@api.gowalla.com/categories", "categories.json")
+        categories = @client.categories
+        categories.size.should == 9
+        categories.first.name.should == 'Architecture & Buildings'
+        categories.first.description.should == 'Bridge, Corporate, Home, Church, etc.'
+        categories.first.spot_categories.size.should == 15
+        categories.first.spot_categories.first.name.should == 'Bridge'
+      end
+
+      should "retrieve information about a specific category" do
+        stub_get("http://pengwynn:0U812@api.gowalla.com/categories/1", "category.json")
+        category = @client.category(1)
+        category.name.should == 'Coffee Shop'
+      end
+    end
+    
+    context "and working with Users" do
+      
+      should "retrieve information about a specific user" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/users/sco', 'user.json')
+        user = @client.user('sco')
+        user.bio.should == "CTO & co-founder of Gowalla. Ruby/Cocoa/JavaScript developer. Game designer. Author. Indoorsman."
+        user.stamps_count.should == 506
+      end
+      
+      should "retrieve a list of the stamps the user has collected" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/users/1707/stamps?limit=20', 'stamps.json')
+        stamps = @client.stamps(1707)
+        stamps.size.should == 20
+        stamps.first.spot.name.should == "Muck-N-Dave's Texas BBQ"
+        stamps.first.spot.address.locality.should == 'Austin'
+      end
+      
+      should "retrieve a list of spots the user has visited most often" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/users/1707/top_spots', 'top_spots.json')
+        top_spots = @client.top_spots(1707)
+        top_spots.size.should == 10
+        top_spots.first.name.should == 'Juan Pelota Cafe'
+        top_spots.first.user_checkins_count.should == 30
+      end
+      
+    end
+    
+    context "and working with Items" do
+      should "retrieve information about a specific item" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/items/607583', 'item.json')
+        item = @client.item(607583)
+        item.issue_number.should == 13998
+        item.name.should == 'Sweets'
+        item.determiner.should == 'some'
+      end
+    end
+    
+    context "and working with Trips" do
+      should "retrieve a list of trips" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/trips', 'trips.json')
+        trips = @client.trips
+        trips.first.name.should == 'London Pub Crawl'
+        trips.first.spots.first.url.should == '/spots/164009'
+      end
+      
+      should "retrieve information about a specific trip" do
+        stub_get('http://pengwynn:0U812@api.gowalla.com/trips/1', 'trip.json')
+        trip = @client.trip(1)
+        trip.creator.last_name.should == 'Gowalla'
+        trip.map_bounds.east.should == -63.457031
+      end
+    end
+    
+  end
+  
+  context "when using basic auth" do
+    should "configure api_key, username, and password for easy access" do
+
+      Gowalla.configure do |config|
+        config.api_key = 'api_key'
+        config.api_secret = nil
+        config.username = 'username'
+        config.password = 'password'
+      end
+
+      @client = Gowalla::Client.new
+
+      stub_get('http://username:password@api.gowalla.com/trips', 'trips.json')
+      trips = @client.trips
+
+      @client.username.should == 'username'
+    end
+  end
+
+  context "when using OAuth2" do
+    
+    setup do
+      Gowalla.configure do |config|
+        config.api_key = 'api_key'
+        config.api_secret = 'api_secret'
+      end
+
+      @client = Gowalla::Client.new
+    end
+    
+    should "confiure api_key, api_secret" do
+      @client.api_secret.should == 'api_secret'
+      @client.oauth_client.id.should == 'api_key'
+    end
+    
+    should "create an OAuth2 client" do
+      @client.oauth_client.class.to_s.should == "OAuth2::Client"
+    end
+    
+    should "create an OAuth2 connection" do
+      @client.connection.class.to_s.should == "OAuth2::AccessToken"
+    end
+    
+    should "indicate if it needs an access_token" do
+      @client.needs_access?.should == true
+    end
+    
+  end
+  
+  
+end