lib-fints 1.0.0

package/dist/decoder.js

@@ -0,0 +1,97 @@
+export function decodeElements(text, elements, separator, version, context) {
+    const isResultArray = elements.length === 1 && elements[0].maxCount > 1;
+    let result = isResultArray ? [] : {};
+    const textValues = splitBySeparator(text, separator);
+    let valueIndex = 0;
+    let elementIndex = 0;
+    let elementCount = 0;
+    while (elementIndex < elements.length) {
+        const element = elements[elementIndex];
+        if (element.isInVersion(version)) {
+            let textValue;
+            if (separator === ':') {
+                textValue = textValues.slice(valueIndex, valueIndex + element.maxValueCount(version)).join(':');
+                valueIndex += element.maxValueCount(version);
+            }
+            else {
+                textValue = textValues[valueIndex];
+                valueIndex++;
+            }
+            let value;
+            if (!textValue) {
+                value = undefined;
+                if (elementCount < element.minCount) {
+                    throw new Error(`Mandatory value is missing for element '${element.name}' in '${context}'`);
+                }
+            }
+            else {
+                value = element.decode(textValue, version);
+            }
+            if (isResultArray) {
+                if (element.maxCount > 1) {
+                    if (elements.length === 1) {
+                        result = [...result, value];
+                    }
+                    else {
+                        result[elementIndex] = result[elementIndex] ? [...result[elementIndex], value] : [value];
+                    }
+                }
+                else {
+                    result[elementIndex] = value;
+                }
+            }
+            else {
+                if (element.maxCount > 1) {
+                    result[element.name] = result[element.name] ? [...result[element.name], value] : [value];
+                }
+                else {
+                    result[element.name] = value;
+                }
+            }
+        }
+        elementCount++;
+        if (valueIndex >= textValues.length) {
+            if (elements.slice(elementIndex + 1).some((element) => element.isInVersion(version) && element.minCount > 0)) {
+                throw new Error(`Not all mandatory values are present in '${context}', expected a value for element '${elements[elementIndex + 1].name}'`);
+            }
+            else {
+                break;
+            }
+        }
+        if (elementCount >= element.maxCount) {
+            elementIndex++;
+            elementCount = 0;
+        }
+    }
+    return result;
+}
+export function splitBySeparator(text, separator) {
+    const result = [];
+    let pos = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '@' && !isEscaped(text, index)) {
+            const next = text.indexOf('@', index + 1);
+            const size = Number.parseInt(text.slice(index + 1, next));
+            if (size) {
+                index = next + size;
+            }
+        }
+        else if (char === separator && !isEscaped(text, index)) {
+            result.push(text.slice(pos, index));
+            pos = index + 1;
+        }
+    }
+    if (pos < text.length) {
+        result.push(text.slice(pos));
+    }
+    return result;
+}
+function isEscaped(text, pos) {
+    let count = 0;
+    while (pos > 0 && text[pos - 1] === '?') {
+        count++;
+        pos--;
+    }
+    return count % 2 === 1;
+}

package/dist/dialog.js

@@ -0,0 +1,189 @@
+import { TanMediaRequirement } from './codes.js';
+import { HttpClient } from './httpClient.js';
+import { CustomerMessage, CustomerOrderMessage } from './message.js';
+import { HKEND } from './segments/HKEND.js';
+import { HKIDN } from './segments/HKIDN.js';
+import { HKTAN } from './segments/HKTAN.js';
+import { HNHBK } from './segments/HNHBK.js';
+import { decode } from './segment.js';
+import { PARTED } from './partedSegment.js';
+import { HttpClientNode } from './httpClientNode.js';
+export class Dialog {
+    config;
+    dialogId = '0';
+    lastMessageNumber = 0;
+    isInitialized = false;
+    hasEnded = false;
+    httpClient;
+    constructor(config) {
+        this.config = config;
+        if (!this.config) {
+            throw new Error('configuration must be provided');
+        }
+        this.httpClient = this.getHttpClient();
+    }
+    async initialize(interaction) {
+        if (this.isInitialized) {
+            throw new Error('dialog has already been initialized');
+        }
+        if (this.hasEnded) {
+            throw Error('cannot initialize a dialog that has already ended');
+        }
+        if (this.lastMessageNumber > 0) {
+            throw new Error('dialog initialization must be the first message in a dialog');
+        }
+        interaction.dialog = this;
+        this.lastMessageNumber++;
+        const message = new CustomerMessage(this.dialogId, this.lastMessageNumber);
+        const tanMethod = this.config.selectedTanMethod;
+        const isScaSupported = tanMethod && tanMethod.version >= 6;
+        if (this.config.userId && this.config.pin) {
+            message.sign(this.config.countryCode, this.config.bankId, this.config.userId, this.config.pin, this.config.bankingInformation.systemId, isScaSupported ? this.config.tanMethodId : undefined);
+        }
+        const segments = interaction.getSegments(this.config);
+        segments.forEach((segment) => message.addSegment(segment));
+        if (this.config.userId && this.config.pin && isScaSupported) {
+            const hktan = {
+                header: { segId: HKTAN.Id, segNr: 0, version: tanMethod.version },
+                tanProcess: 4,
+                segId: HKIDN.Id,
+            };
+            message.addSegment(hktan);
+        }
+        const initResponse = await this.httpClient.sendMessage(message);
+        const clientResponse = interaction.getClientResponse(initResponse);
+        this.dialogId = clientResponse.dialogId;
+        if (clientResponse.success && !clientResponse.requiresTan) {
+            this.isInitialized = true;
+        }
+        this.checkEnded(initResponse);
+        return clientResponse;
+    }
+    async end() {
+        if (!this.isInitialized || this.hasEnded) {
+            return true;
+        }
+        const tanMethod = this.config.selectedTanMethod;
+        const isScaSupported = tanMethod && tanMethod.version >= 6;
+        if (this.config.tanMethodId && !tanMethod) {
+            throw new Error('given tanMethodId is not available according to the BPD');
+        }
+        this.lastMessageNumber++;
+        const message = new CustomerMessage(this.dialogId, this.lastMessageNumber);
+        if (this.config.userId && this.config.pin) {
+            message.sign(this.config.countryCode, this.config.bankId, this.config.userId, this.config.pin, this.config.bankingInformation.systemId, isScaSupported ? this.config.tanMethodId : undefined);
+        }
+        const hkend = {
+            header: { segId: HKEND.Id, segNr: 0, version: HKEND.Version },
+            dialogId: this.dialogId,
+        };
+        message.addSegment(hkend);
+        const responseMessage = await this.httpClient.sendMessage(message);
+        this.checkEnded(responseMessage);
+        return this.hasEnded;
+    }
+    async startCustomerOrderInteraction(interaction) {
+        if (!this.isInitialized) {
+            throw Error('dialog must be initialized before sending a customer order');
+        }
+        if (this.hasEnded) {
+            throw Error('cannot send a customer message when dialog has already ended');
+        }
+        const bankTransaction = this.config.bankingInformation.bpd?.allowedTransactions.find((t) => t.transId === interaction.segId);
+        if (!bankTransaction) {
+            throw Error(`transaction ${interaction.segId} is not supported according to the BPD`);
+        }
+        interaction.dialog = this;
+        this.lastMessageNumber++;
+        const message = new CustomerOrderMessage(interaction.segId, interaction.responseSegId, this.dialogId, this.lastMessageNumber);
+        if (this.config.userId && this.config.pin) {
+            message.sign(this.config.countryCode, this.config.bankId, this.config.userId, this.config.pin, this.config.bankingInformation.systemId, this.config.selectedTanMethod && (bankTransaction.tanRequired || this.config.selectedTanMethod.version >= 6)
+                ? this.config.tanMethodId
+                : undefined);
+        }
+        const segments = interaction.getSegments(this.config);
+        segments.forEach((segment) => message.addSegment(segment));
+        if (bankTransaction.tanRequired) {
+            if (this.config.userId && this.config.pin && this.config.tanMethodId) {
+                const hktan = {
+                    header: { segId: HKTAN.Id, segNr: 0, version: this.config.selectedTanMethod.version },
+                    tanProcess: 4,
+                    segId: interaction.segId,
+                    tanMedia: this.config.tanMediaName,
+                };
+                message.addSegment(hktan);
+            }
+        }
+        let responseMessage = await this.httpClient.sendMessage(message);
+        let partedSegment = responseMessage.findSegment(PARTED.Id);
+        if (partedSegment) {
+            while (responseMessage.hasReturnCode(3040)) {
+                const answers = responseMessage.getBankAnswers();
+                const segmentWithContinuation = segments.find((s) => s.header.segId === interaction.segId);
+                if (!segmentWithContinuation) {
+                    throw new Error(`Response contains segment with further information, but corresponding segment could not be found or is not specified`);
+                }
+                segmentWithContinuation.continuationMark = answers.find((a) => a.code === 3040).params[0];
+                message.findSegment(HNHBK.Id).msgNr = ++this.lastMessageNumber;
+                const nextResponseMessage = await this.httpClient.sendMessage(message);
+                const nextPartedSegment = nextResponseMessage.findSegment(PARTED.Id);
+                if (nextPartedSegment) {
+                    nextPartedSegment.rawData =
+                        partedSegment.rawData + nextPartedSegment.rawData.slice(nextPartedSegment.rawData.indexOf('+') + 1);
+                    partedSegment = nextPartedSegment;
+                }
+                responseMessage = nextResponseMessage;
+            }
+            const completeSegment = decode(partedSegment.rawData);
+            const index = responseMessage.segments.indexOf(partedSegment);
+            responseMessage.segments.splice(index, 1, completeSegment);
+        }
+        this.checkEnded(responseMessage);
+        return interaction.getClientResponse(responseMessage);
+    }
+    async sendTanMessage(refSegId, tanOrderReference, tan) {
+        if (!refSegId || !tanOrderReference || !tan) {
+            throw Error('refSegId, tanOrderReference and TAN must be provided to send a TAN message');
+        }
+        if (!this.isInitialized) {
+            throw Error('dialog must be initialized before sending a TAN message');
+        }
+        if (this.hasEnded) {
+            throw Error('cannot send a TAN message when dialog has alreay ended');
+        }
+        this.lastMessageNumber++;
+        const message = new CustomerMessage(this.dialogId, this.lastMessageNumber);
+        if (this.config.userId && this.config.pin) {
+            message.sign(this.config.countryCode, this.config.bankId, this.config.userId, this.config.pin, this.config.bankingInformation.systemId, this.config.tanMethodId, tan);
+        }
+        if (this.config.userId && this.config.pin && this.config.tanMethodId) {
+            const hktan = {
+                header: { segId: HKTAN.Id, segNr: 0, version: this.config.selectedTanMethod.version },
+                tanProcess: 2,
+                segId: refSegId,
+                orderRef: tanOrderReference,
+                nextTan: false,
+                tanMedia: this.config.selectedTanMethod.tanMediaRequirement >= TanMediaRequirement.Optional
+                    ? this.config.tanMediaName
+                    : undefined,
+            };
+            message.addSegment(hktan);
+        }
+        const responseMessage = await this.httpClient.sendMessage(message);
+        this.checkEnded(responseMessage);
+        return responseMessage;
+    }
+    checkEnded(initResponse) {
+        if (initResponse.hasReturnCode(100) || initResponse.hasReturnCode(9800)) {
+            this.hasEnded = true;
+        }
+    }
+    getHttpClient() {
+        if (typeof fetch === 'function') {
+            return new HttpClient(this.config.bankingUrl, this.config.debugEnabled);
+        }
+        else {
+            return new HttpClientNode(this.config.bankingUrl, this.config.debugEnabled);
+        }
+    }
+}

package/dist/encoder.js

@@ -0,0 +1,47 @@
+export function encodeElements(values, elements, separator, version, context) {
+    const isArray = Array.isArray(values);
+    if (!values || (isArray && values.length === 0) || (!isArray && Object.keys(values).length === 0)) {
+        if (context.length >= 3) {
+            return separator.repeat(elements.reduce((sum, element) => sum + element.maxValueCount(version), 0) - 1);
+        }
+        return '';
+    }
+    if (isArray && values.length !== elements.length) {
+        throw new Error(`Values to encode don't match number of elements (${values.length} <> ${elements.length}) when encoding '${context.join('->')}'`);
+    }
+    let textValues = [];
+    let elementIndex = 0;
+    while (elementIndex < elements.length) {
+        const element = elements[elementIndex];
+        if (!element.isInVersion(version)) {
+            elementIndex++;
+            continue;
+        }
+        if (isArray) {
+            if (elementIndex >= values.length) {
+                if (elementIndex < element.minCount) {
+                    throw new Error(`There are not enough values for all mandatory elements when encoding '${context.join('->')}'`);
+                }
+            }
+            if (element.maxCount > 1) {
+                textValues.push(values[elementIndex]?.map((value) => element.encode(value, context, version)).join(separator));
+            }
+            else {
+                textValues.push(element.encode(values[elementIndex], context, version));
+            }
+        }
+        else {
+            if (element.maxCount > 1) {
+                textValues.push(values[element.name]?.map((value) => element.encode(value, context, version)).join(separator));
+            }
+            else {
+                textValues.push(element.encode(values[element.name], context, version));
+            }
+        }
+        elementIndex++;
+    }
+    if (context.length < 3) {
+        textValues.splice(textValues.findLastIndex((text) => !!text && text !== ':') + 1);
+    }
+    return textValues.join(separator);
+}

package/dist/format.js

@@ -0,0 +1,6 @@
+export function finTsEncode(value) {
+    return value.replace(/([\?:\+'@])/g, '?$1');
+}
+export function finTsDecode(value) {
+    return value.replace(/\?([\?:\+'@])/g, '$1');
+}

package/dist/httpClient.js

@@ -0,0 +1,41 @@
+import { Message } from './message.js';
+export class HttpClient {
+    url;
+    debug;
+    constructor(url, debug = false) {
+        this.url = url;
+        this.debug = debug;
+    }
+    async sendMessage(message) {
+        const encodedMessage = message.encode();
+        const requestBuffer = Buffer.from(encodedMessage);
+        if (this.debug) {
+            console.log('Request Message:\n' + message.toString());
+        }
+        const response = await fetch(this.url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'text/plain' },
+            body: requestBuffer.toString('base64'),
+        });
+        if (response.ok) {
+            const responseBuffer = Buffer.from(await response.text(), 'base64');
+            const responseText = responseBuffer.toString('latin1');
+            try {
+                const customerOrderMessage = message;
+                const responseMessage = Message.decode(responseText, customerOrderMessage.supportsPartedResponseSegments ? customerOrderMessage.orderResponseSegId : undefined);
+                if (this.debug) {
+                    console.log('Response Message:\n' + responseMessage.toString(true) + '\n');
+                }
+                return responseMessage;
+            }
+            catch (error) {
+                console.error('Error decoding response message:', error);
+                console.error('Response Message Content:\n', responseText.split("'").join('\n'));
+                throw error;
+            }
+        }
+        else {
+            throw Error(`Request failed with status code ${response.status}: ${await response.text()}`);
+        }
+    }
+}

package/dist/httpClientNode.js

@@ -0,0 +1,59 @@
+import { Message } from './message.js';
+import * as https from 'https';
+export class HttpClientNode {
+    url;
+    debug;
+    constructor(url, debug = false) {
+        this.url = url;
+        this.debug = debug;
+    }
+    async sendMessage(message) {
+        const encodedMessage = message.encode();
+        const requestBuffer = Buffer.from(encodedMessage).toString('base64');
+        if (this.debug) {
+            console.log('Request Message:\n' + message.toString());
+        }
+        const requestOptions = {
+            method: 'POST',
+            headers: { 'Content-Type': 'text/plain' },
+        };
+        return new Promise((resolve, reject) => {
+            const req = https.request(this.url, requestOptions, (res) => {
+                let data = '';
+                res.on('data', (chunk) => {
+                    data += chunk;
+                });
+                res.on('end', () => {
+                    if (res.statusCode === 200) {
+                        const responseBuffer = Buffer.from(data, 'base64');
+                        const responseText = responseBuffer.toString('latin1');
+                        try {
+                            const customerOrderMessage = message;
+                            const responseMessage = Message.decode(responseText, customerOrderMessage.supportsPartedResponseSegments
+                                ? customerOrderMessage.orderResponseSegId
+                                : undefined);
+                            if (this.debug) {
+                                console.log('Response Message:\n' + responseMessage.toString(true) + '\n');
+                            }
+                            resolve(responseMessage);
+                        }
+                        catch (error) {
+                            console.error('Error decoding response message:', error);
+                            console.error('Response Message Content:\n', responseText.split("'").join('\n'));
+                            reject(error);
+                        }
+                    }
+                    else {
+                        reject(new Error(`Request failed with status code ${res.statusCode}: ${data}`));
+                    }
+                });
+            });
+            req.on('error', (error) => {
+                console.error('Request error:', error);
+                reject(error);
+            });
+            req.write(requestBuffer);
+            req.end();
+        });
+    }
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { registerSegments } from './segments/registry.js';
+registerSegments();
+export * from './client.js';
+export * from './config.js';
+export * from './segment.js';
+export * from './message.js';
+export * from './dialog.js';
+export * from './httpClient.js';
+export * from './bankAnswer.js';
+export * from './bankAccount.js';
+export * from './bankingInformation.js';
+export * from './accountBalance.js';
+export * from './bpd.js';
+export * from './upd.js';
+export * from './mt940parser.js';

package/dist/interactions/balanceInteraction.js

@@ -0,0 +1,47 @@
+import { CustomerOrderInteraction } from './customerInteraction.js';
+import { CreditDebit } from '../codes.js';
+import { HISAL } from '../segments/HISAL.js';
+import { HKSAL } from '../segments/HKSAL.js';
+export class BalanceInteraction extends CustomerOrderInteraction {
+    accountNumber;
+    constructor(accountNumber) {
+        super(HKSAL.Id, HISAL.Id);
+        this.accountNumber = accountNumber;
+    }
+    createSegments(init) {
+        const bankAccount = init.getBankAccount(this.accountNumber);
+        if (!init.isAccountTransactionSupported(this.accountNumber, this.segId)) {
+            throw Error(`Account ${this.accountNumber} does not support business transaction '${this.segId}'`);
+        }
+        const account = { ...bankAccount, iban: undefined };
+        const version = init.getMaxSupportedTransactionVersion(HKSAL.Id);
+        if (!version) {
+            throw Error(`There is no supported version for business transaction '${HKSAL.Id}`);
+        }
+        const hksal = {
+            header: { segId: HKSAL.Id, segNr: 0, version: version },
+            account,
+            allAccounts: false,
+        };
+        return [hksal];
+    }
+    handleResponse(response, clientResponse) {
+        const hisal = response.findSegment(HISAL.Id);
+        if (hisal) {
+            clientResponse.balance = {
+                date: hisal.balance.date,
+                currency: hisal.currency,
+                balance: balanceToValue(hisal.balance),
+                notedBalance: balanceToValue(hisal.notedBalance),
+                creditLimit: hisal.creditLimit?.value,
+                availableAmount: hisal.availableAmount?.value,
+            };
+        }
+    }
+}
+function balanceToValue(balance) {
+    if (!balance) {
+        return undefined;
+    }
+    return balance.creditDebit === CreditDebit.Credit ? balance.amount.value : -balance.amount.value;
+}

package/dist/interactions/customerInteraction.js

@@ -0,0 +1,55 @@
+import { HITAN } from '../segments/HITAN.js';
+import { HNHBK } from '../segments/HNHBK.js';
+export class CustomerInteraction {
+    segId;
+    dialog;
+    constructor(segId) {
+        this.segId = segId;
+    }
+    getSegments(init) {
+        return this.createSegments(init);
+    }
+    getClientResponse(response) {
+        const clientResponse = this.handleBaseResponse(response);
+        if (clientResponse.success && !clientResponse.requiresTan) {
+            this.handleResponse(response, clientResponse);
+        }
+        return clientResponse;
+    }
+    handleBaseResponse(response) {
+        const hnhbk = response.findSegment(HNHBK.Id);
+        const dialogId = hnhbk?.dialogId ?? '';
+        if (response.hasReturnCode(30)) {
+            const hitan = response.findSegment(HITAN.Id);
+            if (hitan) {
+                return {
+                    dialogId,
+                    success: true,
+                    bankingInformationUpdated: false,
+                    bankAnswers: response.getBankAnswers(),
+                    requiresTan: true,
+                    tanReference: hitan.orderReference,
+                    tanChallenge: hitan.challenge,
+                    tanMediaName: hitan.tanMedia,
+                };
+            }
+            else {
+                throw new Error('HITAN segment not found in response, despite return code 30');
+            }
+        }
+        return {
+            dialogId,
+            success: response.getHighestReturnCode() < 9000,
+            bankingInformationUpdated: false,
+            bankAnswers: response.getBankAnswers(),
+            requiresTan: false,
+        };
+    }
+}
+export class CustomerOrderInteraction extends CustomerInteraction {
+    responseSegId;
+    constructor(segId, responseSegId) {
+        super(segId);
+        this.responseSegId = responseSegId;
+    }
+}