intercom 3.5.10 → 4.1.2

data/lib/intercom/conversation.rb

@@ -1,7 +1,12 @@
 require 'intercom/traits/api_resource'
+require 'intercom/api_operations/nested_resource'
 
 module Intercom
   class Conversation
     include Traits::ApiResource
+    include ApiOperations::NestedResource
+
+    nested_resource_methods :tag, operations: %i[add delete]
+    nested_resource_methods :contact, operations: %i[add delete], path: :customers
   end
 end

data/lib/intercom/data_attribute.rb

@@ -0,0 +1,7 @@
+require 'intercom/traits/api_resource'
+
+module Intercom
+  class DataAttribute
+    include Traits::ApiResource
+  end
+end

data/lib/intercom/deprecated_leads_collection_proxy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Intercom
+  class DeprecatedLeadsCollectionProxy < ClientCollectionProxy
+    def fetch(next_page)
+      response_hash = if next_page
+                        @client.get(next_page, {})
+                      else
+                        @client.get(@url, @params)
+                      end
+      transform(response_hash)
+    end
+
+    def transform(response_hash)
+      response_hash['type'] = 'lead.list'
+      leads_list = response_hash.delete('contacts')
+      leads_list.each { |lead| lead['type'] = 'lead' }
+      response_hash['leads'] = leads_list
+      response_hash
+    end
+  end
+end

data/lib/intercom/deprecated_resources.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Intercom
+  module DeprecatedResources
+    def deprecated__leads
+      Intercom::Service::Lead.new(self)
+    end
+
+    def deprecated__users
+      Intercom::Service::User.new(self)
+    end
+  end
+end

data/lib/intercom/errors.rb

@@ -23,16 +23,28 @@ module Intercom
     end
   end
 
-  # Raised when the credentials you provide don't match a valid account on Intercom.
-  # Check that you have set <b>Intercom.app_id=</b> and <b>Intercom.app_api_key=</b> correctly.
+  # Raised when the token you provided is incorrect or not authorized to access certain type of data.
+  # Check that you have set Intercom.token correctly.
   class AuthenticationError < IntercomError; end
 
+  # Raised when the token provided is linked to a deleted application.
+  class AppSuspendedError < AuthenticationError; end
+
+  # Raised when the token provided has been revoked.
+  class TokenRevokedError < AuthenticationError; end
+
+  # Raised when the token provided can't be decoded, and is most likely invalid.
+  class TokenUnauthorizedError < AuthenticationError; end
+
   # Raised when something goes wrong on within the Intercom API service.
   class ServerError < IntercomError; end
 
   # Raised when we have bad gateway errors.
   class BadGatewayError < IntercomError; end
 
+  # Raised when we have gateway timeout errors.
+  class GatewayTimeoutError < IntercomError; end
+
   # Raised when we experience a socket read timeout
   class ServiceUnavailableError < IntercomError; end
 
@@ -42,23 +54,50 @@ module Intercom
   # Raised when requesting resources on behalf of a user that doesn't exist in your application on Intercom.
   class ResourceNotFound < IntercomError; end
 
+  # Raised when requesting an admin that doesn't exist in your Intercom workspace.
+  class AdminNotFound < IntercomError; end
+
+  # Raised when trying to create a resource that already exists in Intercom.
+  class ResourceNotUniqueError < IntercomError; end
+
   # Raised when the request has bad syntax
   class BadRequestError < IntercomError; end
 
   # Raised when you have exceeded the API rate limit
   class RateLimitExceeded < IntercomError; end
 
+  # Raised when some attribute of the response cannot be handled
+  class UnexpectedResponseError < IntercomError; end
+
   # Raised when the request throws an error not accounted for
   class UnexpectedError < IntercomError; end
 
+  # Raised when the CDA limit for the app has been reached
+  class CDALimitReachedError < IntercomError; end
+
   # Raised when multiple users match the query (typically duplicate email addresses)
   class MultipleMatchingUsersError < IntercomError; end
 
+  # Raised when restoring a blocked user
+  class BlockedUserError < IntercomError; end
+
   # Raised when you try to call a non-setter method that does not exist on an object
-  class Intercom::AttributeNotSetError < IntercomError ; end
+  class Intercom::AttributeNotSetError < IntercomError; end
 
   # Raised when unexpected nil returned from server
-  class Intercom::HttpError < IntercomError ; end
+  class Intercom::HttpError < IntercomError; end
+
+  # Raised when an invalid api version is used
+  class ApiVersionInvalid < IntercomError; end
+
+  # Raised when an creating a scroll if one already exists
+  class ScrollAlreadyExistsError < IntercomError; end
+
+  # Raised when a CDA is invalid
+  class InvalidDocumentError < IntercomError; end
+
+  # Raised when a merge is invalid
+  class InvalidMergeError < IntercomError; end
 
   #
   # Non-public errors (internal to the gem)
@@ -71,4 +110,5 @@ module Intercom
   class Intercom::NoMethodMissingHandler < IntercomInternalError; end
 
   class Intercom::DeserializationError < IntercomInternalError; end
+
 end

data/lib/intercom/extended_api_operations/segments.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'intercom/client_collection_proxy'
 require 'intercom/utils'
 
@@ -6,7 +8,7 @@ module Intercom
     module Segments
       def by_segment(id)
         collection_name = Utils.resource_class_to_collection_name(collection_class)
-        ClientCollectionProxy.new(collection_name, finder_details: {url: "/#{collection_name}?segment_id=#{id}"}, client: @client)
+        ClientCollectionProxy.new(collection_name, collection_class, details: { url: "/#{collection_name}?segment_id=#{id}" }, client: @client)
       end
     end
   end

data/lib/intercom/extended_api_operations/tags.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'intercom/client_collection_proxy'
 require 'intercom/utils'
 
@@ -6,7 +8,7 @@ module Intercom
     module Tags
       def by_tag(id)
         collection_name = Utils.resource_class_to_collection_name(collection_class)
-        ClientCollectionProxy.new(collection_name, finder_details: {url: "/#{collection_name}?tag_id=#{id}"}, client: @client)
+        ClientCollectionProxy.new(collection_name, collection_class, details: { url: "/#{collection_name}?tag_id=#{id}" }, client: @client)
       end
     end
   end

data/lib/intercom/lead.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'intercom/traits/api_resource'
+
+module Intercom
+  class Lead
+    include Traits::ApiResource
+
+    def identity_vars
+      %i[email user_id]
+    end
+
+    def flat_store_attributes
+      [:custom_attributes]
+    end
+
+    def update_verb
+      'put'
+    end
+  end
+end

data/lib/intercom/lib/typed_json_deserializer.rb

@@ -1,54 +1,59 @@
+# frozen_string_literal: true
+
 require 'intercom/utils'
 
 module Intercom
   module Lib
-      # Responsibility: To decide whether we are deserializing a collection or an
-      # entity of a particular type and to dispatch deserialization
-      class TypedJsonDeserializer
-        attr_reader :json
-
-        def initialize(json)
-          @json = json
-        end
+    # Responsibility: To decide whether we are deserializing a collection or an
+    # entity of a particular type and to dispatch deserialization
+    class TypedJsonDeserializer
+      attr_reader :json
+
+      def initialize(json, client)
+        @json = json
+        @client = client
+      end
 
-        def deserialize
-          if blank_object_type?(object_type)
-            raise DeserializationError, "No type field was found to facilitate deserialization"
-          elsif list_object_type?(object_type)
-            deserialize_collection(json[object_entity_key])
-          else # singular object type
-            deserialize_object(json)
-          end
+      def deserialize
+        if blank_object_type?(object_type)
+          raise DeserializationError, 'No type field was found to facilitate deserialization'
+        elsif list_object_type?(object_type)
+          deserialize_collection(json[object_entity_key])
+        else # singular object type
+          deserialize_object(json)
         end
+      end
 
-        private
+      private
 
-        def blank_object_type?(object_type)
-          object_type.nil? || object_type == ''
-        end
+      def blank_object_type?(object_type)
+        object_type.nil? || object_type == ''
+      end
 
-        def list_object_type?(object_type)
-          object_type.end_with?('.list')
-        end
+      def list_object_type?(object_type)
+        object_type.end_with?('.list')
+      end
 
-        def deserialize_collection(collection_json)
-          return [] if collection_json == nil
-          collection_json.map { |item_json| TypedJsonDeserializer.new(item_json).deserialize }
-        end
+      def deserialize_collection(collection_json)
+        return [] if collection_json.nil?
 
-        def deserialize_object(object_json)
-          entity_class = Utils.constantize_singular_resource_name(object_entity_key)
-          entity_class.from_api(object_json)
-        end
+        collection_json.map { |item_json| TypedJsonDeserializer.new(item_json, @client).deserialize }
+      end
 
-        def object_type
-          @object_type ||= json['type']
-        end
+      def deserialize_object(object_json)
+        entity_class = Utils.constantize_singular_resource_name(object_entity_key)
+        deserialized = entity_class.from_api(object_json)
+        deserialized.client = @client
+        deserialized
+      end
 
-        def object_entity_key
-          @object_entity_key ||= Utils.entity_key_from_type(object_type)
-        end
+      def object_type
+        @object_type ||= json['type']
+      end
 
+      def object_entity_key
+        @object_entity_key ||= Utils.entity_key_from_type(object_type)
       end
+    end
   end
 end

data/lib/intercom/note.rb

@@ -4,5 +4,9 @@ require 'intercom/traits/api_resource'
 module Intercom
   class Note
     include Traits::ApiResource
+
+    def self.collection_proxy_class
+      Intercom::BaseCollectionProxy
+    end
   end
 end

data/lib/intercom/request.rb

@@ -1,101 +1,141 @@
+# frozen_string_literal: true
+
 require 'cgi'
 require 'net/https'
 
 module Intercom
   class Request
-    attr_accessor :path, :net_http_method, :rate_limit_details
-
-    def initialize(path, net_http_method)
-      self.path = path
-      self.net_http_method = net_http_method
-    end
+    class << self
+      def get(path, params)
+        new(path, Net::HTTP::Get.new(append_query_string_to_url(path, params), default_headers))
+      end
 
-    def set_common_headers(method, base_uri)
-      method.add_field('AcceptEncoding', 'gzip, deflate')
-    end
+      def post(path, form_data)
+        new(path, method_with_body(Net::HTTP::Post, path, form_data))
+      end
 
-    def set_basic_auth(method, username, secret)
-      method.basic_auth(CGI.unescape(username), CGI.unescape(secret))
-    end
+      def delete(path, params)
+        new(path, method_with_body(Net::HTTP::Delete, path, params))
+      end
 
-    def self.get(path, params)
-      new(path, Net::HTTP::Get.new(append_query_string_to_url(path, params), default_headers))
-    end
+      def put(path, form_data)
+        new(path, method_with_body(Net::HTTP::Put, path, form_data))
+      end
 
-    def self.post(path, form_data)
-      new(path, method_with_body(Net::HTTP::Post, path, form_data))
-    end
+      private def method_with_body(http_method, path, params)
+        request = http_method.send(:new, path, default_headers)
+        request.body = params.to_json
+        request['Content-Type'] = 'application/json'
+        request
+      end
 
-    def self.delete(path, params)
-      new(path, method_with_body(Net::HTTP::Delete, path, params))
-    end
+      private def default_headers
+        { 'Accept-Encoding' => 'gzip, deflate', 'Accept' => 'application/vnd.intercom.3+json', 'User-Agent' => "Intercom-Ruby/#{Intercom::VERSION}" }
+      end
 
-    def self.put(path, form_data)
-      new(path, method_with_body(Net::HTTP::Put, path, form_data))
-    end
+      private def append_query_string_to_url(url, params)
+        return url if params.empty?
 
-    def self.method_with_body(http_method, path, params)
-      request = http_method.send(:new, path, default_headers)
-      request.body = params.to_json
-      request["Content-Type"] = "application/json"
-      request
+        query_string = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
+        url + "?#{query_string}"
+      end
     end
 
-    def self.default_headers
-      {'Accept-Encoding' => 'gzip, deflate', 'Accept' => 'application/vnd.intercom.3+json', 'User-Agent' => "Intercom-Ruby/#{Intercom::VERSION}"}
+    def initialize(path, net_http_method)
+      self.path = path
+      self.net_http_method = net_http_method
+      self.handle_rate_limit = false
     end
 
-    def client(uri)
-      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
-    end
+    attr_accessor :handle_rate_limit
 
-    def execute(target_base_url=nil, username:, secret: nil)
+    def execute(target_base_url = nil, token:, read_timeout: 90, open_timeout: 30, api_version: nil)
+      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)
+      set_auth_header(net_http_method, token)
+      set_api_version(net_http_method, api_version) if api_version
       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)
-            decoded_body = decode_body(response)
-            parsed_body = parse_body(decoded_body, response)
             raise_errors_on_failure(response)
+
+            parsed_body = extract_response_body(response)
+
+            return nil if parsed_body.nil?
+
+            raise_application_errors_on_failure(parsed_body, response.code.to_i) if parsed_body['type'] == 'error.list'
+
             parsed_body
+          rescue Intercom::RateLimitExceeded => e
+            if @handle_rate_limit
+              seconds_to_retry = (@rate_limit_details[:reset_at] - Time.now.utc).ceil
+              if (retries -= 1) < 0
+                raise Intercom::RateLimitExceeded, '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
           rescue Timeout::Error
-            raise Intercom::ServiceUnavailableError.new('Service Unavailable [request timed out]')
+            raise Intercom::ServiceUnavailableError, 'Service Unavailable [request timed out]'
           end
         end
       rescue Timeout::Error
-        raise Intercom::ServiceConnectionError.new('Failed to connect to service [connection attempt timed out]')
+        raise Intercom::ServiceConnectionError, 'Failed to connect to service [connection attempt timed out]'
       end
     end
 
-    def decode_body(response)
-      decode(response['content-encoding'], response.body)
-    end
+    attr_accessor :path,
+                  :net_http_method,
+                  :rate_limit_details
 
-    def parse_body(decoded_body, response)
-      parsed_body = nil
-      return parsed_body if decoded_body.nil? || decoded_body.strip.empty?
-      begin
-        parsed_body = JSON.parse(decoded_body)
-      rescue JSON::ParserError => _
-        raise_errors_on_failure(response)
+    private :path,
+            :net_http_method
+
+    private 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
-      raise_application_errors_on_failure(parsed_body, response.code.to_i) if parsed_body['type'] == 'error.list'
-      parsed_body
+      net.read_timeout = read_timeout
+      net.open_timeout = open_timeout
+      net
+    end
+
+    private def extract_response_body(response)
+      decoded_body = decode(response['content-encoding'], response.body)
+
+      json_parse_response(decoded_body, response.code)
     end
 
-    def set_rate_limit_details(response)
+    private def decode(content_encoding, body)
+      return body if !body || body.empty? || content_encoding != 'gzip'
+
+      Zlib::GzipReader.new(StringIO.new(body)).read.force_encoding('utf-8')
+    end
+
+    private def json_parse_response(str, code)
+      return nil if str.to_s.empty?
+
+      JSON.parse(str)
+    rescue JSON::ParserError
+      msg = <<~MSG.gsub(/[[:space:]]+/, ' ').strip # #squish from ActiveSuppor
+        Expected a JSON response body. Instead got '#{str}'
+        with status code '#{code}'.
+      MSG
+
+      raise UnexpectedResponseError, msg
+    end
+
+    private def set_rate_limit_details(response)
       rate_limit_details = {}
       rate_limit_details[:limit] = response['X-RateLimit-Limit'].to_i if response['X-RateLimit-Limit']
       rate_limit_details[:remaining] = response['X-RateLimit-Remaining'].to_i if response['X-RateLimit-Remaining']
@@ -103,52 +143,85 @@ module Intercom
       @rate_limit_details = rate_limit_details
     end
 
-    def decode(content_encoding, body)
-      return body if (!body) || body.empty? || content_encoding != 'gzip'
-      Zlib::GzipReader.new(StringIO.new(body)).read.force_encoding("utf-8")
+    private def set_common_headers(method, _base_uri)
+      method.add_field('AcceptEncoding', 'gzip, deflate')
     end
 
-    def raise_errors_on_failure(res)
-      if res.code.to_i.eql?(404)
-        raise Intercom::ResourceNotFound.new('Resource Not Found')
-      elsif res.code.to_i.eql?(401)
-        raise Intercom::AuthenticationError.new('Unauthorized')
-      elsif res.code.to_i.eql?(403)
-        raise Intercom::AuthenticationError.new('Forbidden')
-      elsif res.code.to_i.eql?(500)
-        raise Intercom::ServerError.new('Server Error')
-      elsif res.code.to_i.eql?(502)
-        raise Intercom::BadGatewayError.new('Bad Gateway Error')
-      elsif res.code.to_i.eql?(503)
-        raise Intercom::ServiceUnavailableError.new('Service Unavailable')
+    private def set_auth_header(method, token)
+      method.add_field('Authorization', "Bearer #{token}")
+    end
+
+    private def set_api_version(method, api_version)
+      method.add_field('Intercom-Version', api_version)
+    end
+
+    private def raise_errors_on_failure(res)
+      code = res.code.to_i
+
+      if code == 404
+        raise Intercom::ResourceNotFound, 'Resource Not Found'
+      elsif code == 401
+        raise Intercom::AuthenticationError, 'Unauthorized'
+      elsif code == 403
+        raise Intercom::AuthenticationError, 'Forbidden'
+      elsif code == 429
+        raise Intercom::RateLimitExceeded, 'Rate Limit Exceeded'
+      elsif code == 500
+        raise Intercom::ServerError, 'Server Error'
+      elsif code == 502
+        raise Intercom::BadGatewayError, 'Bad Gateway Error'
+      elsif code == 503
+        raise Intercom::ServiceUnavailableError, 'Service Unavailable'
+      elsif code == 504
+        raise Intercom::GatewayTimeoutError, 'Gateway Timeout'
       end
     end
 
-    def raise_application_errors_on_failure(error_list_details, http_code)
+    private def raise_application_errors_on_failure(error_list_details, http_code)
       # Currently, we don't support multiple errors
       error_details = error_list_details['errors'].first
       error_code = error_details['type'] || error_details['code']
       error_field = error_details['field']
       parsed_http_code = (http_code > 0 ? http_code : nil)
       error_context = {
-        :http_code => parsed_http_code,
-        :application_error_code => error_code,
-        :field => error_field,
-        :request_id => error_list_details['request_id']
+        http_code: parsed_http_code,
+        application_error_code: error_code,
+        field: error_field,
+        request_id: error_list_details['request_id']
       }
       case error_code
-      when 'unauthorized', 'forbidden'
+      when 'unauthorized', 'forbidden', 'token_not_found'
         raise Intercom::AuthenticationError.new(error_details['message'], error_context)
-      when "bad_request", "missing_parameter", 'parameter_invalid', 'parameter_not_found'
+      when 'token_suspended'
+        raise Intercom::AppSuspendedError.new(error_details['message'], error_context)
+      when 'token_revoked'
+        raise Intercom::TokenRevokedError.new(error_details['message'], error_context)
+      when 'token_unauthorized'
+        raise Intercom::TokenUnauthorizedError.new(error_details['message'], error_context)
+      when 'bad_request', 'missing_parameter', 'parameter_invalid', 'parameter_not_found'
         raise Intercom::BadRequestError.new(error_details['message'], error_context)
-      when "not_found"
+      when 'not_restorable'
+        raise Intercom::BlockedUserError.new(error_details['message'], error_context)
+      when 'not_found', 'company_not_found'
         raise Intercom::ResourceNotFound.new(error_details['message'], error_context)
-      when "rate_limit_exceeded"
+      when 'admin_not_found'
+        raise Intercom::AdminNotFound.new(error_details['message'], error_context)
+      when 'rate_limit_exceeded'
         raise Intercom::RateLimitExceeded.new(error_details['message'], error_context)
+      when 'custom_data_limit_reached'
+        raise Intercom::CDALimitReachedError.new(error_details['message'], error_context)
+      when 'invalid_document'
+        raise Intercom::InvalidDocumentError.new(error_details['message'], error_context)
       when 'service_unavailable'
         raise Intercom::ServiceUnavailableError.new(error_details['message'], error_context)
       when 'conflict', 'unique_user_constraint'
         raise Intercom::MultipleMatchingUsersError.new(error_details['message'], error_context)
+      when 'resource_conflict'
+        raise Intercom::ResourceNotUniqueError.new(error_details['message'], error_context)
+      when 'intercom_version_invalid'
+        raise Intercom::ApiVersionInvalid.new(error_details['message'], error_context)
+      when 'scroll_exists'
+        raise Intercom::ScrollAlreadyExistsError.new(error_details['message'], error_context)
       when nil, ''
         raise Intercom::UnexpectedError.new(message_for_unexpected_error_without_type(error_details, parsed_http_code), error_context)
       else
@@ -156,18 +229,12 @@ module Intercom
       end
     end
 
-    def message_for_unexpected_error_with_type(error_details, parsed_http_code)
+    private def message_for_unexpected_error_with_type(error_details, parsed_http_code)
       "The error of type '#{error_details['type']}' is not recognized. It occurred with the message: #{error_details['message']} and http_code: '#{parsed_http_code}'. Please contact Intercom with these details."
     end
 
-    def message_for_unexpected_error_without_type(error_details, parsed_http_code)
+    private def message_for_unexpected_error_without_type(error_details, parsed_http_code)
       "An unexpected error occured. It occurred with the message: #{error_details['message']} and http_code: '#{parsed_http_code}'. Please contact Intercom with these details."
     end
-
-    def self.append_query_string_to_url(url, params)
-      return url if params.empty?
-      query_string = params.map { |k, v| "#{k.to_s}=#{CGI::escape(v.to_s)}" }.join('&')
-      url + "?#{query_string}"
-    end
   end
 end