fints-lib 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Frederick Gnodtke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# fints-lib
+
+[![npm](https://img.shields.io/npm/v/fints-lib.svg)](https://www.npmjs.com/package/fints-lib)
+[![CI](https://github.com/larsdecker/fints/actions/workflows/ci.yml/badge.svg)](https://github.com/larsdecker/fints/actions/workflows/ci.yml)
+
+A client library for communicating with [FinTS servers](https://www.hbci-zka.de/).
+
+> **Note:** This is a fork and continuation of [Prior99/fints](https://github.com/Prior99/fints). Published as `fints-lib` on npm.
+
+## Installation
+
+```bash
+npm install fints-lib
+# or
+yarn add fints-lib
+```
+
+## Example
+
+```typescript
+import { PinTanClient } from "fints-lib";
+
+const startDate = new Date("2018-08-10T12:00:00Z");
+const endDate = new Date("2018-10-10T12:00:00Z");
+
+const client = new PinTanClient({
+    url: "https://example.com/fints",
+    name: "username",
+    pin: 12345,
+    blz: 12345678,
+});
+
+const accounts = await client.accounts();
+console.info(accounts); // List of all accounts.
+
+const statements = await client.statements(accounts[0], startDate, endDate);
+console.info(statements); // List of all statements with transactions in specified date range.
+```
+
+
+### Handling login TAN challenges
+
+Some banks require a TAN as part of the login dialog. When that happens the library raises a `TanRequiredError`. The error now includes enhanced information about the TAN process state and context. You can complete the login by submitting the TAN and continue working with the returned dialog:
+
+```typescript
+import { TanRequiredError, TanProcessStep } from "fints-lib";
+
+try {
+    const accounts = await client.accounts();
+} catch (error) {
+    if (error instanceof TanRequiredError) {
+        // Enhanced error information
+        console.log("TAN Challenge:", error.challengeText);
+        console.log("Process Step:", error.getStepDescription());
+        console.log("Triggering Segment:", error.triggeringSegment);
+        console.log("Is Multi-Step:", error.isMultiStep());
+        
+        // Complete the login with TAN
+        const dialog = await client.completeLogin(error.dialog, error.transactionReference, "123456");
+        const accounts = await client.accounts(dialog);
+        await dialog.end();
+    }
+}
+```
+
+[Submitting SEPA credit transfers](#submitting-a-credit-transfer)
+[Submitting SEPA direct debits](#submitting-a-direct-debit)
+
+[Further code examples](README_advanced_usage.md)
+
+## Features
+
+- **FinTS 3.0 Compatibility**: Full support for FinTS 3.0 (HBCI version 300) protocol
+- **Enhanced Error Handling**: Comprehensive error code mapping with specific exception types
+- **Timeout & Retry**: Configurable HTTP timeouts and automatic retry with exponential backoff
+- **Multi-Step TAN Flows**: Enhanced support for complex TAN authentication flows
+- Load list of accounts.
+- Load list of statements and transactions in specified range.
+- Fetch current account balances.
+- List depot holdings.
+- Initiate SEPA credit transfers (pain.001) with TAN handling.
+- Submit SEPA direct debit orders (pain.008) with TAN handling.
+- Parse statement [MT940](https://en.wikipedia.org/wiki/MT940) format.
+- Parse transaction descriptions.
+- Extract [reference tags](https://www.dzbank.de/content/dam/dzbank_de/de/home/produkte_services/Firmenkunden/PDF-Dokumente/transaction%20banking/elektronicBanking/SEPA-Belegungsregeln_MT940-DK_082016.~644b217ec96b35dfffcaf18dc2df800a.pdf) from transactions.
+- List supported TAN methods.
+- Parse basic metadata.
+
+## Configuration Options
+
+### Basic Configuration
+
+```typescript
+const client = new PinTanClient({
+    url: "https://example.com/fints",
+    name: "username",
+    pin: 12345,
+    blz: 12345678,
+});
+```
+
+### Advanced Configuration with Timeout & Retry
+
+```typescript
+const client = new PinTanClient({
+    url: "https://example.com/fints",
+    name: "username",
+    pin: 12345,
+    blz: 12345678,
+    // Optional: Configure HTTP timeout (default: 30000ms)
+    timeout: 45000,
+    // Optional: Configure max retry attempts (default: 3)
+    maxRetries: 5,
+    // Optional: Configure retry delay for exponential backoff (default: 1000ms)
+    retryDelay: 2000,
+    // Optional: Enable debug mode
+    debug: true,
+});
+```
+
+## Error Handling
+
+The library now provides comprehensive error handling with specific exception types:
+
+```typescript
+import {
+    FinTSError,
+    AuthenticationError,
+    PinError,
+    OrderRejectedError,
+    DialogAbortedError,
+    StrongAuthenticationRequiredError,
+} from "fints-lib";
+
+try {
+    const accounts = await client.accounts();
+} catch (error) {
+    if (error instanceof PinError) {
+        console.error("PIN is incorrect:", error.message);
+    } else if (error instanceof AuthenticationError) {
+        console.error("Authentication failed:", error.message);
+    } else if (error instanceof StrongAuthenticationRequiredError) {
+        console.error("Strong customer authentication (PSD2) required:", error.message);
+    } else if (error instanceof FinTSError) {
+        console.error("FinTS error:", error.code, error.message);
+    }
+}
+```
+
+### Error Code Mapping
+
+All FinTS error codes are now mapped to descriptive messages:
+
+```typescript
+import { formatErrorCode, getErrorCodeInfo } from "fints-lib";
+
+// Get detailed information about an error code
+const info = getErrorCodeInfo("9942"); // PIN incorrect
+console.log(info.category); // "error"
+console.log(info.message); // "PIN falsch"
+
+// Format error code with message
+const formatted = formatErrorCode("9942", "Custom message");
+// Output: "[9942] PIN falsch - Custom message"
+```
+
+## Missing
+
+
+## Submitting a credit transfer
+
+```typescript
+import { PinTanClient, TanRequiredError, CreditTransferRequest } from "fints-lib";
+
+const client = new PinTanClient({
+    url: "https://example.com/fints",
+    name: "username",
+    pin: 12345,
+    blz: 12345678,
+});
+
+const accounts = await client.accounts();
+const account = accounts[0];
+
+const transfer: CreditTransferRequest = {
+    debtorName: "John Doe",
+    creditor: {
+        name: "ACME GmbH",
+        iban: "DE44500105175407324931",
+        bic: "INGDDEFFXXX",
+    },
+    amount: 100.0,
+    remittanceInformation: "Invoice 0815",
+};
+
+try {
+    const submission = await client.creditTransfer(account, transfer);
+    console.log(submission.taskId);
+} catch (error) {
+    if (error instanceof TanRequiredError) {
+        const submission = error.creditTransferSubmission!;
+        const completed = await client.completeCreditTransfer(
+            error.dialog,
+            error.transactionReference,
+            "123456",
+            submission,
+        );
+        console.log(completed.taskId);
+    }
+}
+```
+
+## Submitting a direct debit
+
+```typescript
+import { PinTanClient, TanRequiredError, DirectDebitRequest } from "fints-lib";
+
+const client = new PinTanClient({
+    url: "https://example.com/fints",
+    name: "username",
+    pin: 12345,
+    blz: 12345678,
+});
+
+const accounts = await client.accounts();
+const account = accounts[0];
+
+const debit: DirectDebitRequest = {
+    creditorName: "ACME GmbH",
+    creditorId: "DE98ZZZ09999999999",
+    debtor: {
+        name: "John Doe",
+        iban: "DE02120300000000202051",
+    },
+    amount: 42.5,
+    mandateId: "MANDATE-123",
+    mandateSignatureDate: new Date("2022-01-10"),
+    requestedCollectionDate: new Date(),
+    remittanceInformation: "Invoice 0815",
+};
+
+try {
+    const submission = await client.directDebit(account, debit);
+    console.log(submission.taskId);
+} catch (error) {
+    if (error instanceof TanRequiredError) {
+        const submission = error.directDebitSubmission!;
+        const completed = await client.completeDirectDebit(
+            error.dialog,
+            error.transactionReference,
+            "123456",
+            submission,
+        );
+        console.log(completed.taskId);
+    }
+}
+```
+
+## Resources
+
+- [API Reference](https://prior99.gitlab.io/fints)
+- [Official specification](https://www.hbci-zka.de/spec/3_0.htm)
+- [Database of banks with their URLs](https://github.com/jhermsmeier/fints-institute-db)

package/package.json

@@ -0,0 +1,80 @@
+{
+    "name": "fints-lib",
+    "version": "0.6.0",
+    "description": "FinTS client library with psd2 support",
+    "keywords": [
+        "fints",
+        "hbci",
+        "banking",
+        "api",
+        "ios",
+        "nodejs",
+        "node",
+        "psd2",
+        "sepa",
+        "mt940",
+        "pain.001",
+        "pain.008",
+        "german-banking",
+        "online-banking"
+    ],
+    "scripts": {
+        "prebuild": "cxsd -t generated https://raw.githubusercontent.com/hbci4j/hbci4java/master/src/main/resources/pain.001.001.03.xsd",
+        "build": "tsc -p ./tsconfig-build.json",
+        "clean": "rm -rf dist",
+        "docs": "typedoc --mode file --out docs/ src/",
+        "test": "TZ=UTC jest --testPathIgnorePatterns=test-pin-tan-client-e2e",
+        "test:acceptance": "TZ=UTC jest test-pin-tan-client-e2e"
+    },
+    "files": [
+        "dist",
+        "LICENSE",
+        "package.json",
+        "README.md"
+    ],
+    "main": "dist/index.js",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/larsdecker/fints",
+        "directory": "packages/fints"
+    },
+    "typings": "dist/index.d.ts",
+    "author": "Frederick Gnodtke",
+    "contributors": [
+        {
+            "name": "Mathias Arens",
+            "email": "github@mathiasarens.de",
+            "url": "https://github.com/mathiasarens"
+        },
+        {
+            "name": "Lars Decker",
+            "url": "https://github.com/larsdecker"
+        }
+    ],
+    "license": "MIT",
+    "devDependencies": {
+        "@types/invariant": "^2.2.37",
+        "@types/isomorphic-fetch": "^0.0.39",
+        "@types/istanbul-lib-report": "^3.0.3",
+        "@types/jest": "^29.5.14",
+        "@types/node": "^25.0.3",
+        "cxsd": "^0.1.1",
+        "fetch-mock": "^12.6.0",
+        "fints-institute-db": "^0.16.0",
+        "jest": "^29.7.0",
+        "minimatch": "^10.0.1",
+        "ts-jest": "^29.4.6",
+        "typedoc": "^0.27.9",
+        "typescript": "^5.8.0"
+    },
+    "dependencies": {
+        "bind-decorator": "^1.0.11",
+        "date-fns": "^4.1.0",
+        "fast-xml-parser": "^5.3.3",
+        "iconv-lite": "^0.7.1",
+        "invariant": "^2.2.4",
+        "isomorphic-fetch": "^3.0.0",
+        "mt940-js": "^1.0.0",
+        "winston": "^3.19.0"
+    }
+}