vonage 7.9.0 → 7.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d8620ac3418486f818675d3b75efdf29a572c38100d00aeb8f36ab36aae4fb0
-  data.tar.gz: 7c1f845f11ba6b1eb625cdf20b703c2b19af2f789dd41e5368ce99465eab2d05
+  metadata.gz: cc021f5f0b897743382fe24b1973b1fa1ffa57086b590577d9f794a3fbef5355
+  data.tar.gz: 500df71d3f79eb6c8de37f5dc694d705526eab298f92cec34e90420290aa8e00
 SHA512:
-  metadata.gz: 04e95b2647f1d19323fa512b803de87baa245379957fa051c3b13cb12571bf5cb93e735aa28ef332b47f5cf1ccaded503f628b88ee73856ab1e94ee09573d175
-  data.tar.gz: 37ae894d0413c3b72d4c9d8d65462fcb5853740cd8bfcc254f4701fd1529dc3fc3a66fed0888db1e8b0de2ea28461cb4822d7e7e3f06ba5a5db53fce202c4ab3
+  metadata.gz: '049c59c41953de3695a71b722adf03e868bae4edb4f36f145a0e03b61859f512ed508ca3f1e8b1eee54200d058a55265858b9be4f8449c9ea68e60b274ed7282'
+  data.tar.gz: 57fcf30de159323ef20feee16dec66f1eab1b7360e2b75e17a96f368f54c3015db4f83bd4d9b51c1b69739e5c762d25131e0d66bbd1cd09ec14325bfa5f8daae

data/README.md

@@ -17,6 +17,8 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
     * [Webhook signatures](#webhook-signatures)
     * [Pagination](#pagination)
     * [NCCO Builder](#ncco-builder)
+    * [Messages API](#messages-api)
+    * [Verify API v2](#verify-api-v2)
 * [Documentation](#documentation)
 * [Frequently Asked Questions](#frequently-asked-questions)
     * [Supported APIs](#supported-apis)
@@ -220,11 +222,136 @@ Once the message data is created, you can then send the message.
 response = client.messaging.send(to: "447700900000", from: "447700900001", **message)
 ```
 
+## Verify API v2
+
+The [Vonage Verify API v2](https://developer.vonage.com/en/verify/verify-v2/overview) allows you to manage 2FA verification workflows over a number of different channels such as SMS, WhatsApp, WhatsApp Interactive, Voice, Email, and Silent Authentication, either individually or in combination with each other. See the Vonage Developer Documentation for a [complete API reference](https://developer.vonage.com/en/api/verify.v2) listing all the channels, verification options, and callback types.
+
+The Ruby SDK provides two methods for interacting with the Verify v2 API:
+
+- `Verify2#start_verification`: starts a new verification request. Here you can specify options for the request and the workflow to be used.
+- `Verify2#check_code`: for channels where the end-user is sent a one-time code, this method is used to verify the code against the `request_id` of the verification request created by the `start_verification` method.
+
+### Creating a Verify2 Object
+
+```ruby
+verify = client.verify2
+```
+
+### Making a verification request
+
+For simple requests, you may prefer to manually set the value for `workflow` (an array of one or more hashes containing the settings for a particular channel) and any optional params.
+
+Example with the required `:brand` and `:workflow` arguments:
+
+```ruby
+verification_request = verify.start_verification(
+  brand: 'Acme',
+  workflow: [{channel: 'sms', to: '447000000000'}]
+)
+```
+
+Example with the required `:brand` and `:workflow` arguments, and an optional `code_length`:
+
+```ruby
+verification_request = verify.start_verification(
+  brand: 'Acme',
+  workflow: [{channel: 'sms', to: '447000000000'}],
+  code_length: 6
+)
+```
+
+For more complex requests (e.g. with mutliple workflow channels or addtional options), or to take advantage of built-in input validation, you can use the `StartVerificationOptions` object and the `Workflow` and various channel objects or the `WorkflowBuilder`:
+
+#### Create options using StartVerificationOptions object
+
+```ruby
+opts = verify.start_verification_options(
+  locale: 'fr-fr',
+  code_length: 6,
+  client_ref: 'abc-123'
+).to_h
+
+verification_request = verify.start_verification(
+  brand: 'Acme',
+  workflow: [{channel: 'email', to: 'alice.example.com'}],
+  **opts
+)
+```
+
+#### Create workflow using Workflow and Channel objects
+
+```ruby
+# Instantiate a Workflow object
+workflow = verify.workflow
+
+# Add channels to the workflow
+workflow << workflow.sms(to: '447000000000')
+workflow << workflow.email(to: 'alice.example.com')
+
+# Channel data is encpsulated in channel objects stored in the Workflow list array
+workflow.list
+# => [ #<Vonage::Verify2::Channels::SMS:0x0000561474a74778 @channel="sms", @to="447000000000">,
+  #<Vonage::Verify2::Channels::Email:0x0000561474c51a28 @channel="email", @to="alice.example.com">]
+
+# To use the list as the value for `:workflow` in a `start_verification` request call,
+# the objects must be hashified
+workflow_list = workflow.hashified_list
+# => [{:channel=>"sms", :to=>"447000000000"}, {:channel=>"email", :to=>"alice.example.com"}]
+
+verification_request = verify.start_verification(brand: 'Acme', workflow: workflow_list)
+```
+
+#### Create a workflow using the WorkflowBuilder
+
+```ruby
+workflow = verify.workflow_builder.build do |builder|
+  builder.add_voice(to: '447000000001')
+  builder.add_whatsapp(to: '447000000000')
+end
+
+workflow_list = workflow.hashified_list
+# => [{:channel=>"voice", :to=>"447000000001"}, {:channel=>"whatsapp", :to=>"447000000000"}]
+
+verification_request = verify.start_verification(brand: 'Acme', workflow: workflow_list)
+```
+
+### Cancelling a request
+
+You can cancel in in-progress verification request
+
+```ruby
+# Get the `request_id` from the Vonage#Response object returned by the `start_verification` method call
+request_id = verification_request.request_id
+
+verify.cancel_verification_request(request_id: request_id)
+```
+
+### Checking a code
+
+```ruby
+# Get the `request_id` from the Vonage#Response object returned by the `start_verification` method call
+request_id = verification_request.request_id
+
+# Get the one-time code via user input
+# e.g. from params in a route handler or controller action for a form input
+code = params[:code]
+
+begin
+  code_check = verify.check_code(request_id: request_id, code: code)
+rescue => error
+  # an invalid code will raise an exception of type Vonage::ClientError
+end
+
+if code_check.http_response.code == '200'
+  # code is valid
+end
+```
+
 ## Documentation
 
 Vonage Ruby documentation: https://www.rubydoc.info/github/Vonage/vonage-ruby-sdk
 
-Vonage Ruby code examples: https://github.com/Nexmo/nexmo-ruby-code-snippets
+Vonage Ruby code examples: https://github.com/Vonage/vonage-ruby-code-snippets
 
 Vonage APIs API reference: https://developer.nexmo.com/api
 
@@ -252,6 +379,7 @@ The following is a list of Vonage APIs and whether the Ruby SDK provides support
 | Reports API | Beta |❌|
 | SMS API | General Availability |✅|
 | Verify API | General Availability |✅|
+| Verify API v2 | General Availability |✅|
 | Voice API | General Availability |✅|
 
 ## License

data/lib/vonage/client.rb

@@ -131,6 +131,13 @@ module Vonage
       @verify ||= T.let(Verify.new(config), T.nilable(Vonage::Verify))
     end
 
+    # @return [Verify2]
+    #
+    sig { returns(T.nilable(Vonage::Verify2)) }
+    def verify2
+      @verify2 ||= T.let(Verify2.new(config), T.nilable(Vonage::Verify2))
+    end
+
     # @return [Voice]
     #
     sig { returns(T.nilable(Vonage::Voice)) }

data/lib/vonage/namespace.rb

@@ -202,7 +202,7 @@ module Vonage
       when Net::HTTPNoContent
         response_class.new(nil, response)
       when Net::HTTPSuccess
-        if response['Content-Type'].split(';').first == 'application/json'
+        if response['Content-Type'] && response['Content-Type'].split(';').first == 'application/json'
           entity = ::JSON.parse(response.body, object_class: Vonage::Entity)
 
           response_class.new(entity, response)

data/lib/vonage/verify2/channels/email.rb

@@ -0,0 +1,38 @@
+# typed: true
+# frozen_string_literal: true
+require 'phonelib'
+
+module Vonage
+  class Verify2::Channels::Email
+
+    attr_reader :channel, :to, :from
+
+    def initialize(to:, from: nil)
+      self.channel = 'email'
+      self.to = to
+      self.from = from if from
+    end
+
+    def to=(to)
+      # TODO: add validation
+      @to = to
+    end
+
+    def from=(from)
+      # TODO: add validation
+      @from = from
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+
+    private
+
+    attr_writer :channel
+  end
+end

data/lib/vonage/verify2/channels/silent_auth.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+require 'phonelib'
+
+module Vonage
+  class Verify2::Channels::SilentAuth
+
+    attr_reader :channel, :to
+
+    def initialize(to:)
+      self.channel = 'silent_auth'
+      self.to = to
+    end
+
+    def to=(to)
+      raise ArgumentError, "Invalid 'to' value #{to}. Expected to be in E.164 format" unless Phonelib.parse(to.to_i).valid?
+      @to = to
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+
+    private
+
+    attr_writer :channel
+  end
+end

data/lib/vonage/verify2/channels/sms.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+require 'phonelib'
+
+module Vonage
+  class Verify2::Channels::SMS
+    APP_HASH_LENGTH = 11
+
+    attr_reader :channel, :to, :app_hash
+
+    def initialize(to:, app_hash: nil)
+      self.channel = 'sms'
+      self.to = to
+      self.app_hash = app_hash if app_hash
+    end
+
+    def to=(to)
+      raise ArgumentError, "Invalid 'to' value #{to}. Expected to be in E.164 format" unless Phonelib.parse(to).valid?
+      @to = to
+    end
+
+    def app_hash=(app_hash)
+      raise ArgumentError, "Invalid 'app_hash' value #{app_hash}. Length must be #{APP_HASH_LENGTH}" unless app_hash.length == APP_HASH_LENGTH
+      @app_hash = app_hash
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+
+    private
+
+    attr_writer :channel
+  end
+end

data/lib/vonage/verify2/channels/voice.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+require 'phonelib'
+
+module Vonage
+  class Verify2::Channels::Voice
+
+    attr_reader :channel, :to
+
+    def initialize(to:)
+      self.channel = 'voice'
+      self.to = to
+    end
+
+    def to=(to)
+      raise ArgumentError, "Invalid 'to' value #{to}. Expected to be in E.164 format" unless Phonelib.parse(to.to_i).valid?
+      @to = to
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+
+    private
+
+    attr_writer :channel
+  end
+end

data/lib/vonage/verify2/channels/whats_app.rb

@@ -0,0 +1,38 @@
+# typed: true
+# frozen_string_literal: true
+require 'phonelib'
+
+module Vonage
+  class Verify2::Channels::WhatsApp
+
+    attr_reader :channel, :to, :from
+
+    def initialize(to:, from: nil)
+      self.channel = 'whatsapp'
+      self.to = to
+      self.from = from if from
+    end
+
+    def to=(to)
+      raise ArgumentError, "Invalid 'to' value #{to}. Expected to be in E.164 format" unless Phonelib.parse(to.to_i).valid?
+      @to = to
+    end
+
+    def from=(from)
+      raise ArgumentError, "Invalid 'from' value #{from}. Expected to be in E.164 format" unless Phonelib.parse(from.to_i).valid?
+      @from = from
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+
+    private
+
+    attr_writer :channel
+  end
+end

data/lib/vonage/verify2/channels/whats_app_interactive.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+require 'phonelib'
+
+module Vonage
+  class Verify2::Channels::WhatsAppInteractive
+
+    attr_reader :channel, :to
+
+    def initialize(to:)
+      self.channel = 'whatsapp_interactive'
+      self.to = to
+    end
+
+    def to=(to)
+      raise ArgumentError, "Invalid 'to' value #{to}. Expected to be in E.164 format" unless Phonelib.parse(to.to_i).valid?
+      @to = to
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+
+    private
+
+    attr_writer :channel
+  end
+end

data/lib/vonage/verify2/start_verification_options.rb

@@ -0,0 +1,71 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Verify2::StartVerificationOptions
+    VALID_OPTS = [:locale, :channel_timeout, :client_ref, :code_length, :code, :fraud_check].freeze
+
+    VALID_LOCALES = [
+      'en-us', 'en-gb', 'es-es', 'es-mx', 'es-us', 'it-it', 'fr-fr',
+      'de-de', 'ru-ru', 'hi-in', 'pt-br', 'pt-pt', 'id-id'
+    ].freeze
+
+    MIN_CHANNEL_TIMEOUT, MAX_CHANNEL_TIMEOUT = [60, 900]
+
+    MIN_CODE_LENGTH, MAX_CODE_LENGTH = [4, 10]
+
+    attr_reader(*VALID_OPTS)
+
+    def initialize(**opts)
+      VALID_OPTS.each do |opt|
+        send("#{opt}=", opts[opt]) unless opts[opt].nil?
+      end
+    end
+
+    def locale=(locale)
+      unless VALID_LOCALES.include?(locale)
+        raise ArgumentError, "Invalid 'locale' #{locale}. Please choose from the following #{VALID_LOCALES}"
+      end
+
+      @locale = locale
+    end
+
+    def channel_timeout=(channel_timeout)
+      unless channel_timeout.between?(MIN_CHANNEL_TIMEOUT, MAX_CHANNEL_TIMEOUT)
+        raise ArgumentError, "Invalid 'channel_timeout' #{channel_timeout}. Must be between #{MIN_CHANNEL_TIMEOUT} and #{MAX_CHANNEL_TIMEOUT} (inclusive)"
+      end
+
+      @channel_timeout = channel_timeout
+    end
+
+    def client_ref=(client_ref)
+      @client_ref = client_ref
+    end
+
+    def code_length=(code_length)
+      unless code_length.between?(MIN_CODE_LENGTH, MAX_CODE_LENGTH)
+        raise ArgumentError, "Invalid 'code_length' #{code_length}. Must be between #{MIN_CODE_LENGTH} and #{MAX_CODE_LENGTH} (inclusive)"
+      end
+
+      @code_length = code_length
+    end
+
+    def code=(code)
+      @code = code
+    end
+
+    def fraud_check=(fraud_check)
+      raise ArgumentError, "Invalid 'fraud_check' #{fraud_check}. Must be `false`" unless fraud_check == false
+
+      @fraud_check = fraud_check
+    end
+
+    def to_h
+      hash = Hash.new
+      self.instance_variables.each do |ivar|
+        hash[ivar.to_s.delete("@").to_sym] = self.instance_variable_get(ivar)
+      end
+      hash
+    end
+  end
+end

data/lib/vonage/verify2/workflow.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Verify2::Workflow
+    CHANNELS = {
+      sms: Verify2::Channels::SMS,
+      whatsapp: Verify2::Channels::WhatsApp,
+      whatsapp_interactive: Verify2::Channels::WhatsAppInteractive,
+      voice: Verify2::Channels::Voice,
+      email: Verify2::Channels::Email,
+      silent_auth: Verify2::Channels::SilentAuth
+    }
+
+    CHANNELS.keys.each do |method|
+      define_method method do |attributes|
+        CHANNELS[method].new(**attributes)
+      end
+    end
+
+    def self.method_missing(method)
+      raise ClientError.new("Workflow channel must be one of the valid options. Please refer to https://developer.vonage.com/en/api/verify.v2#newRequest for a complete list.")
+    end
+
+    attr_reader :list
+
+    def initialize
+      @list = []
+    end
+
+    def <<(workflow)
+      list << workflow
+    end
+
+    def hashified_list
+      list.map(&:to_h)
+    end
+  end
+end

data/lib/vonage/verify2/workflow_builder.rb

@@ -0,0 +1,25 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Verify2::WorkflowBuilder
+
+    def self.build
+      builder = self.new
+      yield builder if block_given?
+      builder.workflow
+    end
+
+    attr_reader :workflow
+
+    def initialize
+      @workflow = Vonage::Verify2::Workflow.new
+    end
+
+    Vonage::Verify2::Workflow::CHANNELS.keys.each do |channel|
+      define_method "add_#{channel.to_s}" do |args|
+        workflow << workflow.send(channel, **args)
+      end
+    end
+  end
+end

data/lib/vonage/verify2.rb

@@ -0,0 +1,93 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Verify2 < Namespace
+    self.authentication = BearerToken
+
+    self.request_body = JSON
+
+    # Request a verification be sent to a user.
+    #
+    # @example
+    #   verification_request = verify.start_verification(
+    #     brand: 'Acme',
+    #     workflow: [{channel: 'sms', to: '447000000000'}],
+    #     code_length: 6
+    #   )
+    #
+    # @param [required, String] :brand The brand that is sending the verification request
+    #
+    # @param [required, Array<Hash>] :workflow An array of hashes for channels in the workflow
+    #
+    # @param [optional, Hash] opts the options for the verification request.
+    #   @option opts [Integer] :code_length The length of the one-time code provided to the end-user
+    #   @option opts [String] :code An optional alphanumeric custom code to use instead of an auto-generated code
+    #   @option opts [String] :locale The language to use for the verification message (where applicable)
+    #   @option opts [Integer] :channel_timeout Wait time in seconds before trying the next channel in the workflow
+    #   @option opts [String] :client_ref Reference to be included in callbacks
+    #   @option opts [Boolean] If used, must be set to `false`. Will bypass a network block for a single Verify V2 request
+    #
+    # @return Vomage::Response
+    # @see https://developer.vonage.com/en/api/verify.v2#newRequest
+    #
+    def start_verification(brand:, workflow:, **opts)
+      raise ArgumentError, ':workflow must be an Array' unless workflow.is_a?(Array)
+      raise ArgumentError, ':workflow must not be empty' if workflow.empty?
+
+      request('/v2/verify/', params: opts.merge(brand: brand, workflow: workflow), type: Post)
+    end
+
+    # Check a supplied code against a request to see if it is valid.
+    #
+    # @example
+    #   code_check = verify.check_code(request_id: '7e8c5965-0a3f-44df-8a14-f1486209d8a2', code: '1234')
+    #
+    # @param [required, String] :request_id The request_id of the verification request being checked
+    #
+    # @param [required, String] :code The code supplied to the end-user by the verification request
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#checkCode
+    #
+    def check_code(request_id:, code:)
+      request('/v2/verify/' + request_id, params: {code: code}, type: Post)
+    end
+
+    # Cancel a verifiction. If a verification request is still active, calling this method aborts the workflow.
+    #
+    # @example
+    #   verify.cancel_verification_request(request_id: '7e8c5965-0a3f-44df-8a14-f1486209d8a2')
+    #
+    # @param [required, String] :request_id The request_id of the verification request to be cancelled
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#cancelRequest
+    #
+    def cancel_verification_request(request_id:)
+      request('/v2/verify/' + request_id, type: Delete)
+    end
+
+    # Instantiate a new Vonage::Verify2::StartVerificationOptions object
+    #
+    # @param [optional, Hash] opts the options for the verification request.
+    #   @option opts [Integer] :code_length The length of the one-time code provided to the end-user
+    #   @option opts [String] :code An optional alphanumeric custom code to use instead of an auto-generated code
+    #   @option opts [String] :locale The language to use for the verification message (where applicable)
+    #   @option opts [Integer] :channel_timeout Wait time in seconds before trying the next channel in the workflow
+    #   @option opts [String] :client_ref Reference to be included in callbacks
+    #   @option opts [Boolean] If used, must be set to `false`. Will bypass a network block for a single Verify V2 request
+    #
+    def start_verification_options(**opts)
+      StartVerificationOptions.new(**opts)
+    end
+
+    # Instantiate a new Vonage::Verify2::Workflow object
+    def workflow
+      Workflow.new
+    end
+
+    # Return the Vonage::Verify2::WorkflowBuilder class
+    def workflow_builder
+      WorkflowBuilder.itself
+    end
+  end
+end

data/lib/vonage/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vonage
 version: !ruby/object:Gem::Version
-  version: 7.9.0
+  version: 7.10.0
 platform: ruby
 authors:
 - Vonage
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-19 00:00:00.000000000 Z
+date: 2023-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: vonage-jwt
@@ -152,6 +152,16 @@ files:
 - lib/vonage/tfa.rb
 - lib/vonage/user_agent.rb
 - lib/vonage/verify.rb
+- lib/vonage/verify2.rb
+- lib/vonage/verify2/channels/email.rb
+- lib/vonage/verify2/channels/silent_auth.rb
+- lib/vonage/verify2/channels/sms.rb
+- lib/vonage/verify2/channels/voice.rb
+- lib/vonage/verify2/channels/whats_app.rb
+- lib/vonage/verify2/channels/whats_app_interactive.rb
+- lib/vonage/verify2/start_verification_options.rb
+- lib/vonage/verify2/workflow.rb
+- lib/vonage/verify2/workflow_builder.rb
 - lib/vonage/version.rb
 - lib/vonage/voice.rb
 - lib/vonage/voice/actions/connect.rb