billomat 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40a474e94aa0c704209fa2ebd99a4981730be955
-  data.tar.gz: efc188086b6124410a52c6d6796541a38fddb7af
+  metadata.gz: e9b1dc728272e6dca7e6fe43418c9ec7511f962b
+  data.tar.gz: a83499376d3e6aa576d4a9270d3d5f3bd3566199
 SHA512:
-  metadata.gz: 11510e2136f9f04d213b44459bb9459628c67e38d5a469b9491300ad4f68faef00f8bad55817eb4e88048f4f167aa745607062c41ac15debfeaba631cb477c08
-  data.tar.gz: cbf6cbb1066541439b77030703b2a5085f0975dbdf7a089ca46e5c0dd2ad8fb4fec789d5091af2a8b77543fa95658176a95cb82ccc41de2533a6e7bad99b0102
+  metadata.gz: 4387bcef030751f0147c14469d0b25fc332266c0462be814396ba749ff8ba51c2dd474437d7946d6069ca20c732f516a11bfead7fa31d69b3a4e405b4f5213ca
+  data.tar.gz: 7502cfd88d175ed62aa57be385c99dc00b07a03cb49f97cfed3ab6f71214944e9cb3572ee03da6ee5b43102394020a90028a993629fa589bedd01d7e00873d5e

data/.travis.yml

@@ -1,5 +1,18 @@
+env:
+  global:
+    - CC_TEST_REPORTER_ID=a77802032cccc178727a1df1ff1f283a8255959f9a175f20b73b8231ca35da2f
 sudo: false
 language: ruby
 rvm:
-  - 2.4.1
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
 before_install: gem install bundler -v 1.15.1
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/README.md

@@ -1,5 +1,7 @@
 # Billomat
 [![Build Status](https://travis-ci.org/hausgold/billomat.svg?branch=master)](https://travis-ci.org/hausgold/billomat)
+[![Maintainability](https://api.codeclimate.com/v1/badges/49baf848f42a2e5b95db/maintainability)](https://codeclimate.com/github/hausgold/billomat/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/49baf848f42a2e5b95db/test_coverage)](https://codeclimate.com/github/hausgold/billomat/test_coverage)
 
 This gem provides a Ruby API for [billomat.com](https://billomat.com) - an online accounting service.
 
@@ -13,11 +15,15 @@ gem 'billomat'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install billomat
+```bash
+$ gem install billomat
+```
 
 ## Usage
 
@@ -25,7 +31,7 @@ Or install it yourself as:
 
 The configuration takes two settings: `api_key` and `subdomain`. The latter is e.g. the name of your organization.
 
-```
+```ruby
 Billomat.configure do |config|
   config.subdomain = 'your-company'
   config.api_key   = 'a3b148a61cb642389b4f9953f6233f20'
@@ -36,7 +42,7 @@ end
 
 Currently there is basic support for the models `Invoice`, `Client`, `InvoicePayment`, `InvoiceItem`
 
-```
+```ruby
 Billomat::Models::Invoice.where(invoice_number: 'RE1234')
 => [#<Billomat::Models::Invoice:0x005574b58d6510 ...]
 
@@ -51,7 +57,6 @@ client.delete
 => true
 ```
 
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/billomat/actions/cancel.rb

@@ -2,17 +2,26 @@
 
 module Billomat
   module Actions
+    ##
+    # This actions cancels an invoice
     class Cancel
+      # @param [String] invoice_id The invoice ID
+      # @return [Billomat::Actions::Cancel]
       def initialize(invoice_id)
         @invoice_id = invoice_id
       end
 
+      ##
+      # Calls the gateway
+      #
+      # @return [TrueClass]
       def call
         Billomat::Gateway.new(:put, path).run
 
         true
       end
 
+      # @return [String] The cancel path with the invoice_id
       def path
         "/invoices/#{@invoice_id}/cancel"
       end

data/lib/billomat/actions/complete.rb

@@ -2,22 +2,42 @@
 
 module Billomat
   module Actions
+    ##
+    # Completes an invoice by calling the /complete path on a resource
     class Complete
+      ##
+      # Returns a Complete object
+      #
+      # @param [String] invoice_id The ID of the invoice
+      # @param [Hash] opts The options for this request
+      # @return [Billomat::Actions::Complete]
+      #
+      # @example
+      #   Billomat::Actions::Complete('12345', { template_id: '10231' })
       def initialize(invoice_id, opts = {})
         @invoice_id = invoice_id
         @opts = opts
       end
 
+      ##
+      # Calls the gateway
+      #
+      # @return [TrueClass]
       def call
         Billomat::Gateway.new(:put, path, wrapped_data).run
 
         true
       end
 
+      ##
+      # The given options have to be wrapped
+      #
+      # @return [Hash] The payload for the complete request
       def wrapped_data
         { complete: @opts }
       end
 
+      # @return [String] The complete path with the invoice_id
       def path
         "/invoices/#{@invoice_id}/complete"
       end

data/lib/billomat/actions/email.rb

@@ -1,27 +1,43 @@
 # frozen_string_literal: true
 
-# This actions sends an invoice email
-# Recipients must be passed like this:
-# { recipients: { to: 'bob@example.org' } }
-
 module Billomat
   module Actions
+    ##
+    # This actions sends an invoice email.
+    # Recipients must be passed like this:
+    # { recipients: { to: 'bob@example.org' } }
+    #
+    # @example
+    #   Billomat::Actions::Email.new('1235', { recipiens: { to: 'a@b.org' } })
     class Email
+      # @param [String] invoice_id The invoice ID
+      # @param [Hash] opts The options for this action
+      #
+      # @return [Billomat::Actions::Email]
       def initialize(invoice_id, opts = {})
         @invoice_id = invoice_id
         @opts = opts
       end
 
+      ##
+      # Calls the gateway
+      #
+      # @return [TrueClass]
       def call
         Billomat::Gateway.new(:post, path, wrapped_data).run
 
         true
       end
 
+      ##
+      # Wraps the options
+      #
+      # @return [Hash] The wrapped email options
       def wrapped_data
         { email: @opts }
       end
 
+      # @return [String] The path for the email action
       def path
         "/invoices/#{@invoice_id}/email"
       end

data/lib/billomat/actions/pdf.rb

@@ -2,17 +2,32 @@
 
 module Billomat
   module Actions
+    ##
+    # This class allows to download the invoice as a pdf.
+    # The PDF comes in a base64 encoded string in the response body.
     class Pdf
+      # @param [String] invoice_id The invoice ID
+      # @param [Hash] opts The options for this action
+      #
+      # @return [Billomat::Actions::Pdf]
       def initialize(invoice_id, opts = {})
         @invoice_id = invoice_id
         @opts = opts
       end
 
+      ##
+      # Calls the gateway
+      #
+      # @return [TrueClass]
       def call
         resp = Billomat::Gateway.new(:get, path).run
         resp['pdf']
       end
 
+      ##
+      # Wraps the options
+      #
+      # @return [Hash] The wrapped email options
       def path
         "/invoices/#{@invoice_id}/pdf"
       end

data/lib/billomat/actions/uncancel.rb

@@ -2,17 +2,30 @@
 
 module Billomat
   module Actions
+    ##
+    # This actions uncancels an canceld invoice.
+    #
+    # @example
+    #   Billomat::Actions::Uncancel.new('1235')
     class Uncancel
+      # @param [String] invoice_id The invoice ID
+      #
+      # @return [Billomat::Actions::Uncancel]
       def initialize(invoice_id)
         @invoice_id = invoice_id
       end
 
+      ##
+      # Calls the gateway
+      #
+      # @return [TrueClass]
       def call
         Billomat::Gateway.new(:put, path).run
 
         true
       end
 
+      # @return [String] The path for the uncancel action
       def path
         "/invoices/#{@invoice_id}/uncancel"
       end

data/lib/billomat/actions.rb

@@ -7,5 +7,8 @@ require 'billomat/actions/cancel'
 require 'billomat/actions/uncancel'
 
 module Billomat
+  ##
+  # Actions are API calls that do not directly represent a resource.
+  # They are mostly non-RESTful actions that are called on a resources.
   module Actions; end
 end

data/lib/billomat/gateway.rb

@@ -4,17 +4,34 @@ require 'rest-client'
 require 'json'
 
 module Billomat
+  ##
+  # Raised if something goes wrong during an API call
   class GatewayError < StandardError; end
 
+  ##
+  # This class can be used by the gem to communicate with the API
   class Gateway
     attr_reader :method, :path, :body
 
+    ##
+    # Creates a new Gateway
+    #
+    # @param [Symbol] method The HTTP verb
+    # @param [String] path The path of the resource
+    # @param [Hash] body The payload for the request
+    #
+    # @example
+    #   Billomat::Gateway.new(:get, '/invoices')
+    #   Billomat::Gateway.new(:post, '/invoices', { 'invoice' => { ... } })
     def initialize(method, path, body = {})
       @method   = method.to_sym
       @path     = path
       @body     = body
     end
 
+    ##
+    # Executes the API call
+    # @return [Hash] The response body
     def run
       resp = RestClient::Request.execute(
         method:   method,
@@ -30,14 +47,17 @@ module Billomat
       JSON.parse(resp.body)
     end
 
+    # @return [String] The complete URL for the request
     def url
       "https://#{config.subdomain}.billomat.net/api#{path}"
     end
 
+    # @return [Integer]
     def timeout
       5
     end
 
+    # @return [Hash] The headers for the request.
     def headers
       {
         'Accept'           => 'application/json',
@@ -46,6 +66,7 @@ module Billomat
       }
     end
 
+    # @return [Billomat::Configuration] The global gem configuration
     def config
       Billomat.configuration
     end

data/lib/billomat/models/base.rb

@@ -4,28 +4,52 @@ require 'ostruct'
 
 module Billomat
   module Models
+    ##
+    # This class is the base for all other models (resources).
+    # It handles the communication with the gateway to talk to the API.
     class Base
       attr_accessor :data
 
+      ##
+      # Tries to find the resource for the given id
+      #
+      # @param [String] id The resource id
+      # @return [Billomat::Models::Base, nil] The found resource or nil
       def self.find(id)
         return nil if id.nil?
         resp = Billomat::Gateway.new(:get, "#{base_path}/#{id}").run
         new(resp[resource_name])
       end
 
+      ##
+      # Allows to query for a record
+      #
+      # @param [Hash] hash The query parameters
+      # @return [Array<Billomat::Models::Base>] The found records
       def self.where(hash = {})
         Billomat::Search.new(self, hash).run
       end
 
+      ##
+      # Initializes a new model
+      #
+      # @param [Hash] data The attributes of the object
+      # @return [Billomat::Models::Base] The record as an object
       def initialize(data = {})
         @data = OpenStruct.new(data)
       end
 
+      ##
+      # Persists the current object in the API.
+      # When record is new it calls create, otherwise it saves the object.
+      #
+      # @return [TrueClass]
       def save
         return create if id.blank?
         update
       end
 
+      # @return [TrueClass]
       def create
         resp = Billomat::Gateway.new(
           :post, self.class.base_path, wrapped_data
@@ -36,6 +60,7 @@ module Billomat
         true
       end
 
+      # @return [TrueClass]
       def update
         path = "#{self.class.base_path}/#{id}"
         resp = Billomat::Gateway.new(:put, path, wrapped_data).run
@@ -44,6 +69,7 @@ module Billomat
         true
       end
 
+      # @return [TrueClass]
       def delete
         path = "#{self.class.base_path}/#{id}"
         Billomat::Gateway.new(:delete, path).run
@@ -51,19 +77,41 @@ module Billomat
         true
       end
 
+      # @return [String, nil] The object's ID
       def id
         @data['id'] || nil
       end
 
+      ##
+      # Wraps the data so the API accepts the request
+      #
+      # @example
+      #   some_invoice.wrapped_data
+      #   #=> { "invoice" => { "id" => "12345"  } }
+      #
+      # @return [Hash] The wrapped data
       def wrapped_data
         { self.class.resource_name => @data.to_h }
       end
 
+      ##
+      # All values in the @data hash can be accessed like a 'normal' method
+      #
+      # @example
+      #   invoice = Billomat::Models::Invoice.new(invoice_number: '123')
+      #   invoice.invoice_number
+      #   #=> '123'
       def method_missing(method, *args, &block)
         return @data[method] if @data.to_h.keys.include?(method)
         super
       end
 
+      ##
+      # Necessary for method_missing
+      #
+      # @param [Symbol] method The method name
+      # @param [TrueClass, FalseClass] include_privat
+      # @return [TrueClass, FalseClass]
       def respond_to_missing?(method, include_privat = false)
         @data.to_h.keys.include?(method.to_s) || super
       end

data/lib/billomat/models/client.rb

@@ -2,11 +2,15 @@
 
 module Billomat
   module Models
+    ##
+    # Representation of the client resource
     class Client < Base
+      # @return [String] The resource's base path
       def self.base_path
         '/clients'
       end
 
+      # @return [String] The resource's name
       def self.resource_name
         'client'
       end

data/lib/billomat/models/invoice.rb

@@ -2,29 +2,43 @@
 
 module Billomat
   module Models
+    ##
+    # Representation of the invoice resource
     class Invoice < Base
+      # @return [String] The resource's base path
       def self.base_path
         '/invoices'
       end
 
+      # @return [String] The resource's name
       def self.resource_name
         'invoice'
       end
 
+      ##
+      # Completes the invoice by calling the Complete action
       def complete!
         Billomat::Actions::Complete.new(id).call
       end
 
+      ##
+      # Cancels the invoice by calling the Cancel action
       def cancel!
         Billomat::Actions::Cancel.new(id).call
       end
 
+      ##
+      # Sends the invoice as an email to the given recipient
+      #
+      # @param [String] recipient The email address of the recipient
       def send_email(recipient)
         email_params = { recipients: { to: recipient } }
 
         Billomat::Actions::Email.new(id, email_params).call
       end
 
+      ##
+      # Allows to download the invoice as an PDF
       def to_pdf
         Billomat::Actions::Pdf.new(id).call
       end

data/lib/billomat/models/invoice_item.rb

@@ -2,11 +2,15 @@
 
 module Billomat
   module Models
+    ##
+    # Representation of the invoice item resource
     class InvoiceItem < Base
+      # @return [String] The resource's base path
       def self.base_path
         '/invoice-items'
       end
 
+      # @return [String] The resource's name
       def self.resource_name
         'invoice-item'
       end

data/lib/billomat/models/invoice_payment.rb

@@ -2,11 +2,15 @@
 
 module Billomat
   module Models
+    ##
+    # Representation of the invoice payment resource
     class InvoicePayment < Base
+      # @return [String] The resource's base path
       def self.base_path
         '/invoice-payments'
       end
 
+      # @return [String] The resource's name
       def self.resource_name
         'invoice-payment'
       end

data/lib/billomat/models.rb

@@ -7,5 +7,7 @@ require 'billomat/models/invoice_item'
 require 'billomat/models/invoice_payment'
 
 module Billomat
+  ##
+  # Models represent a resource in the API, e.g. invoices, clients
   module Models; end
 end

data/lib/billomat/search.rb

@@ -3,21 +3,41 @@
 require 'uri'
 
 module Billomat
+  ##
+  # This class provides the possibility to query the resources
   class Search
+    ##
+    # Creates a new search object
+    #
+    # @param [Class] resource The resource class to be queried
+    # @param [Hash] hash The query
     def initialize(resource, hash)
       @resource = resource
       @hash     = hash
     end
 
+    # @return [String] The path including the query
     def path
       "#{@resource.base_path}?#{hash_to_query}"
     end
 
+    ##
+    # Runs the query and calls the gateway
+    #
+    # @return [Array<Billomat::Model::Base>]
     def run
-      return [] if @hash.compact.empty?
+      return [] if @hash.reject { |k, v| v.nil? }.empty?
       to_array(Billomat::Gateway.new(:get, path).run)
     end
 
+    ##
+    # Corrects the response to always return an array
+    #
+    # @todo Due to a strange API behaviour we have to fix the reponse here.
+    #   This may be fixed in a new API version.
+    #
+    # @param [Hash] resp The response from the gateway
+    # @return [Array<Billomat::Model::Base>]
     def to_array(resp)
       case count(resp)
       when 0
@@ -32,10 +52,13 @@ module Billomat
       end
     end
 
+    # @return [String] The name of the resource
     def name
       @resource.resource_name
     end
 
+    # @param [Hash] resp The response from the gateway
+    # @return [Integer] The number of records found
     def count(resp)
       return 0 if resp.nil?
       resp["#{name}s"]['@total'].to_i
@@ -43,6 +66,7 @@ module Billomat
 
     private
 
+    # @return [String] The query as www encoded string
     def hash_to_query
       URI.encode_www_form(@hash)
     end

data/lib/billomat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Billomat
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/billomat.rb

@@ -7,15 +7,27 @@ require 'billomat/actions'
 require 'billomat/search'
 require 'billomat/gateway'
 
+##
+# An wrapper for the
+# <a href="https://billomat.com">Billomat</a>
+# API
 module Billomat
   class << self
     attr_writer :configuration
   end
 
+  # @return [Billomat::Configuration] The global billomat configuration
   def self.configuration
     @configuration ||= Billomat::Configuration.new
   end
 
+  # Class method to set and change the global configuration
+  #
+  # @example
+  #   Billomat.configure do |config|
+  #     config.subdomain = 'your-business-name'
+  #     config.api_key = 'a3b148a61cb642389b4f9953f6233f20'
+  #   end
   def self.configure
     yield(configuration)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: billomat
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Henning Vogt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-05 00:00:00.000000000 Z
+date: 2017-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client