papierkram_api_client 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ad6eb6ad8c0a3e4bd834cfd8162eec1de325fca9d7eac9eaba3803e38d2bdce
-  data.tar.gz: 6a382f2ae7f48217a42edf5a8c65d4f4b6ac302e7025dfbd030e43cf8d62fc8c
+  metadata.gz: 7efda340be625d91834f22276f4e95767a7d06621bb7d4e8ab6cbb7a503c40f0
+  data.tar.gz: dad2650ea0bf6cc8339988ff4e5ab4265e26bad4c203398166d14296db415cdd
 SHA512:
-  metadata.gz: a54dc382abc5083ac943853d6331a19aef63e3ba1560d6e36c40e2fade3577b8e3d5a131b80c51962385fea8df0084c46197a30035f7f953931a5161a6a32644
-  data.tar.gz: af47f4d1001746a9e28d6706b49bad8eab5b3f5855ffd57919c39068792451a73c02e4a1b6fc3ad4f8de955828251fcf337bc38462892792fa0e158a80f0c5fe
+  metadata.gz: '039f293aa1bcf2da3ba920cae9d63ff014a674764f76302f5f318cc89763df94518d69ddc61a105fcd0b13bff487e1a8196ead1a6e32f8e405f26cfb2a54096f'
+  data.tar.gz: 41344eba19e9d4d76fca686ec05f8f0724fb38caeb0b08397e54ac2a0464fda1a58d3d7e7118a92c5d5eef7b4f5cf3d9dfd52fd7bbeaf0641f4844b983748eb4

data/.rubocop.yml

@@ -19,6 +19,11 @@ Layout/LineLength:
 
 Metrics/MethodLength:
   Max: 16
+  CountAsOne:
+    - "array"
+    - "hash"
+    - "heredoc"
+    - "method_call"
 
 Metrics/ParameterLists:
   Max: 8

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# Changelog
+
+## [0.2.1] - 2023-04-21
+
+### Added
+
+- [#20](https://github.com/simonneutert/papierkram_api_client/pull/20) Adds Banking::Transactions as endpoint with tests. [@simonneutert](https://github.com/simonneutert)
+
+## [0.2.0] - 2023-04-18
+
+Das Namespacing hat sich geändert. Die Klasse `PapierkramApiClient` ist jetzt `PapierkramApi::Client`.
+
+Bitte schaue für Details in die upgedatete Dokumentation in [README.md](README.md) und passe gegebenenfalls deinen Code an.
+
+### Changed
+
+- [#19](https://github.com/simonneutert/papierkram_api_client/pull/19) Bump rubocop from 1.50.1 to 1.50.2. [@simonneutert](https://github.com/simonneutert)
+- [#18](https://github.com/simonneutert/papierkram_api_client/pull/18) Stub basic business intelligence module. [@simonneutert](https://github.com/simonneutert)
+
 ## [0.1.3] - 2023-04-15
 
 Solltest du diesen Client mithilfe von Umgebungsvariablen einrichten, musst du deinen Code aktualisieren, um die neuen Variablen zu verwenden. Siehe `.env.sample` für die aktualisierten Variablen.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    papierkram_api_client (0.1.3)
+    papierkram_api_client (0.2.1)
       faraday (~> 2.7)
       httpx (~> 0.22.5)
 
@@ -34,9 +34,9 @@ GEM
       method_source (~> 1.0)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.7.0)
+    regexp_parser (2.8.0)
     rexml (3.2.5)
-    rubocop (1.50.1)
+    rubocop (1.50.2)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.2.0.0)

data/README.md

@@ -4,8 +4,14 @@
 
 Der erste ~~illegale~~ inoffizielle API Client in [Ruby](https://www.ruby-lang.org/de/) für [Papierkram.de](https://www.papierkram.de)!
 
+### Hol mehr aus deinen Daten raus! Dieser Client bietet dir bald einige Features im Bereich [Business Intelligence](#business-intelligence)!<!-- omit in toc -->
+
+---
+
 <img src="pac.svg" alt="PAC Logo, Zunge leckt an Karl Klammer und zieht Daten aus dem Papierkram-Account wie Frosch die Fliege vom Teich" width="300">
 
+Hol dir den [Papierkram API Client](https://rubygems.org/gems/papierkram_api_client) als [Ruby Gem](https://rubygems.org/gems/papierkram_api_client)!
+
 ---
 
 **WERBUNG** (es ist ein Aufruf zur Mitarbeit 🫠)
@@ -20,9 +26,7 @@ Das Gleiche, nur in grün, also für [NodeJS](https://github.com/simonneutert/pa
 
 Check das [CHANGELOG.md](CHANGELOG.md), Baby!
 
- Hier geht es zu den offiziellen API Docs  
-https://DEINE-SUBDOMAIN.papierkram.de/api/v1/api-docs/index.html  
-(wenn du bereits ein Papierkram-Konto hast).  
+Hier geht es zu den [offiziellen API Docs](https://demo.papierkram.de/api/v1/api-docs/index.html).  
 Schau bitte dort um alle Rückgabefelder/-werte zu checken, bis ich die Dokumentation hier komplett habe.
 
 ---
@@ -32,7 +36,7 @@ Ruby client für die Papierkram API (V1).
 Aktuell unterstützte Endpunkte / Objekte:
 
 - [x] Banking::BankConnection
-- [ ] Banking::BankTransaction
+- [x] Banking::BankTransaction
 - [x] Contact::Company (Unternehmen)
 - [x] Contact::Company (Kontaktpersonen)
 - [x] Expense::Voucher (Ausgabe Belege)
@@ -46,7 +50,7 @@ Aktuell unterstützte Endpunkte / Objekte:
 
 ## Was, wie, warum?<!-- omit in toc -->
 
-Papierkram.de hat nun endlich eine API Schnittstelle für die Programmierung von eigenen Anwendungen. Die Dokumentation findest du hier: [https://DEINE-SUBDOMAIN.papierkram.de/api/v1/api-docs/index.html](https://DEINE-SUBDOMAIN.papierkram.de/api/v1/api-docs/index.html). Dieses Projekt soll eine einfache Schnittstelle für die Papierkram API bereitstellen.
+Papierkram.de hat nun endlich eine API Schnittstelle für die Programmierung von eigenen Anwendungen. Die Dokumentation findest du hier: [https://DEINE-SUBDOMAIN.papierkram.de/papierkram_api/v1/api-docs/index.html](https://DEINE-SUBDOMAIN.papierkram.de/papierkram_api/v1/api-docs/index.html). Dieses Projekt soll eine einfache Schnittstelle für die Papierkram API bereitstellen.
 
 Ziele:
 
@@ -96,6 +100,10 @@ Ziele:
     - [alle Zeiteinträge](#alle-zeiteinträge)
     - [einen Zeiteintrag](#einen-zeiteintrag)
   - [Verbleibendes Quota](#verbleibendes-quota)
+- [Business Intelligence](#business-intelligence)
+  - [Business::Intelligence (BI) ExpenseByCategory (Ausgaben nach Kategorie)](#businessintelligence-bi-expensebycategory-ausgaben-nach-kategorie)
+    - [alle Ausgaben eines Monats nach Kategorie](#alle-ausgaben-eines-monats-nach-kategorie)
+    - [alle Ausgaben eines Monats nach Kategorie gefiltert nach Steuersatz](#alle-ausgaben-eines-monats-nach-kategorie-gefiltert-nach-steuersatz)
 - [Helpers](#helpers)
   - [Generiere ein PDF aus Response](#generiere-ein-pdf-aus-response)
 - [Development](#development)
@@ -122,10 +130,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
 # client instanziieren
 
 # wenn ENV gesetzt sind (siehe Readme)
-client = PapierkramApiClient::Client.new
+client = PapierkramApi::Client.new
 
 # ODER per Variablen
-client = PapierkramApiClient::Client.new('subdomain', "YOUR-API-KEY");
+client = PapierkramApi::Client.new('subdomain', "YOUR-API-KEY");
 
 # info Endpunkt abfragen
 info_details = client.info.details
@@ -142,41 +150,44 @@ puts invoices.body
 
 Der API Client ist die Hauptklasse für die Kommunikation mit der Papierkram API. Er wird mit den Zugangsdaten initialisiert.
 
-[Client](/lib/papierkram_api_client.rb)
+[Client](lib/papierkram_api/client.rb)
 
 Wenn du etwas hinter die Kulissen sehen willst, schau dir diese [Faraday](https://github.com/lostisland/faraday) Klasse an [Faraday::Response](https://github.com/lostisland/faraday/blob/main/lib/faraday/response.rb).
 
-
 ### Initialisierung
 
 Entweder werden die Zugangsdaten als Argumente übergeben:
 
 ```ruby
 # usage with subdomain and api key
-client = PapierkramApiClient::Client.new('subdomain', "SUPER-LONG-API-KEY")
+client = PapierkramApi::Client.new('subdomain', "SUPER-LONG-API-KEY")
 ```
 
 Oder es werden die Umgebungsvariablen `PAPIERKRAM_API_SUBDOMAIN` und `PAPIERKRAM_API_KEY` gesetzt und der Client ohne Argumente initialisiert.
 
 ```ruby
 # usage with environment variables
-client = PapierkramApiClient::Client.new
+client = PapierkramApi::Client.new
 ```
 
 ### Banking::BankConnection (Bankverbindung)
 
-Der Endpunkt `/api/v1/banking/bank_connections` liefert Informationen über die Bankverbindungen. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/banking/bank_connections` liefert Informationen über die Bankverbindungen. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [BankConnections](/lib/api/v1/banking/bank_connections.rb) für mögliche Parameter.
+Siehe [BankConnections](lib/papierkram_api/v1/endpoints/banking/bank_connections.rb) für mögliche Parameter.
 
 #### alle Bankverbindungen
 
 ```ruby
-bank_connections = client.banking.bank_connections.all
+bank_connections = client.banking_bank_connections.all
 puts bank_connections.headers
 puts bank_connections.body
 ```
 
+<details>
+
+<summary>Response</summary>
+
 ```ruby
 # body
 {
@@ -194,14 +205,20 @@ puts bank_connections.body
 }
 ```
 
+</details>
+
 #### eine Bankverbindung
 
 ```ruby
-bank_connection = client.banking.bank_connections.by(id: 1)
+bank_connection = client.banking_bank_connections.by(id: 1)
 puts bank_connection.headers
 puts bank_connection.body
 ```
 
+<details>
+
+<summary>Response</summary>
+
 ```ruby
 # body
 {
@@ -226,17 +243,19 @@ puts bank_connection.body
 }
 ```
 
+</details>
+
 ### Banking::Transaction (Kontoumsatz)
 
 WORK IN PROGRESS
 
-[Transactions](/lib/api/v1/banking/transactions.rb)
+[Transactions](lib/papierkram_api/v1/endpoints/banking/transactions.rb)
 
 ### Contact::Company (Unternehmen)
 
-Der Endpunkt `/api/v1/contact/companies` liefert Informationen über die Unternehmen. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/contact/companies` liefert Informationen über die Unternehmen. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Companies](/lib/api/v1/contact/companies.rb) für mögliche Parameter.
+Siehe [Companies](lib/papierkram_api/v1/endpoints/contact/companies.rb) für mögliche Parameter.
 
 #### alle Unternehmen
 
@@ -256,14 +275,14 @@ puts company.body
 
 ### Contact::Company (Kontaktperson eines Unternehmens)
 
-Der Endpunkt `/api/v1/contact/companies/{company_id}` liefert Informationen über die Kontaktpersonen. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/contact/companies/{company_id}` liefert Informationen über die Kontaktpersonen. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [CompaniesPersons](/lib/api/v1/contact/companies_persons.rb) für mögliche Parameter.
+Siehe [CompaniesPersons](lib/papierkram_api/v1/endpoints/contact/companies_persons.rb) für mögliche Parameter.
 
 #### alle Kontaktpersonen (eines Unternehmens)
 
 ```ruby
-companies = client.contact.companies_persons.all(company_id: 1)
+companies = client.contact_companies_persons.all(company_id: 1)
 puts companies.headers
 puts companies.body
 ```
@@ -271,21 +290,21 @@ puts companies.body
 #### eine Kontaktperson (eines Unternehmens)
 
 ```ruby
-company = client.contact.companies_persons.by(company_id: 1, id: 1)
+company = client.contact_companies_persons.by(company_id: 1, id: 1)
 puts company.headers
 puts company.body
 ```
 
 ### Expense::Voucher (Ausgabe Beleg)
 
-Der Endpunkt `/api/v1/expense/vouchers` liefert Informationen über die Ausgabe Belege. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/expense/vouchers` liefert Informationen über die Ausgabe Belege. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Vouchers](/lib/api/v1/expense/vouchers.rb) für mögliche Parameter.
+Siehe [Vouchers](lib/papierkram_api/v1/endpoints/expense/vouchers.rb) für mögliche Parameter.
 
 #### alle Ausgabe Belege
 
 ```ruby
-vouchers = client.expense.vouchers.all
+vouchers = client.expense_vouchers.all
 puts vouchers.headers
 puts vouchers.body
 ```
@@ -293,7 +312,7 @@ puts vouchers.body
 #### einen Ausgabe Beleg
 
 ```ruby
-voucher = client.expense.vouchers.by(id: 1)
+voucher = client.expense_vouchers.by(id: 1)
 puts voucher.headers
 puts voucher.body
 ```
@@ -301,21 +320,21 @@ puts voucher.body
 #### einen Ausgabe Beleg als PDF
 
 ```ruby
-voucher = client.expense.vouchers.by(id: 1, pdf: true)
-puts Api::V1::Helpers::PdfFromResponse.new(voucher).to_pdf 
+voucher = client.expense_vouchers.by(id: 1, pdf: true)
+puts PapierkramApi::V1::Helpers::PdfFromResponse.new(voucher).to_pdf
 # => {response: Faraday::Response, path_to_pdf_file: 'path/to/tempfile_pdf.pdf'}
 ```
 
 ### Income::Estimate (Angebot)
 
-Der Endpunkt `/api/v1/income/estimates` liefert Informationen über die Angebote. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/income/estimates` liefert Informationen über die Angebote. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Estimates](/lib/api/v1/income/estimates.rb) für mögliche Parameter.
+Siehe [Estimates](lib/papierkram_api/v1/endpoints/income/estimates.rb) für mögliche Parameter.
 
 #### alle Angebote
 
 ```ruby
-estimates = client.income.estimates.all
+estimates = client.income_estimates.all
 puts estimates.headers
 puts estimates.body
 ```
@@ -323,7 +342,7 @@ puts estimates.body
 #### ein Angebot
 
 ```ruby
-estimate = client.income.estimates.by(id: 1)
+estimate = client.income_estimates.by(id: 1)
 puts estimate.headers
 puts estimate.body
 ```
@@ -331,21 +350,21 @@ puts estimate.body
 #### ein Angebot als PDF
 
 ```ruby
-estimate = client.income.estimates.by(id: 1, pdf: true)
-puts Api::V1::Helpers::PdfFromResponse.new(estimate).to_pdf 
+estimate = client.income_estimates.by(id: 1, pdf: true)
+puts PapierkramApi::V1::Helpers::PdfFromResponse.new(estimate).to_pdf
 # => {response: Faraday::Response, path_to_pdf_file: 'path/to/tempfile_pdf.pdf'}
 ```
 
 ### Income::Invoice (Rechnung)
 
-Der Endpunkt `/api/v1/income/invoices` liefert Informationen über die Rechnungen. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/income/invoices` liefert Informationen über die Rechnungen. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Invoices](/lib/api/v1/income/invoices.rb) für mögliche Parameter.
+Siehe [Invoices](lib/papierkram_api/v1/endpoints/income/invoices.rb) für mögliche Parameter.
 
 #### alle Rechnungen
 
 ```ruby
-invoices = client.income.invoices.all
+invoices = client.income_invoices.all
 puts invoices.headers
 puts invoices.body
 ```
@@ -353,7 +372,7 @@ puts invoices.body
 #### eine Rechnung
 
 ```ruby
-invoice = client.income.invoices.by(id: 1)
+invoice = client.income_invoices.by(id: 1)
 puts invoice.headers
 puts invoice.body
 ```
@@ -361,21 +380,21 @@ puts invoice.body
 #### eine Rechnung als PDF
 
 ```ruby
-invoice = client.income.invoices.by(id: 1, pdf: true)
-puts Api::V1::Helpers::PdfFromResponse.new(invoice).to_pdf 
+invoice = client.income_invoices.by(id: 1, pdf: true)
+puts PapierkramApi::V1::Helpers::PdfFromResponse.new(invoice).to_pdf
 # => {response: Faraday::Response, path_to_pdf_file: 'path/to/tempfile_pdf.pdf'}
 ```
 
 ### Income::Proposition (Waren / Dienstleistungen)
 
-Der Endpunkt `/api/v1/income/propositions` liefert Informationen über die Waren / Dienstleistungen. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/income/propositions` liefert Informationen über die Waren / Dienstleistungen. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Propositions](/lib/api/v1/income/propositions.rb) für mögliche Parameter.
+Siehe [Propositions](lib/papierkram_api/v1/endpoints/income/propositions.rb) für mögliche Parameter.
 
 #### alle Waren / Dienstleistungen
 
 ```ruby
-propositions = client.income.propositions.all
+propositions = client.income_propositions.all
 puts propositions.headers
 puts propositions.body
 ```
@@ -383,16 +402,16 @@ puts propositions.body
 #### eine Ware / Dienstleistung
 
 ```ruby
-proposition = client.income.propositions.by(id: 1)
+proposition = client.income_propositions.by(id: 1)
 puts proposition.headers
 puts proposition.body
 ```
 
 ### Info
 
-Der Endpunkt `/api/v1/info` liefert Informationen über die API. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `lib/papierkram_api/v1/endpoints/info.rb` liefert Informationen über die API. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Info](/lib/api/v1/info.rb).
+Siehe [Info](lib/papierkram_api/v1/endpoints/info.rb).
 
 ```ruby
 info = client.info.details
@@ -402,9 +421,9 @@ puts info.body
 
 ### Project::Project (Projekt)
 
-Der Endpunkt `/api/v1/projects` liefert Informationen über die Projekte. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/endpoints/projects` liefert Informationen über die Projekte. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Projects](/lib/api/v1/projects.rb) für mögliche Parameter.
+Siehe [Projects](lib/papierkram_api/v1/endpoints/projects.rb) für mögliche Parameter.
 
 #### alle Projekte
 
@@ -424,9 +443,9 @@ puts project.body
 
 ### Tracker::Task (Aufgabe)
 
-Der Endpunkt `/api/v1/tracker/tasks` liefert Informationen über die Aufgaben. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/tracker/tasks` liefert Informationen über die Aufgaben. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-Siehe [Tasks](/lib/api/v1/tracker/tasks.rb) für mögliche Parameter.
+Siehe [Tasks](lib/papierkram_api/v1/endpoints/tracker/tasks.rb) für mögliche Parameter.
 
 #### alle Aufgaben
 
@@ -446,9 +465,9 @@ puts task.body
 
 ### Tracker::TimeEntry (Zeiteintrag)
 
-Der Endpunkt `/api/v1/tracker/time_entries` liefert Informationen über die Zeiteinträge. Die Informationen werden als `Faraday::Response` zurückgegeben.
+Der Endpunkt `/papierkram_api/v1/tracker/time_entries` liefert Informationen über die Zeiteinträge. Die Informationen werden als `Faraday::Response` zurückgegeben.
 
-[TimeEntries](/lib/api/v1/tracker/time_entries.rb)
+[TimeEntries](lib/papierkram_api/v1/endpoints/tracker/time_entries.rb)
 
 #### alle Zeiteinträge
 
@@ -470,7 +489,7 @@ puts time_entry.body
 
 Jede API Anfrage "kostet" 1 Quota. Das Quota wird bei jedem Request aktualisiert. Um das verbleibende Quota zu erhalten, kann die Methode `remaining_quota` aufgerufen werden.
 
-[Base](/lib/api/v1/base.rb)
+[Base](lib/papierkram_api/v1/endpoints/base.rb)
 
 Du kannst dein Quota über die Papierkram Webseite einsehen. Die Anzahl der verbleibenden Anfragen wird dir dort angezeigt.
 
@@ -482,21 +501,100 @@ response = client.info.details
 quota = client.info.remaining_quota(response)
 ```
 
+## Business Intelligence
+
+TODO ergänzen wie man `SmartQueries` erstellt und verwendet.  
+TODO ergänzen wie man `SmartQueries` funktioneren.  
+TODO ergänzen wie die Rückgabewerte von `SmartQueries` gestaltet werden sollten.
+
+### Business::Intelligence (BI) ExpenseByCategory (Ausgaben nach Kategorie)
+
+Der Endpunkt `/papierkram_api/v1/business_intelligence/expense_by_categories` liefert Informationen über die Ausgaben nach Kategorie. Die Informationen werden als `Hash` zurückgegeben.
+
+#### alle Ausgaben eines Monats nach Kategorie
+
+```ruby
+client = PapierkramApi::Client.new
+expense_voucher_data_service = client.expense_vouchers.data_service(:for_month_in_year_service)
+expense_vouchers_in_date_range = expense_voucher_data_service.for_month_in_year(year: 2020, month: 8)
+
+service = client.business_intelligence.expenses_by_category
+result = service.call(expense_vouchers: expense_vouchers_in_date_range)
+puts result
+```
+
+```ruby
+{"Betriebsbedarf"=>
+  {"amount"=>476.0,
+   "amount_by_creditor"=>{nil=>476.0},
+   "line_items"=>
+    [{"name"=>"2020-01-03",
+      "amount"=>119.0,
+      "category"=>"Betriebsbedarf",
+      "vat_rate"=>"19%",
+      "billing"=>nil,
+      "depreciation"=>nil,
+      "voucher_name"=>"B-00214 - 2020-08-01",
+      "voucher_id"=>641,
+      "creditor"=>nil},
+     {"name"=>"2020-01-03",
+      "amount"=>119.0,
+      "category"=>"Betriebsbedarf",
+      "vat_rate"=>"19%",
+      "billing"=>nil,
+      "depreciation"=>nil,
+      "voucher_name"=>"B-00215 - 2020-08-02",
+      "voucher_id"=>644,
+      "creditor"=>nil},
+     {"name"=>"2020-01-03",
+      "amount"=>119.0,
+      "category"=>"Betriebsbedarf",
+      "vat_rate"=>"19%",
+      "billing"=>nil,
+      "depreciation"=>nil,
+      "voucher_name"=>"B-00216 - 2020-08-03",
+      "voucher_id"=>647,
+      "creditor"=>nil},
+     {"name"=>"2020-01-03",
+      "amount"=>119.0,
+      "category"=>"Betriebsbedarf",
+      "vat_rate"=>"19%",
+      "billing"=>nil,
+      "depreciation"=>nil,
+      "voucher_name"=>"B-00217 - 2020-08-04",
+      "voucher_id"=>650,
+      "creditor"=>nil}]}}
+```
+
+#### alle Ausgaben eines Monats nach Kategorie gefiltert nach Steuersatz
+
+```ruby
+client = PapierkramApi::Client.new
+expense_voucher_data_service = client.expense_vouchers.data_service(:for_month_in_year_service)
+expense_vouchers_in_date_range = expense_voucher_data_service.for_month_in_year(year: 2020, month: 8)
+
+service = client.business_intelligence.expenses_by_category
+result = service.call(expense_vouchers: expense_vouchers_in_date_range) do |line_items|
+  line_items.select { |v| v['vat_rate'] == '19%' }
+end
+puts result
+```
+
 ## Helpers
 
 Es gibt einige Helper, die dir das Leben leichter machen.
 
 ### Generiere ein PDF aus Response
 
-Mit dem Helper `Api::V1::Helpers::PdfFromResponse` kannst du für unterstützte Endpunkte aus einer `Faraday::Response` ein PDF schreiben.
+Mit dem Helper `PapierkramApi::V1::Helpers::PdfFromResponse` kannst du für unterstützte Endpunkte aus einer `Faraday::Response` ein PDF schreiben.
 
 Unterstützte Endpunkte sind beispielsweise: `Income::Estimate`, `Income::Invoice`, `Expense::Voucher`.
 
-[Api::V1::Helpers::PdfFromResponse](/lib/api/v1/helpers/pdf_from_response.rb)
+[Api::V1::Helpers::PdfFromResponse](lib/papierkram_api/v1/helper/pdf_from_response.rb)
 
 ```ruby
 response = client.income_invoices.by(id: 1, pdf: true)
-pdf = Api::V1::Helpers::PdfFromResponse.new(response).to_pdf("Rechnung Nummer XXX")
+pdf = PapierkramApi::V1::Helpers::PdfFromResponse.new(response).to_pdf("Rechnung Nummer XXX")
 puts pdf
 ```
 
@@ -522,7 +620,7 @@ Bitte achte darauf, dass du die Tests ausführst und die Tests dann auch grün s
 
 🚨 **SEHR WICHTIG!** Dein API Key wird in den Tests verwendet werden. **Bitte achte darauf**, dass du den API Key nicht in deinen Commits hast! Wenn du per Environment Variable arbeitest, dann wird dein API Key **nicht von VCR aufgezeichnet**. Das bedeutet, dass du deine Tests nicht mit deinem API Key ausführen solltest. ⚠️
 
-🚨 **NOCH WICHTIGER!** deine Kundendaten, also Klarnamen, E-Mails und Telefonnummern haben hier nichts verloren! Bitte sorge dafür, dass du deine Tests mit einem Testaccount ausführst. 🙏 ODER editiere deine Kundendaten in den *VCR Cassettes* nach dem Test. 🙏
+🚨 **NOCH WICHTIGER!** deine Kundendaten, also Klarnamen, E-Mails und Telefonnummern haben hier nichts verloren! Bitte sorge dafür, dass du deine Tests mit einem Testaccount ausführst. 🙏 ODER editiere deine Kundendaten in den _VCR Cassettes_ nach dem Test. 🙏
 
 Wenn du unsicher bist, sprich mich an oder erstelle ein Issue. Ich helfe dir gerne weiter. 🤗
 

data/lib/papierkram_api/client.rb

@@ -0,0 +1,91 @@
+# 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
+      @banking_transactions ||= PapierkramApi::V1::Endpoints::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