ach_client 0.5.1

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

@@ -0,0 +1,97 @@
+module AchClient
+  # Namespace for all things Sftp
+  class Sftp
+    # NACHA representation of an AchBatch
+    class AchBatch < Abstract::AchBatch
+
+      def initialize(ach_transactions: [], batch_number: nil)
+        super(ach_transactions: ach_transactions)
+        @batch_number = batch_number
+      end
+
+      # The filename used for the batch
+      # @return [String] filename to use
+      def batch_file_name
+        self.class.parent.file_naming_strategy.(@batch_number)
+      end
+
+      # Sends the batch to SFTP provider
+      # @return [Array<String>]
+      def send_batch
+        self.class.parent.write_remote_file(
+          file_path: File.join(
+            self.class.parent.outgoing_path,
+            batch_file_name
+          ),
+          file_body: cook_some_nachas.to_s
+        )
+        @ach_transactions.map(&:external_ach_id)
+      end
+
+      # Converts this AchBatch into the NACHA object representation provided
+      # by the ACH gem.
+      # @return [ACH::ACHFile] Yo NACHA
+      def cook_some_nachas
+        nacha = ACH::ACHFile.new
+        nacha.instance_variable_set(:@header, nacha_file_header)
+
+        # The NACHA can have multiple batches.
+        # Transactions in the same batch must have the same originator and
+        # sec_code, so we group by sec_code and originator when building batches
+        @ach_transactions.group_by(&:sec_code).map do |sec_code, transactions|
+          transactions.group_by(&:originator_name)
+                      .map do |originator_name, batch_transactions|
+            batch_transactions.group_by(&:effective_entry_date)
+                            .map do |effective_entry_date, batched_transactions|
+              nacha.batches << nacha_batch(
+                sec_code,
+                originator_name,
+                effective_entry_date,
+                batched_transactions
+              )
+            end
+          end
+        end
+        nacha
+      end
+
+      private
+      def nacha_file_header
+        file_header = ACH::Records::FileHeader.new
+        [
+          :immediate_destination,
+          :immediate_destination_name,
+          :immediate_origin,
+          :immediate_origin_name
+        ].each do |attribute|
+          file_header.send("#{attribute}=", self.class.parent.send(attribute))
+        end
+        file_header
+      end
+
+      def nacha_batch(
+        sec_code,
+        originator_name,
+        effective_entry_date,
+        transactions
+      )
+        batch = ACH::Batch.new
+        batch_header = batch.header
+        batch_header.company_name = originator_name
+        batch_header.company_identification =
+          self.class.parent.company_identification
+        batch_header.standard_entry_class_code = sec_code
+        batch_header.company_entry_description =
+          self.class.parent.company_entry_description
+        batch_header.company_descriptive_date = effective_entry_date
+        batch_header.effective_entry_date = effective_entry_date
+        batch_header.originating_dfi_identification =
+          self.class.parent.originating_dfi_identification
+        transactions.each do |transaction|
+          batch.entries << transaction.to_entry_detail
+        end
+        batch
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+module AchClient
+  class Sftp
+    # Poll SFTP provider for Inbox files
+    class AchStatusChecker < Abstract::AchStatusChecker
+
+      ##
+      # Gets the status of ach transactions since the last time we ran this
+      # method
+      # @return [Hash{String => AchClient::AchResponse}] Hash with
+      #   individual_id_number values as keys, AchResponse objects as values
+      def self.most_recent
+        process_files(most_recent_files)
+      end
+
+      ##
+      # Gets the status of ach transactions between the given dates
+      # @param start_date [String] lower bound of date ranged status query
+      # @param end_date [String] upper bound of date ranged status query
+      # @return [Hash{String => AchClient::AchResponse}] Hash with
+      #   individual_id_number values as keys, AchResponse objects as values
+      def self.in_range(start_date:, end_date:)
+        in_range = {}
+        self.parent.with_sftp_connection do |connection|
+          in_range = process_files(
+            files_in_range(
+              connection: connection,
+              start_date: start_date,
+              end_date: end_date
+            )
+          )
+        end
+        in_range
+      end
+
+      private_class_method def self.process_files(files)
+        files.reduce({}) do |acc, entry|
+          ACH::ACHFile.new(entry.last).batches.map do |batch|
+            batch.entries.map do |ach|
+              # return trace ==> response
+              { ach.individual_id_number => process_ach(batch, ach) }
+            end.reduce({}, &:merge)
+          end.reduce({}, &:merge).merge(acc)
+        end
+      end
+
+      private_class_method def self.process_ach(batch, ach)
+        if ach.addenda.length == 0
+          # If there are no addenda, it is a success.
+          AchClient::SettledAchResponse.new(
+            amount: (ach.amount / 100.0).to_d,
+            date: batch.header.effective_entry_date
+          )
+        else
+          # If there is an addenda, it is a return
+          process_ach_return(batch, ach)
+        end
+      end
+
+      private_class_method def self.process_ach_return(batch, ach)
+        # I'm not sure why/if there would be multiple addenda.
+        # So just taking the first one.
+        case ach.addenda.first.reason_code.first
+        # If the first letter is R, it is a return
+        when 'R'
+          AchClient::ReturnedAchResponse.new(
+            amount: (ach.amount / 100.0).to_d,
+            date: batch.header.effective_entry_date,
+            return_code: AchClient::ReturnCodes.find_by(
+              code: ach.addenda.first.reason_code
+            )
+          )
+        # If the first letter is C, it is a correction
+        when 'C'
+          AchClient::CorrectedAchResponse.new(
+            amount: (ach.amount / 100.0).to_d,
+            date: batch.header.effective_entry_date,
+            return_code: AchClient::ReturnCodes.find_by(
+              code: ach.addenda.first.reason_code
+            ),
+            corrections: {
+              # The key for deciphering this field is probably documented
+              # somewhere. We can expand on this once there is a use case for
+              # automatically processing corrections
+              unhandled_correction_data: ach.addenda.first.corrected_data
+            }
+          )
+        end
+      end
+
+      private_class_method def self.inbox_path_to(filename)
+        "#{self.parent.incoming_path}/#{filename}"
+      end
+
+      private_class_method def self.files_in_range(
+        connection:,
+        start_date:,
+        end_date: nil
+      )
+        # Get info on all files - equivalent to `ls`
+        connection.dir.entries(self.parent.incoming_path)
+                      .select do |file|
+          last_modified_time = Time.at(file.attributes.mtime)
+          # Filter to files modified in date range
+          last_modified_time > start_date && (
+            !end_date || last_modified_time < end_date
+          )
+        end.map do |file|
+          body = connection.file.open(inbox_path_to(file.name), 'r').read
+          AchClient::Logging::LogProviderJob.perform_async(
+            body: body,
+            name: "response-#{DateTime.now}-#{file.name.parameterize}"
+          )
+          { file.name => body }
+        end.reduce(&:merge)
+      end
+
+      # Returns the last datetime that the most_recent function was called
+      private_class_method def self.last_most_recent_check_date(connection:)
+        most_recent_string = connection.file.open(
+          inbox_path_to('most_recent'),
+          'r'
+        ).read
+        DateTime.parse(most_recent_string)
+      end
+
+      # Leave file with last grabbed date
+      private_class_method def self.update_most_recent_check_date(connection:)
+        connection.file.open(inbox_path_to('most_recent'), 'w') do |file|
+          file.write(DateTime.now.to_s)
+        end
+      end
+
+      private_class_method def self.most_recent_files
+        files = []
+        self.parent.with_sftp_connection do |connection|
+          files = files_in_range(
+            connection: connection,
+            start_date: last_most_recent_check_date(connection: connection)
+          )
+        update_most_recent_check_date(connection: connection)
+        end
+        files
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module AchClient
+  class Sftp
+    # Generic SFTP provider representation of a single ACH Transaction
+    class AchTransaction < Abstract::AchTransaction
+
+      # Most SFTP providers only support batch transactions
+      def send
+        raise 'NACHA/SFTP providers do not support individual transactions'
+      end
+
+      # Converts this ach transaction to the ACH gem's representation of a
+      # ach transaction for eventual NACHA transformation
+      # @return [ACH::EntryDetail] ACH gem's ach transaction record
+      def to_entry_detail
+        entry = ACH::EntryDetail.new
+        entry.transaction_code = transaction_code
+        entry.routing_number = routing_number
+        entry.account_number = account_number
+        entry.amount = amount_in_cents
+        entry.individual_id_number = external_ach_id # Doesn't need to be a number
+        entry.individual_name = merchant_name
+        entry.originating_dfi_identification =
+          self.class.parent.originating_dfi_identification
+        entry.trace_number = external_ach_id.gsub(/\D/, '').to_i # Does need to be a number
+        entry
+      end
+
+      private
+
+      def amount_in_cents
+        # Take absolute value in case amount is negative
+        Helpers::DollarsToCents.dollars_to_cents(amount.abs)
+      end
+
+      def transaction_code
+        [
+          AccountTypeTransformer.serialize_to_provider_value(
+            account_type
+          ),
+          TransactionTypeTransformer.serialize_to_provider_value(
+            potentially_flipped_transaction_type
+          )
+        ].reduce(&:+)
+      end
+
+      # Some NACHA providers can't handle negative amounts
+      # So we flip the amount and toggle the transaction type between
+      #   Debit and Credit or vice versa
+      def potentially_flipped_transaction_type
+        if amount.negative?
+          if transaction_type == TransactionTypes::Credit
+            TransactionTypes::Debit
+          else
+            TransactionTypes::Credit
+          end
+        else
+          self.transaction_type
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module AchClient
+  # Base concern for providers like SVB and BOA that use NACHA format
+  module NachaProvider
+    extend ActiveSupport::Concern
+
+    included do
+      # @return [String] Immediate Destination ID provided by SVB, refers to SVB
+      class_attribute :immediate_destination
+
+      # @return [String] Immediate Destination Name provided by SVB, refers to SVB
+      class_attribute :immediate_destination_name
+
+      # @return [String] Immediate Origin ID provided by SVB, refers to you
+      class_attribute :immediate_origin
+
+      # @return [String] Immediate Origin Name provided by SVB, refers to you
+      class_attribute :immediate_origin_name
+
+      # @return [String] Company Identification provided by SVB, refers to you
+      class_attribute :company_identification
+
+      # @return [String] Company Entry Description, whatever that means
+      class_attribute :company_entry_description
+
+      # @return [String] originating_dfi_identification refers to your bank?
+      # originating_dfi => "Originating Depository Financial Institution"
+      class_attribute :originating_dfi_identification
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+require 'net/sftp'
+
+module AchClient
+  # Base concern for providers like SVB that use an SFTP system instead of API
+  module SftpProvider
+    extend ActiveSupport::Concern
+
+    included do
+      # @return [String] Hostname/URL of SVB's "Direct File Transmission" server
+      class_attribute :host
+
+      # @return [String] The username they gave you to login to the server
+      class_attribute :username
+
+      # @return [String] The password they gave you to login to the server
+      class_attribute :password
+
+      # @return [String] The private ssh key that matches the public ssh key you
+      # provided to SVB, ie the output of `cat path/to/private/ssh/key`
+      class_attribute :private_ssh_key
+
+      # @return [String | NilClass] Passphrase for your private ssh key
+      # (if applicable)
+      class_attribute :passphrase
+
+      # @return [String] The path on the remote server to the directory where
+      # you will deposit your outgoing NACHA files
+      class_attribute :outgoing_path
+
+      # @return [String] The path on the remote server to the directory where
+      # the SFTP provider will deposit return/confirmation files
+      class_attribute :incoming_path
+
+      # @return [Proc] A function that defines the filenaming strategy for your
+      # provider. The function should take an optional batch number and return
+      # a filename string
+      class_attribute :file_naming_strategy
+
+      # Executes the given block with an obtained SFTP connection configured
+      # using the above settings
+      # @param block [Proc] the code to execute with a provided connection
+      # @return [Object] the result of the block
+      def self.with_sftp_connection(&_block)
+        Net::SFTP.start(*connection_params) do |sftp_connection|
+          yield(sftp_connection)
+        end
+      end
+
+      # Opens an SFTP connection, and writes a new file at the given path with
+      # the given body
+      # @param file_path [String] path to the new file on the remote server
+      # @param file_body [String] text you want to write to the new file
+      # @return [String] the filename written to, if successful
+      def self.write_remote_file(file_path:, file_body:)
+        self.with_sftp_connection do |sftp_connection|
+          sftp_connection.file.open(file_path, 'w') do |file|
+            # Log the file contents
+            AchClient::Logging::LogProviderJob.perform_async(
+              body: file_body,
+              name: "request-#{DateTime.now}-#{file_path.parameterize}"
+            )
+            # Write the file on the remote server
+            file.puts(file_body)
+          end
+        end
+        file_path
+      end
+
+      # Lists the files in the given directory that match the given glob
+      # @param file_path [String] path to directory the search will start from
+      # @param glob [String] the glob to search for, ie "*.rb" => all .rb files
+      # @return [Array<String>] List of discovered filenames that match the glob
+      def self.list_files(file_path:, glob:)
+        result = nil
+        self.with_sftp_connection do |sftp_connection|
+          result = sftp_connection.dir.glob(file_path, glob)
+        end
+        result.map(&:name)
+      end
+
+      # Returns the contents of the files in the given directory that match
+      # the given glob
+      # @param file_path [String] path to directory the search will start from
+      # @param glob [String] the glob to search for, ie "*.rb" => all .rb files
+      # @return [{String => String}] Hash of discovered files, where each
+      # key is a filename and each value is a file's contents
+      def self.retrieve_files(file_path:, glob:)
+        files = nil
+        # retrieve the files from the remote server
+        self.with_sftp_connection do |sftp_connection|
+          files = sftp_connection.dir.glob(file_path, glob).map do |file|
+            {
+              file.name =>
+              sftp_connection.file.open(
+                File.join(file_path, file.name),
+                'r'
+              ).read
+            }
+          end.reduce(&:merge)
+        end
+        # log the retrieved files
+        files.each do |name, body|
+          AchClient::Logging::LogProviderJob.perform_async(
+            body: body,
+            name: "response-#{DateTime.now}-#{name}"
+          )
+        end
+        files
+      end
+
+      private_class_method def self.connection_params
+        [
+          host,
+          username,
+          [
+            (private_ssh_key ? {key_data: [private_ssh_key]} : nil),
+            (passphrase ? {passphrase: passphrase} : nil),
+            password: password
+          ].compact.reduce(&:merge)
+        ]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module AchClient
+  class Sftp
+    ##
+    # Transforms TransactionTypes between AchClient class and the string
+    # that NACHA expects
+    class TransactionTypeTransformer < AchClient::Transformer
+      # '2' means Credit, '7' means Debit
+      # The account type string is the second character in the transaction_code
+      # field.
+      # @return [Hash {String => Class}] the mapping
+      def self.transformer
+        {
+          '2' => AchClient::TransactionTypes::Credit,
+          '7' => AchClient::TransactionTypes::Debit
+        }
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/account_type_transformer.rb

@@ -0,0 +1,17 @@
+module AchClient
+  class AchWorks
+    ##
+    # Transforms AccountTypes between AchClient class and the string
+    # that AchWorks expects
+    class AccountTypeTransformer < AchClient::Transformer
+      # 'C' means Checking, 'S' means Savings
+      # @return [Hash {String => Class}] the mapping
+      def self.transformer
+        {
+          'S' => AchClient::AccountTypes::Savings,
+          'C' => AchClient::AccountTypes::Checking
+        }
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/ach_batch.rb

@@ -0,0 +1,89 @@
+module AchClient
+  class AchWorks
+
+    # AchWorks implementation for AchBatch
+    class AchBatch < Abstract::AchBatch
+
+      ##
+      # Sends the batch to AchWorks using their SendACHTransBatch SOAP action
+      # If the action is successful, will return the filename that AchWorks
+      # gives us. We can use that to track the batch processing later on.
+      # If it fails, an exception will be thrown.
+      # @return [Array<String>] the external_ach_id's for each transaction
+      def send_batch
+        AchClient::AchWorks.wrap_request(
+          method: :send_ach_trans_batch,
+          message: self.to_hash,
+          path: [:send_ach_trans_batch_response, :send_ach_trans_batch_result]
+        )[:file_name]
+        external_ach_ids
+      end
+
+      # Converts this batch to a hash which can be sent to ACHWorks via Savon
+      # @return [Hash] hash to send to AchWorks
+      def to_hash
+        CompanyInfo.build.to_hash.merge(
+          {
+            InpACHFile:{
+              SSS: AchClient::AchWorks.s_s_s,
+              LocID: AchClient::AchWorks.loc_i_d,
+              ACHFileName: nil, # Docs say to leave this blank...
+              TotalNumRecords: total_number_records,
+              TotalDebitRecords: total_debit_records,
+              TotalDebitAmount: total_debit_amount,
+              TotalCreditRecords: total_credit_records,
+              TotalCreditAmount: total_credit_amount,
+              ACHRecords: {
+                ACHTransRecord: @ach_transactions.map(&:to_hash)
+              }
+            }
+          }
+        )
+      end
+
+      private
+
+      def external_ach_ids
+        @ach_transactions.map(&:external_ach_id)
+      end
+
+      # Because AchWorks can't count...
+      def total_number_records
+        @ach_transactions.count
+      end
+
+      # Because AchWorks can't filter...
+      def debit_records
+        @ach_transactions.select(&:debit?)
+      end
+
+      def credit_records
+        @ach_transactions.select(&:credit?)
+      end
+
+      # They still don't know how to count.
+      def total_debit_records
+        debit_records.count
+      end
+
+      def total_credit_records
+        credit_records.count
+      end
+
+      # "Plusing numbers" is real hard as well.
+      def total_debit_amount
+        total_amount(debit_records)
+      end
+
+      def total_credit_amount
+        total_amount(credit_records)
+      end
+
+      def total_amount(ach_transactions)
+        ach_transactions.reduce(0) do |sum, transaction|
+          sum + transaction.amount
+        end
+      end
+    end
+  end
+end

data/lib/ach_client/providers/soap/ach_works/ach_status_checker.rb

@@ -0,0 +1,86 @@
+module AchClient
+  class AchWorks
+    # Poll AchWorks for status of processed or processing Ach transactions.
+    class AchStatusChecker < Abstract::AchStatusChecker
+      ##
+      # Gets the most recent "unread" ach statuses from AchWorks.
+      # NOT IDEMPOTENT - Once this method is called (successfully or
+      # unsuccessfully), AchWorks will never return the same Ach transactions
+      # here again.
+      # Wraps: http://tstsvr.achworks.com/dnet/achws.asmx?op=GetACHReturns
+      # @return [Hash{String => AchClient::AchResponse}] Hash with FrontEndTrace
+      #   values as keys, AchResponse objects as values
+      def self.most_recent
+        request_and_process_response(
+          method: :get_ach_returns,
+          message: most_recent_hash
+        )
+      end
+
+      ##
+      # Gets the status of ach transactions between the given dates
+      # Sometimes AchWorks will modify the end date...
+      # Wraps: http://tstsvr.achworks.com/dnet/achws.asmx?op=GetACHReturnsHist
+      # BEWARE OF LARGE DATE RANGES: AchWorks doesn't appear to cache or even
+      # paginate their responses, so if your range has too many responses,
+      # something will probably break.
+      # @param start_date [String] lower bound of date ranged status query
+      # @param end_date [String] upper bound of date ranged status query
+      # @return [Hash{String => AchClient::AchResponse}] Hash with FrontEndTrace
+      #   values as keys, AchResponse objects as values
+      def self.in_range(start_date:, end_date:)
+        request_and_process_response(
+          method: :get_ach_returns_hist,
+          message: in_range_hash(start_date: start_date, end_date: end_date)
+        )
+      end
+
+      private_class_method def self.request_and_process_response(
+        method:,
+        message:
+      )
+        response = AchClient::AchWorks.wrap_request(
+          method: method,
+          message: message,
+          path: ['_response', '_result'].map do |postfix|
+            (method.to_s + postfix).to_sym
+          end
+        )
+        if response[:total_num_records] == '0'
+          []
+        else
+          response[:ach_return_records][:ach_return_record].select do |record|
+            # Exclude records with no front end trace
+            # They are probably 9BNK response codes, not actual transactions
+            # 9BNK is when AchWorks gives us an aggregate record, containing
+            #   the total debit/credit to your actual bank account.
+            # We don't care about those here.
+            record[:front_end_trace].present?
+          end.map do |record|
+            {
+              record[:front_end_trace][1..-1] =>
+              AchClient::AchWorks::ResponseRecordProcessor
+                .process_response_record(record)
+            }
+          end.reduce(&:merge)
+        end
+      end
+
+      private_class_method def self.company_info
+        AchClient::AchWorks::CompanyInfo.build
+      end
+
+      private_class_method def self.most_recent_hash
+        company_info.to_hash
+      end
+
+      private_class_method def self.in_range_hash(start_date:, end_date:)
+        company_info.to_hash.merge({
+          ReturnDateFrom:
+            AchClient::AchWorks::DateFormatter.format(start_date),
+          ReturnDateTo: AchClient::AchWorks::DateFormatter.format(end_date)
+        })
+      end
+    end
+  end
+end