https://github.com/willglynn/poslavu

POSLavu API client for Ruby
https://github.com/willglynn/poslavu

Last synced: 3 months ago
JSON representation

POSLavu API client for Ruby

• Host: GitHub
• URL: https://github.com/willglynn/poslavu
• Owner: willglynn
• License: mit
• Created: 2012-10-03T18:04:47.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2012-10-07T22:48:42.000Z (about 12 years ago)
• Last Synced: 2024-09-17T05:19:11.468Z (4 months ago)
• Language: Ruby
• Size: 140 KB
• Stars: 7
• Watchers: 4
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.rdoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= POSLavu

{}[http://travis-ci.org/willglynn/poslavu] {}[https://gemnasium.com/willglynn/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.

== Status

The gem works for basic API calls and querying. I had planned on adding a set

of ActiveModel-compliant objects on top, but the organization I built this for

is now giving up on POSLavu, citing stability issues and myriad other pain

points. As a result, I will not be developing this gem further.

If you're in a position where this gem will be helpful, by all means, use it.

If it breaks, by all means, fix it and send a pull request. If you'd like to

take over, let me know; I'm open.

== 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 (git checkout -b my-new-feature)

3. Commit your changes (git commit -am 'Added some feature')

4. Push to the branch (git push origin my-new-feature)

5. Create new Pull Request