trufina 0.2.5

data/lib/exceptions.rb

@@ -0,0 +1,15 @@
+# This file defines all Trufina Exceptions
+
+class Trufina
+  module Exceptions
+    class TrufinaException < StandardError; end
+    class ConfigFileError < TrufinaException; end
+    class MissingToken < TrufinaException; end
+    class MissingRequiredElements < TrufinaException; end
+    class MissingRequiredAttributes < TrufinaException; end
+    class InvalidElement < TrufinaException; end
+    class NetworkError < TrufinaException; end
+    class UnknownResponseType < TrufinaException; end
+    class TrufinaResponseException < TrufinaException; end
+  end
+end

data/lib/requests.rb

@@ -0,0 +1,139 @@
+# Contains all Trufina::Requests::* classes.
+
+class Trufina
+  
+  # These classes are used to generate requests to the Trufina API.
+  # There's a class in this module for each possible Trufina API call.
+  module Requests
+
+    API_NAMESPACE_URL = "http://www.trufina.com/truapi/1/0"
+    class BaseRequest
+      include AllowCreationFromHash
+
+      def initialize(hash = {})
+        super # init method in AllowCreationFromHash
+        autofill_from_config
+      end
+
+      def render
+        validate_contents
+        # validate_against_schema # -- Functioning code doesn't validate, waiting for feedback from Trufina before implementing
+        to_xml
+      end
+    
+      protected
+    
+      # Automatically assign any required auth or URL information from the global config
+      def autofill_from_config
+        self.pid ||= Config.credentials[:PID] if self.respond_to?(:pid=)
+        self.pak ||= Config.credentials[:PAK] if self.respond_to?(:pak=)
+      
+        # Note: URLs are optional fields, but prefilling from config anyway
+        self.cancel_url  ||= Config.endpoints[:cancel]  if self.respond_to?(:cancel_url=)
+        self.success_url ||= Config.endpoints[:success] if self.respond_to?(:success_url=)
+        self.failure_url ||= Config.endpoints[:failure] if self.respond_to?(:failure_url=)
+      end
+    
+      # Ensure all required data is set BEFORE sending the request off to the remote API
+      def validate_contents
+        missing_elements = self.class.elements.map(&:name).select {|e| !self.respond_to?(e) || self.send(e).nil?}
+        raise Exceptions::MissingRequiredElements.new(missing_elements.join(', ')) unless missing_elements.empty?
+
+        missing_attributes = self.class.attributes.map(&:name).select {|a| !self.respond_to?(a) || self.send(a).nil?}
+        raise Exceptions::MissingRequiredAttributes.new(missing_attributes.join(', ')) unless missing_attributes.empty?
+      end
+    
+      # We have access to Trufina's XML schema, so we might as well validate against it before we hit their servers
+      # http://codeidol.com/other/rubyckbk/XML-and-HTML/Validating-an-XML-Document/
+      def validate_against_schema
+        lxml = XML::Document.string( self.to_xml )
+        lxml.validate(Trufina.schema)
+      end
+    
+    end
+  
+    # When we receive a TrufinaAccessNotification from Trufina, we can then use
+    # the included TNID to receive shared user data (note the TNID is valid for 
+    # 14 days) with an InfoRequest.  We receive this notification when the user 
+    # changes their info or share permissions, or after we send a TrufinaAccessRequest.
+    # 
+    # Similar to LoginInfoRequest, but no user interaction.
+    class InfoRequest < BaseRequest
+      include HappyMapper
+      tag 'TrufinaInfoRequest'
+      namespace_url API_NAMESPACE_URL
+    
+      element :pid,   String, :tag => 'PID'
+      element :tnid,  String, :tag => 'TNID'
+      element :pak,   String, :tag => 'PAK'
+    end
+  
+    # We redirect user to Trufina, they complete registration, Trufina redirects
+    # them back to our success url with an attached TLID.  We then have 15 minutes
+    # to use this TLID to retreive the shared data with a LoginInfoRequest.
+    # 
+    # Similar to InfoRequest, but requires user interaction.
+    class LoginInfoRequest < BaseRequest
+      include HappyMapper
+      tag 'TrufinaLoginInfoRequest'
+      namespace_url API_NAMESPACE_URL
+    
+      element :pid,   String, :tag => 'PID'
+      element :tlid,   String, :tag => 'TLID'
+      element :pak,   String, :tag => 'PAK'
+    end
+  
+    # Once we've completed the login flow and retreived our information,
+    # if we want additional information later we ask for it with the
+    # AccessRequest.
+    # 
+    # The AccessResponse will contain a status of "pending" for the
+    # additional credentials, and Trufina will notify the user via email
+    # that a partner is requesting a new credential.  Once the user grants 
+    # permission for that credential, the Partner will be notified via a 
+    # AccessNotification.
+    class AccessRequest < BaseRequest
+      include HappyMapper
+      tag 'TrufinaAccessRequest'
+      namespace_url API_NAMESPACE_URL
+    
+      element :pid,   String, :tag => 'PID'
+      element :prt,   String, :tag => 'PRT'
+      element :pak,   String, :tag => 'PAK'
+      element :pur,   String, :tag => 'PUR'
+
+      element :data,  Elements::AccessRequest, :single => true
+    end
+  
+  
+    # When we wan to send a user to Trufina to register and/or provide their
+    # information and allow us access, we send this to Trufina, who sends us
+    # back a PLID we can use to generate the redirect URL to which we should
+    # send the user.
+    class LoginRequest < BaseRequest
+      # TODO -- DOCS UNCLEAR! MAY need a xlmns="" for each of these elements..?
+      include HappyMapper
+      tag 'TrufinaLoginRequest'
+      namespace_url API_NAMESPACE_URL
+    
+      element :pid,   String, :tag => 'PID'
+      element :prt,   String, :tag => 'PRT'
+      element :pak,   String, :tag => 'PAK'
+    
+      element :cancel_url,    String, :tag => 'CancelURL'
+      element :success_url,   String, :tag => 'SuccessURL'
+      element :failure_url,   String, :tag => 'FailureURL'
+    
+      element :data,  Elements::AccessRequest, :single => true
+      element :seed,  Elements::SeedInfoGroup, :single => true
+      
+      def initialize *args
+        super(args)
+        
+        # Trufina is brilliant, and they fail if this isn't in the request (even though they don't actually read the value)
+        seed.residence_address.timeframe = 'current' if seed && seed.residence_address
+      end
+    end
+  
+  end
+end

data/lib/responses.rb

@@ -0,0 +1,86 @@
+# Contains all Trufina::Responses::* classes.
+
+class Trufina
+  class Response
+    # Given returned Trufina XML, instantiate the proper HappyMapper wrapper.
+    # 
+    # (Note that this does not perform any error checking beyond unknown 
+    # root node name -- the higher level error checking is handled in the 
+    # Trufina.parseFromTrufina method)
+    def self.parse(raw_xml)
+      xml = LibXML::XML::Parser.string(raw_xml).parse
+      
+      puts "Received XML:\n\n#{xml}\n\n" if Trufina::Config.debug?
+      
+      # Try to find an appropriate local happymapper class
+      begin
+        klass = "Trufina::Responses::#{xml.root.name.gsub('Trufina', '')}".constantize
+        return klass.parse(xml)
+      rescue
+        raise Exceptions::UnknownResponseType.new("Raw XML: \n\n#{xml}")
+      end
+    end
+  end
+
+  # These classes are used to parse responses from the Trufina API.
+  # There's a class in this module for each possible Trufina response 
+  # (plus AccessNotification, which is basically an asynchronous response).
+  module Responses
+  
+    class RequestFailure
+      include HappyMapper
+      tag 'TrufinaRequestFailure'
+    
+      element :error,   String, :tag => 'Error', :attributes => {:kind => String}
+    end
+
+    class AccessNotification
+      include HappyMapper
+      tag 'TrufinaAccessNotification'
+    
+      element :prt,   String, :tag => 'PRT'
+      element :tnid,  String, :tag => 'TNID'
+    end
+
+    class AccessResponse
+      include HappyMapper
+      tag 'TrufinaAccessResponse'
+    
+      element :prt,   String, :tag => 'PRT'
+      element :data,  Elements::AccessResponseGroup, :single => true
+      element :error, String, :tag => 'Error'
+    end
+
+    class InfoResponse
+      include HappyMapper
+      tag 'TrufinaInfoResponse'
+    
+      element :prt,   String, :tag => 'PRT'
+      element :tnid,  String, :tag => 'TNID'
+      element :pur,   String, :tag => 'PUR'
+      element :data,  Elements::AccessResponseGroup, :single => true
+      element :error, String, :tag => 'Error'
+    end
+
+    class LoginInfoResponse
+      include HappyMapper
+      tag 'TrufinaLoginInfoResponse'
+    
+      element :tlid,   String, :tag => 'TLID'
+      element :prt,    String, :tag => 'PRT'
+      element :pur,    String, :tag => 'PUR'
+      element :data,   Elements::AccessResponseGroup, :single => true
+      element :error, String, :tag => 'Error'
+    end
+
+    class LoginResponse
+      include HappyMapper
+      tag 'TrufinaLoginResponse'
+    
+      element :prt,   String, :tag => 'PRT'
+      element :plid,  String, :tag => 'PLID'
+      element :error, String, :tag => 'Error'
+    end
+
+  end
+end

data/lib/trufina.rb

@@ -0,0 +1,153 @@
+require 'net/http'
+require 'net/https'
+require 'ostruct'
+require 'open-uri'
+
+# Provides a DSL to easily interact with the XML API offered by Trufina.com.
+class Trufina
+
+  class << self
+    
+    # Creates and sends a login request for the specified PRT
+    #
+    # Examples:
+    #
+    #   Trufina.login_request(Time.now)
+    #   Trufina.login_request(Time.now, :requested => [:phone], :seed => {:name => {:first => 'Foo', :last => 'Bar'}})
+    #
+    # Options:
+    #   * requested -- Hash of requested info to be returned once the user is done with Trufina
+    #   * seed  -- Hash of seed data used to prefill the user's forms at Trufina's website
+    def login_request(prt, opts = {})
+      opts[:requested] ||= {:name => [:first, :last]}
+      xml = Requests::LoginRequest.new(:prt => prt, :data => opts[:requested], :seed => remove_empties_from_hash(opts[:seed] || [])).render
+      sendToTrufina(xml)
+    end
+
+    # Given a PRT, send the login request an return the redirect URL
+    #
+    # Sends login request to get a PLID from Trufina, then uses that to build
+    # a redirect URL specific to this user.
+    # 
+    # Once user completes filling out their information and makes it available
+    # to us, Trufina will ping us with an access_notification to let us know
+    # it's there and we should ask for it.
+    #
+    # Options:
+    #   * demo  -- Boolean value. If true, and Trufina::Config.staging? is true, returns demo URL
+    #   * requested -- Hash of requested info to be returned once the user is done with Trufina
+    #   * seed  -- Hash of seed data used to prefill the user's forms at Trufina's website
+    def login_url(prt, opts = {})
+      plid = login_request(prt, :requested => opts.delete(:requested), :seed => opts.delete(:seed)).plid
+      login_url_from_plid( plid, opts.delete(:demo) )
+    end
+
+    # This should be exposed to the internet to receive Trufina's postback after
+    # a user follows the login_url and completes a profile
+    # 
+    # Receives the access notification, and automatically sends a request for
+    # the actual information.
+    def handle_access_notification(raw_xml)
+      info_request( parseFromTrufina(raw_xml).tnid )
+    end
+
+    # Given a TNID, send info_request
+    def info_request(tnid)
+      xml = Requests::InfoRequest.new(:tnid => tnid).render
+      sendToTrufina(xml)
+    end
+
+    # Given a TLID, send login_info_request
+    def login_info_request(tlid)
+      xml = Requests::LoginInfoRequest.new(:tlid => tlid).render
+      sendToTrufina(xml)
+    end
+
+    # Given either an auth hash containing a PUR and a PRT (e.g. from an InfoResponse 
+    # or LoginInfoResponse) or a suitable Trufina::*Response object directly (i.e.
+    # we can just pass the results of a Trufina.login_info_request directly for auth),
+    # as well as a data hash containing any data fields we wish to 
+    # request about the specified user, sends a request for data off to Trufina.
+    # Trufina will respond immediately with a status of "pending" for the newly
+    # requested information, will notify the user via email that we're requesting
+    # new info, and finally will notify us via an AccessNotification if/when the 
+    # user grants us access to the additional data.
+    def access_request(auth = {}, data = {})
+      auth = {:pur => auth.pur, :prt => auth.prt} unless auth.is_a?(Hash)
+      xml = Requests::AccessRequest.new( auth.merge(:data => data) ).render
+      sendToTrufina(xml)
+    end
+
+    # Retreive Trufina's XSD Schema
+    def schema
+      @@schema ||= XML::Schema.from_string(open("http://www.trufina.com/api/truapi.xsd").read)
+    end
+
+
+    protected
+
+    def domain # :nodoc:
+      Config.staging? ? 'staging.trufina.com' : 'www.trufina.com'
+    end
+  
+    def endpoint # :nodoc:
+      '/WebServices/API/'
+    end
+
+    # Send the specified XML to Trufina's servers
+    def sendToTrufina(xml)
+      puts "Sending XML to #{domain}#{endpoint}:\n\n#{xml}\n\n" if Trufina::Config.debug?
+      
+      # Connection Info
+      api = Net::HTTP.new( domain, 443 )
+      api.use_ssl = true
+      api.verify_mode = OpenSSL::SSL::VERIFY_NONE # Prevent annoying warnings
+    
+      # Request info
+      method_call = Net::HTTP::Post.new( endpoint, {'Content-Type' => 'text/xml'} )
+      method_call.body = xml
+
+      if Config.staging?
+        method_call.basic_auth(Config.staging_access[:username], Config.staging_access[:password])
+      end
+    
+      # OK, execute the actual call
+      response = api.request(method_call)
+      raise Exceptions::NetworkError.new(response.msg) unless response.is_a?(Net::HTTPSuccess)
+      parseFromTrufina(response.body)
+    end
+  
+    # Try to make something useful from Trufina's XML responses
+    def parseFromTrufina(raw_xml)
+      response = Trufina::Response.parse(raw_xml)
+      
+      # Raise exception if we've received an error
+      if response.is_a?(Trufina::Responses::RequestFailure) # Big error -- the entire returned XML is to tell us
+        raise Exceptions::TrufinaResponseException.new("#{response.error.kind}: #{response.error}")
+      elsif response.respond_to?(:error) && response.error # Smaller error, noted inline
+        raise Exceptions::TrufinaResponseException.new("Error in #{response.class.name}: #{response.error}")
+      end
+      
+      return response
+    end
+     
+    # Given a PLID (from a login_request), return a url to send the user to
+    def login_url_from_plid(plid, is_demo = nil)
+      path = (Config.staging? && is_demo) ? "/DemoPartnerLogin/DemoLogin/#{plid}" : "/PartnerLogin/Login/#{plid}"
+      auth = Config.staging? ? "#{Config.staging_access[:username]}:#{Config.staging_access[:password]}@" : ''
+      "http://#{auth}#{domain}#{path}"
+    end
+    
+    # Removes any hash keys with empty values - seed data can't have any blanks, or Trufina gets mad
+    def remove_empties_from_hash(old_hash)
+      new_hash = {}
+      old_hash.each do |key, value|
+        next if value.nil? || value == '' || value == [] || value == {}
+        new_hash[key] = value.is_a?(Hash) ? remove_empties_from_hash(value) : value
+      end
+      
+      return new_hash
+    end
+    
+  end
+end

data/rails/init.rb

@@ -0,0 +1,12 @@
+base = File.join(File.dirname(__FILE__), '..')
+
+# Require jimmyz's happymapper to enable to_xml for happymap classes
+require 'happymapper'
+
+# Require the rest of the plugin files
+require File.join(base, 'lib', 'exceptions.rb')
+require File.join(base, 'lib', 'config.rb')
+require File.join(base, 'lib', 'elements.rb')
+require File.join(base, 'lib', 'requests.rb')
+require File.join(base, 'lib', 'responses.rb')
+require File.join(base, 'lib', 'trufina.rb')

data/tasks/trufina_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :trufina do
+#   # Task goes here
+# end

data/test/fixtures/requests/access_request.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<TrufinaAccessRequest xmlns="http://www.trufina.com/truapi/1/0">
+  <PID><%= Trufina::Config.credentials[:PID] %></PID>
+  <PRT><%= @prt %></PRT>
+  <PAK><%= Trufina::Config.credentials[:PAK] %></PAK>
+  <PUR><%= @pur %></PUR>
+  <AccessRequest>
+    <Name>
+      <First />
+    </Name>
+    <Age />
+    <ResidenceAddress>
+      <State />
+    </ResidenceAddress>
+  </AccessRequest>
+</TrufinaAccessRequest>

data/test/fixtures/requests/info_request.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<TrufinaInfoRequest xmlns="http://www.trufina.com/truapi/1/0">
+	<PID><%= Trufina::Config.credentials[:PID] %></PID>
+	<TNID><%= @tnid %></TNID>
+	<PAK><%= Trufina::Config.credentials[:PAK] %></PAK>
+</TrufinaInfoRequest>

data/test/fixtures/requests/login_info_request.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<TrufinaLoginInfoRequest xmlns="http://www.trufina.com/truapi/1/0">
+  <PID><%= Trufina::Config.credentials[:PID] %></PID>
+  <TLID><%= @tlid %></TLID>
+  <PAK><%= Trufina::Config.credentials[:PAK] %></PAK>
+</TrufinaLoginInfoRequest>