nexmo 6.2.0 → 7.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 435a12da7a4fdd6a713aaf4660d5e7ae9e81013e7272df5d0bbbf9b2d5c6c9b8
-  data.tar.gz: ed72a0177f94fdc83b592d86d2e7a198023e6b55511984ffe03a1c409d8947c4
+  metadata.gz: 964a347a61a516b4161b0110412b262ff82614b5c48cddb0d85ee6b9878854ee
+  data.tar.gz: 50edc921ee4c8a8e4f7172d5c1d8ec3efa195d04d9923efcd98c2f4f6623d145
 SHA512:
-  metadata.gz: 662bf6adc6417ffad8ae5612297a1dce42be997a7a95c030c5b0630fdeff278e0bf09a26be88465827c1e7b69d6f0d4823ca9bbde77a79af132cacd7fe2fb998
-  data.tar.gz: 0e739f013dc8f4b564a58f90b8aa1bd1ad61920a15825f4ea1b9a38c3b32dbcea3946ee4824eb1e4aae52a3cfbcac654759016c6eef6d32d41a63eaecb238d72
+  metadata.gz: 0b35dad79758fb59d4ef8662b6684afd655965ca402832c19b652c7985a4234ad3d815dbbbe190ccfda001901067918e3518fce6d3aa31c9f3ed88e09e8bfacb
+  data.tar.gz: 91b1f197f77d8cfd7fcabc3d35d69e6b9adbad8d1dd30c0f0e7f8d376bc7dc521dd519ab0184c79ec1d02fb879afaaf0c8c606fc6a13692c03ba8804e31d0f92

data/README.md

@@ -2,15 +2,18 @@
 
 [![Gem Version](https://badge.fury.io/rb/nexmo.svg)](https://badge.fury.io/rb/nexmo) [![Build Status](https://api.travis-ci.org/Nexmo/nexmo-ruby.svg?branch=master)](https://travis-ci.org/Nexmo/nexmo-ruby) [![Coverage Status](https://coveralls.io/repos/github/Nexmo/nexmo-ruby/badge.svg?branch=coveralls)](https://coveralls.io/github/Nexmo/nexmo-ruby?branch=master)
 
+<img src="https://developer.nexmo.com/assets/images/Vonage_Nexmo.svg" height="48px" alt="Nexmo is now known as Vonage" />
+
 This is the Ruby client library for Nexmo's API. To use it you'll
 need a Nexmo account. Sign up [for free at nexmo.com][signup].
 
 * [Requirements](#requirements)
 * [Installation](#installation)
 * [Usage](#usage)
-* [Logging](#logging)
-* [JWT authentication](#jwt-authentication)
-* [Webhook signatures](#webhook-signatures)
+    * [Logging](#logging)
+    * [Overriding the default hosts](#overriding-the-default-hosts)
+    * [JWT authentication](#jwt-authentication)
+    * [Webhook signatures](#webhook-signatures)
 * [Documentation](#documentation)
 * [License](#license)
 
@@ -73,6 +76,21 @@ By default the library sets the logger to `Rails.logger` if it is defined.
 To disable logging set the logger to `nil`.
 
 
+## Overriding the default hosts
+
+To override the default hosts that the SDK uses for HTTP requests, you need to
+specify the `api_host`, `rest_host` or both in the client configuration. For example:
+
+```ruby
+client = Nexmo::Client.new(
+  api_host: 'api-sg-1.nexmo.com',
+  rest_host: 'rest-sg-1.nexmo.com'
+)
+```
+
+By default the hosts are set to `api.nexmo.com` and `rest.nexmo.com`, respectively.
+
+
 ## JWT authentication
 
 To call newer endpoints that support JWT authentication such as the Voice API you'll

data/lib/nexmo.rb

@@ -1,5 +1,7 @@
+# typed: true
 # frozen_string_literal: true
 require 'zeitwerk'
+require 'sorbet-runtime'
 
 module Nexmo
   loader = Zeitwerk::Loader.new

data/lib/nexmo/abstract_authentication.rb

@@ -1,9 +1,9 @@
+# typed: ignore
+
 module Nexmo
   class AbstractAuthentication
     def initialize(config)
       @config = config
     end
   end
-
-  private_constant :AbstractAuthentication
 end

data/lib/nexmo/account.rb

@@ -1,10 +1,12 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Nexmo
   class Account < Namespace
+    extend T::Sig
     include Keys
 
-    self.host = 'rest.nexmo.com'
+    self.host = :rest_host
 
     # Retrieve your account balance.
     #
@@ -12,6 +14,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/developer/account#get-balance
     #
+    sig { returns(Nexmo::Response) }
     def balance
       request('/account/get-balance')
     end
@@ -34,6 +37,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/developer/account#settings
     #
+    sig { params(params: T::Hash[Symbol, T.untyped]).returns(Nexmo::Response) }
     def update(params)
       request('/account/settings', params: camelcase(params), type: Post)
     end
@@ -49,6 +53,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/developer/account#top-up
     #
+    sig { params(params: T::Hash[Symbol, T.untyped]).returns(Nexmo::Response) }
     def topup(params)
       request('/account/top-up', params: params, type: Post)
     end

data/lib/nexmo/alerts.rb

@@ -1,8 +1,10 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Nexmo
   class Alerts < Namespace
-    self.host = 'rest.nexmo.com'
+    extend T::Sig
+    self.host = :rest_host
 
     # Request the list of phone numbers opted out from your campaign.
     #
@@ -10,6 +12,7 @@ module Nexmo
     #
     # @return [Response]
     #
+    sig { returns(Nexmo::Response) }
     def list
       request('/sc/us/alert/opt-in/query/json')
     end
@@ -25,6 +28,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/sms/us-short-codes/alerts/subscription
     #
+    sig { params(params: T::Hash[Symbol, T.untyped]).returns(Nexmo::Response) }
     def remove(params)
       request('/sc/us/alert/opt-in/manage/json', params: params, type: Post)
     end
@@ -60,6 +64,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/sms/us-short-codes/alerts/sending
     #
+    sig { params(params: T::Hash[Symbol, T.untyped]).returns(Nexmo::Response) }
     def send(params)
       request('/sc/us/alert/json', params: params, type: Post)
     end

data/lib/nexmo/applications.rb

@@ -1,7 +1,9 @@
+# typed: strict
 # frozen_string_literal: true
 
 module Nexmo
   class Applications < Namespace
+    extend T::Sig
     self.authentication = Basic
 
     self.request_body = JSON
@@ -13,9 +15,20 @@ module Nexmo
     # @example
     #   params = {
     #     name: 'Example App',
-    #     type: 'voice',
-    #     answer_url: answer_url,
-    #     event_url: event_url
+    #     capabilities: {
+    #       'messages': {
+    #         'webhooks': {
+    #           'inbound_url': {
+    #             'address': 'https://example.com/webhooks/inbound',
+    #             'http_method': 'POST'
+    #           },
+    #           'status_url': {
+    #             'address': 'https://example.com/webhooks/status',
+    #             'http_method': 'POST'
+    #           }
+    #         }
+    #       }
+    #     }
     #   }
     #
     #   response = client.applications.create(params)
@@ -37,6 +50,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/application.v2#createApplication
     #
+    sig { params(params: T::Hash[Symbol, T.untyped]).returns(Nexmo::Response) }
     def create(params)
       request('/v2/applications', params: params, type: Post)
     end
@@ -61,6 +75,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/application.v2#listApplication
     #
+    sig { params(params: T.nilable(T::Hash[Symbol, Integer])).returns(Nexmo::Response) }
     def list(params = nil)
       request('/v2/applications', params: params, response_class: ListResponse)
     end
@@ -76,6 +91,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/application.v2#getApplication
     #
+    sig { params(id: String).returns(Nexmo::Response) }
     def get(id)
       request('/v2/applications/' + id)
     end
@@ -103,6 +119,10 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/application.v2#updateApplication
     #
+    sig { params(
+      id: String,
+      params: T::Hash[Symbol, T.untyped]
+    ).returns(Nexmo::Response) }
     def update(id, params)
       request('/v2/applications/' + id, params: params, type: Put)
     end
@@ -120,6 +140,7 @@ module Nexmo
     #
     # @see https://developer.nexmo.com/api/application.v2#deleteApplication
     #
+    sig { params(id: String).returns(Nexmo::Response) }
     def delete(id)
       request('/v2/applications/' + id, type: Delete)
     end

data/lib/nexmo/applications/list_response.rb

@@ -1,3 +1,5 @@
+# typed: ignore
+
 class Nexmo::Applications::ListResponse < Nexmo::Response
   include Enumerable
 

data/lib/nexmo/authentication_error.rb

@@ -1,3 +1,5 @@
+# typed: strong
+
 module Nexmo
   class AuthenticationError < ClientError
   end

data/lib/nexmo/basic.rb

@@ -1,3 +1,5 @@
+# typed: ignore
+
 module Nexmo
   class Basic < AbstractAuthentication
     def update(object)

data/lib/nexmo/bearer_token.rb

@@ -1,3 +1,4 @@
+# typed: ignore
 # frozen_string_literal: true
 
 module Nexmo

data/lib/nexmo/client.rb

@@ -1,111 +1,134 @@
+# typed: strict
+
 module Nexmo
   class Client
+    extend T::Sig
+
+    sig { returns(Nexmo::Config) }
     attr_reader :config
 
+    sig { params(options: T.nilable(T::Hash[Symbol, T.untyped])).void }
     def initialize(options = nil)
-      @config = Nexmo.config.merge(options)
+      @config = T.let(Nexmo.config.merge(options), Nexmo::Config)
     end
 
     # @return [Signature]
     #
+    sig { returns(T.nilable(Nexmo::Signature)) }
     def signature
-      @signature ||= Signature.new(config)
+      @signature ||= T.let(Signature.new(config), T.nilable(Nexmo::Signature))
     end
 
     # @return [Account]
     #
+    sig { returns(T.nilable(Nexmo::Account)) }
     def account
-      @account ||= Account.new(config)
+      @account ||= T.let(Account.new(config), T.nilable(Nexmo::Account))
     end
 
     # @return [Alerts]
     #
+    sig { returns(T.nilable(Nexmo::Alerts)) }
     def alerts
-      @alerts ||= Alerts.new(config)
+      @alerts ||= T.let(Alerts.new(config), T.nilable(Nexmo::Alerts))
     end
 
     # @return [Applications]
     #
+    sig { returns(T.nilable(Nexmo::Applications)) }
     def applications
-      @applications ||= Applications.new(config)
-    end
-
-    # @return [Calls]
-    #
-    def calls
-      @calls ||= Calls.new(config)
+      @applications ||= T.let(Applications.new(config), T.nilable(Nexmo::Applications))
     end
 
     # @return [Conversations]
     #
+    sig { returns(T.nilable(Nexmo::Conversations)) }
     def conversations
-      @conversations ||= Conversations.new(config)
+      @conversations ||= T.let(Conversations.new(config), T.nilable(Nexmo::Conversations))
     end
 
     # @return [Conversions]
     #
+    sig { returns(T.nilable(Nexmo::Conversions)) }
     def conversions
-      @conversions ||= Conversions.new(config)
+      @conversions ||= T.let(Conversions.new(config), T.nilable(Nexmo::Conversions))
     end
 
     # @return [Files]
     #
+    sig { returns(T.nilable(Nexmo::Files)) }
     def files
-      @files ||= Files.new(config)
+      @files ||= T.let(Files.new(config), T.nilable(Nexmo::Files))
     end
 
     # @return [Messages]
     #
+    sig { returns(T.nilable(Nexmo::Messages)) }
     def messages
-      @messages ||= Messages.new(config)
+      @messages ||= T.let(Messages.new(config), T.nilable(Nexmo::Messages))
     end
 
     # @return [NumberInsight]
     #
+    sig { returns(T.nilable(Nexmo::NumberInsight)) }
     def number_insight
-      @number_insight ||= NumberInsight.new(config)
+      @number_insight ||= T.let(NumberInsight.new(config), T.nilable(Nexmo::NumberInsight))
     end
 
     # @return [Numbers]
     #
+    sig { returns(T.nilable(Nexmo::Numbers)) }
     def numbers
-      @numbers ||= Numbers.new(config)
+      @numbers ||= T.let(Numbers.new(config), T.nilable(Nexmo::Numbers))
     end
 
     # @return [PricingTypes]
     #
+    sig { returns(T.nilable(Nexmo::PricingTypes)) }
     def pricing
-      @pricing ||= PricingTypes.new(config)
+      @pricing ||= T.let(PricingTypes.new(config), T.nilable(Nexmo::PricingTypes))
     end
 
     # @return [Redact]
     #
+    sig { returns(T.nilable(Nexmo::Redact)) }
     def redact
-      @redact ||= Redact.new(config)
+      @redact ||= T.let(Redact.new(config), T.nilable(Nexmo::Redact))
     end
 
     # @return [Secrets]
     #
+    sig { returns(T.nilable(Nexmo::Secrets)) }
     def secrets
-      @secrets ||= Secrets.new(config)
+      @secrets ||= T.let(Secrets.new(config), T.nilable(Nexmo::Secrets))
     end
 
     # @return [SMS]
     #
+    sig { returns(T.nilable(Nexmo::SMS)) }
     def sms
-      @sms ||= SMS.new(config)
+      @sms ||= T.let(SMS.new(config), T.nilable(Nexmo::SMS))
     end
 
     # @return [TFA]
     #
+    sig { returns(T.nilable(Nexmo::TFA)) }
     def tfa
-      @tfa ||= TFA.new(config)
+      @tfa ||= T.let(TFA.new(config), T.nilable(Nexmo::TFA))
     end
 
     # @return [Verify]
     #
+    sig { returns(T.nilable(Nexmo::Verify)) }
     def verify
-      @verify ||= Verify.new(config)
+      @verify ||= T.let(Verify.new(config), T.nilable(Nexmo::Verify))
+    end
+
+    # @return [Voice]
+    #
+    sig { returns(T.nilable(Nexmo::Voice)) }
+    def voice
+      @voice ||= T.let(Voice.new(config), T.nilable(Nexmo::Voice))
     end
   end
 end

data/lib/nexmo/client_error.rb

@@ -1,3 +1,5 @@
+# typed: strong
+
 module Nexmo
   class ClientError < Error
   end

data/lib/nexmo/config.rb

@@ -1,23 +1,30 @@
+# typed: true
 # frozen_string_literal: true
 require 'logger'
 
 module Nexmo
   class Config
+    extend T::Sig
+
+    sig { void }
     def initialize
-      self.api_key = ENV['NEXMO_API_KEY']
-      self.api_secret = ENV['NEXMO_API_SECRET']
-      self.application_id = nil
-      self.logger = (defined?(Rails.logger) && Rails.logger) || ::Logger.new(nil)
-      self.private_key = nil
+      self.api_host = 'api.nexmo.com'
+      self.api_key = T.let(ENV['NEXMO_API_KEY'], T.nilable(String))
+      self.api_secret = T.let(ENV['NEXMO_API_SECRET'], T.nilable(String))
+      self.application_id = ENV['NEXMO_APPLICATION_ID']
+      self.logger = (defined?(::Rails.logger) && ::Rails.logger) || Nexmo::Logger.new(nil)
+      self.private_key = ENV['NEXMO_PRIVATE_KEY_PATH'] ? File.read(T.must(ENV['NEXMO_PRIVATE_KEY_PATH'])) : ENV['NEXMO_PRIVATE_KEY']
+      self.rest_host = 'rest.nexmo.com'
       self.signature_secret = ENV['NEXMO_SIGNATURE_SECRET']
       self.signature_method = ENV['NEXMO_SIGNATURE_METHOD'] || 'md5hash'
-      self.token = nil
+      self.token = T.let(nil, T.nilable(String))
     end
 
     # Merges the config with the given options hash.
     #
     # @return [Nexmo::Config]
     #
+    sig { params(options: T.nilable(T::Hash[Symbol, T.untyped])).returns(Nexmo::Config) }
     def merge(options)
       return self if options.nil? || options.empty?
 
@@ -26,13 +33,18 @@ module Nexmo
       end
     end
 
+    sig { returns(String) }
+    attr_accessor :api_host
+
     # Returns the value of attribute api_key.
     #
     # @return [String]
     #
     # @raise [AuthenticationError]
     #
+    sig { returns(T.nilable(String)) }
     def api_key
+      @api_key = T.let(@api_key, T.nilable(String))
       unless @api_key
         raise AuthenticationError.new('No API key provided. ' \
           'See https://developer.nexmo.com/concepts/guides/authentication for details, ' \
@@ -42,6 +54,7 @@ module Nexmo
       @api_key
     end
 
+    sig { params(api_key: T.nilable(String)).returns(T.nilable(String)) }
     attr_writer :api_key
 
     # Returns the value of attribute api_secret.
@@ -50,7 +63,9 @@ module Nexmo
     #
     # @raise [AuthenticationError]
     #
+    sig { returns(T.nilable(String)) }
     def api_secret
+      @api_secret = T.let(@api_secret, T.nilable(String))
       unless @api_secret
         raise AuthenticationError.new('No API secret provided. ' \
           'See https://developer.nexmo.com/concepts/guides/authentication for details, ' \
@@ -60,6 +75,7 @@ module Nexmo
       @api_secret
     end
 
+    sig { params(api_secret: T.nilable(String)).returns(T.nilable(String)) }
     attr_writer :api_secret
 
     # Returns the value of attribute application_id.
@@ -68,7 +84,9 @@ module Nexmo
     #
     # @raise [AuthenticationError]
     #
+    sig { returns(T.nilable(String)) }
     def application_id
+      @application_id = T.let(@application_id, T.nilable(String))
       unless @application_id
         raise AuthenticationError.new('No application_id provided. ' \
           'Either provide an application_id, or set an auth token. ' \
@@ -80,32 +98,40 @@ module Nexmo
       @application_id
     end
 
+    sig { params(application_id: T.nilable(String)).returns(T.nilable(String)) }
     attr_writer :application_id
 
+    sig { returns(T.nilable(String)) }
     attr_accessor :app_name
 
+    sig { returns(T.nilable(String)) }
     attr_accessor :app_version
 
     # Returns the value of attribute http.
     #
     # @return [Nexmo::HTTP::Options]
     #
+    sig { returns(T.nilable(Nexmo::HTTP::Options)) }
     attr_reader :http
 
+    sig { params(hash: T::Hash[T.untyped, T.untyped]).returns(T.nilable(Nexmo::HTTP::Options)) }
     def http=(hash)
-      @http = HTTP::Options.new(hash)
+      @http = T.let(nil, T.nilable(Nexmo::HTTP::Options))
+      @http = Nexmo::HTTP::Options.new(hash)
     end
 
     # Returns the value of attribute logger.
     #
     # @return [Nexmo::Logger]
     #
+    sig { returns(T.nilable(Nexmo::Logger)) }
     attr_reader :logger
 
     # @return [Nexmo::Logger]
     #
+    sig { params(logger: T.nilable(T.any(::Logger, Nexmo::Logger))).returns(T.nilable(Nexmo::Logger)) }
     def logger=(logger)
-      @logger = Logger.new(logger)
+      @logger = T.let(Logger.new(logger), T.nilable(Nexmo::Logger))
     end
 
     # Returns the value of attribute private_key.
@@ -114,7 +140,9 @@ module Nexmo
     #
     # @raise [AuthenticationError]
     #
+    sig { returns(T.nilable(String)) }
     def private_key
+      @private_key = T.let(@private_key, T.nilable(String))
       unless @private_key
         raise AuthenticationError.new('No private_key provided. ' \
           'Either provide a private_key, or set an auth token. ' \
@@ -126,15 +154,21 @@ module Nexmo
       @private_key
     end
 
+    sig { params(private_key: T.nilable(String)).returns(T.nilable(String)) }
     attr_writer :private_key
 
+    sig { returns(String) }
+    attr_accessor :rest_host
+
     # Returns the value of attribute signature_secret.
     #
     # @return [String]
     #
     # @raise [AuthenticationError]
     #
+    sig { returns(T.nilable(String)) }
     def signature_secret
+      @signature_secret = T.let(@signature_secret, T.nilable(String))
       unless @signature_secret
         raise AuthenticationError.new('No signature_secret provided. ' \
           'You can find your signature secret in the Nexmo dashboard. ' \
@@ -145,22 +179,28 @@ module Nexmo
       @signature_secret
     end
 
+    sig { params(signature_secret: T.nilable(String)).returns(T.nilable(String)) }
     attr_writer :signature_secret
 
+    sig { returns(String) }
     attr_accessor :signature_method
 
     # Returns the value of attribute token, or a temporary short lived token.
     #
     # @return [String]
     #
+    sig { returns(T.nilable(String)) }
     def token
-      @token || JWT.generate({application_id: application_id}, private_key)
+      @token = T.let(nil, T.nilable(String))
+      @token || JWT.generate({application_id: application_id}, T.must(private_key))
     end
 
+    sig { params(token: T.nilable(String)).returns(T.nilable(String)) }
     attr_writer :token
 
     protected
 
+    sig { params(name: Symbol, value: T.nilable(T.untyped)).void }
     def write_attribute(name, value)
       public_send(:"#{name}=", value)
     end