untappd-api 0.0.2 → 0.1.0

data/README.rdoc

@@ -4,12 +4,22 @@ A simple Ruby wrapper for accessing the Untappd API.
 For more information, see http://untappd.com/api/dashboard.
 
 == Usage
-Each method returns a Hash representing the response.
+Each method returns a Hashie::Mash representing the response.
 
 === Example:
-  require 'untappd-api'
+  require 'untappd'
 
-  client = Untappd::Base.new(API_KEY)
-  beer = client.beer_info(:bid => 17904)["results"]
-  beer["name"] # => "Third Coast Old Ale"
-  beer["brewery"] #=> "Bell's Brewery, Inc."
+  Untappd.configure do |config|
+    config.application_key = "YOUR_API_KEY")
+    config.username = "your_username"       # Some API calls require a signed in user
+    config.password = "your_password"       # Most API methods do not require a user
+  end
+
+  Untappd.beer(1234)
+  Untappd.user(user: 'gambrinus') # Returns the signed in user if no :user option passed
+
+  # You can change the signed in user after initial configuration
+  Untappd.username = "another_user"
+  Untappd.password = "that_guys_password"
+
+All methods are documented in the lib/untappd/client directory.

data/lib/untappd.rb

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

data/lib/untappd/api.rb

@@ -0,0 +1,79 @@
+require 'httparty'
+require 'hashie'
+
+module Untappd
+  class API
+    include HTTParty
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    # Override these setters so that HTTParty class methods get updated as well
+    def endpoint=(val)
+      @endpoint = val
+      @klass.base_uri(endpoint)
+    end
+
+    def application_key=(val)
+      @application_key = val
+      @klass.default_params(:key => application_key)
+    end
+    
+    # Create a new API
+    def initialize(options={})
+      @klass = self.class
+      options = Untappd.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key]) 
+      end
+
+      # Set HTTParty class configurations
+      @klass.format(:json)
+    end
+
+    private
+  
+    # Wrap calls to the HTTParty get and post methods and return results as Hashie::Mash
+    def get(path, options={})
+      response = @klass.get(path, :query => options,
+                                  :basic_auth => auth).parsed_response
+      handle_error(response)
+      Hashie::Mash.new(response).results
+    end
+
+    def post(path, options={})
+      response = @klass.post(path,  :body => options,
+                                    :basic_auth => auth)
+      handle_error(response)
+      Hashie::Mash.new(response)
+    end
+
+    def auth
+      if username && password
+        { :username => username, 
+          :password => Digest::MD5.hexdigest(password) }
+      end
+    end
+
+    def handle_error(response)
+      message = response['error']
+
+      case response['http_code']
+        when 400
+          raise BadRequest, message
+        when 401
+          raise Unauthorized, message
+        when 403
+          raise General, message
+        when 404
+          raise NotFound, message
+        when 500
+          raise InternalError, message
+        when 502
+          raise BadGateway, message
+        when 503
+          raise Unavailable, message
+        when 504
+          raise GatewayTimeout, message
+      end
+    end
+  end
+end

data/lib/untappd/client.rb

@@ -0,0 +1,17 @@
+module Untappd
+  
+  class Client < API
+    require 'untappd/client/beer'
+    require 'untappd/client/brewery'
+    require 'untappd/client/checkin'
+    require 'untappd/client/user'
+    require 'untappd/client/venue'
+
+    include Untappd::Client::Beer
+    include Untappd::Client::Brewery
+    include Untappd::Client::Checkin
+    include Untappd::Client::User
+    include Untappd::Client::Venue
+
+  end
+end

data/lib/untappd/client/beer.rb

@@ -0,0 +1,65 @@
+module Untappd
+  class Client
+    module Beer
+      
+      # Returns the feed for the specified beer.
+      #
+      # @format :json
+      # @authenticated false
+      # @param id [String, Integer] The ID of the beer.
+      # @option options [String, Integer] :since The ID of the last recent check-in.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Array] The requested beer feed.
+      # @example Retrieve the feed for beer with ID 3839.
+      #   Untappd.beer_feed(399)
+      def beer_feed(id, options={})
+        options.merge!(:bid => id)
+        get('/beer_checkins', options)
+      end
+
+      # Returns info for the specified beer.
+      #
+      # @format :json
+      # @authenticated false
+      # @param id [String, Integer] The ID of the beer.
+      # @return [Hashie::Mash] The requested beer.
+      # @example Retrieve the beer with ID 3839.
+      #   Untappd.beer(3839)
+      def beer(id)
+        options = { :bid => id }
+        get('/beer_info', options)
+      end
+
+      # Search beers with the specified query.
+      #
+      # @format :json
+      # @authenticated false
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @option options [String, Integer] :sort Alphabetical order ("name") or checkin count order ("count").
+      # @return [Array] The search results.
+      # @example Search beers for "Pale ale".
+      #   Untappd.beer_search("Pale ale")
+      def beer_search(query, options={})
+        options.merge!(:q => query)
+        get('/beer_search', options)
+      end
+
+      # Returns the currently trending beers.
+      #
+      # @format :json
+      # @authenticated false
+      # @option options [String] :type "all", "macro", "micro", "local". "all" is set as default.
+      # @option options [String, Integer] :limit The number of records to return. (max 10)
+      # @option options [String, Integer] :age "daily", "weekly", "monthly".
+      # @option options [String, Integer] :geolat Latitude to filter results by. Required when :type => "local".
+      # @option options [String, Integer] :geolng Longitude to filter results by. Required when :type => "local".
+      # @return [Array] The search results.
+      # @example Return all trending beers.
+      #   Untappd.trending_beers
+      def trending_beers(options={})
+        get('/trending', options)
+      end
+    end
+  end
+end
+

data/lib/untappd/client/brewery.rb

@@ -0,0 +1,48 @@
+module Untappd
+  class Client
+    module Brewery
+
+      # Returns the feed for the specified brewery.
+      #
+      # @format :json
+      # @authenticated false
+      # @param id [String, Integer] The ID of the brewery.
+      # @option options [String, Integer] :since The ID of the last recent check-in.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Array] The requested brewery feed.
+      # @example Retrieve the feed for brewery with ID 399.
+      #   Untappd.brewery_feed(399)
+      def brewery_feed(id, options={})
+        options.merge!(:brewery_id => id)
+        get('/brewery_checkins', options)
+      end
+
+      # Returns info for the specified brewery.
+      #
+      # @format :json
+      # @authenticated false
+      # @param id [String, Integer] The ID of the brewery.
+      # @return [Hashie::Mash] The requested brewery.
+      # @example Retrieve brewery with ID 399.
+      #   Untappd.brewery(399)
+      def brewery(id)
+        options = { :brewery_id => id }
+        get('/brewery_info', options)
+      end
+
+      # Search breweries with the specified query.
+      #
+      # @format :json
+      # @authenticated false
+      # @param query [String] The term that you want to search.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Array] The search results.
+      # @example Search breweries for "Bell's".
+      #   Untappd.brewery_search("Bell's")
+      def brewery_search(query, options={})
+        options.merge!(:q => query)
+        get('/brewery_search', options)
+      end
+    end
+  end
+end

data/lib/untappd/client/checkin.rb

@@ -0,0 +1,113 @@
+module Untappd
+  class Client
+    module Checkin
+      
+      # Returns all public checkins, otherwise known as "The Pub".
+      #
+      # @format :json
+      # @authenticated false
+      # @option options [String, Integer] :since The ID of the last recent check-in.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @option options [String, Integer] :geolat Latitude to filter results by.
+      # @option options [String, Integer] :geolng Longitude to filter results by.
+      # @return [Array] The requested beer feed.
+      # @example Retrieve the public feed.
+      #   Untappd.public_feed
+      def public_feed(options={})
+        get('/thepub', options)
+      end
+
+      # Alias for public_feed
+      alias_method :the_pub, :public_feed
+
+      # Returns info for the specified checkin.
+      #
+      # @format :json
+      # @authenticated false
+      # @param id [String, Integer] The ID of the checkin.
+      # @return [Hashie::Mash] The requested checkin.
+      # @example Retrieve the checkin with ID 669114 .
+      #   Untappd.beer(3839)
+      def checkin_details(id)
+        options = { :id => id }
+        get('/details', options)
+      end
+
+      # Perform a checkin with the authenticated user.
+      #
+      # @format :json
+      # @authenticated true 
+      # @param gmt_offset [String, Integer] The numeric value of hours the user is from GMT (Greenwich Mean Time).
+      # @param beer_id [String, Integer] The ID of the beer you wish to check into.
+      # @option options [String] :foursquare_id The MD5 hash ID of the Venue you want to attach the beer checkin to.
+      # @option options [String] :shout The text you would like included as a comment.  Max of 140 characters.
+      # @option options [String, Integer] :rating_value The score you would like to add for the beer.  Must be whole numbers from 1 to 5.
+      # @option options [String, Integer] :user_lat Latitude of the user.  Required if you want to add a location to the checkin.
+      # @option options [String, Integer] :user_lng Longitude of the user. Required if you want to add a location to the checkin.
+      # @option options [String] :facebook Set to "on" to post checkin to Facebook.  Defaults to "off".
+      # @option options [String] :twitter Set to "on" to post checkin to Twitter.  Defaults to "off".
+      # @option options [String] :foursquare Set to "on" to pass checkin on to Foursquare.  Defaults to "off".
+      # @option options [String] :gowalla Set to "on" to pass checkin on to Gowalla.  Defaults to "off".
+      # @return [Hashie::Mash] The results of the checkin. Includes info for beer, venue, badges earned, and recommendations.
+      # @example Checkin to beer with ID 6284 from Eastern time zone (GMT - 5 hours).
+      #   Untappd.checkin(-5, 6284)
+      def checkin(beer_id, gmt_offset, options={})
+        options.merge!(:gmt_offset => gmt_offset, :bid => beer_id)
+        post('/checkin', options)
+      end
+      
+      # Add a comment to a checkin.
+      #
+      # @format :json
+      # @authenticated true 
+      # @param checkin_id [String, Integer] The ID of the checkin you wish to comment on.
+      # @param comment [String] The comment text you would like to add.  Max 140 characters.
+      # @return [Hashie::Mash] The results of adding the comment. Includes user and comment details.
+      # @example Comment on checkin with ID 669114 and comment text of "Nice."
+      #   Untappd.add_comment(669114, "Nice.")
+      def add_comment(checkin_id, comment)
+        options = { :checkin_id => checkin_id, :comment => comment }
+        post('/add_comment', options)
+      end
+
+      # Delete a comment made by the authenticated user.
+      #
+      # @format :json
+      # @authenticated true 
+      # @param comment_id [String, Integer] The ID of the comment you wish to delete.
+      # @return [Hashie::Mash] The results of deleting the comment.
+      # @example Delete comment with ID 669114.
+      #   Untappd.delete_comment(669114)
+      def delete_comment(comment_id)
+        options = { :comment_id => comment_id }
+        post('/delete_comment', options)
+      end
+
+      # Toast a checkin.
+      #
+      # @format :json
+      # @authenticated true 
+      # @param checkin_id [String, Integer] The ID of the checkin you wish to toast.
+      # @return [Hashie::Mash] The results of the toast.
+      # @example Toast checkin with ID 669114.
+      #   Untappd.toast(669114)
+      def toast(checkin_id)
+        options = { :checkin_id => checkin_id }
+        post('/toast', options)
+      end
+
+      # Remove a toast made by the authenticated user from a checkin.
+      #
+      # @format :json
+      # @authenticated true 
+      # @param checkin_id [String, Integer] The ID of the checkin you wish to remove your toast from.
+      # @return [Hashie::Mash] The results of the toast removal.
+      # @example Remove toast from checkin with ID 669114.
+      #   Untappd.remove_toast(669114)
+      def untoast(checkin_id)
+        options = { :checkin_id => checkin_id }
+        post('/delete_toast', options)
+      end
+    end
+  end
+end

data/lib/untappd/client/user.rb

@@ -0,0 +1,95 @@
+module Untappd
+  class Client
+    module User
+
+      # Returns the feed for the specified user.
+      #
+      # @format :json
+      # @authenticated false unless :name option is omitted.
+      # @option options [String] :user The user whose feed you wish to request.  If not provided, the feed of the authenticated user will be returned.
+      # @option options [String, Integer] :since The ID of the last recent check-in.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Hashie::Mash] The requested user feed.
+      # @example Retrieve the feed for user with username "gambrinus".
+      #   Untappd.user_feed(:user => "gambrinus")
+      def user_feed(options={})
+        get('/user_feed', options)
+      end
+
+      # Returns the friend feed for the authenticated user.
+      #
+      # @format :json
+      # @authenticated true
+      # @option options [String, Integer] :since The ID of the last recent check-in.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Hashie::Mash] The requested friend feed of the authenticated user.
+      # @example Retrieve the friend feed for the authenticated user.
+      #   Untappd.friend_feed
+      def friend_feed(options={})
+        get('/feed', options)
+      end
+
+      # Returns the info for the requested user.
+      #
+      # @format :json
+      # @authenticated false unless :user option is omitted.
+      # @option options [String] :user The username of the user you wish to request info for.  Returns info for authenticated user if omitted.
+      # @return [Hashie::Mash] The requested user info.
+      # @example Retrieve the info for the user with username "gambrinus".
+      #   Untappd.user(:user => "gambrinus')
+      def user(options={})
+        get('/user', options)
+      end
+
+      # Returns the badge info for the requested user.
+      #
+      # @format :json
+      # @authenticated false unless :user option is omitted.
+      # @option options [String] :user The username of the user you wish to request info for.  Returns info for authenticated user if omitted.
+      # @return [Hashie::Mash] The badge info for the requested user.
+      # @example Retrieve the badge info for the user with username "gambrinus".
+      #   Untappd.badges(:user => "gambrinus')
+      def badges(options={})
+        get('/user_badge', options)
+      end
+
+      # Returns the friends for the requested user.
+      #
+      # @format :json
+      # @authenticated false unless :user option is omitted.
+      # @option options [String] :user The username of the user you wish to request info for.  Returns info for authenticated user if omitted.
+      # @return [Hashie::Mash] The friends of the requested user.
+      # @example Retrieve the friends of the user with username "gambrinus".
+      #   Untappd.friends(:user => "gambrinus')
+      def friends(options={})
+        get('/friends', options)
+      end
+
+      # Returns the wish list of the requested user.
+      #
+      # @format :json
+      # @authenticated false unless :user option is omitted.
+      # @option options [String] :user The username of the user you wish to request info for.  Returns info for authenticated user if omitted.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Hashie::Mash] The wish list of the requested user.
+      # @example Retrieve the wish list of the user with username "gambrinus".
+      #   Untappd.wish_list(:user => "gambrinus')
+      def wish_list(options={})
+        get('/wish_list', options)
+      end
+
+      # Returns the distinct beers of the requested user.
+      #
+      # @format :json
+      # @authenticated false unless :user option is omitted.
+      # @option options [String] :user The username of the user you wish to request info for.  Returns info for authenticated user if omitted.
+      # @option options [String, Integer] :offset The offset you would like the dataset to begin with.
+      # @return [Hashie::Mash] The distinct beers of the requested user.
+      # @example Retrieve the distinct beers of the user with username "gambrinus".
+      #   Untappd.distinct_beers(:user => "gambrinus')
+      def distinct_beers(options={})
+        get('/user_distinct', options)
+      end
+    end
+  end
+end