nexmo 5.8.0 → 5.9.0

data/lib/nexmo/params.rb

@@ -2,7 +2,7 @@
 require 'cgi'
 
 module Nexmo
-  module Params # :nodoc:
+  module Params
     def self.encode(params)
       params.flat_map { |k, vs| Array(vs).map { |v| "#{escape(k)}=#{escape(v)}" } }.join('&')
     end
@@ -21,4 +21,6 @@ module Nexmo
 
     private_class_method :escape
   end
+
+  private_constant :Params
 end

data/lib/nexmo/redact.rb

@@ -6,6 +6,26 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Redact a specific message.
+    #
+    # @example
+    #   response = client.redact.transaction(id: '00A0B0C0', product: 'sms')
+    #
+    # @option params [required, String] :id
+    #   The transaction ID to redact.
+    #
+    # @option params [required, String] :product
+    #   Product name that the ID provided relates to.
+    #
+    # @option params [required, String] :type
+    #   Required if redacting SMS data.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/redact#redact-message
+    #
     def transaction(params)
       request('/v1/redact/transaction', params: params, type: Post)
     end

data/lib/nexmo/secrets.rb

@@ -6,18 +6,71 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Create API Secret.
+    #
+    # @example
+    #   response = client.secrets.create(secret: 'T0ps3cr3t')
+    #
+    # @option params [required, String] :secret
+    #   The new secret must follow these rules:
+    #   - minimum 8 characters
+    #   - maximum 25 characters
+    #   - minimum 1 lower case character
+    #   - minimum 1 upper case character
+    #   - minimum 1 digit
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/account#createAPISecret
+    #
     def create(params)
       request('/accounts/' + account_id + '/secrets', params: params, type: Post)
     end
 
+    # Retrieve API Secrets.
+    #
+    # @example
+    #   response = client.secrets.list
+    #   response._embedded.secrets.each do |item|
+    #     puts "#{item.created_at} #{item.id}"
+    #   end
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/account#retrieveAPISecrets
+    #
     def list
       request('/accounts/' + account_id + '/secrets')
     end
 
+    # Retrieve one API Secret.
+    #
+    # @example
+    #   response = client.secrets.get(secret_id)
+    #
+    # @param [String] secret_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/account#retrieveAPISecret
+    #
     def get(secret_id)
       request('/accounts/' + account_id + '/secrets/' + secret_id)
     end
 
+    # Revoke an API Secret.
+    #
+    # @example
+    #   response = client.secrets.revoke(secret_id)
+    #
+    # @param [String] secret_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/account#revokeAPISecret
+    #
     def revoke(secret_id)
       request('/accounts/' + account_id + '/secrets/' + secret_id, type: Delete)
     end

data/lib/nexmo/signature.rb

@@ -3,34 +3,45 @@ require 'jwt'
 
 module Nexmo
   class Signature
-    def self.check(params, secret)
+    def initialize(secret)
+      @secret = secret
+    end
+
+    # Check webhook request signature.
+    #
+    # @example
+    #   client = Nexmo::Client.new(signature_secret: 'secret')
+    #
+    #   if client.signature.check(request.GET)
+    #     # valid signature
+    #   else
+    #     # invalid signature
+    #   end
+    #
+    # @param [Hash] params
+    #
+    # @see https://developer.nexmo.com/concepts/guides/signing-messages
+    #
+    def check(params)
       params = params.dup
 
       signature = params.delete('sig')
 
-      ::JWT::SecurityUtils.secure_compare(signature, digest(params, secret))
-    end
-
-    def initialize(client)
-      @client = client
+      ::JWT::SecurityUtils.secure_compare(signature, digest(params))
     end
 
-    def check(params)
-      self.class.check(params, @client.signature_secret)
-    end
+    private
 
-    def self.digest(params, secret)
+    def digest(params)
       md5 = Digest::MD5.new
 
       params.sort.each do |k, v|
         md5.update("&#{k}=#{v}")
       end
 
-      md5.update(secret)
+      md5.update(@secret)
 
       md5.hexdigest
     end
-
-    private_class_method :digest
   end
 end

data/lib/nexmo/sms.rb

@@ -6,6 +6,94 @@ module Nexmo
 
     self.host = 'rest.nexmo.com'
 
+    # Send an outbound SMS from your Nexmo account.
+    #
+    # @example
+    #   response = client.sms.send(from: 'Ruby', to: '447700900000', text: 'Hello world')
+    #
+    #   if response.messages.first.status == '0'
+    #     puts "Sent message id=#{response.messages.first.message_id}"
+    #   else
+    #     puts "Error: #{response.messages.first.error_text}"
+    #   end
+    #
+    # @option params [required, String] :from
+    #   The name or number the message should be sent from.
+    #   Alphanumeric senderID's are not supported in all countries, see [Global Messaging](https://developer.nexmo.com/messaging/sms/guides/global-messaging#country-specific-features) for more details.
+    #   If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.
+    #
+    # @option params [required, String] :to
+    #   The number that the message should be sent to.
+    #   Numbers are specified in E.164 format.
+    #
+    # @option params [String] :text
+    #   The body of the message being sent.
+    #   If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the **:type** to `text`.
+    #   If your message contains characters outside this range, then you will need to set the **:type** to `unicode`.
+    #
+    # @option params [Integer] :ttl
+    #   The duration in milliseconds the delivery of an SMS will be attempted.
+    #   By default Nexmo attempt delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours.
+    #   We recommend this value should be kept at its default or at least 30 minutes.
+    #
+    # @option params [Boolean] :status_report_req
+    #   Boolean indicating if you like to receive a [Delivery Receipt](https://developer.nexmo.com/messaging/sms/building-blocks/receive-a-delivery-receipt).
+    #
+    # @option params [String] :callback
+    #   The webhook endpoint the delivery receipt for this sms is sent to.
+    #   This parameter overrides the webhook endpoint you set in Dashboard.
+    #
+    # @option params [Integer] :message_class
+    #   The Data Coding Scheme value of the message.
+    #
+    # @option params [String] :type
+    #   The format of the message body.
+    #
+    # @option params [String] :vcard
+    #   A business card in [vCard format](https://en.wikipedia.org/wiki/VCard).
+    #   Depends on **:type** option having the value `vcard`.
+    #
+    # @option params [String] :vcal
+    #   A calendar event in [vCal format](https://en.wikipedia.org/wiki/VCal).
+    #   Depends on **:type** option having the value `vcal`.
+    #
+    # @option params [String] :body
+    #   Hex encoded binary data.
+    #   Depends on **:type** option having the value `binary`.
+    #
+    # @option params [String] :udh
+    #   Your custom Hex encoded [User Data Header](https://en.wikipedia.org/wiki/User_Data_Header).
+    #   Depends on **:type** option having the value `binary`.
+    #
+    # @option params [Integer] :protocol_id
+    #   The value of the [protocol identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier) to use.
+    #   Ensure that the value is aligned with **:udh**.
+    #
+    # @option params [String] :title
+    #   The title for a wappush SMS.
+    #   Depends on **:type** option having the value `wappush`.
+    #
+    # @option params [String] :url
+    #   The URL of your website.
+    #   Depends on **:type** option having the value `wappush`.
+    #
+    # @option params [String] :validity
+    #   The availability for an SMS in milliseconds.
+    #   Depends on **:type** option having the value `wappush`.
+    #
+    # @option params [String] :client_ref
+    #   You can optionally include your own reference of up to 40 characters.
+    #
+    # @option params [String] :account_ref
+    #   An optional string used to identify separate accounts using the SMS endpoint for billing purposes.
+    #   To use this feature, please email [support@nexmo.com](mailto:support@nexmo.com).
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/sms#send-an-sms
+    #
     def send(params)
       request('/sms/json', params: hyphenate(params), type: Post)
     end

data/lib/nexmo/user_agent.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Nexmo
-  module UserAgent # :nodoc:
+  module UserAgent
     def self.string(app_name, app_version)
       identifiers = []
       identifiers << 'nexmo-ruby/' + VERSION
@@ -10,4 +10,6 @@ module Nexmo
       identifiers.join(' ')
     end
   end
+
+  private_constant :UserAgent
 end

data/lib/nexmo/verify.rb

@@ -4,26 +4,170 @@ module Nexmo
   class Verify < Namespace
     alias_method :http_request, :request
 
+    private :http_request
+
+    # Generate and send a PIN to your user.
+    #
+    # @note You can make a maximum of one Verify request per second.
+    #
+    # @example
+    #   response = client.verify.request(number: '447700900000', brand: 'Acme Inc')
+    #
+    #   if response.status == '0'
+    #     puts "Started verification request_id=#{response.request_id}"
+    #   else
+    #     puts "Error: #{response.error_text}"
+    #   end
+    #
+    # @option params [required, String] :number
+    #   The mobile or landline phone number to verify.
+    #   Unless you are setting **:country** explicitly, this number must be in E.164 format.
+    #
+    # @option params [String] :country
+    #   If you do not provide **:number** in international format or you are not sure if **:number** is correctly formatted, specify the two-character country code in **:country**.
+    #   Verify will then format the number for you.
+    #
+    # @option params [required, String] :brand
+    #   An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name.
+    #   For example: "Your `Acme Inc` PIN is ..."
+    #
+    # @option params [String] :sender_id
+    #   An 11-character alphanumeric string that represents the [identity of the sender](https://developer.nexmo.com/messaging/sms/guides/custom-sender-id) of the verification request.
+    #   Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.
+    #
+    # @option params [Integer] :code_length
+    #   The length of the verification code.
+    #
+    # @option params [String] :lg
+    #   By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the **:number**.
+    #   For example, the text message or TTS message for a `33*` number is sent in French.
+    #   Use this parameter to explicitly control the language, accent and gender used for the Verify request.
+    #
+    # @option params [Integer] :pin_expiry
+    #   How log the generated verification code is valid for, in seconds.
+    #   When you specify both **:pin_expiry** and **:next_event_wait** then **:pin_expiry** must be an integer multiple of **:next_event_wait** otherwise **:pin_expiry** is defaulted to equal **:next_event_wait**.
+    #   See [changing the event timings](https://developer.nexmo.com/verify/guides/changing-default-timings).
+    #
+    # @option params [Integer] :next_event_wait
+    #   Specifies the wait time in seconds between attempts to deliver the verification code.
+    #
+    # @option params [Integer] :workflow_id
+    #   Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user.
+    #   For example, an id of 1 identifies the workflow SMS - TTS - TTS.
+    #   For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/guides/workflows-and-events).
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/verify#verifyRequest
+    #
     def request(params)
       http_request('/verify/json', params: params, type: Post)
     end
 
+    # Confirm that the PIN you received from your user matches the one sent by Nexmo in your verification request.
+    #
+    # @example
+    #   response = client.verify.check(request_id: request_id, code: '1234')
+    #
+    #   if response.status == '0'
+    #     puts "Verification complete, event_id=#{response.event_id}"
+    #   else
+    #     puts "Error: #{response.error_text}"
+    #   end
+    #
+    # @option params [required, String] :request_id
+    #   The Verify request to check.
+    #   This is the `request_id` you received in the response to the Verify request.
+    #
+    # @option params [required, String] :code
+    #   The verification code entered by your user.
+    #
+    # @option params [String] :ip_address
+    #   The IP address used by your user when they entered the verification code.
+    #   Nexmo uses this information to identify fraud and spam. This ultimately benefits all Nexmo customers.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/verify#verifyCheck
+    #
     def check(params)
       http_request('/verify/check/json', params: params, type: Post)
     end
 
+    # Check the status of past or current verification requests.
+    #
+    # @example
+    #   response = client.verify.search(request_id: request_id)
+    #
+    # @option params [String] :request_id
+    #   The `request_id` you received in the Verify Request Response.
+    #
+    # @option params [Array<string>] :request_ids
+    #   More than one `request_id`.
+    #   Each `request_id` is a new parameter in the Verify Search request.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/verify#verifySearch
+    #
     def search(params)
       http_request('/verify/search/json', params: params)
     end
 
+    # Control the progress of your verification requests.
+    #
+    # @example
+    #   response = client.verify.control(request_id: request_id, cmd: 'cancel')
+    #
+    # @option params [required, String] :request_id
+    #   The `request_id` you received in the response to the Verify request.
+    #
+    # @option params [required, String] :cmd
+    #   The command to execute, depending on whether you want to cancel the verification process, or advance to the next verification event.
+    #   You must wait at least 30 seconds before cancelling a Verify request.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/verify#verifyControl
+    #
     def control(params)
       http_request('/verify/control/json', params: params, type: Post)
     end
 
+    # Cancel an existing verification request.
+    #
+    # @example
+    #   response = client.verify.cancel(request_id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/verify#verifyControl
+    #
     def cancel(id)
       control(request_id: id, cmd: 'cancel')
     end
 
+    # Trigger the next verification event for an existing verification request.
+    #
+    # @example
+    #   response = client.verify.trigger_next_event(request_id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/verify#verifyControl
+    #
     def trigger_next_event(id)
       control(request_id: id, cmd: 'trigger_next_event')
     end