vonage 7.15.1 → 7.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d6768944b13ad567a9009b6b8612d4877f2bb61a33a5320c8bdaba5227e8250
-  data.tar.gz: d6ce687150cbc230e15b9437bce3c29c6ea2c9c11b69c6938dd0d5c9d76bf5c3
+  metadata.gz: eee7072db61e23948a8659c05fa1c1a071a231de32da5506c2a0a1f8e0dec525
+  data.tar.gz: 7082dab4129bb5f251f14cb5cbfc19cdd21b82da8349535194258bb95c656a88
 SHA512:
-  metadata.gz: 630445900058e653422d18dafb417d84babe40bc60584a598f60cb149539410a5f96348ac8eea1656ce67dc1b6ebc0956859059928b1d442ae7664f4446bbc7b
-  data.tar.gz: 64924d4e8c26cb23d76f327a4fe5ac137cf39fc6c870a850179e04ee5033b4b8c4420207adb1f1435891996c9386fe4ff0024fc4d12435060ab53bbe6c9c9ba6
+  metadata.gz: 9274d4f25c3ac03361e7024aa24685e2be658db11c57601bbc349bc3c65784ef097d836e309318e87de8f4256dab45bbe814638d708230b7463df58589968fa8
+  data.tar.gz: e410a075c96c179c18ca87e047c9c16c3e364c97c36c535eb946dabe4497070a3d465332756db899016ee20af2b45c09dfa846156e9392dde29dfecda4955ae0

data/README.md

@@ -12,6 +12,7 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
 * [Installation](#installation)
 * [Usage](#usage)
     * [Logging](#logging)
+    * [Exceptions](#exceptions)
     * [Overriding the default hosts](#overriding-the-default-hosts)
     * [JWT authentication](#jwt-authentication)
     * [Webhook signatures](#webhook-signatures)
@@ -82,6 +83,46 @@ By default the library sets the logger to `Rails.logger` if it is defined.
 
 To disable logging set the logger to `nil`.
 
+## Exceptions
+
+Where exceptions result from an error response from the Vonage API (HTTP responses that aren't ion the range `2xx` or `3xx`), the `Net::HTTPResponse` object will be available as a property of the `Exception` object via a `http_response` getter method (where there is no `Net::HTTPResponse` object associated with the exception, the value of `http_response` will be `nil`).
+
+You can rescue the the exception to access the `http_response`, as well as use other getters provided for specific parts of the response. For example:
+
+```ruby
+begin
+  verification_request = client.verify2.start_verification(
+    brand: 'Acme',
+    workflow: [{channel: 'sms', to: '44700000000'}]
+  )
+rescue Vonage::APIError => error
+  if error.http_response
+    error.http_response # => #<Net::HTTPUnauthorized 401 Unauthorized readbody=true>
+    error.http_response_code # => "401"
+    error.http_response_headers # => {"date"=>["Sun, 24 Sep 2023 11:08:47 GMT"], ...rest of headers}
+    error.http_response_body # => {"title"=>"Unauthorized", ...rest of body}
+  end
+end
+```
+
+For certain legacy API products, such as the [SMS API](https://developer.vonage.com/en/messaging/sms/overview), [Verify v1 API](https://developer.vonage.com/en/verify/verify-v1/overview) and [Number Insight v1 API](https://developer.vonage.com/en/number-insight/overview), a `200` response is received even in situations where there is an API-related error. For exceptions raised in these situation, rather than a `Net::HTTPResponse` object, a `Vonage::Response` object will be made available as a property of the exception via a `response` getter method. The properties on this object will depend on the response data provided by the API endpoint. For example:
+
+```ruby
+begin
+  sms = client.sms.send(
+    from: 'Vonage',
+    to: '44700000000',
+    text: 'Hello World!'
+  )
+rescue Vonage::Error => error
+  if error.is_a? Vonage::ServiceError
+    error.response # => #<Vonage::Response:0x0000555b2e49d4f8>
+    error.response.messages.first.status # => "4"
+    error.response.messages.first.error_text # => "Bad Credentials"
+    error.response.http_response # => #<Net::HTTPOK 200 OK readbody=true>
+  end
+end
+```
 
 ## Overriding the default hosts
 

data/lib/vonage/api_error.rb

@@ -0,0 +1,33 @@
+# typed: strong
+require "json"
+
+module Vonage
+  class APIError < Error
+    extend T::Sig
+
+    sig { returns(Net::HTTPResponse) }
+    attr_reader :http_response
+
+    sig { params(message: T.nilable(String), http_response: T.nilable(Net::HTTPResponse)).void }
+    def initialize(message = nil, http_response: nil)
+      super(message)
+      @http_response = http_response
+    end
+
+    def http_response_code
+      return nil unless http_response
+      http_response.code
+    end
+
+    def http_response_headers
+      return nil unless http_response
+      http_response.to_hash
+    end
+
+    def http_response_body
+      return nil unless http_response
+      return {} unless http_response.content_type && http_response.content_type.include?("json")
+      ::JSON.parse(http_response.body)
+    end
+  end
+end

data/lib/vonage/client_error.rb

@@ -1,6 +1,6 @@
 # typed: strong
 
 module Vonage
-  class ClientError < Error
+  class ClientError < APIError
   end
 end

data/lib/vonage/errors.rb

@@ -27,27 +27,30 @@ module Vonage
         when Net::HTTPServerError
           ServerError
         else
-          Error
+          APIError
         end
 
-      message =
-        if response.content_type == "application/json"
-          hash = ::JSON.parse(response.body)
+      message = response.content_type.to_s.include?("json") ? set_message(response) : ""
 
-          if hash.key?("error_title")
-            hash["error_title"]
-          elsif hash.key?("error-code-label")
-            hash["error-code-label"]
-          elsif hash.key?("description")
-            hash["description"]
-          elsif hash.key?("message")
-            hash["message"]
-          elsif problem_details?(hash)
-            problem_details_message(hash)
-          end
-        end
+      exception_class.new(message, http_response: response)
+    end
+
+    def self.set_message(response)
+      hash = ::JSON.parse(response.body)
 
-      exception_class.new(message)
+      if hash.key?("error_title")
+        hash["error_title"]
+      elsif hash.key?("error-code-label")
+        hash["error-code-label"]
+      elsif hash.key?("description")
+        hash["description"]
+      elsif hash.key?("message")
+        hash["message"]
+      elsif problem_details?(hash)
+        problem_details_message(hash)
+      else
+        ""
+      end
     end
 
     sig { params(hash: T::Hash[String, T.untyped]).returns(T::Boolean) }
@@ -57,7 +60,7 @@ module Vonage
 
     sig { params(hash: T::Hash[String, T.untyped]).returns(String) }
     def self.problem_details_message(hash)
-      "#{hash["title"]}. #{hash["detail"]} See #{hash["type"]} for more info, or email support@nexmo.com if you have any questions."
+      "#{hash["title"]}. #{hash["detail"]} See #{hash["type"]} for more info, or email support@vonage.com if you have any questions."
     end
   end
 

data/lib/vonage/server_error.rb

@@ -1,6 +1,6 @@
 # typed: strong
 
 module Vonage
-  class ServerError < Error
+  class ServerError < APIError
   end
 end

data/lib/vonage/version.rb

@@ -1,5 +1,5 @@
 # typed: strong
 
 module Vonage
-  VERSION = "7.15.1"
+  VERSION = "7.16.0"
 end

data/lib/vonage.rb

@@ -7,6 +7,7 @@ module Vonage
   loader = Zeitwerk::Loader.new
   loader.tag = File.basename(__FILE__, '.rb')
   loader.inflector.inflect({
+    'api_error' => 'APIError',
     'dtmf' => 'DTMF',
     'gsm7' => 'GSM7',
     'http' => 'HTTP',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vonage
 version: !ruby/object:Gem::Version
-  version: 7.15.1
+  version: 7.16.0
 platform: ruby
 authors:
 - Vonage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-15 00:00:00.000000000 Z
+date: 2023-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vonage-jwt
@@ -113,6 +113,7 @@ files:
 - lib/vonage/abstract_authentication.rb
 - lib/vonage/account.rb
 - lib/vonage/alerts.rb
+- lib/vonage/api_error.rb
 - lib/vonage/applications.rb
 - lib/vonage/applications/list_response.rb
 - lib/vonage/authentication_error.rb