linkedin-oauth2 0.1.1 → 1.0.0

data/lib/linked_in/configuration.rb

@@ -0,0 +1,41 @@
+module LinkedIn
+  # Configuration for the LinkedIn gem.
+  #
+  #     LinkedIn.configure do |config|
+  #       config.client_id     = ENV["LINKEDIN_CLIENT_ID"]
+  #       config.client_secret = ENV["LINKEDIN_CLIENT_SECRET"]
+  #     end
+  #
+  # The default endpoints for LinkedIn are also stored here.
+  #
+  # LinkedIn uses the term "API key" to refer to "client id". They also
+  # use the term "Secret Key" to refer to "client_secret". We alias those
+  # terms in the config.
+  #
+  # * LinkedIn.config.site = "https://www.linkedin.com"
+  # * LinkedIn.config.token_url = "/uas/oauth2/accessToken"
+  # * LinkedIn.config.authorize_url = "/uas/oauth2/authorization"
+  class Configuration
+    attr_accessor :api,
+                  :site,
+                  :scope,
+                  :client_id,
+                  :token_url,
+                  :api_version,
+                  :redirect_uri,
+                  :authorize_url,
+                  :client_secret,
+                  :default_profile_fields
+
+    alias_method :api_key, :client_id
+    alias_method :secret_key, :client_secret
+
+    def initialize
+      @api = "https://api.linkedin.com"
+      @api_version = "/v1"
+      @site = "https://www.linkedin.com"
+      @token_url = "/uas/oauth2/accessToken"
+      @authorize_url = "/uas/oauth2/authorization"
+    end
+  end
+end

data/lib/linked_in/connection.rb

@@ -0,0 +1,31 @@
+module LinkedIn
+  # Used to perform requests against LinkedIn's API.
+  class Connection < ::Faraday::Connection
+
+    def initialize(url=nil, options=nil, &block)
+
+      if url.is_a? Hash
+        options = url
+        url = options[:url]
+      end
+
+      url = default_url if url.nil?
+
+      super url, options, &block
+
+      # We need to use the FlatParamsEncoder so we can pass multiple of
+      # the same param to certain endpoints (like the search API).
+      self.options.params_encoder = ::Faraday::FlatParamsEncoder
+
+      self.response :raise_error
+    end
+
+
+    private ##############################################################
+
+
+    def default_url
+      LinkedIn.config.api + LinkedIn.config.api_version
+    end
+  end
+end

data/lib/linked_in/errors.rb

@@ -1,19 +1,39 @@
 module LinkedIn
-  module Errors
-    class LinkedInError < StandardError
-      attr_reader :data
-      def initialize(data)
-        @data = data
-        super
-      end
+
+  # Raised when users call a deprecated function
+  class Deprecated < StandardError; end
+
+  # Raised when we know requests will be malformed
+  class InvalidRequest < StandardError; end
+
+  # Raised when LinkedIn returns a non 400+ status code during an OAuth
+  # request.
+  class OAuthError < OAuth2::Error; end
+
+  # Raised when LinkedIn returns a non 400+ status code during an API
+  # request
+  class APIError < OAuth2::Error; end
+
+  module ErrorMessages
+    class << self
+      attr_reader :deprecated,
+                  :redirect_uri,
+                  :no_auth_code,
+                  :no_access_token,
+                  :credentials_missing,
+                  :redirect_uri_mismatch
     end
 
-    class UnauthorizedError      < LinkedInError; end
-    class GeneralError           < LinkedInError; end
-    class AccessDeniedError      < LinkedInError; end
+    @deprecated = "This has been deprecated by LinkedIn. Check https://developer.linkedin.com to see the latest available API calls"
+
+    @redirect_uri = "You must provide a redirect_uri. Set it in LinkedIn.configure or pass it in as the redirect_uri option. It must exactly match the redirect_uri you set on your application's settings page on LinkedIn's website."
+
+    @no_auth_code = "You must provide the authorization code passed to your redirect uri in the url params"
+
+    @no_access_token = "You must have an access token to use LinkedIn's API. Use the LinkedIn::OAuth2 module to obtain an access token"
+
+    @credentials_missing = "Client credentials do not exist. Please either pass your client_id and client_secret to the LinkedIn::Oauth.new constructor or set them via LinkedIn.configure"
 
-    class UnavailableError       < StandardError; end
-    class InformLinkedInError    < StandardError; end
-    class NotFoundError          < StandardError; end
+    @redirect_uri_mismatch = "Your redirect_uri must be exactly the same as the one used to generated your auth code url"
   end
 end

data/lib/linked_in/groups.rb

@@ -0,0 +1,116 @@
+module LinkedIn
+  # Groups API
+  #
+  # @see http://developer.linkedin.com/documents/groups-api Groups API
+  # @see http://developer.linkedin.com/documents/groups-fields Groups Fields
+  #
+  # The following API actions do not have corresponding methods in
+  # this module
+  #
+  #   * PUT Change my Group Settings
+  #   * POST Change my Group Settings
+  #   * DELETE Leave a group
+  #   * PUT Follow/unfollow a Group post
+  #   * PUT Flag a Post as a Promotion or Job
+  #   * DELETE Delete a Post
+  #   * DELETE Flag a post as inappropriate
+  #   * DELETE A comment or flag comment as inappropriate
+  #   * DELETE Remove a Group Suggestion
+  #
+  # [(contribute here)](https://github.com/emorikawa/linkedin-oauth2)
+  class Groups < APIResource
+    # Retrieve group suggestions for the current user
+    #
+    # Permissions: r_fullprofile
+    #
+    # @see http://developer.linkedin.com/documents/job-bookmarks-and-suggestions
+    #
+    # @macro profile_options
+    # @return [LinkedIn::Mash]
+    def group_suggestions(options = {})
+      path = "#{profile_path(options)}/suggestions/groups"
+      get(path, options)
+    end
+
+    # Retrieve the groups a current user belongs to
+    #
+    # Permissions: rw_groups
+    #
+    # @see http://developer.linkedin.com/documents/groups-api
+    #
+    # @macro profile_options
+    # @return [LinkedIn::Mash]
+    def group_memberships(options = {})
+      path = "#{profile_path(options)}/group-memberships"
+      get(path, options)
+    end
+
+    # Retrieve the profile of a group
+    #
+    # Permissions: rw_groups
+    #
+    # @see http://developer.linkedin.com/documents/groups-api
+    #
+    # @param [Hash] options identifies the group or groups
+    # @optio options [String] :id identifier for the group
+    # @return [LinkedIn::Mash]
+    def group_profile(options)
+      path = group_path(options)
+      get(path, options)
+    end
+
+    # Retrieve the posts in a group
+    #
+    # Permissions: rw_groups
+    #
+    # @see http://developer.linkedin.com/documents/groups-api
+    #
+    # @param [Hash] options identifies the group or groups
+    # @optio options [String] :id identifier for the group
+    # @optio options [String] :count
+    # @optio options [String] :start
+    # @return [LinkedIn::Mash]
+    def group_posts(options)
+      path = "#{group_path(options)}/posts"
+      get(path, options)
+    end
+
+    # Create a share for a company that the authenticated user
+    # administers
+    #
+    # Permissions: rw_groups
+    #
+    # @see http://developer.linkedin.com/documents/groups-api#create
+    #
+    # @param [String] group_id Group ID
+    # @macro share_input_fields
+    # @return [void]
+    def add_group_share(group_id, share)
+      path = "/groups/#{group_id}/posts"
+      post(path, share)
+    end
+
+    # (Update) User joins, or requests to join, a group
+    #
+    # @see http://developer.linkedin.com/documents/groups-api#membergroups
+    #
+    # @param [String] group_id Group ID
+    # @return [void]
+    def join_group(group_id)
+      path = "/people/~/group-memberships/#{group_id}"
+      body = {'membership-state' => {'code' => 'member' }}
+      put(path, body)
+    end
+
+
+    private ##############################################################
+
+
+    def group_path(options)
+      path = "/groups"
+      if id = options.delete(:id)
+        path += "/#{id}"
+      end
+    end
+  end
+end

data/lib/linked_in/jobs.rb

@@ -0,0 +1,68 @@
+module LinkedIn
+  # Jobs API
+  #
+  # @see http://developer.linkedin.com/documents/job-lookup-api-and-fields Job Lookup API and Fields
+  # @see http://developer.linkedin.com/documents/job-bookmarks-and-suggestions Job Bookmarks and Suggestions
+  #
+  # The following API actions do not have corresponding methods in
+  # this module
+  #
+  #   * DELETE a Job Bookmark
+  class Jobs < APIResource
+    # Retrieve likes on a particular company update:
+    #
+    # @see http://developer.linkedin.com/reading-company-shares
+    #
+    # @param [Hash] options identifies the job
+    # @option options [String] id unique identifier for a job
+    # @return [LinkedIn::Mash]
+    def job(options = {})
+      path = jobs_path(options)
+      get(path, options)
+    end
+
+    # Retrieve the current members' job bookmarks
+    #
+    # @see http://developer.linkedin.com/documents/job-bookmarks-and-suggestions
+    #
+    # @macro profile_options
+    # @return [LinkedIn::Mash]
+    def job_bookmarks(options = {})
+      path = "#{profile_path(options)}/job-bookmarks"
+      get(path, options)
+    end
+
+    # Retrieve job suggestions for the current user
+    #
+    # @see http://developer.linkedin.com/documents/job-bookmarks-and-suggestions
+    #
+    # @macro profile_options
+    # @return [LinkedIn::Mash]
+    def job_suggestions(options = {})
+      path = "#{profile_path(options)}/suggestions/job-suggestions"
+      get(path, options)
+    end
+
+    # Create a job bookmark for the authenticated user
+    #
+    # @see http://developer.linkedin.com/documents/job-bookmarks-and-suggestions
+    #
+    # @param [String] job_id Job ID
+    # @return [void]
+    def add_job_bookmark(job_id)
+      path = "/people/~/job-bookmarks"
+      post(path, {job: {id: job_id}})
+    end
+
+    private ##############################################################
+
+    def jobs_path(options)
+      path = "/jobs"
+      if id = options.delete(:id)
+        path += "/id=#{id}"
+      else
+        path += "/~"
+      end
+    end
+  end
+end

data/lib/linked_in/mash.rb

@@ -1,12 +1,11 @@
-require 'hashie'
-require 'multi_json'
-
 module LinkedIn
+  # Coerces LinkedIn JSON to a nice Ruby hash
+  # LinkedIn::Mash inherits from Hashie::Mash
   class Mash < ::Hashie::Mash
 
     # a simple helper to convert a json string to a Mash
     def self.from_json(json_string)
-      result_hash = ::MultiJson.decode(json_string)
+      result_hash = JSON.load(json_string)
       new(result_hash)
     end
 
@@ -29,40 +28,41 @@ module LinkedIn
       end
     end
 
-    protected
 
-      def contains_date_fields?
-        self.year? && self.month? && self.day?
-      end
+    protected ############################################################
 
-      # overload the convert_key mash method so that the LinkedIn
-      # keys are made a little more ruby-ish
-      def convert_key(key)
-        case key.to_s
-        when '_key'
-          'id'
-        when '_total'
-          'total'
-        when 'values'
-          'all'
-        when 'numResults'
-          'total_results'
-        else
-          underscore(key)
-        end
-      end
 
-      # borrowed from ActiveSupport
-      # no need require an entire lib when we only need one method
-      def underscore(camel_cased_word)
-        word = camel_cased_word.to_s.dup
-        word.gsub!(/::/, '/')
-        word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
-        word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
-        word.tr!("-", "_")
-        word.downcase!
-        word
+    def contains_date_fields?
+      self.year? && self.month? && self.day?
+    end
+
+    # overload the convert_key mash method so that the LinkedIn
+    # keys are made a little more ruby-ish
+    def convert_key(key)
+      case key.to_s
+      when '_key'
+        'id'
+      when '_total'
+        'total'
+      when 'values'
+        'all'
+      when 'numResults'
+        'total_results'
+      else
+        underscore(key)
       end
+    end
 
+    # borrowed from ActiveSupport
+    # no need require an entire lib when we only need one method
+    def underscore(camel_cased_word)
+      word = camel_cased_word.to_s.dup
+      word.gsub!(/::/, '/')
+      word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
   end
 end

data/lib/linked_in/oauth2.rb

@@ -0,0 +1,223 @@
+module LinkedIn
+  # The LinkedIn::OAuth2::Client class. Inherits directly from [intreda/oauth2](https://github.com/intridea/oauth2)'s `OAuth2::Client`
+  #
+  # LinkedIn::OAuth2 sets the following default options:
+  #
+  # * site = "https://www.linkedin.com"
+  # * token_url = "/uas/oauth2/accessToken"
+  # * authorize_url = "/uas/oauth2/authorization"
+  #
+  # More details on LinkedIn's Authorization process can be found here: https://developer.linkedin.com/documents/authentication
+  class OAuth2 < ::OAuth2::Client
+
+    attr_accessor :access_token
+
+    # Instantiate a new OAuth 2.0 client using your client ID (aka API
+    # Key) and client secret (aka Secret Key).
+    #
+    # You should set the client_id and client_secret in the config.
+    #
+    #     LinkedIn.configure do |config|
+    #       config.client_id     = ENV["LINKEDIN_CLIENT_ID"]
+    #       config.client_secret = ENV["LINKEDIN_CLIENT_SECRET"]
+    #     end
+    #
+    # This will let you initialize with zero arguments.
+    #
+    # If you have already set the `client_id` and `client_secret` in your
+    # config, the first and only argument can be the `options` hash.
+    #
+    # @param [String] client_id the client_id value
+    # @param [String] client_secret the client_secret value
+    # @param [Hash] options the options to create the client with
+    # @option options [Symbol] :token_method (:post) HTTP method to use to
+    #   request token (:get or :post)
+    # @option options [Hash] :connection_opts ({}) Hash of connection options 
+    #   to pass to initialize Faraday with
+    # @option options [FixNum] :max_redirects (5) maximum number of redirects 
+    #   to follow
+    # @option options [Boolean] :raise_errors (true) whether or not to
+    #   raise an error on malformed responses
+    # @yield [builder] The Faraday connection builder
+    def initialize(client_id=LinkedIn.config.client_id,
+                   client_secret=LinkedIn.config.client_secret,
+                   options = {}, &block)
+
+      if client_id.is_a? Hash
+        options = client_id
+        client_id = LinkedIn.config.client_id
+      end
+
+      options = default_oauth_options(options)
+
+      super client_id, client_secret, options, &block
+
+      @redirect_uri = options[:redirect_uri]
+
+      if self.options[:raise_errors]
+        check_credentials!(client_id, client_secret)
+      end
+    end
+
+    # Generates the URL users use to sign into your application.
+    #
+    # Once a user enters their LinkedIn credentials, they will be
+    # redirected to your `redirect_uri` with the `code` parameter attached
+    # to it. The value of the `code` parameter can be used to get an
+    # access token.
+    #
+    # We recommend you set your `client_id, `client_secret`, and
+    # `redirect_uri` in the `LinkedIn.configure` block. They can also be
+    # passed in as options.
+    #
+    # @param [Hash] options the options to generate the url with
+    # @option options [String] :redirect_uri The url that gets redirected
+    #   to after a successful authentication. This must exactly match the
+    #   redirect urls setup on your LinkedIn Application Settings page.
+    #   This option is not required if you already set the redirect_uri in
+    #   the config.
+    # @option options [String] :scope A string of requested permissions
+    #   you want from users when they authenticate with your app. If these
+    #   are set on yoru LinkedIn Application settings page, you do not
+    #   need to pass them in. The string must be a space-sparated,
+    #   case-sensitive list of available scopes. See available scopes on
+    #   LinkedIn's API documentation page.
+    # @option options [String] :state A long string used for CSRF
+    #   protection. It is added as the `state` GET param in the
+    #   redirect_uri
+    # @option options [Boolean] :raise_errors (true) whether or not to
+    #   raise an error on malformed responses
+    def auth_code_url(options={})
+      options = default_auth_code_url_options(options)
+
+      if self.options[:raise_errors]
+        check_redirect_uri!(options)
+      end
+
+      @redirect_uri = options[:redirect_uri]
+
+      self.auth_code.authorize_url(options)
+    end
+
+    # Returns the access token string for the newly authenticated user.
+    #
+    # It also sets the `access_token` field on this LinkedIn::OAuth2
+    # instance.
+    #
+    # The required `code`
+    #
+    # @param [String] code the auth code which is passed in as a GET
+    #   parameter to your `redirect_uri` after users authenticate your app
+    # @param [Hash] options
+    # @option options [String] :redirect_uri You normally should not have
+    #   to pass in the redirect_uri again. If `auth_code_url` was called
+    #   on this LinkedIn::OAuth2 instance, then the `redirect_uri` will
+    #   already be set. This is because the `redirect_uri` in the access
+    #   token request must exactly match the `redirect_uri` in the auth
+    #   code url.
+    # @option options [Boolean] :raise_errors (true) whether or not to
+    #   raise an error on malformed responses
+    def get_access_token(code=nil, options={})
+      check_for_code!(code)
+      options = default_access_code_options(options)
+
+      if self.options[:raise_errors]
+        check_access_code_url!(options)
+      end
+
+      tok = self.auth_code.get_token(code, options)
+      self.access_token = LinkedIn::AccessToken.new(tok.token,
+                                                    tok.expires_in,
+                                                    tok.expires_at)
+      return self.access_token
+    rescue ::OAuth2::Error => e
+      raise OAuthError.new(e.response)
+    end
+
+
+    private ##############################################################
+
+
+    def default_access_code_options(custom_options={})
+      custom_options ||= {}
+      options = {raise_errors: true}
+
+      @redirect_uri = LinkedIn.config.redirect_uri if @redirect_uri.nil?
+      options[:redirect_uri] = @redirect_uri
+
+      options = options.merge custom_options
+      return options
+    end
+
+    def default_auth_code_url_options(custom_options={})
+      custom_options ||= {}
+      options = {raise_errors: true}
+
+      if not LinkedIn.config.redirect_uri.nil?
+        options[:redirect_uri] = LinkedIn.config.redirect_uri
+      end
+      if not LinkedIn.config.scope.nil?
+        options[:scope] = LinkedIn.config.scope
+      end
+
+      options = options.merge custom_options
+
+      if options[:state].nil?
+        options[:state] = generate_csrf_token
+      end
+
+      return options
+    end
+
+    def generate_csrf_token
+      SecureRandom.base64(32)
+    end
+
+    def check_access_code_url!(options={})
+      check_redirect_uri!(options)
+      if options[:redirect_uri] != @redirect_uri
+        raise redirect_uri_mismatch
+      end
+    end
+
+    def check_for_code!(code)
+      if code.nil?
+        msg = ErrorMessages.no_auth_code
+        raise InvalidRequest.new(msg)
+      end
+    end
+
+    def check_redirect_uri!(options={})
+      if options[:redirect_uri].nil?
+        raise redirect_uri_error
+      end
+    end
+
+    def default_oauth_options(custom_options={})
+      custom_options ||= {}
+      options = {}
+      options[:site] = LinkedIn.config.site
+      options[:token_url] = LinkedIn.config.token_url
+      options[:authorize_url] = LinkedIn.config.authorize_url
+      return options.merge custom_options
+    end
+
+    def check_credentials!(client_id, client_secret)
+      if client_id.nil? or client_secret.nil?
+        raise credential_error
+      end
+    end
+
+    def redirect_uri_error
+      InvalidRequest.new ErrorMessages.redirect_uri
+    end
+
+    def credential_error
+      InvalidRequest.new ErrorMessages.credentials_missing
+    end
+
+    def redirect_uri_mismatch
+      InvalidRequest.new ErrorMessages.redirect_uri_mismatch
+    end
+  end
+end