linkedin_orbit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fff300ca5f8ea75c7c1105279561dd768a90838a148eb0ea43b086aecb17e0ed
-  data.tar.gz: 6a74e4317caacae6034a574fec736c4ea185559b2b3f6ef3512def8b73fe61c9
+  metadata.gz: 72da0485d3741083f4f16250d750ecbae919d67a54a5aca51d8a00d73d8a0719
+  data.tar.gz: 88b8658762763e70dd9a3bec29d040ec025b5ff6d6ad31f1ce89f30bd58ac95b
 SHA512:
-  metadata.gz: 7d1b4860f81499d513e33857556686aea179b47052e0a04fe567b6298d1cda21493bf91c5f9ea4e3d3122b1f9d50149a8477ab6cb2d9d3e02bade259852db6af
-  data.tar.gz: 4749a5b174ded3352409a89f46d1dd249c534e9d3d8acf4fc1ac04442d1ea51321e0f74399287ec445a3c1561c0be280d5221605c0f4dd54e1e101f443311fa7
+  metadata.gz: 05ddc9104e36e1a798640ec2ec275c68aed856108f17ad200aed418610fb6b7b2b72ac394fca1fc54b4b317aae3d6892bf63c10b7a8ef4e263dd1116ead8ab39
+  data.tar.gz: ab9e3c2911639813bc048005b02998f3f5102c17a1a7675c3f701fd192c0bc78c1477ad85f527004bd137afe3c88346750c0696be0d77809fe04b8fb7801808c

data/Gemfile

@@ -8,4 +8,6 @@ gem "rake", "~> 13.0"
 
 gem "rubocop", "~> 1.7"
 
+gem "orbit_activities"
+
 gem "byebug"

data/Gemfile.lock

@@ -1,18 +1,19 @@
 PATH
   remote: .
   specs:
-    linkedin_orbit (0.0.2)
+    linkedin_orbit (0.1.4)
       dotenv (~> 2.7)
       http (~> 4.4)
       json (~> 2.5)
       linkedin (~> 1.1)
+      orbit_activities (~> 0.2)
       thor (~> 1.1)
       zeitwerk (~> 2.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.2)
     byebug (11.1.3)
@@ -22,16 +23,24 @@ GEM
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
     dotenv (2.7.6)
-    faraday (1.4.1)
+    faraday (1.5.0)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0.1)
       faraday-net_http (~> 1.0)
       faraday-net_http_persistent (~> 1.1)
+      faraday-patron (~> 1.0)
       multipart-post (>= 1.2, < 3)
       ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
     faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
     faraday-net_http (1.0.1)
     faraday-net_http_persistent (1.1.0)
-    ffi (1.15.0)
+    faraday-patron (1.0.0)
+    ffi (1.15.3)
     ffi-compiler (1.0.1)
       ffi (>= 1.0.0)
       rake
@@ -42,7 +51,7 @@ GEM
       http-cookie (~> 1.0)
       http-form_data (~> 2.2)
       http-parser (~> 1.2.0)
-    http-cookie (1.0.3)
+    http-cookie (1.0.4)
       domain_name (~> 0.5)
     http-form_data (2.3.0)
     http-parser (1.2.3)
@@ -62,6 +71,11 @@ GEM
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
+    orbit_activities (0.2.2)
+      http (~> 4.4)
+      json (~> 2.5)
+      rake (~> 13.0)
+      zeitwerk (~> 2.4)
     parallel (1.20.1)
     parser (3.0.1.1)
       ast (~> 2.4.1)
@@ -84,16 +98,16 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
-    rubocop (1.14.0)
+    rubocop (1.18.2)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.5.0, < 2.0)
+      rubocop-ast (>= 1.7.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.5.0)
+    rubocop-ast (1.7.0)
       parser (>= 3.0.1.1)
     ruby-progressbar (1.11.0)
     ruby2_keywords (0.0.4)
@@ -102,7 +116,7 @@ GEM
       unf_ext
     unf_ext (0.0.7.7)
     unicode-display_width (2.0.0)
-    webmock (3.12.0)
+    webmock (3.13.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
@@ -115,6 +129,7 @@ PLATFORMS
 DEPENDENCIES
   byebug
   linkedin_orbit!
+  orbit_activities
   rake (~> 13.0)
   rspec (~> 3.4)
   rubocop (~> 1.7)

data/README.md

@@ -4,7 +4,9 @@
 [![Gem Version](https://badge.fury.io/rb/linkedin_orbit.svg)](https://badge.fury.io/rb/dev_orbit)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](code_of_conduct.md)
 
-This is a Ruby app that can be used to integrate LinkedIn post comments into your organization's Orbit workspace.
+Add your LinkedIn interactions into your Orbit workspace with this community-built integration.
+
+![New LinkedIn post comment in Orbit screenshot](readme_images/new-comment-screenshot.png)
 
 |<p align="left">:sparkles:</p> This is a *community project*. The Orbit team does its best to maintain it and keep it up to date with any recent API changes.<br/><br/>We welcome community contributions to make sure that it stays current. <p align="right">:sparkles:</p>|
 |-----------------------------------------|
@@ -21,7 +23,7 @@ The application requires the following environment variables:
 | Variable | Description | More Info
 |---|---|--|
 | `LINKEDIN_TOKEN` | LinkedIn Token | Follow the [First Time Setup guide](docs/FIRST_TIME_INSTRUCTIONS.md) to obtain the token
-| `LINKEDIN_ORGANIZATION` | LinkedIn Organization Page ID | Format: `urn:li:organization:#{id}`. ID is the set of numbers in LinkedIn page URL, i.e. `https://www.linkedin.com/company/28866695`, the ID is `28866695`.
+| `LINKEDIN_ORGANIZATION` | LinkedIn Organization Page ID | Format: `urn:li:organization:#{id}`, where `id` is the set of numbers in the LinkedIn page URL, i.e. `https://www.linkedin.com/company/28866695`, the `id` is `28866695`.
 | `ORBIT_API_KEY` | API key for Orbit | Found in `Account Settings` in your Orbit workspace
 | `ORBIT_WORKSPACE_ID` | ID for your Orbit workspace | Last part of the Orbit workspace URL, i.e. `https://app.orbit.love/my-workspace`, the ID is `my-workspace`
 
@@ -54,8 +56,20 @@ client = LinkedinOrbit::Client.new(
 client = LinkedinOrbit::Client.new
 ```
 
+### Performing a Historical Import
+
+You may want to perform a one-time historical import to fetch all your previous LinkedIn interactions and bring them into your Orbit workspace. To do so, instantiate your `client` with the `historical_import` flag:
+
+```ruby
+client = LinkedinOrbit::Client.new(
+  historical_import: true
+)
+```
+
 ### Fetching LinkedIn Comments
 
+**The API token owner must be an admin on the LinkedIn organization's page in order to fetch comments. Please ask the manager of your LinkedIn page to grant admin status to your account before attempting to fetch comments.**
+
 Once, you have an instantiated client, you can fetch LinkedIn comments on your organization's posts and send them to Orbit by invoking the `#comments` instance method:
 
 ```ruby
@@ -68,6 +82,8 @@ You can also use this package with the included CLI. To use the CLI pass in the
 ```bash
 $ ORBIT_API_KEY=... ORBIT_WORKSPACE_ID=... LINKEDIN_TOKEN=... LINKEDIN_ORGANIZATION=... bundle exec linkedin_orbit --check_comments
 ```
+
+**Add the `--historical-import` flag to your CLI command to perform a historical import of all your LinkedIn interactions using the CLI.**
 ## GitHub Actions Automation Setup
 
 ⚡ You can set up this integration in a matter of minutes using our GitHub Actions template. It will run regularly to add new activities to your Orbit workspace. All you need is a GitHub account.

data/bin/linkedin_orbit

@@ -2,6 +2,7 @@
 require 'optparse'
 
 check_comments = false
+historical_import = false
 
 options = {}
 choices = OptionParser.new do |opts|
@@ -13,6 +14,9 @@ choices = OptionParser.new do |opts|
   opts.on("--check-comments", "Check for new LinkedIn comments") do
     check_comments = true
   end
+  opts.on("--historical-import", "Performa historical import of all LinkedIn interactions") do
+    historical_import = true
+  end
 end.parse!
 
 $LOAD_PATH.unshift(File.expand_path('../lib/dev_orbit', __dir__))
@@ -23,5 +27,6 @@ require_relative '../scripts/check_comments'
 if check_comments
   puts "Checking for new LinkedIn comments and posting them to your Orbit workspace..."
   ARGV[0] = 'render'
+  ARGV[1] = historical_import
   LinkedinOrbit::Scripts::CheckComments.start(ARGV)
 end

data/docs/FIRST_TIME_INSTRUCTIONS.md

@@ -1,8 +1,17 @@
 # Instructions for First Time Set Up
 
-These instructions will walk you through authenticating to LinkedIn, and receiving your LinkedIn token, which is needed to use this integration. You will only need to do this once every two months.
+|These instructions will walk you through authenticating to LinkedIn, and receiving your LinkedIn token, which is needed to use this integration. You will only need to do this once every two months.|
+|-----------------------------------------|
 
-## Creating a LinkedIn Developers App
+![Setup Flow for LinkedIn](../readme_images/linkedin-flow.png)
+
+## 1. Before You Start
+
+LinkedIn requires that the personal account (your LinkedIn account) requesting API access for an organization or company on LinkedIn be an admin of the organization or company's LinkedIn page. 
+
+Please verify that you have administrative privileges for the organization LinkedIn page. If you do not, your organization's administrator can grant your account the correct access level. 
+## 2. LinkedIn Setup
+### Creating a LinkedIn Developers App
 
 The first thing you must do is create a LinkedIn Developers app.
 
@@ -21,7 +30,7 @@ Once you submit the form, it usually takes 3-4 days for LinkedIn to confirm the
 
 While you wait for verification, you can do the next step, which is to request the right API scope from LinkedIn.
 
-## Requesting the LinkedIn Marketing Developer Platform API Access
+### Requesting the LinkedIn Marketing Developer Platform API Access
 
 LinkedIn has many different types of APIs and many different types of access levels to those APIs. The API your app needs access to is the **Marketing Developer Platform**.
 
@@ -33,7 +42,17 @@ This will take another few days for LinkedIn to verify and confirm this request.
 
 ![LinkedIn Developer Products List](../readme_images/products_list.png)
 
-## LinkedIn API Credentials
+## 3. Wait for LinkedIn
+
+At this point, you need to wait for LinkedIn to approve both your new developer application, and access to the Marketing Developer Platform API. This generally takes several days. LinkedIn will both email you with an update, and post an update inside the [LinkedIn Developers](https://www.linkedin.com/developers) page. 
+
+If your request is denied access, you can submit an appeal to LinkedIn. The appeal process can take several days again. Pay close attention to the specified reason LinkedIn provided for the initial rejection, and work to remedy it before submitting an appeal.
+
+The Orbit Developer Relations team unfortunately cannot assist or address LinkedIn API approval processes.
+
+## 4. Integration Setup
+
+### LinkedIn API Credentials
 
 You will need your LinkedIn API credentials to move forward. You can copy your LinkedIn credentials, which are your Client ID and Client Secret from the "Auth" section in the LinkedIn Developers dashboard.
 
@@ -45,7 +64,9 @@ You will also see on the "Auth" page a section called "OAuth 2.0 Settings". We w
 
 After you have finished all of the above steps, you are ready to move on to the last step in this first time setup instructions.
 
-## LinkedIn Token
+### LinkedIn Token
+
+**Do not proceed to this step until you have received approval from LinkedIn for your API access request. This next step will not work until that has happened.**
 
 LinkedIn uses OAuth 2.0 as its authentication format, and as such, you need to authenticate *one time every two months* to obtain a token that will be used for the integration from then on. 
 
@@ -73,14 +94,14 @@ Now, return back to your browser window with your Heroku app running. Click on t
 
 The last step you need to complete in this first time setup is to add the LinkedIn token you created into the LinkedIn Orbit community integration credentials, either in the context of a standalone app or in the context of running it as a GitHub Action.
 
-## Add the LinkedIn Token to the LinkedIn Orbit Community Integration
-### Within GitHub Actions
+### Add the LinkedIn Token to the LinkedIn Orbit Community Integration
+#### Within GitHub Actions
 
 *(This step assumes you have a GitHub repository created already to run the LinkedIn Orbit community integration. If you do not, please follow [this guide](https://docs.github.com/en/github/getting-started-with-github/create-a-repo) first.)*
 
 The LinkedIn token you created in the last step needs to be added to the GitHub repository that you are running the LinkedIn Orbit community integration from. To do so, follow the step-by-step guide in the [README](https://github.com/orbit-love/github-actions-templates/blob/main/README.md#adding-your-credentials-to-github) in the GitHub Actions instructions. The name for this secret **must** be: `LINKEDIN_TOKEN`.
 
-### Within a Standalone App
+#### Within a Standalone App
 
 If you are running the community integration as a standalone app, you can add the LinkedIn token as an environment variable inside the `.env` file in the root directory of the codebase.
 
@@ -89,6 +110,6 @@ Open up the `.env` file and add a new line starting with `LINKEDIN_TOKEN=` and a
 
 You have now successfully finished the setup for your LinkedIn Orbit community integration. This steps needs to occur once every 60 days.
 
-In between, you can safely delete the Heroku app you created and recreate a new one when you need to do this again.
+In between, you should delete the Heroku app you created and recreate a new one when you need to do this again as keeping it alive potentially exposes your LinkedIn token to those who may come across it.
 
 From within the Heroku dashboard, navigate to the "Settings" for the app and at the very bottom of the page is a button called "Delete app". Once you click on that button, Heroku will confirm you wish to delete the app. Upon confirmation, the app will be deleted and the deployment on the web will be removed.

data/lib/linkedin_orbit.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
+require "orbit_activities"
+require_relative "linkedin_orbit/version"
 
 module LinkedinOrbit
   loader = Zeitwerk::Loader.new

data/lib/linkedin_orbit/client.rb

@@ -29,13 +29,18 @@ require "json"
 #   The LinkedIn organization would use the last component of that web address and would be:
 #   urn:li:organization:28866695
 #
+# @option params [Boolean] :historical_import
+#   Whether to do an import of all LinkedIn interactions ignoring latest
+#   activity already in the Orbit workspace.
+#   Default is false.
+#
 # @param [Hash] params
 #
 # @return [DevOrbit::Client]
 #
 module LinkedinOrbit
   class Client
-    attr_accessor :orbit_api_key, :orbit_workspace, :linkedin_organization
+    attr_accessor :orbit_api_key, :orbit_workspace, :linkedin_organization, :historical_import
     attr_reader :linkedin_token
 
     def initialize(params = {})
@@ -43,6 +48,7 @@ module LinkedinOrbit
       @orbit_workspace = params.fetch(:orbit_workspace, ENV["ORBIT_WORKSPACE_ID"])
       @linkedin_token = token
       @linkedin_organization = params.fetch(:linkedin_organization, ENV["LINKEDIN_ORGANIZATION"])
+      @historical_import = params.fetch(:historical_import, false)
     end
 
     def token
@@ -54,7 +60,8 @@ module LinkedinOrbit
         linkedin_token: @linkedin_token,
         linkedin_organization: @linkedin_organization,
         orbit_api_key: @orbit_api_key,
-        orbit_workspace: @orbit_workspace
+        orbit_workspace: @orbit_workspace,
+        historical_import: @historical_import
       ).process_comments
     end
   end

data/lib/linkedin_orbit/interactions/comment.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "net/http"
 require "json"
 
 module LinkedinOrbit
@@ -16,27 +15,20 @@ module LinkedinOrbit
       end
 
       def after_initialize!
-        url = URI("https://app.orbit.love/api/v1/#{@orbit_workspace}/activities")
-
-        http = Net::HTTP.new(url.host, url.port)
-        http.use_ssl = true
-
-        request = Net::HTTP::Post.new(url)
-        request["Accept"] = "application/json"
-        request["Content-Type"] = "application/json"
-        request["Authorization"] = "Bearer #{@orbit_api_key}"
-
-        request.body = construct_body.to_json
-
-        response = http.request(request)
-
-        JSON.parse(response.body)
+        OrbitActivities::Request.new(
+          api_key: @orbit_api_key,
+          workspace_id: @orbit_workspace,
+          user_agent: "community-ruby-linkedin-orbit/#{LinkedinOrbit::VERSION}",
+          action: "new_activity",
+          body: construct_body.to_json
+        )
       end
 
       def construct_body
         {
           activity: {
             activity_type: "linkedin:comment",
+            tags: ["channel:linkedin"],
             title: "Commented on LinkedIn Post",
             description: construct_description,
             occurred_at: Time.at(@comment["created"]["time"] / 1000).utc,

data/lib/linkedin_orbit/linkedin.rb

@@ -7,12 +7,19 @@ module LinkedinOrbit
       @linkedin_token = params.fetch(:linkedin_token)
       @orbit_api_key = params.fetch(:orbit_api_key)
       @orbit_workspace = params.fetch(:orbit_workspace)
+      @historical_import = params.fetch(:historical_import, false)
     end
 
     def process_comments
       posts = get_posts
 
+      return posts unless posts.is_a?(Array)
+
+      orbit_timestamp = last_orbit_activity_timestamp
+      
       posts.each do |post|
+        times = 0
+
         comments = get_post_comments(post["id"])
 
         comments.reject! { |comment| comment["actor~"]["id"] == "private" }
@@ -20,6 +27,16 @@ module LinkedinOrbit
         next if comments.nil? || comments.empty?
 
         comments.each do |comment|
+          unless @historical_import && orbit_timestamp
+            next if Time.at(comment["created"]["time"] / 1000).utc.to_s < orbit_timestamp unless orbit_timestamp.nil?
+          end
+
+          if orbit_timestamp && @historical_import == false
+            next if Time.at(comment["created"]["time"] / 1000).utc.to_s < orbit_timestamp
+          end
+
+          times += 1
+
           LinkedinOrbit::Orbit.call(
             type: "comments",
             data: {
@@ -30,6 +47,11 @@ module LinkedinOrbit
             orbit_api_key: @orbit_api_key
           )
         end
+
+        output = "Sent #{times} new comments to your Orbit workspace"
+
+        puts output
+        return output
       end
     end
 
@@ -47,7 +69,16 @@ module LinkedinOrbit
       response = https.request(request)
 
       response = JSON.parse(response.body)
-      
+
+      return response["message"] if response["serviceErrorCode"]
+
+      if response["elements"].nil? || response["elements"].empty?
+        return <<~HEREDOC
+          No new posts to process from your LinkedIn organization.
+          If you suspect this is incorrect, verify your LinkedIn organization schema is correct in your credentials.
+        HEREDOC
+      end
+
       response["elements"].each do |element|
         posts << {
           "id" => element["activity"],
@@ -74,5 +105,17 @@ module LinkedinOrbit
 
       response["elements"]
     end
+
+    def last_orbit_activity_timestamp
+      @last_orbit_activity_timestamp ||= begin
+        OrbitActivities::Request.new(
+          api_key: @orbit_api_key,
+          workspace_id: @orbit_workspace,
+          user_agent: "community-ruby-linkedin-orbit/#{LinkedinOrbit::VERSION}",
+          action: "latest_activity_timestamp",
+          filters: { activity_type: "custom:linkedin:comment" }
+        ).response
+      end
+    end
   end
 end

data/lib/linkedin_orbit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LinkedinOrbit
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end

data/linkedin_orbit.gemspec

@@ -32,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "thor", "~> 1.1"
   spec.add_dependency "linkedin", "~> 1.1"
   spec.add_dependency "dotenv", "~> 2.7"
+  spec.add_dependency "orbit_activities", "~> 0.2"
   spec.add_development_dependency "rspec", "~> 3.4"
   spec.add_development_dependency "webmock", "~> 3.12"
 end

data/scripts/check_comments.rb

@@ -1,15 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "dev_orbit"
+require "linkedin_orbit"
 require "thor"
 
 module LinkedinOrbit
   module Scripts
     class CheckComments < Thor
       desc "render", "check for new LinkedIn post comments and push them to Orbit"
-      def render
-        client = LinkedinOrbit::Client.new
+      def render(*params)
+        client = LinkedinOrbit::Client.new(historical_import: params[0])
         client.comments
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linkedin_orbit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Orbit DevRel
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-11 00:00:00.000000000 Z
+date: 2021-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -95,6 +95,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: orbit_activities
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -154,9 +168,11 @@ files:
 - readme_images/client_credentials.png
 - readme_images/create_app_button.png
 - readme_images/heroku_view_app_button.png
+- readme_images/linkedin-flow.png
 - readme_images/linkedin_oauth_redirects.png
 - readme_images/logo.png
 - readme_images/marketing_platform_request_access.png
+- readme_images/new-comment-screenshot.png
 - readme_images/products_list.png
 - readme_images/ways-to-use.png
 - scripts/check_comments.rb