lib-fints 1.0.0

package/dist/config.js

@@ -0,0 +1,181 @@
+import { getSegmentDefinition } from './segments/registry.js';
+/**
+ * Configuration for the FinTS client
+ */
+export class FinTSConfig {
+    productId;
+    productVersion;
+    url;
+    bankIdentification;
+    userId;
+    pin;
+    tanMethodId;
+    tanMediaName;
+    customerId;
+    country;
+    bankingInformation;
+    debugEnabled = false;
+    constructor(productId, productVersion, url, bankIdentification, userId, pin, bankingInformation, tanMethodId, tanMediaName, customerId, country = 280) {
+        this.productId = productId;
+        this.productVersion = productVersion;
+        this.url = url;
+        this.bankIdentification = bankIdentification;
+        this.userId = userId;
+        this.pin = pin;
+        this.tanMethodId = tanMethodId;
+        this.tanMediaName = tanMediaName;
+        this.customerId = customerId;
+        this.country = country;
+        if (!productId) {
+            throw Error('productId needs to be provided in configuration');
+        }
+        if (!bankingInformation) {
+            this.bankingInformation = {
+                systemId: '0',
+                bankMessages: [],
+            };
+        }
+        else {
+            this.bankingInformation = bankingInformation;
+        }
+        if (!this.bankingUrl) {
+            throw Error('bank URL needs to be provided in configuration');
+        }
+        if (!this.countryCode) {
+            throw Error('countryCode needs to be provided in configuration');
+        }
+        if (!this.bankId) {
+            throw Error('bank ID (BLZ) needs to be provided in configuration');
+        }
+        if (tanMethodId) {
+            this.selectTanMethod(tanMethodId);
+        }
+        if (tanMediaName) {
+            this.selectTanMedia(tanMediaName);
+        }
+    }
+    /**
+     * Factory method to create a configuration for the first time use i.e. no previous banking information is available
+     * @param productId The product ID obtained by registering with ZKA, see https://www.hbci-zka.de/register/prod_register.htm
+     * @param productVersion The version of your end product
+     * @param url The banks FinTS endpoint URL
+     * @param bankId The bank ID (BLZ)
+     * @param userId The user ID
+     * @param pin The PIN to authenticate the user
+     * @param customerId An optional customer ID when this is not the same as the user ID
+     * @param countryCode The country code of the bank, defaults to 280 (Germany)
+     * @returns a FinTS configuration
+     */
+    static forFirstTimeUse(productId, productVersion, url, bankId, userId, pin, customerId, countryCode = 280) {
+        return new FinTSConfig(productId, productVersion, url, bankId, userId, pin, undefined, undefined, undefined, customerId, countryCode);
+    }
+    /**
+     * Factory method to create a configuration from existing banking information
+     * @param productId The product ID obtained by registering with ZKA, see https://www.hbci-zka.de/register/prod_register.htm
+     * @param productVersion The version of your end product
+     * @param bankingInformation The banking information obtained from a previous synchronization
+     * @param userId The user ID
+     * @param pin The PIN to authenticate the user
+     * @param tanMethodId The ID of the TAN method to use, see config.availableTanMethods
+     * @param tanMediaName The name of the TAN media to use, see config.selectedTanMethod.activeTanMedia
+     * @param customerId An optional customer ID when this is not the same as the user ID
+     * @param countryCode The country code of the bank, defaults to 280 (Germany)
+     * @returns a FinTS configuration
+     */
+    static fromBankingInformation(productId, productVersion, bankingInformation, userId, pin, tanMethodId, tanMediaName, customerId, countryCode = 280) {
+        return new FinTSConfig(productId, productVersion, undefined, undefined, userId, pin, bankingInformation, tanMethodId, tanMediaName, customerId, countryCode);
+    }
+    /**
+     * The FinTS URL of the bank
+     */
+    get bankingUrl() {
+        return this.bankingInformation.bpd?.url ?? this.url;
+    }
+    /**
+     * The country code of the bank
+     */
+    get countryCode() {
+        return this.bankingInformation.bpd?.countryCode ?? this.country;
+    }
+    /**
+     * The bank ID (BLZ)
+     */
+    get bankId() {
+        return this.bankingInformation.bpd?.bankId ?? this.bankIdentification;
+    }
+    /**
+     * A list of all available TAN methods for the user
+     */
+    get availableTanMethods() {
+        return (this.bankingInformation.bpd?.supportedTanMethods?.filter((m) => this.bankingInformation.bpd?.availableTanMethodIds?.includes(m.id)) ?? []);
+    }
+    /**
+     * Selects a TAN method by its ID for the user, see also FinTSConfig#availableTanMethods
+     * @param tanMethodId The ID of the TAN method to select, corresponding to an ID in availableTanMethods
+     */
+    selectTanMethod(tanMethodId) {
+        if (!this.bankingInformation.bpd?.availableTanMethodIds?.find((id) => id === tanMethodId)) {
+            throw new Error(`TAN Method '${tanMethodId}' not found in the available TAN methods in the BPD`);
+        }
+        this.tanMethodId = tanMethodId;
+    }
+    /**
+     * Selects a TAN media by its name for the user
+     * @param tanMediaName The name of the TAN media, corresponding to a name in selectedTanMethod.activeTanMedia
+     */
+    selectTanMedia(tanMediaName) {
+        if (tanMediaName && !this.tanMethodId) {
+            throw new Error('tanMediaName can only be used when a TAN method is also selected');
+        }
+        if (tanMediaName && !this.selectedTanMethod?.activeTanMedia?.includes(tanMediaName)) {
+            throw new Error(`TAN media '${tanMediaName}' not found in the active TAN media list for the selected TAN method`);
+        }
+        this.tanMediaName = tanMediaName;
+    }
+    /**
+     * The currently selected TAN method for the user
+     */
+    get selectedTanMethod() {
+        return this.availableTanMethods.find((t) => t.id === this.tanMethodId);
+    }
+    /**
+     * Checks if a transaction is supported by the bank
+     * @param transId The transaction ID
+     */
+    isTransactionSupported(transId) {
+        return this.bankingInformation.bpd?.allowedTransactions.find((t) => t.transId === transId) !== undefined;
+    }
+    /**
+     * Checks if a transaction is supported for a specific account
+     * @param accountNumber The account number
+     * @param transId The transaction ID
+     */
+    isAccountTransactionSupported(accountNumber, transId) {
+        const bankAccount = this.getBankAccount(accountNumber);
+        return !!bankAccount.allowedTransactions?.find((t) => t.transId === transId);
+    }
+    /**
+     * Gets the maximum supported transaction version of a transaction, considering this client's support and the bank's support
+     * @param transId The transaction ID
+     */
+    getMaxSupportedTransactionVersion(transId) {
+        const definition = getSegmentDefinition(transId);
+        if (!definition) {
+            throw new Error(`segment definition for ${transId} not registered`);
+        }
+        const allowedVersions = this.bankingInformation.bpd?.allowedTransactions.find((t) => t.transId === transId)?.versions ?? [];
+        const maxSupportedversion = allowedVersions.sort().findLast((version) => version <= definition.version) ?? undefined;
+        return maxSupportedversion;
+    }
+    /**
+     * Gets the bank account information for a specific account number
+     * @param accountNumber The account number
+     */
+    getBankAccount(accountNumber) {
+        const bankAccount = this.bankingInformation.upd?.bankAccounts.find((a) => a.accountNumber === accountNumber);
+        if (!bankAccount) {
+            throw Error(`Account ${accountNumber} not found in UPD`);
+        }
+        return bankAccount;
+    }
+}

package/dist/dataElements/AlphaNumeric.js

@@ -0,0 +1,24 @@
+import { DataElement } from './DataElement.js';
+import { finTsDecode, finTsEncode } from '../format.js';
+export class AlphaNumeric extends DataElement {
+    maxLength;
+    constructor(name, minCount = 0, maxCount = 1, maxLength, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.maxLength = maxLength;
+    }
+    encode(value) {
+        if (!value) {
+            return '';
+        }
+        if (value.indexOf('\n') >= 0 || value.indexOf('\r') >= 0) {
+            throw Error(`the AlphaNumeric value '${this.name}' must not contain CR or LF characters`);
+        }
+        if (this.maxLength && value.toString().length > this.maxLength) {
+            throw Error(`the AlphaNumeric value '${this.name}' must not exceed its maximum length`);
+        }
+        return finTsEncode(value.trim());
+    }
+    decode(text) {
+        return finTsDecode(text);
+    }
+}

package/dist/dataElements/Amount.js

@@ -0,0 +1,6 @@
+import { Float } from './Float.js';
+export class Amount extends Float {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, 15, minVersion, maxVersion);
+    }
+}

package/dist/dataElements/Binary.js

@@ -0,0 +1,20 @@
+import { DataElement } from './DataElement.js';
+export class Binary extends DataElement {
+    maxLength;
+    constructor(name, minCount = 0, maxCount = 1, maxLength, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.maxLength = maxLength;
+    }
+    encode(value) {
+        if (!value) {
+            return '';
+        }
+        if (this.maxLength && value.length > this.maxLength) {
+            throw Error(`the Binary value '${this.name}' must not exceed its maximum length`);
+        }
+        return `@${value.length}@${value}`;
+    }
+    decode(text) {
+        return text.slice(text.indexOf('@', 1) + 1);
+    }
+}

package/dist/dataElements/Country.js

@@ -0,0 +1,6 @@
+import { Digits } from './Digits.js';
+export class Country extends Digits {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, 3, minVersion, maxVersion);
+    }
+}

package/dist/dataElements/Currency.js

@@ -0,0 +1,6 @@
+import { AlphaNumeric } from './AlphaNumeric.js';
+export class Currency extends AlphaNumeric {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, 3, minVersion, maxVersion);
+    }
+}

package/dist/dataElements/Dat.js

@@ -0,0 +1,18 @@
+import { DataElement } from './DataElement.js';
+export class Dat extends DataElement {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+    }
+    encode(value) {
+        if (!value) {
+            return '';
+        }
+        return value.toISOString().substring(0, 10).replaceAll('-', '');
+    }
+    decode(text) {
+        return new Date(`${text.substring(0, 4)}-${text.substring(4, 6)}-${text.substring(6)}`);
+    }
+    toString(value) {
+        return super.toString(value?.toDateString());
+    }
+}

package/dist/dataElements/DataElement.js

@@ -0,0 +1,37 @@
+export class DataElement {
+    name;
+    minCount;
+    maxCount;
+    minVersion;
+    maxVersion;
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        this.name = name;
+        this.minCount = minCount;
+        this.maxCount = maxCount;
+        this.minVersion = minVersion;
+        this.maxVersion = maxVersion;
+        if (minCount < 0 || maxCount < 0 || minCount > maxCount) {
+            throw new Error('invalid count range');
+        }
+        if (minVersion && maxVersion && minVersion > maxVersion) {
+            throw new Error('invalid version range');
+        }
+    }
+    maxValueCount(version) {
+        return this.isInVersion(version) ? 1 : 0;
+    }
+    isInVersion(version) {
+        return (!this.minVersion || version >= this.minVersion) && (!this.maxVersion || version <= this.maxVersion);
+    }
+    toString(value) {
+        if (value !== undefined && value !== null && value !== '') {
+            return `${this.name}: ${value}`;
+        }
+        else if (this.minCount > 0) {
+            return `${this.name}: <MISSING>`;
+        }
+        else {
+            return '';
+        }
+    }
+}

package/dist/dataElements/Digits.js

@@ -0,0 +1,23 @@
+import { DataElement } from './DataElement.js';
+export class Digits extends DataElement {
+    digits;
+    constructor(name, minCount = 0, maxCount = 1, digits, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.digits = digits;
+    }
+    encode(value) {
+        if (this.digits < 1) {
+            throw Error('the number of digits in a Digits value must be greatet than zero');
+        }
+        if (!Number.isInteger(value) || value < 0) {
+            throw Error(`the Digits value '${this.name}' must be a positive integer`);
+        }
+        if (String(value).length > this.digits) {
+            throw Error(`the Digits value '${this.name}' must fit into the given number of digits`);
+        }
+        return value.toString().padStart(this.digits, '0');
+    }
+    decode(text) {
+        return Number.parseInt(text);
+    }
+}

package/dist/dataElements/Float.js

@@ -0,0 +1,21 @@
+import { DataElement } from './DataElement.js';
+export class Float extends DataElement {
+    maxLength;
+    constructor(name, minCount = 0, maxCount = 1, maxLength, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.maxLength = maxLength;
+    }
+    encode(value) {
+        if (value < 0) {
+            throw Error(`the Float value '${this.name}' must be positive`);
+        }
+        if (this.maxLength && value.toString().length > this.maxLength) {
+            throw Error(`the Float value '${this.name}' must not exceed its maximum length`);
+        }
+        const text = value.toString().replace('.', ',');
+        return text.indexOf(',') >= 0 ? text : text + ',';
+    }
+    decode(text) {
+        return Number.parseFloat(text.replace(',', '.'));
+    }
+}

package/dist/dataElements/Identification.js

@@ -0,0 +1,6 @@
+import { AlphaNumeric } from './AlphaNumeric.js';
+export class Identification extends AlphaNumeric {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, 30, minVersion, maxVersion);
+    }
+}

package/dist/dataElements/Numeric.js

@@ -0,0 +1,26 @@
+import { DataElement } from './DataElement.js';
+export class Numeric extends DataElement {
+    maxLength;
+    constructor(name, minCount = 0, maxCount = 1, maxLength, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.maxLength = maxLength;
+    }
+    encode(value) {
+        if (value === undefined || value === null) {
+            return '';
+        }
+        if (!Number.isInteger(value) || value < 0) {
+            throw Error(`the Numeric value '${this.name}' must be a positive integer`);
+        }
+        if (this.maxLength && value.toString().length > this.maxLength) {
+            throw Error(`the Numeric value '${this.name}' must not exceed its maximum length`);
+        }
+        return value.toString();
+    }
+    decode(text) {
+        return Number.parseInt(text);
+    }
+    static decode(text) {
+        return Number.parseInt(text);
+    }
+}

package/dist/dataElements/Text.js

@@ -0,0 +1,21 @@
+import { DataElement } from './DataElement.js';
+import { finTsDecode, finTsEncode } from '../format.js';
+export class Text extends DataElement {
+    maxLength;
+    constructor(name, minCount = 0, maxCount = 1, maxLength, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.maxLength = maxLength;
+    }
+    encode(value) {
+        if (!value) {
+            return '';
+        }
+        if (this.maxLength && value.length > this.maxLength) {
+            throw Error('a Text value must not exceed its maximum length');
+        }
+        return finTsEncode(value.trim());
+    }
+    decode(text) {
+        return finTsDecode(text);
+    }
+}

package/dist/dataElements/Time.js

@@ -0,0 +1,18 @@
+import { DataElement } from './DataElement.js';
+export class Time extends DataElement {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+    }
+    encode(value) {
+        if (!value) {
+            return '';
+        }
+        return value.toISOString().substring(11, 19).replaceAll(':', '');
+    }
+    decode(text) {
+        return new Date(`1970-01-01T${text.substring(0, 2)}:${text.substring(2, 4)}:${text.substring(4)}Z`);
+    }
+    toString(value) {
+        return super.toString(value?.toTimeString());
+    }
+}

package/dist/dataElements/YesNo.js

@@ -0,0 +1,18 @@
+import { DataElement } from './DataElement.js';
+export class YesNo extends DataElement {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+    }
+    encode(value) {
+        if (value === undefined || value === null) {
+            return '';
+        }
+        return value ? 'J' : 'N';
+    }
+    decode(text) {
+        if (text !== 'J' && text !== 'N') {
+            throw Error(`the YesNo value '${this.name}' must be the character J or N`);
+        }
+        return text === 'J';
+    }
+}

package/dist/dataGroups/Account.js

@@ -0,0 +1,12 @@
+import { DataGroup } from './DataGroup.js';
+import { Identification } from '../dataElements/Identification.js';
+import { BankIdentification } from './BankIdentification.js';
+export class AccountGroup extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [
+            new Identification('accountNumber', 1, 1),
+            new Identification('subAccountId', 0, 1),
+            new BankIdentification('bank', 1, 1),
+        ], minCount, maxCount, minVersion, maxVersion);
+    }
+}

package/dist/dataGroups/Balance.js

@@ -0,0 +1,15 @@
+import { Time } from '../dataElements/Time.js';
+import { Dat } from '../dataElements/Dat.js';
+import { AlphaNumeric } from '../dataElements/AlphaNumeric.js';
+import { DataGroup } from './DataGroup.js';
+import { MoneyGroup } from './Money.js';
+export class BalanceGroup extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [
+            new AlphaNumeric('creditDebit', 1, 1, 1),
+            new MoneyGroup('amount', 1, 1),
+            new Dat('date', 1, 1),
+            new Time('time', 0, 1),
+        ], minCount, maxCount, minVersion, maxVersion);
+    }
+}

package/dist/dataGroups/BankIdentification.js

@@ -0,0 +1,8 @@
+import { AlphaNumeric } from '../dataElements/AlphaNumeric.js';
+import { DataGroup } from './DataGroup.js';
+import { Country } from '../dataElements/Country.js';
+export class BankIdentification extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [new Country('country', 1, 1), new AlphaNumeric('bankId', 1, 1, 30)], minCount, maxCount, minVersion, maxVersion);
+    }
+}

package/dist/dataGroups/DataGroup.js

@@ -0,0 +1,54 @@
+import { DataElement } from '../dataElements/DataElement.js';
+import { decodeElements } from '../decoder.js';
+import { encodeElements } from '../encoder.js';
+export class DataGroup extends DataElement {
+    elements;
+    constructor(name, elements, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, minCount, maxCount, minVersion, maxVersion);
+        this.elements = elements;
+        if (!Array.isArray(elements)) {
+            throw new Error('a FinTS data group must be initialized with an array');
+        }
+        if (elements.length <= 0) {
+            throw new Error('cannot create a FinTS data group with no elements');
+        }
+    }
+    maxValueCount(version) {
+        return this.elements.reduce((count, element) => count + element.maxValueCount(version), 0);
+    }
+    encode(values, context, version) {
+        if (!version) {
+            throw new Error('version is required for encoding an element group');
+        }
+        const isSingleArray = this.elements.length === 1 && this.elements[0].maxCount > 1;
+        return encodeElements(isSingleArray ? [values] : values, this.elements, ':', version, [...context, this.name]);
+    }
+    decode(text, version) {
+        if (!text.replaceAll(':', '')) {
+            return undefined;
+        }
+        if (!version) {
+            throw new Error('version is required for decoding an element group');
+        }
+        return decodeElements(text, this.elements, ':', version, this.name);
+    }
+    toString(values) {
+        if (!values) {
+            return '';
+        }
+        let texts = this.elements.map((element) => {
+            if (element.maxCount > 1) {
+                if (this.elements.length === 1) {
+                    return values.map((value) => element.toString(value)).join('; ');
+                }
+                else {
+                    return values[element.name]?.map((value) => element.toString(value)).join('; ') ?? '';
+                }
+            }
+            else {
+                return element.toString(values[element.name]);
+            }
+        });
+        return `[${texts.filter((text) => !!text).join(', ')}]`;
+    }
+}

package/dist/dataGroups/InternationalAccount.js

@@ -0,0 +1,15 @@
+import { AlphaNumeric } from '../dataElements/AlphaNumeric.js';
+import { DataGroup } from './DataGroup.js';
+import { Identification } from '../dataElements/Identification.js';
+import { BankIdentification } from './BankIdentification.js';
+export class InternationalAccountGroup extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [
+            new AlphaNumeric('iban', 0, 1, 34),
+            new AlphaNumeric('bic', 0, 1, 11),
+            new Identification('accountNumber', 0, 1),
+            new Identification('subAccountId', 0, 1),
+            new BankIdentification('bank', 0, 1),
+        ], minCount, maxCount, minVersion, maxVersion);
+    }
+}

package/dist/dataGroups/Money.js

@@ -0,0 +1,8 @@
+import { DataGroup } from './DataGroup.js';
+import { Amount } from '../dataElements/Amount.js';
+import { Currency } from '../dataElements/Currency.js';
+export class MoneyGroup extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [new Amount('value', 1, 1), new Currency('currency', 1, 1)], minCount, maxCount, minVersion, maxVersion);
+    }
+}

package/dist/dataGroups/RefMessage.js

@@ -0,0 +1,8 @@
+import { Numeric } from '../dataElements/Numeric.js';
+import { DataGroup } from './DataGroup.js';
+import { Identification } from '../dataElements/Identification.js';
+export class RefMessageGroup extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [new Identification('dialogId', 1, 1), new Numeric('msgNr', 1, 1, 4)], minCount, maxCount, minVersion, maxVersion);
+    }
+}

package/dist/dataGroups/TimeStamp.js

@@ -0,0 +1,8 @@
+import { Time } from '../dataElements/Time.js';
+import { Dat } from '../dataElements/Dat.js';
+import { DataGroup } from './DataGroup.js';
+export class TimeStampGroup extends DataGroup {
+    constructor(name, minCount = 0, maxCount = 1, minVersion, maxVersion) {
+        super(name, [new Dat('date', 1, 1), new Time('time', 0, 1)], minCount, maxCount, minVersion, maxVersion);
+    }
+}