localist-instagvram 0.6.2

data/lib/instagram/client/users.rb

@@ -0,0 +1,165 @@
+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 TODO:docs url
+      def user(*args)
+        id = args.first || 'self'
+        response = get("users/#{id}")
+        response["data"]
+      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. Maxiumum of 100 allowed per page.
+      # @return [Array]
+      # @see TODO:doc url
+      # @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["data"]
+      end
+
+      # Returns a list of users whom a given user follows
+      #
+      # @overload 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 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, maximum 150.
+      #   @return [Hashie::Mash]
+      #   @example Return a list of users @mikeyk follows
+      #     Instagram.user_follows(4) # @mikeyk user ID being 4
+      # @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 user_follows(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        id = args.first || "self"
+        response = get("users/#{id}/follows", options)
+        response["data"]
+      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, maximum 150.
+    #   @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
+    # @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["data"]
+    end
+
+    # Returns a list of users whom a given user is followed by
+    #
+    # @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 TODO:docs url
+    # @format :json
+    # @authenticated truei
+    # @rate_limited true
+    def user_requested_by()
+      response = get("users/self/requested-by")
+      response["data"]
+    end
+
+    # Returns the 20 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] :count Specifies the number of records to retrieve, per page. Must be less than or equal to 100.
+    #   @return [Array]
+    #   @example Return the 20 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 TODO:docs URL
+    def user_media_feed(*args)
+      options = args.first.is_a?(Hash) ? args.pop : {}
+      response = get('users/self/feed', options)
+      response["data"]
+    end
+
+    # Returns a list of recent media items for a given user
+    #
+    # @overload user_recent_media(id=nil, 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, maximum 150.
+    #   @return [Hashie::Mash]
+    #   @example Return a list of media items taken by @mikeyk
+    #     Instagram.user_recent_media(4) # @mikeyk user ID being 4
+    # @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 user_recent_media(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      id = args.first || "self"
+      response = get("users/#{id}/media/recent", options)
+      response["data"]
+    end
+  end
+end

data/lib/instagram/client/utils.rb

@@ -0,0 +1,15 @@
+module Instagram
+  class Client
+    # @private
+    module Utils
+      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,90 @@
+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 = [
+      :adapter,
+      :client_id,
+      :client_secret,
+      :access_token,
+      :endpoint,
+      :format,
+      :user_agent,
+      :proxy
+    ].freeze
+
+    # An array of valid request/response formats
+    #
+    # @note Not all methods support the XML format.
+    VALID_FORMATS = [
+      :json].freeze
+
+    # 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 an application redirect uri
+    DEFAULT_REDIRECT_URI = nil
+
+    # By default, don't set a user access token
+    DEFAULT_ACCESS_TOKEN = nil
+
+    # 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
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_USER_AGENT = "Instagram Ruby Gem #{Instagram::VERSION}".freeze
+
+    # @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.adapter        = DEFAULT_ADAPTER
+      self.client_id      = DEFAULT_CLIENT_ID
+      self.client_secret  = DEFAULT_CLIENT_SECRET
+      self.access_token   = DEFAULT_ACCESS_TOKEN
+      self.endpoint       = DEFAULT_ENDPOINT
+      self.format         = DEFAULT_FORMAT
+      self.user_agent     = DEFAULT_USER_AGENT
+      self.proxy          = DEFAULT_PROXY
+    end
+  end
+end

data/lib/instagram/connection.rb

@@ -0,0 +1,31 @@
+require 'faraday_middleware'
+Dir[File.expand_path('../../faraday/*.rb', __FILE__)].each{|f| require f}
+
+module Instagram
+  # @private
+  module Connection
+    private
+
+    def connection(raw=false)
+      options = {
+        :headers => {'Accept' => "application/#{format}; charset=utf-8", 'User-Agent' => user_agent},
+        :proxy => proxy,
+        :ssl => {:verify => false},
+        :url => endpoint,
+      }
+
+      Faraday::Connection.new(options) do |connection|
+        connection.use Faraday::Request::OAuth2, client_id, access_token
+        connection.adapter(adapter)
+        connection.use Faraday::Response::RaiseHttp5xx
+        unless raw
+          case format.to_s.downcase
+          when 'json' then connection.use Faraday::Response::ParseJson
+          end
+        end
+        connection.use Faraday::Response::RaiseHttp4xx
+        connection.use Faraday::Response::Mashify unless raw
+      end
+    end
+  end
+end

data/lib/instagram/error.rb

@@ -0,0 +1,19 @@
+module Instagram
+  # Custom error class for rescuing from all Instagram errors
+  class Error < StandardError; end
+
+  # Raised when Instagram returns the HTTP status code 400
+  class BadRequest < Error; end
+
+  # Raised when Instagram returns the HTTP status code 404
+  class NotFound < Error; end
+
+  # Raised when Instagram returns the HTTP status code 500
+  class InternalServerError < Error; end
+
+  # Raised when Instagram returns the HTTP status code 503
+  class ServiceUnavailable < Error; end
+
+  # Raised when a subscription payload hash is invalid
+  class InvalidSignature < Error; end
+end

data/lib/instagram/oauth.rb

@@ -0,0 +1,27 @@
+module Instagram
+  # Defines HTTP request methods
+  module OAuth
+    # Return URL for OAuth authorization
+    def authorize_url(options={})
+      options[:response_type] ||= "code"
+      params = access_token_params.merge(options)
+      connection.build_url("/oauth/authorize/", params).to_s
+    end
+
+    # Return an access token from authorization
+    def get_access_token(code, options={})
+      options[:grant_type] ||= "authorization_code"
+      params = access_token_params.merge(options)
+      post("/oauth/access_token/", params.merge(:code => code), raw=false, unformatted=true)
+    end
+
+    private
+
+    def access_token_params
+      {
+        :client_id => client_id,
+        :client_secret => client_secret
+      }
+    end
+  end
+end

data/lib/instagram/request.rb

@@ -0,0 +1,45 @@
+module Instagram
+  # Defines HTTP request methods
+  module Request
+    # Perform an HTTP GET request
+    def get(path, options={}, raw=false, unformatted=false)
+      request(:get, path, options, raw, unformatted)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, options={}, raw=false, unformatted=false)
+      request(:post, path, options, raw, unformatted)
+    end
+
+    # Perform an HTTP PUT request
+    def put(path, options={}, raw=false, unformatted=false)
+      request(:put, path, options, raw, unformatted)
+    end
+
+    # Perform an HTTP DELETE request
+    def delete(path, options={}, raw=false, unformatted=false)
+      request(:delete, path, options, raw, unformatted)
+    end
+
+    private
+
+    # Perform an HTTP request
+    def request(method, path, options, raw=false, unformatted=false)
+      response = connection(raw).send(method) do |request|
+        path = formatted_path(path) unless unformatted
+        case method
+        when :get, :delete
+          request.url(path, options)
+        when :post, :put
+          request.path = path
+          request.body = options unless options.empty?
+        end
+      end
+      raw ? response : response.body
+    end
+
+    def formatted_path(path)
+      [path, format].compact.join('.')
+    end
+  end
+end

data/lib/instagram/version.rb

@@ -0,0 +1,3 @@
+module Instagram
+  VERSION = '0.6.2'.freeze unless defined?(::Instagram::VERSION)
+end

data/spec/faraday/response_spec.rb

@@ -0,0 +1,28 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe Faraday::Response do
+  before do
+    @client = Instagram::Client.new
+  end
+
+  {
+    400 => Instagram::BadRequest,
+    404 => Instagram::NotFound,
+    500 => Instagram::InternalServerError,
+    503 => Instagram::ServiceUnavailable
+  }.each do |status, exception|
+    context "when HTTP status is #{status}" do
+
+      before do
+        stub_get('users/self/feed.json').
+          to_return(:status => status)
+      end
+
+      it "should raise #{exception.name} error" do
+        lambda do
+          @client.user_media_feed()
+        end.should raise_error(exception)
+      end
+    end
+  end
+end

data/spec/fixtures/access_token.json

@@ -0,0 +1,9 @@
+{
+    "access_token": "at", 
+    "user": {
+        "username": "mikeyk", 
+        "full_name": "Mike Krieger!!", 
+        "profile_picture": "http://distillery.s3.amazonaws.com/profiles/profile_4_75sq_1292324747_debug.jpg", 
+        "id": "4"
+    }
+}