foursquared 0.0.4

data/lib/foursquared/response/venue.rb

@@ -0,0 +1,252 @@
+module Foursquared
+  module Response
+    # Venue response
+    class Venue
+      attr_reader :client, :response
+
+      def initialize client, response
+        @client = client
+        @response = response
+      end
+
+      # The venue ID
+      # @return [String]
+      def id
+        response["id"]
+      end
+
+      # The venue name
+      # @return [String]
+      def name
+        response["name"]
+      end
+
+      # The contact details for the venue
+      # @return [Hash]
+      def contact
+        response["contact"]
+      end
+
+      # The location details for the venue
+      # @return [Hash]
+      def location
+        response["location"]
+      end
+
+      # Whether this is a verified venue
+      # @return [Boolean]
+      def verified?
+        response["verified"]
+      end
+
+      # The canonical url for this venue
+      # @return [String]
+      def canonical_url
+        response["canonicalUrl"]
+      end
+
+      # An array of categories that have been applied to this venue
+      # @return [Array<Foursquared::Response::Category>]
+      def categories
+        response["categories"].map!{|category| Foursquared::Response::Category.new(client, category)} if response["categories"]
+      end
+
+      # Contains checkinsCount , usersCount , and tipCount.
+      # @return [Hash]
+      def stats
+        response["stats"]
+      end
+
+      # URL of the venue's website, typically provided by the venue manager.
+      def url
+        response["url"]
+      end
+
+      # An object containing the price tier from 1 (least pricey) - 4 (most pricey) and a message describing the price tier.
+      # @return [Hash]
+      def price
+        response["price"]
+      end
+
+      # Whether the current user has liked this venue.
+      # @return [Boolean]
+      def like?
+        response["like"]
+      end
+
+      # Whether the current user has disliked this venue.
+      # @return [Boolean]
+      def dislike?
+        response["dislike"]
+      end
+
+      # The rating for this venue
+      # @return [Float]
+      def rating
+        response["rating"]
+      end
+
+      # Array of categories that have been applied to this venue
+      # @return [Array<Foursquared::Response::Category>]
+      def categories
+        @categories = response["categories"] || []
+        @categories.map!{|category| Foursquared::Response::Category.new(client, category)}
+      end
+
+      # Menu information for the venue.
+      # @return [Hash]
+      def menu
+        response["menu"]
+      end
+
+      # Contains the hours during the week that the venue is open along with any named hours segments in a human-readable format.
+      # @return [Hash]
+      def hours
+        response["hours"]
+      end
+
+      # An array of phrases applied to this menu
+      # @return [Array<Hash>]
+      def phrases
+        response["phrases"]
+      end
+
+      # Count and items of reasons that have been applied at this venue
+      # @return [Hash]
+      def reasons
+        response["reasons"]
+      end
+
+      # Venue description
+      # @return [String]
+      def description
+        response["description"]
+      end
+
+      # The mayor of the venue
+      # @return [Foursquared::Response::User]
+      def mayor
+        Foursquared::Response::User.new(response["mayor"]["user"]) if response["mayor"] and response["mayor"]["user"]
+      end
+
+      # Users who like the venue
+      # @return [Hash]
+      def likes
+        likes_response = client.get("/venues/#{id}/likes")["response"]
+        @likes = {}
+        if likes_response["likes"]
+          @likes.merge!(likes_response["likes"])
+          if @likes["groups"]
+            @likes["groups"].each do |group|
+              group["items"].map!{|item| Foursquared::Response::User.new(client, item)}
+            end
+          end
+        end
+        @likes
+      end
+
+      # Count and items of specials at the venue
+      # @return [Hash]
+      def specials
+        @specials = response["specials"]
+        @specials["items"].map!{|item| Foursquared::Response::Special.new(client, item)} if @specials
+        @specials
+      end
+
+      # The time at which the venue was added
+      # @return [Time]
+      def created_at
+        Time.at(response["createdAt"]) if response["createdAt"]
+      end
+
+      # The tips for this venue
+      # @return [Hash]
+      def tips
+        @tips = response["tips"]
+        if @tips["groups"]
+          @tips["groups"].each do |group|
+            group["items"].map!{|item| Foursquared::Response::Tip.new(client, item)}
+          end
+        end
+        @tips
+      end
+
+      # Array of string tags for this venue
+      # @return [Array<String>]
+      def tags
+        response["tags"]
+      end
+
+      # The shortened url for the venue
+      # @return [String]
+      def short_url
+        response["shortUrl"]
+      end
+
+      # The time zone
+      # @return [String]
+      def time_zone
+        response["timeZone"]
+      end
+
+      # A grouped response of lists that contain this venue
+      # @return [Hash]
+      def listed
+        @listed = response["listed"]
+        @listed["groups"].each do |group|
+          @listed["items"].map!{|item| Foursquared::Response::List.new(client, item)}
+        end
+        @listed
+      end
+
+      # The number of times the acting user has been to this venue
+      # @return [Integer]
+      def been_here
+        response["beenHere"]["count"] if response["beenHere"]
+      end
+
+      # Present only for venues returned in Explore search results.
+      # @return [Hash]
+      def flags
+        response["flags"]
+      end
+
+      # Present if and only if the current user has at least one assigned role for this venue.
+      # @return [Array]
+      def roles
+        response["roles"]
+      end
+
+      # The venue photos
+      # @return [Hash] count and groups of photos
+      def photos
+        @photos = response["photos"]
+        if @photos
+          @photos["groups"].each do |group|
+            group["items"].map!{|item| Foursquared::Response::Photo.new(client, item)}
+          end
+        end
+        @photos
+      end
+
+      # The users who have checked in here now
+      # @return [Hash] count and groups of users
+      def here_now
+        @here_now = response["hereNow"]
+        if @here_now
+          @here_now["groups"].each do |group|
+            group["items"].map!{|item| Foursquared::Response::User.new(client, item)}
+          end
+        end
+        @here_now
+      end
+
+      # Specials available at nearby venues
+      # @return [Array<Foursquared::Response::Special>]
+      def specials_nearby
+        response["specialsNearby"].map{|special| Foursquared::Response::Special.new(client, special)} if response["specialsNearby"]
+      end
+
+    end
+  end
+end

data/lib/foursquared/settings.rb

@@ -0,0 +1,28 @@
+module Foursquared
+  # Settings module
+  module Settings
+
+    # Return the value for the setting with given ID
+    # @param [String] setting_id ID of the setting
+    # @return [Hash] ex: {"value" => "true"}
+    def setting setting_id
+      response = get("/settings/#{setting_id}")["response"]
+      response
+    end
+
+    # Returns all settings for the user
+    # @return [Hash]
+    def all_settings
+      response = get("/settings/all")["response"]["settings"]
+    end
+
+    # Set the value for a setting
+    # @param [String] setting_id ID of the setting
+    # @param [Hash] options
+    # @option options [Integer] :value 1 for true or 0 for false
+    # @return [Hash] With a confirmation message
+    def set_setting setting_id, options={}
+      response = post("/settings/#{setting_id}/set",options)["response"]
+    end
+  end
+end

data/lib/foursquared/specials.rb

@@ -0,0 +1,25 @@
+module Foursquared
+  # Specials module
+  module Specials
+    # Gives details about a special
+    # @param [String] special_id required ID of special to retrieve
+    # @param [Hash] options
+    # @option options [String] :venueId required ID of a venue the special is running at
+    # @option options [String] :userId ID of the user to check whether the special is unlocked for. Only available if the current user is the manager of the venue. If not provided, checks wher the special is unlocked for the current user.
+    # @return [Foursquared::Response::Special]
+    def special special_id, options={}
+      response = get("/specials/#{special_id}")["response"]
+      @special = Foursquared::Response::Special.new(self, response["special"])
+    end
+
+    # Flag a Special
+    # @param [String] special_id required ID of special to flag
+    # @param [Hash] options
+    # @option option [String] :venueId required The id of the venue running the special.
+    # @option option [String] :problem required One of not_redeemable, not_valuable, other.
+    # @option option [String] :text Additional text about why the user has flagged this special
+    def flag_special special_id, options={}
+      response = post("/specials/#{special_id}/flag", options)["response"]
+    end
+  end
+end

data/lib/foursquared/tips.rb

@@ -0,0 +1,113 @@
+module Foursquared
+  # Tips module
+  module Tips
+    # Tip detail 
+    # @param [String] tip_id required, ID of tip to retrieve.
+    # @return [Foursquared::Response::Tip] A complete tip.
+    def tip tip_id
+      response = get("/tips/#{tip_id}")["response"]
+      Foursquared::Response::Tip.new(self, response["tip"])
+    end
+
+    # Add a tip 
+    # @param [Hash] options
+    # @option options [String] :venueId required, the venue where you want to add this tip.
+    # @option options [String] :text required, the text of the tip, up to 200 characters.
+    # @option options [String] :url A URL related to this tip.
+    # @option options [String] :broadcast eg: twitter,facebook
+    # @return [Foursquared::Response::Tip] The newly added tip
+    def add_tip options={}
+      response = post("/tips/add", options)["response"]
+      Foursquared::Response::Tip.new(self, response["tip"])
+    end
+
+    # Search Nearby Tips 
+    # @param [Hash] options
+    # @option options [String] :ll required, unless near is provided. Latitude and longitude of the user's location.
+    # @option options [String] :near required, unless ll is provided. A string naming a place in the world
+    # @option options [Integer] :limit optional, number of results to return, up to 500.
+    # @option options [Integer] :offset optional, used to page through results.
+    # @option options [String] :filter if set to friends, only show nearby tips from friends.
+    # @option options [String] :query only find tips matching the given term, cannot be used in conjunction with friends filter.
+    # @return [Array] tips matching the criteria
+    def search_tips options={}
+      response = get("/tips/search", options)["response"]
+      @tips = response["tips"]
+      @tips.collect{|tip| Foursquared::Response::Tip.new(self, tip)}
+    end
+
+    # Users who have done a tip
+    # @param [String] tip_id required, ID of tip.
+    # @param [Hash] options
+    # @option options [Integer] :limit optional, number of results to return, up to 200.
+    # @option options [Integer] :offset optional, used to page through results.
+    # @return A count and items of compact user objects
+    def tip_dones tip_id, options={}
+      response = get("/tips/#{tip_id}/done", options)["response"]
+      @users = response["users"]
+      @users["items"].map!{|item| Foursquared::Response::User.new(self, item)} if @users["items"]
+      @users
+    end
+
+    # Users who have liked a tip
+    # @param [String] tip_id required, ID of tip.
+    # @return [Hash] A count and groups of users who like this tip
+    def tip_likes tip_id
+      response = get("/tips/#{tip_id}/likes")["response"]
+      @likes = response["likes"]
+      @likes["groups"].each{ |group| group["items"].map!{|item| Foursquared::Response::User.new(client, item)}} if @likes and @likes["groups"]
+    end
+
+    # The lists that this tip appears on 
+    # @param [String] tip_id required, ID of tip.
+    # @return [Hash]
+    def tip_listed tip_id, options={}
+      response = get("/tips/#{tip_id}/listed")["response"]
+      @lists = response["lists"]
+      if @lists["groups"]
+        @lists["groups"].each do |group|
+          group["items"].map!{|item| Foursquared::Response::List.new(client, item) } if group["items"]
+        end
+      elsif @lists["items"]
+        @lists["items"].map!{|item| Foursquared::Response::List.new(client, item) }
+      end
+    end
+
+    # Like or unlike a tip 
+    # @param [String] tip_id required, ID of tip.
+    # @param [Hash] options
+    # @option options [Integer] :set If 1, like this tip. If 0 unlike (un-do a previous like) it. Default value is 1
+    # @return [Hash] Updated count and groups of users who like this tip.
+    def like_tip tip_id, options={}
+      response = post("/tips/#{tip_id}/like", options)["response"]
+      @likes = response["likes"]
+      @likes["groups"].each{ |group| group["items"].map!{|item| Foursquared::Response::User.new(client, item)}} if @likes and @likes["groups"]
+      @likes
+    end
+
+    # Mark a tip done 
+    # @param [String] tip_id required, ID of tip.
+    # @return [Foursquared::Response::Tip] The marked to-do.
+    def mark_tip_done tip_id
+      response = post("/tips/#{tip_id}/markdone")["response"]
+      Foursquared::Response::Tip.new(self, response["tip"])
+    end
+
+    # Mark a tip to-do
+    # @param [String] tip_id required, ID of tip.
+    # @return [Foursquared::Response::Todo] The marked to-do.
+    def mark_tip_todo tip_id
+      response = post("/tips/#{tip_id}/marktodo")["response"]
+      Foursquared::Response::Todo.new(self, response["todo"])
+    end
+
+    # Unmark a tip as to-do 
+    # @param [String] tip_id required, ID of tip.
+    # @return [Foursquared::Response::Tip] The current tip
+    def unmark_tip_todo tip_id
+      response = post("/tips/#{tip_id}/unmark")["response"]
+      Foursquared::Response::Tip.new(self, response["tip"])
+    end
+
+  end
+end

data/lib/foursquared/users.rb

@@ -0,0 +1,206 @@
+# Foursquared Module
+module Foursquared
+  # Users module
+  module Users
+
+    # Return profile information for a given user
+    # @param [String, Integer] user_id user's id
+    # @return [Foursquared::Response::User] A user.
+    def user user_id="self"
+      @user = get("/users/#{user_id}")["response"]["user"]
+      Foursquared::Response::User.new(self,@user)
+    end
+
+    # Returns the user's leaderboard.
+    # @param [Hash] options the optional options to be passed with the request
+    # @option options [Integer] :neighbors Number of friends' scores to return that are adjacent to your score, in ranked order.
+    # @return [Hash] the user's leaderboard.
+    def leaderboard options={}
+      @leaderboard = get("/users/leaderboard", options)["response"]["leaderboard"]
+      @leaderboard["items"].each do |item|
+        item["user"] = Foursquared::Response::User.new(self,item["user"])
+      end
+      @leaderboard
+    end
+
+    # Approves a pending friend request from another user.
+    # @param [String, Integer] user_id The request user's id
+    # @return [Foursquared::Response::User] the approved user
+    def approve_friend_request user_id
+      response = post("/users/#{user_id}/approve")["response"]
+      @user = Foursquared::Response::User.new(self,response["user"])
+    end
+
+    # Denies a pending friend request from another user.
+    # @param [String, Integer] user_id The request user's id
+    # @return [Foursquared::Response::User] the denied user
+    def deny_friend_request user_id
+      response = post("/users/#{user_id}/deny")["response"]
+      @user = Foursquared::Response::User.new(self,response["user"])
+    end
+
+    # Send a Friend/Follow Request
+    # @param [String, Integer] user_id The request user's/page's id
+    # @return [Foursquared::Response::User] the pending user
+    def send_friend_request user_id
+      response = post("/users/#{user_id}/request")["response"]
+      @user = Foursquared::Response::User.new(self,response["user"])
+    end
+
+    # Removes a friend, unfollows a celebrity, or cancels a pending friend request.
+    # @param [String, Integer] user_id The request user's id
+    # @return [Foursquared::Response::User] the removed user
+    def unfriend user_id
+      response = post("/users/#{user_id}/unfriend")["response"]
+      @user = Foursquared::Response::User.new(self,response["user"])
+    end
+
+    # Pending friend requests
+    # @return [Array] User objects
+    def requests
+      response = get("/users/requests")["response"]
+      @requests = response["requests"].collect{|request| Foursquared::Response::User.new(self,request)}
+    end
+
+    # Find users
+    # @param [Hash] options
+    # @option options [String] :phone A comma-delimited list of phone numbers to look for.
+    # @option options [String] :email A comma-delimited list of email addresses to look for.
+    # @option options [String] :twitter A comma-delimited list of Twitter handles to look for.
+    # @option options [String] :twitterSource A single Twitter handle. Results will be users that this handle follows on Twitter who use Foursquare.
+    # @option options [String] :fbid A comma-delimited list of Facebook ID's to look for.
+    # @option options [String] :name A single string to search for in users' names.
+    # @return [Hash]
+    def search options={}
+      response = get("/users/search", options)["response"]
+      response["results"].map!{|result| Foursquared::Response::User.new(self,result)}
+      response
+    end
+
+    # Set whether to receive pings about a user
+    # @param [String, Integer] user_id User ID of a friend
+    # @param [Hash] options
+    # @option options [Boolean] :value True or false.
+    # @return [Foursquared::Response::User] User object for the user
+    def set_pings user_id, options={}
+      response = post("/users/#{user_id}/setpings", options)["response"]
+      @user = Foursquared::Response::User.new(self,response["user"])
+    end
+
+    # Update user's photo
+    # @param [String] image_filename The location of the photo to be uploaded
+    # @return [Foursquared::Response::User] User object for the user
+    def update_photo image_filename
+      response = post("/users/self/update", options={:photo => File.read(image_filename)})["response"]
+      @user = Foursquared::Response::User.new(self, response["user"])
+    end
+
+    # Checkins by a user
+    # @param [String, Integer] user_id
+    # @param [Hash] options
+    # @option options [Integer] :limit Number of results to return, up to 250.
+    # @option options [Integer] :offset The number of results to skip. Used to page through results.
+    # @option options [String] :sort How to sort the returned checkins. Can be "newestfirst" or "oldestfirst".
+    # @option options [Integer] :afterTimestamp Retrieve the first results to follow these seconds since epoch
+    # @option options [Integer] :beforeTimestamp Retrieve the first results prior to these seconds since epoch
+    # @return [Hash] A count and items of check-ins.
+    def user_checkins user_id="self", options={}
+      response = get("/users/#{user_id}/checkins",options)["response"]["checkins"]
+      response["items"].map!{|checkin| Foursquared::Response::Checkin.new(self, checkin)} if response["items"]
+      response
+    end
+
+    # List friends
+    # @param [String, Integer] user_id
+    # @param [Hash] options
+    # @option options [Integer] :limit Number of results to return, up to 500.
+    # @option options [Integer] :offset Used to page through results.
+    # @return [Hash]  A count and items of friends.
+    def user_friends user_id="self", options={}
+      response = get("/users/#{user_id}/friends"), options["response"]["friends"]
+      response["items"].map!{|friend| Foursquared::Response::User.new(self, friend)} if response["items"]
+      response
+    end
+
+    # Return the user's lists
+    # @param [String, Integer] user_id
+    # @param [Hash] options
+    # @option options [String] :group "edited", "created", "followed", "friends" or "suggested"
+    # @option options [String] :ll Location of the user eg: 40.7,-74
+    # @return [Hash]
+    def user_lists user_id="self", options={}
+      response = get("/users/#{user_id}/lists", options)["response"]
+      @lists = response["lists"]
+      @lists["groups"].each do |group|
+        group["items"].map!{|item| Foursquared::Response::List.new(self, item)}
+      end
+      @lists
+    end
+
+    # List user's mayorships
+    # @param [String, Integer] user_id
+    # @return [Hash]
+    def user_mayorships user_id="self"
+      response = get("/users/#{user_id}/mayorships")["response"]
+      @mayorships = response["mayorships"]
+      @mayorships["items"].each{|item| item["venue"] = Foursquared::Response::Venue.new(self, item["venue"])}
+      @mayorships
+    end
+
+    # Photos from a User
+    # @param [String, Integer] user_id
+    # @param [Hash] options
+    # @option options [Integer] :limit Number of results to return, up to 500.
+    # @option options [Integer] :offset The number of results to skip. Used to page through results.
+    # @return [Hash] A count and items of photos.
+    def user_photos user_id="self", options={}
+      response = get("/users/#{user_id}/photos",options)["response"]
+      @photos = response["photos"]
+      @photos["items"].map!{|item| Foursquared::Response::Photo.new(self, item)}
+    end
+
+    # Tips from a User
+    # @param [String, Integer] user_id
+    # @param [Hash] options
+    # @option options :limit Number of results to return, up to 200.
+    # @option options :offset The number of results to skip. Used to page through results.
+    # @option options :llBounds Restricts the returned results to the input bounding box.
+    # @option options :categoryId Restricts the returned results to venues matching the input category id.
+    # @return [Foursquared::Response::List]
+    def user_tips user_id="self", options={}
+      response = get("/lists/#{user_id}/tips", options)["response"]
+      Foursquared::Response::List.new(self, response["list"])
+    end
+
+    # Todos from a User
+    # @param [String, Integer] user_id
+    # @param [Hash] options
+    # @option options :limit Number of results to return, up to 200.
+    # @option options :offset The number of results to skip. Used to page through results.
+    # @option options :llBounds Restricts the returned results to the input bounding box.
+    # @option options :categoryId Restricts the returned results to venues matching the input category id.
+    # @return [Foursquared::Response::List]
+    def user_todos user_id="self", options={}
+      response = get("/lists/#{user_id}/todos", options)["response"]
+      Foursquared::Response::List.new(self, response["list"])
+    end
+
+    # Badges for a user
+    # @param [String, Integer] user_id
+    # @return [Hash]
+    def user_badges user_id="self"
+      response = get("/users/#{user_id}/badges")["response"]
+      if response["sets"] and response["sets"]["groups"]
+        response["sets"]["groups"].map!{|group| Foursquared::Response::BadgeGroup.new(self, group)}
+      end
+
+      if response["badges"]
+        response["badges"].each_key do |badge_id|
+          response["badges"][badge_id] = badge(badge_id)
+        end
+      end
+      response
+    end
+
+  end
+end