quimby 0.2.2

data/README.md

@@ -0,0 +1,81 @@
+# Quimby
+
+### Formerly named after a pop star whose lawyers decided they didn't like us using his name.
+
+It's a Foursquare API wrapper. It uses objects instead of hashes, and tries to be smart about when to load things. 
+
+## Usage
+
+Get a foursquare:
+
+    foursquare = Foursquare::Base.new("ACCESS_TOKEN")
+
+You can also user `client_id` and `client_secret`
+
+    foursquare = Foursquare::Base.new("CLIENT_ID", "CLIENT_SECRET")
+
+### Users
+
+Find a user:
+
+    user = foursquare.users.find("USER_ID")
+
+Now we've got a `Foursquare::User` object. You can call sweet methods like `user.name` and even
+`user.last_checkin`. **In general, John Mayer's Foursquare object methods are just snake-cased
+versions of the attributes returned in the JSON.** Now let's accidentally that user's friends:
+
+    user.friends
+
+This will return an array of `Foursquare::User` objects. Don't worry about the fact that they're
+populated by limited JSON. Quimby will fetch the extra JSON if you need it. For example:
+
+    friend = user.friends.first
+    friend.name # Will not trigger a network call, since we already have it
+    friend.twitter # Will trigger a network to load the user's contact information
+
+### Checkins
+
+But wait, Foursquare isn't just users! It's checkins too! So let's find some checkins:
+
+    user.checkins
+
+Now we have an array of `Foursquare::Checkin` objects. We can also grab a specific checkin:
+
+    checkin = foursquare.checkins.find("CHECKIN_ID")
+
+### Venues
+
+We can get at a checkin's venue by calling `checkin.venue`. Pretty easy, RIGHT? Right. If you want to
+find a venue directly, here ya go:
+
+    foursquare.venues.find("VENUE_ID")
+
+You can also search venues:
+
+    foursquare.venues.search(:ll => "40.7236307,-73.9999479") # Returns all resulting groups
+    foursquare.venues.nearby(:ll => "40.7236307,-73.9999479") # Returns only nearby venues
+    foursquare.venues.trending(:ll => "40.7236307,-73.9999479") # Returns only trending venues
+    foursquare.venues.favorites(:ll => "40.7236307,-73.9999479") # Returns only favorite venues
+
+The `:ll` option is required for venue searches. You can also feel free to pass any of the other
+available Foursquare API options, as specified in the docs.
+
+### Logging
+
+If you want to see what's going on up in there, you can set `Foursquare.verbose` to `true`
+
+    Foursquare.verbose = true
+
+Right now it'll log to `STDOUT`. Maybe I'll add nicer logging later. If you're lucky. In the meantime,
+if you want to use your own logger, and you're kind of a jerk like me, you can do something like this:
+
+    Foursquare.verbose = true
+    def Foursquare.log(message)
+      Rails.logger.info("[foursquare] #{message}") # HAX, SORRY BRANDON
+    end
+
+## TODO
+
+* Creating checkins works, but it should really return notifications. Also, if the
+  checkin can't be created, it should return errors.
+* I don't know, so much other stuff.

data/lib/foursquare.rb

@@ -0,0 +1,44 @@
+$LOAD_PATH << File.dirname(__FILE__)
+
+require "rubygems"
+require "typhoeus"
+require "json"
+require "cgi"
+require "foursquare/base"
+require "foursquare/checkin_proxy"
+require "foursquare/checkin"
+require "foursquare/user_proxy"
+require "foursquare/user"
+require "foursquare/venue_proxy"
+require "foursquare/venue"
+require "foursquare/settings"
+require "foursquare/tip"
+require "foursquare/photo"
+
+module Foursquare
+  class Error < StandardError ; end
+
+  def self.verbose=(setting)
+    @verbose = setting
+  end
+
+  def self.verbose?
+    @verbose
+  end
+
+  def self.log(msg)
+    return unless verbose?
+    puts "[foursquare] #{msg}"
+  end
+
+  ERRORS = {
+    "invalid_auth" => "OAuth token was not provided or was invalid.",
+    "param_error" => "A required parameter was missing or a parameter was malformed. This is also used if the resource ID in the path is incorrect.",
+    "endpoint_error" => "The requested path does not exist.",
+    "not_authorized" => "Although authentication succeeded, the acting user is not allowed to see this information due to privacy restrictions.",
+    "rate_limit_exceeded" => "Rate limit for this hour exceeded.",
+    "deprecated" => "Something about this request is using deprecated functionality, or the response format may be about to change.",
+    "server_error" => "Server is currently experiencing issues. Check status.foursquare.com for udpates.",
+    "other" => "Some other type of error occurred."
+  }
+end

data/lib/foursquare/base.rb

@@ -0,0 +1,81 @@
+module Foursquare
+  class Base
+    API = "https://api.foursquare.com/v2/"
+
+    def initialize(*args)
+      case args.size
+      when 1
+        @access_token = args.first
+      when 2
+        @client_id, @client_secret = args
+      else
+        raise ArgumentError, "You need to pass either an access_token or client_id and client_secret"
+      end
+    end
+
+    def users
+      Foursquare::UserProxy.new(self)
+    end
+
+    def checkins
+      Foursquare::CheckinProxy.new(self)
+    end
+
+    def venues
+      Foursquare::VenueProxy.new(self)
+    end
+
+    def settings
+      @settings ||= Foursquare::Settings.new(self)
+    end
+
+    def get(path, params={})
+      params = camelize(params)
+      Foursquare.log("GET #{API + path}")
+      Foursquare.log("PARAMS: #{params.inspect}")
+      merge_auth_params(params)
+      response = JSON.parse(Typhoeus::Request.get(API + path, :params => params).body)
+      Foursquare.log(response.inspect)
+      error(response) || response["response"]
+    end
+
+    def post(path, params={})
+      params = camelize(params)
+      Foursquare.log("POST #{API + path}")
+      Foursquare.log("PARAMS: #{params.inspect}")
+      merge_auth_params(params)
+      response = JSON.parse(Typhoeus::Request.post(API + path, :params => params).body)
+      Foursquare.log(response.inspect)
+      error(response) || response["response"]
+    end
+
+    private
+
+    def camelize(params)
+      params.inject({}) { |o, (k, v)|
+        o[k.to_s.gsub(/(_[a-z])/) { |m| m[1..1].upcase }] = v
+        o
+      }
+    end
+
+    def error(response)
+      case response["meta"]["errorType"]
+      when nil
+        # It's all good.
+      when "deprecated"
+        Foursquare.log(Foursquare::ERRORS[response['meta']['errorType']])
+        nil
+      else
+        raise Foursquare::Error.new(Foursquare::ERRORS[response['meta']['errorType']])
+      end
+    end
+
+    def merge_auth_params(params)
+      if @access_token
+        params.merge!(:oauth_token => @access_token)
+      else
+        params.merge!(:client_id => @client_id, :client_secret => @client_secret)
+      end
+    end
+  end
+end

data/lib/foursquare/checkin.rb

@@ -0,0 +1,56 @@
+module Foursquare
+  class Checkin
+    attr_reader :json
+
+    def initialize(foursquare, json)
+      @foursquare, @json = foursquare, json
+    end
+
+    def id
+      @json["id"]
+    end
+
+    def fetch
+      @json = @foursquare.get("checkins/#{id}")["checkin"]
+      self
+    end
+
+    def type
+      @json["type"]
+    end
+
+    def shout?
+      type == "shout"
+    end
+
+    def created_at
+      Time.at(@json["createdAt"].to_i)
+    end
+
+    def shout
+      @json["shout"]
+    end
+
+    def mayor?
+      @json["isMayor"]
+    end
+
+    def timezone
+      @json["timeZone"]
+    end
+
+    def venue
+      @json["venue"] && Foursquare::Venue.new(@foursquare, @json["venue"])
+    end
+
+    def user(full=false)
+      fetch unless @json["user"]
+
+      if full
+        @foursquare.users.find(@json["user"]["id"])
+      else
+        Foursquare::User.new(@foursquare, @json["user"])
+      end
+    end
+  end
+end

data/lib/foursquare/checkin_proxy.rb

@@ -0,0 +1,32 @@
+module Foursquare
+  class CheckinProxy
+    def initialize(foursquare)
+      @foursquare = foursquare
+    end
+
+    def find(id)
+      Foursquare::Checkin.new(@foursquare, @foursquare.get("checkins/#{id}")["checkin"])
+    end
+
+    def recent(options={})
+      @foursquare.get("checkins/recent", options)["recent"].map do |json|
+        Foursquare::Checkin.new(@foursquare, json)
+      end
+    end
+
+    def all(options={})
+      @foursquare.get("users/self/checkins", options)["checkins"]["items"].map do |json|
+        Foursquare::Checkin.new(@foursquare, json)
+      end
+    end
+
+    def create(options={})
+      if json = @foursquare.post("checkins/add", options)
+        Foursquare::Checkin.new(@foursquare, json["checkin"])
+      else
+        nil
+      end
+    end
+    alias_method :add, :create
+  end
+end

data/lib/foursquare/multi.rb

@@ -0,0 +1,38 @@
+# Here's how I want this to work:
+#
+#   users, venues = foursquare.multi do |request|
+#     request.users.search :twitter => "nakajima"
+#     request.venues.search :ll => "12,-71"
+#   end
+#
+# It's just difficult to implement. So it's not implemented yet.
+module Foursquare
+  class Multi
+    def initialize(foursquare, block)
+      @foursquare = foursquare
+      @requests = []
+      @responses = []
+    end
+
+    def get(path, options={})
+      @requests << path + query(params)
+    end
+
+    def perform
+      responses = @foursquare.get("multi", :requests => @requests.join(','))
+    end
+
+    private
+
+    def query(params)
+      camelized = params.inject({}) { |o, (k, v)|
+        o[k.to_s.gsub(/(_[a-z])/) { |m| m[1..1].upcase }] = v
+        o
+      }
+      camelized.inject([]) { |o, (k, v)|
+        o << CGI.escape(k) + "=" CGI.escape(v)
+        o
+      }.join('&')
+    end
+  end
+end

data/lib/foursquare/photo.rb

@@ -0,0 +1,27 @@
+module Foursquare
+  class Photo
+    def initialize(foursquare, json)
+      @foursquare, @json = foursquare, json
+    end
+
+    def id
+      @json["id"]
+    end
+
+    def name
+      @json["name"]
+    end
+
+    def created_at
+      @json["createdAt"]
+    end
+
+    def url
+      @json["url"]
+    end
+
+    def sizes
+      @json["sizes"]
+    end
+  end
+end

data/lib/foursquare/settings.rb

@@ -0,0 +1,31 @@
+module Foursquare
+  class Settings
+    def initialize(foursquare, json={})
+      @foursquare, @json = foursquare, json
+    end
+
+    def fetch
+      @json = @foursquare.get('settings/all')["settings"]
+    end
+
+    def receive_pings?
+      fetch unless @json.has_key?('receivePings')
+      @json['receivePings']
+    end
+
+    def receive_comment_pings?
+      fetch unless @json.has_key?('receiveCommentPings')
+      @json['receiveCommentPings']
+    end
+
+    def send_to_twitter?
+      fetch unless @json.has_key?('sendToTwitter')
+      @json['sendToTwitter']
+    end
+
+    def send_to_facebook?
+      fetch unless @json.has_key?('sendToFacebook')
+      @json['sendToFacebook']
+    end
+  end
+end

data/lib/foursquare/tip.rb

@@ -0,0 +1,35 @@
+module Foursquare
+  class Tip
+    def initialize(foursquare, json)
+      @foursquare, @json = foursquare, json
+    end
+
+    def id
+      @json["id"]
+    end
+
+    def text
+      @json["text"]
+    end
+
+    def created_at
+      @json["createdAt"]
+    end
+
+    def status
+      @json["status"]
+    end
+
+    def photo
+      @json["photo"]
+    end
+
+    def user
+      @json["user"] && Foursquare::User.new(@foursquare, @json["user"])
+    end
+
+    def venue
+      @json["venue"] && Foursquare::Venue.new(@foursquare, @json["venue"])
+    end
+  end
+end

data/lib/foursquare/user.rb

@@ -0,0 +1,115 @@
+module Foursquare
+  class User
+    attr_reader :json
+
+    def initialize(foursquare, json)
+      @foursquare, @json = foursquare, json
+    end
+
+    def fetch
+      @json = @foursquare.get("users/#{id}")["user"]
+      self
+    end
+
+    def id
+      @json["id"]
+    end
+
+    def name
+      [first_name, last_name].join(' ').strip
+    end
+
+    def first_name
+      @json["firstName"]
+    end
+
+    def last_name
+      @json["lastName"]
+    end
+
+    def photo
+      @json["photo"]
+    end
+
+    def gender
+      @json["gender"]
+    end
+
+    def home_city
+      @json["homeCity"]
+    end
+
+    def relationship
+      @json["relationship"]
+    end
+
+    def pings
+      fetch unless @json.has_key?("pings")
+      @json["pings"]
+    end
+
+    def contact
+      fetch unless @json.has_key?("contact")
+      @json["contact"]
+    end
+
+    def email
+      contact["email"]
+    end
+
+    def twitter
+      contact["twitter"]
+    end
+
+    def phone_number
+      contact["phone"]
+    end
+
+    def badge_count
+      fetch unless @json.has_key?("badges")
+      @json["badges"]["count"]
+    end
+
+    def mayorships
+      fetch unless @json.has_key?("mayorships")
+      @json["mayorships"]["items"]
+    end
+
+    def checkin_count
+      fetch unless @json.has_key?("checkins")
+      @json["checkins"]["count"]
+    end
+
+    def last_checkin
+      fetch unless @json.has_key?("checkins")
+      return unless @json["checkins"]["items"]
+      item = @json["checkins"]["items"].last
+      Foursquare::Checkin.new(@foursquare, item)
+    end
+
+    def checkins_here
+      checkin_json = @foursquare.get("venues/#{last_checkin.venue.id}/herenow")
+      checkin_json["hereNow"]["items"].map do |item|
+        begin
+          next unless json = @foursquare.get("checkins/#{item["id"]}")
+          checkin = json["checkin"]
+          Foursquare::Checkin.new(@foursquare, checkin)
+        rescue Foursquare::Error
+          # We can't get checkin information for people who aren't our friends.
+        end
+      end.compact
+    end
+
+    def friends(options={})
+      @foursquare.get("users/#{id}/friends", options)["friends"]["items"].map do |item|
+        Foursquare::User.new(@foursquare, item)
+      end
+    end
+
+    def tips(options={})
+      @foursquare.get("users/#{id}/tips", options)["tips"]["items"].map do |item|
+        Foursquare::Tip.new(@foursquare, item)
+      end
+    end
+  end
+end

data/lib/foursquare/user_proxy.rb

@@ -0,0 +1,21 @@
+module Foursquare
+  class UserProxy
+    def initialize(foursquare)
+      @foursquare = foursquare
+    end
+
+    def self.search(foursquare, options={})
+      
+    end
+
+    def find(id)
+      Foursquare::User.new(@foursquare, @foursquare.get("users/#{id}")["user"])
+    end
+
+    def search(options={})
+      @foursquare.get("users/search", options)["results"].map do |json|
+        Foursquare::User.new(@foursquare, json)
+      end
+    end
+  end
+end

data/lib/foursquare/venue.rb

@@ -0,0 +1,51 @@
+module Foursquare
+  class Venue
+    attr_reader :json
+
+    def initialize(foursquare, json)
+      @foursquare, @json = foursquare, json
+    end
+
+    def id
+      @json["id"]
+    end
+
+    def name
+      @json["name"]
+    end
+
+    def contact
+      @json["contact"]
+    end
+
+    def location
+      @json["location"]
+    end
+
+    def categories
+      @json["categories"]
+    end
+
+    def verified?
+      @json["verified"]
+    end
+
+    def checkins_count
+      @json["stats"]["checkinsCount"]
+    end
+
+    def users_count
+      @json["stats"]["usersCount"]
+    end
+
+    def todos_count
+      @json["todos"]["count"]
+    end
+
+    def photos(options={:group => "checkin"})
+      @foursquare.get("venues/#{id}/photos", options)["photos"]["items"].map do |item|
+        Foursquare::Photo.new(@foursquare, item)
+      end
+    end
+  end
+end

data/lib/foursquare/venue_proxy.rb

@@ -0,0 +1,43 @@
+module Foursquare
+  class VenueProxy
+    def initialize(foursquare)
+      @foursquare = foursquare
+    end
+
+    def find(id)
+      Foursquare::Venue.new(@foursquare, @foursquare.get("venues/#{id}")["venue"])
+    end
+
+    def search(options={})
+      raise ArgumentError, "You must include :ll" unless options[:ll]
+      response = @foursquare.get('venues/search', options)["groups"].inject({}) do |venues, group|
+        venues[group["type"]] ||= []
+        venues[group["type"]] << group["items"].map do |json|
+          Foursquare::Venue.new(@foursquare, json)
+        end
+      end
+    end
+
+    def trending(options={})
+      search_group("trending", options)
+    end
+
+    def favorites(options={})
+      search_group("favorites", options)
+    end
+
+    def nearby(options={})
+      search_group("nearby", options)
+    end
+
+    private
+
+    def search_group(name, options)
+      raise ArgumentError, "You must include :ll" unless options[:ll]
+      response = @foursquare.get('venues/search', options)["groups"].detect { |group| group["type"] == name }
+      response ? response["items"].map do |json|
+        Foursquare::Venue.new(@foursquare, json)
+      end : []
+    end
+  end
+end

data/spec/THERE_ARENT_ANY

@@ -0,0 +1 @@
+My bad. Whatevz.

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification 
+name: quimby
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 0
+  - 2
+  - 2
+  version: 0.2.2
+platform: ruby
+authors: 
+- Pat Nakajima
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-14 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: typhoeus
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: 
+email: pat@groupme.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- lib/foursquare.rb
+- lib/foursquare/base.rb
+- lib/foursquare/settings.rb
+- lib/foursquare/tip.rb
+- lib/foursquare/multi.rb
+- lib/foursquare/checkin.rb
+- lib/foursquare/photo.rb
+- lib/foursquare/checkin_proxy.rb
+- lib/foursquare/user.rb
+- lib/foursquare/user_proxy.rb
+- lib/foursquare/venue.rb
+- lib/foursquare/venue_proxy.rb
+- spec/THERE_ARENT_ANY
+has_rdoc: true
+homepage: https://github.com/groupme/quimby
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.4.1
+signing_key: 
+specification_version: 3
+summary: A Foursquare API wrapper
+test_files: []
+