nexmo 5.8.0 → 5.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +1 -1
  3. data/lib/nexmo.rb +1 -1
  4. data/lib/nexmo/account.rb +36 -1
  5. data/lib/nexmo/alerts.rb +46 -0
  6. data/lib/nexmo/applications.rb +118 -0
  7. data/lib/nexmo/applications_v2.rb +71 -0
  8. data/lib/nexmo/authentication/abstract.rb +3 -1
  9. data/lib/nexmo/authentication/basic.rb +3 -1
  10. data/lib/nexmo/authentication/bearer_token.rb +3 -1
  11. data/lib/nexmo/authentication/key_secret_params.rb +3 -1
  12. data/lib/nexmo/authentication/key_secret_query.rb +3 -1
  13. data/lib/nexmo/call_dtmf.rb +12 -0
  14. data/lib/nexmo/call_stream.rb +26 -0
  15. data/lib/nexmo/call_talk.rb +30 -0
  16. data/lib/nexmo/calls.rb +188 -0
  17. data/lib/nexmo/client.rb +77 -1
  18. data/lib/nexmo/conversation_events.rb +47 -0
  19. data/lib/nexmo/conversation_legs.rb +14 -0
  20. data/lib/nexmo/conversation_members.rb +74 -0
  21. data/lib/nexmo/conversation_users.rb +63 -0
  22. data/lib/nexmo/conversations.rb +110 -0
  23. data/lib/nexmo/errors.rb +41 -0
  24. data/lib/nexmo/errors/error.rb +0 -27
  25. data/lib/nexmo/form_data.rb +3 -1
  26. data/lib/nexmo/http.rb +3 -1
  27. data/lib/nexmo/json.rb +3 -1
  28. data/lib/nexmo/jwt.rb +25 -0
  29. data/lib/nexmo/keys.rb +3 -1
  30. data/lib/nexmo/logger.rb +3 -1
  31. data/lib/nexmo/namespace.rb +4 -2
  32. data/lib/nexmo/number_insight.rb +102 -0
  33. data/lib/nexmo/numbers.rb +155 -0
  34. data/lib/nexmo/params.rb +3 -1
  35. data/lib/nexmo/redact.rb +20 -0
  36. data/lib/nexmo/secrets.rb +53 -0
  37. data/lib/nexmo/signature.rb +24 -13
  38. data/lib/nexmo/sms.rb +88 -0
  39. data/lib/nexmo/user_agent.rb +3 -1
  40. data/lib/nexmo/verify.rb +144 -0
  41. data/lib/nexmo/version.rb +1 -1
  42. data/nexmo.gemspec +2 -0
  43. metadata +31 -3
  44. data/lib/nexmo/problem.rb +0 -20
data/lib/nexmo/params.rb CHANGED
@@ -2,7 +2,7 @@
2
2
  require 'cgi'
3
3
 
4
4
  module Nexmo
5
- module Params # :nodoc:
5
+ module Params
6
6
  def self.encode(params)
7
7
  params.flat_map { |k, vs| Array(vs).map { |v| "#{escape(k)}=#{escape(v)}" } }.join('&')
8
8
  end
@@ -21,4 +21,6 @@ module Nexmo
21
21
 
22
22
  private_class_method :escape
23
23
  end
24
+
25
+ private_constant :Params
24
26
  end
data/lib/nexmo/redact.rb CHANGED
@@ -6,6 +6,26 @@ module Nexmo
6
6
 
7
7
  self.request_body = JSON
8
8
 
9
+ # Redact a specific message.
10
+ #
11
+ # @example
12
+ # response = client.redact.transaction(id: '00A0B0C0', product: 'sms')
13
+ #
14
+ # @option params [required, String] :id
15
+ # The transaction ID to redact.
16
+ #
17
+ # @option params [required, String] :product
18
+ # Product name that the ID provided relates to.
19
+ #
20
+ # @option params [required, String] :type
21
+ # Required if redacting SMS data.
22
+ #
23
+ # @param [Hash] params
24
+ #
25
+ # @return [Entity]
26
+ #
27
+ # @see https://developer.nexmo.com/api/redact#redact-message
28
+ #
9
29
  def transaction(params)
10
30
  request('/v1/redact/transaction', params: params, type: Post)
11
31
  end
data/lib/nexmo/secrets.rb CHANGED
@@ -6,18 +6,71 @@ module Nexmo
6
6
 
7
7
  self.request_body = JSON
8
8
 
9
+ # Create API Secret.
10
+ #
11
+ # @example
12
+ # response = client.secrets.create(secret: 'T0ps3cr3t')
13
+ #
14
+ # @option params [required, String] :secret
15
+ # The new secret must follow these rules:
16
+ # - minimum 8 characters
17
+ # - maximum 25 characters
18
+ # - minimum 1 lower case character
19
+ # - minimum 1 upper case character
20
+ # - minimum 1 digit
21
+ #
22
+ # @param [Hash] params
23
+ #
24
+ # @return [Entity]
25
+ #
26
+ # @see https://developer.nexmo.com/api/account#createAPISecret
27
+ #
9
28
  def create(params)
10
29
  request('/accounts/' + account_id + '/secrets', params: params, type: Post)
11
30
  end
12
31
 
32
+ # Retrieve API Secrets.
33
+ #
34
+ # @example
35
+ # response = client.secrets.list
36
+ # response._embedded.secrets.each do |item|
37
+ # puts "#{item.created_at} #{item.id}"
38
+ # end
39
+ #
40
+ # @return [Entity]
41
+ #
42
+ # @see https://developer.nexmo.com/api/account#retrieveAPISecrets
43
+ #
13
44
  def list
14
45
  request('/accounts/' + account_id + '/secrets')
15
46
  end
16
47
 
48
+ # Retrieve one API Secret.
49
+ #
50
+ # @example
51
+ # response = client.secrets.get(secret_id)
52
+ #
53
+ # @param [String] secret_id
54
+ #
55
+ # @return [Entity]
56
+ #
57
+ # @see https://developer.nexmo.com/api/account#retrieveAPISecret
58
+ #
17
59
  def get(secret_id)
18
60
  request('/accounts/' + account_id + '/secrets/' + secret_id)
19
61
  end
20
62
 
63
+ # Revoke an API Secret.
64
+ #
65
+ # @example
66
+ # response = client.secrets.revoke(secret_id)
67
+ #
68
+ # @param [String] secret_id
69
+ #
70
+ # @return [Entity]
71
+ #
72
+ # @see https://developer.nexmo.com/api/account#revokeAPISecret
73
+ #
21
74
  def revoke(secret_id)
22
75
  request('/accounts/' + account_id + '/secrets/' + secret_id, type: Delete)
23
76
  end
@@ -3,34 +3,45 @@ require 'jwt'
3
3
 
4
4
  module Nexmo
5
5
  class Signature
6
- def self.check(params, secret)
6
+ def initialize(secret)
7
+ @secret = secret
8
+ end
9
+
10
+ # Check webhook request signature.
11
+ #
12
+ # @example
13
+ # client = Nexmo::Client.new(signature_secret: 'secret')
14
+ #
15
+ # if client.signature.check(request.GET)
16
+ # # valid signature
17
+ # else
18
+ # # invalid signature
19
+ # end
20
+ #
21
+ # @param [Hash] params
22
+ #
23
+ # @see https://developer.nexmo.com/concepts/guides/signing-messages
24
+ #
25
+ def check(params)
7
26
  params = params.dup
8
27
 
9
28
  signature = params.delete('sig')
10
29
 
11
- ::JWT::SecurityUtils.secure_compare(signature, digest(params, secret))
12
- end
13
-
14
- def initialize(client)
15
- @client = client
30
+ ::JWT::SecurityUtils.secure_compare(signature, digest(params))
16
31
  end
17
32
 
18
- def check(params)
19
- self.class.check(params, @client.signature_secret)
20
- end
33
+ private
21
34
 
22
- def self.digest(params, secret)
35
+ def digest(params)
23
36
  md5 = Digest::MD5.new
24
37
 
25
38
  params.sort.each do |k, v|
26
39
  md5.update("&#{k}=#{v}")
27
40
  end
28
41
 
29
- md5.update(secret)
42
+ md5.update(@secret)
30
43
 
31
44
  md5.hexdigest
32
45
  end
33
-
34
- private_class_method :digest
35
46
  end
36
47
  end
data/lib/nexmo/sms.rb CHANGED
@@ -6,6 +6,94 @@ module Nexmo
6
6
 
7
7
  self.host = 'rest.nexmo.com'
8
8
 
9
+ # Send an outbound SMS from your Nexmo account.
10
+ #
11
+ # @example
12
+ # response = client.sms.send(from: 'Ruby', to: '447700900000', text: 'Hello world')
13
+ #
14
+ # if response.messages.first.status == '0'
15
+ # puts "Sent message id=#{response.messages.first.message_id}"
16
+ # else
17
+ # puts "Error: #{response.messages.first.error_text}"
18
+ # end
19
+ #
20
+ # @option params [required, String] :from
21
+ # The name or number the message should be sent from.
22
+ # 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.
23
+ # If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.
24
+ #
25
+ # @option params [required, String] :to
26
+ # The number that the message should be sent to.
27
+ # Numbers are specified in E.164 format.
28
+ #
29
+ # @option params [String] :text
30
+ # The body of the message being sent.
31
+ # 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`.
32
+ # If your message contains characters outside this range, then you will need to set the **:type** to `unicode`.
33
+ #
34
+ # @option params [Integer] :ttl
35
+ # The duration in milliseconds the delivery of an SMS will be attempted.
36
+ # By default Nexmo attempt delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours.
37
+ # We recommend this value should be kept at its default or at least 30 minutes.
38
+ #
39
+ # @option params [Boolean] :status_report_req
40
+ # Boolean indicating if you like to receive a [Delivery Receipt](https://developer.nexmo.com/messaging/sms/building-blocks/receive-a-delivery-receipt).
41
+ #
42
+ # @option params [String] :callback
43
+ # The webhook endpoint the delivery receipt for this sms is sent to.
44
+ # This parameter overrides the webhook endpoint you set in Dashboard.
45
+ #
46
+ # @option params [Integer] :message_class
47
+ # The Data Coding Scheme value of the message.
48
+ #
49
+ # @option params [String] :type
50
+ # The format of the message body.
51
+ #
52
+ # @option params [String] :vcard
53
+ # A business card in [vCard format](https://en.wikipedia.org/wiki/VCard).
54
+ # Depends on **:type** option having the value `vcard`.
55
+ #
56
+ # @option params [String] :vcal
57
+ # A calendar event in [vCal format](https://en.wikipedia.org/wiki/VCal).
58
+ # Depends on **:type** option having the value `vcal`.
59
+ #
60
+ # @option params [String] :body
61
+ # Hex encoded binary data.
62
+ # Depends on **:type** option having the value `binary`.
63
+ #
64
+ # @option params [String] :udh
65
+ # Your custom Hex encoded [User Data Header](https://en.wikipedia.org/wiki/User_Data_Header).
66
+ # Depends on **:type** option having the value `binary`.
67
+ #
68
+ # @option params [Integer] :protocol_id
69
+ # The value of the [protocol identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier) to use.
70
+ # Ensure that the value is aligned with **:udh**.
71
+ #
72
+ # @option params [String] :title
73
+ # The title for a wappush SMS.
74
+ # Depends on **:type** option having the value `wappush`.
75
+ #
76
+ # @option params [String] :url
77
+ # The URL of your website.
78
+ # Depends on **:type** option having the value `wappush`.
79
+ #
80
+ # @option params [String] :validity
81
+ # The availability for an SMS in milliseconds.
82
+ # Depends on **:type** option having the value `wappush`.
83
+ #
84
+ # @option params [String] :client_ref
85
+ # You can optionally include your own reference of up to 40 characters.
86
+ #
87
+ # @option params [String] :account_ref
88
+ # An optional string used to identify separate accounts using the SMS endpoint for billing purposes.
89
+ # To use this feature, please email [support@nexmo.com](mailto:support@nexmo.com).
90
+ #
91
+ # @param [Hash] params
92
+ #
93
+ # @return [Entity]
94
+ #
95
+ # @see https://developer.nexmo.com/api/sms#send-an-sms
96
+ #
9
97
  def send(params)
10
98
  request('/sms/json', params: hyphenate(params), type: Post)
11
99
  end
@@ -1,7 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Nexmo
4
- module UserAgent # :nodoc:
4
+ module UserAgent
5
5
  def self.string(app_name, app_version)
6
6
  identifiers = []
7
7
  identifiers << 'nexmo-ruby/' + VERSION
@@ -10,4 +10,6 @@ module Nexmo
10
10
  identifiers.join(' ')
11
11
  end
12
12
  end
13
+
14
+ private_constant :UserAgent
13
15
  end
data/lib/nexmo/verify.rb CHANGED
@@ -4,26 +4,170 @@ module Nexmo
4
4
  class Verify < Namespace
5
5
  alias_method :http_request, :request
6
6
 
7
+ private :http_request
8
+
9
+ # Generate and send a PIN to your user.
10
+ #
11
+ # @note You can make a maximum of one Verify request per second.
12
+ #
13
+ # @example
14
+ # response = client.verify.request(number: '447700900000', brand: 'Acme Inc')
15
+ #
16
+ # if response.status == '0'
17
+ # puts "Started verification request_id=#{response.request_id}"
18
+ # else
19
+ # puts "Error: #{response.error_text}"
20
+ # end
21
+ #
22
+ # @option params [required, String] :number
23
+ # The mobile or landline phone number to verify.
24
+ # Unless you are setting **:country** explicitly, this number must be in E.164 format.
25
+ #
26
+ # @option params [String] :country
27
+ # 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**.
28
+ # Verify will then format the number for you.
29
+ #
30
+ # @option params [required, String] :brand
31
+ # An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name.
32
+ # For example: "Your `Acme Inc` PIN is ..."
33
+ #
34
+ # @option params [String] :sender_id
35
+ # 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.
36
+ # Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.
37
+ #
38
+ # @option params [Integer] :code_length
39
+ # The length of the verification code.
40
+ #
41
+ # @option params [String] :lg
42
+ # By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the **:number**.
43
+ # For example, the text message or TTS message for a `33*` number is sent in French.
44
+ # Use this parameter to explicitly control the language, accent and gender used for the Verify request.
45
+ #
46
+ # @option params [Integer] :pin_expiry
47
+ # How log the generated verification code is valid for, in seconds.
48
+ # 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**.
49
+ # See [changing the event timings](https://developer.nexmo.com/verify/guides/changing-default-timings).
50
+ #
51
+ # @option params [Integer] :next_event_wait
52
+ # Specifies the wait time in seconds between attempts to deliver the verification code.
53
+ #
54
+ # @option params [Integer] :workflow_id
55
+ # Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user.
56
+ # For example, an id of 1 identifies the workflow SMS - TTS - TTS.
57
+ # For a list of all workflows and their associated ids, please visit the [developer portal](https://developer.nexmo.com/verify/guides/workflows-and-events).
58
+ #
59
+ # @param [Hash] params
60
+ #
61
+ # @return [Entity]
62
+ #
63
+ # @see https://developer.nexmo.com/api/verify#verifyRequest
64
+ #
7
65
  def request(params)
8
66
  http_request('/verify/json', params: params, type: Post)
9
67
  end
10
68
 
69
+ # Confirm that the PIN you received from your user matches the one sent by Nexmo in your verification request.
70
+ #
71
+ # @example
72
+ # response = client.verify.check(request_id: request_id, code: '1234')
73
+ #
74
+ # if response.status == '0'
75
+ # puts "Verification complete, event_id=#{response.event_id}"
76
+ # else
77
+ # puts "Error: #{response.error_text}"
78
+ # end
79
+ #
80
+ # @option params [required, String] :request_id
81
+ # The Verify request to check.
82
+ # This is the `request_id` you received in the response to the Verify request.
83
+ #
84
+ # @option params [required, String] :code
85
+ # The verification code entered by your user.
86
+ #
87
+ # @option params [String] :ip_address
88
+ # The IP address used by your user when they entered the verification code.
89
+ # Nexmo uses this information to identify fraud and spam. This ultimately benefits all Nexmo customers.
90
+ #
91
+ # @param [Hash] params
92
+ #
93
+ # @return [Entity]
94
+ #
95
+ # @see https://developer.nexmo.com/api/verify#verifyCheck
96
+ #
11
97
  def check(params)
12
98
  http_request('/verify/check/json', params: params, type: Post)
13
99
  end
14
100
 
101
+ # Check the status of past or current verification requests.
102
+ #
103
+ # @example
104
+ # response = client.verify.search(request_id: request_id)
105
+ #
106
+ # @option params [String] :request_id
107
+ # The `request_id` you received in the Verify Request Response.
108
+ #
109
+ # @option params [Array<string>] :request_ids
110
+ # More than one `request_id`.
111
+ # Each `request_id` is a new parameter in the Verify Search request.
112
+ #
113
+ # @param [Hash] params
114
+ #
115
+ # @return [Entity]
116
+ #
117
+ # @see https://developer.nexmo.com/api/verify#verifySearch
118
+ #
15
119
  def search(params)
16
120
  http_request('/verify/search/json', params: params)
17
121
  end
18
122
 
123
+ # Control the progress of your verification requests.
124
+ #
125
+ # @example
126
+ # response = client.verify.control(request_id: request_id, cmd: 'cancel')
127
+ #
128
+ # @option params [required, String] :request_id
129
+ # The `request_id` you received in the response to the Verify request.
130
+ #
131
+ # @option params [required, String] :cmd
132
+ # The command to execute, depending on whether you want to cancel the verification process, or advance to the next verification event.
133
+ # You must wait at least 30 seconds before cancelling a Verify request.
134
+ #
135
+ # @param [Hash] params
136
+ #
137
+ # @return [Entity]
138
+ #
139
+ # @see https://developer.nexmo.com/api/verify#verifyControl
140
+ #
19
141
  def control(params)
20
142
  http_request('/verify/control/json', params: params, type: Post)
21
143
  end
22
144
 
145
+ # Cancel an existing verification request.
146
+ #
147
+ # @example
148
+ # response = client.verify.cancel(request_id)
149
+ #
150
+ # @param [String] id
151
+ #
152
+ # @return [Entity]
153
+ #
154
+ # @see https://developer.nexmo.com/api/verify#verifyControl
155
+ #
23
156
  def cancel(id)
24
157
  control(request_id: id, cmd: 'cancel')
25
158
  end
26
159
 
160
+ # Trigger the next verification event for an existing verification request.
161
+ #
162
+ # @example
163
+ # response = client.verify.trigger_next_event(request_id)
164
+ #
165
+ # @param [String] id
166
+ #
167
+ # @return [Entity]
168
+ #
169
+ # @see https://developer.nexmo.com/api/verify#verifyControl
170
+ #
27
171
  def trigger_next_event(id)
28
172
  control(request_id: id, cmd: 'trigger_next_event')
29
173
  end