sage_one 0.0.1

data/.gitignore

@@ -0,0 +1,14 @@
+*.gem
+.bundle
+Gemfile.lock
+log/*
+.rvmrc
+.DS_Store
+coverage
+*.sublime
+.yardoc
+_yardoc
+spec/reports
+rdoc
+doc/*
+start_irb

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - jruby-19mode
+  - rbx-19mode
+  - ruby-head
+  - jruby-head
+before_install:
+  - gem update --system
+  - gem --version

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+lib/**/*.rb
+-
+LICENSE

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+platforms :jruby do
+  gem "jruby-openssl", "~> 0.7"
+end
+
+# Specify your gem's dependencies in sage_one.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Luke Brown, Chris Stainthorpe
+
+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,141 @@
+# Sage One [![Build Status](https://secure.travis-ci.org/customersure/sage_one.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/7b1e86c3d9e3583a684d326a97ba06d0.png)][gemnasium]
+Faraday-based Ruby wrapper for the Sage One API
+
+[travis]: http://travis-ci.org/customersure/sage_one
+[gemnasium]: https://gemnasium.com/customersure/sage_one
+
+## Installation
+Add `sage_one` gem to your `Gemfile`
+
+    gem 'sage_one'
+
+## Documentation
+[http://rdoc.info/gems/sage_one][documentation]
+
+[documentation]: http://rdoc.info/gems/sage_one
+
+## Usage
+### Authentication
+This documentation assumes you have already obtained a client id and client secret from Sage.
+
+To make any requests to the Sage One API, you must present an OAuth access token. The basic flow for obtaining a token for a user is as follows:
+
+```ruby
+# The code below is over-simplified. Read Sage's own API docs and the documentation for SageOne::Oauth to get
+# a better idea of how to implement this in the context of your own app.
+SageOne.configure do |c|
+  c.client_id     = "YOUR_CLIENT_ID_OBTAINED_FROM_SAGE"
+  c.client_secret = "YOUR_CLIENT_SECRET_OBTAINED_FROM_SAGE"
+end
+
+# Redirect the current user to SageOne. This will give them the choice to link SageOne with your app.
+# and subsequently redirect them back to your callback_url with an authorisation_code if they choose to do so.
+redirect_to SageOne.authorize_url('https://www.example.com/your_callback_url')
+
+# Then, in the callback URL controller, run get_access_token, i.e.
+response = SageOne.get_access_token(params[:code], 'https://www.example.com/your_callback_url')
+User.save_access_token(response.access_token) unless response.access_token.nil?
+```
+
+### Standard API requests
+Once you have an access token, configure the client with it, along with your client id and secret, and you're good to go:
+
+```ruby
+SageOne.configure do |c|
+  c.client_id     = "YOUR_CLIENT_ID_OBTAINED_FROM_SAGE"
+  c.client_secret = "YOUR_CLIENT_SECRET_OBTAINED_FROM_SAGE"
+  c.access_token  = current_user.access_token
+end
+
+# Get an array of all sales invoices
+invoices = SageOne.sales_invoices
+
+# Add search params
+SageOne.sales_invoices(status: 2, contact: 65489)
+
+# Dates in search params...
+# The SageOne API requires that you specify dates as dd/mm/yyyy
+SageOne.sales_invoices(from_date: '21/11/2011')
+
+# We simplify this by also allowing you to specify a date-like object (anything that responds to strftime)
+SageOne.sales_invoices(from_date: 2.weeks.ago)  #rails
+
+# Note that we can't protect you from doing the wrong thing with ambiguous dates..
+SageOne.sales_invoices(from_date: '05/01/2012') # Hope that you meant 5th January and not 1st May
+```
+You can configure the `SageOne` client on the fly. For example, if you'd prefer to configure your client_id and secret in an
+initializer then set the access_token in a controller:
+
+```ruby
+SageOne.new(access_token: current_user.access_token).sales_invoices
+```
+
+### Pagination
+You can request any 'page' of results returned from the API by adding `start_index: n` to any API call:
+
+```ruby
+SageOne.sales_invoices(start_index: 30)
+SageOne.sales_invoices(start_date: '28/02/2010', start_index: 50)
+
+```
+
+You can also turn on 'auto traversal' to have the client recursively get a full result set. Beware of using this on large result sets.
+
+```ruby
+# Recursively request ALL sales invoices, appending them to the body of the request
+SageOne.new(auto_traversal: true).sales_invoices
+```
+
+### Other usage notees
+- HTTP 1.1 requires that you set a Host: header. Whilst the gem will currently work fine without this, if conformance to the spec is important to you, set this with `request_host=`
+- You can set a proxy server with `proxy=`
+- To obtain raw, unprocessed responses back from the API, specify `raw_responses = true`. Read the documentation for more information on this.
+
+
+## Open Source
+See the [LICENSE][] file for more information.
+
+We actively encourage contributions to this gem. Whilst we have provided a robust, tested, documented, full-featured core of an wrapper for this new API, we have to balance our time spent on this gem against [the day job][cs].
+Therefore, if there are API endpoints we haven't covered yet, please fork us, add tests, documentation and coverage, and submit a pull request.
+
+### Submitting a Pull Request
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake spec`. If your specs fail, return to step 5.
+7. Run `open coverage/index.html`. If your changes are not completely covered
+   by your tests, return to step 3.
+8. Add documentation for your feature or bug fix.
+9. Run `bundle exec rake doc:yard`. If your changes are not 100% documented, go
+   back to step 8.
+10. Add, commit, and push your changes.
+11. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/
+[cs]: http://www.customersure.com/
+
+## Supported Ruby Versions
+TODO
+
+## Contributors and Inspiration
+
+[SageOne][sageone] is a product of [The Sage Group][sage].
+
+The `sage_one` gem was created by [Luke Brown][luke] and [Chris Stainthorpe][chris] whilst at [CustomerSure][cs], but is heavily inspired by the following gems: [Octokit][], [Twitter][], and [instagram-ruby-gem][].
+
+[sage]: http://www.sage.com/
+[sageone]: http://www.sageone.com/
+[luke]: http://www.tsdbrown.com/
+[chris]: http://www.randomcat.co.uk/
+[octokit]: https://github.com/pengwynn/octokit/
+[twitter]: https://github.com/sferik/twitter/
+[instagram-ruby-gem]: https://github.com/Instagram/instagram-ruby-gem/
+
+## Copyright
+Copyright (c) 2012 Chris Stainthorpe, Luke Brown. See [LICENSE][] for details.
+
+[license]: https://github.com/customersure/sage_one/blob/master/LICENSE

data/Rakefile

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

data/bin/autospec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'autospec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('sage_one', 'autospec')

data/bin/htmldiff

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'htmldiff' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('sage_one', 'htmldiff')

data/bin/ldiff

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'ldiff' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('sage_one', 'ldiff')

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('sage_one', 'rake')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('sage_one', 'rspec')

data/bin/yard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('yard', 'yard')

data/bin/yardoc

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'yardoc' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('yard', 'yardoc')

data/bin/yri

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'yri' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('yard', 'yri')

data/lib/faraday/request/oauth2.rb

@@ -0,0 +1,25 @@
+require 'faraday'
+
+# @api private
+module FaradayMiddleware
+
+  AUTH_HEADER = 'Authorization'.freeze
+
+  # Simple middleware that adds the access token to each request.
+  #
+  # The access token is placed in the "Authorization" HTTP request header.
+  # However, an explicit "Authorization" header for the current request
+  # will not be overriden.
+  # @api private
+  class OAuth2 < Faraday::Middleware
+    def call(env)
+      env[:request_headers][AUTH_HEADER] ||= %(Bearer #{@token}) if @token
+      @app.call env
+    end
+
+    def initialize(app, token = nil)
+      super(app)
+      @token = token
+    end
+  end
+end

data/lib/faraday/response/convert_sdata_to_headers.rb

@@ -0,0 +1,70 @@
+require 'faraday'
+require 'faraday_middleware/response_middleware'
+require 'addressable/uri'
+
+# @api private
+module FaradayMiddleware
+
+  # Middleware to strip out Sage's pagination SData from the body and place
+  # it in a custom response header instead (Using familiar 'Link' header syntax).
+  # This just leaves the resources in the body which can then be recursively
+  # collected later by following the links.
+  #
+  # @api private
+  class ConvertSdataToHeaders < ResponseMiddleware
+
+    SDATA_START_INDEX    = "$startIndex".freeze
+    SDATA_TOTAL_RESULTS  = "$totalResults".freeze
+    SDATA_ITEMS_PER_PAGE = "$itemsPerPage".freeze
+    SDATA_RESOURCES      = "$resources".freeze
+    SDATA_HEADER_NAME    = "X-SData-Pagination-Links".freeze
+
+    def call(env)
+      @app.call(env).on_complete do
+        @response = env[:response]
+
+        # Only proceed if SData is actually present
+        next unless @response.body && @response.body.kind_of?(Hash) && @response.body[SDATA_TOTAL_RESULTS]
+
+        @url  = Addressable::URI::parse(env[:url])
+        @url.query_values ||= {}
+
+        # Add 'next' link, if we're not on the last page
+        add_link(next_start_index, 'next') if next_start_index < @response.body[SDATA_TOTAL_RESULTS]
+
+        # Add 'prev' link if we're not on the first page
+        add_link(prev_start_index, 'prev') if prev_start_index >= 0
+
+        # Special case: If we're halfway through the first page, don't allow negative start indices
+        add_link(0, 'prev') if @response.body[SDATA_START_INDEX] != 0 && prev_start_index < 0
+
+        # Add the page links into the header
+        @response.headers[SDATA_HEADER_NAME] = @links.join(', ') unless @links.empty?
+
+        # Strip out the SData from the body
+        env[:body] = @response.body[SDATA_RESOURCES]
+      end
+    end
+
+    def initialize(app)
+      @links = []
+      super app
+    end
+
+    private
+
+    def add_link(start_index, rel)
+      @url.query_values = @url.query_values.merge({ SDATA_START_INDEX => start_index })
+      @links << %Q{<#{@url.to_str}>; rel="#{rel}"}
+    end
+
+    def next_start_index
+      @response.body[SDATA_START_INDEX] + @response.body[SDATA_ITEMS_PER_PAGE]
+    end
+
+    def prev_start_index
+      @response.body[SDATA_START_INDEX] - @response.body[SDATA_ITEMS_PER_PAGE]
+    end
+
+  end
+end

data/lib/faraday/response/raise_sage_one_exception.rb

@@ -0,0 +1,42 @@
+require 'faraday'
+
+# @api private
+module FaradayMiddleware
+
+  # Checks the status of the API request and raises
+  # relevant exceptions when detected.
+  # @see SageOne::Error SageOne::Error for possible errors to rescue from.
+  #
+  # @api private
+  class RaiseSageOneException < Faraday::Middleware
+    def call(env)
+      @app.call(env).on_complete do |response|
+        case response[:status].to_i
+        when 400
+          raise SageOne::BadRequest, error_message(response)
+        when 401
+          raise SageOne::Unauthorized, error_message(response)
+        when 403
+          raise SageOne::Forbidden, error_message(response)
+        when 404
+          raise SageOne::NotFound, error_message(response)
+        when 409
+          raise SageOne::Conflict, error_message(response)
+        when 422
+          raise SageOne::UnprocessableEntity, error_message(response)
+        end
+      end
+    end
+
+    private
+
+    def error_message(response)
+      JSON.unparse({
+        method: response[:method],
+        url:    response[:url].to_s,
+        status: response[:status],
+        body:   (response[:body].nil? ? "" : response[:body])
+      })
+    end
+  end
+end

data/lib/sage_one/client/contacts.rb

@@ -0,0 +1,14 @@
+module SageOne
+  class Client
+    module Contacts
+      # Get a contact record by ID
+      # @param [Integer] id Contact ID
+      # @return [Hashie::Mash] Contact record
+      # @example Get a contact:
+      #   SageOne.contact(12345)
+      def contact(id)
+        get("contacts/#{id}")
+      end
+    end
+  end
+end

data/lib/sage_one/client/sales_invoices.rb

@@ -0,0 +1,77 @@
+module SageOne
+  class Client
+    module SalesInvoices
+
+      # List sales invoices
+      # @param options [Hash] A customizable set of options.
+      # @option options [Integer] :contact Use this to filter by contact id
+      # @option options [Integer] :status Invoice payment status.
+      # @option options [String] :search Filter by contact_name or reference (not case sensitive)
+      # @option options [String, #strftime] :from_date Either a string formatted as 'dd/mm/yyyy' or an object which responds to strftime
+      # @option options [String, #strftime] :to_date Either a string formatted as 'dd/mm/yyyy' or an object which responds to strftime
+      # @option options [Integer] :start_index The start index in pagination to begin from.
+      # @return [Array<Invoice>] A list of all sales_invoices. Each invoice is a Hashie.
+      # @example Get all sales invoices
+      #   SageOne.sales_invoices
+      def sales_invoices(options={})
+        get("sales_invoices", options)
+      end
+
+      # Create a sales invoice
+      # @param options [Hash] A customizable set of options. Note that you don't have to wrap these,
+      #                       i.e. { sales_invoice: {options} }, just pass in the options hash
+      # @option options [String, #strftime] :date The invoice date either as a dd/mm/yyyy-formatted string or any object that responds to strftime
+      # @option options [Integer] :contact_id The ID of the contact associated with the sales invoice. This must be a customer (contact_type 1).
+      # @option options [String] :contact_name The name of the contact associated with the invoice. This should be the contact[name_and_company_name] from the ID of the specified contact.
+      # @option options [String] :main_address  The address where the invoice is to be sent.
+      # @option options [Integer] :carriage_tax_code_id The ID of the tax_rate if sales_invoice[carriage] is supplied.
+      # @option options [Array<Hash>] :line_items_attributes An array of line items. Each Hash requires:
+      #                               *  <b>:unit_price</b>        (<tt>Float</tt>) The unit cost of the line item.
+      #                               *  <b>:quantity</b>          (<tt>Float</tt>) The number of units on the specified line item.
+      #                               *  <b>:description</b>       (<tt>String</tt>) The description of the specified line item, maximum 60 characters.
+      #                               *  <b>:tax_code_id</b>       (<tt>Integer</tt>) The ID of the tax_rate for the item line.
+      #                               *  <b>:ledger_account_id</b> (<tt>Integer</tt>) The ID of the income_type.
+      # @return [Invoice] A Hashie of the created invoice
+      # @example Create a sales invoice:
+      #     SageOne.create_sales_invoice({
+      #       date: Time.now
+      #       contact_id: 654
+      #       contact_name: "Dave Regis"
+      #       main_address: "Regis Enterprises, PO Box 123"
+      #       carriage_tax_code_id: 5
+      #       line_items_attributes: { unit_price: 12.34, quantity: 1.0, description: "Salmon steak", tax_code_id: 1, ledger_account_id: 987 }
+      #     })
+      def create_sales_invoice(options)
+        post('sales_invoices', sales_invoice: options)
+      end
+
+      # Retrieve a sales invoice
+      # @param id [Integer] The id of the invoice you want to retrieve.
+      # @return [Invoice] A Hashie of the requested invoice
+      # @example Load an invoice
+      #     invoice = SageOne.sales_invoice(8754)
+      def sales_invoice(id)
+        get "sales_invoices/#{id}"
+      end
+
+      # Update a sales invoice
+      # @param id [Integer] The id of the invoice you want to update.
+      # @param (see #create_sales_invoice)
+      # @option (see #create_sales_invoice)
+      # @return [Invoice] A Hashie of the updated invoice
+      def update_sales_invoice(id, options)
+        put("sales_invoices/#{id}", sales_invoice: options)
+      end
+
+      # Delete a sales invoice
+      # @param id [Integer] The id of the invoice you want to delete.
+      # @return [Invoice] A Hashie of the deleted invoice
+      # @example Delete an invoice
+      #    invoice = SageOne.delete_sales_invoice!(12)
+      def delete_sales_invoice!(id)
+        delete("sales_invoices/#{id}")
+      end
+    end
+  end
+end
+

data/lib/sage_one/client.rb

@@ -0,0 +1,33 @@
+require 'sage_one/connection'
+require 'sage_one/request'
+
+require 'sage_one/oauth'
+
+require 'sage_one/client/sales_invoices'
+require 'sage_one/client/contacts'
+
+module SageOne
+  class Client
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+
+    # Creates an instance of Client configured with
+    # the current SageOne::Configuration options.
+    # Pass in a hash of any valid options to override
+    # them for this instance.
+    #
+    # @see SageOne::Configuration::VALID_OPTIONS_KEYS
+    #   SageOne::Configuration::VALID_OPTIONS_KEYS
+    def initialize(options={})
+      options = SageOne.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include SageOne::Connection
+    include SageOne::Request
+    include SageOne::OAuth
+    include SageOne::Client::SalesInvoices
+    include SageOne::Client::Contacts
+  end
+end