nmi_direct_post 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d376bc5d9401a3274444f713f3ef40f04a4a41e3
+  data.tar.gz: 383d6fb624a33d30f1121904b76c5b77eb0af761
+SHA512:
+  metadata.gz: d40ddf52eceb8174336a6b9675d8a3a0e7161135cbdaed6effd7c1a361c54ebcb84432e08391a9b8829ffed9dd366401123cd750ecbe488e5b9cccf13b77e8a4
+  data.tar.gz: 9ac20fafa098b00e4069d05b994f0d15175033cd6b7408c617c10cd32e0318f1c6984039db20d95606fdb7375803c5413bef446914629ef29d74120cd3a53229

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+spec/support/credentials.rb

data/.rspec

@@ -0,0 +1 @@
+--color

data/.simplecov

@@ -0,0 +1,4 @@
+if ENV['COVERAGE']
+  SimpleCov.start 'test_frameworks' do
+  end
+end

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Isaac Betesh
+
+MIT License
+
+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,83 @@
+# NmiDirectPost
+
+NmiDirectPost is a gem that encapsulates the NMI Direct Post API in an ActiveRecord-like syntax.
+For more information on the NMI Direct Post API, see:
+    https://secure.nmi.com/merchants/resources/integration/integration_portal.php
+
+To mimic ActivRecord syntax, it is necessary to blur, from the client's standpoint, the boundary between NMI's Direct Post API and its Query API.  This fuzziness is part of the encapsulation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nmi_direct_post'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nmi_direct_post
+
+## Usage
+
+1) Before you can query or post, establish the connection:
+
+    NmiDirectPost::Base.establish_connection("MY_NMI_USERNAME", "MY_NMI_PASSWORD")
+
+Theoretically, you can use a different connection for NmiDirectPost::Transaction or NmiDirectPost::CustomerVault by calling establish_connection on either of those derived classes, instead of on Base.
+However, it's hard to imagine a case where this would be useful; the option is only present to mimic the syntax of ActiveRecord.
+
+2) Query the API:
+
+    NmiDirectPost::Transaction.find_by_transaction_id(123456789)
+    NmiDirectPost::CustomerVault.find_by_customer_vault_id(123123123)
+
+3) Create a CustomerVault:
+
+    george = NmiDirectPostCustomerVault.new(:first_name => 'George', :last_name => 'Washington', :cc_number => '4111111111111111', :cc_exp => '03/17')
+    george.create
+
+4) Update a CustomerVault:
+
+    george.update!(:email => 'el_primero_presidente@whitehouse.gov', :address_1 => '1600 Pennsylvania Ave NW', :city => 'Washington', :state => 'DC', :postal_code => '20500')
+
+  ALTERNATIVELY:
+
+    george.email = 'el_primero_presidente@whitehouse.gov'
+    george.address_1 = '1600 Pennsylvania Ave NW'
+    george.city = 'Washington'
+    george.state = 'DC'
+    george.postal_code = '20500'
+    george.save! # Returns true
+
+5) Delete a CustomerVault:
+
+    george.destroy # Returns the CustomerVault
+
+6) Reload a CustomerVault:
+
+    george.email = 'el_primero_presidente@whitehouse.gov'
+    george.reload # Returns the Customer Vault
+    george.email # Returns the previously set email
+
+7) CustomerVault class methods:
+
+    NmiDirectPost::CustomerVault.all_ids # Returns array of `customer_vault_id`s
+    NmiDirectPost::CustomerVault.first
+    NmiDirectPost::CustomerVault.last
+    NmiDirectPost::CustomerVault.all # Returns very, very big array.  This method had very poor performance and could be optimized significantly in a future version of this gem.
+
+8) Create a Transaction:
+
+    parking_ticket = NmiDirectPost::Transaction(:type => :sale, :amount => 150.01, :customer_vault_id => george.customer_vault_id)
+    parking_ticket.save! # Returns true
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/nmi_direct_post.rb

@@ -0,0 +1,7 @@
+require "nmi_direct_post/version"
+require "nmi_direct_post/transaction"
+require "nmi_direct_post/customer_vault"
+
+module NmiDirectPost
+  # Your code goes here...
+end

data/lib/nmi_direct_post/base.rb

@@ -0,0 +1,102 @@
+require 'net/https'
+require 'openssl'
+
+require 'active_support/concern'
+require 'active_support/callbacks'
+require 'active_model/conversion'
+require 'active_model/validator'
+require 'active_model/callbacks'
+require 'active_support/core_ext/module/delegation'
+require 'active_model/naming'
+require 'active_model/translation'
+require 'active_model/validations'
+require 'active_model/errors'
+require 'active_support/core_ext/object/blank'
+require 'addressable/uri'
+require_relative 'logger'
+
+module NmiDirectPost
+  class Base
+    POST_URI = "https://secure.nmi.com/api/transact.php"
+    GET_URI = "https://secure.nmi.com/api/query.php"
+
+    AUTH_PARAMS = [:username, :password]
+    attr_reader *AUTH_PARAMS
+    attr_reader :response, :response_text, :response_code
+
+    include ActiveModel::Validations
+    include ActiveModel::Conversion
+    validates_presence_of :username, :password
+
+    def initialize
+      @username, @password = self.class.username, self.class.password
+    end
+
+    def persisted?
+      false
+    end
+
+    def success?
+      1 == self.response
+    end
+
+    def logger
+      NmiDirectPost.logger
+    end
+
+    class << self
+      NO_CONNECTION = "Please set a username by calling NmiDirectPost::Base.establish_connection(ENV['NMI_USERNAME'], ENV['NMI_PASSWORD'])"
+      def establish_connection(username, password)
+        @username, @password = username, password
+      end
+
+      def username
+        @username || (in_base? ? raise_no_connection_error : superclass.username).tap { |_| raise_no_connection_error if _.blank? }
+      end
+
+      def password
+        @password || (in_base? ? raise_no_connection_error : superclass.password).tap { |_| raise_no_connection_error if _.blank? }
+      end
+
+      def generate_query_string(attributes, target = self)
+        ((attributes.reject { |attr| target.__send__(attr).blank? }).collect { |attr| "#{attr}=#{Addressable::URI.escape(target.__send__(attr).to_s)}"}).join('&')
+      end
+
+      def get(query)
+        uri = [GET_URI, query].join('?')
+        data = get_http_response(uri).body
+        Hash.from_xml(data)["nm_response"]
+      end
+
+      def post(query)
+        uri = [POST_URI, query].join('?')
+        data = get_http_response(uri)
+        Addressable::URI.parse([POST_URI, data.body].join('?')).query_values
+      end
+
+      protected
+        def get_http_response(uri)
+          request = Net::HTTP::Get.new(uri)
+          url = URI.parse(uri)
+          http = Net::HTTP.new(url.host, url.port)
+          http.use_ssl = true
+          http.ssl_version = :TLSv1
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.request(request)
+        end
+
+        def in_base?
+          'Object' == superclass.name
+        end
+
+        def raise_no_connection_error
+          raise(StandardError, NO_CONNECTION)
+        end
+    end
+
+    protected
+      def generate_query_string(attributes)
+        self.class.generate_query_string(attributes, self)
+      end
+  end
+end

data/lib/nmi_direct_post/customer_vault.rb

@@ -0,0 +1,245 @@
+require 'active_model/serialization'
+require 'active_model/serializers/xml'
+require 'active_support/core_ext/hash/indifferent_access'
+require_relative 'base'
+
+module NmiDirectPost
+  class CustomerVaultNotFoundError < StandardError; end
+
+  class CustomerVaultInvalidPostActionError < StandardError; end
+
+  module MassAssignmentSecurity
+    class Error < StandardError; end
+  end
+
+  class CustomerVault < Base
+    private
+      def self.attr_accessor_with_tracking_of_changes(*list)
+        list.each do |attr|
+          attr_reader attr
+          define_method("#{attr}=") do |val|
+            (@attributes_to_save ||=[]) << attr
+            instance_variable_set("@#{attr}", val)
+          end
+        end
+      end
+    public
+    READ_ONLY_ATTRIBUTES ||= [:check_hash, :cc_hash]
+    attr_reader *READ_ONLY_ATTRIBUTES
+    attr_reader :customer_vault_id, :customer_vault, :report_type
+
+    MERCHANT_DEFINED_FIELDS ||= 20.times.collect { |i| :"merchant_defined_field_#{i+1}" }
+    WHITELIST_ATTRIBUTES ||= [:id, :first_name, :last_name, :address_1, :address_2, :company, :city, :state, :postal_code, :country, :email, :phone, :fax, :cell_phone, :customertaxid, :website, :shipping_first_name, :shipping_last_name, :shipping_address_1, :shipping_address_2, :shipping_company, :shipping_city, :shipping_state, :shipping_postal_code, :shipping_country, :shipping_email, :shipping_carrier, :tracking_number, :shipping_date, :shipping, :cc_number, :cc_exp, :cc_issue_number, :check_account, :check_aba, :check_name, :account_holder_type, :account_type, :sec_code, :processor_id, :cc_bin, :cc_start_date] + MERCHANT_DEFINED_FIELDS
+    attr_accessor_with_tracking_of_changes *WHITELIST_ATTRIBUTES
+
+    validate :billing_information_present?, :if => Proc.new { |record| :add_customer == record.customer_vault }
+    validates_presence_of :customer_vault_id, :message => "You must specify a %{attribute} ID when looking up an individual customer vault", :if => Proc.new { |record| :customer_vault == record.report_type }
+    validates_presence_of :customer_vault_id, :message => "You must specify a %{attribute} ID when updating a customer vault", :if => Proc.new { |record| :update_customer == record.customer_vault }
+    validates_inclusion_of :customer_vault_id, :in => [nil], :message => "You cannot specify a %{attribute} ID when creating a new customer vault.  NMI will assign one upon creating the record",
+        :if => Proc.new { |record| :add_customer == record.customer_vault }
+
+    def initialize(attributes)
+      super()
+      if attributes[:customer_vault_id].blank?
+        set_attributes(attributes.dup) unless attributes.empty?
+      else
+        @customer_vault_id = attributes[:customer_vault_id].to_i
+        reload
+      end
+    end
+
+    def create
+      post_action(:add)
+      self.success?
+    end
+
+    def update!(attributes)
+      begin
+        set_attributes(attributes)
+        post_action(:update)
+      ensure
+        @attributes_to_save.delete_if {|v| @attributes_to_update.include?(v) } if @attributes_to_save
+        @attributes_to_update = nil
+      end
+      self
+    end
+
+    def save!
+      post_action(:update)
+      reload
+      self.success?
+    end
+
+    def destroy
+      post_action(:delete)
+      self
+    end
+
+    def reload
+      @report_type = :customer_vault
+      if invalid?
+        @report_type = nil
+        return self
+      end
+      begin
+        safe_params = customer_vault_instance_params
+        logger.debug { "Loading NMI customer vault from customer_vault_id(#{customer_vault_id}) using query: #{safe_params}" }
+        response = self.class.get(self.class.all_params(safe_params))["customer_vault"]
+        raise CustomerVaultNotFoundError, "No record found for customer vault ID #{self.customer_vault_id}" if response.nil?
+        attributes = response["customer"].with_indifferent_access
+        READ_ONLY_ATTRIBUTES.each do |a|
+          if attributes.key?(a)
+            val = attributes.delete(a)
+            instance_variable_set("@#{a}",val)
+          end
+        end
+        set_attributes(attributes.tap { |_| _.delete(:customer_vault_id) })
+      ensure
+        @report_type = nil
+        @attributes_to_update = nil
+        @attributes_to_save = nil
+      end
+      self
+    end
+
+    def credit_card?
+      !@cc_hash.blank?
+    end
+
+    def checking?
+      !@check_hash.blank?
+    end
+
+    def find!
+      begin
+        @report_type = :customer_vault
+        safe_params = generate_query_string(MERCHANT_DEFINED_FIELDS + [:last_name, :email, :report_type]) # These are the only fields you can use when looking up without a customer_vault_id
+        logger.info { "Querying NMI customer vault: #{safe_params}" }
+        @customer_vault_id = self.class.get(self.class.all_params(safe_params))['customer_vault'][0]['customer_vault_id'] # This assumes there is only 1 result.
+        # TODO: When there are multiple results, we don't know which one you want.  Maybe raise an error in that case?
+        reload
+      ensure
+        @report_type = nil
+      end
+    end
+
+    class << self
+      attr_reader :report_type
+
+      def find_by_customer_vault_id(customer_vault_id)
+        raise StandardError, "CustomerVaultID cannot be blank" if customer_vault_id.blank?
+        begin
+          new(:customer_vault_id => customer_vault_id)
+        rescue CustomerVaultNotFoundError
+          return nil
+        end
+      end
+
+      def first(limit = 1)
+        limit(0, limit-1).first
+      end
+
+      def last(limit = 1)
+        limit(-limit, -1).first
+      end
+
+      def all_ids
+        @report_type = :customer_vault
+        safe_params = generate_query_string([:report_type])
+        NmiDirectPost.logger.debug { "Loading all NMI customer vaults using query: #{safe_params}" }
+        begin
+          customers = get(all_params(safe_params))["customer_vault"]
+        ensure
+          @report_type = nil
+        end
+        return [] if customers.nil?
+        customers = customers["customer"]
+        customers.collect { |customer| customer["customer_vault_id"].to_i }
+      end
+
+      def all
+        limit
+      end
+
+      def all_params(safe_params)
+        [safe_params, generate_query_string(Base::AUTH_PARAMS)].join('&')
+      end
+
+      private
+        def limit(first = 0, last = -1)
+          all_ids[first..last].collect { |id| new(:customer_vault_id => id) }
+        end
+    end
+
+    private
+      def customer_vault_instance_params
+        generate_query_string([:customer_vault, :customer_vault_id, :report_type])
+      end
+
+      def post(safe_params)
+        logger.info { "Sending Direct Post to NMI: #{safe_params}" }
+        response = self.class.post(self.class.all_params(safe_params))
+        @response, @response_text, @response_code = response["response"].to_i, response["responsetext"], response["response_code"].to_i
+        @customer_vault_id = response["customer_vault_id"].to_i if :add_customer == self.customer_vault
+      end
+
+      def set_attributes(attributes)
+        attributes = attributes.with_indifferent_access
+        @attributes_to_update = []
+        merchant_defined_fields = []
+        if attributes.key?(:merchant_defined_field) && attributes[:merchant_defined_field].is_a?(String)
+          self.merchant_defined_field_1 = attributes.delete(:merchant_defined_field)
+        end
+        WHITELIST_ATTRIBUTES.each do |a|
+          if attributes.key?(a)
+            val = attributes.delete(a)
+            @attributes_to_update << a
+          end
+          merchant_defined_field_index = a.to_s.split('merchant_defined_field_')[1]
+          if (!merchant_defined_field_index.nil? && val.nil? && attributes.key?(:merchant_defined_field) && attributes[:merchant_defined_field].is_a?(Array))
+            index = merchant_defined_field_index.to_i - 1
+            if attributes[:merchant_defined_field].size > index
+              val = attributes[:merchant_defined_field][index]
+              attributes[:merchant_defined_field][index] = nil
+              @attributes_to_update << a
+            end
+          end
+          self.__send__("#{a}=", val) if @attributes_to_update.include?(a)
+        end
+        attributes.delete(:merchant_defined_field) unless attributes.key?(:merchant_defined_field) && attributes[:merchant_defined_field].any?
+        @id = @id.to_i if @id
+        raise MassAssignmentSecurity::Error, "Cannot mass-assign the following attributes: #{attributes.keys.join(", ")}" unless attributes.empty?
+      end
+
+      def billing_information_present?
+        self.errors.add(:billing_information, "Either :cc_number (a credit card number) and :cc_exp (the credit card expiration date), or :check_account, :check_aba (the routing number of the checking account) and :check_name (a nickname for the account), must be present") if (missing_cc_information? && missing_checking_information?)
+      end
+
+      def missing_checking_information?
+        self.check_account.blank? || self.check_aba.blank? || self.check_name.blank?
+      end
+
+      def missing_cc_information?
+        self.cc_exp.blank? || self.cc_number.blank?
+      end
+
+      def post_action(action)
+        @customer_vault = :"#{action}_customer"
+        safe_params = case action.to_sym
+        when :delete
+          customer_vault_instance_params
+        when :add
+          [customer_vault_instance_params, generate_query_string(WHITELIST_ATTRIBUTES)].join("&")
+        when :update
+          [customer_vault_instance_params, generate_query_string(@attributes_to_update || @attributes_to_save)].join("&")
+        else
+          raise CustomerVaultInvalidPostActionError, "#{action} is not a valid post action.  NmiDirectPost allows the following post actions: :add, :update, :delete"
+        end
+        begin
+          post(safe_params) if valid?
+        ensure
+          @customer_vault = nil
+        end
+      end
+  end
+end