fints-lib 0.6.0 → 0.7.0

package/dist/constants.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HBCI_VERSION = exports.COMPRESSION_NONE = exports.SECURITY_SUPPLIER_ROLE = exports.SECURITY_BOUNDARY = exports.SECURITY_FUNCTION = exports.HEADER_LENGTH = exports.PRODUCT_VERSION = exports.PRODUCT_NAME = exports.LANG_FR = exports.LANG_EN = exports.LANG_DE = exports.SYNC_MODE_SIGNATURE_ID = exports.SYNC_MODE_LAST_MSG_NUMBER = exports.SYNC_MODE_NEW_CUSTOMER_ID = exports.COUNTRY_CODE = void 0;
+exports.COUNTRY_CODE = 280;
+exports.SYNC_MODE_NEW_CUSTOMER_ID = 0;
+exports.SYNC_MODE_LAST_MSG_NUMBER = 1;
+exports.SYNC_MODE_SIGNATURE_ID = 2;
+exports.LANG_DE = 1;
+exports.LANG_EN = 2;
+exports.LANG_FR = 3;
+exports.PRODUCT_NAME = "fints";
+exports.PRODUCT_VERSION = "0.1";
+exports.HEADER_LENGTH = 29;
+exports.SECURITY_FUNCTION = "999";
+exports.SECURITY_BOUNDARY = 1;
+exports.SECURITY_SUPPLIER_ROLE = 1;
+exports.COMPRESSION_NONE = 0;
+exports.HBCI_VERSION = 300;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAG,GAAG,CAAC;AAEnB,QAAA,yBAAyB,GAAG,CAAC,CAAC;AAC9B,QAAA,yBAAyB,GAAG,CAAC,CAAC;AAC9B,QAAA,sBAAsB,GAAG,CAAC,CAAC;AAE3B,QAAA,OAAO,GAAG,CAAC,CAAC;AACZ,QAAA,OAAO,GAAG,CAAC,CAAC;AACZ,QAAA,OAAO,GAAG,CAAC,CAAC;AAEZ,QAAA,YAAY,GAAG,OAAO,CAAC;AACvB,QAAA,eAAe,GAAG,KAAK,CAAC;AAExB,QAAA,aAAa,GAAG,EAAE,CAAC;AAEnB,QAAA,iBAAiB,GAAG,KAAK,CAAC;AAC1B,QAAA,iBAAiB,GAAG,CAAC,CAAC;AACtB,QAAA,sBAAsB,GAAG,CAAC,CAAC;AAE3B,QAAA,gBAAgB,GAAG,CAAC,CAAC;AAErB,QAAA,YAAY,GAAG,GAAG,CAAC"}

package/dist/dialog.d.ts

@@ -0,0 +1,111 @@
+import { Connection } from "./types";
+import { HIUPD } from "./segments";
+import { Request } from "./request";
+import { Response } from "./response";
+import { TanMethod } from "./tan-method";
+/**
+ * Properties passed to configure a `Dialog`.
+ */
+export declare class DialogConfig {
+    /**
+     * The product ID that was assigned by ZKA
+     */
+    productId: string;
+    /**
+     * The banks identification number (Bankleitzahl).
+     */
+    blz: string;
+    /**
+     * The username or identification number.
+     */
+    name: string;
+    /**
+     * The pin code or password used for authenticating with the fints server.
+     */
+    pin: string;
+    /**
+     * The system's id. This id needs to be stored across all dialogs and will be assigned
+     * by the server at the first request.
+     */
+    systemId: string;
+}
+/**
+ * A dialog consisting of multiple related requests and responses.
+ */
+export declare class Dialog extends DialogConfig {
+    /**
+     * All messages sent within a dialog are numbered.
+     * This counter is kept here.
+     */
+    msgNo: number;
+    /**
+     * A unique id for the dialog.
+     * Assigned by the server as response to the initial request.
+     * For the initial request a `0` needs to be sent.
+     */
+    dialogId: string;
+    /**
+     * A list of allowed TAN methods as configured by the server.
+     */
+    tanMethods: TanMethod[];
+    /**
+     * The server will only accept a certain version for the HISALS segment.
+     * This version defaults to the latest version (6).
+     * The server's maximum supported version can be parsed from the initial requests and is stored here.
+     */
+    hisalsVersion: number;
+    /**
+     * The server will only accept a certain version for the HIKAZS segment.
+     * This version defaults to the latest version (6).
+     * The server's maximum supported version can be parsed from the initial requests and is stored here.
+     */
+    hikazsVersion: number;
+    /**
+     * The server will only accept a certain version for the HICDB segment.
+     * This version defaults to the latest version (1).
+     * The server's maximum supported version can be parsed from the initial requests and is stored here.
+     */
+    hicdbVersion: number;
+    hktanVersion: number;
+    hkdseVersion: number;
+    hkccsVersion: number;
+    /**
+     * The server will only accept a certain version for the HIWPD segment.
+     * Stores the maximum supported version parsed during synchronization.
+     */
+    hiwpdsVersion: number;
+    /**
+     * A list of supported SEPA pain-formats as configured by the server.
+     */
+    painFormats: string[];
+    hiupd: HIUPD[];
+    connection: Connection;
+    constructor(config: DialogConfig, connection: Connection);
+    /**
+     * Send a synchronization request to the server.
+     * Only one synchronization is needed per dialog.
+     * This is most likely the initial request sent.
+     * It will be answered with the system's id and a list of supported TAN methods.
+     * The supported HISALS and HIKAZS version can also be parsed from this request.
+     *
+     * @return The response as received by the server.
+     */
+    sync(): Promise<void>;
+    /**
+     * Send the initializing request to the server.
+     * The dialog is ready for performing custom requests afterwards.
+     */
+    init(): Promise<Response>;
+    /**
+     * End the currently open request.
+     */
+    end(): Promise<void>;
+    /**
+     * Send a custom request to the fints server and return the received response.
+     *
+     * @param request The request to send to the server.
+     *
+     * @return The response received from the server.
+     */
+    send(request: Request): Promise<Response>;
+}

package/dist/dialog.js

@@ -0,0 +1,187 @@
+"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.Dialog = exports.DialogConfig = void 0;
+const segments_1 = require("./segments");
+const request_1 = require("./request");
+const utils_1 = require("./utils");
+const response_error_1 = require("./errors/response-error");
+const tan_required_error_1 = require("./errors/tan-required-error");
+const hitan_1 = require("./segments/hitan");
+const constants_1 = require("./constants");
+/**
+ * Properties passed to configure a `Dialog`.
+ */
+class DialogConfig {
+    constructor() {
+        /**
+         * The product ID that was assigned by ZKA
+         */
+        this.productId = constants_1.PRODUCT_NAME;
+    }
+}
+exports.DialogConfig = DialogConfig;
+/**
+ * A dialog consisting of multiple related requests and responses.
+ */
+class Dialog extends DialogConfig {
+    constructor(config, connection) {
+        super();
+        /**
+         * All messages sent within a dialog are numbered.
+         * This counter is kept here.
+         */
+        this.msgNo = 1;
+        /**
+         * A unique id for the dialog.
+         * Assigned by the server as response to the initial request.
+         * For the initial request a `0` needs to be sent.
+         */
+        this.dialogId = "0";
+        /**
+         * A list of allowed TAN methods as configured by the server.
+         */
+        this.tanMethods = [];
+        /**
+         * The server will only accept a certain version for the HISALS segment.
+         * This version defaults to the latest version (6).
+         * The server's maximum supported version can be parsed from the initial requests and is stored here.
+         */
+        this.hisalsVersion = 6;
+        /**
+         * The server will only accept a certain version for the HIKAZS segment.
+         * This version defaults to the latest version (6).
+         * The server's maximum supported version can be parsed from the initial requests and is stored here.
+         */
+        this.hikazsVersion = 6;
+        /**
+         * The server will only accept a certain version for the HICDB segment.
+         * This version defaults to the latest version (1).
+         * The server's maximum supported version can be parsed from the initial requests and is stored here.
+         */
+        this.hicdbVersion = 1;
+        this.hktanVersion = 1;
+        this.hkdseVersion = 1;
+        this.hkccsVersion = 1;
+        /**
+         * The server will only accept a certain version for the HIWPD segment.
+         * Stores the maximum supported version parsed during synchronization.
+         */
+        this.hiwpdsVersion = 0;
+        /**
+         * A list of supported SEPA pain-formats as configured by the server.
+         */
+        this.painFormats = [];
+        Object.assign(this, config);
+        this.connection = connection;
+    }
+    /**
+     * Send a synchronization request to the server.
+     * Only one synchronization is needed per dialog.
+     * This is most likely the initial request sent.
+     * It will be answered with the system's id and a list of supported TAN methods.
+     * The supported HISALS and HIKAZS version can also be parsed from this request.
+     *
+     * @return The response as received by the server.
+     */
+    sync() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { blz, name, pin, systemId, dialogId, msgNo } = this;
+            const segments = [
+                new segments_1.HKIDN({ segNo: 3, blz, name, systemId: "0" }),
+                new segments_1.HKVVB({ segNo: 4, productId: this.productId, lang: 0 }),
+                new segments_1.HKSYN({ segNo: 5 }),
+            ];
+            const response = yield this.send(new request_1.Request({ blz, name, pin, systemId, dialogId, msgNo, segments }));
+            this.systemId = (0, utils_1.escapeFinTS)(response.systemId);
+            this.dialogId = response.dialogId;
+            this.hisalsVersion = response.segmentMaxVersion(segments_1.HISALS);
+            this.hikazsVersion = response.segmentMaxVersion(segments_1.HIKAZS);
+            this.hicdbVersion = response.segmentMaxVersion(segments_1.HICDBS);
+            const hkdseVersion = response.segmentMaxVersion(segments_1.HIDSES);
+            this.hkdseVersion = hkdseVersion > 0 ? hkdseVersion : 1;
+            const hkccsVersion = response.segmentMaxVersion(segments_1.HICCSS);
+            this.hkccsVersion = hkccsVersion > 0 ? hkccsVersion : 1;
+            this.hiwpdsVersion = response.segmentMaxVersion(segments_1.HIWPDS);
+            this.hktanVersion = response.segmentMaxVersion(segments_1.HITANS);
+            this.tanMethods = response.supportedTanMethods;
+            this.painFormats = response.painFormats;
+            const hiupd = response.findSegments(segments_1.HIUPD);
+            this.hiupd = hiupd;
+            yield this.end();
+        });
+    }
+    /**
+     * Send the initializing request to the server.
+     * The dialog is ready for performing custom requests afterwards.
+     */
+    init() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { blz, name, pin, dialogId, msgNo, tanMethods } = this;
+            const segments = [
+                new segments_1.HKIDN({ segNo: 3, blz, name, systemId: "0" }),
+                new segments_1.HKVVB({ segNo: 4, productId: this.productId, lang: 0 }),
+            ];
+            if (this.hktanVersion >= 6) {
+                const version = this.hktanVersion >= 7 ? 7 : 6;
+                segments.push(new segments_1.HKTAN({ segNo: 5, version, process: "4" }));
+            }
+            const response = yield this.send(new request_1.Request({ blz, name, pin, systemId: "0", dialogId, msgNo, segments, tanMethods }));
+            this.dialogId = response.dialogId;
+            return response;
+        });
+    }
+    /**
+     * End the currently open request.
+     */
+    end() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { blz, name, pin, systemId, dialogId, msgNo } = this;
+            const segments = [new segments_1.HKEND({ segNo: 3, dialogId })];
+            yield this.send(new request_1.Request({ blz, name, pin, systemId, dialogId, msgNo, segments }));
+            this.dialogId = "0";
+            this.msgNo = 1;
+        });
+    }
+    /**
+     * Send a custom request to the fints server and return the received response.
+     *
+     * @param request The request to send to the server.
+     *
+     * @return The response received from the server.
+     */
+    send(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            request.msgNo = this.msgNo;
+            request.dialogId = this.dialogId;
+            request.tanMethods = this.tanMethods;
+            const response = yield this.connection.send(request);
+            this.dialogId = response.dialogId;
+            if (!response.success) {
+                throw new response_error_1.ResponseError(response);
+            }
+            if (response.returnValues().has("0030")) {
+                const hitan = response.findSegment(hitan_1.HITAN);
+                const returnValue = response.returnValues().get("0030");
+                // Determine which segment triggered the TAN requirement
+                const triggeringSegment = request.segments.length > 0 ? request.segments[0].type : undefined;
+                throw new tan_required_error_1.TanRequiredError(returnValue.message, hitan.transactionReference, hitan.challengeText, hitan.challengeMedia, this, tan_required_error_1.TanProcessStep.CHALLENGE_RESPONSE_NEEDED, triggeringSegment, {
+                    returnCode: "0030",
+                    requestSegments: request.segments.map((s) => s.type),
+                });
+            }
+            this.msgNo++;
+            return response;
+        });
+    }
+}
+exports.Dialog = Dialog;
+//# sourceMappingURL=dialog.js.map

package/dist/dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog.js","sourceRoot":"","sources":["../src/dialog.ts"],"names":[],"mappings":"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"}

package/dist/error-codes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * FinTS Error and Return Code Mappings
+ * Based on FinTS 3.0 specification
+ *
+ * Code ranges:
+ * 0xxx - Success messages
+ * 3xxx - Warnings
+ * 9xxx - Errors
+ */
+export interface FinTSErrorCodeInfo {
+    code: string;
+    message: string;
+    category: "success" | "warning" | "error";
+    description: string;
+}
+/**
+ * Complete mapping of FinTS return codes
+ */
+export declare const FINTS_ERROR_CODES: Record<string, FinTSErrorCodeInfo>;
+/**
+ * Get error code information
+ */
+export declare function getErrorCodeInfo(code: string): FinTSErrorCodeInfo | undefined;
+/**
+ * Check if a code represents a success
+ */
+export declare function isSuccessCode(code: string): boolean;
+/**
+ * Check if a code represents a warning
+ */
+export declare function isWarningCode(code: string): boolean;
+/**
+ * Check if a code represents an error
+ */
+export declare function isErrorCode(code: string): boolean;
+/**
+ * Get a human-readable error message with code
+ */
+export declare function formatErrorCode(code: string, originalMessage?: string): string;

package/dist/error-codes.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * FinTS Error and Return Code Mappings
+ * Based on FinTS 3.0 specification
+ *
+ * Code ranges:
+ * 0xxx - Success messages
+ * 3xxx - Warnings
+ * 9xxx - Errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINTS_ERROR_CODES = void 0;
+exports.getErrorCodeInfo = getErrorCodeInfo;
+exports.isSuccessCode = isSuccessCode;
+exports.isWarningCode = isWarningCode;
+exports.isErrorCode = isErrorCode;
+exports.formatErrorCode = formatErrorCode;
+/**
+ * Complete mapping of FinTS return codes
+ */
+exports.FINTS_ERROR_CODES = {
+    // Success codes (0xxx)
+    "0010": {
+        code: "0010",
+        message: "Nachricht entgegengenommen",
+        category: "success",
+        description: "Message successfully received",
+    },
+    "0020": {
+        code: "0020",
+        message: "Dialoginitialisierung erfolgreich",
+        category: "success",
+        description: "Dialog initialization successful",
+    },
+    "0030": {
+        code: "0030",
+        message: "Auftrag entgegengenommen - Sicherheitsfreigabe erforderlich",
+        category: "success",
+        description: "Order received - TAN/Security clearance required",
+    },
+    "0100": {
+        code: "0100",
+        message: "Dialog beendet",
+        category: "success",
+        description: "Dialog ended successfully",
+    },
+    // Warning codes (3xxx)
+    "3010": {
+        code: "3010",
+        message: "Teilweise fehlerhaft",
+        category: "warning",
+        description: "Partially erroneous",
+    },
+    "3040": {
+        code: "3040",
+        message: "Auftragsdaten liegen nicht vollständig vor - weitere Auftragsdaten benötigt",
+        category: "warning",
+        description: "Order data not complete - more data needed (touchdown)",
+    },
+    "3050": {
+        code: "3050",
+        message: "Auftragsart derzeit nicht zugelassen",
+        category: "warning",
+        description: "Order type currently not permitted",
+    },
+    "3060": {
+        code: "3060",
+        message: "Teilweise fehlerhaft, Restdaten folgen",
+        category: "warning",
+        description: "Partially erroneous, remaining data follows",
+    },
+    "3076": {
+        code: "3076",
+        message: "Starke Kundenauthentifizierung notwendig",
+        category: "warning",
+        description: "Strong customer authentication necessary (PSD2)",
+    },
+    "3920": {
+        code: "3920",
+        message: "Zugelassene Zwei-Schritt-Verfahren für den Benutzer",
+        category: "warning",
+        description: "Permitted two-step procedures for the user",
+    },
+    "3956": {
+        code: "3956",
+        message: "Starke Kundenauthentifizierung notwendig",
+        category: "warning",
+        description: "Strong customer authentication necessary",
+    },
+    // Error codes (9xxx)
+    "9010": {
+        code: "9010",
+        message: "Nachrichtenaufbau fehlerhaft",
+        category: "error",
+        description: "Message structure error",
+    },
+    "9030": {
+        code: "9030",
+        message: "Nachrichtenkopf fehlerhaft",
+        category: "error",
+        description: "Message header error",
+    },
+    "9040": {
+        code: "9040",
+        message: "Nachrichten-Ende fehlerhaft",
+        category: "error",
+        description: "Message end error",
+    },
+    "9050": {
+        code: "9050",
+        message: "Nachrichtensignatur fehlerhaft oder fehlt",
+        category: "error",
+        description: "Message signature error or missing",
+    },
+    "9070": {
+        code: "9070",
+        message: "Test-BPD/UPD nicht mehr aktuell",
+        category: "error",
+        description: "Test BPD/UPD no longer current",
+    },
+    "9080": {
+        code: "9080",
+        message: "Teilnehmer im Testsystem nicht vorhanden",
+        category: "error",
+        description: "Participant not present in test system",
+    },
+    "9110": {
+        code: "9110",
+        message: "Kunde nicht berechtigt",
+        category: "error",
+        description: "Customer not authorized",
+    },
+    "9120": {
+        code: "9120",
+        message: "Auftrag nicht zugelassen",
+        category: "error",
+        description: "Order not permitted",
+    },
+    "9130": {
+        code: "9130",
+        message: "Maximale Anzahl Aufträge überschritten",
+        category: "error",
+        description: "Maximum number of orders exceeded",
+    },
+    "9140": {
+        code: "9140",
+        message: "Geschäftsvorfall nicht zugelassen",
+        category: "error",
+        description: "Business transaction not permitted",
+    },
+    "9210": {
+        code: "9210",
+        message: "Feature nicht unterstützt",
+        category: "error",
+        description: "Feature not supported",
+    },
+    "9340": {
+        code: "9340",
+        message: "Nachricht abgelehnt",
+        category: "error",
+        description: "Message rejected",
+    },
+    "9380": {
+        code: "9380",
+        message: "Dialog abgebrochen",
+        category: "error",
+        description: "Dialog aborted",
+    },
+    "9390": {
+        code: "9390",
+        message: "Nachricht doppelt",
+        category: "error",
+        description: "Duplicate message",
+    },
+    "9800": {
+        code: "9800",
+        message: "Dialog/Nachricht abgebrochen",
+        category: "error",
+        description: "Dialog/Message aborted",
+    },
+    "9931": {
+        code: "9931",
+        message: "Kundensystem-ID ungültig",
+        category: "error",
+        description: "Customer system ID invalid",
+    },
+    "9942": {
+        code: "9942",
+        message: "PIN falsch",
+        category: "error",
+        description: "PIN incorrect",
+    },
+};
+/**
+ * Get error code information
+ */
+function getErrorCodeInfo(code) {
+    return exports.FINTS_ERROR_CODES[code];
+}
+/**
+ * Check if a code represents a success
+ */
+function isSuccessCode(code) {
+    return code.startsWith("0");
+}
+/**
+ * Check if a code represents a warning
+ */
+function isWarningCode(code) {
+    return code.startsWith("3");
+}
+/**
+ * Check if a code represents an error
+ */
+function isErrorCode(code) {
+    return code.startsWith("9");
+}
+/**
+ * Get a human-readable error message with code
+ */
+function formatErrorCode(code, originalMessage) {
+    const info = getErrorCodeInfo(code);
+    if (info) {
+        return `[${code}] ${info.message}${originalMessage && originalMessage !== info.message ? ` - ${originalMessage}` : ""}`;
+    }
+    return originalMessage ? `[${code}] ${originalMessage}` : `[${code}] Unknown error code`;
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../src/error-codes.ts"],"names":[],"mappings":"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"}

package/dist/errors/fints-error.d.ts

@@ -0,0 +1,55 @@
+import { ReturnValue } from "../return-value";
+/**
+ * Base class for FinTS-specific errors with enhanced error information
+ */
+export declare class FinTSError extends Error {
+    code: string;
+    returnValue?: ReturnValue;
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when customer authentication fails
+ */
+export declare class AuthenticationError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when an order/transaction is rejected
+ */
+export declare class OrderRejectedError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when the dialog is aborted by the server
+ */
+export declare class DialogAbortedError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when a message has structural errors
+ */
+export declare class MessageStructureError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when a PIN is incorrect
+ */
+export declare class PinError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when strong customer authentication is required (PSD2)
+ */
+export declare class StrongAuthenticationRequiredError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Error thrown when system/customer ID is invalid
+ */
+export declare class InvalidSystemIdError extends FinTSError {
+    constructor(message: string, code?: string, returnValue?: ReturnValue);
+}
+/**
+ * Factory function to create appropriate error based on error code
+ */
+export declare function createFinTSError(code: string, message: string, returnValue?: ReturnValue): FinTSError;