papierkram_api_client 0.1.0

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

@@ -0,0 +1,28 @@
+# 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

@@ -0,0 +1,18 @@
+# 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

@@ -0,0 +1,75 @@
+# 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

@@ -0,0 +1,28 @@
+# 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

@@ -0,0 +1,26 @@
+# 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

@@ -0,0 +1,44 @@
+# 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

data/lib/api/v1/helper/pdf_from_response.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    module Helper
+      # This class is responsible to convert a response to a pdf file.
+      class PdfFromResponse
+        def initialize(response)
+          @response = response
+        end
+
+        def to_pdf(filename = Time.now.to_s)
+          raise ArgumentError, 'Response is not a Faraday::Response' unless @response.is_a?(Faraday::Response)
+          raise ArgumentError, 'Response is not a PDF file' unless response.body.start_with?('%PDF-1.4')
+
+          file = Tempfile.new([filename.to_s, '.pdf'], binmode: true)
+          file.write(response.body)
+          file.close
+
+          { response: @response, path_to_pdf_file: file.path }
+        end
+      end
+    end
+  end
+end

data/lib/api/v1/income/estimates.rb

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

data/lib/api/v1/income/invoices.rb

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

data/lib/api/v1/income/propositions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    module Income
+      # This class is responsible for all the API calls related to income propositions.
+      class Propositions < Api::V1::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

data/lib/api/v1/info.rb

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

data/lib/api/v1/projects.rb

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

data/lib/api/v1/tracker/tasks.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    module Tracker
+      # This class is responsible for all the API calls related to tracker tasks connections.
+      class Tasks < Api::V1::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

data/lib/api/v1/tracker/time_entries.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    module Tracker
+      # This class is responsible for all the API calls related to tracker time entries connections.
+      class TimeEntries < Api::V1::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/MethodLength
+                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

data/lib/papierkram_api_client/version.rb

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

data/lib/papierkram_api_client.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'httpx/adapters/faraday'
+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

data/sig/papierkram_api_client.rbs

@@ -0,0 +1,4 @@
+module PapierkramApiClient
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end