nexmo 6.3.0 → 7.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 431850b9568a3bacf15de1cf1f31883616451e0fdd49283e9f78deb76cf74ba9
-  data.tar.gz: 8d3c2e1314efd2235abb2e3b243367fa715eb9d568048178f8d86e7455ed2abd
+  metadata.gz: ad124eb0e0e93884dc48ed8257b977c2cc365b19668326751d0fa9c0dd843696
+  data.tar.gz: a7e1dae46b7e4c9d86b49fa51f6e74679ec1df56d55961e81e1a8d12b1831f29
 SHA512:
-  metadata.gz: c27cf8e95a1793a0c16f5787a9c9fe0063dfdd245e1bb8f162c8195f051f7b3ccbdec407f879e0ff7084c55f7a46ccf8932249255edfa4bb22c30384380cf587
-  data.tar.gz: e5d15599fb9f691337d053f76d2c74e498744787e98890256fab12bfa4f681105e9ca932397af14cb034b33cd379065a66d0f80f1ce23a4c2d1bc1fe4df63db3
+  metadata.gz: 4de53e3319290efe704e16603a09aa79af15cc47aaf75f539e1e442b040d6e86f7427e6a412702c0557cd1d43c1ee8b31b38e71646ac615766277ed63caa590c
+  data.tar.gz: 57c846af9f53f5537a6aeda3d588e36c6ef41c273f18640fe2214e37428ecd8d5ba7cfe91b619fc5035c43b0847a9507d97b9b036aa3fc1d6bb6b67bf975601f

data/README.md

@@ -1,6 +1,8 @@
 # Nexmo Client Library for Ruby
 
-[![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)
+[![Gem Version](https://badge.fury.io/rb/nexmo.svg)](https://badge.fury.io/rb/nexmo) [![Coverage Status](https://github.com/nexmo/nexmo-ruby/workflows/CI/badge.svg) [![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].
@@ -8,9 +10,10 @@ 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
@@ -94,18 +112,19 @@ the token option. For example:
 ```ruby
 claims = {
   application_id: application_id,
+  private_key: 'path/to/private.key',
   nbf: 1483315200,
-  exp: 1514764800,
-  iat: 1483228800
+  ttl: 800
 }
 
-private_key = File.read('path/to/private.key')
-
-token = Nexmo::JWT.generate(claims, private_key)
+token = Nexmo::JWT.generate(claims)
 
 client = Nexmo::Client.new(token: token)
 ````
 
+Documentation for the Nexmo Ruby JWT generator gem can be found at
+[https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby](https://www.rubydoc.info/github/nexmo/nexmo-jwt-ruby).
+The documentation outlines all the possible parameters you can use to customize and build a token with.
 
 ## Webhook signatures
 

data/lib/nexmo.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 require 'zeitwerk'
 require 'sorbet-runtime'

data/lib/nexmo/abstract_authentication.rb

@@ -6,6 +6,4 @@ module Nexmo
       @config = config
     end
   end
-
-  private_constant :AbstractAuthentication
 end

data/lib/nexmo/account.rb

@@ -1,8 +1,9 @@
-# typed: false
+# typed: strict
 # frozen_string_literal: true
 
 module Nexmo
   class Account < Namespace
+    extend T::Sig
     include Keys
 
     self.host = :rest_host
@@ -13,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
@@ -35,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
@@ -50,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,9 @@
-# typed: false
+# typed: strict
 # frozen_string_literal: true
 
 module Nexmo
   class Alerts < Namespace
+    extend T::Sig
     self.host = :rest_host
 
     # Request the list of phone numbers opted out from your campaign.
@@ -11,6 +12,7 @@ module Nexmo
     #
     # @return [Response]
     #
+    sig { returns(Nexmo::Response) }
     def list
       request('/sc/us/alert/opt-in/query/json')
     end
@@ -26,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
@@ -61,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,8 +1,9 @@
-# typed: false
+# typed: strict
 # frozen_string_literal: true
 
 module Nexmo
   class Applications < Namespace
+    extend T::Sig
     self.authentication = Basic
 
     self.request_body = JSON
@@ -14,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)
@@ -38,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
@@ -62,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
@@ -77,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
@@ -104,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
@@ -121,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/client.rb

@@ -1,113 +1,134 @@
-# typed: false
+# 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/config.rb

@@ -1,26 +1,30 @@
-# typed: false
+# typed: true
 # frozen_string_literal: true
 require 'logger'
 
 module Nexmo
   class Config
+    extend T::Sig
+
+    sig { void }
     def initialize
       self.api_host = 'api.nexmo.com'
-      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_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?
 
@@ -29,6 +33,7 @@ module Nexmo
       end
     end
 
+    sig { returns(String) }
     attr_accessor :api_host
 
     # Returns the value of attribute api_key.
@@ -37,7 +42,9 @@ module Nexmo
     #
     # @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, ' \
@@ -47,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.
@@ -55,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, ' \
@@ -65,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.
@@ -73,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. ' \
@@ -85,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.
@@ -119,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. ' \
@@ -131,8 +154,10 @@ 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.
@@ -141,7 +166,9 @@ module Nexmo
     #
     # @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. ' \
@@ -152,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