fakturan_nu 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f81bdfd634d37068875813a2c43c877ed859b4fb
+  data.tar.gz: 666f324bd953f0a55e9e6af4e8bbf70ad7405036
+SHA512:
+  metadata.gz: c3591f8e8cb7cc5604029feec9e3a91b9e42a09fe302a97f8fe89aec1086abad8d30dafe9adee1163d330aeb7868210a3f9cc293af5ca9540b666f105e89194a
+  data.tar.gz: 4bd0783fff70fe74a037ee80f5a4e8df43873b6d4bb35e249775255d6cc42f789ec613386bd231d47625cd9be45c2d306d0c3d43f19b77b2c4c8d1c31738df59

data/.gitignore

@@ -0,0 +1,36 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+.DS_Store

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Imagineit AB
+
+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,121 @@
+Ruby client for the fakturan.nu API
+==============================
+
+API client in ruby for the Swedish web based invoicing software [fakturan.nu](https://www.fakturan.nu). The API is currently in Beta and may be subject to change without notice until final release.
+
+---
+
+## Installation
+
+If you're using Rails/Bundler, add this to your Gemfile:
+
+```ruby
+gem "fakturan_nu"
+```
+
+Then create an initializer in app/initializers called  ``` fakturan_nu.rb  ``` (or whatever name you choose) with the following:
+
+```ruby
+Fakturan.setup 'your api username here', 'your api key/password here'
+Fakturan.use_sandbox = true # Should be true during development/testing and false in production.
+```
+
+If you're not using Rails, just ``` require 'fakturan_nu'``` and run setup wherever you like.
+
+## Usage
+
+### General
+
+The client attempts to provide an interface similar to ActiveRecord.
+
+```ruby
+Fakturan::Product.all
+# GET "https://fakturan.nu/api/v2/products" and return an array of product objects
+
+Fakturan::Product.find(1)
+# GET "https://fakturan.nu/api/v2/products/1" and return a product object
+
+product = Fakturan::Product.create(name: "Shoes")
+# POST "https://fakturan.nu/api/v2/products" and return the saved product object
+
+product = Fakturan::Product.new(name: "Shoes")
+product.tax = 12
+product.save
+# POST "https://fakturan.nu/api/v2/products" and return the saved product object
+
+product = Fakturan::Product.find(1)
+# GET "https://fakturan.nu/api/v2/products/1" and return a product object
+product.name = "Blue suede shoes" # Update a property
+product.save
+# PUT "https://fakturan.nu/api/v2/products/1" and return the updated product object
+```
+
+### Invoices
+
+For creating invoices, a date and a client is required:
+```ruby
+invoice = Fakturan::Invoice.create(date: Date.today, client: { company: "Acme Inc" })
+# POST "https://fakturan.nu/api/v2/invoices" # Will create a new client + invoice
+
+invoice = Fakturan::Invoice.create(date: Date.today, client_id: 1)
+# POST "https://fakturan.nu/api/v2/invoices" # Will create a new invoice for client with id: 1
+
+```
+
+### Available resources and properties
+
+For a full list of resources and the properties of each type of resource, see the [api reference](https://sandbox.fakturan.nu/apidocs). 
+
+## Pagination
+
+The Fakturan.nu API paginates results. When a collection is fetched, it contains pagination information on the metadata accessor. So in order to get all results, you can do:
+
+```ruby
+products = Fakturan::Product.all # This will give you paginated results of 30 items per page by default
+products.concat(Fakturan::Product.get(products.metadata[:next])) while products.metadata[:next]
+```
+
+You can change the default number of items per page (30) by passing in the per_page parameter:
+
+```ruby
+products = Fakturan::Product.where(per_page: 100) # This will give you paginated results of 100 items per page
+products.concat(Fakturan::Product.get(products.metadata[:next])) while products.metadata[:next]
+```
+
+The maximum number of items per page allowed is 100.
+
+## Validation
+
+Errors and validation are handled much like in ActiveRecord:
+
+```ruby
+invoice = Fakturan::Invoice.new
+invoice.save # false
+invoice.errors.to_a # ["Client can't be blank", "Date can't be blank", "Date is invalid"]
+```
+
+As with ActiveRecord, the ``` save ``` and ``` create ``` methods will return ``` true ``` or ``` false ``` depending on validations, while  ``` save! ``` and ``` create! ``` will raise an error if validations fail. The error that is raised in such cases is ``` Fakturan::Error::ResourceInvalid ```.
+
+## Error handling
+
+If the server responds with an error, or if the server cannot be reached, one of the following errors will be raised:
+
+```ruby
+Fakturan::Error::AccessDenied     # http status code: 401
+Fakturan::Error::ResourceNotFound # http status code: 404
+Fakturan::Error::ConnectionFailed # http status code: 407
+Fakturan::Error::ResourceInvalid  # http status code: 422
+Fakturan::Error::ClientError      # http status code: other in the 400-499 range
+Fakturan::Error::ServerError      # http status code: other in the 500-599 range
+```
+
+These errors are all descendents of ```Fakturan::Error``` and should be caught in a begin-rescue block like so (example in a Rails-controller):
+
+```ruby
+begin
+  invoice = Fakturan::Invoice.create!
+rescue Fakturan::Error => error
+  render plain: error.message, status: error.status
+end
+```
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+task default: :test
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/*_test.rb'
+end

data/config/locales/en.yml

@@ -0,0 +1,2 @@
+en:
+	

data/fakturan_nu.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |s|
+  s.name        = 'fakturan_nu'
+  s.version     = '1.0.0'
+  s.date        = '2014-12-17'
+  s.summary     = 'A ruby client for the Fakturan.nu - API'
+  s.description = 'A ruby client for the Fakturan.nu - API. Fakturan.nu is a webbapp for billing.'
+  s.authors     = ['Jonathan Bourque Olivegren']
+  s.email       = 'jonathan@imagineit.se'
+  s.files       = `git ls-files`.split("\n") # http://www.codinginthecrease.com/news_article/show/350843?referrer_id=948927
+  s.homepage    = 'http://rubygems.org/gems/fakturan_nu'
+  s.license       = 'MIT'
+
+  s.add_dependency 'spyke',   '~> 1.8', '>= 1.8.7'
+  s.add_dependency 'faraday', '>= 0.8', '< 1.0'
+  s.add_dependency 'multi_json', '~> 1.11', '>= 1.11.0'
+  # So we can use model.errors.details before Rails 5.
+  s.add_dependency 'active_model-errors_details', '~> 1.1', '>= 1.1.1'
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'webmock'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'minitest-reporters'
+  s.add_development_dependency 'minitest-around'
+  s.add_development_dependency 'vcr'
+end

data/lib/fakturan_nu/address.rb

@@ -0,0 +1,5 @@
+module Fakturan
+  class Address < Base
+    uri nil
+  end
+end

data/lib/fakturan_nu/base.rb

@@ -0,0 +1,88 @@
+require 'fakturan_nu/error'
+
+module Fakturan
+  class Base < Spyke::Base
+    include_root_in_json false
+
+    def self.connection
+      Fakturan.connection
+    end
+
+    def self.create!(attrs = {})
+      instance = self.new(attrs)
+      instance.save!
+      return instance
+    end
+
+    def self.create(attrs = {})
+      instance = self.new(attrs)
+      instance.save
+      return instance
+    end
+
+    def save
+      errors.clear
+      super
+      return !errors.any?
+    end
+
+    def save!
+      raise Fakturan::Error::ResourceInvalid, self unless self.save
+    end
+
+    # This is an override from: https://github.com/balvig/spyke/blob/master/lib/spyke/http.rb
+    # to allow for nested errors on associated objects
+    def add_errors_to_model(errors_hash)
+      errors_hash.each do |field, field_errors|
+        ass_name, field_name = field.split(".").map(&:to_sym)
+        field_name = ass_name unless field_name
+
+        if association = self.class.reflect_on_association(ass_name) # The errors are for an associatied object
+          if association.type == Spyke::Associations::HasMany
+            field_errors.each do |new_error_hash_with_index|
+              new_error_hash_with_index.each do |index, inner_errors_hash|
+                error_attribute = inner_errors_hash.keys.first.split('.').last.to_sym
+                self.send(ass_name)[index.to_i].add_to_errors(error_attribute, inner_errors_hash.values.last)
+              end
+            end
+          else # It's a belongs_to or has_one
+            # We add the error to the associated object
+            self.send(ass_name).add_to_errors(field_name, field_errors)
+            # and then we get the errors (with generated messages) and add them to
+            # the parent (but without details, like nested_attributes works)
+            # This only makes sense on belongs_to and has_one, since it's impossible
+            # to know which object is refered to on has_many
+            self.send(ass_name).errors.each do |attribute, message|
+              attribute = "#{ass_name}.#{attribute}"
+              errors[attribute] << message
+              errors[attribute].uniq!
+            end
+          end
+        else
+          self.add_to_errors(field_name.to_sym, field_errors)
+        end
+
+      end
+    end
+
+    def add_to_errors field_name, field_errors
+      field_errors.each do |attributes|
+        attributes = attributes.symbolize_keys
+        error_name = attributes.delete(:error).to_sym
+        errors.add(field_name.to_sym, error_name, attributes)
+      end
+    end
+
+    # This is an override from: https://github.com/balvig/spyke/blob/master/lib/spyke/http.rb
+    # In order to re-raise Faraday error as Fakturan error
+    def self.request(method, path, params = {})
+      begin
+        super
+      rescue Faraday::ConnectionFailed => e
+        raise Fakturan::Error::ConnectionFailed, e.message
+      rescue Faraday::TimeoutError => e
+        raise Fakturan::Error::ConnectionFailed, e.message
+      end
+    end
+  end
+end

data/lib/fakturan_nu/client.rb

@@ -0,0 +1,19 @@
+module Fakturan
+  class Client < Base
+    uri "clients/(:id)"
+    has_many :invoices, uri: "clients/:id/invoices", foreign_key: 'id'
+    has_one :address
+
+    accepts_nested_attributes_for :address
+
+    attributes :number, :first_name, :last_name, :email, :company, :phone, :home_phone, :mobile_phone, :fax, :org_number, :private, :web, :vat_number
+
+    def address=(attrs_or_obj)
+      if attrs_or_obj.respond_to?(:each)
+        send(:address_attributes=, attrs_or_obj)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/fakturan_nu/error.rb

@@ -0,0 +1,69 @@
+require 'active_model/errors_details'
+
+# This is just to provide a set of errors with consistent scope
+# https://github.com/lostisland/faraday/blob/master/lib/faraday/error.rb
+module Fakturan
+  class Error < StandardError; end
+
+  class WithResponse < Error
+    attr_reader :response
+
+    def status
+      response[:status]
+    end
+    
+    def initialize(ex, response = nil)
+      @wrapped_exception = nil
+      @response = response
+
+      if ex.respond_to?(:backtrace) # If ex behaves like an Exception
+        super(ex.message)
+        @wrapped_exception = ex
+      elsif ex.respond_to?(:each_key) # If ex behaves like a Hash
+        super("the server responded with status #{ex[:status]} - #{ex[:body]}")
+        @response = ex
+      else
+        super(ex.to_s)
+      end
+    end
+
+    def backtrace
+      if @wrapped_exception
+        @wrapped_exception.backtrace
+      else
+        super
+      end
+    end
+
+    def inspect
+      %(#<#{self.class}>)
+    end
+  end
+
+  class ClientError      < WithResponse; end
+  class ServerError      < WithResponse; end
+  class AccessDenied     < WithResponse; end
+  class ResourceNotFound < WithResponse; end
+  class ParseError       < WithResponse; end
+
+  class ConnectionFailed < Error
+    def status; 407; end
+  end
+
+  class ResourceInvalid < Error
+    attr_reader :model
+
+    def status; 422; end
+
+    def initialize(model)
+      @model = model
+      msg = @model.errors.details #to_a.join(" ")
+      super(msg)
+    end
+  end
+
+  # This is just so that we can have Fakturan::Error be both a class and a "scope": Fakturan::Error::ResourceInvalid
+  [:WithResponse, :ClientError, :ServerError, :AccessDenied, :ResourceNotFound, :ParseError, :ConnectionFailed, :ResourceInvalid].each do |const|
+    Error.const_set(const, Fakturan.const_get(const))
+  end
+end

data/lib/fakturan_nu/invoice.rb

@@ -0,0 +1,40 @@
+module Fakturan
+  class Invoice < Base
+    uri "invoices/(:id)"
+
+    # The foreign_key decides which attribute will be used to set the id
+    belongs_to :client, uri: "clients/:id", foreign_key: 'client_id'
+    has_one :address, uri: nil
+    
+    has_many :rows, uri: nil
+
+    accepts_nested_attributes_for :rows, :address, :client
+
+    # These create getter methods on new instances, mostly for use in forms
+    attributes :number, :date, :client_id, :days, :our_reference, :your_reference, :sent, :paid, :paid_at, :interval_period, :auto_send, :recurring, :last_day_of_month, :start_recurring_from, :locale, :currency
+
+    def rows=(attrs_or_obj_array)
+      if attrs_or_obj_array.first.respond_to?(:each)
+        send(:rows_attributes=, attrs_or_obj_array)
+      else
+        super
+      end
+    end
+
+    def address=(attrs_or_obj)
+      if attrs_or_obj.respond_to?(:each)
+        send(:address_attributes=, attrs_or_obj)
+      else
+        super
+      end
+    end
+
+    def client=(attrs_or_obj)
+      if attrs_or_obj.respond_to?(:each)
+        send(:client_attributes=, attrs_or_obj)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/fakturan_nu/middleware/parse_json.rb

@@ -0,0 +1,23 @@
+module Fakturan
+  module Response
+    class ParseJSON < Faraday::Response::Middleware
+      def parse(body)
+        json = MultiJson.load(body, symbolize_keys: true)
+        res = {
+          data: json[:data],
+          metadata: json[:paging],
+          errors: json[:errors]
+        }
+        return res
+      end
+
+      def on_complete(env)
+        begin # https://github.com/lostisland/faraday/blob/master/lib/faraday/response.rb
+          env.body = parse(env.body) if env.parse_body?
+        rescue MultiJson::ParseError => exception
+          raise Fakturan::Error::ParseError, {:status => env.status, :headers => env.response_headers, :body => env.body}
+        end
+      end
+    end
+  end
+end

data/lib/fakturan_nu/middleware/raise_error.rb

@@ -0,0 +1,33 @@
+require 'fakturan_nu/error'
+
+module Fakturan
+  module Response
+    class RaiseError < Faraday::Response::Middleware
+      ClientErrorStatuses = 400...499
+      ServerErrorStatuses = 500...599
+
+      def on_complete(env)
+        case env[:status]
+        when 401
+          raise Fakturan::Error::AccessDenied, response_values(env)
+        when 404
+          raise Fakturan::Error::ResourceNotFound, response_values(env)
+        when 407
+          # mimic the behavior that we get with proxy requests with HTTPS
+          raise Faraday::ConnectionFailed, %{407 "Proxy Authentication Required "} # We raise this instead of our own ConnectionFailed error, since Faraday::ConnectionFailed will be raise on timeouts or refused connections anyway
+        when 422
+          # We don't do anything except fallback to standard behaviour in Spyke, which is to store errors on .errors and not raise an exception
+          # If an exception is desirable, then use .save! on the model instead of .save.
+        when ClientErrorStatuses
+          raise Fakturan::Error::ClientError, response_values(env)
+        when ServerErrorStatuses
+          raise Fakturan::Error::ServerError, response_values(env)
+        end
+      end
+
+      def response_values(env)
+        {:status => env.status, :headers => env.response_headers, :body => env.body}
+      end
+    end
+  end
+end

data/lib/fakturan_nu/product.rb

@@ -0,0 +1,7 @@
+module Fakturan
+  class Product < Base
+    uri 'products/(:id)'
+
+    attributes :name, :unit, :price, :tax, :product_code
+  end
+end

data/lib/fakturan_nu/row.rb

@@ -0,0 +1,7 @@
+module Fakturan
+  class Row < Base
+    uri nil
+
+    attributes :product_id, :discount, :amount, :text, :product_code, :product_name, :product_unit, :product_price, :product_tax, :text_row, :sort_order
+  end
+end

data/lib/fakturan_nu/spyke_extensions.rb

@@ -0,0 +1,24 @@
+module Spyke
+  class Collection
+    # For pagination. 
+    # Makes it possible to do ps = Fakturan::Product.all and then
+    # ps.concat(Fakturan::Product.get(ps.metadata[:next])) while ps.metadata[:next])
+    def concat ary_or_collection
+      @metadata = ary_or_collection.metadata if ary_or_collection.respond_to?(:metadata)
+      super
+    end
+  end
+
+  class Relation
+    # For pagination and more array-like behaviour.
+    # It's very tempting to add << as well, but as I recall, it didn't behave as expected
+    delegate :concat, :+, :-, to: :find_some
+  end
+
+  module Associations
+    class Builder
+      # Allows us to do reflect_on_association(ass_name).type
+      attr_accessor :type
+    end
+  end
+end

data/lib/fakturan_nu.rb

@@ -0,0 +1,87 @@
+# -*- encoding: utf-8 -*-
+require 'spyke'
+#require 'active_support/json/decoding' # if we want date-strings to be typecast as DateTimes. Can be done through Faraday-middleware too.
+require 'faraday_middleware'
+require 'multi_json'
+require 'fakturan_nu/spyke_extensions'
+require 'fakturan_nu/middleware/parse_json'
+require 'fakturan_nu/middleware/raise_error'
+
+require 'fakturan_nu/base'
+require 'fakturan_nu/address'
+require 'fakturan_nu/product'
+require 'fakturan_nu/client'
+require 'fakturan_nu/row'
+require 'fakturan_nu/invoice'
+
+I18n.load_path += Dir.glob( File.dirname(__FILE__) + "lib/locales/*.{rb,yml}" )
+
+module Fakturan
+  @use_sandbox = false
+  @api_version = 2
+
+  mattr_accessor :accept_language
+
+  def self.setup username = nil, pass = nil
+    #self.parse_json_times = true
+
+    @username, @pass = username, pass
+    self.accept_language = 'en-US'
+
+    @connection = Faraday.new(url: build_url) do |connection|
+      # Request
+      connection.request :json
+      connection.use Faraday::Request::BasicAuthentication, @username, @pass
+
+      # Response
+      connection.use Fakturan::Response::ParseJSON
+      connection.use Fakturan::Response::RaiseError
+
+      # Adapter should be last
+      connection.adapter Faraday.default_adapter
+    end
+  end
+
+  def self.connection
+    @connection
+  end
+
+  #def self.parse_json_times=(true_or_false)
+  #  ActiveSupport.parse_json_times = true_or_false
+  #end
+
+  def self.use_token_auth(token)
+    @connection.token_auth(token)
+  end
+
+  def self.use_basic_auth(username = nil, pass = nil)
+    @username, @pass = username, pass if (username && pass)
+    @connection.basic_auth(@username, @pass)
+  end
+
+  def self.use_sandbox=(true_or_false)
+    @use_sandbox = true_or_false
+    rebuild_url
+  end
+
+  def self.api_version=(version_no)
+    @api_version = version_no
+    rebuild_url
+  end
+
+  def self.url
+    @connection.url_prefix.to_s
+  end
+
+  def self.url=(new_url)
+    @connection.url_prefix = new_url
+  end
+
+  def self.build_url
+    "https://#{@use_sandbox ? 'sandbox.' : ''}fakturan.nu/api/v#{@api_version}"
+  end
+
+  def self.rebuild_url
+    self.url = self.build_url
+  end
+end

data/test/basics_test.rb

@@ -0,0 +1,26 @@
+require 'test_helper'
+VCR.turn_off!
+
+module Fakturan
+  class BasicsTest < MiniTest::Test
+
+    # They are not, but I dislike them jumping around in the output. Makes it harder to compare two test runs.
+    i_suck_and_my_tests_are_order_dependent!
+
+    def test_auth_with_token_and_back_to_basic
+      basic_auth_endpoint = stub_api_request(:get, '/clients/1').to_return(body: '{"data":{"id": 1, "name":"DCT"}}', status: 200)
+
+      token_endpoint = stub_request(:get, "http://#{BASE_URL}/clients/1")
+                       .with(headers: { authorization: "Token token=\"XYZ\""})
+                       .to_return(body: '{"data":{"id": 1, "name":"DCT"}}', status: 200)
+
+      Fakturan::Client.find(1)
+      Fakturan.use_token_auth('XYZ')
+      Fakturan::Client.find(1)
+      Fakturan.use_basic_auth
+      Fakturan::Client.find(1)
+      assert_requested basic_auth_endpoint, times: 2
+      assert_requested token_endpoint, times: 1
+    end
+  end
+end