instagram-continued 1.2.0

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 http://instagram.com/developer/endpoints/tags/#get_tags
+      def tag(tag, *args)
+        response = get("tags/#{tag}")
+        response
+      end
+
+      # Returns a list of recent media items for a given Instagram tag
+      #
+      # @overload tag_recent_media(tag, options={})
+      #   @param tag-name [String] An Instagram tag name.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :max_tag_id (nil) Returns results with an ID less than (that is, older than) or equal to the specified ID. The value can be retrieved from the returned response via pagination.max_tag_id.
+      #   @option options [Integer] :min_tag_id (nil) Returns results with an ID greater than (that is, newer than) or equal to the specified ID. The value can be retrieved from the returned response via pagination.min_tag_id.
+      #   @return [Hashie::Mash]
+      #   @example Return a list of the most recent media items tagged "cat"
+      #     Instagram.tag_recent_media('cat')
+      # @see https://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, false, false, false)
+        response
+      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.
+      # @return [Hashie::Mash]
+      # @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={})
+        response = get('tags/search', options.merge(:q => query))
+        response
+      end
+    end
+  end
+end

data/lib/instagram/client/users.rb

@@ -0,0 +1,310 @@
+module Instagram
+  class Client
+    # Defines methods related to users
+    module Users
+      # Returns extended information of a given user
+      #
+      # @overload user(id=nil, options={})
+      #   @param user [Integer] An Instagram user ID
+      #   @return [Hashie::Mash] The requested user.
+      #   @example Return extended information for @shayne
+      #     Instagram.user(20)
+      # @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
+      # @see http://instagram.com/developer/endpoints/users/#get_users
+      def user(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        id = args.first || 'self'
+        response = get("users/#{id}", options)
+        response
+      end
+
+      # Returns users that match the given query
+      #
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      # @param query [String] The search query to run against user search.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :count The number of users to retrieve.
+      # @return [Hashie::Mash]
+      # @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={})
+        response = get('users/search', options.merge(:q => query))
+        response
+      end
+
+      # Returns a list of users whom a given user follows
+      #
+      # @overload user_follows(id=nil, options={})
+      #   @param options [Hash] A customizable set of options.
+      #   @return [Hashie::Mash]
+      #   @example Returns a list of users the authenticated user follows
+      #     Instagram.user_follows
+      # @overload user_follows(id=nil, options={})
+      #   @param user [Integer] An Instagram user ID.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :cursor (nil) Breaks the results into pages. Provide values as returned in the response objects's next_cursor attribute to page forward in the list.
+      #   @option options [Integer] :count (nil) Limits the number of results returned per page.
+      #   @return [Hashie::Mash]
+      #   @example Return a list of users @mikeyk follows
+      #     Instagram.user_follows(4) # @mikeyk user ID being 4
+      # @see http://instagram.com/developer/endpoints/relationships/#get_users_follows
+      # @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 user_follows(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        id = args.first || "self"
+        response = get("users/#{id}/follows", options)
+        response
+      end
+    end
+
+    # Returns a list of users whom a given user is followed by
+    #
+    # @overload user_followed_by(id=nil, options={})
+    #   @param options [Hash] A customizable set of options.
+    #   @return [Hashie::Mash]
+    #   @example Returns a list of users the authenticated user is followed by
+    #     Instagram.user_followed_by
+    # @overload user_followed_by(id=nil, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] A customizable set of options.
+    #   @option options [Integer] :cursor (nil) Breaks the results into pages. Provide values as returned in the response objects's next_cursor attribute to page forward in the list.
+    #   @option options [Integer] :count (nil) Limits the number of results returned per page.
+    #   @return [Hashie::Mash]
+    #   @example Return a list of users @mikeyk is followed by
+    #     Instagram.user_followed_by(4) # @mikeyk user ID being 4
+    # @see http://instagram.com/developer/endpoints/relationships/#get_users_followed_by
+    # @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 user_followed_by(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      id = args.first || "self"
+      response = get("users/#{id}/followed-by", options)
+      response
+    end
+
+    # 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.
+    #   @return [Hashie::Mash]
+    #   @example Returns a list of users awaiting approval of a ollow request, for the authenticated user
+    #     Instagram.user_requested_by
+    # @overload user_requested_by()
+    #   @return [Hashie::Mash]
+    #   @example Return a list of users who have requested to follow the authenticated user
+    #     Instagram.user_requested_by()
+    # @see http://instagram.com/developer/endpoints/relationships/#get_incoming_requests
+    # @format :json
+    # @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
+    #
+    # @overload user_media_feed(options={})
+    #   @param options [Hash] A customizable set of options.
+    #   @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
+    #   @option options [Integer] :min_id Return media later than this min_id
+    #   @option options [Integer] :count Specifies the number of records to retrieve, per page.
+    #   @return [Hashie::Mash]
+    #   @example Return most recent media images that would appear on @shayne's feed
+    #     Instagram.user_media_feed() # assuming @shayne is the authorized user
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    # @see http://instagram.com/developer/endpoints/users/#get_users_feed
+    def user_media_feed(*args)
+      options = args.first.is_a?(Hash) ? args.pop : {}
+      response = get('users/self/feed', options)
+      response
+    end
+
+    # Returns a list of recent media items for a given user
+    #
+    # @overload user_recent_media(options={})
+    #   @param options [Hash] A customizable set of options.
+    #   @return [Hashie::Mash]
+    #   @example Returns a list of recent media items for the currently authenticated user
+    #     Instagram.user_recent_media
+    # @overload user_recent_media(id=nil, 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.
+    #   @return [Hashie::Mash]
+    #   @example Return a list of media items taken by @mikeyk
+    #     Instagram.user_recent_media(4) # @mikeyk user ID being 4
+    # @see http://instagram.com/developer/endpoints/users/#get_users_media_recent
+    # @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 user_recent_media(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      id = args.first || "self"
+      response = get("users/#{id}/media/recent", options)
+      response
+    end
+
+    # Returns a list of media items liked by the current user
+    #
+    # @overload user_liked_media(options={})
+    #   @param options [Hash] A customizable set of options.
+    #   @option options [Integer] :max_like_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 Returns a list of media items liked by the currently authenticated user
+    #     Instagram.user_liked_media
+    # @see http://instagram.com/developer/endpoints/users/#get_users_liked_feed
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def user_liked_media(options={})
+      response = get("users/self/media/liked", options)
+      response
+    end
+
+    # Returns information about the current user's relationship (follow/following/etc) to another user
+    #
+    # @overload user_relationship(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @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/#get_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def user_relationship(id, options={})
+      response = get("users/#{id}/relationship", options)
+      response
+    end
+
+    # Create a follows relationship between the current user and the target user
+    #
+    # @overload follow_user(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @return [Hashie::Mash]
+    #   @example Request the current user to follow the target user
+    #     Instagram.follow_user(4)
+    # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def follow_user(id, options={})
+      options["action"] = "follow"
+      response = post("users/#{id}/relationship", options, signature=true)
+      response
+    end
+
+    # Destroy a follows relationship between the current user and the target user
+    #
+    # @overload unfollow_user(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @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/#post_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def unfollow_user(id, options={})
+      options["action"] = "unfollow"
+      response = post("users/#{id}/relationship", options, signature=true)
+      response
+    end
+
+    # Block a relationship between the current user and the target user
+    #
+    # @overload unfollow_user(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @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/#post_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def block_user(id, options={})
+      options["action"] = "block"
+      response = post("users/#{id}/relationship", options, signature=true)
+      response
+    end
+
+    # Remove a relationship block between the current user and the target user
+    #
+    # @overload unblock_user(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @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/#post_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def unblock_user(id, options={})
+      options["action"] = "unblock"
+      response = post("users/#{id}/relationship", options, signature=true)
+      response
+    end
+
+    # Approve a relationship request between the current user and the target user
+    #
+    # @overload approve_user(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @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/#post_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def approve_user(id, options={})
+      options["action"] = "approve"
+      response = post("users/#{id}/relationship", options, signature=true)
+      response
+    end
+
+    # Deny a relationship request between the current user and the target user
+    #
+    # @overload deny_user(id, options={})
+    #   @param user [Integer] An Instagram user ID.
+    #   @param options [Hash] An optional options hash
+    #   @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/#post_relationship
+    # @format :json
+    # @authenticated true
+    # @rate_limited true
+    def deny_user(id, options={})
+      options["action"] = "deny"
+      response = post("users/#{id}/relationship", options, signature=true)
+      response
+    end
+  end
+end

data/lib/instagram/client/utils.rb

@@ -0,0 +1,28 @@
+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, false, true)
+        response
+      end
+    
+      private
+
+      # Returns the configured user name or the user name of the authenticated user
+      #
+      # @return [String]
+      def get_username
+        @user_name ||= self.user.username
+      end
+    end
+  end
+end

data/lib/instagram/configuration.rb

@@ -0,0 +1,122 @@
+require 'faraday'
+require File.expand_path('../version', __FILE__)
+
+module Instagram
+  # Defines constants and methods related to configuration
+  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,
+      :client_ips,
+      :connection_options,
+      :scope,
+      :redirect_uri,
+      :endpoint,
+      :format,
+      :proxy,
+      :user_agent,
+      :no_response_wrapper,
+      :loud_logger,
+      :sign_requests,
+    ].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
+    #
+    # @note The default faraday adapter is Net::HTTP.
+    DEFAULT_ADAPTER = Faraday.default_adapter
+
+    # By default, don't set an application ID
+    DEFAULT_CLIENT_ID = nil
+
+    # By default, don't set an application secret
+    DEFAULT_CLIENT_SECRET = nil
+
+    # By default, don't set application IPs
+    DEFAULT_CLIENT_IPS = nil
+
+    # By default, don't set any connection options
+    DEFAULT_CONNECTION_OPTIONS = {}
+
+    # The endpoint that will be used to connect if none is set
+    #
+    # @note There is no reason to use any other endpoint at this time
+    DEFAULT_ENDPOINT = 'https://api.instagram.com/v1/'.freeze
+
+    # The response format appended to the path and sent in the 'Accept' header if none is set
+    #
+    # @note JSON is the only available format at this time
+    DEFAULT_FORMAT = :json
+
+    # 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
+
+    # By default, don't turn on loud logging
+    DEFAULT_LOUD_LOGGER = nil
+
+    # By default, requests are not signed
+    DEFAULT_SIGN_REQUESTS = false
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+    end
+
+    # Create a hash of options and their values
+    def options
+      VALID_OPTIONS_KEYS.inject({}) do |option, key|
+        option.merge!(key => send(key))
+      end
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.access_token       = DEFAULT_ACCESS_TOKEN
+      self.adapter            = DEFAULT_ADAPTER
+      self.client_id          = DEFAULT_CLIENT_ID
+      self.client_secret      = DEFAULT_CLIENT_SECRET
+      self.client_ips         = DEFAULT_CLIENT_IPS
+      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
+      self.loud_logger        = DEFAULT_LOUD_LOGGER
+      self.sign_requests      = DEFAULT_SIGN_REQUESTS
+    end
+  end
+end