instagram 0.3.2 → 0.6

data/lib/instagram/api.rb

@@ -0,0 +1,23 @@
+require File.expand_path('../connection', __FILE__)
+require File.expand_path('../request', __FILE__)
+require File.expand_path('../oauth', __FILE__)
+
+module Instagram
+  # @private
+  class API
+    # @private
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    # Creates a new API
+    def initialize(options={})
+      options = Instagram.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include Connection
+    include Request
+    include OAuth
+  end
+end

data/lib/instagram/client.rb

@@ -0,0 +1,19 @@
+module Instagram
+  # Wrapper for the Instagram REST API
+  #
+  # @note All methods have been separated into modules and follow the same grouping used in {TODO:doc_URL the Instagram API Documentation}.
+  # @see TODO:doc_url
+  class Client < API
+    Dir[File.expand_path('../client/*.rb', __FILE__)].each{|f| require f}
+
+    include Instagram::Client::Utils
+
+    include Instagram::Client::Users
+    include Instagram::Client::Media
+    include Instagram::Client::Locations
+    include Instagram::Client::Tags
+    include Instagram::Client::Comments
+    include Instagram::Client::Likes
+    include Instagram::Client::Subscriptions
+  end
+end

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 comment.
+      #   @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 TODO:docs url
+      def media_comments(id, *args)
+        response = get("media/#{id}/comments")
+        response["data"]
+      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 TODO:docs url
+      def create_media_comment(id, text, options={})
+        response = post("media/#{id}/comments", options.merge(:text => text))
+        response["data"]
+      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 either the owner comment or the media item (or both).
+      # @rate_limited true
+      # @see TODO:docs url
+      def delete_media_comment(media_id, comment_id, options={})
+        response = delete("media/#{media_id}/comments/#{comment_id}", options)
+        response["data"]
+      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 TODO:docs url
+      def media_likes(id, *args)
+        response = get("media/#{id}/likes")
+        response["data"]
+      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 [nil]
+      #   @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 TODO:docs url
+      def like_media(id, options={})
+        response = post("media/#{id}/likes", options)
+        response["data"]
+      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 [nil]
+      #   @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 TODO:docs url
+      def unlike_media(id, options={})
+        response = delete("media/#{id}/likes", options)
+        response["data"]
+      end
+    end
+  end
+end

data/lib/instagram/client/locations.rb

@@ -0,0 +1,59 @@
+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 TODO:docs url
+      def location(id, *args)
+        response = get("locations/#{id}")
+        response["data"]
+      end
+
+      # Returns a list of recent media items for a given Instagram location
+      #
+      # @overload location_recent_media(id, options={})
+      #   @param user [Integer] An Instagram user ID.
+      #   @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, maximum 150.
+      #   @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
+      # @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["data"]
+      end
+
+      # Returns Instagram locations within proximity of given lat,lng
+      #
+      # @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. Maxiumum of 100 allowed per page.
+      # @return [Array]
+      # @example Return locations around 37.7808851, -122.3948632 (164 S Park, SF, CA USA)
+      #   Instagram.location_search("37.7808851", "-122.3948632")
+      # @see TODO:doc url
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def location_search(lat, lng, options={})
+        response = get('locations/search', options.merge(:lat => lat, :lng => lng))
+        response["data"]
+      end
+    end
+  end
+end

data/lib/instagram/client/media.rb

@@ -0,0 +1,63 @@
+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 TODO:docs url
+      def media_item(*args)
+        id = args.first || 'self'
+        response = get("media/#{id}")
+        response["data"]
+      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 TODO:docs url
+      # @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["data"]
+      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. Maxiumum of 100 allowed per page.
+      # @return [Array]
+      # @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
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def media_search(lat, lng, options={})
+        response = get('media/search', options.merge(:lat => lat, :lng => lng))
+        response["data"]
+      end
+    end
+  end
+end

data/lib/instagram/client/real_time.rb

@@ -0,0 +1,8 @@
+module Instagram
+  class Client
+    # Defines methods related to real-time
+    module RealTime
+      # TODO
+    end
+  end
+end

data/lib/instagram/client/subscriptions.rb

@@ -0,0 +1,141 @@
+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["data"]
+      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 (max 5000 meters)
+      # @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] he 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 (max 5000 meters)
+      #
+      #     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))
+        response["data"]
+      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, inlcude 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, inlcude an :object_id to only remove subscriptions of that object and object_id
+      #   @return [nil]
+      #   @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))
+        response["data"]
+      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
+      #   @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, &block)
+        raise ArgumentError, "callbacks block expected" unless block_given?
+        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

data/lib/instagram/client/tags.rb

@@ -0,0 +1,59 @@
+module Instagram
+  class Client
+    # Defines methods related to tags
+    module Tags
+      # Returns extended information of a given Instagram tag
+      #
+      # @overload tag(tag)
+      #   @param tag [String] An Instagram tag name
+      #   @return [Hashie::Mash] The requested tag.
+      #   @example Return extended information for the tag "cat"
+      #     Instagram.tag('cat')
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      # @see TODO:docs url
+      def tag(tag, *args)
+        response = get("tags/#{tag}")
+        response["data"]
+      end
+
+      # Returns a list of recent media items for a given Instagram tag
+      #
+      # @overload tag_recent_media(tag, options={})
+      #   @param user [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, maximum 150.
+      #   @return [Hashie::Mash]
+      #   @example Return a list of the most recent media items tagged "cat"
+      #     Instagram.tag_recent_media('cat')
+      # @see TODO:docs url
+      # @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["data"]
+      end
+
+      # Returns a list of tags starting with the given search query
+      #
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      # @param query [String] The beginning or complete tag name to search for
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :count The number of media items to retrieve. Maxiumum of 100 allowed per page.
+      # @return [Array]
+      # @see TODO:doc url
+      # @example Return tags that start with "cat"
+      #   Instagram.tag_search("cat")
+      def tag_search(query, options={})
+        response = get('tags/search', options.merge(:q => query))
+        response["data"]
+      end
+    end
+  end
+end