nfg-client 1.0.0 → 1.0.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZDhhZGYxODA1OTNjMTcwNWJiMDVjMzUwOTE5NTgzNzEwOGQ3NDY5Mg==
+    YzY4OGY4MGQ0ZTRhY2FkYzQ5NTU0MTdlODE3YWY1YjkwOWViM2JiNw==
   data.tar.gz: !binary |-
-    ZmVjOTFiMWM5ZTA2NGQwMzc5NjNmYWZjNTBlYjllYjlkNDllNmNlMw==
+    MWZkMzFiZTQ0N2E4ZGYxN2VhMjI0NmJjN2Y5MmY4M2NhODJmMGE4ZQ==
 SHA512:
   metadata.gz: !binary |-
-    OTU5ZjhlZTQ1NGNlNDNiNDY0MDI1OTI2ODA1N2JhZDk5NGJlNzgxYWQ0Njgy
-    YzRlZGRlOWY0MjA0MmMyYTY4MGE1NDg4ZTk3NmJmNjQ5ODA5MTg3M2U4OThl
-    ODYyODRlNGNjNjQ1ZGI3MjJkZTc0ZGEwNmExZjhiMzBhMzA4YmE=
+    MTZhOGFkMTZlMjM0MThhY2EyNzgzMTMzZTQyYTgyYTU5YWJiNDg4Mzk1OWY0
+    N2MwYzhhZjBlNWQ0YjNlYTkxMzA5NGFjMmQ1N2FiZDJkZjNjZDg5MDYwMzE5
+    NjRlZDQwZjJjZmJhMTYxMGFlMTY5YzQ2MWVjZDU0YTc4MjJlNTk=
   data.tar.gz: !binary |-
-    ODc3MTViZmU1YzBmNzI2NjMwMGVhNWQ5OGRkNzg0MTliNzcyYjc2N2M1NzM2
-    ZTczOTMzYWE1YzQyNTgyNzA0MGE4ODMyMGFiNzc1ZjMxNGNhYmJmZTE1OGVm
-    NTM3NWY3MzAxMTFmZjNjOTA2ZDY2NGJjMDQ0Yjg4ZTk4ZWU2Mzc=
+    NDBmOTJkMjA1OWE4NjU3NTVjZDdmNDNmYzQ2NWMyZGIyNGQ5NjBjNjYzZThi
+    Yjc5OGJhOWExM2YxNGE4YmFmNThhYzM5MmY4YjkyNDZlMzI4ZTI5MTljYjZi
+    YzEwZDhjNjAzMDZmZDVkNDhhMGM2NzBkNTFmYmM1MDQxNTZkNWM=

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Antonio Ruano Cuesta
+Copyright (c) 2014 by Antonio Ruano Cuesta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -358,3 +358,13 @@ When a call fails (i.e. the "StatusCode" is different than "Success"), it's usua
             "CallDuration" => "x.x",
             ...
     }
+    
+# Contributors
+
+Special thanks to:
+
+- [Tom Hoen](https://github.com/hoenth), for the addition of the test suite and code refactoring.
+
+# Copyright
+
+Copyright (c) 2014 by [Antonio Ruano Cuesta](https://github.com/aruanoc). See [LICENSE](https://github.com/aruanoc/nfg-client/blob/master/LICENSE.md) for details.

data/Rakefile

@@ -6,3 +6,9 @@ RSpec::Core::RakeTask.new(:spec)
 
 desc 'Default: run specs.'
 task :default => :spec
+
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r nfg-client.rb"
+end

data/lib/nfg-client/client.rb

@@ -20,8 +20,9 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def create_cof(params)
+      requires!(params, :DonorToken, :DonorFirstName, :DonorLastName, :DonorEmail, :DonorAddress1, :DonorAddress2, :DonorCity, :DonorState, :DonorZip, :DonorCountry, :DonorPhone, :CardType, :NameOnCard, :CardNumber, :ExpMonth, :ExpYear, :CSC)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('CreateCOF', call_params, @use_sandbox)
+      response = nfg_soap_request('CreateCOF', call_params)
       if response.is_a? REXML::Element
         {
           'StatusCode' => response.elements['StatusCode'].get_text.to_s,
@@ -41,8 +42,9 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def delete_donor_cof(params)
+      requires!(params, :DonorToken, :COFId)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('DeleteDonorCOF', call_params, @use_sandbox)
+      response = nfg_soap_request('DeleteDonorCOF', call_params)
       if response.is_a? REXML::Element
         if response.elements['StatusCode'].get_text.to_s == 'Success'
           {
@@ -74,8 +76,9 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def get_donor_cofs(params)
+      requires!(params, :DonorToken)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('GetDonorCOFs', call_params, @use_sandbox)
+      response = nfg_soap_request('GetDonorCOFs', call_params)
       if response.is_a? REXML::Element
         response_hash = {
           'StatusCode' => response.elements['StatusCode'].get_text.to_s,
@@ -107,11 +110,13 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def get_fee(params)
+      requires!(params, :DonationLineItems, :TipAmount, :CardType)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('GetFee', call_params, @use_sandbox)
+      response = nfg_soap_request('GetFee', call_params)
       if response.is_a? REXML::Element
         if response.elements['ErrorDetails'].elements['ErrorInfo'].nil?
           {
+            'StatusCode' => 'Success',
             'Message' => response.elements['Message'].get_text.to_s,
             'ErrorDetails' => response.elements['ErrorDetails'].get_text.to_s,
             'CallDuration' => response.elements['CallDuration'].get_text.to_s,
@@ -122,6 +127,7 @@ module NFGClient
           }
         else
           {
+            'StatusCode' => 'ValidationFailed',
             'Message' => response.elements['Message'].get_text.to_s,
             'ErrorDetails' => {
               'ErrorInfo' => {
@@ -140,14 +146,14 @@ module NFGClient
         response
       end
     end
-
     # Makes a donation using the given COF
     #
     # Arguments:
     #   params: (Hash)
     def make_cof_donation(params)
+      requires!(params, :DonationLineItems, :TotalAmount, :TipAmount, :DonorIpAddress, :DonorToken, :COFId)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('MakeCOFDonation', call_params, @use_sandbox)
+      response = nfg_soap_request('MakeCOFDonation', call_params)
       if response.is_a? REXML::Element
         if response.elements['StatusCode'].get_text.to_s == 'Success'
           {
@@ -183,8 +189,9 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def make_donation_add_cof(params)
+      requires!(params, :DonationLineItems, :TotalAmount, :TipAmount, :DonorIpAddress, :DonorToken, :DonorFirstName, :DonorLastName, :DonorEmail, :DonorAddress1, :DonorAddress2, :DonorCity, :DonorState, :DonorZip, :DonorCountry, :DonorPhone, :CardType, :NameOnCard, :CardNumber, :ExpMonth, :ExpYear, :CSC)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('MakeDonationAddCOF', call_params, @use_sandbox)
+      response = nfg_soap_request('MakeDonationAddCOF', call_params)
       if response.is_a? REXML::Element
         if (response.elements['StatusCode'].get_text.to_s == 'Success') || ((response.elements['StatusCode'].get_text.to_s != 'Success') && response.elements['ErrorDetails'].elements['ErrorInfo'].nil?)
           {
@@ -220,8 +227,9 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def get_donor_donation_history(params)
+      requires!(params, :DonorToken)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('GetDonorDonationHistory', call_params, @use_sandbox)
+      response = nfg_soap_request('GetDonorDonationHistory', call_params)
       if response.is_a? REXML::Element
         response_hash = {
           'StatusCode' => response.elements['StatusCode'].get_text.to_s,
@@ -254,8 +262,9 @@ module NFGClient
     # Arguments:
     #   params: (Hash)
     def get_donation_report(params)
+      requires!(params, :StartDate, :EndDate, :DonationReportType)
       call_params = add_credentials_to_params(params)
-      response = nfg_soap_request('GetDonationReport', call_params, @use_sandbox)
+      response = nfg_soap_request('GetDonationReport', call_params)
       if response.is_a? REXML::Element
         response_hash = {
           'StatusCode' => response.elements['StatusCode'].get_text.to_s,

data/lib/nfg-client/utils.rb

@@ -21,32 +21,21 @@ module NFGClient
     # Arguments:
     #   nfg_method: (String)
     #   params: (Hash)
-    def nfg_soap_request(nfg_method, params, use_sandbox = false)
+    def nfg_soap_request(nfg_method, params)
       if (nfg_method.is_a? String) && (params.is_a? Hash)
-        # Build SOAP 1.2 request
-        soap_request = build_nfg_soap_request(nfg_method,params)
         
-        # Build request URL & header
-        host = use_sandbox ? @@nfg_urls['sandbox']['host'] : @@nfg_urls['production']['host']
-        url = use_sandbox ? @@nfg_urls['sandbox']['url'] : @@nfg_urls['production']['url']
-        headers = {
-          'Host' => host,
-          'Content-Type' => 'application/soap+xml; charset=utf-8',
-          'Content-Length' => soap_request.length.to_s,
-          'SOAPAction' => "#{url}/#{nfg_method}".gsub('.asmx','')
-        }
+        # Build SOAP 1.2 request
+        soap_request = build_nfg_soap_request(nfg_method, params)
+
+        headers = format_headers(nfg_method, soap_request)
 
         return_value = Hash.new
 
         # Being HTTP Post
         begin
-          uri = URI.parse(url)
-          https_conn = Net::HTTP.new(uri.host, uri.port)
-          https_conn.use_ssl = true
-          response = https_conn.post(uri.path, soap_request, headers)          
+          response = ssl_post(soap_request, headers)
           if response.code == '200'
             parsed = REXML::Document.new(response.body)
-            #return response.body
             # Build return hash parsing XML response
             if parsed.root.nil?
               return_value['StatusCode'] = 'MissingParameter'
@@ -61,6 +50,7 @@ module NFGClient
             return_value['ErrorDetails'] = response.body
           end
         rescue StandardError => e
+          p e
           return_value['StatusCode'] = 'UnexpectedError'
           return_value['Message'] = e
           return_value['ErrorDetails'] = e.backtrace.join(' ')
@@ -70,22 +60,85 @@ module NFGClient
       else
         raise ArgumentError.new('http_post requires a nfg_method and a hash of params')
       end
-    end   
+    end
 
+    # Returns a complete NFG SOAP request based on the provided target method and params
     def build_nfg_soap_request(nfg_method, params)
       get_nfg_soap_request_template.gsub('|body|',"<#{nfg_method} xmlns=\"http://api.networkforgood.org/partnerdonationservice\">#{hash_to_xml(params)}</#{nfg_method}>")
     end
 
+    # Returns a SOAP template with no body
     def get_nfg_soap_request_template
       "<?xml version=\"1.0\" encoding=\"utf-8\"?><soap12:Envelope xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:soap12=\"http://www.w3.org/2003/05/soap-envelope\"><soap12:Body>|body|</soap12:Body></soap12:Envelope>"
     end
 
+    # Makes HTTPS post request with given body (soap_request) and headers
+    #
+    # Arguments:
+    #   soap_request: (String)
+    #   headers: (Hash)
+    def ssl_post(soap_request, headers)
+       uri = URI.parse(url)
+       https_conn = Net::HTTP.new(uri.host, uri.port)
+       https_conn.use_ssl = true
+       https_conn.post(uri.path, soap_request, headers)
+    end
+
+    # Returns NFG friendly headers hash for HTTPS post
+    #
+    # Arguments:
+    #   nfg_method: (String)
+    #   soap_request: (String)
+    def format_headers(nfg_method, soap_request)
+      {
+        'Host' => host,
+        'Content-Type' => 'application/soap+xml; charset=utf-8',
+        'Content-Length' => soap_request.length.to_s,
+        'SOAPAction' => "#{url}/#{nfg_method}".gsub('.asmx','')
+      }
+    end
+
+    # Returns NFG target host
+    def host
+      return @@nfg_urls['sandbox']['host'] if @use_sandbox
+      @@nfg_urls['production']['host']
+    end
+
+    # Returns NFG target URL
+    def url
+      return @@nfg_urls['sandbox']['url'] if @use_sandbox
+      @@nfg_urls['production']['url']
+    end
+
+    # Returns a string containing an XML representation of the given hash
+    #
+    # Arguments:
+    #   hash: (Hash)
     def hash_to_xml(hash)
       hash.map do |k, v|
         text = (v.is_a? Hash) ? hash_to_xml(v) : v
-        xml_elem = (v.is_a? Hash) ? k.gsub(/(\d)/, "") : k
+        # It removes the digits at the end of each "DonationItem" hash key
+        xml_elem = (v.is_a? Hash) ? k.to_s.gsub(/(\d)/, "") : k
         "<%s>%s</%s>" % [xml_elem, text, xml_elem]
       end.join
     end
+
+    # Raises an exception if the required params are not part of the given hash
+    #
+    # Arguments:
+    #   hash: (Hash)
+    #   *params: (Array or Symbol)
+    def requires!(hash, *params)
+      params.each do |param|
+        if param.is_a?(Array)
+          raise ArgumentError.new("Missing required parameter: #{param.first}") unless hash.has_key?(param.first) || hash.has_key?(param.first.to_s)
+
+          valid_options = param[1..-1]
+          raise ArgumentError.new("Parameter: #{param.first} must be one of #{valid_options.to_sentence(:words_connector => 'or')}") unless valid_options.include?(hash[param.first]) || valid_options.include?(hash[param.first.to_s])
+        else
+          raise ArgumentError.new("Missing required parameter: #{param}") unless hash.has_key?(param) || hash.has_key?(param.to_s)
+        end
+      end
+    end
   end
 end

data/lib/nfg-client/version.rb

@@ -1,3 +1,3 @@
 module NFGClient
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/nfg-client.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency 'rspec', '~> 2.13.0'
   gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'mocha'
 end

data/spec/remote/nfg-client_remote_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+
+# Your ip address must be whitelisted at NFG for these tests to work
+
+
+describe NFGClient do
+  let(:nfg_client) { NFGClient.new(PartnerID, PartnerPW, PartnerSource, PartnerCampaign, true) }
+  describe "create_cof" do
+    context 'with valid information' do
+      it "should create a card on file" do
+        result = nfg_client.create_cof(create_cof_params)
+        expect(result["StatusCode"]).to eql('Success')
+        expect(result["DonorToken"]).to eql(create_cof_params[:DonorToken])
+        expect(result["COFId"]).to_not eq('0')
+      end
+    end
+
+    context "with invalid information" do
+      it "should not create a card on file" do
+        result = nfg_client.create_cof(create_cof_params.merge({ ExpYear: '14' }))
+        expect(result["StatusCode"]).to eql('ValidationFailed')
+        expect(result["DonorToken"]).to eql(create_cof_params[:DonorToken])
+        expect(result["COFId"]).to eql('0')
+      end
+    end
+  end
+
+  describe "get_fee" do
+    context 'with valid information' do
+      it "should be successful" do
+        result = nfg_client.get_fee(get_fee_params)
+        expect(result["StatusCode"]).to eql('Success')
+        expect(result["TotalChargeAmount"]).to eql("100.0")
+      end
+    end
+
+    context 'with invalid information' do
+      it "should not be successful" do
+        result = nfg_client.get_fee(get_fee_params('12-1212121'))
+        expect(result["StatusCode"]).to eql('ValidationFailed')
+        expect(result["ErrorDetails"]["ErrorInfo"]["ErrCode"]).to eql('NpoNotFound')
+      end
+    end
+  end
+
+  describe "delete_donor_cof" do
+    context "with valid information" do
+      it "should remove the cof" do
+        result = nfg_client.create_cof(create_cof_params)
+        result = nfg_client.delete_donor_cof(  { DonorToken: result['DonorToken'], COFId: result['COFId']})
+        expect(result["StatusCode"]).to eql('Success')
+      end
+    end
+
+    context "with invalid COFId" do
+      it "should return an error" do
+        result = nfg_client.delete_donor_cof( delete_donor_cof_params )
+        expect(result["StatusCode"]).to eql('OtherError')
+      end
+    end
+  end
+
+  describe "make_cof_donation" do
+    context "with valid information" do
+      it "should make the donation" do
+        result = nfg_client.create_cof(create_cof_params)
+        result = nfg_client.make_cof_donation(make_cof_donation_params(result['COFId']))
+        expect(result["StatusCode"]).to eql('Success')
+        expect(result["ChargeId"]).to_not eq('0')
+      end
+    end
+
+    context "with invalid information" do
+      it "should not make the donation" do
+        result = nfg_client.make_cof_donation(make_cof_donation_params)
+        expect(result["StatusCode"]).to eql('ValidationFailed')
+        expect(result["ChargeId"]).to eq('0')
+        expect(result["ErrorDetails"]["ErrorInfo"]["ErrCode"]).to eql('COFNotFound')
+      end
+    end
+  end
+
+  describe "make_donation_add_cof" do
+    context "with valid information" do
+      it "should make the donation" do
+        result = nfg_client.make_donation_add_cof(make_donation_add_cof_params)
+        expect(result["StatusCode"]).to eql('Success')
+        expect(result["ChargeId"]).to_not eq('0')
+        expect(result["COFId"]).to_not eq('0')
+      end
+    end
+
+    context "with invalid information" do
+      it "should not make the donation" do
+        result = nfg_client.make_donation_add_cof(make_donation_add_cof_params('444'))
+        expect(result["StatusCode"]).to eql('ChargeFailed')
+        expect(result["ChargeId"]).to_not eq('0')
+        expect(result["COFId"]).to eq('0')
+      end
+    end
+  end
+
+  describe "get_donor_donation_history" do
+    it "should return something" do
+      result = nfg_client.create_cof(create_cof_params)
+      params = make_donation_add_cof_params
+      result = nfg_client.make_donation_add_cof(params)
+      result =  nfg_client.get_donor_donation_history(DonorToken: params[:DonorToken])
+
+      expect(result["StatusCode"]).to eql('Success')
+      expect(result["Donations"]).to eql('Success')
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -1,6 +1,14 @@
 require 'simplecov'
+require 'mocha/api'
+require 'andand'
+
+require 'nfg-client'
+
 SimpleCov.start
 
+# load all of the files in the support folder
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
 # This file was generated by the `rspec --init` command. Conventionally, all
 # specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
 # Require this file using `require "spec_helper"` to ensure that it is only

data/spec/support/api_parameters.rb

@@ -0,0 +1,134 @@
+def create_cof_params
+  {
+    DonorIpAddress: '198.168.200.200',
+    DonorToken: 'AIH3939',
+    DonorFirstName: 'John',
+    DonorLastName: 'Smith',
+    DonorEmail: 'john@smith.com',
+    DonorAddress1: '123 Address Way',
+    DonorAddress2: '',
+    DonorCity: 'Baltimore',
+    DonorState: 'MD',
+    DonorZip: '21210',
+    DonorCountry: 'US',
+    DonorPhone: '410-544-8778',
+    CardType: 'Visa',
+    NameOnCard: 'John Smith',
+    CardNumber: '4111111111111111',
+    ExpMonth: '12',
+    ExpYear: '2016',
+    CSC: '123'
+  }
+end
+
+def delete_donor_cof_params
+  {
+    DonorToken: 'AIH3939',
+    COFId: '1111111',
+  }
+end
+
+def get_donation_report_params
+  {
+    StartDate: '2014-01-01 00:00:00',
+    EndDate: '2014-01-01 12:00:00',
+    DonationReportType: 'All'
+  }
+end
+
+def get_donor_cofs_params
+  {
+    DonorToken: 'AIH3939',
+  }
+end
+
+def get_donor_donation_history_params
+  {
+    DonorToken: 239949
+  }
+end
+
+# default is NFG EIN
+def get_fee_params(npo_ein = '68-0480736')
+  {
+    DonationLineItems: {
+      DonationItem: {
+        NpoEin: npo_ein,
+        Designation: 'annual_fund',
+        Dedication: 'For my grandfather',
+        donorVis: 'ProvideAll',
+        ItemAmount: 100.00,
+        RecurType: 'NotRecurring',
+        AddOrDeduct: 'Add',
+        TransactionType: 'Donation'
+      }
+    },
+    TipAmount: 3.00,
+    CardType: 'Visa'
+  }
+end
+
+def make_cof_donation_params(cof_id = '11111111')
+  {
+    DonationLineItems: {
+      DonationItem: {
+        NpoEin: '68-0480736',
+        Designation: 'annual_fund',
+        Dedication: 'For my grandfather',
+        donorVis: 'ProvideAll',
+        ItemAmount: 100.00,
+        RecurType: 'NotRecurring',
+        AddOrDeduct: 'Add',
+        TransactionType: 'Donation'
+      }
+    },
+    TotalAmount: 100.00,
+    TipAmount: 3.00,
+    PartnerTransactionIdentifier: 'my_order_id',
+    DonorIpAddress: '198.168.200.200',
+    DonorToken: 'AIH3939',
+    COFId: cof_id
+  }
+end
+
+def make_donation_add_cof_params(csc = '123')
+  {
+    DonationLineItems: {
+      DonationItem: {
+        NpoEin: '68-0480736',
+        Designation: 'annual_fund',
+        Dedication: 'For my grandfather',
+        donorVis: 'ProvideAll',
+        ItemAmount: 100.00,
+        RecurType: 'NotRecurring',
+        AddOrDeduct: 'Add',
+        TransactionType: 'Donation'
+      }
+    },
+    TotalAmount: 100.00,
+    TipAmount: 3.00,
+    PartnerTransactionIdentifier: 'my_order_id',
+    DonorIpAddress: '198.168.200.200',
+    DonorToken: donor_token,
+    DonorFirstName: 'John',
+    DonorLastName: 'Smith',
+    DonorEmail: 'john@smith.com',
+    DonorAddress1: '100 Address Way',
+    DonorAddress2: '',
+    DonorCity: 'Baltimore',
+    DonorState: 'MD',
+    DonorZip: '21210',
+    DonorCountry: 'US',
+    DonorPhone: '410-544-8778',
+    CardType: 'Visa',
+    NameOnCard: 'John Smith',
+    CardNumber: '4111111111111111',
+    ExpMonth: '12',
+    ExpYear: '2015',
+    CSC: csc
+  }
+end
+
+def donor_token
+  'NFG_' + Time.now.strftime("%Y-%m-%d-%H%M%S")
+end