linkedin 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: beb262e6873736feb890b56c140f682c80beb36f
-  data.tar.gz: 8e1878a8f048e6807c3c3470aa9e9cc391ba4354
+  metadata.gz: 4586ae7fcf4a2d1ed3767ba0f9f086366394f6b0
+  data.tar.gz: 7d56220662ae630e2aebc568348ae46fd073b354
 SHA512:
-  metadata.gz: 4de393817404a35a883e2987ef686e2763a5b9c0d684998aff0c66a28e988dde4da3513889fa6de8bed23562abd2e9a32851d8a6fedb6967d5027d2442c28f6d
-  data.tar.gz: 8b22d8d9eff024281c1a8c388ecabe73e436f3ed80806694113890d319c72c206d3f58ad8a831e37d88e856490bdccf00f8f5d3365f65d2787e1adb998619be3
+  metadata.gz: fc14611de8a4c196203fd8300e1af097067172b463d919102d635ffb24f27a7b8b5e787530a0ca0e5b2669dae1be632e116097d7691b03ff3964952750dcaf41
+  data.tar.gz: 1a74bf22abe4fb30e037aeb004d3528965ed9050ab8bd416079cd1640223461a4bbc19c6c92172f2fd83068fbcf008111e7ac416bb02b3bba7983a1b86febdc4

data/.travis.yml

@@ -2,6 +2,5 @@ rvm:
   - 2.0.0
   - 2.1.0
   - 1.9.3
-  - jruby-18mode
   - jruby-19mode
   - rbx

data/.yardopts

@@ -0,0 +1,7 @@
+--no-private
+--markup markdown
+-
+README.md
+CHANGELOG.md
+LICENSE
+EXAMPLES.md

data/{changelog.markdown → CHANGELOG.md}

@@ -1,5 +1,9 @@
 # Changelog
 
+* Document all methods
+* Re-organize modules under Api to match organization in LinkedIn's REST
+  API documentation
+
 ## 0.4.4 - Jan 11, 2014
 
 * Group share add
@@ -92,4 +96,4 @@
 
 ## 0.0.1 - November 24, 2009
 
-* Initial release
+* Initial release

data/EXAMPLES.md

@@ -0,0 +1,199 @@
+# Linkedin Gem Examples
+
+## OAuth 1.0a Authentication
+
+Here's an example of authenticating with the LinkedIn API
+
+```ruby
+require 'rubygems'
+require 'linkedin'
+
+# get your api keys at https://www.linkedin.com/secure/developer
+client = LinkedIn::Client.new('your_consumer_key', 'your_consumer_secret')
+
+# If you want to use one of the scopes from linkedin you have to pass it in at this point
+# You can learn more about it here: http://developer.linkedin.com/documents/authentication
+request_token = client.request_token({}, :scope => "r_basicprofile+r_emailaddress")
+
+rtoken = request_token.token
+rsecret = request_token.secret
+
+# to test from your desktop, open the following url in your browser
+# and record the pin it gives you
+request_token.authorize_url
+=> "https://api.linkedin.com/uas/oauth/authorize?oauth_token=<generated_token>"
+
+# then fetch your access keys
+client.authorize_from_request(rtoken, rsecret, pin)
+=> ["OU812", "8675309"] # <= save these for future requests
+
+# or authorize from previously fetched access keys
+client.authorize_from_access("OU812", "8675309")
+
+# you're now free to move about the cabin, call any API method
+```
+
+
+## Profile
+
+Here are some examples of accessing a user's profile
+
+```ruby
+# AUTHENTICATE FIRST found in examples/authenticate.rb
+
+# client is a LinkedIn::Client
+
+# get the profile for the authenticated user
+client.profile
+
+# get a profile for someone found in network via ID
+client.profile(:id => 'gNma67_AdI')
+
+# get a profile for someone via their public profile url
+client.profile(:url => 'http://www.linkedin.com/in/netherland')
+
+# provides the ability to access authenticated user's company field in the profile
+user = client.profile(:fields => %w(positions))
+companies = user.positions.all.map{|t| t.company}
+# Example: most recent company can be accessed via companies[0]
+
+# Example of a multi-email search against the special email search API
+account_exists = client.profile(:email => 'email=yy@zz.com,email=xx@yy.com', :fields => ['id'])
+```
+
+
+## Sending a Message
+
+Here's an example of sending a message to two recipients
+
+```ruby
+# AUTHENTICATE FIRST found in examples/authenticate.md
+
+# client is a LinkedIn::Client
+
+# send a message to a person in your network. you will need to authenticate the 
+# user and ask for the "w_messages" permission.
+response = client.send_message("subject", "body", ["person_1_id", "person_2_id"])
+```
+
+
+## User's Network
+
+Here are some examples of accessing network updates and connections of
+the authenticated user
+
+``` ruby
+# AUTHENTICATE FIRST found in examples/authenticate.rb
+
+# client is a LinkedIn::Client
+
+# get network updates for the authenticated user
+client.network_updates
+
+# get profile picture changes
+client.network_updates(:type => 'PICT')
+
+# view connections for the currently authenticated user
+client.connections
+```
+# get the original picture-url for one of the connections
+client.picture_urls(:id => 'id_of_connection')
+
+## Update User's Status
+
+Here's an example of updating the current user's status
+
+```ruby
+# AUTHENTICATE FIRST found in examples/authenticate.rb
+
+# client is a LinkedIn::Client
+
+# update status for the authenticated user
+client.add_share(:comment => 'is playing with the LinkedIn Ruby gem')
+```
+
+
+## Sinatra App
+
+Here's an example sinatra application that performs authentication,
+after which some info about the authenticated user can be retrieved.
+
+```ruby
+require "rubygems"
+require "haml"
+require "sinatra"
+require "linkedin"
+
+enable :sessions
+
+helpers do
+  def login?
+    !session[:atoken].nil?
+  end
+  
+  def profile
+    linkedin_client.profile unless session[:atoken].nil?
+  end
+  
+  def connections
+    linkedin_client.connections unless session[:atoken].nil?
+  end
+  
+  private
+  def linkedin_client
+    client = LinkedIn::Client.new(settings.api, settings.secret)
+    client.authorize_from_access(session[:atoken], session[:asecret])
+    client
+  end 
+  
+end
+
+configure do
+  # get your api keys at https://www.linkedin.com/secure/developer
+  set :api, "your_api_key"
+  set :secret, "your_secret"
+end
+
+get "/" do
+  haml :index
+end
+
+get "/auth" do
+  client = LinkedIn::Client.new(settings.api, settings.secret)
+  request_token = client.request_token(:oauth_callback => "http://#{request.host}:#{request.port}/auth/callback")
+  session[:rtoken] = request_token.token
+  session[:rsecret] = request_token.secret
+
+  redirect client.request_token.authorize_url
+end
+
+get "/auth/logout" do
+   session[:atoken] = nil
+   redirect "/"
+end
+
+get "/auth/callback" do
+  client = LinkedIn::Client.new(settings.api, settings.secret)
+  if session[:atoken].nil?
+    pin = params[:oauth_verifier]
+    atoken, asecret = client.authorize_from_request(session[:rtoken], session[:rsecret], pin)
+    session[:atoken] = atoken
+    session[:asecret] = asecret    
+  end
+  redirect "/"
+end
+
+
+__END__
+@@index
+-if login?
+  %p Welcome #{profile.first_name}!
+  %a{:href => "/auth/logout"} Logout
+  %p= profile.headline
+  %br
+  %div= "You have #{connections.total} connections!"
+  -connections.all.each do |c|
+    %div= "#{c.first_name} #{c.last_name} - #{c.headline}"
+-else
+  %a{:href => "/auth"} Login using LinkedIn
+```

data/Gemfile

@@ -4,4 +4,8 @@ platforms :jruby do
   gem 'jruby-openssl', '~> 0.7'
 end
 
+platforms :rbx do
+  gem 'rubysl'
+end
+
 gemspec

data/README.md

@@ -0,0 +1,43 @@
+# LinkedIn
+
+Ruby wrapper for the [LinkedIn API](http://developer.linkedin.com). The LinkedIn gem provides an easy-to-use wrapper for LinkedIn's REST APIs.
+
+Travis CI : [![Build Status](https://secure.travis-ci.org/hexgnu/linkedin.png)](http://travis-ci.org/hexgnu/linkedin)
+
+## Installation
+
+    gem install linkedin
+
+## Documentation
+
+[http://rdoc.info/gems/linkedin](http://rdoc.info/gems/linkedin)
+
+## Usage
+
+[View the Examples](EXAMPLES.md)
+
+## Changelog
+
+[View the Changelog](CHANGELOG.md)
+
+## TODO
+
+* Update and correct test suite
+* Change to Faraday for authentication
+* Implement Messaging APIs
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Make sure your test doesn't just check of instance of LinkedIn::Mash :smile:.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+   bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2013-Present [Matt Kirk](http://matthewkirk.com) 2009-11 [Wynn Netherland](http://wynnnetherland.com). See LICENSE for details.

data/Rakefile

@@ -10,11 +10,6 @@ task :test => :spec
 task :default => :spec
 load 'vcr/tasks/vcr.rake'
 
-require 'rdoc/task'
 require File.expand_path('../lib/linked_in/version', __FILE__)
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "linkedin #{LinkedIn::VERSION::STRING}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/linked_in/api.rb

@@ -1,6 +1,38 @@
 module LinkedIn
   module Api
-    autoload :QueryMethods,  "linked_in/api/query_methods"
-    autoload :UpdateMethods, "linked_in/api/update_methods"
+
+    # @!macro person_path_options
+    #  @param [Hash] options identifies the user profile you want
+    #  @option options [String] :id a member token
+    #  @option options [String] :url a Public Profile URL
+    #  @option options [String] :email
+
+    # @!macro company_path_options
+    #  @param [Hash] options identifies the user profile you want
+    #  @option options [String] :domain company email domain
+    #  @option options [String] :id company ID
+    #  @option options [String] :url
+    #  @option options [String] :name company universal name
+    #  @option options [String] :is_admin list all companies that the
+    #   authenticated is an administrator of
+
+    # @!macro share_input_fields
+    #  @param [Hash] share content of the share
+    #  @option share [String] :comment
+    #  @option share [String] :content
+    #  @option share [String] :title
+    #  @option share [String] :submitted-url
+    #  @option share [String] :submitted-image-url
+    #  @option share [String] :description
+    #  @option share [String] :visibility
+    #  @option share [String] :code
+
+    autoload :QueryHelpers,  "linked_in/api/query_helpers"
+    autoload :People,  "linked_in/api/people"
+    autoload :Groups,  "linked_in/api/groups"
+    autoload :Companies,  "linked_in/api/companies"
+    autoload :Jobs,  "linked_in/api/jobs"
+    autoload :ShareAndSocialStream,  "linked_in/api/share_and_social_stream"
+    autoload :Communications, "linked_in/api/communications"
   end
 end

data/lib/linked_in/api/communications.rb

@@ -0,0 +1,44 @@
+module LinkedIn
+  module Api
+
+    # Communications APIs
+    #
+    # @see http://developer.linkedin.com/documents/communications
+    module Communications
+
+      # (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
+      #   client.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
+end

data/lib/linked_in/api/companies.rb

@@ -0,0 +1,128 @@
+module LinkedIn
+  module Api
+
+    # Companies API
+    #
+    # @see http://developer.linkedin.com/documents/companies Companies API
+    # @see http://developer.linkedin.com/documents/company-lookup-api-and-fields Company Fields
+    #
+    # The following API actions do not have corresponding methods in
+    # this module
+    #
+    #   * Permissions Checking Endpoints for Company Shares
+    #   * GET Suggested Companies to Follow
+    #   * GET Company Products
+    #
+    # [(contribute here)](https://github.com/hexgnu/linkedin)
+    module Companies
+
+      # Retrieve a Company Profile
+      #
+      # @see http://developer.linkedin.com/documents/company-lookup-api-and-fields
+      #
+      # @macro company_path_options
+      # @option options [String] :scope
+      # @option options [String] :type
+      # @option options [String] :count
+      # @option options [String] :start
+      # @return [LinkedIn::Mash]
+      def company(options = {})
+        path   = company_path(options)
+        simple_query(path, options)
+      end
+
+      # Retrieve a feed of event items for a Company
+      #
+      # @see http://developer.linkedin.com/reading-company-shares
+      #
+      # @macro company_path_options
+      # @option options [String] :event-type
+      # @option options [String] :count
+      # @option options [String] :start
+      # @return [LinkedIn::Mash]
+      def company_updates(options={})
+        path = "#{company_path(options)}/updates"
+        simple_query(path, options)
+      end
+
+      # Retrieve statistics for a particular company page
+      #
+      # Permissions: rw_company_admin
+      #
+      # @see http://developer.linkedin.com/documents/company-statistics
+      #
+      # @macro company_path_options
+      # @return [LinkedIn::Mash]
+      def company_statistics(options={})
+        path = "#{company_path(options)}/company-statistics"
+        simple_query(path, options)
+      end
+
+      # Retrieve comments on a particular company update:
+      #
+      # @see http://developer.linkedin.com/reading-company-shares
+      #
+      # @param [String] update_key a update/update-key representing a
+      #   particular company update
+      # @macro company_path_options
+      # @return [LinkedIn::Mash]
+      def company_updates_comments(update_key, options={})
+        path = "#{company_path(options)}/updates/key=#{update_key}/update-comments"
+        simple_query(path, options)
+      end
+
+      # Retrieve likes on a particular company update:
+      #
+      # @see http://developer.linkedin.com/reading-company-shares
+      #
+      # @param [String] update_key a update/update-key representing a
+      #   particular company update
+      # @macro company_path_options
+      # @return [LinkedIn::Mash]
+      def company_updates_likes(update_key, options={})
+        path = "#{company_path(options)}/updates/key=#{update_key}/likes"
+        simple_query(path, options)
+      end
+
+      # Create a share for a company that the authenticated user
+      # administers
+      #
+      # Permissions: rw_company_admin
+      #
+      # @see http://developer.linkedin.com/creating-company-shares
+      # @see http://developer.linkedin.com/documents/targeting-company-shares Targeting Company Shares
+      #
+      # @param [String] company_id Company ID
+      # @macro share_input_fields
+      # @return [void]
+      def add_company_share(company_id, share)
+        path = "/companies/#{company_id}/shares"
+        defaults = {:visibility => {:code => "anyone"}}
+        post(path, MultiJson.dump(defaults.merge(share)), "Content-Type" => "application/json")
+      end
+
+      # (Create) authenticated user starts following a company
+      #
+      # @see http://developer.linkedin.com/documents/company-follow-and-suggestions
+      #
+      # @param [String] company_id Company ID
+      # @return [void]
+      def follow_company(company_id)
+        path = "/people/~/following/companies"
+        body = {:id => company_id }
+        post(path, MultiJson.dump(body), "Content-Type" => "application/json")
+      end
+
+      # (Destroy) authenticated user stops following a company
+      #
+      # @see http://developer.linkedin.com/documents/company-follow-and-suggestions
+      #
+      # @param [String] company_id Company ID
+      # @return [void]
+      def unfollow_company(company_id)
+        path = "/people/~/following/companies/id=#{company_id}"
+        delete(path)
+      end
+    end
+  end
+end