client_for_poslynx 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YjVkZWJhOTMxOTkyZjRjNmJmYmNhZDE2MTc2ZDNiOGExMjVkYzBjNw==
+  data.tar.gz: !binary |-
+    ZTIzMzQ2NmJkN2ZlMWUwZTVjNDM2YTZkNjlkNWRkOGVlODUyOWRhMg==
+SHA512:
+  metadata.gz: !binary |-
+    Yjk5YTJhNjcyZjQ4YzJjYjMyMTE3YzMwOTgyYzcwNGM2NTdlMWExYzhmMTc3
+    Yzk1NTNkZWQzZDIwYWE0ZDMwMTFlOGNjNGEyMDExZTQxMTU0MTRiYjViNDcx
+    N2ZmMDFlZTMzZGEzZGY5Y2UwNjA4OWQ3ODg0NDQ4NzY0YThiYjg=
+  data.tar.gz: !binary |-
+    MTZiZjhiMjRlOGEyNjhlNTg0ZmNlMmFjYWNmMjA1OGQ2ZTVkNWVjNDY3ZThm
+    ZTVjNzE4M2YzMjUyMzgyMGE5MmFkZDYyYmFhNmJkNzFjZGRlY2U2MDk2MTA1
+    NGQwOTlkMzg1MTYwNmNkZWM2NWVlMGVlM2U2NDA3NzRkYjhkYzQ=

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Steve Jorgensen
+
+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,75 @@
+# ClientForPoslynx
+
+A client library for Ruby applications to communicate with a
+Precidia Technologies POSLynx (TM) payment appliance.
+
+This library was not developed by or on behalf of Precidia
+Technologies.
+
+Features:
+
+* Data models for requests and responses.
+* Writing requests to output streams.
+* Reading responses from input streams.
+* A fake POSLynx appliance + PIN Pad script.
+* A POSLynx client console script.
+
+The best introduction to this gem is probably to play around with
+with the POSLynx client console.  Assuming you have a POSLynx
+unit with IP address 192.168.1.123, listening on port 54321, with
+a registered client MAC of 000000000000, an example poslynx
+client session might look like...
+
+    bundle exec poslynx_client_console 192.168.1.123:54321
+    1.9.3-p545 :001 > poslynx_client.client_mac_for_examples = '0' * 12
+     => "000000000000"
+    1.9.3-p545 :002 > resp = poslynx_client.send_request( poslynx_client.example_pin_pad_display_message_request )
+     => #<ClientForPoslynx::Data::Responses::PinPadDisplayMessage:0x007fbf529a17f8 @result="SUCCESS", @result_text="Success", @error_code="0000", @button_response="2nd button", @source_data="<PLResponse><Command>PPDISPLAY</Command><Result>SUCCESS</Result><ResultText>Success</ResultText><ErrorCode>0000</ErrorCode><Response>2nd button</Response></PLResponse>\n">
+
+This gem also provides a fake POS/terminal application that you
+can run in a separate console window when you are working without
+the necessary access to an actual POSLynx unit and PIN pad.  To
+start the fake POS/terminal listening on port 3010...
+
+    bundle exec fake_pos_terminal 3010
+
+If you then want to start the client console to interact with the
+fake POS/terminal instance on the same machine...
+
+    bundle exec poslynx_client_console :3010
+
+## Usage
+
+The code in the
+lib/client_for_poslynx/has_client_colsole_support.rb file
+provides a good example of how to use the facilities that this
+gem provides.
+
+## Known Limitations
+
+* Only a subset of the possible messages and elements is supported.
+  __More will be added. Contributions are welcome and encouraged. :)__
+* Performs serialization of requests and parsing of responses, but
+  does not ecapsulate actually making TCP connections and requests.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'client_for_poslynx'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install client_for_poslynx
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/client_for_poslynx/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/bin/fake_pos_terminal

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+option_args = []
+value_args = []
+
+$*.each do |arg|
+  list = arg =~ /^--/ ? option_args : value_args
+  list << arg
+end
+
+# Drop command line arguments so 1st argument won't be treated as
+# file name for input.
+$*.replace []
+
+# The only option we car about is --help, so we either show usage
+# for --help or because an unrecognized option was given.
+show_usage = option_args.length > 0
+
+# Should have exactly 1 value argument for the port number.
+show_usage ||= value_args.length != 1
+
+# Port number should consist of 1 or more digits
+show_usage ||= value_args.first !~ /\A\d+\z/
+
+if show_usage
+  puts
+  puts "Usage: client_for_poslynx <port-number>"
+  puts
+  puts "Runs a fake POS terminal that behaves like a POSLynx unit with"
+  puts "an attached PIN pad. It accepts connections from a client on"
+  puts "the specified TCP port number, and presents a text terminal"
+  puts "user interface that acts similarly to a PIN pad."
+  puts
+  puts "This allows you to manually test or demonstrate your client"
+  puts "software without having access to actual POSLynx hardware."
+  puts
+else
+  port_number = (value_args.first || 0).to_i
+  require 'client_for_poslynx/fake_pos_terminal'
+  ClientForPoslynx::FakePosTerminal.start port_number
+end

data/bin/poslynx_client_console

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+
+option_args = []
+value_args = []
+
+$*.each do |arg|
+  list = arg =~ /^--/ ? option_args : value_args
+  list << arg
+end
+
+# Drop command line arguments so 1st argument won't be treated as
+# file name for input.
+$*.replace []
+
+# The only option we car about is --help, so we either show usage
+# for --help or because an unrecognized option was given.
+show_usage = option_args.length > 0
+
+# Should have exactly 1 value argument for the address + port number.
+show_usage ||= value_args.length != 1
+
+# Port number should consist of an optional IP address, followed by
+# colon, followed by a port number
+show_usage ||= value_args.first !~ /\A([^\s]*)?:(\d+)\z/
+host = $1
+port = $2
+
+bin_path = File.dirname(__FILE__)
+gem_path = File.dirname( bin_path )
+support_path = File.join( gem_path, 'lib', 'client_for_poslynx', 'has_client_console_support.rb' )
+
+if show_usage
+
+  puts <<-EOS
+
+Usage: poslynx_client_console [<host>]:<port-number> Host is the
+domain name or IP address of the POSLynx or fake POS terminal
+host.  If this is not supplied, then 127.0.0.1 is assumed.
+
+Opens an interactive Ruby shell with a globally acccessible
+poslynx_client method that returns an object with conveniences
+for making requests to a POSLynx or to your fake
+POSLynx+terminal host.
+
+For example, you might execute the following commands from
+within the console...
+
+  poslynx_client.client_mac_for_examples = '123456789012'
+  resp = poslynx_client.send_request( poslynx_client.example_credit_card_sale_request )
+
+To see what else the poslynx_client object provides, see the
+source code
+in #{support_path}
+
+  EOS
+
+else
+
+  require 'client_for_poslynx/has_client_console_support'
+  require 'irb'
+
+  host = '127.0.0.1' if host.nil? || host.length == 0
+  port = port.to_i
+
+  class Object
+    include ClientForPoslynx::HasClientConsoleSupport
+  end
+
+  config = poslynx_client.config
+  config.host = host
+  config.port = port
+
+  IRB.start
+
+end

data/client_for_poslynx.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'client_for_poslynx/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "client_for_poslynx"
+  spec.version       = ClientForPoslynx::VERSION
+  spec.authors       = ["Steve Jorgensen"]
+  spec.email         = ["stevej@stevej.name"]
+  spec.summary       = "A TCP client for Precidia's POSLynx™ devices"
+  spec.description   = spec.summary
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'nokogiri', "~> 1.6.2"
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/client_for_poslynx.rb

@@ -0,0 +1,13 @@
+# coding: utf-8
+
+require "client_for_poslynx/version"
+require "client_for_poslynx/data"
+require "client_for_poslynx/message_handling"
+
+module ClientForPoslynx
+
+  class Error < StandardError ; end
+  class InvalidXmlError < Error ; end
+  class InvalidXmlContentError < Error ; end
+
+end

data/lib/client_for_poslynx/data.rb

@@ -0,0 +1,14 @@
+# coding: utf-8
+
+require_relative "data/properties_xml_parser"
+require_relative "data/requests"
+require_relative "data/responses"
+require_relative "data/xml_document"
+
+module ClientForPoslynx
+
+  module Data
+
+  end
+
+end

data/lib/client_for_poslynx/data/abstract_data.rb

@@ -0,0 +1,202 @@
+# coding: utf-8
+
+require 'nokogiri'
+
+module ClientForPoslynx
+  module Data
+
+    class AbstractData
+
+      class << self
+
+        alias blank_new new
+
+        def new
+          blank_new
+        end
+
+        def xml_parse(source_xml)
+          doc = XmlDocument.new( source_xml )
+          concrete_data_classes = descendants.
+            reject{ |d| d.name =~ /\bAbstract[A-Z]\w*$/ }.
+            sort_by{ |d| -d.ancestors.length }
+          data_class = concrete_data_classes.detect{ |dc|
+            dc.root_element_name == doc.root_name &&
+            dc.fits_properties?( doc.property_element_contents )
+          }
+          data_class.xml_deserialize(source_xml)
+        end
+
+        def xml_deserialize(xml)
+          doc = XmlDocument.new(xml)
+          raise InvalidXmlContentError, "#{root_element_name} root element not found" unless doc.root_name == root_element_name
+          instance = load_from_properties( doc.property_element_contents )
+          instance.source_data = doc.source_xml
+          instance
+        end
+
+        def load_from_properties(property_contents)
+          verify_defining_properties property_contents
+          variable_property_contents = select_variable_property_contents(property_contents)
+          instance = blank_new
+          populate_instance_from_properties instance, variable_property_contents
+          instance
+        end
+
+        def fits_properties?(property_contents)
+          unmatched = unmatched_defining_properties( property_contents )
+          unmatched.empty?
+        end
+
+        def defining_element_mappings
+          @defining_element_mappings ||=
+            begin
+              self == AbstractData ?
+                [] :
+                superclass.defining_element_mappings + []
+            end
+        end
+
+        def attr_element_mappings
+          @attr_element_mappings ||=
+            begin
+              self == AbstractData ?
+                [] :
+                superclass.attr_element_mappings + []
+            end
+        end
+
+        private
+
+        def inherited(descendant)
+          descendants << descendant
+        end
+
+        def descendants
+          @@descendants ||= []
+        end
+
+        def defining_element_value(options)
+          attribute = options.fetch( :attribute )
+          element   = options.fetch( :element   )
+          value     = options.fetch( :value     )
+          define_singleton_method(attribute) { value }
+          defining_element_mappings << { attribute: attribute, element: element }
+        end
+
+        def attr_element_mapping(options)
+          type = options[:type]
+          unless type.nil?
+            raise ArgumentError, "The :type option must be a symbol, but a #{type.class} was given." unless Symbol === type
+            raise ArgumentError, "#{type.inspect} is not a valid :type option. Must be :array when given." unless type == :array
+          end
+          attribute = options.fetch( :attribute )
+          element   = options.fetch( :element   )
+          attr_accessor attribute
+          attr_element_mappings << options
+        end
+
+        def verify_defining_properties(property_contents)
+          unmatched = unmatched_defining_properties( property_contents )
+          return if unmatched.empty?
+          message = unmatched.map{ |mapping|
+            attribute, el_name = mapping.values_at(:attribute, :element)
+            defining_value = public_send(attribute)
+            "#{el_name} child element with \"#{defining_value}\" value not found."
+          }.join( ' ' )
+          raise InvalidXmlContentError, message
+        end
+
+        def unmatched_defining_properties(property_contents)
+          unmatched = []
+          defining_element_mappings.each do |mapping|
+            attribute, el_name = mapping.values_at(:attribute, :element)
+            defining_value = public_send(attribute)
+            unmatched << mapping unless property_contents[el_name] == defining_value
+          end
+          unmatched
+        end
+
+        def select_variable_property_contents(property_contents)
+          defining_element_names = defining_element_mappings.map{ |mapping| mapping[:element] }
+          property_contents.reject{ |name, content| defining_element_names.include?(name) }
+        end
+
+        def populate_instance_from_properties instance, variable_property_contents
+          variable_property_contents.each do |name, content|
+            mapping = attr_element_mappings.detect{ |mapping| mapping[:element] == name }
+            next unless mapping
+            value = if mapping[:numbered_lines]
+              template = mapping[:numbered_lines]
+              [].tap{ |lines|
+                line_num = 1
+                while ( content.has_key?(key = template % line_num) )
+                  lines << content[key]
+                  line_num += 1
+                end
+              }
+            elsif mapping[:type] == :array
+              content.split('|')
+            else
+              content
+            end
+            attribute = mapping[:attribute]
+            instance.public_send "#{attribute}=", value
+          end
+        end
+
+      end
+
+      attr_accessor :source_data
+
+      def xml_serialize
+        doc = Nokogiri::XML::Document.new
+        root = doc.create_element(self.class.root_element_name)
+        self.class.defining_element_mappings.each do |mapping|
+          content = self.class.public_send( mapping[:attribute] )
+          next unless content
+          element = doc.create_element( mapping[:element], nil, nil, content )
+          root.add_child element
+        end
+        self.class.attr_element_mappings.each do |mapping|
+          content = public_send( mapping[:attribute] )
+          next unless content
+          element = if mapping[:numbered_lines]
+            build_numbered_lines_xml_node( doc, mapping[:element], mapping[:numbered_lines], content )
+          elsif mapping[:type] == :array
+            build_vertical_bar_separated_list_node( doc, mapping[:element], content )
+          else
+            build_text_element_node( doc, mapping[:element], content )
+          end
+          root.add_child element
+        end
+        doc.root = root
+        doc.serialize(:save_with => Nokogiri::XML::Node::SaveOptions::AS_XML | Nokogiri::XML::Node::SaveOptions::NO_DECLARATION)
+      end
+
+      private
+
+      def build_numbered_lines_xml_node(doc, element_name, line_template, content)
+        element = doc.create_element( element_name )
+        [content].flatten.each_with_index do |line_text, idx|
+          line_num = idx + 1
+          element_name = line_template % line_num
+          line_el = doc.create_element( element_name, nil, nil, line_text )
+          element.add_child line_el
+        end
+        element
+      end
+
+      def build_vertical_bar_separated_list_node(doc, element_name, content)
+        text = [content].flatten * '|'
+        doc.create_element( element_name, nil, nil, text )
+      end
+
+      def build_text_element_node(doc, element_name, content)
+        doc.create_element( element_name, nil, nil, "#{content}" )
+      end
+
+    end
+
+  end
+end