gowalla 0.3.0 → 0.4.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,25 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+*.gem
+.yardopts
+.yardoc
+.bundle
+
+## PROJECT::SPECIFIC

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    gowalla (0.4.0)
+      faraday (~> 0.4.5)
+      faraday_middleware
+      hashie (~> 0.2.0)
+      multi_json (~> 0.0.4)
+      oauth2
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.1)
+    fakeweb (1.3.0)
+    faraday (0.4.6)
+      addressable (>= 2.1.1)
+      rack (>= 1.0.1)
+    faraday_middleware (0.0.4)
+      faraday (~> 0.4.5)
+    hashie (0.2.2)
+    jnunemaker-matchy (0.4.0)
+    multi_json (0.0.4)
+    oauth2 (0.0.13)
+      faraday (~> 0.4.1)
+      multi_json (>= 0.0.4)
+    rack (1.2.1)
+    shoulda (2.10.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.0)
+  fakeweb
+  faraday (~> 0.4.5)
+  faraday_middleware
+  gowalla!
+  hashie (~> 0.2.0)
+  jnunemaker-matchy (~> 0.4.0)
+  multi_json (~> 0.0.4)
+  oauth2
+  shoulda (~> 2.10.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Wynn Netherland
+
+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.md

@@ -0,0 +1,96 @@
+# Gowalla
+
+Ruby wrapper for the [Gowalla API](http://gowalla.com/api/docs).
+
+
+## Installation
+
+    sudo gem install gowalla
+    
+## Get your API key
+
+Be sure and get your API key: [http://gowalla.com/api/keys](http://gowalla.com/api/keys)
+    
+## Usage
+
+### Instantiate a client (Basic Auth)
+
+    gowalla = Gowalla::Client.new(:username => 'pengwynn', :password => 'somepassword', :api_key => 'your_api_key')
+    
+### or configure once
+
+    Gowalla.configure do |config|
+      config.api_key = 'your_api_key'
+      config.username = 'pengwynn'
+      config.password = 'somepassword'
+    end
+    gowalla = Gowalla::Client.new
+    
+### Instantiate a client (OAuth2)
+
+For OAuth2, you'll need to specify a callback URL when you [set up your app and get your API keys](http://gowalla.com/api/keys).
+
+Let's create the client in a protected method in our controller:
+
+    protected
+      def client    
+        Gowalla::Client.new (
+          :api_key     => "your_api_key",
+          :api_secret  => "your_api_secret",
+          :access_token => session[:access_token]
+        )
+      end
+
+We need to get an access token. Perhaps in an a before filter where you need to access Gowalla:
+    
+    redirect(@client.web_server.authorize_url(:redirect_uri => redirect_uri, :state => 1))
+
+or if you need read-write access:
+
+    redirect(@client.web_server.authorize_url(:redirect_uri => redirect_uri, :state => 1, :scope => 'read-write))
+    
+You'll need a callback route to catch the code coming back from Gowalla after a user grants you access and this must match what you specified when you created your app on Gowalla:
+
+    get '/auth/gowalla/callback' do
+      session[:access_token] = client.web_server.get_access_token(params[:code], :redirect_uri => redirect_uri).token
+
+      if session[:access_token]
+        redirect '/auth/gowalla/test'
+      else
+        "Error retrieving access token."
+      end
+    end
+    
+Now that we have an access token we can use the client to make calls, just like we would with Basic Auth. You can checkout a basic [Sinatra example](http://gist.github.com/454283).
+    
+#### Examples
+
+    gowalla.user('pengwynn')
+    => <#Hashie::Mash accept_url="/friendships/accept?user_id=1707" activity_url="/users/1707/events" bio="Web designer and Ruby developer." events_url="/users/1707/events" fb_id=605681706 first_name="Wynn" friends_count=27 friends_only=false friends_url="/users/1707/friends" hometown="Aubrey, TX" image_url="http://s3.amazonaws.com/static.gowalla.com/users/1707-standard.jpg?1262011383" is_friend=false items_count=5 items_url="/users/1707/items" last_name="Netherland" last_visit=<#Hashie::Mash comment="Closing every account I have " created_at="2010/01/26 15:31:46 +0000" spot=<#Hashie::Mash image_url="http://static.gowalla.com/categories/186-standard.png" name="Bank Of America" small_image_url="http://static.gowalla.com/categories/186-small-standard.png" url="/spots/164052"name="Wynn Netherland" pins_count=3 pins_url="/users/1707/pins" reject_url="/friendships/reject?user_id=1707" request_url="/friendships/request?user_id=1707" stamps_count=15 stamps_url="/users/1707/stamps" top_spots_url="/users/1707/top_spots" twitter_username="pengwynn" url="/users/1707" username="pengwynn" vaulted_kinds_count=0 visited_spots_count=15 website="http://wynnnetherland.com">
+    
+
+Details for the current user
+
+    gowalla.user
+    
+Details for another user
+
+    gowalla.user('bradleyjoyce')
+    gowalla.user(1707)
+    
+
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+   bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Wynn Netherland. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require "shoulda/tasks"
+require "rake/testtask"
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new(:test) do |test|
+  test.ruby_opts = ["-rubygems"] if defined? Gem
+  test.libs << "lib" << "test"
+  test.pattern = "test/**/*_test.rb"
+end
+
+task :default => :test

data/changelog.md

@@ -0,0 +1,33 @@
+# Changelog
+## 0.4.0 September 28, 2010
+  * faraday_middleware gem renamed
+  * refactor api methods into individual container classes
+  * Additional user method support (visited spots, pins)
+  * Problem reporting via flags
+  * Patch from [armanddp](http://github.com/armanddp) for Ruby 1.9, Bundler
+## 0.3.0 August 9, 2010
+  * Added checkin API
+  * Patch from [mattt](http://github.com/mattt) for Flag Spots API
+## 0.2.1 June 28, 2010
+  * Use Faraday middleware for JSON parsing, Mash creation
+## 0.2.0 June 27, 2010
+  * Refactored to use Faraday
+  * Now supports OAuth2
+## 0.1.4 May 6, 2010
+  * Updated accepts header
+  * Added patch from [Ruben Fonseca](http://github.com/rubenfonseca) to check in at a spot
+## 0.1.3 March 7, 2010
+  * Updated README with correct config call
+  * Applied patch from [Kacy Fortner](http://github.com/kacy) to add vaulted items and missing items calls
+  * Applied patches from [Eric Hutzelman](http://github.com/ehutzelman) to clean up fixtures, changed api methods
+## 0.1.2 March 3, 2010
+
+  * Applied patch from [Ruben Fonseca](http://github.com/rubenfonseca) to search within a given bounds
+  * Applied patch from [Eric Hutzelman](http://github.com/ehutzelman) to clean up config
+
+## 0.1.0 February 8, 2010
+
+  * Updates for released API
+
+## 0.0.1 January 28, 2010
+  * Initial version

data/gowalla.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/gowalla/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = %q{gowalla}
+  s.version = Gowalla::VERSION
+  s.authors = ["Wynn Netherland", "Eric Hutzelman"]
+  s.email = %q{wynn.netherland@gmail.com}
+  s.summary = %q{Wrapper for the Gowalla API}
+  s.description = %q{Ruby wrapper for the Gowalla API}
+  s.homepage = %q{http://wynnnetherland.com/projects/gowalla/}
+
+  s.add_dependency 'oauth2'
+  s.add_dependency 'faraday', '~> 0.4.5'
+  s.add_dependency 'hashie', '~> 0.2.0'
+  s.add_dependency 'multi_json', '~> 0.0.4'
+  s.add_dependency 'faraday_middleware'
+
+  s.add_development_dependency 'shoulda', '~> 2.10.0'
+  s.add_development_dependency 'jnunemaker-matchy', '~> 0.4.0'
+  s.add_development_dependency 'fakeweb'
+  s.add_development_dependency "bundler", ">= 1.0.0"
+
+  s.required_rubygems_version = ">= 1.3.6"
+  s.platform = Gem::Platform::RUBY
+  s.require_path  = 'lib'
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+end

data/lib/gowalla.rb

@@ -9,24 +9,6 @@ directory = File.expand_path(File.dirname(__FILE__))
 Hash.send :include, Hashie::HashExtensions
 
 module Gowalla
-  
-  VERSION = "0.3.0".freeze
-  
-  # config/initializers/gowalla.rb (for instance)
-  # 
-  # Gowalla.configure do |config|
-  #   config.api_key = 'api_key'
-  #   config.username = 'username'
-  #   config.password = 'password'
-  # end
-  # 
-  # elsewhere
-  #
-  # client = Gowalla::Client.new
-  def self.configure
-    yield self
-    true
-  end
 
   class << self
     attr_accessor :api_key
@@ -34,12 +16,34 @@ module Gowalla
     attr_accessor :password
     attr_accessor :api_secret
     attr_accessor :test_mode
-    
+
+    # config/initializers/gowalla.rb (for instance)
+    #
+    # Gowalla.configure do |config|
+    #   config.api_key = 'api_key'
+    #   config.username = 'username'
+    #   config.password = 'password'
+    # end
+    #
+    # elsewhere
+    #
+    # client = Gowalla::Client.new
+    def configure
+      yield self
+      true
+    end
+
     def test_mode?
       !!self.test_mode
     end
   end
-  
-end
 
-require File.join(directory, 'gowalla', 'client')
+  require 'gowalla/spots'
+  require 'gowalla/items'
+  require 'gowalla/trips'
+  require 'gowalla/checkins'
+  require 'gowalla/flags'
+  require 'gowalla/users'
+  require 'gowalla/client'
+
+end

data/lib/gowalla/checkins.rb

@@ -0,0 +1,31 @@
+module Gowalla
+  module Checkins
+
+    # Fetch info for a checkin
+    #
+    # @param [Integer] id Checkin ID
+    # @return [Hashie::Mash] checkin info
+    def checkin_info(id)
+      connection.get("/checkins/#{id}").body
+    end
+
+    # Check in at a spot
+    #
+    # @option details [Integer] :spot_id Spot ID
+    # @option details [Float] :lat Latitude of spot
+    # @option details [Float] :lng Longitude of spot
+    # @option details [String] :comment Checkin comment
+    # @option details [Boolean] :post_to_twitter Post Checkin to Twitter
+    # @option details [Boolean] :post_to_facebook Post Checkin to Facebook
+    def checkin(details={})
+      checkin_path = "/checkins"
+      checkin_path += "/test" if Gowalla.test_mode?
+      response = connection.post do |req|
+        req.url checkin_path
+        req.body = details
+      end
+      response.body
+    end
+
+  end
+end

data/lib/gowalla/client.rb

@@ -3,11 +3,18 @@ require 'forwardable'
 module Gowalla
   class Client
     extend Forwardable
-    
+
+    include Spots
+    include Users
+    include Items
+    include Trips
+    include Checkins
+    include Flags
+
     attr_reader :username, :api_key, :api_secret
-    
+
     def_delegators :oauth_client, :web_server, :authorize_url, :access_token_url
-    
+
     def initialize(options={})
       @api_key = options[:api_key] || Gowalla.api_key
       @api_secret = options[:api_secret] || Gowalla.api_secret
@@ -17,176 +24,15 @@ module Gowalla
       connection.basic_auth(@username, password) unless @api_secret
       connection.token_auth(@access_token) if @access_token
     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
-      connection.get("/users/#{user_id}").body
-    end
-
-    # Retrieve information about a specific item
-    #
-    # @param [Integer] id Item ID
-    # @return [Hashie::Mash] item info
-    def item(id)
-      connection.get("/items/#{id}").body
-    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)
-      response = connection.get do |req|
-        req.url "/users/#{user_id}/stamps", :limit => limit
-      end
-      response.body.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)
-      connection.get("/users/#{user_id}/top_spots").body.top_spots
-    end
-
-    # Retrieve information about a specific trip
-    #
-    # @param [Integer] trip_id Trip ID
-    # @return [Hashie::Mash] trip info
-    def trip(trip_id)
-      connection.get("/trips/#{trip_id}").body
-    end
-    
-    # Retrieve information about a specific spot
-    #
-    # @param [Integer] spot_id Spot ID
-    # @return [Hashie::Mash] Spot info
-    def spot(spot_id)
-      connection.get("/spots/#{spot_id}").body
-    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)
-      connection.get("/spots/#{spot_id}/events").body.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)
-      connection.get("/spots/#{spot_id}/items").body.items
-    end
-    
-    # Retrieve a list of flags for a particular spot
-    #
-    # @param [Integer] spot_id Spot ID
-    # @return [Hashie::Mash] Array of Flags
-    def spot_flags(spot_id)
-      connection.get("/spots/#{spot_id}/flags").body.flags
-    end
-    
-    # Retrieve a list of flags 
-    #
-    # @return [<Hashie::Mash>] Flag info
-    def list_flags(options={})
-      connection.get("/flags").body.flags
-    end
-    
-    # Retrieve information about a particular flag
-    #
-    # @param [Integer] flag_id Flag ID
-    # @return [Hashie::Mash] Flag info
-    def flag(flag_id)
-      connection.get("/flags/#{flag_id}").body
-    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)
-      response = connection.get do |req|
-        req.url "/spots", query
-      end
-      response.body.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)
-      response = connection.get do |req|
-        req.url "/trips", query
-      end
-      response.body.trips
-    end
-
-    # Lists all spot categories
-    #
-    # @return [<Hashie::Mash>] category info
-    def categories
-      connection.get("/categories").body.spot_categories
-    end
-    
-    # Retrieve information about a specific category
-    #
-    # @param [Integer] id Category ID
-    # @return [Hashie::Mash] category info
-    def category(id)
-      connection.get("/categories/#{id}").body
-    end
-    
-    # Fetch info for a checkin
-    # 
-    # @param [Integer] id Checkin ID
-    # @return [Hashie::Mash] checkin info
-    def checkin_info(id)
-      connection.get("/checkins/#{id}").body
-    end
-    
-    # Check in at a spot
-    # 
-    # @option details [Integer] :spot_id Spot ID
-    # @option details [Float] :lat Latitude of spot
-    # @option details [Float] :lng Longitude of spot
-    # @option details [String] :comment Checkin comment
-    # @option details [Boolean] :post_to_twitter Post Checkin to Twitter
-    # @option details [Boolean] :post_to_facebook Post Checkin to Facebook
-    def checkin(details={})
-      checkin_path = "/checkins"
-      checkin_path += "/test" if Gowalla.test_mode?
-      response = connection.post do |req|
-        req.url checkin_path
-        req.body = details
-      end
-      response.body
-    end
-    
     # 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 
+
+    # Raw HTTP connection, either Faraday::Connection
     #
     # @return [Faraday::Connection]
     def connection
@@ -198,18 +44,18 @@ module Gowalla
         builder.use Faraday::Response::MultiJson
         builder.use Faraday::Response::Mashify
       end
-            
+
     end
-    
+
     # Provides raw access to the OAuth2 Client
     #
-    # @return [OAuth2::Client] 
+    # @return [OAuth2::Client]
     def oauth_client
       if @oauth_client
         @oauth_client
       else
         conn ||= Faraday::Connection.new \
-          :url => "https://api.gowalla.com", 
+          :url => "https://api.gowalla.com",
           :headers => default_headers
 
         oauth= OAuth2::Client.new(api_key, api_secret, oauth_options = {
@@ -223,7 +69,7 @@ module Gowalla
     end
 
     private
-    
+
       # @private
       def format_geo_options(options={})
         options[:lat] = "+#{options[:lat]}" if options[:lat].to_i > 0
@@ -233,17 +79,17 @@ module Gowalla
         end
         options
       end
-      
+
       # @private
       def default_headers
         headers = {
-          :accept =>  'application/json', 
+          :accept =>  'application/json',
           :user_agent => 'Ruby gem',
           'X-Gowalla-API-Key' => api_key
         }
       end
-      
-    
+
+
   end
-  
+
 end