linkedin-v2 0.1.3

data/lib/linked_in/communications.rb

@@ -0,0 +1,40 @@
+module LinkedIn
+  # Communications APIs
+  #
+  # @see http://developer.linkedin.com/documents/communications
+  class Communications < APIResource
+
+    # (Create) send a message from the authenticated user to a
+    # connection
+    #
+    # Permissions: w_messages
+    #
+    # @see http://developer.linkedin.com/documents/messaging-between-connections-api
+    # @see http://developer.linkedin.com/documents/invitation-api Invitation API
+    #
+    # @example
+    #   api.send_message("subject", "body", ["person_1_id", "person_2_id"])
+    #
+    # @param [String] subject Subject of the message
+    # @param [String] body Body of the message, plain text only
+    # @param [Array<String>] recipient_paths a collection of
+    #  profile paths that identify the users who will receive the
+    #  message
+    # @return [void]
+    def send_message(subject, body, recipient_paths)
+      path = "/people/~/mailbox"
+
+      message = {
+        subject: subject,
+        body: body,
+        recipients: {
+          values: recipient_paths.map do |profile_path|
+            {person: {_path: "/people/#{profile_path}"} }
+          end
+        }
+      }
+
+      post(path, MultiJson.dump(message), "Content-Type" => "application/json")
+    end
+  end
+end

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 = "/v2"
+      @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,35 @@
+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
+
+      logger = Logger.new $stderr
+      logger.level = Logger::DEBUG
+      self.response :logger, logger
+
+      self.response :linkedin_raise_error
+    end
+
+
+    private ##############################################################
+
+
+    def default_url
+      LinkedIn.config.api + LinkedIn.config.api_version
+    end
+  end
+end

data/lib/linked_in/errors.rb

@@ -0,0 +1,73 @@
+module LinkedIn
+  # Thanks https://github.com/ResultadosDigitais/linkedin-oauth2 !
+
+  class Error < StandardError
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+      super
+    end
+  end
+
+  # Raised when users call a deprecated function
+  class Deprecated < LinkedIn::Error; end
+
+  # Raised when we know requests will be malformed and LinkedIn returns
+  # a 400 status code
+  class InvalidRequest < LinkedIn::Error; end
+
+  # Raised when LinkedIn returns a 401 status code during an API
+  # request.
+  class UnauthorizedError < LinkedIn::Error; end
+
+  # Raised when LinkedIn returns a 403 status code during an API
+  # request.
+  class AccessDeniedError < LinkedIn::Error; end
+
+  # Raised when LinkedIn returns a 404 status code during an API
+  # request.
+  class NotFoundError < LinkedIn::Error; end
+
+  # Raised when LinkedIn returns a 500 status code during an API
+  # request.
+  class InformLinkedInError < LinkedIn::Error; end
+
+  # Raised when LinkedIn returns a 502+ status code during an API
+  # request.
+  class UnavailableError < LinkedIn::Error; end
+
+  # Raised when LinkedIn returns a non 400+ status code during an OAuth
+  # request.
+  class OAuthError < OAuth2::Error; end
+
+  module ErrorMessages
+    class << self
+      attr_reader :deprecated,
+                  :redirect_uri,
+                  :no_auth_code,
+                  :no_access_token,
+                  :credentials_missing,
+                  :redirect_uri_mismatch,
+                  :throttled
+    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"
+
+    @redirect_uri_mismatch = "Throttle limit for calls to this resource is reached"
+
+    def klass
+
+    end
+
+
+  end
+end

data/lib/linked_in/jobs.rb

@@ -0,0 +1,11 @@
+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
+  #
+  # I do not have access to the Jobs-related endpoints.
+  # [(contribute here)](https://github.com/mdesjardins/linkedin-v2)
+  class Jobs < APIResource
+  end
+end

data/lib/linked_in/mash.rb

@@ -0,0 +1,68 @@
+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 = JSON.load(json_string)
+      new(result_hash)
+    end
+
+    # returns a Date if we have year, month and day, and no conflicting key
+    def to_date
+      if !self.has_key?('to_date') && contains_date_fields?
+        Date.civil(self.year, self.month, self.day)
+      else
+        super
+      end
+    end
+
+    def timestamp
+      value = self['timestamp']
+      if value.kind_of? Integer
+        value = value / 1000 if value > 9999999999
+        Time.at(value)
+      else
+        value
+      end
+    end
+
+
+    protected ############################################################
+
+
+    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/media.rb

@@ -0,0 +1,13 @@
+module LinkedIn
+  # Rich Media APIs
+  #
+  # @see https://developer.linkedin.com/docs/guide/v2/shares/rich-media-shares
+  #
+  # [(contribute here)](https://github.com/mdesjardins/linkedin-v2)
+  class Media < APIResource
+    def summary(options = {})
+      path = "/richMediaSummariesV2/#{options.delete(:id)}"
+      get(path, options)
+    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