Merge branch 'master' into ak/add-hard-delete-request

Author: theandrewykim

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+#### Why?
+Why are you making this change?
+
+#### How?
+Technical details on your change

.travis.yml

@@ -5,7 +5,6 @@ gemspec
 
 group :development, :test do
   platforms :jruby do
-    gem 'json-jruby'
     gem 'jruby-openssl'
   end
 end

Gemfile

@@ -22,7 +22,7 @@ This version of the gem is compatible with `Ruby 2.1` and above.
 
 Using bundler:
 
-    gem 'intercom', '~> 3.5.25'
+    gem 'intercom', '~> 3.6.2'
 
 ## Basic Usage
 
@@ -132,8 +132,10 @@ intercom.companies.save(company)
 # Iterate over all companies
 intercom.companies.all.each {|company| puts %Q(#{company.name} - #{company.custom_attributes["referral_source"]}) }
 intercom.companies.all.map {|company| company.name }
-# Get a list of users in a company
-intercom.companies.users(company.id)
+# Get a list of users in a company by Intercom Company ID
+intercom.companies.users_by_intercom_company_id(company.id)
+# Get a list of users in a company by external company_id
+intercom.companies.users_by_company_id(company.company_id) 
 # Get a large list of companies using scroll
 intercom.companies.scroll.each { |comp| puts comp.name}
 # Please see users scroll for more details of how to use scroll
@@ -149,7 +151,7 @@ intercom.tags.untag(name: 'blue',  users: [{user_id: "42ea2f1b93891f6a99000427"}
 intercom.tags.all.each {|tag| "#{tag.id} - #{tag.name}" }
 intercom.tags.all.map {|tag| tag.name }
 # Tag companies
-tag = intercom.tags.tag(name: 'blue', companies: [{id: "42ea2f1b93891f6a99000427"}])
+tag = intercom.tags.tag(name: 'blue', companies: [{company_id: "42ea2f1b93891f6a99000427"}])
 ```
 
 #### Segments
@@ -174,6 +176,9 @@ intercom.notes.find_all(user_id: '123').each {|note| puts note.body}
 
 #### Conversations
 ```ruby
+# Iterate over all conversations for your app
+intercom.conversations.all.each { |convo| ... }
+
 # FINDING CONVERSATIONS FOR AN ADMIN
 # Iterate over all conversations (open and closed) assigned to an admin
 intercom.conversations.find_all(type: 'admin', id: '7').each {|convo| ... }
@@ -191,6 +196,11 @@ intercom.conversations.find_all(email: '[email protected]', type: 'user').each {|c
 intercom.conversations.find_all(email: '[email protected]', type: 'user', unread: false).each {|convo| ... }
 # Iterate over all unread conversations with a user based on the users email
 intercom.conversations.find_all(email: '[email protected]', type: 'user', unread: true).each {|convo| ... }
+# Iterate over all conversations for a user with their Intercom user ID
+intercom.conversations.find_all(intercom_user_id: '536e564f316c83104c000020', type: 'user').each {|convo| ... }
+# Iterate over all conversations for a lead 
+# NOTE: to iterate over a lead's conversations you MUST use their Intercom User ID and type User
+intercom.conversations.find_all(intercom_user_id: lead.id, type: 'user').each {|convo| ... }
 
 # FINDING A SINGLE CONVERSATION
 conversation = intercom.conversations.find(id: '1')
@@ -218,8 +228,13 @@ intercom.conversations.open(id: conversation.id, admin_id: '123')
 intercom.conversations.close(id: conversation.id, admin_id: '123')
 
 # Assign
+# Note: Conversations can be assigned to teams. However, the entity that performs the operation of assigning the conversation has to be an existing teammate. 
+#       You can use `intercom.admins.all.each {|a| puts a.inspect if a.type == 'admin' }` to list all of your teammates.
 intercom.conversations.assign(id: conversation.id, admin_id: '123', assignee_id: '124')
 
+# Snooze
+intercom.conversations.snooze(id: conversation.id, admin_id: '123', snoozed_until: 9999999999)
+
 # Reply and Open
 intercom.conversations.reply(id: conversation.id, type: 'admin', admin_id: '123', message_type: 'open', body: 'bar')
 
@@ -357,20 +372,50 @@ The metadata key values in the example are treated as follows-
 ### Contacts
 
 `Contacts` represent logged out users of your application.
+Note that `contacts` are referred to as `leads` in the [Intercom](https://developers.intercom.com/intercom-api-reference/reference#leads)
 
 ```ruby
 # Create a contact
 contact = intercom.contacts.create(email: "[email protected]")
 
-# Update a contact
+# Update a contact (via create method)
+# You can update a contact by calling the create method but you MUST provide an id or user_id
+# If you just provide an email, for example, it will create a new contact
+# See https://developers.intercom.com/intercom-api-reference/reference#update-lead for more detail
+contact = intercom.contacts.create(email: "[email protected]", id: "3be0398668071a6bc6850413", name:"update_contact")
+
+# Update a contact (via contact object)
 contact.custom_attributes['foo'] = 'bar'
 intercom.contacts.save(contact)
 
 # Find contacts by email
 contacts = intercom.contacts.find_all(email: "[email protected]")
 
+# Using find to search for contacts by email
+contact_list = intercom.contacts.find(email: "[email protected]")
+# This returns a Contact object with type contact.list
+# Note: Multiple contacts can be returned in this list if there are multiple matching contacts found
+# #<Intercom::Contact:0x00007ff3a80789f8
+#   @changed_fields=#<Set: {}>,
+#   @contacts=
+#     [{"type"=>"contact",
+#       "id"=>"5b7fd9b683681ac52274b9c7",
+#       "user_id"=>"05bc4d17-72cc-433e-88ae-0bf88db5d0e6",
+#       "anonymous"=>true,
+#       "email"=>"[email protected]",
+#       ...}],
+#   @custom_attributes={},
+#   @limited=false,
+#   @pages=#<Intercom::Pages:0x00007ff3a7413c58 @changed_fields=#<Set: {}>, @next=nil, @page=1, @per_page=50, @total_pages=1, @type="pages">,
+#   @total_count=1,
+#   @type="contact.list">
+# Access the contact's data
+contact_list.contacts.first
+
 # Convert a contact into a user
-intercom.contacts.convert(contact, user)
+contact = intercom.contacts.find(id: "536e564f316c83104c000020")
+intercom.contacts.convert(contact, Intercom::User.new(email: email))
+# Using find with email will not work here. See https://github.com/intercom/intercom-ruby/issues/419 for more information
 
 # Delete a contact
 intercom.contacts.delete(contact)
@@ -441,7 +486,7 @@ intercom.rate_limit_details
 ```
 
 You can handle the rate limits yourself but a simple option is to use the handle_rate_limit flag.
-This will automatically catch the 429 rate limit exceeded error and wait until the reset time to retry.
+This will automatically catch the 429 rate limit exceeded error and wait until the reset time to retry. After three retries a rate limit exception will be raised. Encountering this error frequently may require a revisiting of your usage of the API.
 
 ```
 intercom = Intercom::Client.new(token: ENV['AT'], handle_rate_limit: true)

README.md

@@ -1,3 +1,30 @@
+3.6.2
+#384 Add ability to snooze conversation
+You can now snooze conversations in your app via:
+intercom.conversations.snooze(...)
+
+3.6.1
+#430 Allow all conversations to be listed
+You can now iterate over all conversations for your app via:
+intercom.conversations.all.each { |convo| ... }
+
+3.6.0
+BREAKING CHANGE companies
+We updated companies to be able to list users via company_id as well as id (#428 )
+Note that this is a breaking change as we had to remove the old way of listing users via company.
+
+Previously it was:
+intercom.companies.users(company.id)
+
+Now you get a list of users in a company by Intercom Company ID
+intercom.companies.users_by_intercom_company_id(company.id)
+
+Now you get a list of users in a company by external company_id
+intercom.companies.users_by_company_id(company.company_id)
+
+Rate limit handling
+We also improved the way we handle rate limits in PR #409 which was related to issue #405
+
 3.5.23
  - New type of error (ResourceNotUniqueError). Thrown when trying to create a resource that already exists in Intercom
 

changes.txt

@@ -25,7 +25,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "fakeweb", ["~> 1.3"]
   spec.add_development_dependency "pry"
 
-  spec.add_dependency 'json', '>= 1.8'
   spec.required_ruby_version = '>= 2.1.0'
   spec.add_development_dependency 'gem-release'
 end

intercom.gemspec

@@ -2,7 +2,7 @@ module Intercom
   class MisconfiguredClientError < StandardError; end
   class Client
     include Options
-    attr_reader :base_url, :rate_limit_details, :username_part, :password_part, :handle_rate_limit
+    attr_reader :base_url, :rate_limit_details, :username_part, :password_part, :handle_rate_limit, :timeouts
 
     class << self
       def set_base_url(base_url)
@@ -12,6 +12,17 @@ def set_base_url(base_url)
           Proc.new { |obj| set_base_url(old_url).call(o) }
         end
       end
+
+      def set_timeouts(open_timeout: nil, read_timeout: nil)
+        return Proc.new do |o|
+          old_timeouts = o.timeouts
+          timeouts = {}
+          timeouts[:open_timeout] = open_timeout if open_timeout
+          timeouts[:read_timeout] = read_timeout if read_timeout
+          o.send(:timeouts=, timeouts)
+          Proc.new { |obj| set_timeouts(old_timeouts).call(o) }
+        end
+      end
     end
 
     def initialize(app_id: 'my_app_id', api_key: 'my_api_key', token: nil, base_url:'https://api.intercom.io', handle_rate_limit: false)
@@ -27,6 +38,10 @@ def initialize(app_id: 'my_app_id', api_key: 'my_api_key', token: nil, base_url:
       @base_url = base_url
       @rate_limit_details = {}
       @handle_rate_limit = handle_rate_limit
+      @timeouts = {
+        open_timeout: 30,
+        read_timeout: 90
+      }
     end
 
     def admins
@@ -110,13 +125,17 @@ def validate_credentials!
 
     def execute_request(request)
       request.handle_rate_limit = handle_rate_limit
-      request.execute(@base_url, username: @username_part, secret: @password_part)
+      request.execute(@base_url, username: @username_part, secret: @password_part, **timeouts)
     ensure
       @rate_limit_details = request.rate_limit_details
     end
 
     def base_url=(new_url)
       @base_url = new_url
     end
+
+    def timeouts=(timeouts)
+      @timeouts = @timeouts.merge(timeouts)
+    end
   end
 end

lib/intercom/client.rb

@@ -46,25 +46,25 @@ def self.default_headers
       {'Accept-Encoding' => 'gzip, deflate', 'Accept' => 'application/vnd.intercom.3+json', 'User-Agent' => "Intercom-Ruby/#{Intercom::VERSION}"}
     end
 
-    def client(uri)
+    def client(uri, read_timeout:, open_timeout:)
       net = Net::HTTP.new(uri.host, uri.port)
       if uri.is_a?(URI::HTTPS)
         net.use_ssl = true
         net.verify_mode = OpenSSL::SSL::VERIFY_PEER
         net.ca_file = File.join(File.dirname(__FILE__), '../data/cacert.pem')
       end
-      net.read_timeout = 90
-      net.open_timeout = 30
+      net.read_timeout = read_timeout
+      net.open_timeout = open_timeout
       net
     end
 
-    def execute(target_base_url=nil, username:, secret: nil)
+    def execute(target_base_url=nil, username:, secret: nil, read_timeout: 90, open_timeout: 30)
       retries = 3
       base_uri = URI.parse(target_base_url)
       set_common_headers(net_http_method, base_uri)
       set_basic_auth(net_http_method, username, secret)
       begin
-        client(base_uri).start do |http|
+        client(base_uri, read_timeout: read_timeout, open_timeout: open_timeout).start do |http|
           begin
             response = http.request(net_http_method)
             set_rate_limit_details(response)
@@ -75,8 +75,12 @@ def execute(target_base_url=nil, username:, secret: nil)
           rescue Intercom::RateLimitExceeded => e
             if @handle_rate_limit
               seconds_to_retry = (@rate_limit_details[:reset_at] - Time.now.utc).ceil
-              sleep seconds_to_retry unless seconds_to_retry < 0
-              retry unless (retries -=1).zero?
+              if (retries -= 1) < 0
+                raise Intercom::RateLimitExceeded.new('Rate limit retries exceeded. Please examine current API Usage.')
+              else
+                sleep seconds_to_retry unless seconds_to_retry < 0
+                retry
+              end
             else
               raise e
             end

lib/intercom/extended_api_operations/users.rb

@@ -5,7 +5,6 @@
 require 'intercom/api_operations/find_all'
 require 'intercom/api_operations/save'
 require 'intercom/api_operations/load'
-require 'intercom/extended_api_operations/users'
 require 'intercom/extended_api_operations/tags'
 require 'intercom/extended_api_operations/segments'
 
@@ -18,13 +17,24 @@ class Company < BaseService
       include ApiOperations::List
       include ApiOperations::Scroll
       include ApiOperations::Save
-      include ExtendedApiOperations::Users
       include ExtendedApiOperations::Tags
       include ExtendedApiOperations::Segments
 
       def collection_class
         Intercom::Company
       end
+
+      def users_by_intercom_company_id(id)
+        get_users(url: "/companies/#{id}/users")
+      end
+
+      def users_by_company_id(id)
+        get_users(url: "/companies", params: { company_id: id, type: "user" })
+      end
+
+      private def get_users(url:, params: {})
+        ClientCollectionProxy.new("users", finder_details: { url: url, params: params }, client: @client)
+      end
     end
   end
 end