sagamore-client 3.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MGUyNmI0ZTlhZWUxNzNkN2Q1NGJlYjcyOGZjNWQ5ODMxMjEyZDgyMQ==
+  data.tar.gz: !binary |-
+    NDM0ZmQzMzRjNTg3ODdiMmZkMWRkMTVlYzFjNGQyNzUxY2QwYWY3MQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZWIwY2U4MGQyY2JiNGI2ZTg5OTI2ZDUxOTdmMmE5Mjc3Y2VmYTE5YjJjOGJj
+    YWJiNmQ3Y2ZhZGJlYzY5OWQ5NThhN2NmOGY2NGJkYzU2YWVmYWU5MjZiY2Q4
+    YTc0ZThmM2VjMmU5YzQ3ZjU3MjIyMWViNjRmYjJjY2JkMTJiOTU=
+  data.tar.gz: !binary |-
+    MzZjMDA5OWU0YzA4MGM5N2VjYWVjNGQ5ZDQ3NDEyODhkNDlmMGIyMTJhZGMy
+    YzgzNjJlM2QyNjU0MGMwMTk1ODMxNzMwNTk1ZmRlYzViNTRkOWZiOGZlNWNh
+    YzJhNjJiNTZhMWUxYzI2ODAwNmMxY2E4MmEyYmQxYjMyMGVkNDg=

data/.gitignore

@@ -0,0 +1,4 @@
+pkg
+.yardoc
+doc
+coverage

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - ruby-head

data/.yardopts

@@ -0,0 +1 @@
+--title "Sagamore Client"

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 2.11'
+  gem 'webmock', :require => false
+  gem 'coveralls', :require => false
+end
+
+group :development do
+  gem 'pry'
+end

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    sagamore-client (3.0.1)
+      addressable (~> 2.2.8)
+      hashie
+      json (~> 1.7.4)
+      patron (~> 0.4.18)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    coderay (1.0.7)
+    coveralls (0.6.9)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    crack (0.3.1)
+    diff-lcs (1.1.3)
+    hashie (1.2.0)
+    json (1.7.4)
+    method_source (0.8)
+    mime-types (1.25)
+    multi_json (1.8.0)
+    patron (0.4.18)
+    pry (0.9.10)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.3.1)
+    rake (0.9.2.2)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.2)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.1)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    slop (3.3.2)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
+    tins (0.9.0)
+    webmock (1.8.8)
+      addressable (~> 2.2.8)
+      crack (>= 0.1.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls
+  pry
+  rake
+  rspec (~> 2.11)
+  sagamore-client!
+  webmock

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Sagamore Retail
+
+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,252 @@
+# Sagamore Retail Client
+
+[![Build Status](https://travis-ci.org/sagamore/sagamore-client-rb.png)](https://travis-ci.org/sagamore/sagamore-client-rb)
+[![Code Climate](https://codeclimate.com/github/sagamore/sagamore-client-rb.png)](https://codeclimate.com/github/sagamore/sagamore-client-rb)
+[![Coverage Status](https://coveralls.io/repos/sagamore/sagamore-client-rb/badge.png)](https://coveralls.io/r/sagamore/sagamore-client-rb)
+[![Dependency Status](https://gemnasium.com/sagamore/sagamore-client-rb.png)](https://gemnasium.com/sagamore/sagamore-client-rb)
+
+This is the [Sagamore Retail](http://sagamoreretail.com/) (a point-of-sale/retail management system) client library for Ruby. It provides access to the Sagamore Retail HTTP API.
+
+It is a wrapper around the [Patron](http://toland.github.com/patron/) HTTP client library. Supports MRI 1.9+.
+
+You can find [documentation here](http://rdoc.info/github/sagamore/sagamore-client-rb).
+
+## Installation
+
+You need a recent version of libcurl and a sane build environment.
+
+Debian/Ubuntu:
+
+```
+sudo apt-get install build-essential libcurl4-openssl-dev
+gem install sagamore-client
+```
+
+## Connecting
+
+```ruby
+sagamore = Sagamore::Client.new 'http://example.sagamore.us/api'
+sagamore.auth :username => 'user', :password => 'secret'
+```
+
+## Resource oriented
+
+```ruby
+resource = sagamore[:items][1234]
+response = resource.get
+response = resource.delete
+
+# Query string generation:
+resource1 = sagamore[:items]
+resource2 = resource.query(:key1 => 'val1', 'key with spaces' => 'val with spaces')
+resource2.uri.to_s
+# => "/items?key%20with%20spaces=val%20with%20spaces&key1=val1"
+```
+
+## URI oriented
+
+```ruby
+response = sagamore.get '/items/1234'
+response = sagamore.delete '/items/1234'
+item_count = sagamore.count '/items'
+```
+
+## Collection Resources
+
+### Enumerable
+Resources include Ruby's Enumerable module for easy iteration over collections:
+
+```ruby
+sagamore[:items].each do |item|
+  puts item['description']
+end
+
+item_count = sagamore[:items].count
+
+usernames = sagamore[:users].map {|user| user['login']}
+```
+
+### Filtering
+Resources have a `filter` method that support's Sagamore's advanced filter syntax:
+
+```ruby
+active_users = sagamore[:users].filter(:active => true)
+active_users.each do |user|
+  # do something with each active user
+end
+
+# filter returns a new resource which allows for chaining:
+items = sagamore[:items]
+active_items = items.filter(:active => true)
+active_items.filter(:price => {'$gt' => 10}).each do |item|
+   # ...
+end
+
+# filtering custom fields:
+sagamore[:items].filter('custom@size'=> 'XL')
+```
+
+### Sorting
+Resources have a `sort` method that accepts any number of sort options. Note that each call to sort overwrites any previous sorts.
+
+```ruby
+resource.sort(:id, :price)
+resource.sort('created_at,desc')
+
+# returns a new resource for chaining:
+resource.sort(:description, :created_at).filter(:active => true).each do |item|
+  # ...
+end
+```
+
+### Creating Resources
+
+Create a new resource via POST:
+
+```ruby
+collection = client[:items]
+response = collection.post! :description => 'Some New Item'
+response.status_line
+# => "HTTP/1.1 201 Created"
+
+# To fetch the newly created resource:
+new_item_response = response.resource.get!
+new_item_response[:description]
+# => "Some New Item"
+```
+
+### Embedding Related Resources
+
+Use the `embed` method to include the contents of related resource in the response body of each item in the collection:
+
+```ruby
+collection = client[:sales][:orders].embed(:customer, :location)
+collection.first.to_hash
+# => {
+  "id" => 1,
+  "customer_id" => 2,
+  "customer" =>  {
+    # customer data
+  },
+  "location_id" => 3,
+  "location" =>  {
+    # location data
+  }
+}
+```
+
+The `embed` method accepts one or more arguments as symbols or strings. It supports chaining and will merge the results of multiple calls.
+
+### Looping while results exist
+
+Issuing deletes while iterating over a collection resource can cause the pagination to shift resulting in unexpected behavior. Use `while_results` when you want to:
+
+* Consume messages from a queue, deleting each message after it has been processed.
+* Delete all resources in a collection that doesn't support a top-level DELETE method.
+
+For example:
+
+```ruby
+collection = client[:system][:messages]
+collection.while_results do |message|
+  # process message here...
+  collection[message['id']].delete!
+end
+```
+
+## Request body
+
+If the request body is a Hash, it will automatically be serialized as JSON. Otherwise, it is
+passed through untouched:
+
+```ruby
+# this:
+sagamore[:some_collection].post :a => 1, :b => 2
+
+# is equivalent to this:
+sagamore[:some_collection].post '{"a":1,"b":2}'
+```
+
+## Response
+
+```ruby
+response = sagamore[:items][1].get
+
+response.status # Response status code as an Integer
+response.success? # true/false depending on whether 'status' indicates non-error
+response.body # Returns a Sagamore::Client::Body object (see below)
+response.raw_body # Returns the raw response body as a string
+response[:some_key] # Returns the corresponding key from 'body'
+response.headers # Response headers as a Hash
+response.resource # Returns a Resource if the response included a "Location" header, else nil
+```
+
+### Response Body
+
+Given the following JSON response from the server:
+
+```javascript
+{
+  "id": 1234,
+  "custom": {
+    "color": "Blue"
+  }
+}
+```
+
+Here are the various ways you can access the data:
+
+```ruby
+body = response.body
+
+# Symbols and strings can be used interchangeably for keys
+body[:id]
+# => 1234
+
+body[:custom][:color]
+# => "Blue"
+
+body['custom']['color']
+# => "Blue"
+
+body.to_hash
+# => {"id"=>1234, "custom"=>{"color"=>"Blue"}}
+
+response.raw_body
+# => "{\"id\":1234,\"custom\":{\"color\":\"Blue\"}}"
+```
+
+## Bang variants
+
+All HTTP request methods have a bang variant that raises an exception on failure:
+
+```ruby
+response = sagamore[:i_dont_exist].get
+response.status
+# => 404
+
+sagamore[:i_dont_exist].get!
+# Raises Sagamore::Client::RequestFailed exception
+
+# To access the response from the exception:
+begin
+  sagamore[:i_dont_exist].get!
+rescue Sagamore::Client::RequestFailed => error
+  puts error.response.status
+end
+# => 404
+
+```
+
+## Debugging
+
+```ruby
+# Log request/response trace to stdout
+client.debug = true
+
+# Or, log to a file
+client.debug = '/path/to/file.log'
+
+# Same values can be passed via :debug option to client constructor
+client = Sagamore::Client.new '<url>', :debug => true
+```

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/setup'
+Bundler.require(:default, :development)
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+desc "Start a console with a Sagamore::Client instance"
+task :console do
+  require 'sagamore/client'
+  CLIENT = Sagamore::Client.new(ENV['URI'])
+  CLIENT.auth :username => ENV['USER'], :password => ENV['PASSWORD']
+  Pry.start
+end

data/lib/sagamore-client.rb

@@ -0,0 +1 @@
+require 'sagamore/client'

data/lib/sagamore/client.rb

@@ -0,0 +1,263 @@
+require 'rubygems'
+require 'patron'
+require 'addressable/uri'
+require 'json'
+
+require 'sagamore/client/errors'
+
+##
+# Sagamore namespace
+module Sagamore
+  ##
+  # The main point of interaction for the Sagamore Client library.
+  #
+  # Client code must successfully authenticate with the API via the {#auth}
+  # method before calling any HTTP methods or the API will return authorization
+  # errors.
+  #
+  # Provides direct access to the URI-oriented interface via the HTTP methods.
+  # Provides access to the URI-oriented interface via the {#[]} method.
+  class Client
+    ##
+    # Alias for {Addressable::URI}
+    URI = Addressable::URI
+
+    ##
+    # Default number of records per page when iterating over collection resources
+    DEFAULT_PER_PAGE = 20
+
+    ##
+    # Default request timeout in seconds
+    DEFAULT_TIMEOUT = 60
+
+    ##
+    # Default connection timeout in seconds
+    DEFAULT_CONNECT_TIMEOUT = 10
+
+    ##
+    # @return [Addressable::URI] The client's base URI
+    attr_reader :base_uri
+
+    ##
+    # @param [String] base_uri Base URI
+    # @option opts [Boolean, String] :debug Pass true to debug to stdout. Pass a String to debug to given filename.
+    # @option opts [Boolean] :insecure Disable SSL certificate verification
+    def initialize(base_uri, opts={})
+      @base_uri = URI.parse(base_uri)
+      configure_session(base_uri, opts)
+    end
+
+    ##
+    # Returns the underlying Patron session
+    #
+    # @see http://patron.rubyforge.org/Patron/Session.html Patron::Session docs
+    #
+    # @return [Patron::Session]
+    def session
+      @session ||= Patron::Session.new
+    end
+
+    ##
+    # Set to true to enable debugging to STDOUT or a string to write to the file
+    # at that path.
+    #
+    # @param [String, Boolean] debug
+    #
+    # @return [String, Boolean] The debug argument
+    def debug=(debug)
+      session.enable_debug(debug == true ? nil : debug)
+    end
+
+    ##
+    # Passes the given credentials to the server, storing the session token on success.
+    #
+    # @raise [AuthFailed] If the credentials were invalid or the server returned an error
+    #
+    # @return [true]
+    #
+    # @option opts [String] :username Sagamore username
+    # @option opts [String] :password Sagamore password
+    def auth(opts={})
+      unless opts[:username] && opts[:password]
+        raise "Must specify :username and :password"
+      end
+      body = URI.form_encode \
+        :auth_key => opts[:username],
+        :password => opts[:password]
+      response = post '/auth/identity/callback', body,
+        'Content-Type' => 'application/x-www-form-urlencoded'
+      response.success? or raise AuthFailed, "Sagamore auth failed"
+    end
+
+    ##
+    # Performs a HEAD request against the given URI and returns the {Response}.
+    #
+    # @return [Response]
+    def head(uri, headers=false); make_request(:head, uri, headers); end
+
+    ##
+    # Performs a HEAD request against the given URI. Returns the {Response}
+    # on success and raises a {RequestFailed} on failure.
+    #
+    # @raise [RequestFailed] On error response
+    #
+    # @return [Response]
+    def head!(uri, headers=false); raise_on_fail head(uri, headers); end
+
+    ##
+    # Performs a GET request against the given URI and returns the {Response}.
+    #
+    # @return [Response]
+    def get(uri, headers=false); make_request(:get, uri, headers); end
+
+    ##
+    # Performs a GET request against the given URI. Returns the {Response}
+    # on success and raises a {RequestFailed} on failure.
+    #
+    # @raise [RequestFailed] On error response
+    #
+    # @return [Response]
+    def get!(uri, headers=false); raise_on_fail get(uri, headers); end
+
+    ##
+    # Performs a DELETE request against the given URI and returns the {Response}.
+    #
+    # @return [Response]
+    def delete(uri, headers=false); make_request(:delete, uri, headers); end
+
+    ##
+    # Performs a DELETE request against the given URI. Returns the {Response}
+    # on success and raises a {RequestFailed} on failure.
+    #
+    # @raise [RequestFailed] On error response
+    #
+    # @return [Response]
+    def delete!(uri, headers=false); raise_on_fail delete(uri, headers); end
+
+    ##
+    # Performs a PUT request against the given URI and returns the {Response}.
+    #
+    # @return [Response]
+    def put(uri, body, headers=false); make_request(:put, uri, headers, body); end
+
+    ##
+    # Performs a PUT request against the given URI. Returns the {Response}
+    # on success and raises a {RequestFailed} on failure.
+    #
+    # @raise [RequestFailed] On error response
+    #
+    # @return [Response]
+    def put!(uri, body, headers=false); raise_on_fail put(uri, body, headers); end
+
+    ##
+    # Performs a POST request against the given URI and returns the {Response}.
+    #
+    # @return [Response]
+    def post(uri, body, headers=false); make_request(:post, uri, headers, body); end
+
+    ##
+    # Performs a POST request against the given URI. Returns the {Response}
+    # on success and raises a {RequestFailed} on failure.
+    #
+    # @raise [RequestFailed] On error response
+    #
+    # @return [Response]
+    def post!(uri, body, headers=false); raise_on_fail post(uri, body, headers); end
+
+    ##
+    # Returns a Resource for the given URI path.
+    #
+    # @return [Resource]
+    def [](uri)
+      Resource.new(self, uri)
+    end
+
+    ##
+    # Iterates over each page of subordinate resources of the given collection
+    # resource URI and yields the {Response} to the block.
+    def each_page(uri)
+      uri = URI.parse(uri)
+      total_pages = nil
+      page = 1
+      uri.query_values = {'per_page' => DEFAULT_PER_PAGE}.merge(uri.query_values || {})
+      while total_pages.nil? or page <= total_pages
+        uri.merge_query_values! 'page' => page
+        response = get!(uri)
+        yield response
+        total_pages ||= response['pages']
+        page += 1
+      end
+    end
+
+    ##
+    # Iterates over each subordinate resource of the given collection resource
+    # URI and yields its representation to the given block.
+    def each(uri)
+      each_page(uri) do |page|
+        page['results'].each do |result|
+          yield result
+        end
+      end
+    end
+  
+    ##
+    # Returns a count of subordinate resources of the given collection resource
+    # URI.
+    #
+    # @param [#to_s] uri
+    # @raise [RequestFailed] If the GET fails
+    # @return [Integer] The subordinate resource count
+    def count(uri)
+      uri = URI.parse(uri)
+      uri.merge_query_values! 'page' => 1, 'per_page' => 1
+      get!(uri)['total']
+    end
+
+    private
+
+    def prepare_request_body(body)
+      body.is_a?(Hash) ? JSON.dump(body) : body
+    end
+
+    def make_request(method, uri, headers=false, body=false)
+      args = [prepare_uri(uri).to_s]
+      args.push prepare_request_body(body) unless body === false
+      args.push headers unless headers === false
+      new_response session.__send__(method, *args)
+    end
+
+    def raise_on_fail(response)
+      if !response.success?
+        error = RequestFailed.new "Request failed with status: #{response.status_line}"
+        error.response = response
+        raise error
+      end
+      response
+    end
+
+    def prepare_uri(uri)
+      uri = URI.parse(uri)
+      uri.path = uri.path.gsub(/^#{base_uri.path}/, '')
+      uri
+    end
+
+    def new_response(patron_response)
+      Response.new patron_response, self
+    end
+
+    def configure_session(base_url, opts)
+      session.base_url = base_url
+      session.headers['Content-Type'] = 'application/json'
+      session.handle_cookies
+      session.insecure = opts[:insecure] if opts.has_key?(:insecure)
+      session.timeout = DEFAULT_TIMEOUT
+      session.connect_timeout = DEFAULT_CONNECT_TIMEOUT
+      self.debug = opts[:debug] if opts.has_key?(:debug)
+    end
+  end
+end
+
+require 'sagamore/client/resource'
+require 'sagamore/client/response'
+require 'sagamore/client/body'
+require 'sagamore/client/uri_ext'