Add API version support (#459)

Author: conarro

lib/intercom/client.rb

@@ -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, :timeouts
+    attr_reader :base_url, :rate_limit_details, :username_part, :password_part, :handle_rate_limit, :timeouts, :api_version
 
     class << self
       def set_base_url(base_url)
@@ -25,7 +25,7 @@ def set_timeouts(open_timeout: nil, read_timeout: nil)
       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)
+    def initialize(app_id: 'my_app_id', api_key: 'my_api_key', token: nil, base_url:'https://api.intercom.io', handle_rate_limit: false, api_version: nil)
       if token
         @username_part = token
         @password_part = ""
@@ -35,6 +35,9 @@ def initialize(app_id: 'my_app_id', api_key: 'my_api_key', token: nil, base_url:
       end
       validate_credentials!
 
+      @api_version = api_version
+      validate_api_version!
+
       @base_url = base_url
       @rate_limit_details = {}
       @handle_rate_limit = handle_rate_limit
@@ -123,9 +126,14 @@ def validate_credentials!
       fail error if @username_part.nil?
     end
 
+    def validate_api_version!
+      error = MisconfiguredClientError.new("api_version must be either nil or a valid API version")
+      fail error if (@api_version && Gem::Version.new(@api_version) < Gem::Version.new('1.0'))
+    end
+
     def execute_request(request)
       request.handle_rate_limit = handle_rate_limit
-      request.execute(@base_url, username: @username_part, secret: @password_part, **timeouts)
+      request.execute(@base_url, username: @username_part, secret: @password_part, api_version: @api_version, **timeouts)
     ensure
       @rate_limit_details = request.rate_limit_details
     end

lib/intercom/errors.rb

@@ -81,6 +81,9 @@ class Intercom::AttributeNotSetError < IntercomError; end
   # Raised when unexpected nil returned from server
   class Intercom::HttpError < IntercomError; end
 
+  # Raised when an invalid api version is used
+  class ApiVersionInvalid < IntercomError; end
+
   #
   # Non-public errors (internal to the gem)
   #

lib/intercom/request.rb

@@ -19,6 +19,10 @@ def set_basic_auth(method, username, secret)
       method.basic_auth(CGI.unescape(username), CGI.unescape(secret))
     end
 
+    def set_api_version(method, api_version)
+      method.add_field('Intercom-Version', api_version)
+    end
+
     def self.get(path, params)
       new(path, Net::HTTP::Get.new(append_query_string_to_url(path, params), default_headers))
     end
@@ -58,11 +62,12 @@ def client(uri, read_timeout:, open_timeout:)
       net
     end
 
-    def execute(target_base_url=nil, username:, secret: nil, read_timeout: 90, open_timeout: 30)
+    def execute(target_base_url=nil, username:, secret: nil, 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_api_version(net_http_method, api_version) if api_version
       begin
         client(base_uri, read_timeout: read_timeout, open_timeout: open_timeout).start do |http|
           begin
@@ -180,6 +185,8 @@ def raise_application_errors_on_failure(error_list_details, http_code)
         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 nil, ''
         raise Intercom::UnexpectedError.new(message_for_unexpected_error_without_type(error_details, parsed_http_code), error_context)
       else

spec/unit/intercom/client_spec.rb

@@ -42,6 +42,29 @@ module Intercom
       proc { Client.new(app_id: nil, api_key: nil) }.must_raise MisconfiguredClientError
     end
 
+    describe 'API version' do
+      it 'does not set the api version by default' do
+        assert_nil(client.api_version)
+      end
+
+      it 'allows api version to be provided' do
+        Client.new(app_id: app_id, api_key: api_key, api_version: '1.0').api_version.must_equal('1.0')
+      end
+
+      it 'allows api version to be nil' do
+        # matches default behavior, and will honor version set in the Developer Hub
+        assert_nil(Client.new(app_id: app_id, api_key: api_key, api_version: nil).api_version)
+      end
+
+      it 'raises on invalid api version' do
+        proc { Client.new(app_id: app_id, api_key: api_key, api_version: '0.2') }.must_raise MisconfiguredClientError
+      end
+
+      it 'raises on empty api version' do
+        proc { Client.new(app_id: app_id, api_key: api_key, api_version: '') }.must_raise MisconfiguredClientError
+      end
+    end
+
     describe 'OAuth clients' do
       it 'supports "token"' do
         client = Client.new(token: 'foo')

spec/unit/intercom/request_spec.rb

@@ -72,7 +72,6 @@
       req.expects(:sleep).never.with(any_parameters)
       req.execute(target_base_url=uri, username: "ted", secret: "")
     end
-
   end
 
 
@@ -85,6 +84,14 @@
       req = Intercom::Request.put(uri, "")
       expect { req.execute(target_base_url=uri, username: "ted", secret: "") }.must_raise(Intercom::ResourceNotUniqueError)
     end
+
+    it 'should raise ApiVersionInvalid error on intercom_version_invalid code' do
+      # Use webmock to mock the HTTP request
+      stub_request(:put, uri).\
+      to_return(status: [400, "Bad Request"], headers: { 'X-RateLimit-Reset' => (Time.now.utc + 10).to_i.to_s }, body: {type: "error.list", errors: [ code: "intercom_version_invalid" ]}.to_json)
+      req = Intercom::Request.put(uri, "")
+      expect { req.execute(uri, username: "ted", secret: "") }.must_raise(Intercom::ApiVersionInvalid)
+    end
   end
 
   it 'parse_body returns nil if decoded_body is nil' do