From 345f84c0b201f6538db52ca10414e6723473ab20 Mon Sep 17 00:00:00 2001
From: dankito <git@dankito.net>
Date: Thu, 22 Aug 2024 17:07:02 +0200
Subject: [PATCH] Added README

---
 README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..ea4afeb8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,93 @@
+# Banking Client
+
+Library to abstract over different banking client implementations like [fints4k](https://git.dankito.net/codinux/fints4k).
+
+It's primary purpose is to abstract away the different implementation details and to create a common model that can be
+used in all projects directly or indirectly referencing it - Web Service, Middleware, Native Apps, HTML Apps - so that
+not each project has the implement to model again.
+
+## Setup
+
+### Gradle:
+
+```
+plugins {
+    kotlin("jvm") version "2.0.10" // or kotlin("multiplatform"), depending on your requirements
+}
+
+
+repositories {
+    mavenCentral()
+    maven {
+        setUrl("https://maven.dankito.net/api/packages/codinux/maven")
+    }
+}
+
+
+dependencies {
+    implementation("net.codinux.banking.client:fints4k-banking-client:0.5.0")
+}
+```
+
+
+## Usage
+
+### Get AccountData 
+
+Retrieves data like accounts, balance and booked transactions (Konten, Saldo und Kontoumsätze).
+
+Basically:
+
+```kotlin
+class ShowUsage {
+
+    private val bankCode = "" // Bankleitzahl deiner Bank
+
+    private val loginName = "" // Online-Banking Login Name mit dem du dich beim Online-Banking deiner Bank anmeldest
+
+    private val password = "" // Online-Banking Password mit dem du dich beim Online-Banking deiner Bank anmeldest
+
+
+    fun getAccountData() {
+        val client = FinTs4kBankingClientForCustomer(bankCode, loginName, password, SimpleBankingClientCallback())
+
+        val response = client.getAccountData()
+        
+        response.data?.let { data ->
+            val customer = data.customer
+            println("Kunde: ${customer.customerName} ${customer.accounts.size} Konten @ ${customer.bic} ${customer.bankName}")
+
+            println()
+            println("Konten:")
+            customer.accounts.sortedBy { it.type }.forEach { account ->
+                println("${account.identifier} ${account.productName} ${account.balance} ${account.currency}")
+            }
+
+            println()
+            println("Umsätze:")
+            data.bookedTransactions.forEach { transaction ->
+                println("${transaction.valueDate} ${transaction.amount} ${transaction.currency} ${transaction.otherPartyName ?: ""} - ${transaction.reference}")
+            }
+        }
+    }
+}
+```
+
+This fetches the booked account transactions of the last 90 days. In most cases no TAN is required for this.
+
+In case there is, add TAN handling in Client Callback:
+
+```kotlin
+val client = FinTs4kBankingClientForCustomer(bankCode, loginName, password, SimpleBankingClientCallback { tanChallenge, callback ->
+    val tan: String? = null // if a TAN is required, add a UI or ...
+    callback.invoke(EnterTanResult(tan)) // ...  set a break point here, get TAN e.g. from your TAN app, set tan variable in debugger view and resume debugger
+})
+```
+
+Add some error handling by checking `response.error`:
+
+```kotlin
+response.error?.let{ error ->
+    println("Could not fetch account data: ${error.internalError ?: error.errorMessagesFromBank.joinToString()}")
+}
+```
\ No newline at end of file