neustar-ws_get_data 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d875a60812405cf6e3884324a776d0115fb7c17
+  data.tar.gz: fd7751d2ff95aff549a23d1f18272fe9dff93e0d
+SHA512:
+  metadata.gz: 7545c58a95d222b7e2731cc35306362b716ebbf93fe54d090892a6870646995ef0eb8df9cccd5576e276dd98f464992b24678ca9ea0c4083c86e6c9825eaeb80
+  data.tar.gz: 9b97220f9ab3314b97aaa24f4cda7bc3fc65dc439a6d543a608b61882b99cff1d515055cb5845abf6f41a86a252cc974e27572549e27a520ad29825fd7a20a7a

data/.gitignore

@@ -0,0 +1,39 @@
+# SimpleCov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+_yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# For MacOS:
+.DS_Store
+
+# exclude everything in tmp
+tmp/*
+# except the metric_fu directory
+!tmp/metric_fu/
+# but exclude everything *in* the metric_fu directory
+tmp/metric_fu/*
+# except for the _data directory to track metrical outputs
+!tmp/metric_fu/_data/
+
+*.gem
+*.rbc
+.config
+Gemfile.lock
+InstalledFiles
+lib/bundler/man
+spec/reports
+test/tmp
+test/version_tmp

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format nested
+--order rand
+--profile

data/.ruby-gemset

@@ -0,0 +1 @@
+neustar-ws_get_data

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p247

data/Gemfile

@@ -0,0 +1,21 @@
+source "https://rubygems.org"
+
+gem 'savon', '~> 2.2'
+
+group :development do
+  gem "yard"
+  gem "bundler"
+end
+
+group :development, :test do
+  gem "rspec", "~> 2.14.0"
+  gem 'rake', :require => false
+
+  # code metrics:
+  gem "metric_fu"
+end
+
+group :test do
+  gem 'simplecov'          , :require => false
+  gem 'simplecov-rcov-text', :require => false
+end

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 TMXCredit, author Zach Belzer
+
+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
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,48 @@
+# Neustar::WsGetData
+
+This gem wraps the SOAP interface for Neustar's WS-GetData Services. It
+supports both interactive and batch queries.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'neustar-ws_get_data'
+
+And then execute:
+
+    bundle
+
+Or install it yourself as:
+
+    gem install neustar-ws_get_data
+
+## Usage
+
+```ruby
+  client = Neustar::WsGetData::Client.new(
+    :username   => 'username',
+    :password   => 'password',
+    :service_id => 123456
+  )
+
+  client.operations
+  #=> [:query, :batch_query]
+
+  client.phone_attributes('8583145300', [:phone_type])
+  #=> {:phone_type => :wireless}
+
+  client.phone_attributes('8583145300')
+  #=> {:prepaid_phone    => false,
+       :business_phone   => :unknown,
+       :phone_in_service => "Active for 1 month or less",
+       :phone_type       => :wireless}
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,34 @@
+#!/usr/bin/env rake
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'rspec/core/rake_task'
+require './lib/neustar-ws_get_data/version'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+desc "Release tag for this version to github"
+task "git:release" do
+  `git tag v#{Neustar::WsGetData::VERSION}`
+  `git push --tags`
+end
+
+desc "Build and push gem to rubygems"
+task "build" do
+  `gem build neustar-ws_get_data.gemspec`
+  `gem push neustar-ws_get_data-#{Neustar::WsGetData::VERSION}.gem`
+end

data/lib/neustar-ws_get_data.rb

@@ -0,0 +1,25 @@
+require 'savon'
+require 'securerandom'
+
+# Top-level namespace.
+module Neustar
+  # Wrapper to interface with the WS-GetData Service.
+  module WsGetData
+    # Location of SOAP WSDL for WS-GetData:
+    WSDL = 'http://webapp.targusinfo.com/ws-getdata/query.asmx?WSDL'
+  end
+
+  # Top-level error class for Neustar.
+  class Error < StandardError
+  end
+
+  # Error to be raised when basic configuration is missing.
+  class ConfigurationError < Error
+  end
+end
+
+require File.expand_path("../neustar-ws_get_data/version", __FILE__)
+require File.expand_path("../neustar-ws_get_data/client", __FILE__)
+
+elements = File.expand_path("../neustar-ws_get_data/elements/*", __FILE__)
+Dir[elements].each {|element| require element }

data/lib/neustar-ws_get_data/client.rb

@@ -0,0 +1,115 @@
+# Base client used to interface with WS-GetData query and batch_query services.
+class Neustar::WsGetData::Client
+  # Maximum transaction ID:
+  MAX_TRANSACTION_ID = 1_000_000
+
+  # @param [Hash] options The configuration options
+  # @option options [String] :username Name of the Neustar account
+  # @option options [String] :password Password for the Neustar account
+  # @option options [String] ::service_id Service ID for the Neustar account
+  def initialize(options = {})
+    @service    = Savon.client(:wsdl => Neustar::WsGetData::WSDL)
+    @username   = options[:username] or
+                    raise ConfigurationError, "Username required"
+    @password   = options[:password] or
+                    raise ConfigurationError, "Password required"
+    @service_id = options[:service_id] or
+                    raise ConfigurationError, "Service ID required"
+  end
+
+  # List the operations available to the client.
+  #
+  # @return [Array<Symbol>]
+  def operations
+    @service.operations
+  end
+
+  # Execute an 'interactive' query.
+  #
+  # @param [Hash] params
+  # @return [Hash]
+  def query(params)
+    call(:query, params)
+  end
+
+  # Execute a batch query.
+  #
+  # @param [Hash] params
+  # @return [Hash]
+  def batch_query(params)
+    call(:batch_query, params)
+  end
+
+  # Execute a call to the given service type.
+  #
+  # @param [Symbol] service
+  # @return [Hash]
+  def call(service, params)
+    transaction_id = params.fetch(:transaction_id) { build_transaction_id }
+
+    message = origination_params.
+              merge(:transId => transaction_id).
+              merge(params)
+
+    begin
+      response = @service.call(service, :message => message)
+      process_response(service, response)
+    rescue Savon::SOAPFault => error
+      raise Neustar::Error, extract_fault_message(error)
+    end
+  end
+
+  # Execute initial post-processing and error handling on the response.
+  #
+  # @param [Symbol] service
+  # @param [Savon::Response] response
+  #
+  # @return [Hash]
+  def process_response(service, response)
+    response_wrapper = response.body[:"#{service}_response"]
+    response_wrapper && response_wrapper[:response]
+  end
+
+  # Helper to access PhoneAttributes element.
+  # TODO: Refactor out of here
+  #
+  # @param [#to_s] phone_number
+  # @param [Array<Symbol>] indicators
+  def phone_attributes(phone_number, indicators = [])
+    Neustar::WsGetData::PhoneAttributes.query(self, phone_number, indicators)
+  end
+
+  # Parameters used to authenticate the client.
+  #
+  # @return [Hash]
+  def origination_params
+    {
+      :origination => {
+        :username => @username, :password => @password
+      },
+      :serviceId   => @service_id.to_s
+    }
+  end
+
+  # Returns a unique transaction ID to send with each request.
+  #
+  # @return [String]
+  def build_transaction_id
+    SecureRandom.random_number(MAX_TRANSACTION_ID)
+  end
+
+  # Pulls the error message from a Savon::SOAPFault exception.
+  #
+  # @param [Savon::SOAPFault] error
+  # @return [String]
+  def extract_fault_message(error)
+    data = error.to_hash
+
+    if (fault = data[:fault]) and (faultstring = fault[:faultstring]) then
+      faultstring
+    else
+      "Unknown Error"
+    end
+  end
+  private :extract_fault_message
+end

data/lib/neustar-ws_get_data/elements/phone_attributes.rb

@@ -0,0 +1,168 @@
+# From the documentation:
+#
+# "Element ID 1320 accepts a phone number and returns attributes associated
+# with the phone number. Currently, the following attributes are available:
+# Prepaid Phone Indicator, Business Phone Indicator (BPI), Phone In-Service
+# Indicator, and Phone Type Indicator."
+module Neustar::WsGetData::PhoneAttributes
+  extend self
+
+  # Error raised when an invalid phone number is sent to the service.
+  class OutOfDomainError < Neustar::Error; end
+
+  # ID for "Phone Attributes".
+  ELEMENT_ID = 1320
+
+  # Service ID to specify the telephone number in a request.
+  TELEPHONE_SPECIFICATION_SERVICE_ID = 1
+
+  # Service ID to specify which attributes we want returned.
+  PHONE_ATTRIBUTES_REQUESTED_SERVICE_ID = 599
+
+  # Mappings to request certain indicators from the service.
+  INDICATORS = {
+    :prepaid_phone    => 1,
+    :business_phone   => 2,
+    :phone_in_service => 3,
+    :phone_type       => 4,
+  }
+
+  # Whether or not a phone is prepaid.
+  PREPAID_PHONE_ATTRIBUTE_MAP = {
+    'Y' => true,
+    'N' => false
+  }
+
+  # The assumed purpose for a phone.
+  BUSINESS_PHONE_INDICATOR_MAP = {
+    'B' => :business_phone,
+    'C' => :residential_phone,
+    'D' => :dual_phone,
+    'U' => :unknown
+  }
+
+  # The Phone In-Service field indicates whether the phone is active and
+  # provides a range indicator for the active/inactive status.
+  PHONE_IN_SERVICE_INDICATOR_MAP = {
+    'A1' => "Active for 1 month or less",
+    'A2' => "Active for 2 months",
+    'A3' => "Active for 3 months",
+    'A4' => "Active for between 4-6 months",
+    'A5' => "Active for between 7-9 months",
+    'A6' => "Active for between 10-11 months",
+    'A7' => "Active for 12 months or longer",
+    'I1' => "Inactive for 1 month or less",
+    'I2' => "Inactive for 2 months",
+    'I3' => "Inactive for 3 months",
+    'I4' => "Inactive for between 4-6 months",
+    'I5' => "Inactive for between 7-9 months",
+    'I6' => "Inactive for between 10-11 months",
+    'I7' => "Inactive for 12 months or longer",
+    'U'  => "Status Unknown",
+  }
+
+  # The type of phone used.
+  PHONE_TYPE_INDICATOR_MAP = {
+    'W' => :wireless,
+    'L' => :landline,
+    'U' => :unknown
+  }
+
+  # A map between each attribute and their possible values.
+  INDICATOR_MAPPINGS = {
+    :prepaid_phone    => PREPAID_PHONE_ATTRIBUTE_MAP,
+    :business_phone   => BUSINESS_PHONE_INDICATOR_MAP,
+    :phone_in_service => PHONE_IN_SERVICE_INDICATOR_MAP,
+    :phone_type       => PHONE_TYPE_INDICATOR_MAP
+  }
+
+  # Indicates that an invalid phone number was sent to the service.
+  OUT_OF_DOMAIN_ERROR = "6"
+
+  # Method used to execute a query against the Phone Attributes element of the
+  # WS-GetData Service.
+  #
+  # @param [Neustar::WsGetData::Client] client
+  # @param [#to_s] phone_number
+  # @param [Array<Symbol>] indicators
+  #
+  # @return [Hash]
+  def query(client, phone_number, indicators = [])
+    indicators = parse_indicators(indicators)
+
+    params = {
+      :phone_number => phone_number,
+      :indicators   => indicators
+    }
+
+    process_response(execute_request(client, params), params)
+  end
+
+  # Assemble and execute a query using the passed client.
+  #
+  # @param [Neustar::WsGetData::Client] client
+  # @param [Hash] params
+  # @option params [String] :phone_number
+  # @option params [String] :indicators
+  #
+  # @return [Hash]
+  def execute_request(client, params)
+    client.query(
+      :elements => { :id => ELEMENT_ID },
+      :serviceKeys => {
+        :serviceKey => [
+          {
+            :id    => TELEPHONE_SPECIFICATION_SERVICE_ID,
+            :value => params[:phone_number]
+          },
+          {
+            :id    => PHONE_ATTRIBUTES_REQUESTED_SERVICE_ID,
+            :value => params[:indicators]
+          }
+        ]
+      }
+    )
+  end
+
+  # Do element specific processing on response from client.
+  #
+  # @param [Hash] response
+  # @option response [String] :error_code The stringified number
+  #                                       of the error code
+  # @option response [Hash] :result
+  # @param [Hash] params
+  # @option params [String] :phone_number
+  #
+  # @return [Hash]
+  def process_response(response, params)
+    if response[:error_code] == OUT_OF_DOMAIN_ERROR
+      raise OutOfDomainError, params[:phone_number]
+    else
+      string = response[:result][:element][:value]
+      result = {}
+
+      INDICATOR_MAPPINGS.each do |name, mapping|
+        mapping.detect do |key, value|
+          result[name] = value if string.index(key)
+        end
+      end
+
+      result
+    end
+  end
+
+  # Given a list of indicator symbols, derive the argument to send the service.
+  #
+  # @param [Array<Symbol>] indicators
+  # @return [String]
+  def parse_indicators(indicators)
+    vals =
+      if indicators.empty?
+        INDICATORS.values
+      else
+        INDICATORS.values_at(*indicators)
+      end
+
+    vals.join(',')
+  end
+end