papierkram_api_client 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63831b78f4a4447b7d349355292f027893b4a4805652dc5baa7c938a62ad8dd0
-  data.tar.gz: 365a0db65a10d288f1be917a467ef96e7343cf74755ec6469f4065faa09b2cb1
+  metadata.gz: c428355fa2303fe4086587e47b981b46eac42c498ea84cb2ada942b8b926e1d1
+  data.tar.gz: 63f9f3524d98be430356ebc7e19bc344a0e388f9b99c71dcd4303a7427fd0635
 SHA512:
-  metadata.gz: 9cdc3d2759ba1fbbd66179012d193a0683028b63d2e37d5edee4af29d18b5fab5e2728c2d20dbbf8d41afb2d099ddeb9d3986bc623ff6cc34303d4cd1e649719
-  data.tar.gz: 76ca8994286cf1695386a9ea5d75d4ea8becdb5fff834f1ea80ba2693a448ecdecc38d2f7fb0e883477f004049f2227b94a7fc38e00168066fefa2da55fc3a30
+  metadata.gz: c4a0d1e8ae94400e56919997bd82daa69cec0ee3b3e6c26d0525e952c6f075238effe6a589c7217c4d89658ec7e2c41c61159b06362898cf4aed7c7f50399103
+  data.tar.gz: b9abc76a4a14af64eaaa07f98e925a164b1474c40e4a618830966c269c3bccb4f28d8334a07b1ea4672b295e6f3d1ef6808bbbae6147bef4b211b0776bda200c

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,4 +1,27 @@
-## [v0.1.2] - 2023-04-13
+# Changelog
+
+## [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.
+
+- `PAPIERKRAM_SUBDOMAIN` ist jetzt `PAPIERKRAM_API_SUBDOMAIN`
+
+### Changed
+
+[#17](https://github.com/simonneutert/papierkram_api_client/pull/17) tests expense vouchers endpoint and parameters. [@simonneutert](https://github.com/simonneutert)
+
+## [0.1.2] - 2023-04-13
 
 ### Fixed
 

data/Gemfile

@@ -9,6 +9,6 @@ gem 'minitest', '~> 5.0'
 gem 'minitest-vcr', '~> 1.4'
 gem 'pry', '~> 0.14.2'
 gem 'rake', '~> 13.0'
-gem 'rubocop', '~> 1.48'
+gem 'rubocop', '~> 1.50'
 gem 'rubocop-minitest', '~> 0.30.0'
 gem 'vcr', '~> 6.1'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    papierkram_api_client (0.1.2)
+    papierkram_api_client (0.2.0)
       faraday (~> 2.7)
       httpx (~> 0.22.5)
 
@@ -34,16 +34,16 @@ 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.48.1)
+    rubocop (1.50.2)
       json (~> 2.3)
       parallel (~> 1.10)
       parser (>= 3.2.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.26.0, < 2.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.28.0)
@@ -66,7 +66,7 @@ DEPENDENCIES
   papierkram_api_client!
   pry (~> 0.14.2)
   rake (~> 13.0)
-  rubocop (~> 1.48)
+  rubocop (~> 1.50)
   rubocop-minitest (~> 0.30.0)
   vcr (~> 6.1)
 

data/README.md

@@ -4,16 +4,30 @@
 
 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 🫠)
+JETZT NEU! Ohne Lack und frei von Glamour!  
+Das Gleiche, nur in grün, also für [NodeJS](https://github.com/simonneutert/papierkram-api-client). Und als Mega-Baustelle 😬
+
+---
+
 **WICHTIG** Dieses Projekt befindet sich im Entwicklungsstatus bis V1.0.0! Ich werde versuchen, die Änderungen so gut wie möglich zu dokumentieren. Wenn du einen Fehler findest, kannst du gerne einen Issue erstellen oder einen Pull Request mit einer Verbesserung erstellen. Ich freue mich über jede Hilfe!
 
 > 🚨 **Bitte beachte**, dass DU UNBEDINGT die Requests/Responses der VCR Cassettes (die ausschliesslich bei Nutzung der Testsuite angelegt werden) von privaten Daten befreien musst, bevor du einen Pull Request erstellst oder einen Commit ins Web lädst! Ich werde die Cassettes auch nochmal durchgehen, bevor ich die Version 1.0.0 veröffentliche. ABER BITTE, BITTE, BITTE, mach das selbst auch! Ich habe keine Lust, dass irgendwelche Daten von dir oder deinen Kunden auf Github landen. Danke! 🙏
 
 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  
+Hier geht es zu den offiziellen API Docs  
+https://DEINE-SUBDOMAIN.papierkram.de/papierkram_api/v1/api-docs/index.html  
 (wenn du bereits ein Papierkram-Konto hast).  
 Schau bitte dort um alle Rückgabefelder/-werte zu checken, bis ich die Dokumentation hier komplett habe.
 
@@ -38,7 +52,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:
 
@@ -88,6 +102,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)
@@ -114,10 +132,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
@@ -134,41 +152,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_SUBDOMAIN` und `PAPIERKRAM_API_KEY` gesetzt und der Client ohne Argumente initialisiert.
+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
 {
@@ -186,14 +207,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
 {
@@ -218,17 +245,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
 
@@ -248,14 +277,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
 ```
@@ -263,21 +292,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
 ```
@@ -285,7 +314,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
 ```
@@ -293,21 +322,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
 ```
@@ -315,7 +344,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
 ```
@@ -323,21 +352,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
 ```
@@ -345,7 +374,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
 ```
@@ -353,21 +382,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
 ```
@@ -375,16 +404,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
@@ -394,9 +423,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
 
@@ -416,9 +445,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
 
@@ -438,9 +467,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
 
@@ -462,7 +491,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.
 
@@ -474,21 +503,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
 ```
 
@@ -514,7 +622,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. 🤗