lib-fints 1.5.0 → 1.5.2

package/README.md

@@ -85,14 +85,17 @@ Finally you can start fetching balances or statements:
 // for simplicity, use the first account
 const account = syncResponse.bankingInformation.upd.bankAccounts[0];
 
+// Account-specific methods accept either an account number or a BankAccount.
+// Pass the account object when multiple accounts share the same number.
+
 // fetch the current balance
-const balanceResponse = await client.getAccountBalance(account.accountNumber);
+const balanceResponse = await client.getAccountBalance(account);
 
 // fetch all available statements
-const statementResponse = await client.getAccountStatements(account.accountNumber);
+const statementResponse = await client.getAccountStatements(account);
 
 // or fetch portfolio from a securities account
-client.getPortfolio(account.accountNumber);
+client.getPortfolio(account);
 ```
 
 These are only the most basic steps needed to retrieve information from the bank. There are still some unanswered questions like "how to handle TANs" or "how to avoid synchronizations every time you start a new session". These are explained in the corresponding sections below.
@@ -110,7 +113,7 @@ const rl = readline.createInterface({
   output: process.stdout,
 });
 
-let response = await client.getAccountStatements(account.accountNumber);
+let response = await client.getAccountStatements(account);
 
 if (!response.success) {
   return;
@@ -197,11 +200,11 @@ The following table shows all transactions supported by the FinTSClient interfac
 | Transaction                | Method                                                               | Description                                                                     | FinTS Segment(s)           | TAN Support | Account-Specific |
 | -------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------- | ----------- | ---------------- |
 | **Synchronization**        | `synchronize()`                                                      | Synchronizes bank and account information, updating config.bankingInformation   | HKIDN, HKVVB, HKSYN, HKTAB | ✓           | ❌               |
-| **Account Balance**        | `getAccountBalance(accountNumber)`                                   | Fetches the current balance for a specific account                              | HKSAL                      | ✓           | ✓                |
-| **Account Statements**     | `getAccountStatements(accountNumber, from?, to?)`                    | Fetches account transactions/statements for a date range (MT940 or CAMT format) | HKKAZ, HKCAZ               | ✓           | ✓                |
-| **Portfolio**              | `getPortfolio(accountNumber, currency?, priceQuality?, maxEntries?)` | Fetches securities portfolio information for depot accounts                     | HKWPD                      | ✓           | ✓                |
-| **Credit Card Statements** | `getCreditCardStatements(accountNumber, from?)`                      | Fetches credit card statements for credit card accounts                         | DKKKU                      | ✓           | ✓                |
-| **Electronic Statements**  | `getElectronicStatements(accountNumber, options?)`                   | Fetches the statement document from the electronic mailbox, usually a PDF       | HKEKA                      | ✓           | ✓                |
+| **Account Balance**        | `getAccountBalance(account: AccountRef)`                              | Fetches the current balance for a specific account                              | HKSAL                      | ✓           | ✓                |
+| **Account Statements**     | `getAccountStatements(account: AccountRef, from?, to?)`               | Fetches account transactions/statements for a date range (MT940 or CAMT format) | HKKAZ, HKCAZ               | ✓           | ✓                |
+| **Portfolio**              | `getPortfolio(account: AccountRef, currency?, priceQuality?, maxEntries?)` | Fetches securities portfolio information for depot accounts                  | HKWPD                      | ✓           | ✓                |
+| **Credit Card Statements** | `getCreditCardStatements(account: AccountRef, from?)`                 | Fetches credit card statements for credit card accounts                         | DKKKU                      | ✓           | ✓                |
+| **Electronic Statements**  | `getElectronicStatements(account: AccountRef, options?)`              | Fetches the statement document from the electronic mailbox, usually a PDF       | HKEKA                      | ✓           | ✓                |
 | **TAN Method Selection**   | `selectTanMethod(tanMethodId)`                                       | Selects a TAN method by ID from available methods                               | -                          | ❌          | ❌               |
 | **TAN Media Selection**    | `selectTanMedia(tanMediaName)`                                       | Selects a specific TAN media device by name                                     | -                          | ❌          | ❌               |
 
@@ -211,11 +214,11 @@ For each account-specific transaction, the client provides corresponding `can*`
 
 | Support Check Method                         | Purpose                                                         |
 | -------------------------------------------- | --------------------------------------------------------------- |
-| `canGetAccountBalance(accountNumber?)`       | Checks if account balance fetching is supported                 |
-| `canGetAccountStatements(accountNumber?)`    | Checks if account statements fetching is supported (MT940/CAMT) |
-| `canGetPortfolio(accountNumber?)`            | Checks if portfolio information fetching is supported           |
-| `canGetCreditCardStatements(accountNumber?)` | Checks if credit card statements fetching is supported          |
-| `canGetElectronicStatements(accountNumber?)` | Checks if electronic account statements fetching is supported   |
+| `canGetAccountBalance(account?: AccountRef)`       | Checks if account balance fetching is supported                 |
+| `canGetAccountStatements(account?: AccountRef)`    | Checks if account statements fetching is supported (MT940/CAMT) |
+| `canGetPortfolio(account?: AccountRef)`            | Checks if portfolio information fetching is supported           |
+| `canGetCreditCardStatements(account?: AccountRef)` | Checks if credit card statements fetching is supported          |
+| `canGetElectronicStatements(account?: AccountRef)` | Checks if electronic account statements fetching is supported   |
 
 ### Transaction Parameters
 
@@ -246,12 +249,12 @@ if (config.isTransactionSupported('HKWPD')) {
 }
 ```
 
-#### `config.isAccountTransactionSupported(accountNumber: string, transId: string): boolean`
+#### `config.isAccountTransactionSupported(account: AccountRef, transId: string): boolean`
 
 Checks whether a specific transaction type is supported for a particular account.
 
 ```typescript
-if (config.isAccountTransactionSupported('1234567890', 'HKWPD')) {
+if (config.isAccountTransactionSupported(account, 'HKWPD')) {
   console.log('Account supports portfolio requests');
 }
 ```
@@ -280,6 +283,7 @@ Implementing further transactions should be straight forward and contributions a
 
 ### Successfully tested with the following banks
 
+- comdirect
 - DKB
 - ING-DiBa
 - Renault Bank Direkt
@@ -301,7 +305,7 @@ As this is a free-time project, a lot of things are still remaining which could
 
 ## License
 
-This project is licensed under the LGPL 3.0 License - see the [LICENSE](LICENSE) file for details
+This project is licensed under the LGPL-2.1-or-later License - see the [LICENSE](LICENSE) file for details
 
 ## References
 

package/dist/accountDescriptor.js

@@ -0,0 +1,65 @@
+import { HKSPA } from './segments/HKSPA.js';
+/**
+ * Builds the account connection ("Kontoverbindung") a segment carries.
+ *
+ * FinTS has two forms, and segments pick one by version: the national form (KTV,
+ * account number + sub-account + bank) and the international one (KTI, which adds
+ * IBAN and BIC and makes every field optional). The international form allows the
+ * national fields to be present as well, but only where the bank permits it — and
+ * the bank says so in the HISPAS parameters, in `nationalAccountAllowed`.
+ *
+ * Filling both halves regardless is rejected by banks that set the flag to false.
+ * Measured at comdirect (BLZ 2004xxxx), same account, same range, same session:
+ *
+ *   IBAN + BIC + number + sub-account + bank   →  3010 "Kontonummer ist ungültig", 0 statements
+ *   IBAN + BIC                                 →  0020 "Auftrag ausgeführt", 19 statements
+ *   IBAN                                       →  0020 "Auftrag ausgeführt", 19 statements
+ *   number + sub-account + bank                →  3010 "Kontonummer ist ungültig", 0 statements
+ *
+ * The last line is why this is a rule about the national *fields* rather than about
+ * the combination: the bank rejects them in a KTI even when no IBAN accompanies
+ * them.
+ */
+/**
+ * The national form. Built field by field rather than by spreading the account and
+ * blanking what does not belong: the data group has exactly these three fields, and
+ * saying so is clearer than relying on the encoder to ignore the rest.
+ */
+export function nationalAccount(account) {
+    return {
+        accountNumber: account.accountNumber,
+        subAccountId: account.subAccountId,
+        bank: account.bank,
+    };
+}
+/**
+ * The international form. IBAN and BIC always; the national fields only where the
+ * bank's HISPAS parameters allow them.
+ *
+ * An account without an IBAN — a securities account, typically — has nothing else
+ * to identify it with, so it keeps the national fields whatever the flag says. A
+ * request the bank refuses is more useful than one it cannot resolve at all.
+ *
+ * A bank that announces no HISPAS at all keeps both halves, exactly as before. The
+ * specification would read absent permission as no permission, but this library has
+ * already been round that loop: #20 reduced the CAMT descriptor to IBAN and BIC for
+ * comdirect, #25 reported Postbank answering "Angaben zur nationalen Kontoverbindung
+ * für Identifikation erforderlich", and the reduction was reverted. Only a bank that
+ * says `false` gets the shorter form, so no bank that works today can regress on a
+ * rule it never stated.
+ */
+export function internationalAccount(config, account) {
+    if (!account.iban) {
+        return nationalAccount(account);
+    }
+    const hispas = config.getTransactionParameters(HKSPA.Id);
+    return hispas?.nationalAccountAllowed === false
+        ? { iban: account.iban, bic: account.bic }
+        : {
+            iban: account.iban,
+            bic: account.bic,
+            accountNumber: account.accountNumber,
+            subAccountId: account.subAccountId,
+            bank: account.bank,
+        };
+}

package/dist/bankAccount.js

@@ -11,6 +11,14 @@ export var AccountType;
     AccountType["InsurancePolicy"] = "InsurancePolicy";
     AccountType["Miscellaneous"] = "Miscellaneous";
 })(AccountType || (AccountType = {}));
+/** How an account reference reads in an error message. */
+export function describeAccount(account) {
+    if (typeof account === 'string')
+        return account;
+    return account.subAccountId
+        ? `${account.accountNumber} (${account.subAccountId})`
+        : account.accountNumber;
+}
 export function finTsAccountTypeToEnum(accountType) {
     if (accountType >= 1 && accountType <= 9)
         return AccountType.CheckingAccount;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { describeAccount } from './bankAccount.js';
 import { FinTSConfig } from './config.js';
 import { Dialog } from './dialog.js';
 import { BalanceInteraction, } from './interactions/balanceInteraction.js';
@@ -67,21 +68,21 @@ export class FinTSClient {
     }
     /**
      * Checks if the bank supports fetching an account balance in general or for the given account number when provided
-     * @param accountNumber when the account number is provided, checks if the account supports fetching the balance
+     * @param account when the account number is provided, checks if the account supports fetching the balance
      * @returns true if the bank (and account) supports fetching the account balance
      */
-    canGetAccountBalance(accountNumber) {
-        return accountNumber
-            ? this.config.isAccountTransactionSupported(accountNumber, HKSAL.Id)
+    canGetAccountBalance(account) {
+        return account
+            ? this.config.isAccountTransactionSupported(account, HKSAL.Id)
             : this.config.isTransactionSupported(HKSAL.Id);
     }
     /**
      * Fetches the account balance for the given account number
-     * @param accountNumber - the account number to fetch the balance for, must be an account available in the config.baningInformation.UPD.accounts
+     * @param account - the account number to fetch the balance for, must be an account available in the config.baningInformation.UPD.accounts
      * @returns the account balance response
      */
-    async getAccountBalance(accountNumber) {
-        const response = await this.startCustomerOrderInteraction(new BalanceInteraction(accountNumber));
+    async getAccountBalance(account) {
+        const response = await this.startCustomerOrderInteraction(new BalanceInteraction(account));
         return response;
     }
     /**
@@ -95,14 +96,14 @@ export class FinTSClient {
     }
     /**
      * Checks if the bank supports fetching account statements in general or for the given account number when provided
-     * @param accountNumber when the account number is provided, checks if the account supports fetching of statements
+     * @param account when the account number is provided, checks if the account supports fetching of statements
      * @returns true if the bank (and account) supports fetching account statements
      */
-    canGetAccountStatements(accountNumber) {
-        if (accountNumber) {
+    canGetAccountStatements(account) {
+        if (account) {
             // Check if either CAMT or MT940 is supported for this account
-            return (this.config.isAccountTransactionSupported(accountNumber, HKCAZ.Id) ||
-                this.config.isAccountTransactionSupported(accountNumber, HKKAZ.Id));
+            return (this.config.isAccountTransactionSupported(account, HKCAZ.Id) ||
+                this.config.isAccountTransactionSupported(account, HKKAZ.Id));
         }
         else {
             // Check if either CAMT or MT940 is supported by the bank
@@ -111,26 +112,26 @@ export class FinTSClient {
     }
     /**
      * Fetches the account statements for the given account number
-     * @param accountNumber - the account number to fetch the statements for, must be an account available in the config.baningInformation.UPD.accounts
+     * @param account - the account number to fetch the statements for, must be an account available in the config.baningInformation.UPD.accounts
      * @param from - an optional start date of the period to fetch the statements for
      * @param to - an optional end date of the period to fetch the statements for
      * @param preferCamt - whether to prefer CAMT format over MT940 when both are supported (default: true)
      * @returns an account statements response containing an array of statements
      */
-    async getAccountStatements(accountNumber, from, to, preferCamt = true) {
+    async getAccountStatements(account, from, to, preferCamt = true) {
         // Check what formats the bank supports
-        const camtSupported = this.config.isAccountTransactionSupported(accountNumber, 'HKCAZ');
-        const mt940Supported = this.config.isAccountTransactionSupported(accountNumber, 'HKKAZ');
+        const camtSupported = this.config.isAccountTransactionSupported(account, 'HKCAZ');
+        const mt940Supported = this.config.isAccountTransactionSupported(account, 'HKKAZ');
         if (!camtSupported && !mt940Supported) {
-            throw Error(`Account ${accountNumber} does not support account statements`);
+            throw Error(`Account ${describeAccount(account)} does not support account statements`);
         }
         // Choose format based on support and preference
         const useCAMT = (preferCamt && camtSupported) || (!mt940Supported && camtSupported);
         if (useCAMT) {
-            return (await this.startCustomerOrderInteraction(new StatementInteractionCAMT(accountNumber, from, to)));
+            return (await this.startCustomerOrderInteraction(new StatementInteractionCAMT(account, from, to)));
         }
         else {
-            return (await this.startCustomerOrderInteraction(new StatementInteractionMT940(accountNumber, from, to)));
+            return (await this.startCustomerOrderInteraction(new StatementInteractionMT940(account, from, to)));
         }
     }
     /**
@@ -144,24 +145,24 @@ export class FinTSClient {
     }
     /**
      * Checks if the bank supports fetching portfolio information in general or for the given account number when provided
-     * @param accountNumber when the account number is provided, checks if the account supports fetching of portfolio information
+     * @param account when the account number is provided, checks if the account supports fetching of portfolio information
      * @returns true if the bank (and account) supports fetching portfolio information
      */
-    canGetPortfolio(accountNumber) {
-        return accountNumber
-            ? this.config.isAccountTransactionSupported(accountNumber, HKWPD.Id)
+    canGetPortfolio(account) {
+        return account
+            ? this.config.isAccountTransactionSupported(account, HKWPD.Id)
             : this.config.isTransactionSupported(HKWPD.Id);
     }
     /**
      * Fetches the portfolio information for the given depot account number
-     * @param accountNumber - the depot account number to fetch the portfolio for, must be an account available in the config.bankingInformation.UPD.accounts
+     * @param account - the depot account number to fetch the portfolio for, must be an account available in the config.bankingInformation.UPD.accounts
      * @param currency - optional currency filter for the portfolio statement
      * @param priceQuality - optional price quality filter ('1' for real-time, '2' for delayed)
      * @param maxEntries - optional maximum number of entries to retrieve
      * @returns a portfolio response containing holdings and total value
      */
-    async getPortfolio(accountNumber, currency, priceQuality, maxEntries) {
-        return (await this.startCustomerOrderInteraction(new PortfolioInteraction(accountNumber, currency, priceQuality, maxEntries)));
+    async getPortfolio(account, currency, priceQuality, maxEntries) {
+        return (await this.startCustomerOrderInteraction(new PortfolioInteraction(account, currency, priceQuality, maxEntries)));
     }
     /**
      * Continues the portfolio fetching when a TAN is required
@@ -175,24 +176,24 @@ export class FinTSClient {
     }
     /**
      * Checks if the bank supports fetching credit card statements in general or for the given account number
-     * @param accountNumber when the account number is provided, checks if the account supports fetching of statements
+     * @param account when the account number is provided, checks if the account supports fetching of statements
      * @returns true if the bank (and account) supports fetching credit card statements
      */
-    canGetCreditCardStatements(accountNumber) {
-        return accountNumber
-            ? this.config.isAccountTransactionSupported(accountNumber, DKKKU.Id)
+    canGetCreditCardStatements(account) {
+        return account
+            ? this.config.isAccountTransactionSupported(account, DKKKU.Id)
             : this.config.isTransactionSupported(DKKKU.Id);
     }
     /**
      * Fetches the credit card statements for the given account number
-     * @param accountNumber - the account number to fetch the statements for, must be a credit card account available
+     * @param account - the account number to fetch the statements for, must be a credit card account available
      * in the config.baningInformation.UPD.accounts
      * @param from - an optional start date of the period to fetch the statements for
      * @param to - an optional end date of the period to fetch the statements for
      * @returns an account statements response containing an array of statements
      */
-    async getCreditCardStatements(accountNumber, from) {
-        return (await this.startCustomerOrderInteraction(new CreditCardStatementInteraction(accountNumber, from)));
+    async getCreditCardStatements(account, from) {
+        return (await this.startCustomerOrderInteraction(new CreditCardStatementInteraction(account, from)));
     }
     /**
      * Continues the credit card statements fetching when a TAN is required
@@ -205,12 +206,12 @@ export class FinTSClient {
     }
     /**
      * Checks if the bank supports fetching electronic account statements in general or for the given account number
-     * @param accountNumber when the account number is provided, checks if the account supports fetching of electronic statements
+     * @param account when the account number is provided, checks if the account supports fetching of electronic statements
      * @returns true if the bank (and account) supports fetching electronic account statements
      */
-    canGetElectronicStatements(accountNumber) {
-        return accountNumber
-            ? this.config.isAccountTransactionSupported(accountNumber, HKEKA.Id)
+    canGetElectronicStatements(account) {
+        return account
+            ? this.config.isAccountTransactionSupported(account, HKEKA.Id)
             : this.config.isTransactionSupported(HKEKA.Id);
     }
     /**
@@ -222,12 +223,12 @@ export class FinTSClient {
      * fetch the next one. Banks that set `receiptRequired` in their HIEKAS parameters keep
      * offering a statement until it has been acknowledged with its receipt.
      *
-     * @param accountNumber - the account number to fetch the statement for, must be an account available in the config.bankingInformation.upd.accounts
+     * @param account - the account number to fetch the statement for, must be an account available in the config.bankingInformation.upd.accounts
      * @param options - optional format, statement number and year, entry limit and offset
      * @returns a response containing the statement documents and the offset of a waiting successor
      */
-    async getElectronicStatements(accountNumber, options) {
-        return (await this.startCustomerOrderInteraction(new ElectronicStatementInteraction(accountNumber, options)));
+    async getElectronicStatements(account, options) {
+        return (await this.startCustomerOrderInteraction(new ElectronicStatementInteraction(account, options)));
     }
     /**
      * Continues the electronic account statement fetching when a TAN is required

package/dist/config.js

@@ -157,13 +157,36 @@ export class FinTSConfig {
         return (this.bankingInformation.bpd?.allowedTransactions.find((t) => t.transId === transId) !==
             undefined);
     }
+    /**
+     * The account the bank meant, without demanding that it be unambiguous.
+     *
+     * For entries the *bank* supplied — a SEPA account from HISPA, say — rather than
+     * ones a caller asked for. A caller who names an ambiguous account has made a
+     * mistake worth an exception; a bank listing its own accounts has not, and
+     * throwing there would break every dialog at an institution that shares numbers.
+     *
+     * @param account An account number with, where the bank gave one, its sub-account id
+     */
+    matchBankAccount(account) {
+        const accounts = this.bankingInformation.upd?.bankAccounts ?? [];
+        const exactMatch = accounts.find((a) => a.accountNumber === account.accountNumber && a.subAccountId === account.subAccountId);
+        if (exactMatch)
+            return exactMatch;
+        // A tolerance, not a rule: B.3.1 requires the sub-account id to appear the same
+        // way in the UPD and in HKSPA/HISPA, and a bank that omits it here has not kept
+        // to that. Refusing would cost the IBAN for an account that is otherwise
+        // perfectly identified, so a number only one account has still identifies it.
+        // One that several share does not, and guessing is what this change exists to stop.
+        const matches = accounts.filter((a) => a.accountNumber === account.accountNumber);
+        return matches.length === 1 ? matches[0] : undefined;
+    }
     /**
      * Checks if a transaction is supported for a specific account
-     * @param accountNumber The account number
+     * @param account An account number, or an account from `bankingInformation.upd.bankAccounts`
      * @param transId The transaction ID
      */
-    isAccountTransactionSupported(accountNumber, transId) {
-        const bankAccount = this.getBankAccount(accountNumber);
+    isAccountTransactionSupported(account, transId) {
+        const bankAccount = this.getBankAccount(account);
         return !!bankAccount.allowedTransactions?.find((t) => t.transId === transId);
     }
     /**
@@ -181,14 +204,38 @@ export class FinTSConfig {
         return maxSupportedversion;
     }
     /**
-     * Gets the bank account information for a specific account number
-     * @param accountNumber The account number
+     * Resolves an account reference against the accounts the bank reported.
+     *
+     * A number alone is enough wherever it is unique, which is the usual case. Where
+     * it is not, this throws instead of picking one: FinTS identifies an account by
+     * number *and* sub-account id, so a number that matches two accounts does not say
+     * which one is meant, and answering for the wrong one produces a balance or a list
+     * of transactions that belongs to a different account with nothing to indicate it.
+     *
+     * @param account An account number, or an account from `bankingInformation.upd.bankAccounts`
      */
-    getBankAccount(accountNumber) {
-        const bankAccount = this.bankingInformation.upd?.bankAccounts.find((a) => a.accountNumber === accountNumber);
-        if (!bankAccount) {
-            throw Error(`Account ${accountNumber} not found in UPD`);
+    getBankAccount(account) {
+        const accounts = this.bankingInformation.upd?.bankAccounts ?? [];
+        if (typeof account !== 'string') {
+            // Resolved against the UPD rather than trusted as given: the caller may hold
+            // an account from an earlier session, and the entry the bank sent this time
+            // is the one carrying the current allowed transactions.
+            const matchedAccount = accounts.find((a) => a.accountNumber === account.accountNumber && a.subAccountId === account.subAccountId);
+            if (!matchedAccount) {
+                throw Error(`Account ${account.accountNumber}${account.subAccountId ? ` (${account.subAccountId})` : ''} not found in UPD`);
+            }
+            return matchedAccount;
+        }
+        const matches = accounts.filter((a) => a.accountNumber === account);
+        if (matches.length === 0) {
+            throw Error(`Account ${account} not found in UPD`);
+        }
+        if (matches.length > 1) {
+            const subAccountIds = matches.map((a) => a.subAccountId ?? '(none)').join(', ');
+            throw Error(`Account number ${account} is not unique in UPD: ${matches.length} accounts share it, ` +
+                `with sub-account ids ${subAccountIds}. Pass the account itself instead of its number, ` +
+                `from bankingInformation.upd.bankAccounts.`);
         }
-        return bankAccount;
+        return matches[0];
     }
 }

package/dist/interactions/balanceInteraction.js

@@ -1,26 +1,28 @@
+import { internationalAccount, nationalAccount } from '../accountDescriptor.js';
+import { describeAccount } from '../bankAccount.js';
 import { CreditDebit } from '../codes.js';
 import { HISAL } from '../segments/HISAL.js';
 import { HKSAL } from '../segments/HKSAL.js';
 import { CustomerOrderInteraction } from './customerInteraction.js';
 export class BalanceInteraction extends CustomerOrderInteraction {
-    accountNumber;
-    constructor(accountNumber) {
+    account;
+    constructor(account) {
         super(HKSAL.Id, HISAL.Id);
-        this.accountNumber = accountNumber;
+        this.account = account;
     }
     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 bankAccount = init.getBankAccount(this.account);
+        if (!init.isAccountTransactionSupported(this.account, this.segId)) {
+            throw Error(`Account ${describeAccount(this.account)} does not support business transaction '${this.segId}'`);
         }
         const version = init.getMaxSupportedTransactionVersion(HKSAL.Id);
         if (!version) {
             throw Error(`There is no supported version for business transaction '${HKSAL.Id}`);
         }
-        const account = version <= 6 ? { ...bankAccount, iban: undefined, bic: undefined } : bankAccount;
+        const account = version <= 6 ? nationalAccount(bankAccount) : internationalAccount(init, bankAccount);
         const hksal = {
             header: { segId: HKSAL.Id, segNr: 0, version: version },
-            account,
+            account: account,
             allAccounts: false,
         };
         return [hksal];

package/dist/interactions/creditcardStatementInteraction.js

@@ -1,18 +1,19 @@
+import { describeAccount } from '../bankAccount.js';
 import { DIKKU } from '../segments/DIKKU.js';
 import { DKKKU } from '../segments/DKKKU.js';
 import { CustomerOrderInteraction } from './customerInteraction.js';
 export class CreditCardStatementInteraction extends CustomerOrderInteraction {
-    accountNumber;
+    account;
     from;
-    constructor(accountNumber, from) {
+    constructor(account, from) {
         super(DKKKU.Id, DIKKU.Id);
-        this.accountNumber = accountNumber;
+        this.account = account;
         this.from = from;
     }
     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 bankAccount = init.getBankAccount(this.account);
+        if (!init.isAccountTransactionSupported(this.account, this.segId)) {
+            throw Error(`Account ${describeAccount(this.account)} does not support business transaction '${this.segId}'`);
         }
         const account = { ...bankAccount, iban: undefined };
         const version = 2;
@@ -58,7 +59,7 @@ export class CreditCardStatementInteraction extends CustomerOrderInteraction {
             if (dikku.transactions) {
                 for (let i = 0; i < dikku.transactions.length; i++) {
                     const parts = dikku.transactions[i].split(':');
-                    // const accountNumber = parts[0];
+                    // const account = parts[0];
                     const transactionDateStr = parts[1];
                     const valueDateStr = parts[2];
                     const currencyOrig = parts[5];

package/dist/interactions/electronicStatementInteraction.js

@@ -1,3 +1,4 @@
+import { internationalAccount, nationalAccount } from '../accountDescriptor.js';
 import { HIEKA } from '../segments/HIEKA.js';
 import { HKEKA } from '../segments/HKEKA.js';
 import { CustomerOrderInteraction } from './customerInteraction.js';
@@ -36,15 +37,15 @@ function unwrapBase64(bytes) {
     }
 }
 export class ElectronicStatementInteraction extends CustomerOrderInteraction {
-    accountNumber;
+    account;
     options;
-    constructor(accountNumber, options = {}) {
+    constructor(account, options = {}) {
         super(HKEKA.Id, HIEKA.Id);
-        this.accountNumber = accountNumber;
+        this.account = account;
         this.options = options;
     }
     createSegments(init) {
-        const bankAccount = init.getBankAccount(this.accountNumber);
+        const bankAccount = init.getBankAccount(this.account);
         const version = init.getMaxSupportedTransactionVersion(HKEKA.Id);
         if (!version) {
             throw Error(`There is no supported version for business transaction '${HKEKA.Id}'`);
@@ -53,7 +54,7 @@ export class ElectronicStatementInteraction extends CustomerOrderInteraction {
         const format = this.options.format ?? params?.supportedFormats?.[0];
         const hkeka = {
             header: { segId: HKEKA.Id, segNr: 0, version: version },
-            account: bankAccount,
+            account: version <= 3 ? nationalAccount(bankAccount) : internationalAccount(init, bankAccount),
             statementFormat: format,
             statementNumber: this.options.number,
             statementYear: this.options.year,

package/dist/interactions/portfolioInteraction.js

@@ -1,3 +1,5 @@
+import { nationalAccount } from '../accountDescriptor.js';
+import { describeAccount } from '../bankAccount.js';
 import { Mt535Parser } from '../mt535parser.js';
 import { HIWPD } from '../segments/HIWPD.js';
 import { HKWPD } from '../segments/HKWPD.js';
@@ -6,25 +8,25 @@ import { CustomerOrderInteraction } from './customerInteraction.js';
  * Interaction for requesting and parsing stock portfolio information (HKWPD/HIWPD)
  */
 export class PortfolioInteraction extends CustomerOrderInteraction {
-    accountNumber;
+    account;
     currency;
     priceQuality;
     maxEntries;
     paginationMarker;
-    constructor(accountNumber, currency, priceQuality, maxEntries, paginationMarker) {
+    constructor(account, currency, priceQuality, maxEntries, paginationMarker) {
         super(HKWPD.Id, HIWPD.Id);
-        this.accountNumber = accountNumber;
+        this.account = account;
         this.currency = currency;
         this.priceQuality = priceQuality;
         this.maxEntries = maxEntries;
         this.paginationMarker = paginationMarker;
     }
     createSegments(config) {
-        const bankAccount = config.getBankAccount(this.accountNumber);
-        if (!config.isAccountTransactionSupported(this.accountNumber, this.segId)) {
-            throw Error(`Account ${this.accountNumber} does not support business transaction '${this.segId}'`);
+        const bankAccount = config.getBankAccount(this.account);
+        if (!config.isAccountTransactionSupported(this.account, this.segId)) {
+            throw Error(`Account ${describeAccount(this.account)} does not support business transaction '${this.segId}'`);
         }
-        const depotAccount = { ...bankAccount, iban: undefined }; // HKWPD uses KTV which doesn't have IBAN
+        const depotAccount = nationalAccount(bankAccount); // HKWPD uses KTV, which has no IBAN
         const version = config.getMaxSupportedTransactionVersion(HKWPD.Id);
         if (!version) {
             throw Error(`There is no supported version for business transaction '${HKWPD.Id}'`);

package/dist/interactions/sepaAccountInteraction.js

@@ -4,7 +4,7 @@ import { CustomerOrderInteraction } from './customerInteraction.js';
 export class SepaAccountInteraction extends CustomerOrderInteraction {
     accounts;
     maxEntries;
-    constructor(accounts, // optional specific account numbers
+    constructor(accounts, // optional: only these accounts
     maxEntries) {
         super(HKSPA.Id, HISPA.Id);
         this.accounts = accounts;
@@ -18,9 +18,7 @@ export class SepaAccountInteraction extends CustomerOrderInteraction {
         if (!version) {
             throw Error(`There is no supported version for business transaction '${HKSPA.Id}'`);
         }
-        const accounts = this.accounts?.map((accountNumber) => {
-            return init.getBankAccount(accountNumber);
-        });
+        const accounts = this.accounts?.map((account) => init.getBankAccount(account));
         const hkspa = {
             header: { segId: HKSPA.Id, segNr: 0, version: version },
             accounts: accounts,
@@ -38,7 +36,10 @@ export class SepaAccountInteraction extends CustomerOrderInteraction {
                 bankAccount.isSepaAccount = false;
             });
             clientResponse.sepaAccounts.forEach((sepaAccount) => {
-                const bankAccount = this.dialog?.config.getBankAccount(sepaAccount.accountNumber);
+                // Matched, not resolved: this is the bank listing its own accounts, and at an
+                // institution where two of them share a number, demanding an unambiguous
+                // answer here would fail every dialog before it reached its order.
+                const bankAccount = this.dialog?.config.matchBankAccount(sepaAccount);
                 if (bankAccount && !bankAccount.isSepaAccount) {
                     bankAccount.isSepaAccount = sepaAccount.isSepaAccount;
                     bankAccount.iban = sepaAccount.iban;