papierkram_api_client 0.1.2 → 0.2.0

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.

data/lib/papierkram_api/v1/validators/expense_voucher.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module PapierkramApi
+  module V1
+    module Validators
+      # ExpenseVoucher Validator
+      class ExpenseVoucher
+        # Copied from https://simonneutert.papierkram.de/api/v1/api-docs/index.html
+        SWAGGER_SAMPLE = {
+          type: 'expense_voucher',
+          id: 385,
+          name: 'Restaurant visit',
+          due_date: '2020-06-30',
+          document_date: '2020-06-14',
+          description: 'Took customer for dinner.',
+          entertainment_reason: 'sales meeting',
+          flagged: true,
+          provenance: 'domestic',
+          voucher_no: 'B-EXP-0001',
+          state: 'unpaid',
+          record_state: 'active',
+          amount: 165.8,
+          invoice_amount: 0,
+          entertainment_persons: [],
+          creditor: {
+            type: 'company',
+            id: 4814,
+            name: 'Ristorante Il Porcino',
+            contact_type: 'supplier',
+            supplier_no: 'L-00001',
+            customer_no: nil,
+            email: nil,
+            phone: nil,
+            website: nil,
+            twitter: nil,
+            fax: nil,
+            postal_street: 'Dotzheimer Str. 36',
+            postal_zip: '65185',
+            postal_city: 'Wiesbaden',
+            postal_country: 'Deutschland',
+            physical_street: nil,
+            physical_zip: nil,
+            physical_city: nil,
+            physical_country: 'Deutschland',
+            delivery_method: nil,
+            ust_idnr: 'BE0999999999',
+            logo_file_name: nil,
+            logo_content_type: nil,
+            logo_file_size: nil,
+            logo_updated_at: nil,
+            bank_blz: '79351010',
+            bank_institute: 'Sparkasse Bad Kissingen',
+            bank_account_no: '789456123',
+            bank_bic: 'MARKDEFFXXX',
+            bank_sepa_mandate_reference: 'SEPAMRL00001RIP',
+            bank_sepa_mandate_accepted: nil,
+            bank_iban: 'DE68210501700012345678',
+            inbound_address: 'emkx',
+            notes: nil,
+            record_state: 'active',
+            flagged: nil,
+            created_at: '2023-04-04T10:14:16.000+02:00',
+            updated_at: '2023-04-04T10:14:16.000+02:00',
+            color: nil
+          },
+          line_items: [
+            {
+              name: 'restaurant bill',
+              amount: 150.8,
+              category: 'Bewirtungskosten',
+              vat_rate: '19%',
+              billing: nil,
+              depreciation: nil
+            },
+            {
+              name: 'tip',
+              amount: 15,
+              category: 'Bewirtungskosten',
+              vat_rate: '19%',
+              billing: nil,
+              depreciation: nil
+            }
+          ],
+          documents: [
+            {
+              type: 'document',
+              id: 30,
+              uri: 'http://test.odacer.com/system/attachments/1/documents/30/7e6274cdeac3ecfdd1e5c746f6378e5229ddfd0d/data/original/sample.pdf?1680596056'
+            }
+          ]
+        }.freeze
+        SWAGGER_SAMPLE_KEYS_STRINGIFIED = SWAGGER_SAMPLE.keys.map(&:to_s).sort.freeze
+
+        def validate!(expense_voucher)
+          unless expense_voucher['type'] == 'expense_voucher' &&
+                 expense_voucher.keys.sort == SWAGGER_SAMPLE_KEYS_STRINGIFIED
+            raise ArgumentError, 'expense_voucher does not match the expected format'
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/papierkram_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PapierkramApiClient
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/lib/papierkram_api_client.rb

@@ -6,105 +6,24 @@ require 'forwardable'
 require 'tempfile'
 
 require_relative 'papierkram_api_client/version'
-require_relative 'api/v1/base'
-require_relative 'api/v1/banking/bank_connections'
-require_relative 'api/v1/banking/transactions'
-require_relative 'api/v1/contact/companies'
-require_relative 'api/v1/contact/companies_persons'
-require_relative 'api/v1/expense/vouchers'
-require_relative 'api/v1/income/estimates'
-require_relative 'api/v1/income/invoices'
-require_relative 'api/v1/income/propositions'
-require_relative 'api/v1/info'
-require_relative 'api/v1/projects'
-require_relative 'api/v1/tracker/tasks'
-require_relative 'api/v1/tracker/time_entries'
-
-module PapierkramApiClient
-  class Error < StandardError; end
-
-  # 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_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 banking_bank_connections
-      @banking_bank_connections ||= Api::V1::Banking::BankConnections.new(@client)
-    end
-
-    def banking_transactions
-      raise ArgumentError, 'not implemented'
-      # @banking_transactions ||= Api::V1::Banking::Transactions.new(@client)
-    end
-
-    def contact_companies
-      @contact_companies ||= Api::V1::Contact::Companies.new(@client)
-    end
-
-    def contact_companies_persons
-      @contact_companies_persons ||= Api::V1::Contact::CompaniesPersons.new(@client)
-    end
-
-    def expense_vouchers
-      @expense_vouchers ||= Api::V1::Expense::Vouchers.new(@client)
-    end
-
-    def income_estimates
-      @income_estimates ||= Api::V1::Income::Estimates.new(@client)
-    end
-
-    def income_invoices
-      @income_invoices ||= Api::V1::Income::Invoices.new(@client)
-    end
-
-    def income_propositions
-      @income_propositions ||= Api::V1::Income::Propositions.new(@client)
-    end
-
-    def info
-      @info ||= Api::V1::Info.new(@client)
-    end
-
-    def projects
-      @projects ||= Api::V1::Projects.new(@client)
-    end
-
-    def tracker_tasks
-      @tracker_tasks ||= Api::V1::Tracker::Tasks.new(@client)
-    end
-
-    def tracker_time_entries
-      @tracker_time_entries ||= Api::V1::Tracker::TimeEntries.new(@client)
-    end
-
-    private
-
-    def base_url_env
-      "https://#{@subdomain}.papierkram.de"
-    end
-  end
-end
+require_relative 'papierkram_api/v1/helper/pdf_from_response'
+require_relative 'papierkram_api/v1/helper/date_helper'
+require_relative 'papierkram_api/v1/validators/expense_voucher'
+require_relative 'papierkram_api/v1/endpoints/base'
+require_relative 'papierkram_api/v1/endpoints/banking/bank_connections'
+require_relative 'papierkram_api/v1/endpoints/banking/transactions'
+require_relative 'papierkram_api/v1/endpoints/contact/companies'
+require_relative 'papierkram_api/v1/endpoints/contact/companies_persons'
+require_relative 'papierkram_api/v1/endpoints/expense/vouchers'
+require_relative 'papierkram_api/v1/endpoints/income/estimates'
+require_relative 'papierkram_api/v1/endpoints/income/invoices'
+require_relative 'papierkram_api/v1/endpoints/income/propositions'
+require_relative 'papierkram_api/v1/endpoints/info'
+require_relative 'papierkram_api/v1/endpoints/projects'
+require_relative 'papierkram_api/v1/endpoints/tracker/tasks'
+require_relative 'papierkram_api/v1/endpoints/tracker/time_entries'
+require_relative 'papierkram_api/v1/business_intelligence/base'
+require_relative 'papierkram_api/v1/business_intelligence/expenses_by_category'
+require_relative 'papierkram_api/v1/business_intelligence/smart_queries/expense_vouchers_for_month_in_year'
+
+require_relative 'papierkram_api/client'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papierkram_api_client
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Simon Neutert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-13 00:00:00.000000000 Z
+date: 2023-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -56,20 +56,26 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/api/v1/banking/bank_connections.rb
-- lib/api/v1/banking/transactions.rb
-- lib/api/v1/base.rb
-- lib/api/v1/contact/companies.rb
-- lib/api/v1/contact/companies_persons.rb
-- lib/api/v1/expense/vouchers.rb
-- lib/api/v1/helper/pdf_from_response.rb
-- lib/api/v1/income/estimates.rb
-- lib/api/v1/income/invoices.rb
-- lib/api/v1/income/propositions.rb
-- lib/api/v1/info.rb
-- lib/api/v1/projects.rb
-- lib/api/v1/tracker/tasks.rb
-- lib/api/v1/tracker/time_entries.rb
+- lib/papierkram_api/client.rb
+- lib/papierkram_api/v1/business_intelligence/base.rb
+- lib/papierkram_api/v1/business_intelligence/expenses_by_category.rb
+- lib/papierkram_api/v1/business_intelligence/smart_queries/expense_vouchers_for_month_in_year.rb
+- lib/papierkram_api/v1/endpoints/banking/bank_connections.rb
+- lib/papierkram_api/v1/endpoints/banking/transactions.rb
+- lib/papierkram_api/v1/endpoints/base.rb
+- lib/papierkram_api/v1/endpoints/contact/companies.rb
+- lib/papierkram_api/v1/endpoints/contact/companies_persons.rb
+- lib/papierkram_api/v1/endpoints/expense/vouchers.rb
+- lib/papierkram_api/v1/endpoints/income/estimates.rb
+- lib/papierkram_api/v1/endpoints/income/invoices.rb
+- lib/papierkram_api/v1/endpoints/income/propositions.rb
+- lib/papierkram_api/v1/endpoints/info.rb
+- lib/papierkram_api/v1/endpoints/projects.rb
+- lib/papierkram_api/v1/endpoints/tracker/tasks.rb
+- lib/papierkram_api/v1/endpoints/tracker/time_entries.rb
+- lib/papierkram_api/v1/helper/date_helper.rb
+- lib/papierkram_api/v1/helper/pdf_from_response.rb
+- lib/papierkram_api/v1/validators/expense_voucher.rb
 - lib/papierkram_api_client.rb
 - lib/papierkram_api_client/version.rb
 - pac.svg

data/lib/api/v1/banking/bank_connections.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Api
-  module V1
-    module Banking
-      # This class is responsible for all the API calls related to banking bank connections.
-      class BankConnections < Api::V1::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

data/lib/api/v1/banking/transactions.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Api
-  module V1
-    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

data/lib/api/v1/base.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Api
-  module V1
-    # 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

data/lib/api/v1/contact/companies.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Api
-  module V1
-    module Contact
-      # This class is responsible for all the API calls related to banking bank connections.
-      class Companies < Api::V1::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

data/lib/api/v1/contact/companies_persons.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Api
-  module V1
-    module Contact
-      # This class is responsible for all the API calls related to companies' persons connections.
-      class CompaniesPersons < Api::V1::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

data/lib/api/v1/expense/vouchers.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module Api
-  module V1
-    module Expense
-      # This class is responsible for all the API calls related to expense vouchers.
-      class Vouchers < Api::V1::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