dcas-ruby 0.1.0

data/lib/dcas/response.rb

@@ -0,0 +1,123 @@
+# __ Documentation __
+# CreditCard returns are pretty straightforward. They're handled by just this class here, DcasResponse.
+# ACH returns come in two stages, and they have to be handled differently, so they're defined in
+# DcasAchResponse and DcasAchReturn.
+# 
+# A DcasResponse object has a status. That status can be one of ['I', 'A', 'G', 'D']
+# These map to a GotoTransaction's statuses, which are as follows:
+#   'R' => Received
+#   'A' => Accepted
+#   'G' => Paid
+#   'D' => Declined
+#   'E' => Processing Error
+# Notice that the three with the stars map directly to three of a DcasResponse object's statuses.
+# The fourth status, 'I', is used to denote an Informational record. These records are never intended
+# to state whether a payment was accepted, declined, or paid, but rather to provide important information
+# back into the system about an account, such as information that needs to be updated soon.
+
+module DCAS
+  class Response
+    class << self
+      def responses_in(filename_or_content)
+        responses = []
+
+        if filename_or_content !~ /\n/ && File.exists?(filename_or_content)
+          filename_or_content = File.open(filename_or_content, 'rb').map {|l| l.gsub(/[\n\r]+/, "\n")}.join
+        end
+
+        CSV::Reader.parse(filecontents) do |ccrow|
+          # Could be simply '9999' -- error!
+          begin
+            next if ccrow == ['9999']
+            # Otherwise, it is in this format:
+            # CC,AccountNumber,ReturnCode,ReasonDescription,CustTraceCode
+            responses << new(ccrow)
+          rescue # Rescue errors caused by the data in the csv.
+          end
+        end
+
+        responses
+      end
+
+      # Runs the given block for each response in the given response file.
+      def each_response_in(filename_or_content)
+        raise ArgumentError, "must include a block!" unless block_given?
+        responses_in(filename_or_content).each do |response|
+          yield response
+        end
+      end
+    end
+
+    attr_accessor :account_number, :check_number, :client_id, :status, :information, :description, :ach_submitted
+    def attributes
+      at = {}
+      instance_variables.each do |iv|
+        iv.gsub!('@', '')
+        at[iv] = instance_variable_get("@#{iv}")
+      end
+      at
+    end
+    def attributes=(new_attributes)
+      return if new_attributes.nil?
+      with(new_attributes.dup) do |a|
+        a.stringify_keys!
+        a.each {|k,v| send(k + "=", a.delete(k)) if respond_to?("#{k}=")}
+      end
+    end
+
+    # Tells if the payment was invalid. By default it's just false, but child classes can redefine this.
+    def invalid?
+      false
+    end
+
+    CC_RET_CODES = {
+      '0' => 'D',
+      '1' => 'G',
+      '2' => 'I', # I think, we should never get this status. (Haven't yet...)
+      '99' => 'E' # These are always server errors
+    }
+
+    def initialize(attrs={})
+      new_attrs = {}
+      nattrs = attrs.dup
+      if nattrs.is_a?(Hash) # Is xml-hash
+        nattrs.stringify_keys!
+        # status, order_number, transacted_at, transaction_id, description
+        new_attrs = nattrs
+      elsif nattrs.respond_to?('[]') # Is csv row
+        # GotoBilling: MerchantID,FirstName,LastName,CustomerID,Amount,SentDate,SettleDate,TransactionID,TransactionType,Status,Description
+        # DCAS:        CC,AccountNumber,ReturnCode,ReasonDescription,ConfirmationNumber
+        # ret could be 0 (denied), 1 (approved), 2 (call for authorization), or 99 (error)
+        new_attrs = {
+          :status => (nattrs[2].to_s == 'I' ? 'R' : CC_RET_CODES[nattrs[2].to_s]),
+          :description => nattrs[3],
+          :account_number => nattrs[1],
+          :client_id    => nattrs[4][4..-1]
+        }
+        # This is the case where Malibu must call DCAS for authorization. We haven't come across that need yet, but a note should be made.
+        # I'll make it an informational and 'Received' record -- but we have no answer other than this. The transaction won't go through without attention.
+        new_attrs[:information] = "MUST CALL FOR Credit Card payment authorization! If you have any questions ask your Manager or the tech guy." if nattrs[2].to_s == 'I'
+      end
+      self.attributes = new_attrs
+    end
+  
+    # def transaction
+    #   @transaction ||= GotoTransaction.find_by_batch_id_and_client_id(self.batch_id, client_id)
+    # end
+
+    # def record_to_transaction!
+    #   return unless transaction.status != status && transaction.description != description
+    #   if transaction.transaction_id.to_i != 0 && transaction.status == 'G' && status == 'D'
+    #     # Was accepted, now declined.
+    #     # Delete the transaction if it was previously created.
+    #     puts "Previously accepted, now declined: delete transaction on master, remove association on goto_transaction"
+    #     # Helios::Transact.update_on_master(self.transaction.transaction_id, :CType => 1, :client_no => self.transaction_id)
+    #     transaction.transaction_id = 0
+    #   end
+    #   transaction.description = description
+    #   transaction.status = status
+    #   transaction.ach_submitted = ach_submitted if ach_submitted
+    #   transaction.save
+    # end
+  end
+end

data/lib/dcas.rb

@@ -0,0 +1,140 @@
+require 'ftools'
+
+module DCAS
+  TESTING = false
+  BUCKET_HOST = 'ftp.ezpaycenters.net'
+  OUTGOING_BUCKET = 'outgoing'
+  INCOMING_BUCKET = 'incoming'
+  STAGING_BUCKET  = 'staging'
+
+  class << self
+    # Parses the responses from a response file and returns an array of DCAS::Response objects.
+    def parse_response_file(filename_or_content)
+    end
+  end
+
+  class Client
+    # Instantiate a new Client object which can do authenticated actions in a DCAS FTPS bucket.
+    def initialize(options={})
+      raise ArgumentError, "must include :username, :password, :company_alias, :company_username, :company_password, and :cache_location" if [:username, :password, :company_alias, :company_username, :company_password, :cache_location].any? {|k| !options.has_key?(k)}
+      @username = options[:username]
+      @password = options[:password]
+      @company_alias = options[:company_alias]
+      @company_username = options[:company_username]
+      @company_password = options[:company_password]
+      @cache_location = options[:cache_location]
+    end
+
+    attr_reader :username, :password, :company_alias, :company_username, :company_password, :cache_location
+
+    # :nodoc:
+    def batches
+      @batches ||= []
+    end
+
+    # Begin a new batch associated with this client.
+    def new_batch(batch_id)
+      batches << DCAS::PaymentBatch.new(self, batch_id)
+      batches.last
+    end
+
+    # Uploads a single payments file to the DCAS outgoing payments bucket.
+    def submit_payments_file!(filename)
+      shortname = filename.gsub(/.*[\\\/][^\\\/]+$/,'')
+      with_ftp do |ftp|
+        # 1) Create the STAGING folder if it's not already there.
+        ftp.mkdir(DCAS::STAGING_BUCKET) unless ftp.nlst.include?(DCAS::STAGING_BUCKET)
+        ftp.chdir(DCAS::STAGING_BUCKET)
+        # 2) Delete the same filename from the STAGING folder if one exists.
+        ftp.delete(shortname) if ftp.nlst.include?(shortname)
+        # 3) Upload the file into the STAGING folder.
+        ftp.put(filename, shortname)
+        # 4) If we're still connected, check the file size of the file, then move it out of STAGING and mark file as completed.
+        if ftp.nlst.include?(shortname) && ftp.size(shortname) == File.size(filename)
+          ftp.rename(shortname, "../#{DCAS::OUTGOING_BUCKET}/#{shortname}") unless DCAS::TESTING
+        else
+          raise RuntimeError, "FAILED uploading `#{filename}' - incomplete or unsuccessful upload. Please try again."
+        end
+      end
+      true
+    end
+
+    # Writes all batches to file and submits them to the DCAS outgoing payments bucket.
+    def submit_batches!
+      File.makedirs(cache_location)
+      batches_submitted = 0
+      with_ftp do
+        # 1) Gather all payments for this client.
+        batches.each do |batch| # 2) For each file type (ach, cc) yet to be uploaded:
+          filename = cache_location + "/#{company_user}_#{batch.type}_#{Time.now.strftime("%Y%m%d")}.csv"
+          # 1) Create the file locally.
+          File.open(filename) {|f| f << batch.to_csv }
+          # 2) Upload it to the DCAS outgoing payments bucket.
+          batches_submitted += 1 if submit_payments_file!(filename)
+        end
+      end
+    end
+
+    # Checks for response files in the DCAS incoming responses bucket.
+    def available_response_files
+      with_ftp do |ftp|
+        # 3) List the *.csv files in the INCOMING bucket.
+        result = if ftp.nlst.include?(DCAS::INCOMING_BUCKET)
+          ftp.chdir(DCAS::INCOMING_BUCKET)
+          ftp.nlst.select {|f| f =~ /\.csv$/}
+        else
+          []
+        end
+      end
+    end
+
+    # Downloads all response files in the DCAS incoming responses bucket.
+    def download_response_files!
+      files_downloaded = []
+      File.makedirs(cache_location + '/returns')
+      with_ftp do |ftp|
+        files = ftp.list('*.csv')
+        files.each do |filels|
+          size, file = filels.split(/ +/)[4], filels.split(/ +/)[8..-1].join(' ')
+          ftp.get(file, cache_location + '/returns/' + user_suffix + '_' + file)
+          files_downloaded << file
+        end
+      end
+      files_downloaded
+    end
+
+
+    private
+      def user_suffix
+        company_username.match(/(?:malibu|maltan|malent)?(.*)(?:VT)?/)[1]
+      end
+
+      def ftp_connection
+        @ftp ||= Net::FTPS::Implicit.new(DCAS::BUCKET_HOST, username, password, nil, OpenSSL::SSL::VERIFY_NONE)
+      end
+      # This allows all functionality to share the same connection, then log out after all work is finished.
+      def with_ftp(&block)
+        @inside_with_ftp = @inside_with_ftp.to_i + 1
+        if block.arity == 1
+          yield ftp_connection
+        else
+          yield
+        end
+        @inside_with_ftp -= 1
+        ftp_done
+      end
+      def ftp_done
+        close_ftp if @inside_with_ftp.to_i == 0
+      end
+      def close_ftp
+        if @ftp
+          @ftp.quit
+          @ftp.close
+          @ftp = nil
+        end
+      end
+  end
+end
+
+require 'dcas/payment'
+require 'dcas/response'

data/lib/net/ftps_implicit.rb

@@ -0,0 +1,225 @@
+
+# Submitted to ruby-lang.org: http://redmine.ruby-lang.org/issues/show/1371
+# Needs Documentation!
+# quote: "I prefer an approach to modify Net::FTP itself to support implicit
+#         (and explicit) FTPS. Please see Net::IMAP in Ruby 1.9."
+# - so I probably should go and edit the net/ftp file to include some of the
+#   features of FTPS, when TLS is desired over the FTP connection.
+
+
+require 'socket'
+require 'openssl'
+require 'net/ftp'
+
+class Net::FTPS < Net::FTP
+end
+
+class Net::FTPS::Implicit < Net::FTP
+  FTP_PORT = 990
+
+  def initialize(host=nil, user=nil, passwd=nil, acct=nil, verify_mode=OpenSSL::SSL::VERIFY_PEER)
+    super(host, user, passwd, acct)
+    @passive = true
+    @binary = false
+    @debug_mode = false
+    @data_protection = 'P'
+    @data_protected = false
+    @verify_mode = verify_mode
+  end
+  attr_accessor :data_protection
+
+  def open_socket(host, port, data_socket=false)
+    tcpsock = if defined? SOCKSsocket and ENV["SOCKS_SERVER"]
+      @passive = true
+      SOCKSsocket.open(host, port)
+    else
+      TCPSocket.new(host, port)
+    end
+    if !data_socket || @data_protection == 'P'
+      ssl_context = OpenSSL::SSL::SSLContext.new('SSLv23')
+      ssl_context.verify_mode = @verify_mode
+      ssl_context.key = nil
+      ssl_context.cert = nil
+      ssl_context.timeout = 10
+
+      sock = OpenSSL::SSL::SSLSocket.new(tcpsock, ssl_context)
+      sock.connect
+    else
+      sock = tcpsock
+    end
+    return sock
+  end
+  private :open_socket
+
+  def connect(host, port=FTP_PORT)
+    @sock = open_socket(host, port)
+    mon_initialize
+    getresp
+    at_exit {
+      if @sock && !@sock.closed?
+        voidcmd("ABOR") rescue EOFError
+        voidcmd("QUIT") rescue EOFError
+        close
+      end
+    }
+  end
+
+  def abort
+    voidcmd("ABOR") rescue EOFError
+  end
+
+  def quit
+    voidcmd("QUIT") rescue EOFError
+  end
+
+  def close
+    @sock.close # SSL
+    @sock.io.close # TCP
+  end
+
+  def retrbinary(cmd, blocksize, rest_offset = nil) # :yield: data
+    synchronize do
+      voidcmd("TYPE I")
+      conn = transfercmd(cmd, rest_offset)
+      data = get_data(conn,blocksize)
+      yield(data)
+      voidresp
+    end
+  end
+
+  def get_data(sock,blocksize=1024)
+    timeout = 10
+    starttime = Time.now
+    buffer = ''
+    timeouts = 0
+    catch :done do
+      loop do
+        event = select([sock],nil,nil,0.5)
+        if event.nil? # nil would be a timeout, we'd do nothing and start loop over. Of course here we really have no timeout...
+          timeouts += 0.5
+          break if timeouts > timeout
+        else
+          event[0].each do |sock| # Iterate through all sockets that have pending activity
+            if sock.eof? # Socket's been closed by the client
+              throw :done
+            else
+              buffer << sock.readpartial(blocksize)
+              if block_given? # we're in line-by-line mode
+                lines = buffer.split(/\r?\n/)
+                buffer = buffer =~ /\n$/ ? '' : lines.pop
+                lines.each do |line|
+                  yield(line)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+    sock.close
+    buffer
+  end
+
+  def retrlines(cmd) # :yield: line
+    synchronize do
+      voidcmd("TYPE A")
+      voidcmd("STRU F")
+      voidcmd("MODE S")
+      conn = transfercmd(cmd)
+      get_data(conn) do |line|
+        yield(line)
+      end
+      getresp
+    end
+  end
+
+  #
+  # Puts the connection into binary (image) mode, issues the given server-side
+  # command (such as "STOR myfile"), and sends the contents of the file named
+  # +file+ to the server. If the optional block is given, it also passes it
+  # the data, in chunks of +blocksize+ characters.
+  #
+  def storbinary(cmd, file, blocksize, rest_offset = nil, &block) # :yield: data
+    if rest_offset
+      file.seek(rest_offset, IO::SEEK_SET)
+    end
+    synchronize do
+      voidcmd("TYPE I")
+      conn = transfercmd(cmd, rest_offset)
+      loop do
+        buf = file.read(blocksize)
+        break if buf == nil
+        conn.write(buf)
+        yield(buf) if block
+      end
+      conn.close # closes the SSL
+      conn.io.close # closes the TCP below it
+      voidresp
+    end
+  end
+
+  #
+  # Puts the connection into ASCII (text) mode, issues the given server-side
+  # command (such as "STOR myfile"), and sends the contents of the file
+  # named +file+ to the server, one line at a time. If the optional block is
+  # given, it also passes it the lines.
+  #
+  def storlines(cmd, file, &block) # :yield: line
+    synchronize do
+      voidcmd("TYPE A")
+      conn = transfercmd(cmd)
+      loop do
+        buf = file.gets
+        break if buf == nil
+        if buf[-2, 2] != CRLF
+          buf = buf.chomp + CRLF
+        end
+        conn.write(buf)
+        yield(buf) if block
+      end
+      conn.close # closes the SSL
+      conn.io.close # closes the TCP below it
+      voidresp
+    end
+  end
+
+  def transfercmd(cmd, rest_offset=nil)
+    unless @data_protected
+      voidcmd('PBSZ 0')
+      sendcmd("PROT #{@data_protection}")
+      @data_protected = true
+    end
+
+    if @passive
+      host, port = makepasv
+      if @resume and rest_offset
+        resp = sendcmd("REST " + rest_offset.to_s) 
+        if resp[0] != ?3
+          raise FTPReplyError, resp
+        end
+      end
+      putline(cmd)
+      conn = open_socket(host, port, true)
+      resp = getresp # Should be a 150 response
+      if resp[0] != ?1
+        raise FTPReplyError, resp
+      end
+    else
+      sock = makeport
+      if @resume and rest_offset
+        resp = sendcmd("REST " + rest_offset.to_s) 
+        if resp[0] != ?3
+          raise FTPReplyError, resp
+        end
+      end
+      resp = sendcmd(cmd)
+      if resp[0] != ?1
+        raise FTPReplyError, resp
+      end
+      conn = sock.accept
+      sock.close
+    end
+    return conn
+  end
+  private :transfercmd
+end

data/spec/dcas/response_spec.rb

@@ -0,0 +1,11 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe DCAS::Response do
+  before :all do
+  end
+
+  it "should parse a CreditCard response correctly"
+
+  it "should parse an ACH response correctly"
+
+end

data/spec/dcas_spec.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Dcas - Comprehensive failure frequency test" do
+  before :all do
+    DCAS::TESTING = true
+    @fake_client = DCAS::Client.new(
+      :username => 'none',
+      :password => 'none',
+      :company_alias => 'tester',
+      :company_username => 'tester1',
+      :company_password => 'fakeness1',
+      :cache_location => 'none'
+    )
+  end
+
+  it "should generate Ach payment files correctly" do
+    ach_batch = @fake_client.new_batch(1)
+    Fixtures[:TestPayments][:Ach].collect {|p| ach_batch << DCAS::AchPayment.new(*p) }
+    ach_payments_file = ach_batch.to_csv
+    ach_payments_file.should eql(File.read('spec/fixtures/ach_payments.csv'))
+  end
+
+  it "should generate CreditCard payment files correctly" do
+    cc_batch = @fake_client.new_batch(1)
+    Fixtures[:TestPayments][:CreditCard].collect {|p| cc_batch << DCAS::CreditCardPayment.new(*p) }
+    cc_payments_file = cc_batch.to_csv
+    cc_payments_file.should eql(File.read('spec/fixtures/credit_card_payments.csv'))
+  end
+
+  it "should be able to complete an entire mock procedure without failing" do
+    lambda {
+      # Depends: Fixture load of a list of DCAS logins to test
+      # Depends: Fixed test files
+      Fixtures[:Clients].each do |client|
+        cc_batch = client.new_batch(1)
+        Fixtures[:TestPayments][:CreditCard].each {|p| cc_batch << DCAS::CreditCardPayment.new(*p) }
+
+        ach_batch = client.new_batch(1)
+        Fixtures[:TestPayments][:Ach].each {|p| ach_batch << DCAS::AchPayment.new(*p) }
+
+        client.submit_batches!.should eql(Fixtures[:PaymentFiles].length)
+      end
+      Fixtures[:Clients].each do |client|
+        client.download_response_files!
+      end
+    }.should_not raise_error
+  end
+
+  # I can't fake it failing without too much extra work, so I'm just testing successes for now.
+end

data/spec/fixtures/ach_payments.csv

@@ -0,0 +1,11 @@
+HD,tester,tester1,fakeness1,Check
+CA,124083517,182045828,2010010,18.88,,Dan Hall,,,,,,,,,100111428,,,Debit,,Checking
+CA,524881452,584218548,2010010,18.88,,Karie Moore,,,,,,,,,100111200,,,Debit,,Checking
+CA,107502429,94217885428,2010010,18.88,,Therese Boon,,,,,,,,,100111829,,,Debit,,Checking
+CA,342882012,24254,2010010,18.88,,Gretchen Gutierrez,,,,,,,,,100111282,,,Debit,,Savings
+CA,547107458,280458548254,2010010,18.88,,Audrice Pitto,,,,,,,,,100111795,,,Debit,,Checking
+CA,125480806,641081508245,2010010,18.88,,Rachel Ruppert,,,,,,,,,100111537,,,Debit,,Checking
+CA,982458912,52488542858,2010010,18.88,,Judith Witlock,,,,,,,,,100111892,,,Debit,,Checking
+CA,108458068,4728458248,2010010,18.88,,Kris Martell,,,,,,,,,100111172,,,Debit,,Savings
+CA,645388043,38184599459,2010010,18.88,,Michell Penderson,,,,,,,,,100111284,,,Debit,,Checking
+CA,543882548,543886028,2010010,18.88,,Polly Clark,,,,,,,,,100111756,,,Debit,,Checking

data/spec/fixtures/ach_payments.yml

@@ -0,0 +1,81 @@
+---
+-
+  - '00111428'
+  - 'Dan Hall'
+  - '18.88'
+  - 'Checking'
+  - '124083517'
+  - '182045828'
+  - '2010010'
+-
+  - '00111200'
+  - 'Karie Moore'
+  - '18.88'
+  - 'Checking'
+  - '524881452'
+  - '584218548'
+  - '2010010'
+-
+  - '00111829'
+  - 'Therese Boon'
+  - '18.88'
+  - 'Checking'
+  - '107502429'
+  - '94217885428'
+  - '2010010'
+-
+  - '00111282'
+  - 'Gretchen Gutierrez'
+  - '18.88'
+  - 'Savings'
+  - '342882012'
+  - '24254'
+  - '2010010'
+-
+  - '00111795'
+  - 'Audrice Pitto'
+  - '18.88'
+  - 'Checking'
+  - '547107458'
+  - '280458548254'
+  - '2010010'
+-
+  - '00111537'
+  - 'Rachel Ruppert'
+  - '18.88'
+  - 'Checking'
+  - '125480806'
+  - '641081508245'
+  - '2010010'
+-
+  - '00111892'
+  - 'Judith Witlock'
+  - '18.88'
+  - 'Checking'
+  - '982458912'
+  - '52488542858'
+  - '2010010'
+-
+  - '00111172'
+  - 'Kris Martell'
+  - '18.88'
+  - 'Savings'
+  - '108458068'
+  - '4728458248'
+  - '2010010'
+-
+  - '00111284'
+  - 'Michell Penderson'
+  - '18.88'
+  - 'Checking'
+  - '645388043'
+  - '38184599459'
+  - '2010010'
+-
+  - '00111756'
+  - 'Polly Clark'
+  - '18.88'
+  - 'Checking'
+  - '543882548'
+  - '543886028'
+  - '2010010'

data/spec/fixtures/clients.yml.sample

@@ -0,0 +1,15 @@
+---
+-
+  :username: testclient1
+  :password: test1
+  :company_alias: tester1
+  :company_username: testuser1
+  :company_password: fakeness1
+  :cache_location: ./EFT
+-
+  :username: testclient2
+  :password: test2
+  :company_alias: tester2
+  :company_username: testuser2
+  :company_password: fakeness2
+  :cache_location: ./EFT

data/spec/fixtures/credit_card_payments.csv

@@ -0,0 +1,11 @@
+HD,tester,tester1,fakeness1,Check
+CC,VISA,4508288028044788,12/2010,18.88,N,,,Kipp Owen,,,,,,,,100111532,Debit,,2,3,1,
+CC,VISA,4979170284809229,12/2011,18.88,N,,,Brooke Racquet,,,,,,,,100111382,Debit,,2,3,1,
+CC,MCRD,5280827180294022,12/2012,18.88,N,,,Pat Sylvester,,,,,,,,100111018,Debit,,2,3,1,
+CC,MCRD,5173179138280429,12/2011,18.88,N,,,Vicki Tolliki,,,,,,,,100111992,Debit,,2,3,1,
+CC,VISA,4247972792081828,12/2010,18.88,N,,,Cheryl Barger,,,,,,,,100111247,Debit,,2,3,1,
+CC,MCRD,5428208180420824,12/2011,18.88,N,,,Melissa Fletcher,,,,,,,,100111028,Debit,,2,3,1,
+CC,MCRD,5425682492949922,12/2012,18.88,N,,,Mack Payne,,,,,,,,100111384,Debit,,2,3,1,
+CC,MCRD,5208372629781292,12/2011,18.88,N,,,Melissa Latcher,,,,,,,,100111742,Debit,,2,3,1,
+CC,MCRD,5181381081538389,12/2012,18.88,N,,,Caroline Sieben,,,,,,,,100111402,Debit,,2,3,1,
+CC,MCRD,5274727290818284,12/2011,18.88,N,,,Charlotte Sue Hiran,,,,,,,,100111208,Debit,,2,3,1,