fints-lib 0.7.0 → 0.9.0

package/dist/pin-tan-client.d.ts

@@ -3,6 +3,9 @@ import { Dialog, DialogConfig } from "./dialog";
 import { Request } from "./request";
 import { ConnectionConfig } from "./http-connection";
 import { Segment } from "./segments";
+import { DecoupledTanConfig, DecoupledTanStatusCallback } from "./decoupled-tan";
+import { TanRequiredError } from "./errors/tan-required-error";
+import { Response } from "./response";
 /**
  * Set of options needed to construct a `PinTanClient`.
  */
@@ -31,6 +34,10 @@ export interface PinTanClientConfig extends Partial<ConnectionConfig> {
      * If set to `true`, will log all requests performed and responses received.
      */
     debug?: boolean;
+    /**
+     * Configuration for decoupled TAN (asynchronous authentication)
+     */
+    decoupledTanConfig?: DecoupledTanConfig;
 }
 export declare class PinTanClient extends Client {
     /**
@@ -44,4 +51,40 @@ export declare class PinTanClient extends Client {
     constructor(config: PinTanClientConfig);
     createDialog(dialogConfig?: DialogConfig): Dialog;
     createRequest(dialog: Dialog, segments: Segment<any>[], tan?: string): Request;
+    /**
+     * Handle a decoupled TAN challenge with automatic polling
+     *
+     * High-level method for handling decoupled TAN authentication flow.
+     * Automatically manages the polling lifecycle and provides status updates
+     * through an optional callback.
+     *
+     * **Usage Pattern:**
+     * ```typescript
+     * try {
+     *   await client.creditTransfer(account, transfer);
+     * } catch (error) {
+     *   if (error instanceof TanRequiredError && error.isDecoupledTan()) {
+     *     await client.handleDecoupledTanChallenge(error, (status) => {
+     *       console.log(`State: ${status.state}, Requests: ${status.statusRequestCount}`);
+     *     });
+     *   }
+     * }
+     * ```
+     *
+     * **FinTS Specification:**
+     * - Implements tanProcess="2" polling per FinTS 3.0 PINTAN
+     * - Uses HKTAN segment for status checks
+     * - Respects server timing from HITANS segment
+     *
+     * @param error The TanRequiredError that contains the challenge information
+     * @param statusCallback Optional callback for status updates during polling
+     * @return The final response after confirmation
+     *
+     * @throws {Error} If the error is not a decoupled TAN challenge
+     * @throws {DecoupledTanError} If polling fails (timeout, cancellation, etc.)
+     *
+     * @see Dialog.handleDecoupledTan for lower-level control
+     * @see https://www.hbci-zka.de/ for FinTS specification
+     */
+    handleDecoupledTanChallenge(error: TanRequiredError, statusCallback?: DecoupledTanStatusCallback): Promise<Response>;
 }

package/dist/pin-tan-client.js

@@ -1,4 +1,13 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PinTanClient = void 0;
 const client_1 = require("./client");
@@ -21,15 +30,60 @@ class PinTanClient extends client_1.Client {
         this.connection = new http_connection_1.HttpConnection(connectionConfig);
     }
     createDialog(dialogConfig) {
-        const { blz, name, pin, productId = constants_1.PRODUCT_NAME } = this.config;
+        const { blz, name, pin, productId = constants_1.PRODUCT_NAME, decoupledTanConfig } = this.config;
         const { connection } = this;
-        return new dialog_1.Dialog(dialogConfig ? dialogConfig : { blz, name, pin, systemId: "0", productId }, connection);
+        return new dialog_1.Dialog(dialogConfig ? dialogConfig : { blz, name, pin, systemId: "0", productId }, connection, decoupledTanConfig);
     }
     createRequest(dialog, segments, tan) {
         const { blz, name, pin } = this.config;
         const { systemId, dialogId, msgNo, tanMethods } = dialog;
         return new request_1.Request({ blz, name, pin, systemId, dialogId, msgNo, segments, tanMethods, tan });
     }
+    /**
+     * Handle a decoupled TAN challenge with automatic polling
+     *
+     * High-level method for handling decoupled TAN authentication flow.
+     * Automatically manages the polling lifecycle and provides status updates
+     * through an optional callback.
+     *
+     * **Usage Pattern:**
+     * ```typescript
+     * try {
+     *   await client.creditTransfer(account, transfer);
+     * } catch (error) {
+     *   if (error instanceof TanRequiredError && error.isDecoupledTan()) {
+     *     await client.handleDecoupledTanChallenge(error, (status) => {
+     *       console.log(`State: ${status.state}, Requests: ${status.statusRequestCount}`);
+     *     });
+     *   }
+     * }
+     * ```
+     *
+     * **FinTS Specification:**
+     * - Implements tanProcess="2" polling per FinTS 3.0 PINTAN
+     * - Uses HKTAN segment for status checks
+     * - Respects server timing from HITANS segment
+     *
+     * @param error The TanRequiredError that contains the challenge information
+     * @param statusCallback Optional callback for status updates during polling
+     * @return The final response after confirmation
+     *
+     * @throws {Error} If the error is not a decoupled TAN challenge
+     * @throws {DecoupledTanError} If polling fails (timeout, cancellation, etc.)
+     *
+     * @see Dialog.handleDecoupledTan for lower-level control
+     * @see https://www.hbci-zka.de/ for FinTS specification
+     */
+    handleDecoupledTanChallenge(error, statusCallback) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!error.isDecoupledTan()) {
+                throw new Error("The provided TanRequiredError does not represent a decoupled TAN challenge. " +
+                    "Only call handleDecoupledTanChallenge when error.isDecoupledTan() returns true. " +
+                    "For regular TAN challenges, use your normal TAN handling flow instead.");
+            }
+            return error.dialog.handleDecoupledTan(error.transactionReference, error.challengeText, statusCallback);
+        });
+    }
 }
 exports.PinTanClient = PinTanClient;
 //# sourceMappingURL=pin-tan-client.js.map

package/dist/pin-tan-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"pin-tan-client.js","sourceRoot":"","sources":["../src/pin-tan-client.ts"],"names":[],"mappings":";;;AAAA,qCAAkC;AAClC,qCAAgD;AAChD,uCAAoC;AACpC,uDAAqE;AAGrE,2CAA2C;AAgC3C,MAAa,YAAa,SAAQ,eAAM;IAUpC,YAAY,MAA0B;QAClC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QAC/D,MAAM,gBAAgB,GAAqB;YACvC,GAAG;YACH,KAAK,EAAE,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,KAAK;YACrB,OAAO,EAAE,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,KAAK;YACzB,UAAU,EAAE,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,CAAC;YAC3B,UAAU,EAAE,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,IAAI;SACjC,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,IAAI,gCAAc,CAAC,gBAAgB,CAAC,CAAC;IAC3D,CAAC;IAEM,YAAY,CAAC,YAA2B;QAC3C,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,GAAG,wBAAY,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACjE,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;QAC5B,OAAO,IAAI,eAAM,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;IAC9G,CAAC;IAEM,aAAa,CAAC,MAAc,EAAE,QAAwB,EAAE,GAAY;QACvE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACvC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QACzD,OAAO,IAAI,iBAAO,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACjG,CAAC;CACJ;AAnCD,oCAmCC"}
+{"version":3,"file":"pin-tan-client.js","sourceRoot":"","sources":["../src/pin-tan-client.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAAkC;AAClC,qCAAgD;AAChD,uCAAoC;AACpC,uDAAqE;AAGrE,2CAA2C;AAuC3C,MAAa,YAAa,SAAQ,eAAM;IAUpC,YAAY,MAA0B;QAClC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QAC/D,MAAM,gBAAgB,GAAqB;YACvC,GAAG;YACH,KAAK,EAAE,KAAK,aAAL,KAAK,cAAL,KAAK,GAAI,KAAK;YACrB,OAAO,EAAE,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,KAAK;YACzB,UAAU,EAAE,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,CAAC;YAC3B,UAAU,EAAE,UAAU,aAAV,UAAU,cAAV,UAAU,GAAI,IAAI;SACjC,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,IAAI,gCAAc,CAAC,gBAAgB,CAAC,CAAC;IAC3D,CAAC;IAEM,YAAY,CAAC,YAA2B;QAC3C,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,GAAG,wBAAY,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACrF,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;QAC5B,OAAO,IAAI,eAAM,CACb,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,EAC1E,UAAU,EACV,kBAAkB,CACrB,CAAC;IACN,CAAC;IAEM,aAAa,CAAC,MAAc,EAAE,QAAwB,EAAE,GAAY;QACvE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACvC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;QACzD,OAAO,IAAI,iBAAO,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IACjG,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACU,2BAA2B,CACpC,KAAuB,EACvB,cAA2C;;YAE3C,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACX,8EAA8E;oBAC1E,kFAAkF;oBAClF,wEAAwE,CAC/E,CAAC;YACN,CAAC;YAED,OAAO,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC,KAAK,CAAC,oBAAoB,EAAE,KAAK,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;QAC5G,CAAC;KAAA;CACJ;AAzFD,oCAyFC"}

package/dist/segments/hnsha.d.ts

@@ -14,5 +14,10 @@ export declare class HNSHA extends HNSHA_base {
     protected defaults(): void;
     protected serialize(): (string | string[])[];
     protected deserialize(): void;
+    /**
+     * Override debugString to mask sensitive data (PIN/TAN).
+     * This prevents credentials from being exposed in logs.
+     */
+    get debugString(): string | string[];
 }
 export {};

package/dist/segments/hnsha.js

@@ -25,6 +25,26 @@ class HNSHA extends (0, segment_1.SegmentClass)(HNSHAProps) {
     deserialize() {
         throw new Error("Not implemented.");
     }
+    /**
+     * Override debugString to mask sensitive data (PIN/TAN).
+     * This prevents credentials from being exposed in logs.
+     */
+    get debugString() {
+        const info = `Type: ${this.type}\n` +
+            `Version: ${this.version}\n` +
+            `Segment Number: ${this.segNo}\n` +
+            `Referencing: ${this.reference === undefined ? "None" : this.reference}\n` +
+            `----\n`;
+        const { secRef, tan } = this;
+        const maskedData = [
+            format_1.Format.num(secRef),
+            format_1.Format.empty(),
+            tan ? ["***MASKED***", "***MASKED***"] : "***MASKED***",
+        ];
+        return maskedData.reduce((result, group, index) => {
+            return `${result}DG ${index}: ${Array.isArray(group) ? group.join(", ") : group}\n`;
+        }, info);
+    }
 }
 exports.HNSHA = HNSHA;
 //# sourceMappingURL=hnsha.js.map

package/dist/segments/hnsha.js.map

@@ -1 +1 @@
-{"version":3,"file":"hnsha.js","sourceRoot":"","sources":["../../src/segments/hnsha.ts"],"names":[],"mappings":";;;AAAA,uCAAyC;AACzC,sCAAmC;AAEnC,MAAa,UAAU;CAKtB;AALD,gCAKC;AAED;;;GAGG;AACH,MAAa,KAAM,SAAQ,IAAA,sBAAY,EAAC,UAAU,CAAC;IAAnD;;QACW,SAAI,GAAG,OAAO,CAAC;IAc1B,CAAC;IAZa,QAAQ;QACd,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACrB,CAAC;IAES,SAAS;QACf,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAClC,OAAO,CAAC,eAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,eAAM,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;IAES,WAAW;QACjB,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACxC,CAAC;CACJ;AAfD,sBAeC"}
+{"version":3,"file":"hnsha.js","sourceRoot":"","sources":["../../src/segments/hnsha.ts"],"names":[],"mappings":";;;AAAA,uCAAyC;AACzC,sCAAmC;AAEnC,MAAa,UAAU;CAKtB;AALD,gCAKC;AAED;;;GAGG;AACH,MAAa,KAAM,SAAQ,IAAA,sBAAY,EAAC,UAAU,CAAC;IAAnD;;QACW,SAAI,GAAG,OAAO,CAAC;IAoC1B,CAAC;IAlCa,QAAQ;QACd,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACrB,CAAC;IAES,SAAS;QACf,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAClC,OAAO,CAAC,eAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,eAAM,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxE,CAAC;IAES,WAAW;QACjB,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,IAAW,WAAW;QAClB,MAAM,IAAI,GACN,SAAS,IAAI,CAAC,IAAI,IAAI;YACtB,YAAY,IAAI,CAAC,OAAO,IAAI;YAC5B,mBAAmB,IAAI,CAAC,KAAK,IAAI;YACjC,gBAAgB,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI;YAC1E,QAAQ,CAAC;QACb,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC7B,MAAM,UAAU,GAAG;YACf,eAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAClB,eAAM,CAAC,KAAK,EAAE;YACd,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc;SAC1D,CAAC;QACF,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YAC9C,OAAO,GAAG,MAAM,MAAM,KAAK,KAAK,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;QACxF,CAAC,EAAE,IAAI,CAAC,CAAC;IACb,CAAC;CACJ;AArCD,sBAqCC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fints-lib",
-    "version": "0.7.0",
+    "version": "0.9.0",
     "description": "FinTS client library with psd2 support",
     "keywords": [
         "fints",
@@ -56,16 +56,16 @@
         "@types/invariant": "^2.2.37",
         "@types/isomorphic-fetch": "^0.0.39",
         "@types/istanbul-lib-report": "^3.0.3",
-        "@types/jest": "^29.5.14",
+        "@types/jest": "^30.0.0",
         "@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",
+        "jest": "^30.2.0",
+        "minimatch": "^10.1.1",
         "ts-jest": "^29.4.6",
-        "typedoc": "^0.27.9",
-        "typescript": "^5.8.0"
+        "typedoc": "^0.28.15",
+        "typescript": "^5.9.3"
     },
     "dependencies": {
         "bind-decorator": "^1.0.11",