papierkram_api_client 0.1.3 → 0.2.0

data/lib/papierkram_api/v1/business_intelligence/expenses_by_category.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module BusinessIntelligence
+      # Business Intelligence for Expenses
+      class ExpensesByCategory
+        #
+        # Calculate the expenses by category
+        #
+        # @param [Array<Hash>] expense_vouchers represents a list of expense vouchers in the format:
+        #
+        # @param [<Type>] &block <description>
+        #
+        # @return [<Type>] <description>
+        #
+        def call(expense_vouchers:, &block)
+          return {} if expense_vouchers.is_a?(Array) && expense_vouchers.empty?
+
+          validate_expense_vouchers!(expense_vouchers)
+          if block_given?
+            results(expense_vouchers, &block)
+          else
+            results(expense_vouchers)
+          end
+        end
+
+        private
+
+        def results(expense_vouchers)
+          coll = prepare_voucher_data(expense_vouchers)
+          coll = yield(coll) if block_given?
+          line_items_grouped_by_category = coll.group_by { |v| v['category'] }
+          sum_categories!(line_items_grouped_by_category)
+        end
+
+        def sum_categories!(line_items_grouped_by_category)
+          lookup_table = {}
+          line_items_grouped_by_category.each do |category_name, line_items|
+            line_items_by_creditor_lot = {}
+            line_items_by_creditor = line_items.group_by { |v| v['creditor'] }
+            sum_up_creditor!(line_items_by_creditor, line_items_by_creditor_lot)
+            build_result_lookup_table!(lookup_table, category_name, line_items, line_items_by_creditor_lot)
+          end
+          lookup_table
+        end
+
+        def sum_up_creditor!(line_items_by_creditor, line_items_by_creditor_lot)
+          line_items_by_creditor.each do |category_name, line_items|
+            line_items_by_creditor_lot[category_name] = line_items.reduce(0) do |sum, creditor|
+              sum + creditor['amount']
+            end
+          end
+          line_items_by_creditor_lot
+        end
+
+        def build_result_lookup_table!(lookup_table, category_name, line_items, line_items_by_creditor_lot)
+          lookup_table[category_name] = {
+            'amount' => line_items.reduce(0) { |sum, line_item| sum + line_item['amount'] },
+            'amount_by_creditor' => line_items_by_creditor_lot,
+            'line_items' => line_items
+          }
+        end
+
+        def prepare_voucher_data(vouchers)
+          coll = []
+          vouchers.flat_map do |voucher|
+            voucher['line_items'].each do |line_item|
+              res = line_item.merge(
+                { 'voucher_name' => voucher['name'] },
+                { 'voucher_id' => voucher['id'] },
+                'creditor' => voucher['creditor']
+              )
+              coll.push(res)
+            end
+          end
+          coll
+        end
+
+        # TODO: move to a validator class forPapierkramApi::V1::Validators::ExpenseVouchers
+        def validate_expense_vouchers!(expense_vouchers)
+          raise ArgumentError, 'expense_vouchers must be an Array' unless expense_vouchers.is_a?(Array)
+          raise ArgumentError, 'expense_vouchers must not be empty' if expense_vouchers.empty?
+          raise ArgumentError, 'expense_vouchers must contain Hashes' unless expense_vouchers.all?(Hash)
+
+          validator = PapierkramApi::V1::Validators::ExpenseVoucher.new
+          expense_vouchers.all? do |voucher|
+            validate_expense_voucher!(validator, voucher)
+          end
+        end
+
+        def validate_expense_voucher!(validator, expense_voucher)
+          validator.validate!(expense_voucher)
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/business_intelligence/smart_queries/expense_vouchers_for_month_in_year.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module BusinessIntelligence
+      module SmartQueries
+        # This class is responsible for all the API calls related to expense vouchers.
+        class ExpenseVouchersForMonthInYear
+          include PapierkramApi::V1::Helper::DateHelper
+
+          def initialize(expense_voucher_api)
+            @expense_voucher_api = expense_voucher_api
+          end
+
+          def for_month_in_year(year:, month:)
+            @year = year
+            @month = month
+            @start_date = Date.new(@year, @month, 1)
+            @end_date = Date.new(@year, @month + 1, 1) - 1
+            collect_expense_vouchers
+          end
+
+          private
+
+          def collect_expense_vouchers
+            all_expense_vouchers_in_date_range.map do |voucher|
+              @expense_voucher_api.by(id: voucher['id']).body
+            end
+          end
+
+          def all_expense_vouchers_in_date_range
+            page = 1
+            vouchers = []
+            res = expense_vouchers(page: page)
+            res.body['entries'].each { |v| vouchers << v }
+            while res.body['page'] != res.body['total_pages']
+              res = expense_vouchers(page: page)
+              res.body['entries'].each { |v| vouchers << v }
+            end
+            vouchers
+          end
+
+          def expense_vouchers(page: 1)
+            @expense_voucher_api.all(
+              page: page,
+              document_date_range_start: build_date_string_for_api(@start_date),
+              document_date_range_end: build_date_string_for_api(@end_date)
+            )
+          end
+
+          def expense_voucher(id)
+            @expense_voucher_api.by(id: id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/banking/bank_connections.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Banking
+        # This class is responsible for all the API calls related to banking bank connections.
+        class BankConnections < PapierkramApi::V1::Endpoints::Base
+          def by(id:)
+            get("#{@url_api_path}/banking/bank_connections/#{id}")
+          end
+
+          def all(page: 1,
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil)
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+
+            get("#{@url_api_path}/banking/bank_connections", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/banking/transactions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Banking
+        # This class is responsible for all the API calls related to banking transactions.
+        class Transactions
+          def by(id:)
+            # wip
+          end
+
+          def all
+            # wip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/base.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      # This class is the base class for all the API calls.
+      class Base
+        attr_reader :client, :url_api_path
+
+        def initialize(client)
+          @client = client
+          @url_api_path = '/api/v1'
+        end
+
+        def remaining_quota(response)
+          return response.headers['x-remaining-quota'].to_i if response.is_a?(Faraday::Response)
+          raise ArgumentError, 'Invalid response object' unless response.is_a?(Hash)
+
+          quota = response.dig('headers', 'x-remaining-quota') || response['x-remaining-quota']
+          return Integer(quota) if quota
+
+          raise ArgumentError, "No remaining quota found in response: #{response}"
+        end
+
+        def get(url, params = {}, headers = {})
+          validate_get!(params)
+          call_wrapper!(:get, url, params, headers)
+        end
+
+        def post(url, params = {}, headers = {})
+          call_wrapper!(:post, url, params, headers)
+        end
+
+        def put(url, params = {}, headers = {})
+          call_wrapper!(:put, url, params, headers)
+        end
+
+        def patch(url, params = {}, headers = {})
+          call_wrapper!(:patch, url, params, headers)
+        end
+
+        def delete(url, params = {}, headers = {})
+          call_wrapper!(:delete, url, params, headers)
+        end
+
+        private
+
+        def call_wrapper!(method, url, params = {}, headers = {})
+          @client.send(method, url, params, headers)
+        end
+
+        def validate_order_direction!(order_direction)
+          return if order_direction.nil?
+
+          raise ArgumentError, 'Invalid order direction' unless %w[asc desc].include?(order_direction)
+        end
+
+        def validate_billing_state!(billing_state)
+          return if billing_state.nil?
+
+          raise ArgumentError, 'Invalid billing state' unless %w[billed
+                                                                 unbilled
+                                                                 billable
+                                                                 unbillable
+                                                                 archived].include?(billing_state)
+        end
+
+        def validate_get!(params)
+          return unless params
+
+          validate_order_direction!(params[:order_direction])
+          validate_billing_state!(params[:billing_state])
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/contact/companies.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Contact
+        # This class is responsible for all the API calls related to banking bank connections.
+        class Companies < PapierkramApi::V1::Endpoints::Base
+          def by(id:)
+            get("#{@url_api_path}/contact/companies/#{id}")
+          end
+
+          def all(page: 1,
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil)
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+
+            get("#{@url_api_path}/contact/companies", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/contact/companies_persons.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Contact
+        # This class is responsible for all the API calls related to companies' persons connections.
+        class CompaniesPersons < PapierkramApi::V1::Endpoints::Base
+          def by(company_id:, id:)
+            get("#{@url_api_path}/contact/companies/#{company_id}/persons/#{id}")
+          end
+
+          def all(company_id:, page: 1, page_size: 100, order_by: nil, order_direction: nil)
+            query = {
+              company_id: company_id,
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+
+            get("#{@url_api_path}/contact/companies/#{company_id}/persons", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/expense/vouchers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Expense
+        # This class is responsible for all the API calls related to expense vouchers.
+        class Vouchers < PapierkramApi::V1::Endpoints::Base
+          def by(id:, pdf: false)
+            if pdf == true
+              return get("#{@url_api_path}/expense/vouchers/#{id}/pdf", nil,
+                         { headers: { 'Content-Type' => 'application/pdf' } })
+            end
+            get("#{@url_api_path}/expense/vouchers/#{id}")
+          end
+
+          def all(page: 1, # rubocop:disable Metrics/CyclomaticComplexity
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil,
+                  creditor_id: nil,
+                  project_id: nil,
+                  document_date_range_start: nil,
+                  document_date_range_end: nil)
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+            query[:creditor_id] = creditor_id if creditor_id
+            query[:project_id] = project_id if project_id
+            query[:document_date_range_start] = document_date_range_start if document_date_range_start
+            if document_date_range_end && document_date_range_start
+              query[:document_date_range_end] =
+                document_date_range_end
+            end
+
+            get("#{@url_api_path}/expense/vouchers", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/income/estimates.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Income
+        # This class is responsible for all the API calls related to income estimates.
+        class Estimates < PapierkramApi::V1::Endpoints::Base
+          def by(id:, pdf: false)
+            if pdf == true
+              return get("#{@url_api_path}/income/estimates/#{id}/pdf", nil,
+                         { headers: { 'Content-Type' => 'application/pdf' } })
+            end
+
+            get("#{@url_api_path}/income/estimates/#{id}")
+          end
+
+          def all(page: 1, # rubocop:disable Metrics/CyclomaticComplexity
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil,
+                  creditor_id: nil,
+                  project_id: nil,
+                  document_date_range_start: nil,
+                  document_date_range_end: nil)
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+            query[:creditor_id] = creditor_id if creditor_id
+            query[:project_id] = project_id if project_id
+            query[:document_date_range_start] = document_date_range_start if document_date_range_start
+            if document_date_range_end && document_date_range_start
+              query[:document_date_range_end] =
+                document_date_range_end
+            end
+
+            get("#{@url_api_path}/income/estimates", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/income/invoices.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Income
+        # This class is responsible for all the API calls related to income invoices.
+        class Invoices < PapierkramApi::V1::Endpoints::Base
+          def by(id:, pdf: false)
+            if pdf == true
+              return get("#{@url_api_path}/income/invoices/#{id}/pdf", nil,
+                         { headers: { 'Content-Type' => 'application/pdf' } })
+            end
+
+            get("#{@url_api_path}/income/invoices/#{id}")
+          end
+
+          def all(page: 1, # rubocop:disable Metrics/CyclomaticComplexity
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil,
+                  creditor_id: nil,
+                  project_id: nil,
+                  document_date_range_start: nil,
+                  document_date_range_end: nil)
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+            query[:creditor_id] = creditor_id if creditor_id
+            query[:project_id] = project_id if project_id
+            query[:document_date_range_start] = document_date_range_start if document_date_range_start
+            if document_date_range_end && document_date_range_start
+              query[:document_date_range_end] =
+                document_date_range_end
+            end
+
+            get("#{@url_api_path}/income/invoices", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/income/propositions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Income
+        # This class is responsible for all the API calls related to income propositions.
+        class Propositions < PapierkramApi::V1::Endpoints::Base
+          def by(id:)
+            get("#{@url_api_path}/income/propositions/#{id}")
+          end
+
+          def all
+            get("#{@url_api_path}/income/propositions")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/info.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      # This class is responsible for all the API calls related to info connections.
+      class Info < PapierkramApi::V1::Endpoints::Base
+        def details
+          get("#{@url_api_path}/info")
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/projects.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      # This class is responsible for all the API calls related to projects connections.
+      class Projects < PapierkramApi::V1::Endpoints::Base
+        def by(id:)
+          get("#{@url_api_path}/projects/#{id}")
+        end
+
+        def all(page: 1, per_page: 100, order_by: nil, order_direction: nil, company_id: nil)
+          query = {
+            page: page,
+            per_page: per_page
+          }
+          query[:order_by] = order_by if order_by
+          query[:order_direction] = order_direction if order_direction
+          query[:company_id] = company_id if company_id
+
+          get("#{@url_api_path}/projects", query)
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/tracker/tasks.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Tracker
+        # This class is responsible for all the API calls related to tracker tasks connections.
+        class Tasks < PapierkramApi::V1::Endpoints::Base
+          def by(id:)
+            get("#{@url_api_path}/tracker/tasks/#{id}")
+          end
+
+          def all(page: 1,
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil,
+                  project_id: nil,
+                  proposition_id: nil)
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+            query[:project_id] = project_id if project_id
+            query[:proposition_id] = proposition_id if proposition_id
+            get("#{@url_api_path}/tracker/tasks", query)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/endpoints/tracker/time_entries.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Endpoints
+      module Tracker
+        # This class is responsible for all the API calls related to tracker time entries connections.
+        class TimeEntries < PapierkramApi::V1::Endpoints::Base
+          def by(id:)
+            get("#{@url_api_path}/tracker/time_entries/#{id}")
+          end
+
+          def all(page: 1, # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
+                  page_size: 100,
+                  order_by: nil,
+                  order_direction: nil,
+                  project_id: nil,
+                  task_id: nil,
+                  invoice_id: nil,
+                  user_id: nil,
+                  billing_state: nil,
+                  start_time_range_start: nil,
+                  start_time_range_end: nil)
+            validate!(billing_state: billing_state,
+                      start_time_range_start: start_time_range_start,
+                      start_time_range_end: start_time_range_end)
+
+            query = {
+              page: page,
+              page_size: page_size
+            }
+            query[:order_by] = order_by if order_by
+            query[:order_direction] = order_direction if order_direction
+            query[:project_id] = project_id if project_id
+            query[:task_id] = task_id if task_id
+            query[:invoice_id] = invoice_id if invoice_id
+            query[:user_id] = user_id if user_id
+            query[:billing_state] = billing_state if billing_state
+            query[:start_time_range_start] = start_time_range_start if start_time_range_start
+            query[:start_time_range_end] = start_time_range_end if start_time_range_end
+            get("#{@url_api_path}/tracker/time_entries", query)
+          end
+
+          private
+
+          def validate!(billing_state:, start_time_range_start:, start_time_range_end:)
+            if billing_state && !%w[billed unbilled billable unbillable archived].include?(billing_state)
+              raise ArgumentError,
+                    'billing_state must be one of: "billed" "unbilled"" billable" "unbillable" "archived"'
+            end
+            if start_time_range_start && !start_time_range_start.is_a?(Time)
+              raise ArgumentError, 'start_time_range_start must be a Time object'
+            end
+            return unless start_time_range_end && !start_time_range_end.is_a?(Time)
+
+            raise ArgumentError, 'start_time_range_end must be a Time object'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api/v1/helper/date_helper.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Helper
+      # Helper module for date related methods
+      module DateHelper
+        def build_date_string_for_api(date)
+          date.strftime('%Y-%m-%d')
+        end
+      end
+    end
+  end
+end

data/lib/{api → papierkram_api}/v1/helper/pdf_from_response.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Api
+module PapierkramApi
   module V1
     module Helper
       # This class is responsible to convert a response to a pdf file.