billomat 0.2.0 → 0.3.0

data/lib/billomat/actions/complete.rb

@@ -2,14 +2,12 @@
 
 module Billomat
   module Actions
-    ##
-    # Completes an invoice by calling the /complete path on a resource
+    # Completes an invoice by calling the /complete path on a resource.
     class Complete
-      ##
-      # Returns a Complete object
+      # Returns a Complete object.
       #
-      # @param [String] invoice_id The ID of the invoice
-      # @param [Hash] opts The options for this request
+      # @param invoice_id [String] the ID of the invoice
+      # @param opts [Hash] the options for this request
       # @return [Billomat::Actions::Complete]
       #
       # @example
@@ -19,8 +17,7 @@ module Billomat
         @opts = opts
       end
 
-      ##
-      # Calls the gateway
+      # Calls the gateway.
       #
       # @return [TrueClass]
       def call
@@ -29,15 +26,14 @@ module Billomat
         true
       end
 
-      ##
-      # The given options have to be wrapped
+      # The given options have to be wrapped.
       #
-      # @return [Hash] The payload for the complete request
+      # @return [Hash] the payload for the complete request
       def wrapped_data
         { complete: @opts }
       end
 
-      # @return [String] The complete path with the invoice_id
+      # @return [String] the complete path with the invoice_id
       def path
         "/invoices/#{@invoice_id}/complete"
       end

data/lib/billomat/actions/email.rb

@@ -2,25 +2,22 @@
 
 module Billomat
   module Actions
-    ##
     # This actions sends an invoice email.
     # Recipients must be passed like this:
-    # { recipients: { to: 'bob@example.org' } }
+    #   { 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
-      #
+      # @param invoice_id [String] the invoice ID
+      # @param opts [Hash] the options for this action
       # @return [Billomat::Actions::Email]
       def initialize(invoice_id, opts = {})
         @invoice_id = invoice_id
         @opts = opts
       end
 
-      ##
-      # Calls the gateway
+      # Calls the gateway.
       #
       # @return [TrueClass]
       def call
@@ -29,15 +26,14 @@ module Billomat
         true
       end
 
-      ##
       # Wraps the options
       #
-      # @return [Hash] The wrapped email options
+      # @return [Hash] the wrapped email options
       def wrapped_data
         { email: @opts }
       end
 
-      # @return [String] The path for the email action
+      # @return [String] the path for the email action
       def path
         "/invoices/#{@invoice_id}/email"
       end

data/lib/billomat/actions/pdf.rb

@@ -2,21 +2,18 @@
 
 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
-      #
+      # @param invoice_id [String] the invoice ID
+      # @param opts [Hash] the options for this action
       # @return [Billomat::Actions::Pdf]
       def initialize(invoice_id, opts = {})
         @invoice_id = invoice_id
         @opts = opts
       end
 
-      ##
-      # Calls the gateway
+      # Calls the gateway.
       #
       # @return [TrueClass]
       def call
@@ -24,10 +21,7 @@ module Billomat
         resp['pdf']
       end
 
-      ##
-      # Wraps the options
-      #
-      # @return [Hash] The wrapped email options
+      # @return [String] the path for the PDF action
       def path
         "/invoices/#{@invoice_id}/pdf"
       end

data/lib/billomat/actions/uncancel.rb

@@ -2,21 +2,18 @@
 
 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
-      #
+      # @param invoice_id [String] the invoice ID
       # @return [Billomat::Actions::Uncancel]
       def initialize(invoice_id)
         @invoice_id = invoice_id
       end
 
-      ##
-      # Calls the gateway
+      # Calls the gateway.
       #
       # @return [TrueClass]
       def call
@@ -25,7 +22,7 @@ module Billomat
         true
       end
 
-      # @return [String] The path for the uncancel action
+      # @return [String] the path for the uncancel action
       def path
         "/invoices/#{@invoice_id}/uncancel"
       end

data/lib/billomat/actions.rb

@@ -7,7 +7,6 @@ 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

data/lib/billomat/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Billomat
+  # The +billomat+ gem configuration.
   class Configuration
     attr_accessor :api_key, :subdomain, :timeout, :app_id, :app_secret
   end

data/lib/billomat/gateway.rb

@@ -4,16 +4,32 @@ require 'rest-client'
 require 'json'
 
 module Billomat
-  ##
-  # Raised if something goes wrong during an API call
-  class GatewayError < StandardError; end
+  # Raised if something goes wrong during an API call.
+  class GatewayError < StandardError
+    attr_reader :original_exception
 
-  ##
-  # This class can be used by the gem to communicate with the API
+    # Create a new GatewayError from a RestClient exception.
+    #
+    # @param original_exception [RestClient::Exception] the original exception
+    def initialize(original_exception)
+      # Extract the error from the response if it is present. If no error
+      # could be extracted, use the whole body
+      body = original_exception.response&.body
+      response_error = JSON.parse(body).dig('errors', 'error') || body if body
+
+      # Use the default message and append our detailed error
+      message = original_exception.default_message
+      message += " ('#{response_error}')" if response_error
+
+      super(message)
+      @original_exception = original_exception
+    end
+  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
@@ -29,29 +45,33 @@ module Billomat
       @body     = body
     end
 
-    ##
-    # Executes the API call
-    # @return [Hash] The response body
+    # Executes the API call and parse the response.
+    #
+    # @return [Hash] the response body
     def run
       resp = response
 
-      raise GatewayError, resp.body if resp.code > 299
       return nil if resp.body.empty?
 
       JSON.parse(resp.body)
+    rescue RestClient::Exception => e
+      raise GatewayError, e
     end
 
+    # Executes the API call and return the response.
+    #
+    # @return [RestClient::Response] the API response
     def response
       RestClient::Request.execute(
-        method:   method,
-        url:      url,
-        timeout:  timeout,
-        headers:  headers,
-        payload:  body.to_json
+        method: method,
+        url: url,
+        timeout: timeout,
+        headers: headers,
+        payload: body.to_json
       )
     end
 
-    # @return [String] The complete URL for the request
+    # @return [String] the complete URL for the request
     def url
       "https://#{config.subdomain}.billomat.net/api#{path}"
     end
@@ -61,18 +81,18 @@ module Billomat
       config.timeout || 5
     end
 
-    # @return [Hash] The headers for the request.
+    # @return [Hash] the headers for the request
     def headers
       {
-        'Accept'           => 'application/json',
-        'Content-Type'     => 'application/json',
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
         'X-BillomatApiKey' => config.api_key,
-        'X-AppId'          => config.app_id,
-        'X-AppSecret'      => config.app_secret
+        'X-AppId' => config.app_id,
+        'X-AppSecret' => config.app_secret
       }.reject { |_, val| val.nil? }
     end
 
-    # @return [Billomat::Configuration] The global gem configuration
+    # @return [Billomat::Configuration] the global gem configuration
     #
     # :reek:UtilityFunction because it's a shorthand
     def config

data/lib/billomat/models/base.rb

@@ -4,50 +4,49 @@ 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
+      # 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
+      # @param id [String] 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
+      # Allows to query for a record.
       #
-      # @param [Hash] hash The query parameters
-      # @return [Array<Billomat::Models::Base>] The found records
+      # @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
+      # Initializes a new model.
       #
-      # @param [Hash] data The attributes of the object
-      # @return [Billomat::Models::Base] The record as an object
+      # @param data [Hash] 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.nil?
+
         update
       end
+      alias save! save
 
       # @return [TrueClass]
       def create
@@ -59,6 +58,7 @@ module Billomat
 
         true
       end
+      alias create! create
 
       # @return [TrueClass]
       def update
@@ -68,6 +68,7 @@ module Billomat
 
         true
       end
+      alias update! update
 
       # @return [TrueClass]
       def delete
@@ -76,52 +77,50 @@ module Billomat
 
         true
       end
+      alias delete! delete
 
-      # @return [String, nil] The object's ID
+      # @return [String, nil] the object's ID
       def id
         @data['id'] || nil
       end
 
-      ##
-      # Wraps the data so the API accepts the request
+      # Wraps the data so the API accepts the request.
       #
       # @example
       #   some_invoice.wrapped_data
       #   #=> { "invoice" => { "id" => "12345"  } }
       #
-      # @return [Hash] The wrapped data
+      # @return [Hash] the wrapped data
       def wrapped_data
         { self.class.resource_name => @data.to_h }
       end
 
-      ##
-      # Returns the object with the right JSON structure
+      # Returns the object with the right JSON structure.
       #
-      # @return [Hash] The objects data
+      # @return [Hash] the objects data
       def as_json(_options = nil)
         @data.to_h
       end
 
-      ##
-      # All values in the @data hash can be accessed like a 'normal' method
+      # 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)
+        return @data[method] if @data.to_h.key?(method)
+
         super
       end
 
-      ##
-      # Necessary for method_missing
+      # 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
+        @data.to_h.key?(method.to_s) || super
       end
     end
   end

data/lib/billomat/models/client.rb

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

data/lib/billomat/models/contact.rb

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

data/lib/billomat/models/credit_note.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Billomat
+  module Models
+    # Representation of the credit note resource
+    class CreditNote < Base
+      # @return [String] the resource's base path
+      def self.base_path
+        '/credit-notes'
+      end
+
+      # @return [String] the resource's name
+      def self.resource_name
+        'credit-note'
+      end
+    end
+  end
+end

data/lib/billomat/models/credit_note_item.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Billomat
+  module Models
+    # Representation of the credit note item resource
+    class CreditNoteItem < Base
+      # @return [String] the resource's base path
+      def self.base_path
+        '/credit-note-items'
+      end
+
+      # @return [String] the resource's name
+      def self.resource_name
+        'credit-note-item'
+      end
+    end
+  end
+end

data/lib/billomat/models/invoice.rb

@@ -2,33 +2,29 @@
 
 module Billomat
   module Models
-    ##
     # Representation of the invoice resource
     class Invoice < Base
-      # @return [String] The resource's base path
+      # @return [String] the resource's base path
       def self.base_path
         '/invoices'
       end
 
-      # @return [String] The resource's name
+      # @return [String] the resource's name
       def self.resource_name
         'invoice'
       end
 
-      ##
-      # Completes the invoice by calling the Complete action
+      # 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
+      # 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
+      # Sends the invoice as an email to the given recipient.
       #
       # @param [String] recipient The email address of the recipient
       def send_email(recipient)
@@ -37,8 +33,7 @@ module Billomat
         Billomat::Actions::Email.new(id, email_params).call
       end
 
-      ##
-      # Allows to download the invoice as an PDF
+      # 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

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

data/lib/billomat/models/invoice_payment.rb

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

data/lib/billomat/models/tag.rb

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

data/lib/billomat/models/template.rb

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

data/lib/billomat/models.rb

@@ -2,6 +2,8 @@
 
 require 'billomat/models/base'
 require 'billomat/models/client'
+require 'billomat/models/credit_note'
+require 'billomat/models/credit_note_item'
 require 'billomat/models/invoice'
 require 'billomat/models/invoice_item'
 require 'billomat/models/invoice_payment'
@@ -10,7 +12,6 @@ require 'billomat/models/tag'
 require 'billomat/models/template'
 
 module Billomat
-  ##
-  # Models represent a resource in the API, e.g. invoices, clients
+  # Models represent a resource in the API, e.g. invoices, clients.
   module Models; end
 end