emailage 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fc9fbe9dfc143428f04a27e577fdbc63df467c84
+  data.tar.gz: c76766cbc9f668a8c5ec2a6e0bf613c0facb45bf
+SHA512:
+  metadata.gz: e14df265b8c3e97bbe3efc07dc0340512ff20ee994fccf3805507a0fb745cc7e9478ad5b24753fbf97cf5d53dae406dad4c774b729fdec2b5811a184c3d0b8a2
+  data.tar.gz: 48fbd62d151d0bc4d0da5f6bb653dde808c9c51b8995294ddb14a7beb6617b8bcacf2c6259acf4ae1a36445ffa75e2c8dd1082efdaeabdf74b52ab5e38d801de

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in emailage.gemspec
+gemspec

data/README.md

@@ -0,0 +1,89 @@
+[logo]: https://emailage.com/Content/Images/logo.svg "Emailage Logo"
+
+![alt text][logo](https://www.emailage.com)
+
+The Emailage™ API is organized around REST (Representational State Transfer). The API was built to help companies integrate with our highly efficient fraud risk and scoring system. By calling our API endpoints and simply passing us an email and/or IP Address, companies will be provided with real-time risk scoring assessments based around machine learning and proprietary algorithms that evolve with new fraud trends.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'emailage'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install emailage
+    
+## Usage
+
+Instantiate a client
+```ruby
+# For a production server
+emailage = Emailage::Client.new('My account SID', 'My auth token')
+# ... or for a sandbox
+emailage = Emailage::Client.new('My account SID', 'My auth token', sandbox: true)
+```
+
+Query a risk score information for the provided email address, IP address, or a combination
+```ruby
+# For an email address
+emailage.query 'test@example.com'
+# For an IP address
+emailage.query '127.0.0.1'
+# For a combination. Please note the order
+emailage.query ['test@example.com', '127.0.0.1']
+# Pass a User Defined Record ID.
+# Can be used when you want to add an identifier for a query.
+# The identifier will be displayed in the result.
+emailage.query 'test@example.com', urid: 'My record ID for test@example.com'
+```
+Explicit methods produce the same request while validating format of the arguments passed
+```ruby
+# For an email address
+emailage.query_email 'test@example.com'
+# For an IP address
+emailage.query_ip_address '127.0.0.1'
+# For a combination. Please note the order
+emailage.query_email_and_ip_address 'test@example.com', '127.0.0.1'
+# Pass a User Defined Record ID
+emailage.query_email_and_ip_address 'test@example.com', '127.0.0.1', urid: 'My record ID for test@example.com and 127.0.0.1'
+```
+
+Mark an email address as fraud, good, or neutral.  
+All the listed forms are possible.  
+When you mark something as fraud, don't forget to pass a fraud code number from this list:  
+1 - Card Not Present Fraud  
+2 - Customer Dispute (Chargeback)  
+3 - First Party Fraud  
+4 - First Payment Default  
+5 - Identify Theft (Fraud Application)  
+6 - Identify Theft (Account Take Over)  
+7 - Suspected Fraud (Not Confirmed)  
+8 - Synthetic ID  
+9 - Other
+
+```ruby
+# Mark an email address as fraud because of Synthetic ID.
+emailage.flag 'fraud',   'test@example.com', 8
+emailage.flag_as_fraud   'test@example.com', 8
+# Mark an email address as good.
+emailage.flag 'good',    'test@example.com'
+emailage.flag_as_good    'test@example.com'
+# Unflag an email address that was previously marked as good or fraud.
+emailage.flag 'neutral', 'test@example.com'
+emailage.remove_flag     'test@example.com'
+```
+
+### Exceptions
+
+This gem can throw exceptions on any of the following issues:
+
+1. When Curl has an issue, like not being able to connect from your server to Emailage API,
+2. When bad formatted JSON is received,
+3. When an incorrect email or IP address is passed to a flagging or explicitly querying method.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "emailage"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/emailage.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'emailage/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "emailage"
+  spec.version       = Emailage::VERSION
+  spec.authors       = ["Sergey Baev"]
+  spec.email         = ["tinbka@gmail.com"]
+
+  spec.summary       = "Emailage API client written in Ruby"
+  spec.description   = "Emailage is a Fraud Prevention Solution. This gem implements a client for the Emailage web service."
+  spec.homepage      = "https://emailage.com/"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec-core", "~> 3.4"
+  spec.add_development_dependency "rspec-expectations", "~> 3.4"
+  spec.add_development_dependency "rspec-mocks", "~> 3.4"
+  spec.add_development_dependency "yard", "~> 0.8"
+  spec.add_development_dependency "redcarpet", "~> 3.3"
+  
+  spec.add_dependency "typhoeus", "~> 1.0"
+  spec.add_dependency "uuid", "~> 2.3"
+  spec.add_dependency "json", "~> 1.8"
+end

data/lib/emailage.rb

@@ -0,0 +1,22 @@
+$:<<'./lib'
+
+require 'emailage/version'
+require 'emailage/signature'
+require 'emailage/validation'
+require 'emailage/client'
+
+module Emailage
+  FRAUD_CODES = {
+    1 => 'Card Not Present Fraud',
+    2 => 'Customer Dispute (Chargeback)',
+    3 => 'First Party Fraud',
+    4 => 'First Payment Default',
+    5 => 'Identify Theft (Fraud Application)',
+    6 => 'Identify Theft (Account Take Over)',
+    7 => 'Suspected Fraud (Not Confirmed)',
+    8 => 'Synthetic ID',
+    9 => 'Other'
+  }
+  
+  class Error < StandardError; end
+end

data/lib/emailage/client.rb

@@ -0,0 +1,166 @@
+require 'typhoeus'
+require 'uuid'
+require 'json'
+
+module Emailage
+  class Client
+    attr_reader :secret, :token, :hmac_key, :sandbox
+    attr_accessor :raise_errors
+  
+    # @param secret [String] Consumer secret, e.g. SID or API key.
+    # @param token  [String] Consumer OAuth token.
+    # @param sandbox [Boolean] Whether to use a sandbox instead of a production server.
+    #   Ensure the according secret and token are supplied.
+    #
+    # @note HMAC key is created according to Emailage docs rather than OAuth1 spec.
+    #
+    def initialize(secret, token, options={})
+      @secret, @token = secret, token
+      @sandbox = options.fetch :sandbox, false
+      @raise_errors = options.fetch :raise_errors, false
+      
+      # @hmac_key = [@secret, @token].map {|e| CGI.escape(e)}.join '&'
+      @hmac_key = @token + '&'
+    end
+    
+    private
+    
+    # Basic request method utilized by #query and #flag.
+    #
+    # @param endpoint [String] Currently, either an empty string or "/flag".
+    # @param params  [Hash] Non-general GET request params.
+    #
+    # @return [Hash] Original Emailage API's JSON body.
+    #
+    def request(endpoint, params)
+      base_url = "https://#{@sandbox ? 'sandbox' : 'api'}.emailage.com/emailagevalidator"
+      url = "#{base_url}#{endpoint}/"
+      params = {
+        :format => 'json', 
+        :oauth_consumer_key => @secret,
+        :oauth_nonce => UUID.new.generate,
+        :oauth_signature_method => 'HMAC-SHA1',
+        :oauth_timestamp => Time.now.to_i,
+        :oauth_version => 1.0
+      }.merge(params)
+      
+      res = Typhoeus.get url, :params => params.merge(:oauth_signature => Signature.create('GET', url, params, @hmac_key))
+      
+      # For whatever reason Emailage dispatches JSON with unreadable symbls at the start, like \xEF\xBB\xBF.
+      json = res.body.sub(/^[^{]+/, '')
+      JSON.parse json
+    end
+    
+    public
+    
+    # Query a risk score information for the provided email address, IP address, or a combination.
+    #
+    # @param query [String | Array<String>] Email, IP or a tuple of (Email, IP).
+    # @param params [Hash] Extra request params as in API documentation.
+    # @option urid [String] User Defined Record ID.
+    #   Can be used when you want to add an identifier for a query.
+    #   The identifier will be displayed in the result.
+    #
+    def query(query, params={})
+      query *= '+' if query.is_a? Array
+      request '', params.merge(:query => query)
+    end
+    
+    # Query a risk score information for the provided email address.
+    # This method differs from #query in that it ensures that the string supplied is in rfc2822 format.
+    #
+    # @param email [String]
+    # @param params [Hash] Extra request params as in API documentation.
+    # @option urid [String] User Defined Record ID. See #query.
+    #
+    def query_email(email, params={})
+      Validation.validate_email! email
+      query email, params
+    end
+    
+    # Query a risk score information for the provided IP address.
+    # This method differs from #query in that it ensures that the string supplied is in rfc791 format.
+    #
+    # @param ip [String]
+    # @param params [Hash] Extra request params as in API documentation.
+    # @option urid [String] User Defined Record ID. See #query.
+    #
+    def query_ip_address(ip, params={})
+      Validation.validate_ip! ip
+      query ip, params
+    end
+    
+    # Query a risk score information for the provided combination of an Email and IP address.
+    # This method differs from #query in that it ensures that the strings supplied are in rfc2822 and rfc791 formats.
+    #
+    # @param email [String]
+    # @param ip [String]
+    # @param params [Hash] Extra request params as in API documentation.
+    # @option urid [String] User Defined Record ID. See #query.
+    #
+    def query_email_and_ip_address(email, ip, params={})
+      Validation.validate_email! email
+      Validation.validate_ip! ip
+      query [email, ip], params
+    end
+    
+    
+    # Mark an email address as fraud, good, or neutral.
+    #
+    # @param flag  [String] Either fraud, neutral, or good.
+    # @param query [String] Email to be flagged.
+    # @param fraud_code [Integer | String] Reason why the Email or IP is considered fraud. ID or name of the one of FRAUD_CODES options.
+    #   E.g. 8 or "Syntethic ID" for Syntethic ID
+    #   Required only if you flag something as fraud.
+    # @see Emailage::FRAUD_CODES for the list of available reasons and their IDs.
+    #
+    def flag(flag, query, fraud_code=nil)
+      flags = %w[fraud neutral good]
+      unless flags.include? flag.to_s
+        raise ArgumentError, "flag must be one of #{flags * ', '}. #{flag} is given."
+      end
+      
+      Validation.validate_email! query
+      
+      query *= '+' if query.is_a? Array
+      params = {:flag => flag, :query => query}
+      
+      if flag == 'fraud'
+        unless (1..9).to_a.include? fraud_code
+          raise ArgumentError, "fraud_code must be an integer from 1 to 9 corresponding to #{FRAUD_CODES.values*', '}. #{fraud_code} is given."
+        end
+        params[:fraudcodeID] = fraud_code
+      end
+      
+      request '/flag', params
+    end
+    
+    # Mark an email address as fraud.
+    #
+    # @param query [String] Email to be flagged.
+    # @param fraud_code [Integer | String] Reason why the Email or IP is considered fraud. ID or name of the one of FRAUD_CODES options.
+    #   E.g. 8 or "Syntethic ID" for Syntethic ID
+    # @see Emailage::FRAUD_CODES for the list of available reasons and their IDs.
+    #
+    def flag_as_fraud(query, fraud_code)
+      flag 'fraud', query, fraud_code
+    end
+    
+    # Mark an email address as good.
+    #
+    # @param query [String] Email to be flagged.
+    #
+    def flag_as_good(query)
+      flag 'good', query
+    end
+    
+    # Unflag an email address that was marked as good or fraud previously.
+    #
+    # @param query [String] Email to be flagged.
+    #
+    def remove_flag(query)
+      flag 'neutral', query
+    end
+  
+  end
+end

data/lib/emailage/signature.rb

@@ -0,0 +1,44 @@
+require 'cgi'
+require 'openssl'
+require 'base64'
+
+module Emailage
+  module Signature
+    class << self
+      
+      # 9.1.1.  Normalize Request Parameters
+      def normalize_query_parameters(params)
+        params.sort.map {|k,v| [CGI.escape(k.to_s), CGI.escape(v.to_s)].join '='}.join '&'
+      end
+      
+      # 9.1.3.  Concatenate Request Elements
+      def concatenate_request_elements(method, url, query)
+        [method.to_s.upcase, url, query].map {|e| CGI.escape(e)}.join '&'
+      end
+      
+      # 9.2.  HMAC-SHA1
+      def hmac_sha1(base_string, hmac_key)
+        OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha1'), hmac_key, base_string)
+      end
+
+      # http://oauth.net/core/1.0/#signing_process
+      # Using HTTP GET parameters option.
+      #
+      # @param method [String] HTTP 1.1 Method
+      # @param url [String] Normalized URL to be requested until ? sign.
+      # @param params [Hash] GET or www-urlencoded POST request params.
+      # @param hmac_key  [String] Key generated out of Consumer secret and token.
+      #
+      # @return [String] Value of the oauth_signature query parameter.
+      #
+      def create(method, url, params, hmac_key)
+        query = normalize_query_parameters(params)
+        base_string = concatenate_request_elements(method, url, query)
+        digest = hmac_sha1(base_string, hmac_key)
+        # 9.2.1.  Generating Signature
+        Base64.strict_encode64 digest
+      end
+      
+    end
+  end
+end

data/lib/emailage/validation.rb

@@ -0,0 +1,33 @@
+module Emailage
+  module Validation
+    class << self
+      
+      def validate_email!(email)
+        unless email =~ /\A[^@\s]+@([^@\s]+\.)+[^@\s]+\z/
+          raise ArgumentError, "#{email} is not a valid email address."
+        end
+      end
+      
+      def validate_ip!(ip)
+        unless ip =~ /\A\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/
+          raise ArgumentError, "#{ip} is not a valid IP address."
+        end
+      end
+      
+      def validate_email_or_ip!(email_or_ip)
+        if email_or_ip.is_a? Array
+          if email_or_ip.size != 2
+            raise ArgumentError, "an array must contain exactly one Email and one IP address. #{email_or_ip} is given."
+          end
+          validate_email! email_or_ip.first
+          validate_ip! email_or_ip.last
+        else
+          unless email_or_ip =~ /\A([^@\s]+@([^@\s]+\.)+[^@\s]+|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})\z/
+            raise ArgumentError, "#{email_or_ip} is neither a valid IP address nor a valid email address."
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/emailage/version.rb

@@ -0,0 +1,3 @@
+module Emailage
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,196 @@
+--- !ruby/object:Gem::Specification
+name: emailage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergey Baev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: uuid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Emailage is a Fraud Prevention Solution. This gem implements a client
+  for the Emailage web service.
+email:
+- tinbka@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- emailage.gemspec
+- lib/emailage.rb
+- lib/emailage/client.rb
+- lib/emailage/signature.rb
+- lib/emailage/validation.rb
+- lib/emailage/version.rb
+homepage: https://emailage.com/
+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.4.8
+signing_key: 
+specification_version: 4
+summary: Emailage API client written in Ruby
+test_files: []