telesign 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c5e4faab130d077bd865c8b11d76e3873a04646b
+  data.tar.gz: fd647261f558b13ce9908f59bc2afdc2e2ce94e5
+SHA512:
+  metadata.gz: 19d28c08bc21a28bd27f33599e71946545f57b46b8139383fbeafbef20b5b75ae8e254fcdffcf55dcb19c6aac7c145c17efb11fc8029d18743964d1bebc3dd29
+  data.tar.gz: 8c14d197c6e50361813cf5f087df058df90f4199d9298cfc31c19308783bbdc85b502254353e24b67dcf525d4d7ff07a4fb832209ee466df5af874fa20620e8e

data/lib/telesign.rb

@@ -0,0 +1,305 @@
+#
+# Copyright (c) 2016 TeleSign
+#
+# TeleSign Ruby SDK REST API endpoints.
+#
+# The api module contains Python classes and methods that allow you to
+# use the Ruby programming language to programmatically access the
+# Verify and PhoneId TeleSign web services.
+#
+
+require 'telesign/rest'
+
+module Telesign
+
+  module API
+
+    # The PhoneId class exposes services that each provide detailed
+    # information about a specified phone number.
+    class PhoneId < Telesign::API::Rest
+
+      def initialize(customer_id,
+                     secret_key,
+                     ssl=true,
+                     api_host='rest.telesign.com',
+                     timeout=nil)
+
+        super(customer_id,
+              secret_key,
+              ssl,
+              api_host,
+              timeout)
+      end
+
+      # 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.
+      def standard(phone_number,
+                   use_case_code=nil,
+                   extra=nil,
+                   timeout=nil)
+
+        params = {}
+
+        unless use_case_code.nil?
+          params[:ucid] = use_case_code
+        end
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/phoneid/standard/#{phone_number}",
+                params,
+                nil,
+                timeout)
+      end
+
+      # 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).
+      def score(phone_number,
+                use_case_code,
+                extra=nil,
+                timeout=nil)
+
+        params = {:ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/phoneid/score/#{phone_number}",
+                params,
+                nil,
+                timeout)
+      end
+
+      # In addition to the information retrieved by standard, this service provides the
+      # Name & Address associated with the specified phone number.
+      def contact(phone_number,
+                  use_case_code,
+                  extra=nil,
+                  timeout=nil)
+
+        params = {:ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/phoneid/contact/#{phone_number}",
+                params,
+                nil,
+                timeout)
+      end
+
+      # In addition to the information retrieved by standard, this service provides
+      # actionable data associated with the specified phone number.
+      def live(phone_number,
+               use_case_code,
+               extra=nil,
+               timeout=nil)
+
+        params = {:ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/phoneid/live/#{phone_number}",
+                params,
+                nil,
+                timeout)
+      end
+
+      # In addition to the information retrieved by standard, this service provides
+      # data about potential sim_swaps associated with the specified phone number.
+      def sim_swap(phone_number,
+                   use_case_code,
+                   extra=nil,
+                   timeout=nil)
+
+        params = {:ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/phoneid/sim_swap/check/#{phone_number}",
+                params,
+                nil,
+                timeout)
+      end
+
+      # In addition to the information retrieved by standard, this service provides
+      # information on call forwarding for the phone number provided.
+      def call_forward(phone_number,
+                       use_case_code,
+                       extra=nil,
+                       timeout=nil)
+
+        params = {:ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/phoneid/call_forward/#{phone_number}",
+                params,
+                nil,
+                timeout)
+      end
+
+    end
+
+    # The Verify class exposes several services for sending users a verification
+    # token. 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.
+    class Verify < Telesign::API::Rest
+
+      def initialize(customer_id,
+                     secret_key,
+                     ssl=true,
+                     api_host='rest.telesign.com',
+                     timeout=nil)
+
+        super(customer_id,
+              secret_key,
+              ssl,
+              api_host,
+              timeout)
+      end
+
+      # Sends a text message containing the verification code, to the specified
+      # phone number (supported for mobile phones only).
+      def sms(phone_number,
+              use_case_code=nil,
+              extra=nil,
+              timeout=nil)
+
+        params = {:phone_number => phone_number}
+
+        unless use_case_code.nil?
+          params[:use_case_code] = use_case_code
+        end
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Post,
+                "/v1/verify/sms",
+                nil,
+                params,
+                timeout)
+      end
+
+      # Calls the specified phone number, and using speech synthesis, speaks the
+      # verification code to the user.
+      def call(phone_number,
+               use_case_code=nil,
+               extra=nil,
+               timeout=nil)
+
+        params = {:phone_number => phone_number}
+
+        unless use_case_code.nil?
+          params[:use_case_code] = use_case_code
+        end
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Post,
+                "/v1/verify/call",
+                nil,
+                params,
+                timeout)
+      end
+
+      # Calls the specified phone number, and using speech synthesis, speaks the
+      # verification code to the user.
+      def smart(phone_number,
+                use_case_code,
+                extra=nil,
+                timeout=nil)
+
+        params = {:phone_number => phone_number,
+                  :ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Post,
+                "/v1/verify/smart",
+                nil,
+                params,
+                timeout)
+
+      end
+
+      # The **push** method sends a push notification containing the verification
+      # code to the specified phone number (supported for mobile phones only).
+      def push(phone_number,
+               use_case_code,
+               extra=nil,
+               timeout=nil)
+
+        params = {:phone_number => phone_number,
+                  :ucid => use_case_code}
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Post,
+                "/v1/verify/push",
+                nil,
+                params,
+                timeout)
+
+      end
+
+      # Retrieves the verification result. You make this call in your web application
+      # after users complete the authentication transaction (using either a call or sms).
+      def status(reference_id,
+                 verify_code=nil,
+                 extra=nil,
+                 timeout=nil)
+
+        params = {}
+
+        unless verify_code.nil?
+          params[:verify_code] = verify_code
+        end
+
+        unless extra.nil?
+          params.merge!(extra)
+        end
+
+        execute(Net::HTTP::Get,
+                "/v1/verify/#{reference_id}",
+                params,
+                nil,
+                timeout)
+      end
+    end
+  end
+end

data/lib/telesign/rest.rb

@@ -0,0 +1,181 @@
+#
+# Copyright (c) 2016 TeleSign
+#
+# TeleSign Ruby SDK HMAC REST Auth.
+#
+
+require 'pp'
+require 'json'
+require 'time'
+require 'base64'
+require 'openssl'
+require 'net/http'
+
+module Telesign
+
+  module API
+
+    # == TeleSign Ruby SDK REST API Helper
+    #
+    # Telesign::API::Rest provides helper classes and functions
+    # to handle the HMAC REST authentication.
+    #
+    # You can use these helper functions directly or via the Telesign::API::PhoneId
+    # and Telesign::API::Verify classes. Please see the TeleSign REST API docs at
+    # http://docs.telesign.com/rest/index.html for implementation details.
+    #
+    class Rest
+
+      # Creates a new Telesign::API::Rest object with the specified credentials
+      # and HTTP configuration.
+      # The +api_host+ should be a DNS hostname or IP address.
+      def initialize(customer_id,
+                     secret_key,
+                     ssl,
+                     api_host,
+                     timeout=nil)
+
+        @customer_id = customer_id
+        @secret_key = secret_key
+        @ssl = ssl
+        @base_uri = URI("http#{ssl ? 's' : ''}://#{api_host}")
+        @timeout = timeout
+        @user_agent = 'Net::HTTP TeleSignSDK/ruby-1.0.0'
+      end
+
+      # Executes the REST API request based on the given configuration.
+      # See Telesign::API::PhoneId and Telesign::API::Verify for specific
+      # usage.
+      def execute(verb,
+                  resource,
+                  params=nil,
+                  form_data=nil,
+                  timeout=nil)
+
+        # generate the headers
+        headers = generate_auth_headers(
+            @customer_id,
+            @secret_key,
+            resource,
+            verb,
+            form_data.nil? ? nil : URI.encode_www_form(form_data))
+
+        uri = URI.join(@base_uri, resource)
+
+        # set query params
+        uri.query = URI.encode_www_form(params) unless params.nil?
+
+        # configure HTTP object
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = @ssl
+
+        http.open_timeout = timeout.nil? ? @timeout : timeout
+        http.read_timeout = http.open_timeout
+        http.ssl_timeout = http.open_timeout
+        http.continue_timeout = http.open_timeout
+
+        #set headers
+        request = verb.new uri.request_uri
+        headers.each do |k, v|
+          request[k] = v
+        end
+
+        # set post data
+        request.set_form_data(form_data) unless form_data.nil?
+
+        # do the request
+        http_response = http.request(request)
+
+        # check response
+        unless http_response.is_a? Net::HTTPSuccess
+          if http_response.is_a? Net::HTTPUnauthorized
+            raise Telesign::API::AuthError.new(http_response)
+          else
+            raise Telesign::API::APIError.new(http_response)
+          end
+        end
+
+        Telesign::API::APIResponse.new(http_response)
+      end
+
+      # Function to generate the REST API authentication headers. A signature is
+      # computed based on the contents of the request and the client's secret key.
+      def generate_auth_headers (customer_id,
+                                 secret_key,
+                                 resource,
+                                 verb,
+                                 form_data=nil,
+                                 content_type='')
+
+        datetime_stamp = Time.now.utc.to_datetime.rfc822
+        nonce = rand.to_s
+
+        content_type = 'application/x-www-form-urlencoded' if verb == Net::HTTP::Post or verb == Net::HTTP::Put
+
+        string_to_sign = "#{verb.name.split('::').last.upcase}\n" +
+            "#{content_type}\n\n" +
+            "x-ts-auth-method:#{'HMAC-SHA256'}\n" +
+            "x-ts-date:#{datetime_stamp}\n" +
+            "x-ts-nonce:#{nonce}"
+
+        string_to_sign = "#{string_to_sign}\n#{form_data}" unless form_data.nil?
+
+        string_to_sign = string_to_sign + "\n#{resource}"
+
+        signature = Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'),
+                                                         Base64.decode64(secret_key), string_to_sign)).chomp
+
+        {
+            'Authorization' => "TSA #{customer_id}:#{signature}",
+            'x-ts-date' => datetime_stamp,
+            'x-ts-auth-method' => 'HMAC-SHA256',
+            'x-ts-nonce' => nonce,
+            'User-Agent' => @user_agent
+        }
+      end
+    end
+
+    class APIResponse
+
+      attr_accessor :body, :headers, :status, :verify_code
+
+      def initialize(http_response,
+                     verify_code=nil)
+
+        @body = JSON.parse(http_response.body)
+        @headers = http_response.to_hash
+        @status = http_response.code
+        @verify_code = verify_code
+      end
+    end
+
+    class APIError < StandardError
+
+      attr_accessor :errors, :headers, :status, :body
+
+      def initialize(http_response)
+
+        @errors = JSON.parse(http_response.body)['errors']
+        @headers = http_response.to_hash
+        @status = http_response.code
+        @body = http_response.body
+      end
+
+      def to_s
+        result = ''
+        @errors.each do |error|
+          result = "#{result}#{error['description']}\n"
+        end
+
+        result
+      end
+    end
+
+    class AuthError < Telesign::API::APIError
+
+      def initialize(http_response)
+        super(http_response)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,44 @@
+--- !ruby/object:Gem::Specification
+name: telesign
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Jarrad Lee
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-03-02 00:00:00.000000000 Z
+dependencies: []
+description: TeleSign Ruby SDK
+email: jarrad@telesign.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/telesign.rb
+- lib/telesign/rest.rb
+homepage: http://rubygems.org/gems/telesign
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: TeleSign Ruby SDK
+test_files: []