linkedin-v2 0.1.3

data/lib/linked_in/share_and_social_stream.rb

@@ -0,0 +1,143 @@
+module LinkedIn
+  # Share and Social Stream APIs
+  #
+  # @see https://developer.linkedin.com/docs/guide/v2/shares
+  # @see https://developer.linkedin.com/docs/guide/v2/shares/share-api
+  # @see https://developer.linkedin.com/docs/guide/v2/shares/network-update-social-actions
+  #
+  # LinkedIn's v2 API adherence to the documentation is shaky at best. Several of
+  # the calls simply don't work if you, e.g., pass the URN in as a path element
+  # for a resource - you have to use the ids=[URN] format w/ a single URN. Or
+  # sometimes passing in an "actor" parameter in the request body simply doesn't
+  # work, and you have to pass it in as a URL parameter. What you see in this
+  # file is the result of trial-and-error getting these endpoints to work, and the
+  # inconsistency is usually a result of either misunderstanding the docs or the
+  # API not working as advertised. It's also a bit unclear when the API wants
+  # an activity URN vs, e.g., an article URN. Caveat emptor.
+  #
+  # [(contribute here)](https://github.com/mdesjardins/linkedin-v2)
+  class ShareAndSocialStream < APIResource
+
+    # Retrieve shares from a person, organization, or organizationBrand.
+    #
+    # Permissions:
+    #   1.) For personal shares, you may only retrieve shares for the authorized members.
+    #   2.) For organization shares, you may only retrieve shares for organizations for which the
+    #       authorized member is an administrator.
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/share-api#retrieve
+    #
+    # @options options [String] :owner, the URN for whom we are fetching shares.
+    # @return [LinkedIn::Mash]
+    #
+    def shares(options = {})
+      urn = options.delete(:urn)
+      path = "/shares?q=owners&owners=#{urn}"
+      get(path, options)
+    end
+
+    # Create one share from a person, organization, or organizationBrand.
+    #
+    # Permissions:
+    #  1.) For personal shares, you may only post shares as the authorized member.
+    #  2.) For organization shares, you may only post shares as an organization for which the
+    #      authorized member is an administrator.
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/share-api#post
+    #
+    # @option options [String] :owner, the URN of the entity posting the share.
+    # @return [LinkedIn::Mash]
+    #
+    def share(options = {})
+      path = '/shares'
+      defaults = {
+        distribution: {
+          linkedInDistributionTarget: {
+            visibleToGuest: true
+          }
+        }
+      }
+      post(path, MultiJson.dump(defaults.merge(options)), 'Content-Type' => 'application/json')
+    end
+
+    # Retrieves the likes for a specific post.
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/network-update-social-actions#retrieve
+    #
+    # @option options [String] :urn, the URN of the relevant share, UGC post, or comment
+    # @return [LinkedIn::Mash]
+    #
+    def likes(options = {})
+      urn = options.delete(:urn)
+      path = "/socialActions/#{urn}/likes"
+      get(path, options)
+    end
+
+    # Likes a specific share or comment.
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/network-update-social-actions#retrieve.
+    # @option options [String] :object, specifies the URN of the entity to which the like belongs.
+    # This object should be a sub-entity of the top-level share indicated in the request URL, and
+    # should be represented as an URN either of format urn:li:share:{id}
+    # @option options [String] :urn, specifies activity being un-liked (e.g., urn:li:activity::123)
+    # @option options [String] :actor, specifies the entity performing the action. It should be
+    # represented by a urn:li:person:{id} or urn:li:organization:{id} URN.
+    #
+    def like(options = {})
+      urn = options.delete(:urn)
+      path = "/socialActions/#{urn}/likes"
+      post(path, MultiJson.dump(options), 'Content-Type' => 'application/json')
+    end
+
+    # Un-likes a previously liked share or comment.
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/network-update-social-actions#retrieve.
+    # @option options [String] :urn, specifies activity being un-liked (e.g., urn:li:activity:123)
+    # @option options [String] :actor, specifies the entity performing the action. It should b    # represented by a urn:li:person:{id} or urn:li:organization:{id} URN.
+    #
+    def unlike(options = {})
+      urn = options.delete(:urn)
+      actor = options.delete(:actor)
+      path = "/socialActions/#{urn}/likes/#{actor}?actor=#{CGI::escape(actor)}"
+      delete(path, MultiJson.dump(options), 'Content-Type' => 'application/json') #options)
+    end
+
+    # Retrieves the comments for a specific post.
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/network-update-social-actions#retrieve
+    # @option options [String] :urn, specifies activity queried for comments (e.g.,
+    # urn:li:article:123)
+    #
+    def comments(options = {})
+      urn = options.delete(:urn)
+      path = "/socialActions/#{urn}/comments"
+      get(path, options)
+    end
+
+    # Adds a comment to a specific post.
+    #
+    # Permissions:
+    #
+    # @see https://developer.linkedin.com/docs/guide/v2/shares/network-update-social-actions#retrieve
+    #
+    # @option options [String] :urn, specifies activity queried for comments (e.g.,
+    # urn:li:article:123)
+    # @option options [String] :actor, specifies the entity performing the action. It should b    # represented by a urn:li:person:{id} or urn:li:organization:{id} URN.
+    # @option options [String] :message, the text content of the comment.
+    #
+    def comment(options = {})
+      urn = options.delete(:urn)
+      actor = options.delete(:actor)
+      message = options.delete(:message)
+      body = {
+        actor: actor,
+        message: {
+          attributes: [],
+          text: message
+        }
+      }
+      path = "/socialActions/#{urn}/comments"
+      post(path, MultiJson.dump(body), 'Content-Type' => 'application/json')
+    end
+  end
+end

data/lib/linked_in/version.rb

@@ -0,0 +1,3 @@
+module LinkedIn
+  VERSION = '0.1.3'
+end

data/lib/linkedin-v2.rb

@@ -0,0 +1,52 @@
+require "oauth2"
+
+require "linked_in/errors"
+require "linked_in/raise_error"
+require "linked_in/version"
+require "linked_in/configuration"
+
+# Responsible for all authentication
+# LinkedIn::OAuth2 inherits from OAuth2::Client
+require "linked_in/oauth2"
+
+# Coerces LinkedIn JSON to a nice Ruby hash
+# LinkedIn::Mash inherits from Hashie::Mash
+require "hashie"
+require "linked_in/mash"
+
+# Wraps a LinkedIn-specifc API connection
+# LinkedIn::Connection inherits from Faraday::Connection
+require "faraday"
+require "linked_in/connection"
+
+# Data object to wrap API access token
+require "linked_in/access_token"
+
+# Endpoints inherit from APIResource
+require "linked_in/api_resource"
+
+# All of the endpoints
+require "linked_in/jobs"
+require "linked_in/people"
+require "linked_in/search"
+# require "linked_in/groups" not supported by v2 API?
+require "linked_in/organizations"
+require "linked_in/communications"
+require "linked_in/share_and_social_stream"
+require 'linked_in/media'
+
+# The primary API object that makes requests.
+# It composes in all of the endpoints
+require "linked_in/api"
+
+module LinkedIn
+  @config = Configuration.new
+
+  class << self
+    attr_accessor :config
+  end
+
+  def self.configure
+    yield self.config
+  end
+end

data/linkedin-v2.gemspec

@@ -0,0 +1,39 @@
+# encoding: utf-8
+# Follow http://guides.rubygems.org/ best practices
+
+require File.expand_path("../lib/linked_in/version", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name        = "linkedin-v2"
+  gem.email       = ["mike.desjardins@cereslogic.com"]
+  gem.version     = LinkedIn::VERSION
+  gem.authors     = ["Mike Desjardins"]
+  gem.summary     = "Ruby wrapper for the LinkedIn v2 API"
+  gem.license     = "MIT"
+  gem.homepage    = "http://github.com/mdesjardins/linkedin-v2"
+  gem.description = gem.summary
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- spec/**/*`.split("\n")
+  gem.require_paths = ["lib"]
+
+  # To support native JSON. Same requirements as Rails.
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_dependency "oauth2",  "~> 1.0"
+  gem.add_dependency "hashie",  "~> 3.2"
+  gem.add_dependency "faraday", "~> 0.11"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "rspec", "~> 3.0"
+
+  # We use YARD for documentation
+  # Extra gems for GitHub flavored MarkDown in YARD
+  gem.add_development_dependency "yard"
+  gem.add_development_dependency "redcarpet"
+  gem.add_development_dependency "github-markdown"
+
+  # We use VCR to mock LinkedIn API calls
+  gem.add_development_dependency "vcr"
+  gem.add_development_dependency "webmock"
+end

data/spec/linked_in/api/api_spec.rb

@@ -0,0 +1,41 @@
+require "spec_helper"
+
+describe LinkedIn::API do
+  context "With no access token" do
+    let(:err_msg) { LinkedIn::ErrorMessages.no_access_token }
+
+    it "Raises an error" do
+      expect{LinkedIn::API.new}.to raise_error(LinkedIn::InvalidRequest, err_msg)
+    end
+  end
+
+  shared_examples "test access token" do
+    it "Build a LinkedIn::API instance" do
+      expect(subject).to be_kind_of LinkedIn::API
+    end
+
+    it "Sets the access_token object" do
+      expect(subject.access_token).to be_kind_of LinkedIn::AccessToken
+    end
+
+    it "Sets the access_token string" do
+      expect(subject.access_token.token).to eq access_token
+    end
+  end
+
+  context "With a string access token" do
+    let(:access_token) { "dummy_access_token" }
+    subject {LinkedIn::API.new(access_token)}
+
+    include_examples "test access token"
+  end
+
+  context "With a LinkedIn::AccessToken object" do
+    let(:access_token) { "dummy_access_token" }
+    let(:access_token_obj) { LinkedIn::AccessToken.new(access_token) }
+
+    subject {LinkedIn::API.new(access_token_obj)}
+
+    include_examples "test access token"
+  end
+end

data/spec/linked_in/api/communications_spec.rb

@@ -0,0 +1,13 @@
+require "spec_helper"
+
+describe LinkedIn::Communications do
+  let(:access_token) {"dummy_access_token"}
+  let(:api) {LinkedIn::API.new(access_token)}
+
+  it "should be able to send a message" do
+    stub_request(:post, "https://api.linkedin.com/v1/people/~/mailbox?oauth2_access_token=dummy_access_token").to_return(body: "", status: 201)
+    response = api.send_message("subject", "body", ["recip1", "recip2"])
+    expect(response.body).to eq ""
+    expect(response.status).to eq 201
+  end
+end

data/spec/linked_in/api/jobs_spec.rb

@@ -0,0 +1,33 @@
+require "spec_helper"
+
+describe LinkedIn::Jobs, helpers: :api do
+  let(:access_token) {"dummy_access_token"}
+  let(:api) {LinkedIn::API.new(access_token)}
+
+  def stub(url)
+    url += "oauth2_access_token=#{access_token}"
+    stub_request(:get, url).to_return(body: '{}')
+  end
+
+  it "should be able to view a job listing" do
+    stub("https://api.linkedin.com/v1/jobs/id=1586?")
+    expect(api.job(:id => 1586)).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should be able to view its job bookmarks" do
+    stub("https://api.linkedin.com/v1/people/~/job-bookmarks?")
+    expect(api.job_bookmarks).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should be able to view its job suggestion" do
+    stub("https://api.linkedin.com/v1/people/~/suggestions/job-suggestions?")
+    expect(api.job_suggestions).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should be able to add a bookmark" do
+    stub_request(:post, "https://api.linkedin.com/v1/people/~/job-bookmarks?oauth2_access_token=#{access_token}").to_return(body: "", status: 201)
+    response = api.add_job_bookmark(id: 1452577)
+    expect(response.body).to eq ""
+    expect(response.status).to eq 201
+  end
+end

data/spec/linked_in/api/organizations_spec.rb

@@ -0,0 +1,54 @@
+require "spec_helper"
+
+describe LinkedIn::Organizations do
+  let(:access_token) {"dummy access token"}
+  let(:api) {LinkedIn::API.new(access_token)}
+
+  def stub(url)
+    stub_request(:get, url).to_return(body: '{}')
+  end
+
+  it "should be able to view an organization profile" do
+    stub("https://api.linkedin.com/v2/organizations/1586")
+    expect(api.organization(id: 1586)).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should be able to view an organization by vanity name" do
+    stub("https://api.linkedin.com/v2/organizations?q=vanityName&vanityName=acme")
+    expect(api.organization(vanity_name: "acme")).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should be able to view an organization by e-mail domain" do
+    stub("https://api.linkedin.com/v2/organizations?q=emailDomain&emailDomain=acme.com")
+    expect(api.organization(email_domain: "acme.com")).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should load correct organization data" do
+    VCR.use_cassette("organization data") do
+      data = api.organization(id: 11571530)
+      expect(data.id).to eq 11571530
+      expect(data.name).to eq( {"localized"=>{"en_us"=>"del Nariz Social Media"}, "preferred_locale"=>{"country"=>"US", "language"=>"en"}} )
+    end
+  end
+
+  it "should load historical page statistics" do
+    stub("https://api.linkedin.com/v2/organizationPageStatistics?q=organization&organization=urn:li:organization:123456")
+    expect(
+      api.organization_page_statistics(urn: "urn:li:organization:123456")
+    ).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should load historical follow statistics" do
+    stub("https://api.linkedin.com/v2/organizationalEntityFollowerStatistics?q=organizationalEntity&organizationalEntity=urn:li:organization:123456")
+    expect(
+      api.organization_follower_statistics(urn: "urn:li:organization:123456")
+    ).to be_an_instance_of(LinkedIn::Mash)
+  end
+
+  it "should load historical share statistics" do
+    stub("https://api.linkedin.com/v2/organizationalEntityShareStatistics?q=organizationalEntity&organizationalEntity=urn:li:organization:123456")
+    expect(
+      api.organization_share_statistics(urn: "urn:li:organization:123456")
+    ).to be_an_instance_of(LinkedIn::Mash)
+  end
+end

data/spec/linked_in/api/people_spec.rb

@@ -0,0 +1,191 @@
+require 'spec_helper'
+
+describe LinkedIn::People do
+  let(:uid) {"MpkAFJTlPY"}
+  let(:url) {"www.linkedin.com/in/miguel-santos-del-nariz"}
+  let(:access_token) {"AQVM91zzF-bLiOfCsTi8ktxnq99l-tW9meri8F9ZEWAuHf5g1bO_Pa4p0nFwKvZ7VFdSERAnJZq3eNOq6BzDPFNIyGIy50s-7HkLq2hE5uy6HrAQrsMAQR_qZxnBrSD11g_M2sF5XB5fUHZOXEQFgFaXB0M19VUAsvsz3yg-7zMI7w9Zn_DYTLO1e2W9VEZrOgVmRNt1XBIT_pdQO7pQkKv4702yJTrIBOuhZWNLZRClPHd2RRhPf2SJeTkodbnL4xSvzcyEPpLaTPyZIVJnBcsAzYFiG_pJtyGs7x-iWbUZsYgnUVSy8Wg-5eqmvze5tuZdICIP0PJ0AVMNGOxRRiLOEh8MSg"}
+
+  let(:api) {LinkedIn::API.new(access_token)}
+
+  def verify(result)
+    expect(result).to be_kind_of LinkedIn::Mash
+  end
+
+  ###### PROFILES
+  # Self
+  it "grabs your own profile" do
+    VCR.use_cassette("people profile own") do
+      result = api.profile
+      verify result
+      expect(result["firstName"]).to be_kind_of String
+    end
+  end
+
+  # Secure
+  it "accepts secure-urls param via secure option" do
+    VCR.use_cassette("people profile own secure") do
+      verify api.profile(secure: true)
+    end
+  end
+
+  # Language
+  it "gets profiles in a different language" do
+    VCR.use_cassette("people profile lang spanish") do
+      verify api.profile(lang: "es")
+    end
+  end
+
+  # Others
+  it "gets another users profile by user id" do
+    VCR.use_cassette("people profile other uid") do
+      result = api.profile(id: uid)
+      verify result
+      expect(result["firstName"]).to be_kind_of String
+    end
+  end
+  it "gets another users profile by url" do
+    VCR.use_cassette("people profile other url") do
+      result = api.profile(url: url)
+      verify result
+      expect(result["firstName"]).to be_kind_of String
+    end
+  end
+  it "gets another users profile by user id" do
+    VCR.use_cassette("people profile other uid") do
+      verify api.profile(uid)
+    end
+  end
+  it "gets another users profile by url" do
+    VCR.use_cassette("people profile other url") do
+      verify api.profile(url)
+    end
+  end
+
+  # Errors
+  it "errors on bad input" do
+    expect{api.profile("Bad input")}.to raise_error
+  end
+  it "errors on email deprecation" do
+    msg = LinkedIn::ErrorMessages.deprecated
+    expect{api.profile(email: "email@email.com")}.to raise_error(LinkedIn::Deprecated, msg)
+  end
+
+  # Fields
+  it "grabs certain profile fields" do
+    VCR.use_cassette("people profile fields simple") do
+      result = api.profile(fields: ["id","industry"])
+      verify result
+      expect(result["industry"]).to be_kind_of String
+    end
+  end
+  it "grabs more complex profile fields" do
+    VCR.use_cassette("people profile fields complex") do
+      result = api.profile(fields: ["id",{"positions" => ["title"]}])
+      verify result
+      expect(result["positions"]["values"][0]["title"]).to be_kind_of String
+    end
+  end
+
+  # Multiple people
+  it "grabs multiple people by uids" do
+    VCR.use_cassette("people profile multiple uids") do
+      result = api.profile(ids: ["self", uid])
+      verify result
+      expect(result["values"].length).to eq 2
+    end
+  end
+  it "grabs multiple people by urls" do
+    VCR.use_cassette("people profile multiple urls") do
+      result = api.profile(urls: ["self", url])
+      verify result
+      expect(result["values"].length).to eq 2
+    end
+  end
+  it "grabs multiple people by uids and urls" do
+    VCR.use_cassette("people profile multiple uids and urls") do
+      result = api.profile(ids: ["self", uid], urls: [url])
+      verify result
+      expect(result["values"].length).to eq 3
+    end
+  end
+  it "grabs certain fields for multiple people" do
+    VCR.use_cassette("people profile multiple fields") do
+      result = api.profile(ids: ["self", uid], fields: ["id", "industry"])
+      verify result
+      expect(result["values"][0]["industry"]).to be_kind_of String
+    end
+  end
+
+  ###### CONNECTIONS
+  it "grabs your own connections" do
+    VCR.use_cassette("people profile connections self") do
+      result = api.connections
+      verify result
+      expect(result["values"].length).to eq 3
+    end
+  end
+  it "grabs the connections of others" do
+    VCR.use_cassette("people profile connections other") do
+      result = api.connections(id: uid)
+      verify result
+      expect(result["values"].length).to eq 3
+    end
+  end
+  it "grabs certain fields for those connections" do
+    VCR.use_cassette("people profile connections fields") do
+      result = api.connections(fields: ["id", "industry"])
+      verify result
+      expect(result["values"].length).to eq 4
+      expect(result["values"][0]["industry"]).to be_kind_of String
+    end
+  end
+
+  it "grabs new connections since a string date" do
+    VCR.use_cassette("people profile new connections self") do
+      result = api.new_connections("2014-01-01")
+      verify result
+      expect(result["values"].length).to eq 2
+    end
+  end
+  it "grabs new connections since a numeric date" do
+    VCR.use_cassette("people profile new connections self") do
+      verify api.new_connections(1388534400000)
+    end
+  end
+  it "grabs new connections since a Time.utc object" do
+    VCR.use_cassette("people profile new connections self") do
+      verify api.new_connections(Time.utc(2014,1,1))
+    end
+  end
+  it "grabs new connections for another user" do
+    VCR.use_cassette("people profile new connections other") do
+      result = api.new_connections("2014-01-01", id: uid)
+      verify result
+      expect(result["values"].length).to eq 2
+    end
+  end
+  it "grabs certain fields of new connections" do
+    VCR.use_cassette("people profile new connections fields") do
+      result = api.new_connections("2014-01-01", fields: ["id", "industry"])
+      verify result
+      expect(result["values"].length).to eq 3
+      expect(result["values"][0]["industry"]).to be_kind_of String
+    end
+  end
+
+  it "grabs picture urls" do
+    VCR.use_cassette("people picture urls") do
+      result = api.picture_urls
+      verify result
+      expect(result["values"][0] =~ URI::regexp).to_not be_nil
+    end
+  end
+
+  it "grabs skills" do
+    VCR.use_cassette("people profile skills") do
+      result = api.skills
+      verify result
+      expect(result["all"].length).to eq 2
+    end
+  end  
+end