Merged all v2.0.0 changes, see release notes.

.gitignore

@@ -1,18 +1,8 @@
 *.gem
-*.rbc
-.bundle
-.config
-coverage
-InstalledFiles
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
 
-# YARD artifacts
-.yardoc
-_yardoc
-doc/
+# RubyMine IDE
+.idea
+
+# Other
+.DS_Store
+

LICENSE.txt → LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016 TeleSign Corp.
+Copyright (c) 2017 TeleSign Corp.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.rst

@@ -2,134 +2,78 @@
 TeleSign
 ========
 
-**Information**: For more information, visit the `TeleSign website <http://www.TeleSign.com>`_ or the `TeleSign Developer Portal <https://developer.telesign.com/>`_.
-
-**Author**: Telesign Corp.
-
-TeleSign Web Services: Ruby SDK
----------------------------------
-
-**TeleSign web services** conform to the `REST Web Service Design Model <http://en.wikipedia.org/wiki/Representational_state_transfer>`_. Services are exposed as URI-addressable resources through the set of *RESTful* procedures in our **TeleSign REST API**.
-
-The **TeleSign Ruby SDK** is a set of software development tools—a *Ruby Library* that wraps the TeleSign REST API, and it simplifies TeleSign application development in the `Ruby programming language <https://www.ruby-lang.org/>`_. The SDK software is packaged as a Ruby gem called **telesign**, and is distributed using `Ruby Gems <https://rubygems.org/>`_.
-
-The Ruby Classes
-------------------
-
-With just two classes, **Telesign::API** abstracts much of the complexity of the TeleSign REST API.
-
-+---------------------------+--------------------------------------------------------------------------+
-| Ruby Class                | Description                                                              |
-+===========================+==========================================================================+
-| Telesign::API::PhoneId    | The **PhoneId** class exposes four services that each provide            |
-|                           | information about a specified phone number.                              |
-|                           |                                                                          |
-|                           | *standard*                                                               |
-|                           |     Retrieves the standard set of details about the specified phone      |
-|                           |     number. This includes the type of phone (for example, land line or   |
-|                           |     mobile), and its approximate geographic location.                    |
-|                           | *score*                                                                  |
-|                           |     Retrieves a score for the specified phone number. This ranks the     |
-|                           |     phone number's "risk level" on a scale from 0 to 1000, so you can    |
-|                           |     code your web application to handle particular use cases (for        |
-|                           |     example, to stop things like chargebacks, identity theft, fraud, and |
-|                           |     spam).                                                               |
-|                           | *contact*                                                                |
-|                           |     In addition to the information retrieved by *standard*, this service |
-|                           |     provides the name and address associated with the specified phone    |
-|                           |     number.                                                              |
-|                           | *live*                                                                   |
-|                           |     In addition to the information retrieved by *standard*, this service |
-|                           |     provides actionable data associated with the specified phone number. |
-|                           | *number_deactivation*                                                    |
-|                           |     In addition to the information retrieved by *standard*, this service |
-|                           |     provides information on number deactivation for the phone number     |
-|                           |     provided.                                                            |
-+---------------------------+--------------------------------------------------------------------------+
-| Telesign::API::Verify     | The **Verify** class exposes five services for sending users a           |
-|                           | verification token (a three to five-digit number). You can use this      |
-|                           | mechanism to test whether you can reach users at the phone number        |
-|                           | they supplied, or you can have them use the token to authenticate        |
-|                           | themselves with your web application. In addition, this class also       |
-|                           | exposes a service that allows you to confirm the result of the           |
-|                           | authentication.                                                          |
-|                           |                                                                          |
-|                           | You can use this verification factor in combination with *username*      |
-|                           | and *password* to provide *two-factor* authentication for higher         |
-|                           | security.                                                                |
-|                           |                                                                          |
-|                           | *call*                                                                   |
-|                           |     Calls the specified phone number and uses speech synthesis to speak  |
-|                           |     the verification code to the user.                                   |
-|                           | *sms*                                                                    |
-|                           |     Sends a text message containing the verification code to the         |
-|                           |     specified phone number (supported for mobile phones only).           |
-|                           | *smart*                                                                  |
-|                           |     Smart intelligently determines the best service to use based on      |
-|                           |     the end user device and then attempts to place a call, send an SMS,  |
-|                           |     or send a push request.                                              |
-|                           | *push*                                                                   |
-|                           |     Sends a push notification containing the verification code to the    |
-|                           |     specified phone number (supported for registered devices only).      |
-|                           | *status*                                                                 |
-|                           |     Retrieves the verification result. You make this call in your web    |
-|                           |     application after users complete the authentication transaction      |
-|                           |     (using either a *call* or *sms*).                                    |
-|                           |                                                                          |
-+---------------------------+--------------------------------------------------------------------------+
-| Telesign::API::TeleBureau | The **Telebureau** class exposes services for creating, retrieving,      |
-|                           | updating and deleting telebureau fraud events. You can use this          |
-|                           | mechanism to test whether you can reach Telebureau services.             |
-|                           |                                                                          |
-|                           | *create*                                                                 |
-|                           |    Creates a Telebureau event corresponding to supplied data.            |
-|                           | *retrieve*                                                               |
-|                           |    Retrieves the fraud event status. You make this call in your web      |
-|                           |    application after completion of create/update transaction for a       |
-|                           |    Telebureau event.                                                     |
-|                           | *delete*                                                                 |
-|                           |    Deletes a previously submitted fraud event. You make this call in     |
-|                           |    your web application after completion of submit/update transaction    |
-|                           |    for a Telebureau event.                                               |
-|                           |                                                                          |
-+---------------------------+--------------------------------------------------------------------------+
+TeleSign provides the world’s most comprehensive approach to account security for Web and mobile applications.
+
+For more information about TeleSign, visit the `TeleSign website <http://www.TeleSign.com>`_.
+
+TeleSign REST API: Ruby SDK
+---------------------------
+
+**TeleSign web services** conform to the `REST Web Service Design Model
+<http://en.wikipedia.org/wiki/Representational_state_transfer>`_. Services are exposed as URI-addressable resources
+through the set of *RESTful* procedures in our **TeleSign REST API**.
+
+The **TeleSign Ruby SDK** is a set modules and functions — a *Ruby Library* that wraps the
+TeleSign REST API, and it simplifies TeleSign application development in the `Ruby programming language
+<https://www.ruby-lang.org>`_. The SDK software is distributed on
+`GitHub <https://github.com/TeleSign/ruby_telesign>`_ and also as a Ruby Gem using `Ruby Gems <https://rubygems.org>`_.
+
+Documentation
+-------------
+
+Detailed documentation for TeleSign REST APIs is available in the `Developer Portal <https://developer.telesign.com/>`_.
 
 Installation
 ------------
 
-With `Ruby Gems <https://github.com/rubygems/rubygems>`_
-installed, type **gem install telesign** at the command prompt.
+To install the TeleSign Ruby SDK:
+
+.. code-block:: bash
 
-Ruby Code Example: To Verify a Call
--------------------------------------
+    $ gem install telesign
 
-Here's a basic code example.
+Alternatively, you can download the project source, and execute **gem build telesign.gemspec && gem install telesign-[version].gem**.
 
-::
+Ruby Code Example: Messaging
+----------------------------
+
+Here's a basic code example with JSON response.
+
+.. code-block:: ruby
 
     require 'telesign'
-    phone_number = "13103409700"
-    cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
-    secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
-    verify = Telesign::API::Verify.new(cust_id, secret_key) # Instantiate a Verify instance object,
-    result = verify.call(phone_number) # and use it to call the "call" method.
-    p result.body
 
-    {"reference_id"=>"254CADA5F1D40E0090405467DE244D05", "resource_uri"=>"/v1/verify/254CADA5F1D40E0090405467DE244D05", "sub_resource"=>"call", "errors"=>[], "verify"=>{"code_state"=>"UNKNOWN", "code_entered"=>""}, "status"=>{"updated_on"=>"2016-02-29T05:04:06.814381Z", "code"=>103, "description"=>"Call in progress"}}
+    customer_id = 'customer_id'
+    secret_key = 'secret_key'
 
-For more examples, see the Documentation section below.
+    phone_number = 'phone_number'
+    message = 'You\'re scheduled for a dentist appointment at 2:30PM.'
+    message_type = 'ARN'
 
-Authentication
--------------
+    messaging_client = Telesign::MessagingClient.new(customer_id, secret_key)
+    response = messaging_client.message(phone_number, message, message_type)
 
-You will need a Customer ID and API Key in order to use TeleSign’s REST API.  If you are already a customer and need an API Key, you can generate one in `TelePortal <https://teleportal.telesign.com>`_.  If you are not a customer and would like to get an API Key, please contact `[email protected] <mailto:[email protected]>`_
+.. code-block:: javascript
+
+    {"reference_id"=>"B56A497C9A74016489525132F8840634",
+     "status"=>
+      {"updated_on"=>"2017-03-03T04:13:14.028347Z",
+       "code"=>103,
+       "description"=>"Call in progress"}}
+
+For more examples, see the examples folder or visit `TeleSign Developer Portal <https://developer.telesign.com/>`_.
+
+Authentication
+--------------
 
+You will need a Customer ID and API Key in order to use TeleSign’s REST API. If you are already a customer and need an
+API Key, you can generate one in the `Portal <https://portal.telesign.com>`_.
 
-Support and Feedback
---------------------
+Testing
+-------
 
-For more information about the Phone Verify and PhoneID Standard services, please contact your TeleSign representative:
+To run the Ruby SDK test suite:
 
-Email: `[email protected] <mailto:[email protected]>`_
+.. code-block:: bash
 
-Phone: +1 310 740 9700
+    $ rake test

RELEASE

@@ -0,0 +1,18 @@
+2.0.0
+
+- Major refactor and simplification into generic REST client.
+- API parameters are now passed as kwargs to endpoint handlers.
+- UserAgent is now set to track client usage and help debug issues.
+- generate_telesign_headers is now static and easily extracted from the SDK if
+  custom behavior/implementation is required.
+- Now using net/http/persistent to take advantage of http connection pooling for performance,
+  thread safety and graceful reconnects
+
+1.0.2
+
+- Fixed gem imports
+- Added number_deactivation and telebureau create, retrieve and delete endpoints.
+
+1.0.0
+
+- Initial version supporting commonly used Telesign endpoints.

Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end

examples/autoverify/1_get_status_by_external_id.rb

@@ -0,0 +1,16 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+external_id = 'external_id'
+
+av_client = Telesign::AutoVerifyClient.new(customer_id, secret_key)
+response = av_client.status(external_id)
+
+if response.ok
+    puts 'AutoVerify transaction with external_id %s has status code %s and status description %s.' %
+        [external_id,
+        response.json['status']['code'],
+        response.json['status']['description']]
+end

examples/messaging/1_send_message.rb

@@ -0,0 +1,11 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+phone_number = 'phone_number'
+message = 'You\'re scheduled for a dentist appointment at 2:30PM.'
+message_type = 'ARN'
+
+messaging_client = Telesign::MessagingClient.new(customer_id, secret_key)
+response = messaging_client.message(phone_number, message, message_type)

examples/messaging/2_send_message_with_verification_code.rb

@@ -0,0 +1,21 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+phone_number = 'phone_number'
+verify_code = Telesign::Util.random_with_n_digits(5)
+message = "Your code is #{verify_code}"
+message_type = 'OTP'
+
+messaging_client = Telesign::MessagingClient.new(customer_id, secret_key)
+response = messaging_client.message(phone_number, message, message_type)
+
+print 'Please enter the verification code you were sent: '
+user_entered_verify_code = gets.strip
+
+if verify_code == user_entered_verify_code
+    puts 'Your code is correct.'
+else
+    puts 'Your code is incorrect.'
+end

examples/phoneid/1_check_phone_type_to_block_voip.rb

@@ -0,0 +1,18 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+phone_number = 'phone_number'
+phone_type_voip = '5'
+
+phoneid_client = Telesign::PhoneIdClient.new(customer_id, secret_key)
+response = phoneid_client.phoneid(phone_number)
+
+if response.ok
+    if response.json['phone_type']['code'] == phone_type_voip
+        puts "Phone number #{phone_number} is a VOIP phone."
+    else
+        puts "Phone number #{phone_number} is not a VOIP phone."
+    end
+end

examples/phoneid/2_cleansing.rb

@@ -0,0 +1,20 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+extra_digit = '0'
+phone_number = 'phone_number'
+incorrect_phone_number = "#{phone_number}#{extra_digit}"
+
+phoneid_client = Telesign::PhoneIdClient.new(customer_id, secret_key)
+response = phoneid_client.phoneid(incorrect_phone_number)
+
+if response.ok
+    puts 'Cleansed phone number has country code %s and phone number is %s.' %
+        [response.json['numbering']['cleansing']['call']['country_code'],
+        response.json['numbering']['cleansing']['call']['phone_number']]
+
+    puts 'Original phone number was %s.' %
+        [response.json['numbering']['original']['complete_phone_number']]
+end

examples/score/1_check_phone_number_risk_level.rb

@@ -0,0 +1,17 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+phone_number = 'phone_number'
+account_lifecycle_event = 'create'
+
+score_client = Telesign::ScoreClient.new(customer_id, secret_key)
+response = score_client.score(phone_number, account_lifecycle_event)
+
+if response.ok
+    puts "Phone number %s has a '%s' risk level and the recommendation is to '%s' the transaction." %
+        [phone_number,
+        response.json['risk']['level'],
+        response.json['risk']['recommendation']]
+end

examples/voice/1_send_voice_call.rb

@@ -0,0 +1,11 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+phone_number = 'phone_number'
+message = 'You\'re scheduled for a dentist appointment at 2:30PM.'
+message_type = 'ARN'
+
+voice_client = Telesign::VoiceClient.new(customer_id, secret_key)
+response = voice_client.call(phone_number, message, message_type)

examples/voice/2_send_voice_call_with_verification_code.rb

@@ -0,0 +1,22 @@
+require 'telesign'
+
+customer_id = 'customer_id'
+secret_key = 'secret_key'
+
+phone_number = 'phone_number'
+verify_code = Telesign::Util.random_with_n_digits(5)
+verify_code_with_commas = verify_code.chars.join(', ')
+message = "Hello, your code is #{verify_code_with_commas}. Once again, your code is #{verify_code_with_commas}. Goodbye."
+message_type = 'OTP'
+
+voice_client = Telesign::VoiceClient.new(customer_id, secret_key)
+response = voice_client.call(phone_number, message, message_type)
+
+print 'Please enter the verification code you were sent: '
+user_entered_verify_code = gets.strip
+
+if verify_code == user_entered_verify_code
+    puts 'Your code is correct.'
+else
+    puts 'Your code is incorrect.'
+end