vonage 7.15.0 → 7.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe42d262916665b0528b89b25fc9094ff4009739cea53ec28a416afe2ec232c8
-  data.tar.gz: d1bb14fcc3e8c862dedd87a32b80034d9914c0cafcc2c53f071b05a9c640a644
+  metadata.gz: eee7072db61e23948a8659c05fa1c1a071a231de32da5506c2a0a1f8e0dec525
+  data.tar.gz: 7082dab4129bb5f251f14cb5cbfc19cdd21b82da8349535194258bb95c656a88
 SHA512:
-  metadata.gz: a52f19d149c83ff7cbc2fe73982abaf79901c146fa45d006d19ba9f32b9640bf14065e132362aae591869339109deeafa68e72349a1e6d9f2a6fba173efbf9a6
-  data.tar.gz: 38f8d3a78930e5b13e8ed71e3bce0ee37789a506f053e9f31c543bdac10760f574dc976fca097f64f47419f9d99c4b912ce32484b389243b96c52f5fa6e7ef4c
+  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/meetings/applications.rb

@@ -19,7 +19,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#updateApplication
     def update(default_theme_id:)
-      request("/meetings/applications", params: {update_details: {default_theme_id: default_theme_id}}, type: Patch)
+      request("/v1/meetings/applications", params: {update_details: {default_theme_id: default_theme_id}}, type: Patch)
     end
   end
 end

data/lib/vonage/meetings/dial_in_numbers.rb

@@ -17,7 +17,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getDialInNumbers
     def list
-      request("/meetings/dial-in-numbers", response_class: ListResponse)
+      request("/v1/meetings/dial-in-numbers", response_class: ListResponse)
     end
   end
 end

data/lib/vonage/meetings/recordings.rb

@@ -19,7 +19,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getRecording
     def info(recording_id:)
-      request("/meetings/recordings/" + recording_id)
+      request("/v1/meetings/recordings/" + recording_id)
     end
 
     # Delete a specified recording.
@@ -30,7 +30,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#deleteRecording
     def delete(recording_id:)
-      request("/meetings/recordings/" + recording_id, type: Delete)
+      request("/v1/meetings/recordings/" + recording_id, type: Delete)
     end
   end
 end

data/lib/vonage/meetings/rooms.rb

@@ -23,7 +23,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getRooms
     def list(**params)
-      path = "/meetings/rooms"
+      path = "/v1/meetings/rooms"
       path += "?#{Params.encode(params)}" unless params.empty?
 
       request(path, response_class: ListResponse)
@@ -38,7 +38,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getRoom
     def info(room_id:)
-      request("/meetings/rooms/" + room_id)
+      request("/v1/meetings/rooms/" + room_id)
     end
 
     # Create a new room.
@@ -96,7 +96,7 @@ module Vonage
     # @see https://developer.vonage.com/en/api/meetings#createRoom
     def create(display_name:, **params)
       request(
-        "/meetings/rooms",
+        "/v1/meetings/rooms",
         params: params.merge({ display_name: display_name }),
         type: Post
       )
@@ -144,7 +144,7 @@ module Vonage
     def update(room_id:, **params)
       raise ArgumentError, 'must provide at least one other param in addition to :room_id' if params.empty?
       request(
-        "/meetings/rooms/" + room_id,
+        "/v1/meetings/rooms/" + room_id,
         params: {
           update_details: params
         },

data/lib/vonage/meetings/sessions.rb

@@ -20,7 +20,7 @@ module Vonage
     # @see https://developer.vonage.com/en/api/meetings#getSessionRecordings
     def list_recordings(session_id:)
       request(
-        "/meetings/sessions/" + session_id + "/recordings",
+        "/v1/meetings/sessions/" + session_id + "/recordings",
         response_class: ListResponse
       )
     end

data/lib/vonage/meetings/themes.rb

@@ -17,7 +17,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getThemes
     def list
-      request("/meetings/themes", response_class: ListResponse)
+      request("/v1/meetings/themes", response_class: ListResponse)
     end
 
     # Return information for specified theme.
@@ -28,7 +28,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getThemeById
     def info(theme_id:)
-      request("/meetings/themes/" + theme_id)
+      request("/v1/meetings/themes/" + theme_id)
     end
 
     # Create a new theme.
@@ -50,7 +50,7 @@ module Vonage
     # @see https://developer.vonage.com/en/api/meetings#createTheme
     def create(main_color:, brand_text:, **params)
       request(
-        "/meetings/themes",
+        "/v1/meetings/themes",
         params: params.merge(main_color: main_color, brand_text: brand_text),
         type: Post
       )
@@ -77,7 +77,7 @@ module Vonage
     # @see https://developer.vonage.com/en/api/meetings#updateTheme
     def update(theme_id:, **params)
       request(
-        "/meetings/themes/" + theme_id,
+        "/v1/meetings/themes/" + theme_id,
         params: {
           update_details: params
         },
@@ -97,7 +97,7 @@ module Vonage
     # @see https://developer.vonage.com/en/api/meetings#deleteTheme
     def delete(theme_id:, force: false)
       request(
-        "/meetings/themes/" + theme_id + "?force=#{force}",
+        "/v1/meetings/themes/" + theme_id + "?force=#{force}",
         type: Delete
       )
     end
@@ -116,7 +116,7 @@ module Vonage
     #
     # @see https://developer.vonage.com/en/api/meetings#getRoomsByThemeId
     def list_rooms(theme_id:, **params)
-      path = "/meetings/themes/" + theme_id + "/rooms"
+      path = "/v1/meetings/themes/" + theme_id + "/rooms"
       path += "?#{Params.encode(params)}" unless params.empty?
 
       request(path, response_class: Meetings::Rooms::ListResponse)
@@ -164,7 +164,7 @@ module Vonage
     private
 
     def get_logo_upload_credentials
-      request("/meetings/themes/logos-upload-urls", response_class: ListResponse)
+      request("/v1/meetings/themes/logos-upload-urls", response_class: ListResponse)
     end
 
     def upload_logo_file(filepath:, credentials:)
@@ -185,7 +185,7 @@ module Vonage
 
     def finalize_logos(theme_id:, keys: [])
       request(
-        "/meetings/themes/" + theme_id + "/finalizeLogos",
+        "/v1/meetings/themes/" + theme_id + "/finalizeLogos",
         params: {
           keys: keys
         },

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.0"
+  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.0
+  version: 7.16.0
 platform: ruby
 authors:
 - Vonage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-08-10 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