instagram-continued 1.2.0

data/lib/instagram/client/comments.rb

@@ -0,0 +1,62 @@
+module Instagram
+  class Client
+    # Defines methods related to comments
+    module Comments
+      # Returns a list of comments for a given media item ID
+      #
+      # @overload media_comments(id)
+      #   @param id [Integer] An Instagram media item ID
+      #   @return [Hashie::Mash] The requested comments.
+      #   @example Returns a list of comments for the media item of ID 1234
+      #     Instagram.media_comments(777)
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/comments/#get_media_comments
+      def media_comments(id, *args)
+        response = get("media/#{id}/comments")
+        response
+      end
+
+      # Creates a comment for a given media item ID
+      #
+      # @overload create_media_comment(id, text)
+      #   @param id [Integer] An Instagram media item ID
+      #   @param text [String] The text of your comment
+      #   @return [Hashie::Mash] The comment created.
+      #   @example Creates a new comment on media item with ID 777
+      #     Instagram.create_media_comment(777, "Oh noes!")
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/comments/#post_media_comments
+      def create_media_comment(id, text, options={})
+        response = post("media/#{id}/comments", options.merge(:text => text), signature=true)
+        response
+      end
+
+      # Deletes a comment for a given media item ID
+      #
+      # @overload delete_media_comment(media_id, comment_id)
+      #   @param media_id [Integer] An Instagram media item ID.
+      #   @param comment_id [Integer] Your comment ID of the comment you wish to delete.
+      #   @return [nil]
+      #   @example Delete the comment with ID of 1234, on the media item with ID of 777
+      #     Instagram.delete_media_comment(777, 1234)
+      # @format :json
+      # @authenticated true
+      #
+      #   In order to remove a comment, you must be the owner of the comment, the media item, or both.
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/comments/#delete_media_comments
+      def delete_media_comment(media_id, comment_id, options={})
+        response = delete("media/#{media_id}/comments/#{comment_id}", options, signature=true)
+        response
+      end
+    end
+  end
+end

data/lib/instagram/client/embedding.rb

@@ -0,0 +1,28 @@
+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
+        get("oembed?url=#{url}", {}, false, false, true)
+      end
+    end
+  end
+end

data/lib/instagram/client/geographies.rb

@@ -0,0 +1,29 @@
+module Instagram
+  class Client
+    # Defines methods related to real-time geographies
+    module Geographies
+      # Returns a list of recent media items for a given real-time geography
+      #
+      # @overload geography_recent_media(id, options={})
+      #   @param user [Integer] A geography ID from a real-time subscription.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :count (nil) Limit the number of results returned
+      #   @option options [Integer] :min_id (nil) Return media before this min_id
+      #   @option options [Integer] :max_id (nil) Return media after this max_id
+      #   @option options [Integer] :min_timestamp (nil) Return media after this UNIX timestamp
+      #   @option options [Integer] :max_timestamp (nil) Return media before this UNIX timestamp
+      #   @return [Hashie::Mash]
+      #   @example Return a list of the most recent media items taken within a specific geography
+      #     Instagram.geography_recent_media(514276)
+      # @see http://instagram.com/developer/endpoints/geographies/
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def geography_recent_media(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("geographies/#{id}/media/recent", options)
+        response
+      end
+    end
+  end
+end

data/lib/instagram/client/likes.rb

@@ -0,0 +1,58 @@
+module Instagram
+  class Client
+    # Defines methods related to likes
+    module Likes
+      # Returns a list of users who like a given media item ID
+      #
+      # @overload media_likes(id)
+      #   @param media [Integer] An Instagram media item ID
+      #   @return [Hashie::Mash] A list of users.
+      #   @example Returns a list of users who like the media item of ID 1234
+      #     Instagram.media_likes(777)
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/likes/#get_media_likes
+      def media_likes(id, *args)
+        response = get("media/#{id}/likes")
+        response
+      end
+
+      # Issues a like by the currently authenticated user, for a given media item ID
+      #
+      # @overload like_media(id, text)
+      #   @param id [Integer] An Instagram media item ID
+      #   @return [Hashie::Mash] Metadata
+      #   @example Like media item with ID 777
+      #     Instagram.like_media(777)
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/likes/#post_likes
+      def like_media(id, options={})
+        response = post("media/#{id}/likes", options, signature=true)
+        response
+      end
+
+      # Removes the like on a givem media item ID for the currently authenticated user
+      #
+      # @overload unlike_media(id)
+      #   @param media_id [Integer] An Instagram media item ID.
+      #   @return [Hashie::Mash] Metadata
+      #   @example Remove the like for the currently authenticated user on the media item with the ID of 777
+      #     Instagram.unlike_media(777)
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/likes/#delete_likes
+      def unlike_media(id, options={})
+        response = delete("media/#{id}/likes", options, signature=true)
+        response
+      end
+    end
+  end
+end

data/lib/instagram/client/locations.rb

@@ -0,0 +1,75 @@
+module Instagram
+  class Client
+    # Defines methods related to media items
+    module Locations
+      # Returns extended information of a given Instagram location
+      #
+      # @overload location(id)
+      #   @param location [Integer] An Instagram location ID
+      #   @return [Hashie::Mash] The requested location.
+      #   @example Return extended information for the Instagram office
+      #     Instagram.location(514276)
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/locations/#get_locations
+      def location(id, *args)
+        response = get("locations/#{id}")
+        response
+      end
+
+      # Returns a list of recent media items for a given Instagram location
+      #
+      # @overload location_recent_media(id, options={})
+      #   @param user [Integer] An Instagram location ID.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :max_timestamp (nil) Return media before this UNIX timestamp
+      #   @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.
+      #   @return [Hashie::Mash]
+      #   @example Return a list of the most recent media items taken at the Instagram office
+      #     Instagram.location_recent_media(514276)
+      # @see http://instagram.com/developer/endpoints/locations/#get_locations_media_recent
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def location_recent_media(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("locations/#{id}/media/recent", options)
+        response
+      end
+
+      # Returns Instagram locations within proximity of given lat,lng or Facebook Places ID
+      #
+      # @overload location_search(options={})
+      #   @param facebook_places_id [String] A valid Facebook Places ID
+      #   @param lat [String] A given latitude in decimal format
+      #   @param lng [String] A given longitude in decimal format
+      #   @option options [Integer] :count The number of media items to retrieve.
+      #   @return [Hashie::Mash] location resultm object, #data is an Array.
+      #   @example 1: Return a location with the Facebook Places ID = ()
+      #     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 http://instagram.com/developer/endpoints/locations/#get_locations_search
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def location_search(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        case args.size
+        when 1
+          facebook_places_id = args.first
+          response = get('locations/search', options.merge(:facebook_places_id => facebook_places_id))
+        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
+    end
+  end
+end

data/lib/instagram/client/media.rb

@@ -0,0 +1,82 @@
+module Instagram
+  class Client
+    # Defines methods related to media items
+    module Media
+      # Returns extended information of a given media item
+      #
+      # @overload media_item(id)
+      #   @param user [Integer] An Instagram media item ID
+      #   @return [Hashie::Mash] The requested media item.
+      #   @example Return extended information for media item 1234
+      #     Instagram.media_item(1324)
+      # @format :json
+      # @authenticated false unless requesting media from a protected user
+      #
+      #   If getting this data of a protected user, you must authenticate (and be allowed to see that user).
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/media/#get_media
+      def media_item(*args)
+        id = args.first || 'self'
+        response = get("media/#{id}")
+        response
+      end
+
+      # Returns extended information of a given media item
+      #
+      # @overload media_shortcode(shortcode)
+      #   @param shortcode [String] An Instagram media item shortcode
+      #   @return [Hashie::Mash] The requested media item.
+      #   @example Return extended information for media item with shortcode 'D'
+      #     Instagram.media_shortcode('D')
+      # @format none
+      # @authenticated false unless requesting media from a protected user
+      #
+      #   If getting this data of a protected user, you must authenticate (and be allowed to see that user).
+      # @rate_limited true
+      # @see http://instagram.com/developer/endpoints/media/#get_media_by_shortcode
+      def media_shortcode(*args)
+        shortcode = args.first
+        response = get("media/shortcode/#{shortcode}", {}, false, false, true)
+        response
+      end
+
+      # Returns a list of the overall most popular media
+      #
+      # @overload media_popular(options={})
+      #   @param options [Hash] A customizable set of options.
+      #   @return [Hashie::Mash]
+      #   @example Returns a list of the overall most popular media
+      #     Instagram.media_popular
+      # @see http://instagram.com/developer/endpoints/media/#get_media_popular
+      # @format :json
+      # @authenticated false unless requesting it from a protected user
+      #
+      #   If getting this data of a protected user, you must authenticate (and be allowed to see that user).
+      # @rate_limited true
+      def media_popular(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        id = args.first || "self"
+        response = get("media/popular", options)
+        response
+      end
+
+      # Returns media items within proximity of given lat,lng
+      #
+      # @param lat [String] A given latitude in decimal format
+      # @param lng [String] A given longitude in decimal format
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :count The number of media items to retrieve.
+      # @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 http://instagram.com/developer/endpoints/media/#get_media_search
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def media_search(lat, lng, options={})
+        response = get('media/search', options.merge(:lat => lat, :lng => lng))
+        response
+      end
+    end
+  end
+end

data/lib/instagram/client/subscriptions.rb

@@ -0,0 +1,211 @@
+require 'openssl'
+require 'multi_json'
+
+module Instagram
+  class Client
+    # Defines methods related to real-time
+    module Subscriptions
+      # Returns a list of active real-time subscriptions
+      #
+      # @overload subscriptions(options={})
+      #   @return [Hashie::Mash] The list of subscriptions.
+      #   @example Returns a list of subscriptions for the authenticated application
+      #     Instagram.subscriptions
+      # @format :json
+      # @authenticated true
+      #
+      #   Requires client_secret to be set on the client or passed in options
+      # @rate_limited true
+      # @see https://api.instagram.com/developer/realtime/
+      def subscriptions(options={})
+        response = get("subscriptions", options.merge(:client_secret => client_secret))
+        response
+      end
+
+      # Creates a real-time subscription
+      #
+      # @overload create_subscription(options={})
+      #   @param options [Hash] A set of parameters
+      #   @option options [String] :object The object you'd like to subscribe to (user, tag, location or geography)
+      #   @option options [String] :callback_url The subscription callback URL
+      #   @option options [String] :aspect The aspect of the object you'd like to subscribe to (in this case, "media").
+      #   @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
+      # @overload create_subscription(object, callback_url, aspect="media", options={})
+      #   @param object [String] The object you'd like to subscribe to (user, tag, location or geography)
+      #   @param callback_url [String] The subscription callback URL
+      #   @param aspect [String] The aspect of the object you'd like to subscribe to (in this case, "media").
+      #   @param options [Hash] Addition options and parameters
+      #   @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
+      #
+      #     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.
+      #   @example Creates a new subscription to receive notifications for user media changes.
+      #     Instagram.create_subscription("user", "http://example.com/instagram/callback")
+      # @format :json
+      # @authenticated true
+      #
+      #   Requires client_secret to be set on the client or passed in options
+      # @rate_limited true
+      # @see https://api.instagram.com/developer/realtime/
+      def create_subscription(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        object = args.shift
+        callback_url = args.shift
+        aspect = args.shift
+        options.tap {|o|
+          o[:object] = object unless object.nil?
+          o[:callback_url] = callback_url unless callback_url.nil?
+          o[:aspect] = aspect || o[:aspect] || "media"
+        }
+        response = post("subscriptions", options.merge(:client_secret => client_secret), signature=true)
+        response
+      end
+
+      # Deletes a real-time subscription
+      #
+      # @overload delete_subscription(options={})
+      #   @param options [Hash] Addition options and parameters
+      #   @option options [Integer] :subscription_id The subscription's ID
+      #   @option options [String] :object When specified will remove all subscriptions of this object type, unless an :object_id is also specified (user, tag, location or geography)
+      #   @option options [String, Integer] :object_id When specifying :object, include an :object_id to only remove subscriptions of that object and object_id
+      # @overload delete_subscription(subscription_id, options={})
+      #   @param subscription_id [Integer] The subscription's ID
+      #   @param options [Hash] Addition options and parameters
+      #   @option options [String] :object When specified will remove all subscriptions of this object type, unless an :object_id is also specified (user, tag, location or geography)
+      #   @option options [String, Integer] :object_id When specifying :object, include an :object_id to only remove subscriptions of that object and object_id
+      #   @return [Hashie::Mash]
+      #   @example Deletes an application's user change subscription
+      #     Instagram.delete_subscription(:object => "user")
+      # @format :json
+      # @authenticated true
+      #
+      #   Requires client_secret to be set on the client or passed in options
+      # @rate_limited true
+      # @see https://api.instagram.com/developer/realtime/
+      def delete_subscription(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        subscription_id = args.first
+        options.merge!(:id => subscription_id) if subscription_id
+        response = delete("subscriptions", options.merge(:client_secret => client_secret), signature=true)
+        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: 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']
+          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)
+      #   @param json [String] The JSON response received by the Instagram real-time server
+      #   @param block [Proc] A callable in which callbacks are defined
+      #   @option options [String] :signature Pass in an X-Hub-Signature to use for payload validation
+      #   @return [nil]
+      #   @example Process and handle a notification for a user media change
+      #     Instagram.process_subscription(params[:body]) do |handler|
+      #
+      #       handler.on_user_changed do |user_id, data|
+      #
+      #         user = User.by_instagram_id(user_id)
+      #         @client = Instagram.client(:access_token => _access_token_for_user(user))
+      #         latest_media = @client.user_recent_media[0]
+      #         user.media.create_with_hash(latest_media)
+      #       end
+      #
+      #     end
+      # @format :json
+      # @authenticated true
+      #
+      #   Requires client_secret to be set on the client or passed in options
+      # @rate_limited true
+      # @see https://api.instagram.com/developer/realtime/
+      def process_subscription(json, options={}, &block)
+        raise ArgumentError, "callbacks block expected" unless block_given?
+
+        if options.has_key?(:signature)
+          if !client_secret
+            raise ArgumentError, "client_secret must be set during configure"
+          end
+          digest = OpenSSL::Digest.new('sha1')
+          verify_signature = OpenSSL::HMAC.hexdigest(digest, client_secret, json)
+
+          if options[:signature] != verify_signature
+            raise Instagram::InvalidSignature, "invalid X-Hub-Signature does not match verify signature against client_secret"
+          end
+        end
+
+        payload = MultiJson.decode(json)
+        @changes = Hash.new { |h,k| h[k] = [] }
+        for change in payload
+          @changes[change['object']] << change
+        end
+        block.call(self)
+      end
+
+      [:user, :tag, :location, :geography].each do |object|
+        class_eval <<-RUBY_EVAL, __FILE__, __LINE__ +1
+          def on_#{object}_changed(&block)
+            for change in @changes['#{object}']
+              yield change.delete('object_id'), change
+            end
+          end
+        RUBY_EVAL
+      end
+    end
+  end
+end