papierkram_api_client 0.1.2 → 0.2.0

data/lib/papierkram_api/client.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  # The Client class is the main entry point for the Papierkram API Client.
+  class Client
+    attr_accessor :client,
+                  :subdomain,
+                  :api_key,
+                  :base_url,
+                  :remaining_quota
+
+    extend Forwardable
+    def_delegators :@client, :get, :post, :put, :patch, :delete
+
+    def initialize(subdomain = nil, api_key = nil)
+      @subdomain = subdomain || ENV.fetch('PAPIERKRAM_API_SUBDOMAIN', nil)
+      @api_key = api_key || ENV.fetch('PAPIERKRAM_API_KEY', nil)
+      @base_url = base_url_env
+      @remaining_quota = nil
+      build_client!
+    end
+
+    def build_client!
+      @client = Faraday.new(url: @base_url) do |config|
+        config.request :authorization, 'Bearer', @api_key
+        config.request :json
+        config.response :json
+        config.adapter :httpx
+        yield(config) if block_given?
+      end
+    end
+
+    def business_intelligence
+      @business_intelligence ||= PapierkramApi::V1::BusinessIntelligence::Base.new
+    end
+
+    def banking_bank_connections
+      @banking_bank_connections ||= PapierkramApi::V1::Endpoints::Banking::BankConnections.new(@client)
+    end
+
+    def banking_transactions
+      raise ArgumentError, 'not implemented'
+      # @banking_transactions ||= PapierkramApi::V1::Banking::Transactions.new(@client)
+    end
+
+    def contact_companies
+      @contact_companies ||= PapierkramApi::V1::Endpoints::Contact::Companies.new(@client)
+    end
+
+    def contact_companies_persons
+      @contact_companies_persons ||= PapierkramApi::V1::Endpoints::Contact::CompaniesPersons.new(@client)
+    end
+
+    def expense_vouchers
+      @expense_vouchers ||= PapierkramApi::V1::Endpoints::Expense::Vouchers.new(@client)
+    end
+
+    def income_estimates
+      @income_estimates ||= PapierkramApi::V1::Endpoints::Income::Estimates.new(@client)
+    end
+
+    def income_invoices
+      @income_invoices ||= PapierkramApi::V1::Endpoints::Income::Invoices.new(@client)
+    end
+
+    def income_propositions
+      @income_propositions ||= PapierkramApi::V1::Endpoints::Income::Propositions.new(@client)
+    end
+
+    def info
+      @info ||= PapierkramApi::V1::Endpoints::Info.new(@client)
+    end
+
+    def projects
+      @projects ||= PapierkramApi::V1::Endpoints::Projects.new(@client)
+    end
+
+    def tracker_tasks
+      @tracker_tasks ||= PapierkramApi::V1::Endpoints::Tracker::Tasks.new(@client)
+    end
+
+    def tracker_time_entries
+      @tracker_time_entries ||= PapierkramApi::V1::Endpoints::Tracker::TimeEntries.new(@client)
+    end
+
+    private
+
+    def base_url_env
+      "https://#{@subdomain}.papierkram.de"
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module BusinessIntelligence
+      # Business Intelligence Base Class
+      #
+      # Business Intelligence is a set of services that can be used to gain
+      # insights into the data stored in the system.
+      #
+      # Therefor you should pass data to the service and get back a result.
+      #
+      # IMPORTANT no calls to the API should be made in this class.
+      # This is an intentional design decision! To seperate logic from the data source.
+      #
+      class Base
+        def expenses_by_category
+          @expenses_by_category ||= PapierkramApi::V1::BusinessIntelligence::ExpensesByCategory.new
+        end
+      end
+    end
+  end
+end

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