ach_client 0.5.1

data/lib/ach_client/abstract/abstract_method_error.rb

@@ -0,0 +1,3 @@
+# To be raised when someone tries to call an abstract method
+class AbstractMethodError < RuntimeError
+end

data/lib/ach_client/helpers/dollars_to_cents.rb

@@ -0,0 +1,15 @@
+module AchClient
+  # Utility classes shared by all providers
+  class Helpers
+
+    # Turns dollars into cents
+    class DollarsToCents
+
+      # @param dollars [Float | BigDecimal | Fixnum | Integer]
+      # @return [Fixnum] cents
+      def self.dollars_to_cents(dollars)
+        (dollars.to_f.round(2) * 100).to_i
+      end
+    end
+  end
+end

data/lib/ach_client/logging/log_provider_job.rb

@@ -0,0 +1,36 @@
+module AchClient
+  class Logging
+    # Worker to asynchronously invoke the log provider
+    class LogProviderJob
+      include SuckerPunch::Job
+
+      ## Prettifies the xml and sends it asynchronously to the log provider
+      # @param xml [String] xml body to log
+      # @param name [String] title for the log
+      def perform(body:, name:)
+        # Savon logger does a nice job of XML pretty print
+        # Takes: message, list of filters, pretty print boolean
+        AchClient::Logging.log_provider.send_logs(
+          body: maybe_encrypt_message(
+            message: Savon::LogMessage.new(
+              body,
+              AchClient::Logging.log_filters,
+              true
+            ).to_s
+          ),
+          name: name
+        )
+      end
+
+      private
+      def maybe_encrypt_message(message:)
+        # Only encrypt if the client provided a password and a salt
+        if AchClient::Logging.should_use_encryption?
+          AchClient::Logging.codec.encrypt_and_sign(message)
+        else
+          message
+        end
+      end
+    end
+  end
+end

data/lib/ach_client/logging/log_providers/log_provider.rb

@@ -0,0 +1,22 @@
+module AchClient
+  class Logging
+    # Base class for log providers
+    # Extending classes must implement send_logs
+    # The consumer may implement their own log provider and assign it to
+    # AchClient:
+    # ```ruby
+    # class MyCustomLogger < AchClient::Logging::LogProvider
+    #   def self.send_logs(body:, name:)
+    #     # Do whatever you want, like send the log data to S3, or whatever
+    #     #   logging service you choose
+    #   end
+    # end
+    # AchClient::Logging.log_provider = MyCustomLogger
+    # ```
+    class LogProvider
+      def self.send_logs(body:, name:)
+        raise AbstractMethodError, "#{body}#{name}"
+      end
+    end
+  end
+end

data/lib/ach_client/logging/log_providers/null_log_provider.rb

@@ -0,0 +1,14 @@
+module AchClient
+  class Logging
+
+    # A log provider that does nothing.
+    class NullLogProvider < LogProvider
+
+      # Does absolutely nothing with the log info
+      def self.send_logs(*)
+        # Do nothing
+        nil
+      end
+    end
+  end
+end

data/lib/ach_client/logging/log_providers/stdout_log_provider.rb

@@ -0,0 +1,14 @@
+module AchClient
+  class Logging
+    # Logs to stdout (using puts)
+    class StdoutLogProvider < LogProvider
+      # Prints the name and then the body
+      # @param body [String] the log body
+      # @param name [String] the log name
+      def self.send_logs(body:, name:)
+        puts name
+        puts body
+      end
+    end
+  end
+end

data/lib/ach_client/logging/logging.rb

@@ -0,0 +1,76 @@
+require_relative './savon_observer.rb'
+require_relative './log_providers/log_provider.rb'
+
+module AchClient
+  # Base class for all things logging
+  class Logging
+
+    # Register our observer with Savon
+    Savon.observers << AchClient::Logging::SavonObserver.new
+
+    # @return [Class] type of the log provider
+    class_attribute :_log_provider_type
+
+    # @return [String] password to use for encrypting logs
+    class_attribute :encryption_password
+
+    # @return [String] salt to use for encrypting logs
+    class_attribute :encryption_salt
+
+    # Defaults to AchClient::Logging::NullLogProvider
+    # @return [Class] The Log provider to use.
+    def self.log_provider
+      self._log_provider_type || AchClient::Logging::NullLogProvider
+    end
+
+    # Set the log provider
+    # Must extend AchClient::Logging::LogProvider
+    # @param [Class] the new log provider
+    def self.log_provider=(log_provider)
+      if log_provider.is_a?(Class) &&
+         log_provider < AchClient::Logging::LogProvider
+        self._log_provider_type = log_provider
+      else
+        raise 'Must be subclass of AchClient::Logging::LogProvider'
+      end
+    end
+
+    # @return [Array<String>] List of XML nodes to scrub
+    class_attribute :_log_filters
+
+    # @return [Array<String>] List of XML nodes to scrub
+    def self.log_filters
+      self._log_filters || []
+    end
+
+    # Updates the log filters
+    # @param filters [Array<String>] List of XML nodes to scrub from the logs
+    def self.log_filters=(filters)
+      self._log_filters = filters
+    end
+
+    # Creates a codec (does encryption and decryption) using the provided
+    # password and salt
+    # @return [ActiveSupport::MessageEncryptor] the encryptor
+    def self.codec
+      ActiveSupport::MessageEncryptor.new(
+        ActiveSupport::KeyGenerator.new(
+          AchClient::Logging.encryption_password
+        ).generate_key(AchClient::Logging.encryption_salt)
+      )
+    end
+
+    # Returns whether the client has enabled encryption - if both a username and
+    # salt have been provided
+    # @return [Boolean] is encryption enabled?
+    def self.should_use_encryption?
+      encryption_password && encryption_salt
+    end
+
+    # Decrypt encrypted log file
+    # @param gibberish [String] the log body to decrypt
+    def self.decrypt_log(gibberish)
+      codec.decrypt_and_verify(gibberish)
+    end
+  end
+end

data/lib/ach_client/logging/savon_observer.rb

@@ -0,0 +1,26 @@
+module AchClient
+  class Logging
+    # Hooks into every savon request.
+    # #notify is called before the request is made
+    class SavonObserver
+
+      ##
+      # Hooks into every SOAP request and sends the XML body to be logged.
+      # @param operation_name [Symbol] name of SOAP operation being exectuted
+      # @param builder [Savon::Builder] Savon wrapper for the request
+      # @param globals [Savon::GlobalOptions] Savon's global options
+      # @param locals [Savon::LocalOptions] Savon's global options
+      # @return [NilClass] returns nothing so the request is not mutated
+      def notify(operation_name, builder, _globals, _locals)
+        # Send the xml body to the logger job
+        AchClient::Logging::LogProviderJob.perform_async(
+          body: builder.to_s,
+          name: "request-#{operation_name}-#{DateTime.now}.xml"
+        )
+
+        # Must return nil so the request is unaltered
+        nil
+      end
+    end
+  end
+end

data/lib/ach_client/objects/account_types.rb

@@ -0,0 +1,32 @@
+module AchClient
+  ## Representations of merchant account types (checking or savings)
+  module AccountTypes
+    ## Base class for all account types
+    class AccountType
+    end
+
+    ## Represents a checking account
+    class Checking < AchClient::AccountTypes::AccountType
+    end
+
+    ## Represents a savings account
+    class Savings < AchClient::AccountTypes::AccountType
+    end
+
+    ## Represents a business checking account
+    class BusinessChecking < AchClient::AccountTypes::Checking
+    end
+
+    ## Represents a business savings account
+    class BusinessSavings < AchClient::AccountTypes::Savings
+    end
+
+    ## Represents a personal checking account
+    class PersonalChecking < AchClient::AccountTypes::Checking
+    end
+
+    ## Represents a personal savings account
+    class PersonalSavings < AchClient::AccountTypes::Savings
+    end
+  end
+end

data/lib/ach_client/objects/responses/ach_response.rb

@@ -0,0 +1,15 @@
+module AchClient
+  # Abstract Response wrapper for the various ACH response statuses
+  class AchResponse
+
+
+    attr_reader :amount, # Amount of the processed ACH
+                :date # Date the Ach was in this status
+
+    def initialize(amount:, date:)
+      raise AbstractMethodError if self.class == AchClient::AchResponse
+      @amount = amount
+      @date = date
+    end
+  end
+end

data/lib/ach_client/objects/responses/corrected_ach_response.rb

@@ -0,0 +1,18 @@
+require_relative './returned_ach_response.rb'
+
+module AchClient
+  # Representation of an Ach return that contains a correction
+  class CorrectedAchResponse < ReturnedAchResponse
+    attr_reader :corrections
+
+    ##
+    # @param date [DateTime] date of correction return
+    # @param return_code [AchClient::ReturnCode] Ach Return code for the
+    # correction (ie AchClient::ReturnCodes.find_by(code: 'C01'))
+    # @param corrections [Hash] A hash of corrected attributes and their values
+    def initialize(amount:, date:, return_code:, corrections:)
+      @corrections = corrections
+      super(amount: amount, date: date, return_code: return_code)
+    end
+  end
+end

data/lib/ach_client/objects/responses/processing_ach_response.rb

@@ -0,0 +1,6 @@
+module AchClient
+  # The transaction is processing.
+  # Not much else to see here.
+  class ProcessingAchResponse < AchResponse
+  end
+end

data/lib/ach_client/objects/responses/returned_ach_response.rb

@@ -0,0 +1,16 @@
+module AchClient
+  # Representation of an Ach return that failed
+  class ReturnedAchResponse < AchResponse
+
+    attr_reader :return_code
+
+    ##
+    # @param date [DateTime] date of correction return
+    # @param return_code [AchClient::ReturnCode] Ach Return code for the
+    # correction (ie AchClient::ReturnCodes.find_by(code: 'C01'))
+    def initialize(amount:, date:, return_code:)
+      @return_code = return_code
+      super(amount: amount, date: date)
+    end
+  end
+end

data/lib/ach_client/objects/responses/settled_ach_response.rb

@@ -0,0 +1,5 @@
+module AchClient
+  # The transaction is settled. Huzzah!
+  class SettledAchResponse < AchResponse
+  end
+end

data/lib/ach_client/objects/return_code.rb

@@ -0,0 +1,20 @@
+module AchClient
+  # Represents an Ach Return code. Consult NACHA documentation for a full list
+  # See config/return_codes.yml for our list.
+  class ReturnCode
+
+    attr_accessor :code,
+                  :description,
+                  :reason
+
+    # Constructs a Ach return code
+    # @param code [String] the 3 char code identifier (ie 'R01')
+    # @param description [String] full explanation of the return
+    # @param reason [String] shorter explanation of the return
+    def initialize(code:, description:, reason: nil)
+      @code = code
+      @description = description
+      @reason = reason
+    end
+  end
+end

data/lib/ach_client/objects/return_codes.rb

@@ -0,0 +1,33 @@
+module AchClient
+  # Finding and listing all Ach return codes
+  class ReturnCodes
+
+    # The path to the file where the return codes are enumerated
+    RETURN_CODES_YAML = '../../../config/return_codes.yml'
+
+    class_attribute :_return_codes
+
+    # @return [Array<AchClient::ReturnCode>] A list of all return codes.
+    def self.all
+      self._return_codes ||= YAML.load_file(
+        File.expand_path(File.join(File.dirname(__FILE__), RETURN_CODES_YAML))
+      ).map do |code|
+        ReturnCode.new(
+          code: code['code'],
+          description: code['description'],
+          reason: code['reason']
+        )
+      end
+    end
+
+    # Finds the first ReturnCode with the given code, or raises an exception.
+    # @param [String] 3 char code identifier for a return code
+    # @param [AchClient::ReturnCode] The ReturnCode object with that code
+    def self.find_by(code:)
+      self.all.find do |return_code|
+        return_code.code == code
+      # For some reason || is bad syntax in this context
+      end or raise "Could not find return code #{code}"
+    end
+  end
+end

data/lib/ach_client/objects/transaction_types.rb

@@ -0,0 +1,16 @@
+module AchClient
+  ## Representations of Ach transaction types (debit or credit)
+  module TransactionTypes
+    ## Base class for all transaction types
+    class TransactionType
+    end
+
+    ## Representation of a credit transaction type
+    class Credit < AchClient::TransactionTypes::TransactionType
+    end
+
+    ## Representation of a debit transaction type
+    class Debit < AchClient::TransactionTypes::TransactionType
+    end
+  end
+end

data/lib/ach_client/providers/abstract/ach_batch.rb

@@ -0,0 +1,23 @@
+module AchClient
+  # Abstract Ach provider, which all other provider's inherit from
+  class Abstract
+
+    # Base class for sending batched ACH transactions to various providers
+    class AchBatch
+
+      ##
+      # @param ach_transactions [Array] List of AchTransaction objects to batch
+      def initialize(ach_transactions: [])
+        @ach_transactions = ach_transactions
+      end
+
+      ##
+      # Sends the batch to the provider, and returns a tracking identifier
+      # @return [Array<String>] Identifiers to use to poll for result of batch
+      # processing later on.
+      def send_batch
+        raise AbstractMethodError
+      end
+    end
+  end
+end

data/lib/ach_client/providers/abstract/ach_status_checker.rb

@@ -0,0 +1,21 @@
+module AchClient
+  class Abstract
+
+    # Interface for polling provider for ACH status responses
+    class AchStatusChecker
+      # Wrapper for a provider's "most recent bucket"
+      # @return [Hash{String => AchClient::AchResponse}] Hash with provider's
+      #   external ACH id as the key, AchResponse objects as values
+      def self.most_recent
+        raise AbstractMethodError
+      end
+
+      # Wrapper for a providers range response endpoint
+      # @return [Hash{String => AchClient::AchResponse}] Hash with provider's
+      #   external ACH id as the key, AchResponse objects as values
+      def self.in_range(*)
+        raise AbstractMethodError
+      end
+    end
+  end
+end

data/lib/ach_client/providers/abstract/ach_transaction.rb

@@ -0,0 +1,70 @@
+module AchClient
+  class Abstract
+
+    # Generic representation of a single Ach transaction
+    class AchTransaction
+
+      ##
+      # @return [Array] A list of arguments to use in the initializer, and as
+      # instance attributes
+      def self.arguments
+        [
+          :account_number,
+          :account_type,
+          :amount,
+          :effective_entry_date,
+          :external_ach_id,
+          :memo,
+          :merchant_name,
+          :originator_name,
+          :routing_number,
+          :sec_code,
+          :transaction_type
+        ]
+      end
+
+      attr_reader(*arguments)
+
+      ##
+      # @param account_number [String] Merchant's account number
+      # @param account_type [AchClient::AccountTypes::AccountType] Merchant's account type
+      #   (debit or credit), must be an instance of AchClient::AccountTypes::AccountType
+      # @param amount [BigDecimal] Amount of the ACH transaction
+      # @param effective_entry_date [Date] The date the transaction should be enacted
+      # @param external_ach_id [String] Tracking string you would like the
+      # provider to use with your transaction
+      # @param memo [String] Ach memo thing
+      # @param merchant_name [String] Name associated with merchantaccount we
+      #   are ACHing with
+      # @param originator_name [String] String identifying you, will appear on
+      #   merchants bank statement
+      # @param routing_number [String] Routing number of the merchant's account
+      # @param sec_code [String] CCD, PPD, WEB, etc.
+      #  See: https://en.wikipedia.org/wiki/Automated_Clearing_House#SEC_codes
+      # @param transaction_type [AchClient::TransactionTypes::TransactionType] debit or
+      def initialize(*arguments)
+        args = arguments.extract_options!
+        self.class.arguments.each do |param|
+          self.instance_variable_set(
+            "@#{param}".to_sym,
+            args[param]
+          )
+        end
+      end
+
+      # @return [Boolean] true if transaction is a debit
+      def debit?
+        transaction_type == AchClient::TransactionTypes::Debit
+      end
+
+      # @return [Boolean] true if transaction is a credit
+      def credit?
+        transaction_type == AchClient::TransactionTypes::Credit
+      end
+
+      def send
+        raise AbstractMethodError
+      end
+    end
+  end
+end

data/lib/ach_client/providers/abstract/company_info.rb

@@ -0,0 +1,28 @@
+module AchClient
+  class Abstract
+      # Interface for storing company credentials used with a provider
+    class CompanyInfo
+
+      ##
+      # @return [CompanyInfo] instance built from configuration values
+      def self.build
+        raise AbstractMethodError
+      end
+
+      ##
+      # Build a hash to send to provider
+      # @return [Hash] hash to send to provider
+      def to_hash
+        raise AbstractMethodError
+      end
+
+      private_class_method def self.build_from_config(args)
+        self.new(
+          args.map do |arg|
+            {arg => self.to_s.deconstantize.constantize.send(arg)}
+          end.reduce(&:merge)
+        )
+      end
+    end
+  end
+end

data/lib/ach_client/providers/abstract/response_record_processor.rb

@@ -0,0 +1,15 @@
+module AchClient
+  class Abstract
+    ## Interface for turning a Provider's response representation of an ACH
+    # status into an instance of AchClient::Response
+    class ResponseRecordProcessor
+      ## Interface for turning a Provider's response representation of an ACH
+      # status into an instance of AchClient::Response
+      # @param record [Object] the record from the provider
+      # @return [AchClient::AchResponse] our representation of the response
+      def self.process_response_record(_record)
+        raise AbstractMethodError
+      end
+    end
+  end
+end

data/lib/ach_client/providers/abstract/transformer.rb

@@ -0,0 +1,38 @@
+module AchClient
+  ##
+  # Transforms between client class and the strings that the provider expects
+  # For example, the TransactionType classes are serialized as 'C' or 'D' for
+  # AchWorks
+  class Transformer
+
+    ##
+    # Convert provider's string representation to AchClient class
+    #   representation
+    # @param string [String] string to turn into class
+    # @return [Class] for example AchClient::AccountTypes::Checking or
+    # AchClient::AccountTypes::Savings
+    def self.deserialize_provider_value(string)
+      self.transformer[string] or raise(
+        "Unknown #{self} string #{string}"
+      )
+    end
+
+    ##
+    # Convert client class to string representation used by provider
+    # @param type [Class] the type to convert to a string
+    # @return [String] string serialization of the input class
+    def self.serialize_to_provider_value(type)
+      self.transformer.find do |_, v|
+        type <= v
+      end.try(:first) or raise(
+        "type must be one of #{self.transformer.values.join(', ')}"
+      )
+    end
+
+    # Mapping of classes to strings, to be overridden
+    # @return [Hash {String => Class}] the mapping
+    def self.transformer
+      raise AbstractMethodError
+    end
+  end
+end

data/lib/ach_client/providers/sftp/account_type_transformer.rb

@@ -0,0 +1,20 @@
+module AchClient
+  class Sftp
+    ##
+    # Transforms AccountTypes between AchClient class and the string
+    # that NACHA expects
+    class AccountTypeTransformer < AchClient::Transformer
+
+      # '2' means Checking, '3' means Savings
+      # The account type string is the first character in the transaction_code
+      # field.
+      # @return [Hash {String => Class}] the mapping
+      def self.transformer
+        {
+          '3' => AchClient::AccountTypes::Savings,
+          '2' => AchClient::AccountTypes::Checking
+        }
+      end
+    end
+  end
+end