poslavu 0.0.1

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Will Glynn
+
+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.rdoc

@@ -0,0 +1,106 @@
+= POSLavu
+
+POSLavu[http://www.poslavu.com/] is a hosted point-of-sale system. They
+provide an API.
+
+The POSLavu API is, franky, disgusting. It feels like something someone might
+have come up with their first week using MySQL and PHP. There's POST parameters
+and XML fragments and JSON scattered about. Error handling and input
+sanitization are afterthoughts. There's no direction or cohesiveness. Tell me:
+would *you* expose an "order" table with 91 different columns? POSLavu did.
+
+This gem wraps that API into something that's more reasonable than using their
+API directly. A gem can't fix the data model, but it can add some sanity to the
+access methods.
+
+Naturally, you'll need a POSLavu account to do anything useful.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'poslavu'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install poslavu
+
+== Usage
+
+All usage starts by instantiating a client object.
+
+    client = POSLavu::Client.new('dataname', 'token', 'key')
+
+From here, you can invoke API methods directly:
+
+    client.invoke('command', 'parameter' => 'value')
+
+This is the low-level interface. Hopefully you'll never need it.
+
+The POSLavu gem provides a higher-level query interface. Say you want to
+iterate over all your orders:
+
+    client.table('orders').each { |order|
+      # ...
+    }
+
+Done. This will issue multiple API calls as needed, traversing the list of
+orders one page at a time. Naturally, the resulting object is +Enumerable+,
+so you can call +.map+ or +.inject+ or whatever other normal things you
+might want to do.
+
+Now, say you want a list of orders that have produced 4 checks:
+
+    client.table('orders').where('no_of_checks' => 4).each { |order|
+      # ...
+    }
+
+Or maybe you want to restrict by date:
+
+    client.table('orders').filter('opened', :between, '2012-10-01', '2012-10-02')
+
+It also supports pagination, in case you'd like to handle that yourself:
+
+    client.table('orders').page(1, 50)
+    client.table('orders').page(2, 50)
+    client.table('orders').page(3, 50)
+
+Client#table returns a POSLavu::QueryScope, which lets you chain various
+conditions and lazily retrieve the results. Records are encapsulated by
+POSLavu::Row, which is just a Hash that came from the POSLavu API.
+
+== Development
+
+POSLavu uses rspec and WebMock to validate functionality.
+
+There is a component of the test suite that runs read-only queries against
+the live POSLavu API. This is intended as a smoke test, principally exercising
+the RPC mechanism, although it can also identify changes in the server-side
+data model.
+
+Running the live component of the test suite requires POSLavu API credentials.
+This is safe to run against a live site; it does not modify any data. You can
+pass in your credentials using environment variables or by creating a +.env+
+file with the following:
+
+    POSLAVU_DATANAME=foobar
+    POSLAVU_KEY=q834SCx...
+    POSLAVU_TOKEN=EZcWR0n...
+
+You can determine the proper values in the
+API[http://admin.poslavu.com/cp/index.php?mode=api] tab of the POSLavu Control
+Panel. Once you're ready, say:
+
+    $ bundle exec rake live
+
+== Contributing
+
+1. Fork it
+2. Create your feature branch (<tt>git checkout -b my-new-feature</tt>)
+3. Commit your changes (<tt>git commit -am 'Added some feature'</tt>)
+4. Push to the branch (<tt>git push origin my-new-feature</tt>)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ['--color --format documentation --tag ~live']
+end
+
+task :default => :spec
+task :test => :spec
+
+desc "Run tests against the live POSLavu servers"
+task :live do
+  sh "bundle exec rspec --tag live --color --format documentation"
+end

data/lib/poslavu.rb

@@ -0,0 +1,12 @@
+require "poslavu/version"
+
+require "poslavu/row"
+require "poslavu/client"
+require "poslavu/query_scope"
+
+module POSLavu
+end
+
+# Add some aliases so as to not be picky about capitalization
+Object.const_set(:POSlavu, POSLavu)
+Object.const_set(:Poslavu, POSLavu)

data/lib/poslavu/client.rb

@@ -0,0 +1,110 @@
+require "faraday"
+require "nokogiri"
+
+# POSLavu::Client communicates with the POSLavu API over HTTPS.
+# 
+# You must provide a +dataname+, +token+, and +key+ to create a Client.
+# From here, you can call Client#invoke to run arbitrary API commands.
+#
+# Clients don't hold any state except for a Faraday::Connection, which
+# may or may not use persistent connections depending on your default
+# Faraday adapter.
+class POSLavu::Client
+  
+  # Encapsulates an error thrown by the POSLavu API. All failing API calls
+  # via Client#invoke raise a subclass of this exception.
+  #
+  # See also:
+  # * CommandFailedError
+  # * CommunicationError
+  class Error < RuntimeError; end
+  
+  # Represents an error returned by the API. POSLavu couldn't even be bothered to
+  # use HTTP status codes, so there's nothing machine-readable here. If you need
+  # to distinguish various types of errors, you'll have to do string matching and
+  # hope they don't change anything.
+  class CommandFailedError < Error; end
+  
+  # Represents an error outside the scope of normal API failures, including all IP-,
+  # TCP-, and HTTP-level errors.
+  class CommunicationError < Error; end
+  
+  # The API endpoint as a string
+  URL = "https://admin.poslavu.com/cp/reqserv/"
+  
+  # Create a new Client with the specified credentials. These values can be
+  # retrieved from this[http://admin.poslavu.com/cp/index.php?mode=api] page as
+  # required.
+  def initialize(dataname, token, key)
+    @parameters = {
+      'dataname' => dataname,
+      'token' => token,
+      'key' => key
+    }
+  end
+  
+  # Returns this Client's +dataname+.
+  def dataname
+    @parameters['dataname']
+  end
+  
+  def inspect #:nodoc:
+    "#<POSLavu::Client dataname=#{@parameters['dataname'].inspect}>"
+  end
+  
+  # Returns an object that allows you to access the specified table.
+  #
+  #    # Find all orders for a given table
+  #    client.table('orders').where('table_id' => 5).each { |row|
+  #      # ...
+  #    }
+  #
+  # See POSLavu::QueryScope for the query syntax.
+  def table(table)
+    POSLavu::QueryScope.new(self, table)
+  end
+  
+  # Invokes a command, accepting a +parameters+ hash, and returning an array of
+  # POSLavu::Row objects.
+  #
+  # The POSLavu API flattens all these parameters into a single POST request.
+  # +command+ is broken out as a convenience because #table handles querying, and
+  # specifying <tt>'cmd' => 'foo'</tt> repeatedly doesn't feel necessary.
+  def invoke(command, parameters = {})
+    final_parameters = @parameters.merge(parameters).merge('cmd' => command)
+
+    response = connection.post URL, final_parameters
+
+    fragment = Nokogiri::XML.fragment(response.body)
+    elements = fragment.children.select(&:element?)   # .element_children doesn't work
+    
+    if elements.empty?
+      if fragment.to_s.strip.empty?
+        # did we actually get no data?
+        return []
+      else
+        # this is apparently how errors are signalled
+        raise CommandFailedError, fragment.to_s
+      end
+    else
+      # assume all the elements are <row>s, and let Row explode if we're wrong
+      elements.map { |element|
+        POSLavu::Row.from_nokogiri(element)
+      }
+    end
+    
+  rescue Faraday::Error::ClientError
+    raise CommunicationError, $!.to_s
+  end
+
+  protected
+  def connection #:nodoc:
+    @connection ||= Faraday.new(:url => URL) { |faraday|
+      faraday.request :url_encoded
+      faraday.response :raise_error
+      faraday.adapter Faraday.default_adapter
+    }.tap { |connection|
+      connection.headers[:user_agent] = "POSLavu Ruby #{POSLavu::VERSION}"
+    }
+  end
+end

data/lib/poslavu/query_scope.rb

@@ -0,0 +1,160 @@
+require 'multi_json'
+
+# QueryScope represents a retrievable set of records. You can obtain one by
+# calling POSLavu::Client#table() for the table in question.
+#
+# Query scopes are chainable. Given an initial scope representing all records
+# in a table, you may further restrict the records of interest by with #filter,
+# #page, and #where.
+#
+# Query scopes are Enumerable. #each is the obvious access method, but #to_a,
+# #map, #inject, and all your friends are also available.
+#
+# Query scopes are lazy loading. You can manipulate them as much as you want
+# without performing any API calls. The request is actually performed once you
+# call #each or any other Enumerable method. If you've called #page, the results
+# are held in memory. If not, #each issues multiple requests (internally
+# paginating) and does not hold the result in memory.
+class POSLavu::QueryScope
+  include Enumerable
+  
+  # The name of the table, as passed to POSLavu::Client#table
+  attr_reader :table
+  
+  # The list of operators supported by the POSLavu API (and thus supported by #filter).
+  Operators = ['<=', '>=', '<', '>', '=', '<>', '!=', 'BETWEEN', 'LIKE', 'NOT LIKE']
+  
+  # Returns a new QueryScope with the specified filter applied.
+  #
+  # The POSLavu API has a basic query language modeled after SQL, probably because
+  # they're shoveling the filter straight into SQL. It supports restricting +field+s
+  # using a set of Operators. All of them require a value for comparison, except
+  # +BETWEEN+, which requires two values.
+  #
+  # +LIKE+ and +NOT LIKE+ accept +'%'+ as a wildcard. There is no mechanism for
+  # pattern-matching strings containing a percent sign.
+  def filter(field, operator, value, value2=nil)
+    operator = operator.to_s.upcase
+    raise ArgumentError, "invalid operator" unless Operators.include?(operator)
+    
+    chain { |x|
+      filter = { 'field' => field, 'operator' => operator, 'value1' => value.to_s }
+      filter['value2'] = value2.to_s if operator == 'BETWEEN'
+      x.filters << filter
+    }
+  end
+  
+  # Returns a new QueryScope, restricting results to the specified page number.
+  #
+  # Pages are 1-indexed: the first page is page 1, not page 0.
+  def page(number, records_per_page=40)
+    raise ArgumentError, "the first page number is 1 (got #{number})" if number < 1
+    
+    chain { |x|
+      x.start_record = (number - 1) * records_per_page
+      x.record_count = records_per_page
+    }
+  end
+  
+  # Returns a new QueryScope, restricting results to rows matching the specified
+  # hash. It is a convenience method around #filter. The following two statements
+  # are exactly equivalent:
+  #
+  #     client.table('orders').where('table_id' => 4, 'no_of_checks' => 2)
+  #     client.table('orders').filter('table_id', '=', 4).filter('no_of_checks', '=', 2)
+  def where(hash)
+    scope = self
+    hash.each { |key,value|
+      scope = scope.filter(key, '=', value)
+    }
+    scope
+  end
+  
+  # Iterate over the records represented by this query scope.
+  #
+  # If this scope has an explicit #page set, the results will be retrieved and
+  # memoized. Otherwise, this scope will internally paginate and make successive
+  # requests, yielding each row in turn, and the results will not be memoized.
+  def each(&block)
+    if @rows
+      # we've been memoized
+      @rows.each(&block)
+      
+    elsif start_record
+      # we represent a single page
+      # do the fetching and iterate
+      @rows = fetch_rows
+
+      @rows.each(&block)
+    else
+      # we represent the whole set of possible records
+      # fetch repeatedly, in pages
+      page_number = 1
+      records_per_page = 100
+      
+      loop {
+        # create a scope for this page
+        inner_scope = page(page_number, records_per_page)
+        
+        # fetch the records as an array
+        records = inner_scope.to_a
+        
+        # pass them to the caller
+        records.each(&block)
+        
+        # is this the last page?
+        if records.size < records_per_page
+          # was this the first page?
+          if page_number == 1
+            # this is the only page
+            # memoize
+            @rows = records
+          end
+          
+          # regardless, we're done
+          break
+        end
+        
+        page_number += 1
+      }
+      
+    end
+    
+    self
+  end
+  
+  #:nodoc:
+  protected
+  attr_accessor :filters, :start_record, :record_count
+  attr_accessor :rows
+  
+  def initialize(client, table)
+    @client = client
+    @table = table
+    
+    @filters = []
+    @start_record = nil
+    @record_count = nil
+    @rows = nil
+  end
+  
+  def chain(&block)
+    dup.tap { |copy|
+      copy.rows = nil
+      yield(copy)
+    }
+  end
+  
+  def fetch_rows
+    @client.invoke('list', to_params)
+  end
+  
+  def to_params
+    {
+      'table' => @table,
+      'limit' => "#{start_record},#{record_count}"
+    }.tap do |params|
+      params['filters'] = MultiJson.dump(filters) unless filters.empty?
+    end
+  end
+end

data/lib/poslavu/row.rb

@@ -0,0 +1,63 @@
+require "nokogiri"
+
+# The POSLavu API principally operates on database rows exchanged in
+# XML fragments. These are encapsulated as POSLavu::Row objects, which
+# is really just a Hash with some additional methods.
+class POSLavu::Row < Hash
+  # Instantiate a Row, optionally copying an existing Hash.
+  def initialize(hash_to_copy = nil)
+    if hash_to_copy
+      hash_to_copy.each { |key,value|
+        self[key.to_sym] = value.to_s
+      }
+    end
+  end
+  
+  # Instantiate a Row given a string containing a <tt><row/></tt> XML fragment.
+  # This XML fragment must contain exactly one <tt><row></tt> element at the root.
+  def self.from_xml(string)
+    fragment = Nokogiri::XML.fragment(string)
+    from_nokogiri(fragment)
+  end
+  
+  # Instantiate a Row from a Nokogiri::XML::Node or similar. If you're using
+  # the public interface, you shouldn't ever need to call this.
+  def self.from_nokogiri(xml)   # :nodoc:
+    raise ArgumentError, "argument is not a Nokogiri node" unless xml.kind_of?(Nokogiri::XML::Node)
+    
+    if xml.element? && xml.name == 'row'
+      xml_row = xml
+    else
+      rows = xml.xpath('./row')
+      raise ArgumentError, "argument does not directly contain a <row> element" if rows.empty?
+      raise ArgumentError, "argument contains more than one <row> element" if rows.size > 1
+      
+      xml_row = rows.first
+    end
+    
+    new.tap { |row|
+      xml_row.element_children.each { |element|
+        row[element.name.to_sym] = element.text
+      }
+    }
+  end
+  
+  # Adds this Row to a Nokogiri::XML::Node. If you're using the public
+  # interface, you shouldn't ever need to call this.
+  def to_nokogiri(doc)  # :nodoc:
+    row = doc.create_element('row'); doc.add_child(row)
+    each { |key,value|
+      element = doc.create_element(key.to_s)
+      element.add_child(doc.create_text_node(value.to_s))
+      row.add_child(element)
+    }
+    row
+  end
+
+  # Transform this Row into a string containing a <tt><row/></tt> XML fragment
+  def to_xml
+    doc = Nokogiri::XML::Document.new
+    element = to_nokogiri(doc)
+    element.to_s
+  end
+end

data/lib/poslavu/version.rb

@@ -0,0 +1,4 @@
+module POSLavu
+  # The version of the POSLavu gem.
+  VERSION = "0.0.1"
+end

data/poslavu.gemspec

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/poslavu/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Will Glynn"]
+  gem.email         = ["will@willglynn.com"]
+  gem.description   = %q{POSLavu is a hosted point-of-sale system. The `poslavu` gem provides access to the API.}
+  gem.summary       = %q{POSLavu API client}
+  gem.homepage      = "http://github.com/willglynn/poslavu"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "poslavu"
+  gem.require_paths = ["lib"]
+  gem.version       = POSLavu::VERSION
+  
+  gem.rdoc_options  += [
+    '--title', 'POSLavu API Client',
+    '--main', 'README.rdoc',
+    '--exclude', 'spec',
+    '--exclude', 'Gemfile',
+    '--exclude', 'Rakefile'
+    ]
+
+  gem.add_dependency "nokogiri", "~> 1.5"
+  gem.add_dependency "faraday", "~> 0.8"
+  gem.add_dependency "multi_json", "~> 1.3"
+
+  gem.add_development_dependency "bundler", "~> 1.1"
+  gem.add_development_dependency "dotenv", "~> 0.2"
+  gem.add_development_dependency "guard", "~> 1.4"
+  gem.add_development_dependency "rspec", "~> 2.11"
+  gem.add_development_dependency "rake", "~> 0.9.2"
+  gem.add_development_dependency "webmock", "~> 1.8"
+  
+  gem.add_development_dependency "pry"
+end

data/spec/aliases_spec.rb

@@ -0,0 +1,12 @@
+require 'spec_helper'
+
+describe "Global aliases" do
+  describe Poslavu do
+    it { should eql(POSlavu) }
+  end
+
+  describe POSlavu do
+    it { should eql(POSLavu) }
+  end
+end
+

data/spec/live_spec.rb

@@ -0,0 +1,182 @@
+require 'spec_helper'
+
+describe "Live tests", :live => true do
+  if ENV['POSLAVU_DATANAME'] && ENV['POSLAVU_KEY'] && ENV['POSLAVU_TOKEN']
+    before(:all) { WebMock.allow_net_connect! }
+    after(:all) { WebMock.disable_net_connect! }
+    let!(:client) { POSLavu::Client.new(ENV['POSLAVU_DATANAME'], ENV['POSLAVU_TOKEN'], ENV['POSLAVU_KEY']) }
+    subject { client }
+    
+    describe("tables") do
+      let(:response) { client.table(table).page(1,1).to_a }
+      subject { response }
+      
+      describe("locations") do
+        let(:table) { 'locations' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          it { should be_kind_of(POSLavu::Row) }
+          its(:keys) { should eq [:id, :title, :address, :city, :state, :zip, :phone, :website, :manager, :taxrate, :menu_id, :ag1, :ag2, :PINwait, :integrateCC, :seat_numbers, :PINwaitM, :country, :monitary_symbol, :left_or_right, :gratuity_label, :auto_send_at_checkout, :allow_resend, :lock_orders, :lock_order_override, :exit_after_save, :exit_after_send, :exit_after_print_check, :exit_after_checkout, :exit_after_void, :admin_PIN_discount, :admin_PIN_void, :lock_net_path, :tab_view, :tabs_and_tables, :hide_tabs, :allow_tab_view_toggle, :display_forced_modifier_prices, :component_package, :ask4email_at_checkout, :component_package2, :allow_custom_items, :default_receipt_print, :product_level, :exit_order_after_save, :exit_order_after_send, :exit_order_after_print_check, :use_direct_printing, :debug_mode, :allow_deposits, :cc_signatures, :gateway, :cc_transtype, :admin_PIN_terminal_set, :admin_PIN_till_report, :ml_type, :ml_un, :ml_pw, :ml_listid, :disable_decimal, :individual_cc_receipts, :server_manage_tips, :day_start_end_time, :require_cvn, :display_order_sent_in_ipod, :print_forced_mods_on_receipt, :print_optional_mods_on_receipt, :return_after_add_item_on_ipod, :kitchen_ticket_font_size, :receipt_font_size, :modifiers_in_red, :market_type, :allow_debug_menu, :customer_cc_receipt, :verify_swipe_amount, :itemize_payments_on_receipt, :debug_console, :allow_cc_returns, :allow_voice_auth, :allow_partial_auth, :allow_signature_tip, :mute_register_bell, :group_equivalent_items, :cc_signatures_ipod, :string_encoding, :tax_inclusion, :rounding_factor, :round_up_or_down, :tax_auto_gratuity, :level_to_open_register, :append_cct_details, :html_email_receipts, :verify_remaining_payment, :multiple_quantities_in_red, :verify_quickpay, :use_language_pack, :print_item_notes_on_receipt, :verify_entered_payment, :other_transactions_open_drawer, :credit_transactions_open_drawer, :allow_to_rate, :gateway_debug, :level_to_open_register_at_checkout, :ask_for_guest_count, :level_to_edit_sent_items, :default_dining_room_background, :admin_PIN_void_payments, :admin_PIN_refund, :order_pad_font, :email, :raster_mode_font_size1, :raster_mode_font_size2, :print_logo_on_receipts, :allow_tax_exempt, :level_to_grant_tax_exempt, :timezone, :clockin_overlay, :item_icon_color, :component_package3, :save_device_console_log, :order_pad_font_ipod, :default_preauth_amount, :decimal_char, :thousands_char, :get_card_info, :bypass_checkout_message, :hide_item_titles, :allow_RFID, :display_seat_course_icons, :cash_transactions_open_drawer, :component_package_code, :vf_enrollment_id] }
+        }
+      end
+      
+      describe("orders") do
+        let(:table) { 'orders' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          it { should be_kind_of(POSLavu::Row) }
+          its(:keys) { should eq [:id, :order_id, :location, :location_id, :opened, :closed, :subtotal, :taxrate, :tax, :total, :server, :server_id, :tablename, :send_status, :discount, :discount_sh, :gratuity, :gratuity_percent, :card_gratuity, :cash_paid, :card_paid, :gift_certificate, :change_amount, :reopen_refund, :void, :cashier, :cashier_id, :auth_by, :auth_by_id, :guests, :email, :permission, :check_has_printed, :no_of_checks, :card_desc, :transaction_id, :multiple_tax_rates, :tab, :original_id, :deposit_status, :register, :refunded, :refund_notes, :refunded_cc, :refund_notes_cc, :refunded_by, :refunded_by_cc, :cash_tip, :discount_value, :reopened_datetime, :discount_type, :deposit_amount, :subtotal_without_deposit, :togo_status, :togo_phone, :togo_time, :cash_applied, :reopen_datetime, :rounding_amount, :auto_gratuity_is_taxed, :discount_id, :refunded_gc, :register_name, :opening_device, :closing_device, :alt_paid, :alt_refunded, :last_course_sent, :tax_exempt, :reclosed_datetime, :reopening_device, :reclosing_device, :exemption_id, :exemption_name, :recloser, :recloser_id, :void_reason, :alt_tablename, :checked_out, :idiscount_amount, :past_names, :itax, :togo_name, :merges, :active_device, :tabname, :last_modified, :last_mod_device, :discount_info, :last_mod_register_name, :force_closed] }
+        }
+      end
+      
+      describe("order_contents") do
+        let(:table) { 'order_contents' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :loc_id, :order_id, :item, :price, :quantity, :options, :special, :modify_price, :print, :check, :seat, :item_id, :printer, :apply_taxrate, :custom_taxrate, :modifier_list_id, :forced_modifier_group_id, :forced_modifiers_price, :course, :print_order, :open_item, :subtotal, :allow_deposit, :deposit_info, :discount_amount, :discount_value, :discount_type, :after_discount, :subtotal_with_mods, :tax_amount, :notes, :total_with_tax, :itax_rate, :itax, :tax_rate1, :tax1, :tax_rate2, :tax2, :tax_rate3, :tax3, :tax_subtotal1, :tax_subtotal2, :tax_subtotal3, :after_gratuity, :void, :discount_id, :server_time, :device_time, :idiscount_id, :idiscount_sh, :idiscount_value, :idiscount_type, :idiscount_amount, :split_factor, :hidden_data1, :hidden_data2, :hidden_data3, :hidden_data4, :tax_inclusion, :tax_name1, :tax_name2, :tax_name3, :sent, :tax_exempt, :exemption_id, :exemption_name, :itax_name, :checked_out, :hidden_data5, :hidden_data6, :price_override, :original_price, :override_id, :auto_saved, :idiscount_info, :category_id] }
+        }
+      end
+      
+      describe("order_payments") do
+        let(:table) { 'order_payments' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :order_id, :check, :amount, :card_desc, :transaction_id, :refunded, :refund_notes, :refunded_by, :refund_pnref, :tip_amount, :auth, :loc_id, :processed, :auth_code, :card_type, :datetime, :pay_type, :voided, :void_notes, :voided_by, :void_pnref, :register, :got_response, :transtype, :split_tender_id, :temp_data, :change, :total_collected, :record_no, :server_name, :action, :ref_data, :process_data, :voice_auth, :server_id, :preauth_id, :tip_for_id, :swipe_grade, :batch_no, :register_name, :pay_type_id, :first_four, :mpshc_pid, :server_time, :info, :signature, :info_label, :for_deposit, :more_info, :customer_id, :is_deposit, :device_udid, :internal_id] }
+        }
+      end
+      
+      describe("menu_groups") do
+        let(:table) { 'menu_groups' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :menu_id, :group_name, :orderby] }
+        }
+      end
+      
+      describe("menu_categories") do
+        let(:table) { 'menu_categories' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :menu_id, :group_id, :name, :image, :description, :active, :print, :last_modified_date, :printer, :modifier_list_id, :apply_taxrate, :custom_taxrate, :forced_modifier_group_id, :print_order, :super_group_id, :tax_inclusion, :ltg_display] }
+        }
+      end
+      
+      describe("menu_items") do
+        let(:table) { 'menu_items' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :category_id, :menu_id, :name, :price, :description, :image, :options1, :options2, :options3, :active, :print, :quick_item, :last_modified_date, :printer, :apply_taxrate, :custom_taxrate, :modifier_list_id, :forced_modifier_group_id, :image2, :image3, :misc_content, :ingredients, :open_item, :hidden_value, :hidden_value2, :allow_deposit, :UPC, :hidden_value3, :inv_count, :show_in_app, :super_group_id, :tax_inclusion, :ltg_display] }
+        }
+      end
+      
+      describe("tables") do
+        let(:table) { 'tables' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :loc_id, :coord_x, :coord_y, :shapes, :widths, :heights, :names, :title, :rotate, :centerX, :centerY] }
+        }
+      end
+      
+      describe("clock_punches") do
+        let(:table) { 'clock_punches' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :location, :location_id, :punch_type, :server, :server_id, :time, :hours, :punched_out, :time_out, :server_time, :server_time_out, :punch_id, :udid_in, :udid_out, :ip_in, :ip_out, :notes] }
+        }
+      end
+      
+      describe("modifiers") do
+        let(:table) { 'modifiers' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:title, :cost, :category, :id, :ingredients] }
+        }
+      end
+      
+      describe("modifiers_used") do
+        let(:table) { 'modifiers_used' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :loc_id, :order_id, :mod_id, :qty, :type, :row, :cost, :unit_cost] }
+        }
+      end
+      
+      describe("forced_modifiers") do
+        let(:table) { 'forced_modifiers' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:title, :cost, :list_id, :id, :detour, :extra, :extra2, :ingredients, :extra3, :extra4, :extra5] }
+        }
+      end
+      
+      describe("ingredients") do
+        let(:table) { 'ingredients' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:title, :qty, :unit, :low, :high, :id, :category, :cost, :loc_id] }
+        }
+      end
+      
+      describe("ingredient_categories") do
+        let(:table) { 'ingredient_categories' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:title, :description, :id, :loc_id] }
+        }
+      end
+      
+      describe("ingredient_usage") do
+        let(:table) { 'ingredient_usage' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:ts, :date, :orderid, :itemid, :ingredientid, :qty, :id, :loc_id, :server_time, :cost, :content_id] }
+        }
+      end
+      
+      describe("users") do
+        let(:table) { 'users' }
+        it { should_not be_empty }
+      
+        describe("#first") {
+          subject { response.first }
+          its(:keys) { should eq [:id, :company_code, :username, :f_name, :l_name, :email, :access_level, :quick_serve, :loc_id, :service_type, :address, :phone, :mobile, :role_id, :deleted_date, :created_date] }
+        }
+      end
+    end
+    
+  else
+    it("API credentials") {
+      pending "none provided; see README.md"
+    }
+  end
+end

data/spec/poslavu/client_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe POSLavu::Client do
+  let(:dataname) { 'dataname' }
+  let(:token) { 'token' }
+  let(:key) { 'key' }
+  let(:client) { POSLavu::Client.new(dataname, token, key) }
+  subject { client }
+  
+  describe "invoke" do
+    describe "HTTP requests" do
+      before {
+        poslavu_api_stub
+        client.invoke('command', 'abc' => 'def') rescue nil
+      }
+
+      specify("should request with 'dataname' parameter") { WebMock.should have_requested_poslavu_api('dataname' => dataname) }
+      specify("should request with 'token' parameter") { WebMock.should have_requested_poslavu_api('token' => token) }
+      specify("should request with 'key' parameter") { WebMock.should have_requested_poslavu_api('key' => key) }
+      specify("should request with 'cmd' parameter") { WebMock.should have_requested_poslavu_api('cmd' => 'command') }
+      specify("should request with hash parameter") { WebMock.should have_requested_poslavu_api('abc' => 'def') }
+      specify("should request with User-Agent header") { WebMock.should have_requested_poslavu_api.with(:headers => { 'User-Agent' => "POSLavu Ruby #{POSLavu::VERSION}"}) }
+    end
+    
+    describe "error handling" do
+      it "raises errors returned as body text" do
+        poslavu_api_stub { 'this is an error' }
+        lambda { client.invoke('command') }.should raise_exception POSLavu::Client::Error, "this is an error"
+      end
+
+      # not yet observed in the wild
+      it "raises errors for 500 responses" do
+        poslavu_api_stub.to_return(:status => 500)
+        lambda { client.invoke('command') }.should raise_exception POSLavu::Client::Error
+      end
+
+      it "raises errors for timeouts" do
+        poslavu_api_stub.to_timeout
+        lambda { client.invoke('command') }.should raise_exception POSLavu::Client::Error
+      end
+    end
+
+    describe "response parsing" do
+      before { poslavu_api_stub { response } }
+      subject { client.invoke('command') }
+      
+      describe "empty string" do
+        let(:response) { "" }
+        it { should be_kind_of Array }
+        it { should be_empty }
+      end
+      
+      describe "single row" do
+        let(:response) { [POSLavu::Row.new(:foo => 'bar', :baz => 'quxx')] }
+        it { should be_kind_of Array }
+        it("should match the expected value") { subject.should eql response }
+      end
+      
+      describe "multiple rows" do
+        let(:response) { (1..10).map { |n| POSLavu::Row.new(:counter => n) } }
+        it("should match the expected value") { subject.should eql response }
+      end
+    end
+  end
+end

data/spec/poslavu/query_scope_spec.rb

@@ -0,0 +1,138 @@
+describe POSLavu::QueryScope do
+  let(:dataname) { 'dataname' }
+  let(:token) { 'token' }
+  let(:key) { 'key' }
+  let(:table_name) { 'table' }
+  let(:client) { POSLavu::Client.new(dataname, token, key) }
+  let(:table) { client.table(table_name) }
+  
+  it "should be returned by POSLavu::Client#table" do
+    table.should be_kind_of POSLavu::QueryScope
+  end
+  
+  describe "#filter" do
+    before { poslavu_api_stub { POSLavu::Row.new } }
+    ['<=', '>=', '<', '>', '=', '<>', '!=', 'LIKE', 'NOT LIKE'].each { |operator|
+      specify "filters using #{operator}" do
+        table.filter('a', operator, 'b').page(1, 1).each {}
+        WebMock.should have_requested_poslavu_api('filters' => '[{"field":"a","operator":"' + operator + '","value1":"b"}]')
+      end
+    }
+    
+    specify "filters using BETWEEN" do
+      table.filter('a', 'BETWEEN', 'b', 'c').page(1, 1).each {}
+      WebMock.should have_requested_poslavu_api('filters' => '[{"field":"a","operator":"BETWEEN","value1":"b","value2":"c"}]')
+    end
+    
+    
+    it "chains multiple filters" do
+      table.filter('a', '=', 'b').filter('c', '=', 'd').page(1, 1).each {}
+      WebMock.should have_requested_poslavu_api('filters' => '[{"field":"a","operator":"=","value1":"b"},{"field":"c","operator":"=","value1":"d"}]')
+    end
+    
+    it "preserves pagination when filtering" do
+      base = table.page(2, 47)
+      filtered = base.filter('field', '=', 'value')
+      filtered.instance_variable_get(:@start_record).should eq 47
+      filtered.instance_variable_get(:@record_count).should eq 47
+    end
+  end
+  
+  describe "#where" do
+    before { poslavu_api_stub { POSLavu::Row.new } }
+    
+    it "creates proper JSON filter" do
+      table.where('a' => 'b', 'c' => 'd').page(1, 1).each {}
+      WebMock.should have_requested_poslavu_api('filters' => '[{"field":"a","operator":"=","value1":"b"},{"field":"c","operator":"=","value1":"d"}]')
+    end
+  end
+  
+  describe "#each" do
+    describe "for a single page" do
+      let(:page_size) { 40 }
+      before { poslavu_api_stub { (1..page_size).map { |n| POSLavu::Row.new('counter' => n) } } }
+      subject { table.page(1, page_size) }
+    
+      it "returns rows" do
+        collected = []
+        subject.each { |value| collected << value }
+        collected.size.should eq 40
+      end
+      
+      it "memoizes results" do
+        subject.each { }
+        subject.each { }
+        WebMock.should have_requested_poslavu_api.once
+      end
+      
+      it "re-requests when chained" do
+        subject.each { }
+        child = subject.filter('foo', '=', 'bar')
+        child.each { }
+        WebMock.should have_requested_poslavu_api.twice
+      end
+      
+      it "passes filter as JSON" do
+        subject.filter('a', '=', 'b').each {}
+        WebMock.should have_requested_poslavu_api('filters' => '[{"field":"a","operator":"=","value1":"b"}]')
+      end
+    end
+    
+    describe "for all pages when there is only one page" do
+      before {
+        poslavu_api_stub('limit' => '0,100') { (1..50).map { |n| POSLavu::Row.new('counter' => n) } }
+      }
+      
+      subject { table }
+      
+      it "returns all results" do
+        rows = 0
+        subject.each { rows += 1 }
+        rows.should eq 50
+      end
+      
+      it "requests all pages" do
+        subject.each {}
+        WebMock.should have_requested_poslavu_api.once
+      end
+      
+      it "memoizes results" do
+        subject.each {}
+        subject.each {}
+        WebMock.should have_requested_poslavu_api.once
+      end
+    end
+    
+    describe "for all pages when there is more than one" do
+      let(:full_page) { (1..100).map { |n| POSLavu::Row.new('counter' => n) } }
+      let(:half_page) { full_page[0,50] }
+      
+      before {
+        poslavu_api_stub('limit' => '0,100') { full_page }
+        poslavu_api_stub('limit' => '100,100') { full_page }
+        poslavu_api_stub('limit' => '200,100') { half_page }
+      }
+
+      subject { table }
+      
+      it "returns all results" do
+        rows = 0
+        subject.each { rows += 1 }
+        rows.should eq 250
+      end
+      
+      it "requests all pages" do
+        subject.each {}
+        WebMock.should have_requested_poslavu_api.times(3)
+      end
+      
+      it "does not memoize results" do
+        subject.each {}
+        subject.each {}
+        WebMock.should have_requested_poslavu_api.times(6)
+      end
+    end
+    
+  end
+  
+end

data/spec/poslavu/row_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe POSLavu::Row do
+  subject { POSLavu::Row.new }
+  
+  it { should be_kind_of Hash }
+  
+  describe "new" do
+    subject { POSLavu::Row.new(hash) }
+
+    describe "hash with symbol key and string value" do
+      let(:hash) do { :a => 'b' } end
+      its(:keys) { should eql [:a] }
+      its(:values) { should eql ['b'] }
+    end
+
+    describe "hash with string key and integer value" do
+      let(:hash) do { 'a' => 0 } end
+      its(:keys) { should eql [:a] }
+      its(:values) { should eql ['0'] }
+    end
+  end
+  
+  describe "#from_xml" do
+    subject { POSLavu::Row.from_xml(string) }
+    
+    describe "<row/>" do
+      let(:string) { "<row/>" }
+      it { should be_empty }
+    end
+    
+    describe "<row><foo>bar</foo></row>" do
+      let(:string) { "<row><foo>bar</foo></row>" }
+      its(:keys) { should eq [:foo] }
+      its(:values) { should eq ['bar'] }
+      
+      it("to_xml should match") {
+        subject.to_xml.gsub(/\s/, '').should eq(string.gsub(/\s/, ''))
+      }
+    end
+    
+    describe "failure cases" do
+      def self.should_fail(string)
+        subject { lambda { POSLavu::Row.from_xml(string) } }
+        it("#{string.inspect} should raise ArgumentError") { should raise_exception ArgumentError }
+      end
+      
+      should_fail nil
+      should_fail ""
+      should_fail "<not_a_row_element/>"
+      should_fail "<row/><row/>"
+      should_fail "<result><row/></result>"
+    end
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require "poslavu"
+Bundler.require :development
+
+require 'webmock/rspec'
+
+Dir[File.expand_path("../support/**/*.rb", __FILE__)].each {|f| require f}
+
+RSpec.configure { |config|
+  config.include POSLavu::APIStub
+}
+
+Dotenv.load

data/spec/support/poslavu_api_stub.rb

@@ -0,0 +1,29 @@
+module POSLavu::APIStub
+  def poslavu_api_stub(params = {}, &block)
+    stub = stub_http_request(:post, POSLavu::Client::URL).with(:body => hash_including(params))
+    
+    if block
+      stub.to_return { |request|
+        response = block.call(request)
+      
+        if response.instance_of?(Hash)
+          response
+        else
+          body = case response
+          when Array then response.map(&:to_xml).join    # assume array of rows
+          when POSLavu::Row then response.to_xml
+          else response.to_s
+          end
+
+          { :body => body, :status => 200 }
+        end
+      }
+    end
+    
+    stub
+  end
+  
+  def have_requested_poslavu_api(params = {})
+    have_requested(:post, POSLavu::Client::URL).with(:body => hash_including(params))
+  end
+end

metadata

@@ -0,0 +1,247 @@
+--- !ruby/object:Gem::Specification
+name: poslavu
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Will Glynn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: POSLavu is a hosted point-of-sale system. The `poslavu` gem provides
+  access to the API.
+email:
+- will@willglynn.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/poslavu.rb
+- lib/poslavu/client.rb
+- lib/poslavu/query_scope.rb
+- lib/poslavu/row.rb
+- lib/poslavu/version.rb
+- poslavu.gemspec
+- spec/aliases_spec.rb
+- spec/live_spec.rb
+- spec/poslavu/client_spec.rb
+- spec/poslavu/query_scope_spec.rb
+- spec/poslavu/row_spec.rb
+- spec/spec_helper.rb
+- spec/support/poslavu_api_stub.rb
+homepage: http://github.com/willglynn/poslavu
+licenses: []
+post_install_message: 
+rdoc_options:
+- --title
+- POSLavu API Client
+- --main
+- README.rdoc
+- --exclude
+- spec
+- --exclude
+- Gemfile
+- --exclude
+- Rakefile
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4247689874090540976
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4247689874090540976
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: POSLavu API client
+test_files:
+- spec/aliases_spec.rb
+- spec/live_spec.rb
+- spec/poslavu/client_spec.rb
+- spec/poslavu/query_scope_spec.rb
+- spec/poslavu/row_spec.rb
+- spec/spec_helper.rb
+- spec/support/poslavu_api_stub.rb