vonage 7.33.0 → 7.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5b786bdfd6a5142be34fe1400d4e1914b6d6d9ef4b7e15d10a56e88f9bb5250
-  data.tar.gz: 5768855f0b0d03e66222694234f257600fa65a4eaf07dc4c0b9ce36471b87807
+  metadata.gz: abee836fd492dfd3f67911f146aa67f9908e0e588c4346181792027dcdadf766
+  data.tar.gz: 41cde40bde80157f25db813173a6883b13a9212ba9c79ec18321d62474fd6380
 SHA512:
-  metadata.gz: 3596b7759e7dc20c08ea1a127d97519aff481011134db294ac81b01452700757055813b2905d32144ae1977d8daa1d7d391ef1378763360ca3443b117caf7e05
-  data.tar.gz: e4a089e502ded233cbfbc0c07a60ae5dffceae4e5c550556f377202b7a4cef3b1e42806c3901b81c1c9763a7dd884ae82e9e80e0ecb016e56d0e9bbaeadf7e3d
+  metadata.gz: 44fb7fc3f4165562ee599b9e56845b34687a2e0068e8e569ceaa4ae4c2215cd04561078904be22aef273836974a9a81c688e7404e0c557692b411c29526e2b73
+  data.tar.gz: 7fefb05eb9397b4927f5052d25df5e12f46a2b9be666ce52b0557119d34ce15040b951c4622dfc86c3373258a3a59f2a1433515853302b7daaa823e13695aea0

data/README.md

@@ -11,6 +11,10 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
 * [Requirements](#requirements)
 * [Installation](#installation)
 * [Usage](#usage)
+    * [Authentication](#authentication)
+      * [Basic Authentication](#basic-authentication)
+      * [JWT Authentication](#jwt-authentication)
+      * [Signature Authentication](#signature-authentication)
     * [Logging](#logging)
     * [Exceptions](#exceptions)
     * [Overriding the default hosts](#overriding-the-default-hosts)
@@ -22,6 +26,7 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
     * [Verify API v2](#verify-api-v2)
     * [Voice API](#voice-api)
       * [NCCO Builder](#ncco-builder)
+    * [Identity Insights API](#identity-insights-api)
 * [Documentation](#documentation)
 * [Supported APIs](#supported-apis)
 * [Other SDKs and Tools](#other-sdks-and-tools)
@@ -56,7 +61,7 @@ require 'vonage'
 Then construct a client object with your key and secret:
 
 ```ruby
-client = Vonage::Client.new(api_key: 'YOUR-API-KEY', api_secret: 'YOUR-API-SECRET')
+client = Vonage::Client.new
 ```
 
 You can now use the client object to call Vonage APIs. For example, to send an SMS:
@@ -65,39 +70,161 @@ You can now use the client object to call Vonage APIs. For example, to send an S
 client.sms.send(from: 'Ruby', to: '447700900000', text: 'Hello world')
 ```
 
-For production you can specify the `VONAGE_API_KEY` and `VONAGE_API_SECRET`
-environment variables instead of specifying the key and secret explicitly,
-keeping your credentials out of source control.
+When instantiating the `Client` object you can pass in various arguments to configure it such as credentials for [authentication](#authentication), values for [overriding the default hosts](overriding-the-default-hosts), or [configuration options for the HTTP client](#http-client-configuration).
+
+### Authentication
+
+All requests to the Vonage APIs are authenticated, so the `Client` object will need access to your Vonage credentials. Different Vonage API products support different authenitcations methods, so the credentials required will depend on the authenticaton method used. A few API products also support [multiple authentication methods](#products-with-multiple-authentication-methods).
+
+Currently, all Vonage API products support one or more of the following authentication methods:
+
+- [Basic Authentication](#basic-authentication)
+- [JWT Authentication](#jwt-authentication)
+- [Signature Authentication](#signature-authentication)
+
+For a complete list of which products support which authentication methods, please refer to the [Vonage documentation on this topic](https://developer.vonage.com/en/getting-started/concepts/authentication).
+
+Providing the necessary credentials to the client can be done in a number of ways. You can pass the credentials as keyword arguments when calling `Client.new`, for example in order to provide you API Key and API Secret you could use the `api_key` and `api_secret` keyword arguments respectively. You can pass the value for these arguments directly in the method call like so:
+
+```ruby
+client = Vonage::Client.new(api_key: 'abc123', api_secret: 'abc123456789')
+```
+
+Generally though, and especially for production code or any code that you plan to push up to source control, you will want to avoid exposing your credentials directly in this way and instead use environment variables to define your credentials.
 
-For APIs which use a JWT for authentication you'll need to pass `application_id` and `private_key` arguments to the
-`Client` constructor as well as or instead of `api_key` and `api_secret`. See [JWT Authentication](#jwt-authentication).
+> [!CAUTION]
+> When setting environment variables locally, if using a file to do this (such as in an `.env` file), you should include the name of that file in a `.gitignore` file if you are intending to push your code up to source control.
 
-It is also possible to over-ride the default hosts at `Client` instantiation. See [Overriding the default hosts](overriding-the-default-hosts).
+You can choose to define your own custom environment variables and then use Ruby's `ENV` hash to pass them in as the values for your keyword arguments, for example:
 
-### JWT authentication
+```ruby
+client = Vonage::Client.new(api_key: ENV['MY_API_KEY'], api_secret: ENV['MY_API_SECRET'])
+```
 
-To call newer endpoints that support JWT authentication such as the Voice API and Messages API you'll
-also need to specify the `application_id` and `private_key` options. For example:
+A less verbose approach is to instantiate the client *without* passing in keyword arguments for the authentication credentials. 
 
 ```ruby
-client = Vonage::Client.new(application_id: application_id, private_key: private_key)
+client = Vonage::Client.new
 ```
 
-Both arguments should have string values corresponding to the `id` and `private_key`
-values returned in a ["create an application"](https://developer.vonage.com/api/application.v2#createApplication)
-response. These credentials can be stored in a datastore, in environment variables,
-on disk outside of source control, or in some kind of key management infrastructure.
+In this case the `Config` object used by the `Client` will search your environment for some pre-defined environment variables and use the values of those variables if defined. The names of these pre-defined environment variables are outlined in the sections below on the specific authentication methods.
+
+Note that some Vonage API products support multiple authentication methods. In these cases the Ruby SDK sets a default authentication method for that product, which can be over-ridden with a configuration setting. You can learn more about this in the section on [Products with Multiple Authentication Methods](#products-with-multiple-authentication-methods).
+
+#### Basic Authentication
+
+For products that use Basic Authentication, the Ruby SDK sets an `Authorization` header on the HTTP request with a value containing a Base64 encoded version of your API key and secret. You can read more about this authentication method in the [Vonage documentation](https://developer.vonage.com/en/getting-started/concepts/authentication?source=getting-started#basic-authentication).
+
+To set the header the SDK requires access to your API Key and API Secret. You can either:
+
+1. Pass them in to the `Client` constructor as `api_key` and `api_secret` keyword arguments, either passing in the values directly or as environement variables with custom keys:
+    ```ruby
+    client = Vonage::Client.new(api_key: 'abc123', api_secret: 'abc123456789')
+    ```
+    or
+    ```
+    # .env
+    MY_API_KEY=abc123
+    MY_API_SECRET=abc123456789
+    ```
+    ```ruby
+    client = Vonage::Client.new(api_key: ENV['MY_API_KEY'], api_secret: ENV['MY_API_SECRET'])
+    ```
+
+2. Set them as environment variables with the `VONAGE_API_KEY` and `VONAGE_API_SECRET` keys and then call the constructor without the keyword arguments:
+    ```
+    # .env
+    VONAGE_API_KEY=abc123
+    VONAGE_API_SECRET=abc123456789
+    ```
+    ```ruby
+    client = Vonage::Client.new
+    ```
+
+#### JWT Authentication
+
+For products that use Bearer (JWT) Authentication, the Ruby SDK sets an `Authorization` header on the HTTP request with a value containing a JSON Web Token (JWT) derived from an Application ID and Private Key. You can read more about this authentication method in the [Vonage documentation](https://developer.vonage.com/en/getting-started/concepts/authentication#json-web-tokens), but in brief you will need to create a Vonage Application (for example via the [Vonage Developer Dashboard](https://dashboard.vonage.com/applications), [Application API](https://developer.vonage.com/en/application/overview), or [Vonage CLI](https://github.com/vonage/vonage-cli)). This Application will be assigned a unique ID upon creation. You can then generate a public and private key pair specific to this Application.
+
+The Ruby SDK automatically generates the JWT and sets the `Authorization` header for you. To do this it requires access to an Application ID and assocaited Private Key. You can either:
+
+1. Pass them in to the `Client` constructor as `application_id` and `private_key` keyword arguments, either passing in the values directly or as environement variables with custom keys:
+    ```ruby
+    client = Vonage::Client.new(
+      application_id: '78d335fa-323d-0114-9c3d-d6f0d48968cf',
+      private_key: '-----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFA........'
+    )
+    ```
+    or
+    ```
+    # .env
+    MY_APPLICATION_ID=78d335fa-323d-0114-9c3d-d6f0d48968cf
+    MY_PRIVATE_KEY=-----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFA........
+    ```
+    ```ruby
+    client = Vonage::Client.new(application_id: ENV['MY_APPLICATION_ID'], private_key: ENV['MY_PRIVATE_KEY'])
+    ```
+  
+2. Set them as environment variables with the `VONAGE_APPLICATION_ID` and `VONAGE_PRIVATE_KEY` keys and then call the constructor without the keyword arguments:
+    ```
+    # .env
+    VONAGE_APPLICATION_ID=78d335fa-323d-0114-9c3d-d6f0d48968cf
+    VONAGE_PRIVATE_KEY=-----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFA........
+    ```
+    ```ruby
+    client = Vonage::Client.new
+    ```
+
+##### Using a Private Key File
+
+Using the private key directly, whether to pass it in as a keyword argument or set it as an environment variable, can be a litle bit unweildy. Another option is to store it in a `.key` file and then read the contents of that file in as necessary.
+
+> [!CAUTION]
+> You should include the name of your Private Key file in a `.gitignore` file if you are intending to push your code up to source control.
 
-By default the library generates a short lived JWT per request. To generate a long lived
-JWT for multiple requests or to specify JWT claims directly use `Vonage::JWT.generate` and
-the token option. For example:
+For example, if you had your private key stored in a file called `private.key` in the root directory of your Ruby application, you could:
+
+1. Read the contents of the file in using Ruby's `File.read` method when passing the `private_key` keyword argument to the `Client` constructor, either by passing the filepath directly or as an environement variables with a custom key:
+    ```ruby
+    client = Vonage::Client.new(
+      application_id: '78d335fa-323d-0114-9c3d-d6f0d48968cf',
+      private_key: File.read('/private.key)
+    )
+    ```
+    or
+    ```
+    # .env
+    MY_APPLICATION_ID=78d335fa-323d-0114-9c3d-d6f0d48968cf
+    MY_PRIVATE_KEY_PATH=/private.key
+    ```
+    ```ruby
+    client = Vonage::Client.new(application_id: ENV['MY_APPLICATION_ID'], private_key: File.read(ENV['MY_PRIVATE_KEY_PATH']))
+    ```
+
+2. Set the path as an environment variable with the `VONAGE_PRIVATE_KEY_PATH` key (note: this is used in place of the `VONAGE_PRIVATE_KEY` key) and then call the constructor without the keyword arguments:
+    ```
+    # .env
+    VONAGE_APPLICATION_ID=78d335fa-323d-0114-9c3d-d6f0d48968cf
+    VONAGE_PRIVATE_KEY_PATH=/private.key
+    ```
+    ```ruby
+    client = Vonage::Client.new
+    ```
+
+    If `VONAGE_PRIVATE_KEY_PATH` is set, then the Ruby SDK will attempt to read in the contents of the file at the path provided and use those contents as the Private Key.
+
+> [!TIP]
+> You can download your Private Key file when creating or updating a Vonage Application in the [Vonage Developer Dashboard](https://dashboard.vonage.com/applications), or creating a Vonage Application with the [Vonage CLI](https://github.com/vonage/vonage-cli). You can also create your own file using the value of the `keys.private_key` param provided in the HTTP response when creating a Vonage Application using the [Application API](https://developer.vonage.com/en/application/overview).
+
+##### Custom JWTs
+
+By default the library generates a short lived JWT per request (the default `ttl` is `900` seconds). If you need to generate a long lived JWT for multiple requests or specify JWT claims directly use `Vonage::JWT.generate` to generate a custom JWT and then pass that in to the `Client` constructor using the `token` option. For example:
 
 ```ruby
 claims = {
-  application_id: application_id,
-  private_key: 'path/to/private.key',
+  application_id: ENV['VONAGE_APPLICATION_ID'],
+  private_key: File.read(ENV['VONAGE_PRIVATE_KEY_PATH']),
   nbf: 1483315200,
-  ttl: 800
+  ttl: 3600
 }
 
 token = Vonage::JWT.generate(claims)
@@ -105,10 +232,100 @@ token = Vonage::JWT.generate(claims)
 client = Vonage::Client.new(token: token)
 ```
 
+The `Client` object will then use the JWT that you passed in for any API requests rather than generating one on-the-fly for each request.
+
+> [!NOTE]  
+> 1. Unlike with the `Client` constructor, you **must** set `application_id` and `private_key` as key-value pairs in the `claims` Hash when generating a custom JWT.
+> 2. You can choose to set *either* `ttl` *or* `exp` in the `claims`:
+>     - If you set *both* `ttl` is ignored and `exp` is used
+>     - If you choose to set `exp` this must be set as the number of seconds since the UNIX epoch (if using `ttl` the generator calculates this for you)
+
 Documentation for the Vonage Ruby JWT generator gem can be found at: https://www.rubydoc.info/gems/vonage-jwt
 
 The documentation outlines all the possible parameters you can use to customize and build a token with.
 
+#### Signature Authentication
+
+Signature authentication signs the request using a signature created via a signing algorithm and using your Vonage Signature Secret. You can read more about this authentication method in the [Vonage documentation](https://developer.vonage.com/en/getting-started/concepts/signing-messages).
+
+To create the signature the SDK requires access to your API Key and Signature Secret. You can either:
+
+1. Pass them in to the `Client` constructor as `api_key` and `signature_secret` keyword arguments, either passing in the values directly or as environement variables with custom keys:
+    ```ruby
+    client = Vonage::Client.new(api_key: 'abc123', signature_secret: 'hdEooIhQYgo5XAcmbfLfpy5ROcEwGbjcwj6EvywwvYNOxKWj71')
+    ```
+    or
+    ```
+    # .env
+    MY_API_KEY=abc123
+    MY_SIGNATURE_SECRET=hdEooIhQYgo5XAcmbfLfpy5ROcEwGbjcwj6EvywwvYNOxKWj71
+    ```
+    ```ruby
+    client = Vonage::Client.new(api_key: ENV['MY_API_KEY'], api_secret: ENV['MY_SIGNATURE_SECRET'])
+    ```
+
+2. Set them as environment variables with the `VONAGE_API_KEY` and `VONAGE_SIGNATURE_SECRET` keys and then call the constructor without the keyword arguments:
+    ```
+    # .env
+    VONAGE_API_KEY=abc123
+    VONAGE_SIGNATURE_SECRET=hdEooIhQYgo5XAcmbfLfpy5ROcEwGbjcwj6EvywwvYNOxKWj71
+    ```
+    ```ruby
+    client = Vonage::Client.new
+    ```
+
+By default, the Ruby SDK uses the MD5 HASH algorithm to generate the signature. If you've set a different algorithm in your [Vonage API Settings](https://dashboard.vonage.com/settings), you'll need to over-ride the default when instantiating the `Client` object, for example:
+
+```ruby
+  client = Vonage::Client.new(
+    api_key: 'abc123',
+    signature_secret: 'hdEooIhQYgo5XAcmbfLfpy5ROcEwGbjcwj6EvywwvYNOxKWj71',
+    signature_method: 'sha512'
+  )
+```
+
+You can also set the Signature Method as the `VONAGE_SIGNATURE_METHOD` environment variable, for example:
+
+```
+# .env
+VONAGE_API_KEY=abc123
+VONAGE_SIGNATURE_SECRET=hdEooIhQYgo5XAcmbfLfpy5ROcEwGbjcwj6EvywwvYNOxKWj71
+VONAGE_SIGNATURE_METHOD=sha512
+```
+```ruby
+client = Vonage::Client.new
+```
+
+Supported algorithms are:
+
+- `md5hash`
+- `md5` (HMAC)
+- `sha1`
+- `sha256`
+- `sha512`
+
+#### Products with Multiple Authentication Methods
+
+Some Vonage API products support more than one authentication method. For these products the Ruby SDK sets a default authentication method, but this default can be over-ridden in the `Client` configuration using the `authentication_preference` setting. For example, the Messages API supports both Basic Authentication and Bearer Token (JWT) Authentication. For its Messages API implementation the Ruby SDK defaults to Bearer Token (JWT) Authentication and so you would normally need to provide a Vonage Application ID and Private Key as credentials in order to authenticate when using the Messages API via the Ruby SDK. However, you can instead provide your Vonage API Key and API Secret and set the `Client` object to use Basic Authentication instead:
+
+```
+# .env
+VONAGE_API_KEY=abc123
+VONAGE_API_SECRET=abc123456789
+```
+
+```ruby
+client = Vonage::Client.new(authentication_preference: :basic)
+```
+
+Below is a list of Vonage API products currently implemented in the Ruby SDK that support more than one authentication method.
+
+| Product | Authentication Methods | Default | Over-ride Key |
+|---|---|---|---|
+| Messages API | JWT, Basic | JWT | `:basic` |
+| Verify API v2 | JWT, Basic | JWT | `:basic` |
+| SMS API | Basic, Signature | Basic | `:signature` |
+
 ### Logging
 
 Use the logger option to specify a logger. For example:
@@ -721,6 +938,68 @@ response = client.voice.create({
 })
 ```
 
+## Identity Insights API
+
+The [Vonage Identity Insights API](https://developer.vonage.com/en/identity-insights/overview) provides real-time access to a broad range of attributes related to the carrier, subscriber, or device associated with a phone number. See the Vonage Developer Documentation for a [complete API reference](https://developer.vonage.com/en/api/identity-insights) listing all available insight types.
+
+> [!NOTE] 
+> The Vonage Ruby SDK currently supports the following insight types:
+>   - Format
+>   - Current Carrier
+>   - Original Carrier
+>   - SIM Swap
+
+Calling `identity_insights` on an instance of `Client` returns an `IdentityInsights` object which provides methods for interacting with the Identity Insights API.
+
+```ruby
+client.identity_insights # => #<Vonage::IdentityInsights>
+```
+
+### Making an Insights Request
+
+You can make an Identity Insights request by calling the `IdentityInsights#requests` method, for example:
+
+```ruby
+response = client.identity_insights.requests(phone_number: '447900000000', insights: { format: {} })
+```
+
+### Using the Insights Builder
+
+The `IdentityInsights` object implements a `insights_builder` method. This method returns an `InsightsBuilder` object:
+
+```ruby
+insights_builder = client.identity_insights.insights_builder # => #<Vonage::IdentityInsights::InsightsBuilder @insights={}>
+```
+
+You can then call various methods on the builder in order to add the insights that you require. Each of these methods returns the calling object, so the method invocations can be chained:
+
+```ruby
+insights_builder.add_format.add_current_carrier
+# => #<Vonage::IdentityInsights::InsightsBuilder @insights={:format=>{}, :current_carrier=>{}}>
+```
+
+The builder object can be passed into the `IdentityInsights#requests` method invocation as the value of the `insights` keyword argument:
+
+```ruby
+response = client.identity_insights.requests(phone_number: '447900000000', insights: insights_builder)
+```
+
+### Calling the Method with a Block
+
+The `IdentityInsights#requests` method can also be called with a block. The method yields an `InsightsBuilder` object to the block and expects an `InsightsBuilder` object to be returned by the block.
+
+```ruby
+response = client.identity_insights.requests(phone_number: '447900000000', purpose: "FraudPreventionAndDetection") do |builder|
+  builder.add_format
+    .add_original_carrier
+    .add_current_carrier
+    .add_sim_swap(period: 2400)
+end
+```
+
+> [!NOTE]
+> When requesting the SIM Swap insight, you should pass the `purpose` keyword argument to the `IdentityInsights#requests` method invocation with a value of `'FraudPreventionAndDetection'`.
+
 ## Documentation
 
 Vonage Ruby SDK documentation: https://www.rubydoc.info/gems/vonage
@@ -736,10 +1015,11 @@ The following is a list of Vonage APIs for which the Ruby SDK currently provides
 * [Account API](https://developer.vonage.com/en/account/overview)
 * [Application API](https://developer.vonage.com/en/application/overview)
 * [Conversation API](https://developer.vonage.com/en/conversation/overview)
-* [Meetings API](https://developer.vonage.com/en/meetings/overview)
+* [Identity Insights API](https://developer.vonage.com/en/identity-insights/overview)
+* [Meetings API](https://developer.vonage.com/en/meetings/overview) (deprecated)
 * [Messages API](https://developer.vonage.com/en/messages/overview)
-* [Network Number Verification API](https://developer.vonage.com/en/number-verification/overview)
-* [Network SIM Swap API](https://developer.vonage.com/en/sim-swap/overview)
+* [Network Number Verification API](https://developer.vonage.com/en/number-verification/overview) (deprecated)
+* [Network SIM Swap API](https://developer.vonage.com/en/sim-swap/overview) (deprecated)
 * [Number Insight API](https://developer.vonage.com/en/number-insight/overview)
 * [Numbers API](https://developer.vonage.com/en/numbers/overview)
 * [Proactive Connect API](https://developer.vonage.com/en/proactive-connect/overview) *

data/lib/vonage/basic_and_bearer_token.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class BasicAndBearerToken < AbstractAuthentication
+    def update(object, data)
+      return unless object.is_a?(Net::HTTPRequest)
+
+      if @config.authentication_preference == :basic
+        object.basic_auth(@config.api_key, @config.api_secret)
+      else
+        object['Authorization'] = 'Bearer ' + @config.token
+      end
+    end
+  end
+
+  private_constant :BasicAndBearerToken
+end

data/lib/vonage/basic_and_signature.rb

@@ -18,5 +18,5 @@ module Vonage
     end
   end
 
-  private_constant :Basic
+  private_constant :BasicAndSignature
 end

data/lib/vonage/client.rb

@@ -70,6 +70,13 @@ module Vonage
       @files ||= T.let(Files.new(config), T.nilable(Vonage::Files))
     end
 
+    # @return [IdentityInsights]
+    #
+    sig { returns(T.nilable(Vonage::IdentityInsights)) }
+    def identity_insights
+      @identity_insights ||= T.let(IdentityInsights.new(config), T.nilable(Vonage::IdentityInsights))
+    end
+
     # @return [Meetings]
     # @deprecated
     sig { returns(T.nilable(Vonage::Meetings)) }

data/lib/vonage/identity_insights/insights_builder.rb

@@ -0,0 +1,75 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class IdentityInsights::InsightsBuilder
+    def initialize
+      @insights = {}
+    end
+
+    # Add a Format insight.
+    # @example
+    #   builder = Vonage::IdentityInsights::InsightsBuilder.new
+    #   builder.add_format
+    # @return [InsightsBuilder] The InsightsBuilder instance.
+    #
+    def add_format
+      @insights[:format] = {}
+      self
+    end
+
+    # Add a Sim Swap insight.
+    # @example
+    #   builder = Vonage::IdentityInsights::InsightsBuilder.new
+    #   builder.add_sim_swap(period: 180)
+    # @param period [Integer] The period for the sim swap insight.
+    #   - Optional. If provided, must be between 1 and 2400.
+    # @return [InsightsBuilder] The InsightsBuilder instance.
+    #
+    def add_sim_swap(period: nil)
+      params = {}
+      if period
+        validate_sim_swap_period(period)
+        params[:period] = period 
+      end
+      @insights[:sim_swap] = params
+      self
+    end
+
+    # Add a Current Carrier insight.
+    # @example
+    #   builder = Vonage::IdentityInsights::InsightsBuilder.new
+    #   builder.add_current_carrier
+    # @return [InsightsBuilder] The InsightsBuilder instance.
+    #
+    def add_current_carrier
+      @insights[:current_carrier] = {}
+      self
+    end
+
+    # Add an Original Carrier insight.
+    # @example
+    #   builder = Vonage::IdentityInsights::InsightsBuilder.new
+    #   builder.add_original_carrier
+    # @return [InsightsBuilder] The InsightsBuilder instance.
+    #
+    def add_original_carrier
+      @insights[:original_carrier] = {}
+      self
+    end
+
+    # Convert the InsightsBuilder to a Hash.
+    # @return [Hash] The insights as a Hash.
+    #
+    def to_h
+      @insights
+    end
+
+    private
+
+    def validate_sim_swap_period(period)
+      raise ArgumentError, 'Period must be an Integer' unless period.is_a?(Integer)
+      raise ArgumentError, 'Period must be between 1 and 2400' unless period.between?(1, 2400)
+    end
+  end
+end

data/lib/vonage/identity_insights.rb

@@ -0,0 +1,75 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vonage
+  class IdentityInsights < Namespace
+    VALID_INSIGHT_TYPES = %i[format sim_swap original_carrier current_carrier].freeze
+    
+    self.authentication = BearerToken
+
+    self.host = :vonage_host
+
+    self.request_body = JSON
+
+    # Submit an Identity Insights request.
+    #  The SDK currently supports the following insight types: `format`, `sim_swap`, `current_carrier`, and `original_carrier`.
+    #
+    # @example with `insights` as a Hash
+    #   response = client.identity_insights.requests(phone_number: '447900000000', insights: { format: {} })
+    #
+    # @example with `insights` as an InsightsBuilder
+    #   insights = client.identity_insights.insights_builder.add_format.add_sim_swap(period: 180)
+    #   response = client.identity_insights.requests(phone_number: '447900000000', insights: insights)
+    #
+    # @example with a block to build `insights`
+    #   response = client.identity_insights.requests(phone_number: '447900000000') do |builder|
+    #     builder.add_format
+    #     builder.add_sim_swap(period: 180)
+    #   end
+    #
+    # @option params [required, String] :phone_number The phone number to request insights for.
+    #
+    # @option params [String] :purpose The purpose for requesting the insights.
+    #
+    # @option params [Hash, InsightsBuilder] :insights
+    #   A Hash or InsightsBuilder instance specifying the types of insights to request.
+    #   See the Vonage developer documentation for any parameters supported by each insight type.
+    #
+    # for block {|builder| ... }
+    # @yield [builder] passes a InsightsBuilder instance to the block
+    # @yieldreturn [required, InsightsBuilder] expects the block to return a InsightsBuilder instance
+    #
+    # @return [Vonage::Response] The API response.
+    #
+    # @see https://developer.vonage.com/en/api/identity-insights#getInsights
+    #
+    def requests(phone_number:, insights: {}, **options)
+      insights = yield insights_builder if block_given?
+      validate_insights(insights)
+
+      params = {
+        phone_number: phone_number,
+        insights: insights.to_h
+      }.merge(options)
+
+      request('/identity-insights/v1/requests', params: params, type: Post)
+    end
+
+    # Instantiate an InsightsBuilder.
+    # @return [InsightsBuilder] A new InsightsBuilder instance.
+    #
+    def insights_builder
+      InsightsBuilder.new
+    end
+
+    private
+
+    def validate_insights(insights)
+      raise ArgumentError.new("`insights` must be a Hash or instance of InsightsBuilder") unless insights.is_a?(Hash) || insights.is_a?(InsightsBuilder)
+      raise ArgumentError.new("`insights` cannot be empty") if insights.to_h.empty?
+
+      invalid_insights = insights.to_h.keys - VALID_INSIGHT_TYPES
+      raise ArgumentError.new("`insights` contains the following invalid or unsupported insight types: #{invalid_insights.join(', ')}") unless invalid_insights.empty?
+    end
+  end
+end

data/lib/vonage/messaging.rb

@@ -6,7 +6,7 @@ module Vonage
   class Messaging < Namespace
     extend Forwardable
 
-    self.authentication = BearerToken
+    self.authentication = BasicAndBearerToken
 
     self.request_body = JSON
 

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

@@ -25,6 +25,7 @@ module Vonage
       @redirect_url = redirect_url
     end
 
+    # @deprecated: This method is deprecated and will be removed in a future release.
     def sandbox=(sandbox)
       raise ArgumentError, "Invalid 'sandbox' value #{sandbox}. Expected to be boolean value" unless [true, false].include? sandbox
       @sandbox = sandbox

data/lib/vonage/verify2/template_fragments.rb

@@ -5,7 +5,7 @@ module Vonage
   class Verify2::TemplateFragments < Namespace
     CHANNELS = ['sms', 'voice'].freeze
 
-    self.authentication = BearerToken
+    self.authentication = BasicAndBearerToken
 
     self.request_body = JSON
 

data/lib/vonage/verify2/templates.rb

@@ -3,7 +3,7 @@
 
 module Vonage
   class Verify2::Templates < Namespace
-    self.authentication = BearerToken
+    self.authentication = BasicAndBearerToken
 
     self.request_body = JSON
 

data/lib/vonage/verify2.rb

@@ -3,7 +3,7 @@
 
 module Vonage
   class Verify2 < Namespace
-    self.authentication = BearerToken
+    self.authentication = BasicAndBearerToken
 
     self.request_body = JSON
 

data/lib/vonage/version.rb

@@ -1,5 +1,5 @@
 # typed: strong
 
 module Vonage
-  VERSION = '7.33.0'
+  VERSION = '7.34.0'
 end

data/lib/vonage/voice/actions/connect.rb

@@ -153,6 +153,7 @@ module Vonage
       ncco[0].merge!(timeout: builder.timeout) if builder.timeout
       ncco[0].merge!(limit: builder.limit) if builder.limit
       ncco[0].merge!(machineDetection: builder.machineDetection) if builder.machineDetection
+      ncco[0].merge!(advanced_machine_detection: builder.advanced_machine_detection) if builder.advanced_machine_detection
       ncco[0].merge!(eventUrl: builder.eventUrl) if builder.eventUrl
       ncco[0].merge!(eventMethod: builder.eventMethod) if builder.eventMethod
       ncco[0].merge!(ringbackTone: builder.ringbackTone) if builder.ringbackTone
@@ -185,6 +186,7 @@ module Vonage
 
       hash.merge!(dtmfAnswer: endpoint_attrs[:dtmfAnswer]) if endpoint_attrs[:dtmfAnswer]
       hash.merge!(onAnswer: endpoint_attrs[:onAnswer]) if endpoint_attrs[:onAnswer]
+      hash.merge!(shaken: endpoint_attrs[:shaken]) if endpoint_attrs[:shaken]
 
       hash
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vonage
 version: !ruby/object:Gem::Version
-  version: 7.33.0
+  version: 7.34.0
 platform: ruby
 authors:
 - Vonage
@@ -137,6 +137,7 @@ files:
 - lib/vonage/applications/list_response.rb
 - lib/vonage/authentication_error.rb
 - lib/vonage/basic.rb
+- lib/vonage/basic_and_bearer_token.rb
 - lib/vonage/basic_and_signature.rb
 - lib/vonage/bearer_token.rb
 - lib/vonage/client.rb
@@ -164,6 +165,8 @@ files:
 - lib/vonage/form_data.rb
 - lib/vonage/gsm7.rb
 - lib/vonage/http.rb
+- lib/vonage/identity_insights.rb
+- lib/vonage/identity_insights/insights_builder.rb
 - lib/vonage/json.rb
 - lib/vonage/jwt.rb
 - lib/vonage/key_secret_params.rb