foursquared 0.0.4

data/.gitignore

@@ -0,0 +1,10 @@
+vendor/bundle/
+.bundle/
+coverage/
+spec/reports
+*.log
+.yardoc
+*.gem
+yardoc/
+*~
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format doc

data/Gemfile

@@ -0,0 +1,19 @@
+source :rubygems
+
+
+group :osx do
+  gem "growl"
+end
+
+group :linux do
+  gem "rb-inotify"
+  gem "libnotify"
+end
+
+group :windows do
+  gem "wdm", "~> 0.0.3"
+  gem "win32console"
+  gem "rb-notifu"
+end
+
+gemspec

data/Guardfile

@@ -0,0 +1,6 @@
+
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Rony Varghese
+
+MIT License
+
+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,30 @@
+# Foursquared
+[![Build Status](https://travis-ci.org/ronyv89/foursquared.png)](https://travis-ci.org/ronyv89/foursquared)
+
+Simple client library for Foursquare API V2 with OAuth2 authentication
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'foursquared'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install foursquared
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,30 @@
+require 'rspec/core/rake_task'
+require "rake/tasklib"
+require 'ci/reporter/rake/rspec'
+require 'yard'
+require 'yard/rake/yardoc_task'
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new(:spec => ["ci:setup:rspec"]) do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => :spec
+
+desc "Analyze for code complexity"
+task :metric_abc do
+  puts `bundle exec metric_abc \`find lib/ -iname '*.rb'\``
+end
+
+
+
+YARD::Rake::YardocTask.new(:yard) do |y|
+  y.options = ["--output-dir", "yardoc"]
+end
+
+namespace :yardoc do
+  desc "generates yardoc files to yardoc/"
+  task :generate => :yard do
+    puts "Yardoc files generated at yardoc/"
+  end
+end

data/foursquared.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'foursquared/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "foursquared"
+  gem.platform      = Gem::Platform::RUBY
+  gem.version       = Foursquared::VERSION
+  gem.authors       = ["Rony Varghese"]
+  gem.email         = ["ronyv250289@gmail.com"]
+  gem.description   = "Simple foursquare api client"
+  gem.summary       = "Simple foursquare api client"
+  gem.homepage      = "https://github.com/ronyv89/foursquared"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  gem.add_dependency 'httmultiparty'
+  gem.add_dependency 'oauth2'
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "guard"
+  gem.add_development_dependency "guard-rspec"
+  gem.add_development_dependency "simplecov"
+  gem.add_development_dependency "metric_abc"
+  gem.add_development_dependency "yard"
+  gem.add_development_dependency "ci_reporter"
+  gem.add_development_dependency "simplecov-rcov"
+  gem.add_development_dependency "rdiscount"
+  gem.add_development_dependency "webmock"
+  gem.add_development_dependency "rspec_multi_matchers"
+end

data/lib/core_ext/symbol.rb

@@ -0,0 +1,7 @@
+# Ruby's builtin Symbol class
+class Symbol
+  # Convert camel case symbol to snake case symbol
+  def to_usym
+    to_s.gsub(/(.)([A-Z])/,'\1_\2').downcase.to_sym
+  end
+end

data/lib/foursquared/badges.rb

@@ -0,0 +1,12 @@
+module Foursquared
+  # Badges module
+  module Badges
+    # Badge details
+    # @param [String] badge_id required, The id of the badge
+    # @return [Foursquared::Response::Badge]
+    def badge badge_id
+      response = get("/badges/#{badge_id}")["response"]
+      Foursquared::Response::Badge.new(self,response["badge"])
+    end
+  end
+end

data/lib/foursquared/checkins.rb

@@ -0,0 +1,89 @@
+# Foursquared module
+module Foursquared
+  # Checkins module
+  module Checkins
+
+    # Get details of a checkin. 
+    # @param [String] checkin_id The ID of the checkin to retrieve additional information for.
+    # @param [Hash] options
+    # @option options [String] :signature
+    # @return [Foursquared::Response::Checkin] A checkin object
+    def checkin checkin_id, options={}
+      response = get("/checkins/#{checkin_id}",options)["response"]
+      @checkin = Foursquared::Response::Checkin.new(self, response["checkin"])
+    end
+
+    # Create a check-in 
+    # @param [Hash] options
+    # @option options [String] :venueId required The venue where the user is checking in.
+    # @option options [String] :eventId The event the user is checking in to.
+    # @option options [String] :shout A message about your check-in
+    # @option options [String] :mentions Semicolon-delimited list of mentions
+    # @option options [String] :broadcast Who to broadcast this check-in to
+    # @option options [String] :ll Latitude and longitude of the user's location.
+    # @option options [String] :llAcc Accuracy of the user's latitude and longitude, in meters
+    # @option options [String] :alt Altitude of the user's location, in meters.
+    # @option options [String] :altAcc Vertical accuracy of the user's location, in meters.
+    # @return [Foursquared::Response::Checkin] A checkin object
+    def add_checkin options={}
+      response = post("/checkins/add", options)["response"]
+      {:checkin => Foursquared::Response::Checkin.new(self, response["checkin"]), :notifications => Foursquared::Response::Notifications.new(self, response["notifications"])}
+    end
+
+    # Recent checkins by friends
+    # @param [Hash] options
+    # @option options [String] :ll Latitude and longitude of the user's location, so response can include distance
+    # @option options [Integer] :limit Number of results to return, up to 100.
+    # @option options [Integer] :afterTimestamp Seconds after which to look for checkins
+    # @return [Array] An array of checkin objects with user details present
+    def recent_checkins options={}
+      response = get("/checkins/recent", options)["response"]
+      @checkins = response["recent"].collect{|checkin| Foursquared::Response::Checkin.new(self, checkin)}
+    end
+
+    # Users who have liked a checkin
+    # @param [String] checkin_id The ID of the checkin to get likes for.
+    # @return [Hash] A count and groups of users who like this checkin
+    def checkin_likes checkin_id
+      response = get("/checkins/#{checkin_id}/likes")["response"]
+      @likes = response["likes"]
+      @likes.groups.each{|group| group["items"].map!{|item|Foursquared::Response::User.new(self, item)}}
+      @likes
+    end
+
+    # Add a comment to a check-in 
+    # @param [String] checkin_id The ID of the checkin to add a comment to.
+    # @param [Hash] options
+    # @option options [String] :text The text of the comment, up to 200 characters.
+    # @option options [String] :mentions Mentions in your check-in.
+    # @return [Hash] The newly-created comment.
+    def add_checkin_comment checkin_id, options={}
+      response = post("/checkins/#{checkin_id}/addcomment", options)["response"]
+      @comment = response["comment"]
+      @comment["user"] = Foursquared::Response::User.new(self, @comment["user"])
+      @comment
+    end
+
+    # Remove commment from check-in
+    # @param [String] checkin_id The ID of the checkin to remove a comment from.
+    # @param [Hash] options
+    # @option options [String] :commentId
+    # @return [Foursquared::Response::Checkin] The checkin, minus this comment.
+    def delete_checkin_comment checkin_id, options={}
+      response = post("/checkins/#{checkin_id}/deletecomment", options)["response"]
+      @checkin = Foursquared::Response::Checkin.new(self, response["checkin"])
+    end
+
+    # Like or unlike a checkin
+    # @param [String] checkin_id The ID of the checkin to like
+    # @param [Hash] options
+    # @option options [Integer] :set If 1, like this checkin. If 0 unlike (un-do a previous like) it. Default value is 1.
+    def like_checkin checkin_id, options={}
+      response =  post("/checkins/#{checkin_id}/like", options)["response"]["likes"]
+      response["groups"].each do |group|
+        group["items"].map!{|item| Foursquared::Response::User.new(self, item)}
+      end
+      response
+    end
+  end
+end

data/lib/foursquared/client.rb

@@ -0,0 +1,58 @@
+require 'httmultiparty'
+# Foursquared module
+module Foursquared
+  # The Client class
+  class Client
+    attr_accessor :access_token
+    include HTTMultiParty
+    include Users
+    include Photos
+    include Lists
+    include Venues
+    include Checkins
+    include Badges
+    include Events
+    include Pages
+    base_uri 'https://api.foursquare.com/v2/'
+    format :json
+
+    def initialize credentials={}
+      
+      if credentials[:access_token]
+        self.class.default_params :oauth_token => credentials[:access_token]
+      elsif credentials[:client_id] and credentials[:client_secret]
+        self.class.default_params :client_id => credentials[:client_id]
+        self.class.default_params :client_secret => credentials[:client_secret]
+      else
+        raise "Must provide access_token or client_id and client_secret"
+      end
+    end
+
+    # Do a 'get' request
+    # @param [String] url the url to get
+    # @param [Hash] options Additonal options to be passed
+    def get url, options={}
+      options.merge!({:v => Time.now.strftime("%Y%m%d")}) unless options[:v]
+      response = self.class.get(url, {:query => options}).parsed_response
+      if response["meta"]["code"] == 200
+        return response
+      else
+        raise Foursquared::Error.new(response["meta"])
+      end
+    end
+
+    # Do a 'post' request
+    # @param [String] url the url to post
+    # @param [Hash] options Additonal options to be passed
+    def post url, options={}
+      options.merge!({:v => Time.now.strftime("%Y%m%d")}) unless options[:v]
+      response = self.class.post(url, {:body => options}).parsed_response
+      if response["meta"]["code"] == 200
+        return response
+      else
+        raise Foursquared::Error.new(response["meta"])
+      end
+    end
+
+  end
+end

data/lib/foursquared/error.rb

@@ -0,0 +1,17 @@
+module Foursquared
+  # Error class
+  class Error < StandardError
+    attr_reader :code, :type, :detail
+    def initialize meta
+      @code = meta["code"]
+      @detail = meta["errorDetail"]
+      @type = meta["errorType"]
+    end
+
+    # Error message to be displayed on encountering Foursquare::Error
+    def message
+      "#{type}: #{detail} (#{code})"
+    end
+    alias :to_s :message
+  end
+end

data/lib/foursquared/events.rb

@@ -0,0 +1,18 @@
+module Foursquared
+  # Events module
+  module Events
+    # Return the event with the give ID
+    # @return [Foursquared::Response::Event]
+    def event event_id
+      response = get("/events/#{event_id}")["response"]
+      Foursquared::Response::Event.new(self,response["event"])
+    end
+
+    # Return the available event categories
+    # @return [Array] An array of event categories
+    def event_categories
+      response = get("/events/categories")["response"]
+      response["categories"].collect{|category| Foursquared::Response::Category.new(self, category)}
+    end
+  end
+end

data/lib/foursquared/lists.rb

@@ -0,0 +1,97 @@
+module Foursquared
+  # Lists module
+  module Lists
+    # Gives details about a list.
+    # @param [String] list_id required, ID for a list
+    # @param [Hash] options
+    # @option options [Integer] :limit Number of results to return, up to 200.
+    # @option options [Integer] :offset The number of results to skip
+    # @option options [String] :llBounds Restricts the returned results to the input bounding box.
+    # @option options [String] :categoryId Restricts the returned results to venues matching the input category id.
+    # @return [Foursquared::Response::List]
+    def list list_id, options={}
+      response = get("/lists/#{list_id}", options)["response"]
+      @list = Foursquared::Response::List.new(self, response["list"])
+    end
+
+    # Add a List
+    # @param [Hash] options
+    # @option options [String] :name required, The name of the list.
+    # @option options [String] :description The description of the list.
+    # @option options [Boolean] :collaborative Boolean indicating if this list can be edited by friends.
+    # @option options [String] :photoId The id of a photo that should be set as the list photo.
+    # @return [Foursquared::Response::List] The added list
+    def add_list options={}
+      response = post("/lists/add", options)["response"]
+      Foursquared::Response::List.new(self, response["list"])
+    end
+
+    # Suggests photos that may be appropriate for a list item. 
+    # @param [String] list_id required, ID for a list
+    # @param [Hash] options
+    # @option options [String] :itemId required, The ID of the list item
+    # @return [Hash] Groups user and others containing lists (a count and items of photos) of photos uploaded by this user and uploaded by other users.
+    def suggest_list_photo list_id, options={}
+      @photos = get("/lists/#{list_id}/suggestphoto", options)["response"]["photos"]
+      if @photos
+        @photos.each_key do |key|
+          key["items"] = key["items"].collect{|photo| Foursquared::Response::Photo.new(client, photo)}
+        end
+      end
+      @photos
+    end
+
+    # Suggests venues that may be appropriate for a list.
+    # @param [String] list_id required, ID for a list
+    # @return [Array] Compact venues that may be appropriate for this list.
+    def suggest_list_venues list_id
+      @suggested_venues = get("/lists/#{list_id}/suggestvenues")["response"]["suggestedVenues"]
+      @suggested_venues.each do |item|
+        item["venue"] = Foursquared::Response::Venue.new(self, item["venue"])
+      end
+      @suggested_venues
+    end
+
+    # Suggests tips that may be appropriate for a list item
+    # @param [String] list_id required, ID for a list
+    # @param [Hash] options
+    # @option options [String] :itemId required, The ID of the list item
+    def suggest_list_tip list_id, options={}
+      @tips = get("/lists/#{list_id}/suggesttip", options)["response"]["tips"]
+      if @tips
+        @tips.each_key do |key|
+          key["items"].map!{|item| Foursquared::Response::Photo.new(client, item)}
+        end
+      end
+      @tips
+    end
+
+    # Add an Item to a list
+    # @param [String] list_id required, ID for a list
+    # @param [Hash] options
+    # @option options [String] :venueId A venue to add to the list
+    # @option options [String] :text If the target is a user-created list, this will create a public tip on the venue. If the target is /userid/todos, the text will be a private note that is only visible to the author.
+    # @option options [String] :url  If adding a new tip via text, this can associate a url with the tip.
+    # @option options [String] :tipId Used to add a tip to a list. Cannot be used in conjunction with the text and url fields.
+    # @option options [String] :listId Used in conjuction with itemId, the id for a user created or followed list as well as one of USER_ID/tips, USER_ID/todos, or USER_ID/dones.
+    # @option options [String] :itemId Used in conjuction with listId, the id of an item on that list that we wish to copy to this list.
+    # @return [Foursquared::Response::ListItem] The newly added list item
+    def add_list_item list_id, options={}
+      @item = post("/lists/#{list_id}/additem", options)["response"]["item"]
+      Foursquared::Response::ListItem.new(client, @item) if @item
+    end
+
+    # Delete an item from the list
+    # @param [String] list_id required, ID for a list
+    # @param [Hash] options
+    # @option options [String] :venueId ID of a venue to be deleted.
+    # @option options [String] :itemId ID of the item to delete.
+    # @option options [String] :tipId id of a tip to be deleted.
+    # @return [Hash] A count and items of list items that were just deleted.
+    def delete_list_item list_id, options={}
+      @items = client.post("/lists/#{list_id}/deleteitem", options)["response"]["items"]
+      @items["items"].map!{|item| Foursquared::Response::ListItem.new(client, item)}
+      @list_items
+    end
+  end
+end

data/lib/foursquared/oauth/client.rb

@@ -0,0 +1,37 @@
+require 'oauth2'
+module Foursquared
+  # OAuth module
+  module OAuth
+    # OAuth Client class
+    class Client     
+      attr_accessor :client_id, :client_secret, :oauth_client, :callback_url, :access_token
+      def initialize(client_id, client_secret, callback_url, opts={}, &block)
+        @client_id = client_id
+        @client_secret = client_secret
+        @callback_url = callback_url
+        ssl = opts.delete(:ssl)
+
+        @options = {
+                    :site => 'https://foursquare.com/',
+                    :authorize_url => '/oauth2/authenticate?response_type=code',
+                    :token_url => '/oauth2/access_token',
+                    :parse_json => true}.merge(opts)
+        @options[:connection_opts][:ssl] = ssl if ssl
+        @oauth_client = OAuth2::Client.new(client_id, client_secret, @options)
+      end
+
+      # Step 1: URL for OAuth2 oauthorizetion of Foursquare
+      # @return [String]
+      def authorize_url
+        oauth_client.auth_code.authorize_url(:redirect_uri => callback_url)
+      end
+
+      # Step 2: Get access token after authorizing user
+      # @param [String] code The value extracted from the callback url param 'code'
+      def get_access_token code
+        token = oauth_client.auth_code.get_token(code, :redirect_uri => callback_url)
+        @access_token = token.token
+      end
+    end
+  end
+end

data/lib/foursquared/pages.rb

@@ -0,0 +1,49 @@
+module Foursquared
+  # Pages module
+  module Pages
+    # Return the page with the given ID
+    # @param [String] page_id ID of the page
+    # @return [FOursquared::Response::User]
+    def page page_id
+      response  = get("/pages/#{page_id}")["response"]
+      @page = Foursquared::Response::User.new(self, response["user"])
+    end
+
+    # Search Pages
+    # @param [Hash] options
+    # @option options [String] :name  A search term to be applied against page names.
+    # @option options [String] :twitter A comma-delimited list of Twitter handles to look for.
+    # @option options [String] :fbid A comma-delimited list of Facebook ID's to look for.
+    def page_search options={}
+      response = get("/pages/search",options)["response"]
+      @pages = response.collect{|result| Foursquared::Response::User.new(self, result)}
+    end
+
+    # Returns the page's venues.
+    # @param [String] page_id ID of the page
+    # @param [Hash] options
+    # @option options [String] :ll Not valid with ne or sw. Limits results to venues near this latitude and longitude within an optional radius.
+    # @option options [String] :radius Not valid with ne or sw. Limit results to venues within this many meters of the specified ll
+    # @option options [String] :sw With ne, limits results to the bounding quadrangle defined by the latitude and longitude given by sw as its south-west corner, and ne as its north-east corner.
+    # @option options [String] :ne See sw
+    # @option options [Integer] :offset The offset of which venues to return. Defaults to 0.
+    # @option options [String] :limit The number of venues to return. Defaults to 20, max of 100.
+    # @return [Hash] Count and items of venues
+    def page_venues page_id, options={}
+      @venues = get("/pages/#{page_id}/venues", options)["response"]["venues"]
+      @venues["items"].map!{|item| Foursquared::Response::Venue.new(self, item)}
+      @venues
+    end
+
+    # Like or unlike a page
+    # @param [String] page_id ID of the page to like or unlike.
+    # @param [Hash] options
+    # @option options [Integer] :set If 1, like this page. If 0 unlike (un-do a previous like) it. Default value is 1.
+    # @return [Foursquared::Response::User]
+    def like_page page_id, options={}
+      response = post("/pages/#{page_id}/like",options)["response"]
+      @page = Foursquared::Response::User.new(self, response["user"])
+    end
+
+  end
+end

data/lib/foursquared/photos.rb

@@ -0,0 +1,34 @@
+module Foursquared
+  # photos module
+  module Photos
+    # Return the photo with the given ID
+    # @param photo_id The id of the photo
+    # @return [Foursquared::Response::Photo]
+    def photo photo_id
+      response = get("/photos/#{photo_id}")["response"]
+      @photo = Response::Photo.new(self, response["photo"])
+    end
+
+    # Add a new photo to a checkin, tip, venue, or page update in general. 
+    # @param [Hash] options
+    # @option options [String] :checkinId the ID of a checkin owned by the user.
+    # @option options [String] :tipId the ID of a tip owned by the user.
+    # @option options [String] :venueId the ID of a venue, provided only when adding a public photo of the venue in general, rather than a photo for a private checkin, tip, or page update.
+    # @option options [String] :pageId the ID of a page, provided only when adding a photo that will be in an update for that page
+    # @option options [String] :broadcast Whether to broadcast this photo example: twitter,facebook
+    # @option options [Integer] :public When the checkinId is also provided this parameter allows for making the photo public and viewable at the venue. 1 or 0
+    # @option options [String] :ll Latitude and longitude of the user's location.
+    # @option options [String] :llAcc Accuracy of the user's latitude and longitude, in meters.
+    # @option options [String] :alt Altitude of the user's location, in meters.
+    # @option options [String] :altAcc Vertical accuracy of the user's location, in meters.
+    # @option options [String] :postUrl A link for more details about the photo. 
+    # @option options [String] :postContentId Identifier for the photo post to be used in a native link
+    # @option options [String] :postText Text for the photo post, up to 200 characters. A checkinId must also be specified in the request.
+    # @return [Foursquared::Response::Photo] The photo that was just created.
+    def add_photo options={}
+      response = post("/photos/add", options)["response"]
+      @photo = Response::Photo.new(self, response["photo"])
+    end
+
+  end
+end