invoicexpress 0.0.0

data/lib/invoicexpress/client/sequences.rb

@@ -0,0 +1,71 @@
+module Invoicexpress
+  class Client
+    module Sequences
+
+      # Returns all your sequences.
+      #
+      # @return [Array<Invoicexpress::Models::Sequence>] An array with all the sequences
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def sequences(options = {})
+        params = { :klass => Invoicexpress::Models::Sequence }
+
+        get("sequences.xml", params.merge(options))
+      end
+
+      # Returns a specific sequence. 
+      #
+      # @param sequence [Invoicexpress::Models::Sequence, String] The sequence or sequence ID
+      # @return Invoicexpress::Models::Sequence The sequence
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the sequence doesn't exist
+      def sequence(sequence, options={})
+        params = { :klass => Invoicexpress::Models::Sequence }
+
+        get("sequences/#{id_from_sequence(sequence)}.xml", params.merge(options))
+      end
+
+      # Creates a new sequence.
+      #
+      # @param sequence [Invoicexpress::Models::Sequence] The sequence to create
+      # @return Invoicexpress::Models::Sequence The sequence
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def create_sequence(sequence, options={})
+        raise(ArgumentError, "sequence has the wrong type") unless sequence.is_a?(Invoicexpress::Models::Sequence)
+
+        params = { :klass => Invoicexpress::Models::Sequence, :body => sequence }
+        post("sequences.xml", params.merge(options))
+      end
+
+      # Updates a specific sequence.
+      # Only sequences with no finalized invoices can be updated.
+      #
+      # @param sequence [Invoicexpress::Models::Sequence] The sequence to update
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the sequence doesn't exist
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def update_sequence(sequence, options={})
+        raise(ArgumentError, "sequence has the wrong type") unless sequence.is_a?(Invoicexpress::Models::Sequence)
+        if !sequence.id
+          raise ArgumentError, "Sequence ID is required"
+        end
+        params = { :klass => Invoicexpress::Models::Sequence, :body => sequence }
+        put("sequences/#{sequence.id}.xml", params.merge(options))
+      end
+
+      private
+      def id_from_sequence(item)
+        if item.is_a?(Invoicexpress::Models::Sequence)
+          item.id
+        elsif item.is_a?(String)
+          item
+        elsif item.is_a?(Integer)
+          item.to_s
+        else
+          raise ArgumentError, "Cannot get sequence id from #{item}"
+        end
+      end
+
+    end
+  end
+end

data/lib/invoicexpress/client/simplified_invoices.rb

@@ -0,0 +1,130 @@
+require 'invoicexpress/models'
+
+module Invoicexpress
+  class Client
+    module SimplifiedInvoices
+      
+      # Returns all your simplified invoices
+      #
+      # @option options [Integer] page (1) You can ask a specific page of simplified invoices
+      #
+      # @return [Invoicexpress::Models::SimplifiedInvoices] A struct with results (pagination) and all the simplified invoices
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def simplified_invoices(options={})
+        params = { :page => 1, :klass => Invoicexpress::Models::SimplifiedInvoice }
+
+        get("simplified_invoices.xml", params.merge(options))
+      end
+
+
+
+      # Returns all the information about a simplified invoice:
+      # - Basic information (date, status, sequence number)
+      # - Client
+      # - Document items
+      # - Document timeline
+      # Document timeline is composed by:
+      # - Date, time and the user who created it
+      # - Type of the event
+      # The complete list of timeline events is:
+      # - create
+      # - edited
+      # - send_email
+      # - canceled
+      # - deleted
+      # - settled
+      # - second_copy
+      # - archived
+      # - unarchived
+      # - comment
+      #
+      # @param simplified_invoice_id [String] Requested simplified invoice id
+      # @return [Invoicexpress::Models::SimplifiedInvoice] The requested simplified invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the simplified_invoice doesn't exist
+      def simplified_invoice(simplified_invoice_id, options={})
+        params = { :klass => Invoicexpress::Models::SimplifiedInvoice }
+
+        get("simplified_invoices/#{simplified_invoice_id}.xml", params.merge(options))
+      end
+
+      # Creates a new simplified invoice. Also allows to create a new client and/or new items in the same request.
+      # If the client name does not exist a new one is created.
+      # If items do not exist with the given names, new ones will be created.
+      # If item name  already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applyed to that item.
+      # Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items(IVA 0%)
+      #
+      # @param simplified_invoice [Invoicexpress::Models::SimplifiedInvoice] The simplified invoice to create
+      # @return [Invoicexpress::Models::SimplifiedInvoice] The created simplified invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def create_simplified_invoice(simplified_invoice, options={})
+        raise(ArgumentError, "simplified invoice has the wrong type") unless simplified_invoice.is_a?(Invoicexpress::Models::SimplifiedInvoice)
+
+        params = { :klass => Invoicexpress::Models::SimplifiedInvoice, :body  => simplified_invoice }
+        post("simplified_invoices.xml", params.merge(options))
+      end
+
+      # Updates a simplified invoice
+      # It also allows you to create a new client and/or items in the same request.
+      # If the client name does not exist a new client is created.
+      # Regarding item taxes, if the tax name is not found, no tax will be applied to that item.
+      # If item does not exist with the given name, a new one will be created.
+      # If item exists it will be updated with the new values
+      # Be careful when updating the document items, any missing items from the original document will be deleted.
+      #
+      # @param simplified_invoice [Invoicexpress::Models::SimplifiedInvoice] The cash simplified invoice to update
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the simplified invoice doesn't exist
+      def update_simplified_invoice(simplified_invoice, options={})
+        raise(ArgumentError, "simplified invoice has the wrong type") unless simplified_invoice.is_a?(Invoicexpress::Models::SimplifiedInvoice)
+        if !simplified_invoice.id
+          raise ArgumentError, "Invoice ID is required"
+        end
+        params = { :klass => Invoicexpress::Models::SimplifiedInvoice, :body => simplified_invoice.to_core }
+        put("simplified_invoices/#{simplified_invoice.id}.xml", params.merge(options))
+      end
+
+      # Changes the state of a simplified invoice.
+      # Possible state transitions:
+      # - draft to final – finalized
+      # - draft to deleted – deleted
+      # - settled to final – unsettled
+      # - final to second copy – second_copy
+      # - final or second copy to canceled – canceled
+      # - final or second copy to settled – settled
+      # Any other transitions will fail.
+      # When canceling a simplified invoice you must specify a reason.
+      #
+      # @param simplified_invoice_id [String] The simplified invoice id to change
+      # @param simplified_invoice_state [Invoicexpress::Models::InvoiceState] The new state
+      # @return [Invoicexpress::Models::SimplifiedInvoice] The updated simplified invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the simplified invoice doesn't exist
+      def update_simplified_invoice_state(simplified_invoice_id, simplified_invoice_state, options={})
+        raise(ArgumentError, "simplified invoice state has the wrong type") unless simplified_invoice_state.is_a?(Invoicexpress::Models::InvoiceState)
+
+        params = { :klass => Invoicexpress::Models::SimplifiedInvoice, :body => simplified_invoice_state }
+        put("simplified_invoices/#{simplified_invoice_id}/change-state.xml", params.merge(options))
+      end
+
+      # Sends the simplified invoice through email
+      #
+      # @param simplified_invoice_id [String] The simplified invoice id to send
+      # @param message [Invoicexpress::Models::Message] The message to send
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the simplified invoice doesn't exist
+      def simplified_invoice_mail(simplified_invoice_id, message, options={})
+        raise(ArgumentError, "message has the wrong type") unless message.is_a?(Invoicexpress::Models::Message)
+
+        params = { :body => message, :klass => Invoicexpress::Models::SimplifiedInvoice }
+        put("simplified_invoices/#{simplified_invoice_id}/email-document.xml", params.merge(options))
+      end
+
+    end
+  end
+end

data/lib/invoicexpress/client/taxes.rb

@@ -0,0 +1,82 @@
+module Invoicexpress
+  class Client
+    module Taxes
+
+      # Returns all your taxes (lol)
+      #
+      # @return [Array<Invoicexpress::Models::Tax>] An array with all your taxes
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def taxes(options = {})
+        params = { :klass => Invoicexpress::Models::Tax }
+
+        get("taxes.xml", params.merge(options))
+      end
+
+      # Returns a specific tax. 
+      #
+      # @param tax [Invoicexpress::Models::Tax, String] The tax or tax ID
+      # @return Invoicexpress::Models::Tax The tax
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the tax doesn't exist
+      def tax(tax, options={})
+        params = { :klass => Invoicexpress::Models::Tax }
+
+        get("taxes/#{id_from_tax(tax)}.xml", params.merge(options))
+      end
+
+      # Creates a tax.
+      #
+      # @param tax [Invoicexpress::Models::Tax] The tax to create
+      # @return Invoicexpress::Models::Tax The tax created
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def create_tax(tax, options={})
+        raise(ArgumentError, "tax has the wrong type") unless tax.is_a?(Invoicexpress::Models::Tax)
+
+        params = { :klass => Invoicexpress::Models::Tax, :body => tax }
+        post("taxes.xml", params.merge(options))
+      end
+
+      # Updates a tax.
+      #
+      # @param tax [Invoicexpress::Models::Tax] The tax to update
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the tax doesn't exist
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def update_tax(tax, options={})
+        raise(ArgumentError, "tax has the wrong type") unless tax.is_a?(Invoicexpress::Models::Tax)
+
+        if !tax.id
+          raise ArgumentError, "Tax ID is required"
+        end
+        params = { :klass => Invoicexpress::Models::Tax, :body => tax }
+        put("taxes/#{tax.id}.xml", params.merge(options))
+      end
+
+      # Deletes a tax.
+      #
+      # @param tax [Invoicexpress::Models::Tax, String] The tax or tax ID
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the tax doesn't exist
+      def delete_tax(tax, options={})
+        params = { :klass => Invoicexpress::Models::Tax }
+
+        delete("taxes/#{id_from_tax(tax)}.xml", params.merge(options))
+      end
+
+      private
+      def id_from_tax(item)
+        if item.is_a?(Invoicexpress::Models::Tax)
+          item.id
+        elsif item.is_a?(String)
+          item
+        elsif item.is_a?(Integer)
+          item.to_s
+        else
+          raise ArgumentError, "Cannot get tax id from #{item}"
+        end
+      end
+
+    end
+  end
+end

data/lib/invoicexpress/client/users.rb

@@ -0,0 +1,48 @@
+module Invoicexpress
+  class Client
+    module Users
+
+      # This endpoint does not require an API KEY to be acessible.
+      # Instead it requires your current login and password.
+      # Upon successful login it will return all the accounts which belong to you
+      #
+      # @param login [String] Login email
+      # @param password [String] Your password
+      # @return [Array<Invoicexpress::Models::Account>] The list of your accounts
+      # @raise Invoicexpress::Unauthorized When the login/password combination is wrong
+      def login(login, password, options={})
+        credentials = Invoicexpress::Models::Credentials.new(
+          :login => login,
+          :password => password
+        )
+
+        params = { :klass => Invoicexpress::Models::Account, :body => credentials }
+        post("login.xml", params.merge(options))
+      end
+
+      # This method allows you to view your accounts.
+      #
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @return [Array<Invoicexpress::Models::Account>] The list of accounts
+      def accounts(options = {})
+        params = { :klass => Invoicexpress::Models::Account }
+        get("users/accounts.xml", params.merge(options))
+      end
+
+      # Changes the current account to the account id submitte
+      #
+      # @param account_id [String] The account ID to change to
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the account doesn't exist
+      def change_account(account_id, options={})
+        change_account_to = Invoicexpress::Models::ChangeAccountTo.new(
+          :id => account_id
+        )
+
+        params = { :klass => Invoicexpress::Models::Account, :body => change_account_to }
+        put("users/change-account.xml", params.merge(options))
+      end
+
+    end
+  end
+end

data/lib/invoicexpress/configuration.rb

@@ -0,0 +1,51 @@
+require 'faraday'
+require 'invoicexpress/version'
+
+module Invoicexpress
+  module Configuration
+    VALID_OPTIONS_KEYS = [
+      :adapter,
+      :faraday_config_block,
+      :api_endpoint,
+      :screen_name,
+      :proxy,
+      :api_key,
+      :user_agent
+    ].freeze
+
+    DEFAULT_ADAPTER = Faraday.default_adapter
+    DEFAULT_API_ENDPOINT = ENV['INVOICEXPRESS_API_ENDPOINT'] || 'https://%s.invoicexpress.net/'
+    DEFAULT_USER_AGENT = "Invoicexpress Ruby Gem #{Invoicexpress::VERSION}".freeze
+
+    attr_accessor(*VALID_OPTIONS_KEYS)
+
+    def self.extended(base)
+      base.reset
+    end
+    
+    def configure
+      yield self
+    end
+
+    def options
+      VALID_OPTIONS_KEYS.inject({}) { |o,k| o.merge!(k => send(k)) }
+    end
+
+    def api_endpoint=(value)
+      @api_endpoint = File.join(value, "")
+    end
+
+    def faraday_config(&block)
+      @faraday_config_block = block
+    end
+
+    def reset
+      self.adapter      = DEFAULT_ADAPTER
+      self.api_endpoint = DEFAULT_API_ENDPOINT
+      self.user_agent   = DEFAULT_USER_AGENT
+      self.api_key      = nil
+      self.screen_name  = nil
+      self.proxy        = nil
+    end
+  end
+end

data/lib/invoicexpress/connection.rb

@@ -0,0 +1,40 @@
+require 'faraday_middleware'
+require 'faraday/response/parse_xml'
+require 'faraday/response/raise_invoicexpress_errors'
+
+module Invoicexpress
+  # @private
+  module Connection
+    private
+
+    def connection(options={})
+      klass = options.delete(:klass)
+
+      options = {
+        :raw => false,
+        :ssl => { :verify => false }
+      }.merge(options)
+
+      if !proxy.nil?
+        options.merge!(:proxy => proxy)
+      end
+
+      options.merge!(:params => authentication)
+
+      connection = Faraday.new(options) do |builder|
+        builder.request :url_encoded
+
+        builder.use FaradayMiddleware::FollowRedirects
+        builder.use Faraday::Response::ParseXML, klass
+        builder.use Faraday::Response::RaiseInvoicexpressErrors
+
+        faraday_config_block.call(builder) if faraday_config_block
+        builder.adapter *adapter
+      end
+
+      connection.headers[:user_agent] = user_agent
+      connection
+    end
+
+  end
+end

data/lib/invoicexpress/error.rb

@@ -0,0 +1,68 @@
+require 'happymapper'
+
+module Invoicexpress
+  module Models
+    class Errors
+      include HappyMapper
+
+      has_many :error, String
+      alias :errors :error
+    end
+  end
+
+  # Custom error class for rescuing from all Invoicexpress errors
+  #
+  class Error < StandardError
+    attr_accessor :messages
+
+    def initialize(response=nil)
+      @response = response
+      @messages = []
+
+      super(build_error_message)
+    end
+
+    def response_body
+      @response_body ||=
+        if (body = @response[:body]) && !body.empty?
+          if body.is_a?(String) and body.start_with?("<")
+            Invoicexpress::Models::Errors.parse(body)
+          else
+            body
+          end
+        else
+          nil
+        end
+    end
+
+    private
+
+    def build_error_message
+      return nil  if @response.nil?
+
+      message = if response_body
+        if response_body.respond_to?(:errors)
+          ": " + response_body.errors.join(", ")
+        else
+          ": " + response_body
+        end
+      else
+        ''
+      end
+
+      "#{@response[:method].to_s.upcase} #{@response[:url].to_s}: #{@response[:status]}#{message}"
+    end
+  end
+
+  # Raised when Invoicexpress returns a 401 HTTP status code
+  class Unauthorized < Error; end
+
+  # Raised when Invoicexpress returns a 404 HTTP status code
+  class NotFound < Error; end
+
+  # Raised when Invoicexpress returns a 422 HTTP status code
+  class UnprocessableEntity < Error; end
+
+  # Raised when Invoicexpress server goes dark (500 HTTP status code)
+  class InternalServerError < Error; end
+end