foursquared 0.0.4 → 0.0.5

data/.gitignore

@@ -8,3 +8,4 @@ spec/reports
 yardoc/
 *~
 Gemfile.lock
+tmp/

data/README.md

@@ -1,5 +1,4 @@
 # 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
@@ -18,8 +17,63 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### OAuth2 Authentication
 
+  Foursquare OAuth2 authentication is integrated here.
+  First you will have to initialize a Foursquared::OAuth::Client object with the client id, client secret and the callback url
+
+    oauth_client = Foursquared::OAuth::Client.new("your_client_id", "your_client_secret", "http://yourcallbackurl")
+
+  Obtain the authentication url 
+
+    auth_url = oauth_client.authorize_url
+
+  Redirect the user to the above obtained auth_url. After user gives access to your app, they will be redirected to the callback url with a 'code' parameter. Extract this code and get the access token by invoking the following method
+
+    access_token = oauth_client.get_access_token("the_extracted_code")
+
+### Instantiate a client
+  
+  After getting the access token instantiate the Foursquared client
+
+    client = Foursquared::Client.new(:access_token => "your_acess_token")
+
+  For userless access you can skip the above step and instantiate the client with your client id and client secret. 
+
+    client = Foursquared::Client.new(:client_id => "your_client_id", :client_secret => "your_client_secret")
+
+## Features
+
+1. Every response item is an object. For example, every user will be a Foursquared::Response::User.
+2. Each object will have its own actions. For example you can friend, unfriend or deny the request from a user after retrieving the user object.
+
+## Examples
+
+You can always navigate to [the documentation](http://rubydoc.info/gems/foursquared/frames) for a list of all supported methods and available options.
+
+### Get user details
+
+    client.user(10230)
+
+### Get a venue details
+
+    venue = client.venue("4b2afcaaf964a5205bb324e3")
+
+### Checkin at a venue
+  
+  You can use the above obtained Foursquared::Response::Venue object to checkin
+
+    venue.checkin(:broadcast => 'public', :ll => '36.142064,-86.816086', :shout => 'zomg coffee!1!')
+
+  You can also directly checkin at a venue providing its venue id.
+
+    client.add_checkin(:venueId => "4b2afcaaf964a5205bb324e3", :broadcast => 'public', :ll => '36.142064,-86.816086', :shout => 'zomg coffee!1!')
+
+## Todo
+  
+  * Add more tests
+  * Improve documentation
+  * Integrate more endpoints
 ## Contributing
 
 1. Fork it

data/lib/foursquared.rb

@@ -1,18 +1,11 @@
 require 'httmultiparty'
 require 'json'
 directory = File.expand_path(File.dirname(__FILE__))
-require 'core_ext/symbol'
 module Foursquared
   class << self
 
-    
     attr_accessor :client_id, :client_secret, :api_version, :ssl, :access_token, :locale 
-
-
-    def configure
-      yield self
-      true
-    end
+    
   end
 
   # require 'foursquare2/campaigns'
@@ -25,6 +18,7 @@ module Foursquared
   require 'foursquared/events'
   require 'foursquared/pages'
   require 'foursquared/specials'
+  require 'foursquared/settings'
   require 'foursquared/tips'
   require 'foursquared/oauth/client'
   require 'foursquared/client'

data/lib/foursquared/checkins.rb

@@ -24,10 +24,10 @@ module Foursquared
     # @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
+    # @return [Hash] A checkin object and the post checkin notifications
     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"])}
+      {:checkin => Foursquared::Response::Checkin.new(self, response["checkin"]), :notifications => response["notifications"]}
     end
 
     # Recent checkins by friends
@@ -45,9 +45,10 @@ module Foursquared
     # @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 = get("/checkins/#{checkin_id}/likes")["response"]["likes"]
+      @likes["groups"].each do |group|
+        group["items"].map!{|item|Foursquared::Response::User.new(self, item)}
+      end
       @likes
     end
 

data/lib/foursquared/client.rb

@@ -13,16 +13,22 @@ module Foursquared
     include Badges
     include Events
     include Pages
+    include Specials
+    include Settings
+    include Tips
     base_uri 'https://api.foursquare.com/v2/'
     format :json
-
+    
+    attr_accessor :client_id, :client_secret, :access_token
     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]
+      @client_id = credentials[:client_id]
+      @client_secret = credentials[:client_secret]
+      @access_token = credentials[:access_token]
+      if @access_token
+        self.class.default_params :oauth_token => @access_token
+      elsif @client_id and @client_secret
+        self.class.default_params :client_id => @client_id
+        self.class.default_params :client_secret => @client_secret
       else
         raise "Must provide access_token or client_id and client_secret"
       end

data/lib/foursquared/events.rb

@@ -14,5 +14,17 @@ module Foursquared
       response = get("/events/categories")["response"]
       response["categories"].collect{|category| Foursquared::Response::Category.new(self, category)}
     end
+
+    # Create an event for a venue that you manage.
+    # @param [Hash] options
+    # @option options [String] :venueId The id of the venue where the event is being held.
+    # @option options [String] :name The name of the event
+    # @option options [String] :start Time when the event is scheduled to start, in seconds since Unix epoch.
+    # @option options [String] :end Time when the event is scheduled to end, in seconds since Unix epoch.
+    def add_event
+      response = post("/events/categories")["response"]
+      Foursquared::Response::Event.new(self, response["event"])
+    end
+
   end
 end

data/lib/foursquared/oauth/client.rb

@@ -28,6 +28,7 @@ module Foursquared
 
       # Step 2: Get access token after authorizing user
       # @param [String] code The value extracted from the callback url param 'code'
+      # @return [String] the access token
       def get_access_token code
         token = oauth_client.auth_code.get_token(code, :redirect_uri => callback_url)
         @access_token = token.token

data/lib/foursquared/response/event.rb

@@ -3,21 +3,73 @@ module Foursquared
     # Event response
     class Event
       attr_reader :client, :response
+      
       def initialize client, response
         @client  = client
         @response = response
       end
 
-      [:id, :name, :url, :stats].each do |method_name|
-        define_method method_name do
-          response[method_name.to_s] if response
-        end
+
+      # The ID of the event
+      # @return [String]
+      def id
+        response["id"]
       end
 
-      [:venueId, :foreignIds, :categories, :allDay, :timeZone, :unlockMessage].each do |method_name|
-        define_method method_name.to_usym do
-          response[method_name.to_s] if response[method_name.to_s]
-        end
+      # The name of the event
+      # @return [String]
+      def name
+        response["name"]
+      end
+
+      # The website for the event
+      # @return [String]
+      def url
+        response["url"]
+      end
+
+      # The stats for the event
+      # @return [String]
+      def stats
+        response["stats"]
+      end
+
+      # The ID of the venue of the event
+      # @return [String]
+      def venue_id
+        response["venueId"]
+      end
+
+      # The count of ids of this event in third-party services, plus items, an array of domain, the third party provider, and id, the id in their system. 
+      # @return [Hash]
+      def foreign_ids
+        response["foreignIds"]
+      end
+
+      # The categories that have been applied to this event
+      # @return [Array<Foursquared::Response::Category>]
+      def categories
+        @categories = response["categories"]
+        @categories.map!{|category| Foursquared::Response::Category.new(client, category)} if @categories
+        @categories
+      end
+
+      # Whether the event happens throughout the day
+      # @return [Boolean]
+      def all_day?
+        response["allDay"]
+      end
+
+      # The time zone for the event 
+      # @return [String]
+      def time_zone
+        response["timeZone"]
+      end
+
+      # The unlock message for the checkin at the event
+      # @return [String]
+      def unlock_message
+        response["unlockMessage"]
       end
 
       # The time at which the event starts

data/lib/foursquared/response/venue.rb

@@ -247,6 +247,22 @@ module Foursquared
         response["specialsNearby"].map{|special| Foursquared::Response::Special.new(client, special)} if response["specialsNearby"]
       end
 
+      # Checkin at this venue
+      # @param [Hash] options
+      # @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 [Hash] A checkin object and the post checkin notifications
+      def checkin options={}
+        options.merge!({:venueId => id})
+        checkin_response = post("/checkins/add", options)["response"]
+        {:checkin => Foursquared::Response::Checkin.new(self, checkin_response["checkin"]), :notifications => response["notifications"]}
+      end
     end
   end
 end

data/lib/foursquared/version.rb

@@ -1,4 +1,4 @@
 module Foursquared
   # The gem version
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/foursquared/badges_spec.rb

@@ -57,26 +57,11 @@ describe Foursquared::Badges do
 
   subject { foursquared_test_client }
 
-  before(:each) do
-    stub_request(:get, "https://api.foursquare.com/v2/users/self/badges?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").to_return(:status => 200, :body => user_badges.to_json, :headers => {})
-    stub_request(:get, "https://api.foursquare.com/v2/badges/4f7a7d3ae4b02f1b2c869efb?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").
+  describe "#badge" do
+    it "should return the badge with the given badge ID" do
+      stub_request(:get, "https://api.foursquare.com/v2/badges/4f7a7d3ae4b02f1b2c869efb?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").
          to_return(:status => 200, :body => badge.to_json, :headers => {})
-    @user_badges = subject.user_badges("self")
-  end
-  describe "#user_badges" do
-    describe "sets" do
-      it "should give the sets of badge types" do
-        @user_badges["sets"]["groups"].should each { |group|
-          group.should be_a(Foursquared::Response::BadgeGroup)
-        }
-      end
-    end
-    describe "badges" do
-      it "should give the badges' details" do
-        @user_badges["badges"].keys.should each {|badge_id|
-          @user_badges["badges"][badge_id].should be_a(Foursquared::Response::Badge)
-        }
-      end
+      subject.badge("4f7a7d3ae4b02f1b2c869efb").should be_a(Foursquared::Response::Badge)
     end
   end
 end

data/spec/foursquared/checkins_spec.rb

@@ -0,0 +1,113 @@
+require 'spec_helper'
+describe Foursquared::Checkins do 
+
+  let(:checkin) do
+    YAML.load(%{
+      meta:
+        code: 200
+      notifications: []
+      response:
+        checkin:
+          id: "4d627f6814963704dc28ff94"
+          createdAt: 1298300776
+          type: "checkin"
+          shout: "Another one of these days. #snow"
+          timeZoneOffset: -300
+          user:
+            id: "32"
+            firstName: "Dens"
+            gender: "male"
+            photo: 
+              prefix: "https://irs0.4sqi.net/img/user/"
+              suffix: "/32_1239135232.jpg"
+          venue:
+            id: "408c5100f964a520c6f21ee3"
+            name: "Tompkins Square Park"
+
+    })
+  end
+
+  let(:recent_checkins) do
+    YAML.load(%{
+      meta:
+        code: 200
+      response:
+        recent:
+        - id: "50ec9b33e4b0b63dc59108bb"
+          createdAt: 1357683507
+          type: "checkin"
+          shout: "Shadow's photoshoot"
+          timeZoneOffset: 330
+        - id: "50ec7ad7e4b0beb130e3c6fb"
+          createdAt: 1357675223
+          type: "checkin"
+          timeZoneOffset: 330
+    })
+  end
+
+  let(:checkin_likes) do
+    YAML.load(%{
+      meta:
+        code: 200
+      response:
+        likes:
+          count: 2
+          groups:
+          - type: "others"
+            count: 2
+            items:
+            - id: "4006236"
+              firstName: "Shane"
+              lastName: "O."
+              gender: "male"
+              photo: 
+                prefix: "https://irs3.4sqi.net/img/user/"
+                suffix: "/OHXZCLCMRAGXPV3S.jpg"
+            - id: "591008"
+              firstName: "mi1ky"
+              lastName: "L."
+              gender: "female"
+              photo:
+                prefix: "https://irs1.4sqi.net/img/user/"
+                suffix: "/UX1JTWSNWY5YV1PS.jpg"
+          summary: "2 likes"
+    })
+  end
+  subject { foursquared_test_client }
+
+  describe "#add_checkin" do
+    it "should add a new checkin" do
+      stub_request(:post, "https://api.foursquare.com/v2/checkins/add?oauth_token=TestToken").
+         with(:body => "venueId=408c5100f964a520c6f21ee3&v=#{Time.now.strftime("%Y%m%d")}").to_return(:status => 200, :body => checkin.to_json, :headers => {})
+      subject.add_checkin({:venueId => "408c5100f964a520c6f21ee3"})[:checkin].should be_a(Foursquared::Response::Checkin)
+    end
+  end
+
+  describe "#recent_checkins" do
+    it "should return the recent checkins for the acting user" do
+       stub_request(:get, "https://api.foursquare.com/v2/checkins/recent?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").to_return(:status => 200, :body => recent_checkins.to_json, :headers => {})
+      subject.recent_checkins.should each {|checkin|
+        checkin.should be_a Foursquared::Response::Checkin
+      }
+    end
+  end
+
+  describe "#checkin_likes" do
+    before :each do
+      stub_request(:get, "https://api.foursquare.com/v2/checkins/502bcde16de4146b7f104ac6/likes?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").to_return(:status => 200, :body => checkin_likes.to_json, :headers => {})
+    end
+
+    it "should have count, groups and a summary" do
+      subject.checkin_likes("502bcde16de4146b7f104ac6").keys.should ~ ["summary", "count", "groups"]
+    end
+
+    it "should have give groups of users" do
+      subject.checkin_likes("502bcde16de4146b7f104ac6")["groups"].should each { |group|
+          group["items"].should each {|item|
+            item.should be_a Foursquared::Response::User
+          }
+      }
+    end
+  end
+
+end

data/spec/foursquared/response/checkin_spec.rb

@@ -31,8 +31,14 @@ describe Foursquared::Response::Checkin do
                 prefix: "https://irs3.4sqi.net/img/general/"
                 suffix: "/UBTEFRRMLYOHHX4RWHFTGQKSDMY14A1JLHURUTG5VUJ02KQ0.jpg"
             likes:
-              count: 0
-              groups: []
+              count: 1
+              groups: 
+              - type: "others"
+                count: 1
+                items:
+                - id: "141623"
+                  firstName: "chad"
+                  lastName: "g."
             like: false
             score:
             - total: 1
@@ -74,8 +80,6 @@ describe Foursquared::Response::Checkin do
 
     stub_request(:get, "https://api.foursquare.com/v2/checkins/4d627f6814963704dc28ff94?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").
          to_return(:status => 200, :body => checkin.to_json, :headers => {})
-     stub_request(:get, "https://api.foursquare.com/v2/checkins/4d627f6814963704dc28ff94/likes?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").
-     to_return(:status => 200, :body => likes.to_json, :headers => {})
   end
 
   it "should get checkin id" do
@@ -86,14 +90,31 @@ describe Foursquared::Response::Checkin do
     subject.venue.should be_a(Foursquared::Response::Venue)
   end
 
-  it "should return the likes for the checkin" do
-    subject.likes["groups"].should each { |group|
-        group["items"].should be_empty_or_array_of_users
-    }
+  describe "likes for the checkin" do
+    describe "#full_likes" do
+      it "should get the full likes for the checkin" do
+        stub_request(:get, "https://api.foursquare.com/v2/checkins/4d627f6814963704dc28ff94/likes?oauth_token=TestToken&v=#{Time.now.strftime("%Y%m%d")}").to_return(:status => 200, :body => likes.to_json, :headers => {})
+        subject.full_likes["groups"].should each { |group|
+          group["items"].should each { |item|
+            item.should be_a(Foursquared::Response::User)
+          }
+        }
+      end
+    end
+
+    describe "#likes" do
+      it "should return the likes as specified in the checkin response" do
+        subject.likes["groups"].should each { |group|
+          group["items"].should each { |item|
+            item.should be_a(Foursquared::Response::User)
+          }
+        }
+      end
+    end
   end
 
   it "should return the photos for the checkin" do
-    subject.photos.should each { |item|
+    subject.photos["items"].should each { |item|
       item.should be_a Foursquared::Response::Photo
     }
   end

data/spec/foursquared/response/user_spec.rb

@@ -3,7 +3,6 @@ require 'foursquared/response/user'
 require 'foursquared/response/list'
 
 require 'foursquared/client'
-require 'core_ext/symbol'
 describe Foursquared::Response::User do
   let(:me) do
     YAML.load(%{

data/spec/foursquared/response/venue_spec.rb

@@ -3,7 +3,6 @@ require 'foursquared/response/user'
 require 'foursquared/response/list'
 
 require 'foursquared/client'
-require 'core_ext/symbol'
 
 describe Foursquared::Response::Venue do
   let(:venue) do

data/spec/foursquared/users_spec.rb

@@ -1,8 +1,4 @@
-# require 'foursquared/users'
-# require 'foursquared/lists'
-# require 'foursquared/venues'
-# require 'foursquared/photos'
-# require 'foursquared/client'
+
 require 'spec_helper'
 require 'pp'
 describe Foursquared::Users do

data/spec/spec_helper.rb

@@ -1,6 +1,6 @@
 require "simplecov"
 require "simplecov-rcov"
-require 'foursquared'
+
 require 'webmock/rspec'
 require 'rspec_multi_matchers'
 
@@ -10,8 +10,9 @@ SimpleCov.start do
   add_filter "spec"
 end if ENV["COVERAGE"]
 
+require 'foursquared'
 def foursquared_test_client
-  Foursquared::Client.new("TestToken")
+  Foursquared::Client.new({:access_token => "TestToken"})
 end
 
 class Array

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foursquared
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-07 00:00:00.000000000 Z
+date: 2013-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httmultiparty
@@ -250,7 +250,6 @@ files:
 - README.md
 - Rakefile
 - foursquared.gemspec
-- lib/core_ext/symbol.rb
 - lib/foursquared.rb
 - lib/foursquared/badges.rb
 - lib/foursquared/checkins.rb
@@ -288,7 +287,6 @@ files:
 - spec/foursquared/response/badge_spec.rb
 - spec/foursquared/response/category_spec.rb
 - spec/foursquared/response/checkin_spec.rb
-- spec/foursquared/response/event_category_spec.rb
 - spec/foursquared/response/event_spec.rb
 - spec/foursquared/response/list_spec.rb
 - spec/foursquared/response/photo_spec.rb
@@ -332,7 +330,6 @@ test_files:
 - spec/foursquared/response/badge_spec.rb
 - spec/foursquared/response/category_spec.rb
 - spec/foursquared/response/checkin_spec.rb
-- spec/foursquared/response/event_category_spec.rb
 - spec/foursquared/response/event_spec.rb
 - spec/foursquared/response/list_spec.rb
 - spec/foursquared/response/photo_spec.rb

data/lib/core_ext/symbol.rb

@@ -1,7 +0,0 @@
-# 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/spec/foursquared/response/event_category_spec.rb

@@ -1,48 +0,0 @@
-require 'spec_helper'
-require 'foursquared/response/event_category'
-
-describe Foursquared::Response::EventCategory do
-
-  let(:event_category) do
-    YAML.load(%{
-          id: "4dfb90c6bd413dd705e8f897"
-          name: "Movies"
-          pluralName: "Movies"
-          shortName: "Movie"
-          icon:
-            prefix: "https://foursquare.com/img/categories_v2/arts_entertainment/movietheater_"
-            suffix: ".png"
-          categories:
-          - id: "4e132f48bd41026cd50e8f8e"
-            name: "Baseball Games"
-            pluralName: "Baseball Games"
-            shortName: "Baseball"
-            icon:
-              prefix: "https://foursquare.com/img/categories_v2/arts_entertainment/stadium_baseball_"
-              suffix: ".png"
-            categories: []
-      }
-    )
-  end
-
-  subject {Foursquared::Response::EventCategory.new(event_category)}
-
-  describe "#icon" do
-    it "should have prefix, suffix and urls" do
-      subject.icon.keys.should ~ ["urls", "prefix", "suffix", ]
-    end
-
-    describe "urls" do
-      it "should have urls for 32x32, 64x64 and 256x256 icons" do
-        subject.icon["urls"].keys.should ~ ["32x32", "64x64", "256x256"]
-      end
-    end
-
-  end
-
-  it "should give the sub categories of the category" do
-    subject.categories.should each { |category|
-      category.should be_a(Foursquared::Response::EventCategory)
-    }
-  end
-end