telesign_lib 0.0.12

data/lib/telesign/phone_id.rb

@@ -0,0 +1,225 @@
+module TeleSign
+  class PhoneId
+    include Helpers
+
+    attr_accessor :conn, :customer_id, :secret_key
+
+    def initialize opts = {}
+      @conn = opts[:conn]
+      @customer_id = opts[:customer_id]
+      @secret_key = opts[:secret_key]
+    end
+
+    def standard phone_number
+      # Retrieves the standard set of details about the specified phone number.
+      # This includes the type of phone (e.g., land line or mobile),
+      # and it's approximate geographic location.
+
+      #    * - Parameters
+      #      -
+      #    * - `phone_number`
+      #      - The phone number you want details about. You must specify the phone number
+      #        in its entirety. That is, it must begin with the country code, followed by
+      #        the area code, and then by the local number.
+      #        For example, you would specify the phone number (310) 555-1212 as 13105551212.
+
+      # **Example**::
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+
+      #     phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
+
+      #     try:
+      #         phone_info = phoneid.standard(phone_number)
+
+      #     except AuthorizationError as ex:
+      #         # API authorization failed. Check the API response for details.
+      #         ...
+
+      #     except TeleSignError as ex:
+      #         # Failed to completely execute the PhoneID service. Check the API response
+      #         # for details. Data returned might be incomplete or invalid.
+      #         ...
+
+      resource = "/v1/phoneid/standard/%s" % phone_number
+      method = 'GET'
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method)
+
+      response = @conn.get do |req|
+          req.url resource
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response
+    end
+
+    def score phone_number, use_case_code
+      # 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
+      # (e.g., to stop things like chargebacks, identity theft, fraud, and spam).
+
+      #    * - Parameters
+      #      -
+      #    * - `phone_number`
+      #      - The phone number you want details about. You must specify the phone number in its entirety.
+      #        That is, it must begin with the country code, followed by the area code, and then by the local number.
+      #        For example, you would specify the phone number (310) 555-1212 as 13105551212.
+      #    * - `use_case_code`
+      #      - A four letter code used to specify a particular usage scenario for the web service.
+
+      # The following table list the available use-case codes, and includes a description of each.
+
+      # http://docs.telesign.com/rest/content/xt/xt-use-case-codes.html#xref-use-case-codes
+
+      # **Example**::
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+      #     use_case_code = "ATCK"
+
+      #     phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
+
+      #     try:
+      #         score_info = phoneid.score(phone_number, use_case_code)
+      #     except AuthorizationError as ex:
+      #         ...
+      #     except TeleSignError as ex:
+      #         ...
+
+      resource = "/v1/phoneid/score/%s" % phone_number
+      method = 'GET'
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method)
+
+      response = @conn.get do |req|
+          req.url resource
+          req.params[:ucid] = use_case_code
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response
+    end
+
+    def contact phone_number, use_case_code
+      # In addition to the information retrieved by **standard**,
+      # this service provides the Name & Address associated with the specified phone number.
+
+      #    * - Parameters
+      #      -
+      #    * - `phone_number`
+      #      - The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
+      #    * - `use_case_code`
+      #      - A four letter code used to specify a particular usage scenario for the web service.
+
+      # http://docs.telesign.com/rest/content/xt/xt-use-case-codes.html#xref-use-case-codes
+
+      # **Example**::
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+      #     use_case_code = "LEAD"
+
+      #     phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
+
+      #     try:
+      #         phone_info = phoneid.contact(phone_number, use_case_code)
+      #     except AuthorizationError as ex:
+      #         # API authorization failed, the API response should tell you the reason
+      #         ...
+      #     except TeleSignError as ex:
+      #         # failed to completely execute the PhoneID service, check the API response
+      #         #    for details; data returned may be incomplete or not be valid
+      #         ...
+
+      resource = "/v1/phoneid/contact/%s" % phone_number
+      method = 'GET'
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method)
+
+      response = @conn.get do |req|
+          req.url resource
+          req.params[:ucid] = use_case_code
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response
+    end
+
+    def live phone_number, use_case_code
+      # In addition to the information retrieved by **standard**,
+      # this service provides actionable data associated with the specified phone number.
+
+      #    * - Parameters
+      #      -
+      #    * - `phone_number`
+      #      - The phone number you want details about. You must specify the phone number in its entirety.
+      #        That is, it must begin with the country code, followed by the area code,
+      #        and then by the local number.
+      #        For example, you would specify the phone number (310) 555-1212 as 13105551212.
+      #    * - `use_case_code`
+      #      - A four letter code used to specify a particular usage scenario for the web service.
+
+      # The following table list the available use-case codes, and includes a description of each.
+
+      # http://docs.telesign.com/rest/content/xt/xt-use-case-codes.html#xref-use-case-codes
+
+      # **Example**::
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+      #     use_case_code = "RXPF"
+
+      #     phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
+
+      #     try:
+      #         phone_info = phoneid.live(phone_number, use_case_code)
+      #     except AuthorizationError as ex:
+      #         # API authorization failed, the API response should tell you the reason
+      #         ...
+      #     except TeleSignError as ex:
+      #         # failed to completely execute the PhoneID service, check the API response
+      #         #    for details; data returned may be incomplete or not be valid
+      #         ...
+
+      resource = "/v1/phoneid/live/%s" % phone_number
+      method = 'GET'
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method)
+
+      response = @conn.get do |req|
+          req.url resource
+          req.params[:ucid] = use_case_code
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response
+    end
+  end
+end

data/lib/telesign/response.rb

@@ -0,0 +1,13 @@
+module TeleSign
+  class Response
+    attr_accessor :data, :headers, :status, :raw_data, :verify_code
+
+    def initialize data, http_response, verify_code=nil
+      @data = data
+      @headers = http_response.headers
+      @status = http_response.status
+      @raw_data = http_response.body
+      @verify_code = verify_code
+    end
+  end
+end

data/lib/telesign/telesign_error.rb

@@ -0,0 +1,26 @@
+module TeleSign
+  class TeleSignError < ::StandardError
+    # The **exceptions** base class.
+
+    #    * - Attributes
+    #      -
+    #    * - `data`
+    #      - The data returned by the service, in a dictionary form.
+    #    * - `http_response`
+    #      - The full HTTP Response object, including the HTTP status code, headers, and raw returned data.
+
+    attr_accessor :errors, :headers, :status, :data
+
+    def initialize response_json, http_response
+      @errors = response_json['errors']
+      @headers = http_response.headers
+      @status = http_response.status
+      @data = http_response.body
+      super()
+    end
+
+    def to_s
+      @errors.inject(''){|ret, x| ret += "#{x['description']}\n" }
+    end
+  end
+end

data/lib/telesign/validation_error.rb

@@ -0,0 +1,19 @@
+module TeleSign
+  class ValidationError < TeleSignError
+    # """
+    # The submitted data failed the intial validation, and the service was not executed.
+
+    #    * - Attributes
+    #      -
+    #    * - `data`
+    #      - The data returned by the service, in a dictionary form.
+    #    * - `http_response`
+    #      - The full HTTP Response object, including the HTTP status code, headers, and raw returned data.
+
+    # """
+
+    def initialize errors, http_response
+      super
+    end
+  end
+end

data/lib/telesign/verify.rb

@@ -0,0 +1,231 @@
+module TeleSign
+  class Verify
+    include Helpers
+
+    attr_accessor :conn, :customer_id, :secret_key
+
+    def initialize opts = {}
+      @conn = opts[:conn]
+      @customer_id = opts[:customer_id]
+      @secret_key = opts[:secret_key]
+    end
+
+    # The **Verify** class exposes two services for sending users a verification token (a three to five-digit number).
+    # You can use this mechanism to simply 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.
+
+    # This class also exposes a service that is used in conjunction with the first two services,
+    # in that it allows you to confirm the result of the authentication.
+
+    # You can use this verification factor in combination with username & password to provide two-factor authentication for higher security.
+
+    def sms opts = {}
+      phone_number = opts[:phone_number]
+      verify_code = opts[:verify_code]
+      language = opts[:language] || 'en-US'
+      template = opts[:template] || ''
+
+      # Sends a text message containing the verification code, to the specified phone number (supported for mobile phones only).
+
+      #    * - Parameters
+      #      -
+      #    * - `phone_number`
+      #      - The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
+      #    * - `verify_code`
+      #      - (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
+      #    * - `language`
+      #      - (optional) The written language used in the message. The default is English.
+      #    * - `template`
+      #      - (optional) A standard form for the text message. It must contain the token ``$$CODE$$``, which TeleSign auto-populates with the verification code.
+
+      # **Example**::
+
+      #     from telesign.api import Verify
+      #     from telesign.exceptions import AuthorizationError, TeleSignError
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+
+      #     verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
+
+      #     try:
+      #         phone_info = verify.sms(phone_number)
+      #     except AuthorizationError as ex:
+      #         # API authorization failed, the API response should tell you the reason
+      #         ...
+      #     except TeleSignError as ex:
+      #         # failed to execute the Verify service, check the API response for details
+      #         ...
+
+      #     # When the user inputs the validation code, you can verify that it matches the one that you sent.
+      #     if (phone_info != None):
+      #         try:
+      #             status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
+      #         except AuthorizationError as ex:
+      #             ...
+      #         except TeleSignError as ex:
+      #             ...
+
+      if verify_code.nil?
+        verify_code = random_with_N_digits(5)
+      end
+
+      resource = '/v1/verify/sms'
+      method = 'POST'
+
+      fields = {
+          phone_number: phone_number,
+          language: language,
+          verify_code: verify_code,
+          template: template}
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method,
+          fields: fields)
+
+      response = @conn.post do |req|
+          req.url resource
+          req.body = URI.encode_www_form(fields)
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response, verify_code
+    end
+
+    def call opts = {}
+      phone_number = opts[:phone_number]
+      verify_code = opts[:verify_code]
+      language = opts[:language] || 'en-US'
+
+      # Calls the specified phone number, and using speech synthesis, speaks the verification code to the user.
+
+      #    * - Parameters
+      #      -
+      #    * - `phone_number`
+      #      - The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
+      #    * - `verify_code`
+      #      - (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
+      #    * - `language`
+      #      - (optional) The written language used in the message. The default is English.
+
+
+      # **Example**::
+
+      #     from telesign.api import Verify
+      #     from telesign.exceptions import AuthorizationError, TeleSignError
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+
+      #     verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
+
+      #     try:
+      #         phone_info = verify.call(phone_number)
+      #     except AuthorizationError as ex:
+      #         # API authorization failed, the API response should tell you the reason
+      #         ...
+      #     except TeleSignError as ex:
+      #         # failed to execute the Verify service, check the API response for details
+      #         ...
+
+      #     # When the user inputs the validation code, you can verify that it matches the one that you sent.
+      #     if (phone_info != None):
+      #         try:
+      #             status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
+      #         except AuthorizationError as ex:
+      #             ...
+      #         except TeleSignError as ex:
+      #             ...
+
+      if verify_code.nil?
+        verify_code = random_with_N_digits(5)
+      end
+
+      resource = '/v1/verify/call'
+      method = 'POST'
+
+      fields = {
+          phone_number: phone_number,
+          language: language,
+          verify_code: verify_code}
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method,
+          fields: fields)
+
+      response = @conn.post do |req|
+          req.url resource
+          req.body = URI.encode_www_form(fields)
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response, verify_code
+    end
+
+    def status ref_id, verify_code=nil
+      # Retrieves the verification result. You make this call in your web application after users complete the authentication transaction (using either a call or sms).
+
+      #    * - Parameters
+      #      -
+      #    * - `ref_id`
+      #      - The Reference ID returned in the response from the TeleSign server, after you called either **call** or **sms**.
+      #    * - `verify_code`
+      #      - The verification code received from the user.
+
+      # **Example**::
+
+      #     from telesign.api import Verify
+      #     from telesign.exceptions import AuthorizationError, TeleSignError
+
+      #     cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
+      #     secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
+      #     phone_number = "13107409700"
+
+      #     verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
+
+      #     phone_info = verify.sms(phone_number) # Send a text message that contains an auto-generated validation code, to the user.
+
+      #     # When the user inputs the validation code, you can verify that it matches the one that you sent.
+      #     if (phone_info != None):
+      #         try:
+      #             status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
+      #         except AuthorizationError as ex:
+      #             ...
+      #         except TeleSignError as ex:
+      #             ...
+
+      resource = "/v1/verify/%s" % ref_id
+      method = 'GET'
+
+      headers = TeleSign::Auth.generate_auth_headers(
+          customer_id: @customer_id,
+          secret_key: @secret_key,
+          resource: resource,
+          method: method)
+
+      fields = nil
+      if !verify_code.nil?
+        fields = {verify_code: verify_code}
+      end
+
+      response = @conn.get do |req|
+          req.url resource
+          fields.each{|k,v| req.params[k] = v} if fields
+          req.headers = headers
+          # proxies=@proxy
+      end
+
+      return TeleSign::Response.new validate_response(response), response
+    end
+  end
+end

data/lib/telesign/version.rb

@@ -0,0 +1,3 @@
+module TeleSign
+    VERSION = '0.0.12'
+end

data/lib/telesign.rb

@@ -0,0 +1,14 @@
+require 'telesign/version'
+require 'telesign/mock_service/railtie' if defined? Rails
+
+module TeleSign
+  autoload :TeleSignError, 'telesign/telesign_error'
+  autoload :AuthorizationError, 'telesign/authorization_error'
+  autoload :ValidationError, 'telesign/validation_error'
+  autoload :Auth, 'telesign/auth'
+  autoload :Response, 'telesign/response'
+  autoload :Helpers, 'telesign/helpers'
+  autoload :Verify, 'telesign/verify'
+  autoload :PhoneId, 'telesign/phone_id'
+  autoload :Api, 'telesign/api'
+end

data/telesign.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'telesign/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'telesign_lib'
+  spec.version       = TeleSign::VERSION
+  spec.authors       = ['Practice Fusion', 'Andy Koch', 'Andrej Antas']
+  spec.email         = ['akoch@practicefusion.com']
+  spec.description   = %q{Library for comunication with TeleSign REST API}
+  spec.summary       = %q{Client gem for TeleSign REST API}
+  spec.homepage      = 'https://github.com/redrick/ruby_telesign'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^(test)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday', '~> 0.9'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake', '~> 10.4'
+  spec.add_development_dependency 'minitest', '~> 5.5'
+  spec.add_development_dependency 'webmock', '~> 1.20'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'mimic', '~> 0.4'
+end

data/test/auth_test.rb

@@ -0,0 +1,79 @@
+require 'test_helper'
+
+class TestAuth < Minitest::Test
+  def setup
+    @expected_cid = '99999999-1F7E-11E1-B760-000000000000'
+    @expected_secret_key = '8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M8M=='
+    @expected_resource = '/foo/bar/baz/'
+  end
+
+  def test_headers_are_set_on_get
+    TeleSign::Auth.generate_auth_headers(
+            customer_id: @expected_cid,
+            secret_key: @expected_secret_key,
+            resource: @expected_resource,
+            method: 'GET')
+  end
+
+  def test_nonce_is_set
+    expected_nonce = '1234'
+
+    headers = SecureRandom.stub :uuid, expected_nonce do
+      TeleSign::Auth.generate_auth_headers(
+        customer_id: @expected_cid,
+        secret_key: @expected_secret_key,
+        resource: @expected_resource,
+        method: 'GET')
+    end
+
+    assert_equal headers['x-ts-nonce'], expected_nonce
+  end
+
+  def test_date_is_set
+    headers = TeleSign::Auth.generate_auth_headers(
+                customer_id: @expected_cid,
+                secret_key: @expected_secret_key,
+                resource: @expected_resource,
+                method: 'GET')
+
+    # Can't mock datetime
+    refute_match headers['x-ts-date'], nil
+  end
+
+  def test_sha1_default_auth_method
+    expected_auth_method = 'HMAC-SHA1'
+
+    headers = TeleSign::Auth.generate_auth_headers(
+                customer_id: @expected_cid,
+                secret_key: @expected_secret_key,
+                resource: @expected_resource,
+                method: 'GET')
+
+    assert_equal headers['x-ts-auth-method'], expected_auth_method, 'Auth method did not match'
+  end
+
+  def test_sha256_auth_method
+    expected_auth_method = 'HMAC-SHA256'
+
+    headers = TeleSign::Auth.generate_auth_headers(
+                customer_id: @expected_cid,
+                secret_key: @expected_secret_key,
+                resource: @expected_resource,
+                method: 'GET',
+                auth_method: :sha256)
+
+    assert_equal headers['x-ts-auth-method'], expected_auth_method, 'Auth method did not match'
+  end
+
+  def test_customer_id_in_auth
+    expected_auth_start = "TSA %s:" % @expected_cid
+
+    headers = TeleSign::Auth.generate_auth_headers(
+                customer_id: @expected_cid,
+                secret_key: @expected_secret_key,
+                resource: @expected_resource,
+                method: 'GET')
+
+    assert_match /^#{expected_auth_start}/, headers['Authorization'], 'Authorization did not start with TSA and customer ID'
+  end
+end