instagram 0.11.0 → 1.0.0

data/lib/instagram/client/embedding.rb

@@ -1,6 +1,23 @@
 module Instagram
   class Client
+  	# Defines methods related to embedding
     module Embedding
+    	# Returns information about the media associated with the given short link
+      #
+	    # @overload oembed(url=nil, options={})
+	    # 	@param url [String] An instagram short link
+	    #   @param options [Hash] A customizable set of options
+	    #   @option options [Integer] :maxheight Maximum height of returned media
+	    #   @option options [Integer] :maxwidth Maximum width of returned media
+	    #   @option options [Integer] :callback A JSON callback to be invoked
+	    #   @return [Hashie::Mash] Information about the media associated with given short link
+      # 	@example Return information about the media associated with http://instagr.am/p/BUG/
+      #   	Instagram.oembed(http://instagr.am/p/BUG/)
+      #
+      # @see http://instagram.com/developer/embedding/#oembed
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
       def oembed(*args)
         url = args.first
         return nil unless url

data/lib/instagram/client/likes.rb

@@ -14,7 +14,7 @@ module Instagram
       #
       #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/likes/#get_media_likes
       def media_likes(id, *args)
         response = get("media/#{id}/likes")
         response
@@ -32,7 +32,7 @@ module Instagram
       #
       #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/likes/#post_likes
       def like_media(id, options={})
         response = post("media/#{id}/likes", options)
         response
@@ -48,7 +48,7 @@ module Instagram
       # @format :json
       # @authenticated true
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/likes/#delete_likes
       def unlike_media(id, options={})
         response = delete("media/#{id}/likes", options)
         response

data/lib/instagram/client/locations.rb

@@ -12,7 +12,7 @@ module Instagram
       # @format :json
       # @authenticated false
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/locations/#get_locations
       def location(id, *args)
         response = get("locations/#{id}")
         response
@@ -28,7 +28,7 @@ module Instagram
       #   @return [Hashie::Mash]
       #   @example Return a list of the most recent media items taken at the Instagram office
       #     Instagram.location_recent_media(514276)
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/locations/#get_locations_media_recent
       # @format :json
       # @authenticated false
       # @rate_limited true
@@ -50,7 +50,7 @@ module Instagram
       #     Instagram.location_search("3fd66200f964a520c5f11ee3") (Schiller's Liquor Bar, 131 Rivington St., NY, NY 10002)
       #   @example 2: Return locations around 37.7808851, -122.3948632 (164 S Park, SF, CA USA)
       #     Instagram.location_search("37.7808851", "-122.3948632")
-      # @see TODO:doc url
+      # @see http://instagram.com/developer/endpoints/locations/#get_locations_search
       # @format :json
       # @authenticated false
       # @rate_limited true
@@ -63,6 +63,9 @@ module Instagram
         when 2
           lat, lng = args
           response = get('locations/search', options.merge(:lat => lat, :lng => lng))
+        when 3
+          lat, lng, distance = args
+          response = get('locations/search', options.merge(:lat => lat, :lng => lng, :distance => distance))
         end
         response
       end

data/lib/instagram/client/media.rb

@@ -14,7 +14,7 @@ module Instagram
       #
       #   If getting this data of a protected user, you must authenticate (and be allowed to see that user).
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/media/#get_media
       def media_item(*args)
         id = args.first || 'self'
         response = get("media/#{id}")
@@ -28,7 +28,7 @@ module Instagram
       #   @return [Hashie::Mash]
       #   @example Returns a list of the overall most popular media
       #     Instagram.media_popular
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/media/#get_media_popular
       # @format :json
       # @authenticated false unless requesting it from a protected user
       #
@@ -50,7 +50,7 @@ module Instagram
       # @return [Hashie::Mash] A list of matching media
       # @example Return media around 37.7808851, -122.3948632 (164 S Park, SF, CA USA)
       #   Instagram.media_search("37.7808851", "-122.3948632")
-      # @see TODO:doc url
+      # @see http://instagram.com/developer/endpoints/media/#get_media_search
       # @format :json
       # @authenticated false
       # @rate_limited true

data/lib/instagram/client/subscriptions.rb

@@ -41,7 +41,7 @@ module Instagram
       #   @option options [String, Integer] :object_id When specifying a location or tag use the location's ID or tag name respectively
       #   @option options [String, Float] :lat The center latitude of an area, used when subscribing to a geography object
       #   @option options [String, Float] :lng The center longitude of an area, used when subscribing to a geography object
-      #   @option options [String, Integer] :radius The distance in meters you'd like to capture around a given point 
+      #   @option options [String, Integer] :radius The distance in meters you'd like to capture around a given point
       #
       #     Note that we only support "media" at this time, but we might support other types of subscriptions in the future.
       #   @return [Hashie::Mash] The subscription created.
@@ -96,6 +96,61 @@ module Instagram
         response
       end
 
+      # As a security measure (to prevent DDoS attacks), Instagram sends a verification request to your server
+      # after you request a subscription.
+      # This method parses the challenge params and makes sure the call is legitimate.
+      #
+      # @param params the request parameters sent by Instagram.  (You can pass in a Rails params hash.)
+      # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
+      #
+      # @yield verify_token if you need to compute the verification token
+      #                     (for instance, if your callback URL includes a record ID, which you look up
+      #                     and use to calculate a hash), you can pass meet_challenge a block, which
+      #                     will receive the verify_token received back from Instagram.
+      #
+      # @return the challenge string to be sent back to Instagram, or false if the request is invalid.
+      def meet_challenge(params, verify_token = nil, &verification_block)
+        if params["hub.mode"] == "subscribe" &&
+            # you can make sure this is legitimate through two ways
+            # if your store the token across the calls, you can pass in the token value
+            # and we'll make sure it matches
+            ((verify_token && params["hub.verify_token"] == verify_token) ||
+            # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
+            # you can pass in a block, which we'll call with the verify_token sent by Instagram
+            # if it's legit, return anything that evaluates to true; otherwise, return nil or false
+            (verification_block && yield(params["hub.verify_token"])))
+          params["hub.challenge"]
+        else
+          false
+        end
+      end
+
+      # Public: As a security measure, all updates from Instagram are signed using
+      # X-Hub-Signature: sha1=XXXX where XXX is the sha1 of the json payload
+      # using your application secret as the key.
+      #
+      # Example:
+      #   # in Rails controller
+      #   def receive_update
+      #     if Instagram.validate_update(request.body, headers)
+      #       ...
+      #     else
+      #       render text: "not authorized", status: 401
+      #     end
+      #   end
+      def validate_update(body, headers)
+        unless client_secret
+          raise ArgumentError, "client_secret must be set during configure"
+        end
+
+        if request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE'] and
+           signature_parts = request_signature.split('sha1=')
+          request_signature = signature_parts[1]
+          calculated_signature = OpenSSL::HMAC.hexdigest('sha1', client_secret, body)
+          calculated_signature == request_signature
+        end
+      end
+
       # Process a subscription notification JSON payload
       #
       # @overload process_subscription(json, &block)
@@ -124,7 +179,7 @@ module Instagram
       def process_subscription(json, options={}, &block)
         raise ArgumentError, "callbacks block expected" unless block_given?
 
-        if options[:signature]
+        if options.has_key?(:signature)
           if !client_secret
             raise ArgumentError, "client_secret must be set during configure"
           end

data/lib/instagram/client/tags.rb

@@ -12,7 +12,7 @@ module Instagram
       # @format :json
       # @authenticated false
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/tags/#get_tags
       def tag(tag, *args)
         response = get("tags/#{tag}")
         response
@@ -21,20 +21,20 @@ module Instagram
       # Returns a list of recent media items for a given Instagram tag
       #
       # @overload tag_recent_media(tag, options={})
-      #   @param id [String] An Instagram tag name.
+      #   @param tag-name [String] An Instagram tag name.
       #   @param options [Hash] A customizable set of options.
       #   @option options [Integer] :max_id (nil) Returns results with an ID less than (that is, older than) or equal to the specified ID.
-      #   @option options [Integer] :count (nil) Limits the number of results returned per page.
+      #   @option options [Integer] :min_id (nil) Returns results with an ID greater than (that is, newer than) or equal to the specified ID.
       #   @return [Hashie::Mash]
       #   @example Return a list of the most recent media items tagged "cat"
       #     Instagram.tag_recent_media('cat')
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/tags/#get_tags_media_recent
       # @format :json
       # @authenticated false
       # @rate_limited true
       def tag_recent_media(id, *args)
         options = args.last.is_a?(Hash) ? args.pop : {}
-        response = get("tags/#{id}/media/recent", options)
+        response = get("tags/#{id}/media/recent", options, false, false)
         response
       end
 
@@ -47,7 +47,7 @@ module Instagram
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :count The number of media items to retrieve.
       # @return [Hashie::Mash]
-      # @see TODO:doc url
+      # @see http://instagram.com/developer/endpoints/tags/#get_tags_search
       # @example Return tags that start with "cat"
       #   Instagram.tag_search("cat")
       def tag_search(query, options={})

data/lib/instagram/client/users.rb

@@ -14,7 +14,7 @@ module Instagram
       #
       #   If getting this data of a protected user, you must authenticate (and be allowed to see that user).
       # @rate_limited true
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/users/#get_users
       def user(*args)
         options = args.last.is_a?(Hash) ? args.pop : {}
         id = args.first || 'self'
@@ -31,7 +31,7 @@ module Instagram
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :count The number of users to retrieve.
       # @return [Hashie::Mash]
-      # @see TODO:doc url
+      # @see http://instagram.com/developer/endpoints/users/#get_users_search
       # @example Return users that match "Shayne Sweeney"
       #   Instagram.user_search("Shayne Sweeney")
       def user_search(query, options={})
@@ -54,7 +54,7 @@ module Instagram
       #   @return [Hashie::Mash]
       #   @example Return a list of users @mikeyk follows
       #     Instagram.user_follows(4) # @mikeyk user ID being 4
-      # @see TODO:docs url
+      # @see http://instagram.com/developer/endpoints/relationships/#get_users_follows
       # @format :json
       # @authenticated false unless requesting it from a protected user
       #
@@ -83,7 +83,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Return a list of users @mikeyk is followed by
     #     Instagram.user_followed_by(4) # @mikeyk user ID being 4
-    # @see TODO:docs url
+    # @see http://instagram.com/developer/endpoints/relationships/#get_users_followed_by
     # @format :json
     # @authenticated false unless requesting it from a protected user
     #
@@ -96,7 +96,7 @@ module Instagram
       response
     end
 
-    # Returns a list of users whom a given user is followed by
+    # Returns a list of users who have requested the currently authorized user's permission to follow
     #
     # @overload user_requested_by()
     #   @param options [Hash] A customizable set of options.
@@ -107,16 +107,16 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Return a list of users who have requested to follow the authenticated user
     #     Instagram.user_requested_by()
-    # @see TODO:docs url
+    # @see http://instagram.com/developer/endpoints/relationships/#get_incoming_requests
     # @format :json
-    # @authenticated truei
+    # @authenticated true
     # @rate_limited true
     def user_requested_by()
       response = get("users/self/requested-by")
       response
     end
 
-    # Returns most recent media items from the currently authorized user's feed.
+    # Returns most recent media items from the currently authorized user's feed
     #
     # @overload user_media_feed(options={})
     #   @param options [Hash] A customizable set of options.
@@ -190,7 +190,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Return the relationship status between the currently authenticated user and @mikeyk
     #     Instagram.user_relationship(4) # @mikeyk user ID being 4
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#get_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true
@@ -207,7 +207,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Request the current user to follow the target user
     #     Instagram.follow_user(4)
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true
@@ -225,7 +225,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Remove a follows relationship between the current user and the target user
     #     Instagram.unfollow_user(4)
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true
@@ -243,7 +243,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Block a relationship between the current user and the target user
     #     Instagram.block_user(4)
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true
@@ -261,7 +261,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Remove a relationship block between the current user and the target user
     #     Instagram.unblock_user(4)
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true
@@ -279,7 +279,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Approve a relationship request between the current user and the target user
     #     Instagram.approve_user(4)
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true
@@ -297,7 +297,7 @@ module Instagram
     #   @return [Hashie::Mash]
     #   @example Deny a relationship request between the current user and the target user
     #     Instagram.deny_user(4)
-    # @see http://instagram.com/developer/endpoints/relationships/
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
     # @format :json
     # @authenticated true
     # @rate_limited true

data/lib/instagram/client/utils.rb

@@ -2,6 +2,19 @@ module Instagram
   class Client
     # @private
     module Utils
+      # Returns the raw full response including all headers. Can be used to access the values for 'X-Ratelimit-Limit' and 'X-Ratelimit-Remaining' 
+      # ==== Examples
+      #   
+      #   client = Instagram.client(:access_token => session[:access_token])
+      #   response = client.utils_raw_response
+      #   remaining = response.headers[:x_ratelimit_remaining]
+      #   limit = response.headers[:x_ratelimit_limit]
+      #
+      def utils_raw_response
+        response = get('users/self/feed',nil,true)
+        response
+      end
+    
       private
 
       # Returns the configured user name or the user name of the authenticated user

data/lib/instagram/configuration.rb

@@ -6,22 +6,22 @@ module Instagram
   module Configuration
     # An array of valid keys in the options hash when configuring a {Instagram::API}
     VALID_OPTIONS_KEYS = [
+      :access_token,
       :adapter,
       :client_id,
       :client_secret,
+      :connection_options,
       :scope,
-      :access_token,
+      :redirect_uri,
       :endpoint,
       :format,
+      :proxy,
       :user_agent,
-      :proxy
+      :no_response_wrapper
     ].freeze
 
-    # An array of valid request/response formats
-    #
-    # @note Not all methods support the XML format.
-    VALID_FORMATS = [
-      :json].freeze
+    # By default, don't set a user access token
+    DEFAULT_ACCESS_TOKEN = nil
 
     # The adapter that will be used to connect if none is set
     #
@@ -34,14 +34,8 @@ module Instagram
     # By default, don't set an application secret
     DEFAULT_CLIENT_SECRET = nil
 
-    # By default, don't set an application redirect uri
-    DEFAULT_REDIRECT_URI = nil
-
-    # By default, don't set a user access token
-    DEFAULT_ACCESS_TOKEN = nil
-
-    # By default, don't set a user scope
-    DEFAULT_SCOPE = nil
+    # By default, don't set any connection options
+    DEFAULT_CONNECTION_OPTIONS = {}
 
     # The endpoint that will be used to connect if none is set
     #
@@ -56,9 +50,24 @@ module Instagram
     # By default, don't use a proxy server
     DEFAULT_PROXY = nil
 
+    # By default, don't set an application redirect uri
+    DEFAULT_REDIRECT_URI = nil
+
+    # By default, don't set a user scope
+    DEFAULT_SCOPE = nil
+
+    # By default, don't wrap responses with meta data (i.e. pagination)
+    DEFAULT_NO_RESPONSE_WRAPPER = false
+
     # The user agent that will be sent to the API endpoint if none is set
     DEFAULT_USER_AGENT = "Instagram Ruby Gem #{Instagram::VERSION}".freeze
 
+    # An array of valid request/response formats
+    #
+    # @note Not all methods support the XML format.
+    VALID_FORMATS = [
+      :json].freeze
+
     # @private
     attr_accessor *VALID_OPTIONS_KEYS
 
@@ -81,15 +90,18 @@ module Instagram
 
     # Reset all configuration options to defaults
     def reset
-      self.adapter        = DEFAULT_ADAPTER
-      self.client_id      = DEFAULT_CLIENT_ID
-      self.client_secret  = DEFAULT_CLIENT_SECRET
-      self.scope          = DEFAULT_SCOPE
-      self.access_token   = DEFAULT_ACCESS_TOKEN
-      self.endpoint       = DEFAULT_ENDPOINT
-      self.format         = DEFAULT_FORMAT
-      self.user_agent     = DEFAULT_USER_AGENT
-      self.proxy          = DEFAULT_PROXY
+      self.access_token       = DEFAULT_ACCESS_TOKEN
+      self.adapter            = DEFAULT_ADAPTER
+      self.client_id          = DEFAULT_CLIENT_ID
+      self.client_secret      = DEFAULT_CLIENT_SECRET
+      self.connection_options = DEFAULT_CONNECTION_OPTIONS
+      self.scope              = DEFAULT_SCOPE
+      self.redirect_uri       = DEFAULT_REDIRECT_URI
+      self.endpoint           = DEFAULT_ENDPOINT
+      self.format             = DEFAULT_FORMAT
+      self.proxy              = DEFAULT_PROXY
+      self.user_agent         = DEFAULT_USER_AGENT
+      self.no_response_wrapper= DEFAULT_NO_RESPONSE_WRAPPER      
     end
   end
-end
+end