lib-fints 1.5.0 → 1.5.2

package/dist/interactions/statementInteractionCAMT.js

@@ -1,19 +1,20 @@
+import { internationalAccount } from '../accountDescriptor.js';
 import { CamtParser } from '../camtParser.js';
 import { HICAZ } from '../segments/HICAZ.js';
 import { HKCAZ } from '../segments/HKCAZ.js';
 import { CustomerOrderInteraction } from './customerInteraction.js';
 export class StatementInteractionCAMT extends CustomerOrderInteraction {
-    accountNumber;
+    account;
     from;
     to;
-    constructor(accountNumber, from, to) {
+    constructor(account, from, to) {
         super(HKCAZ.Id, HICAZ.Id);
-        this.accountNumber = accountNumber;
+        this.account = account;
         this.from = from;
         this.to = to;
     }
     createSegments(init) {
-        const bankAccount = init.getBankAccount(this.accountNumber);
+        const bankAccount = init.getBankAccount(this.account);
         const version = init.getMaxSupportedTransactionVersion(HKCAZ.Id);
         if (!version) {
             throw Error(`There is no supported version for business transaction '${HKCAZ.Id}'`);
@@ -25,7 +26,7 @@ export class StatementInteractionCAMT extends CustomerOrderInteraction {
         }
         const hkcaz = {
             header: { segId: HKCAZ.Id, segNr: 0, version: version },
-            account: bankAccount,
+            account: internationalAccount(init, bankAccount),
             acceptedCamtFormats: acceptedCamtFormats,
             allAccounts: false,
             from: this.from,

package/dist/interactions/statementInteractionMT940.js

@@ -1,27 +1,28 @@
+import { internationalAccount, nationalAccount } from '../accountDescriptor.js';
 import { Mt940Parser } from '../mt940parser.js';
 import { HIKAZ } from '../segments/HIKAZ.js';
 import { HKKAZ } from '../segments/HKKAZ.js';
 import { CustomerOrderInteraction } from './customerInteraction.js';
 export class StatementInteractionMT940 extends CustomerOrderInteraction {
-    accountNumber;
+    account;
     from;
     to;
-    constructor(accountNumber, from, to) {
+    constructor(account, from, to) {
         super(HKKAZ.Id, HIKAZ.Id);
-        this.accountNumber = accountNumber;
+        this.account = account;
         this.from = from;
         this.to = to;
     }
     createSegments(init) {
-        const bankAccount = init.getBankAccount(this.accountNumber);
-        const account = { ...bankAccount, iban: undefined };
+        const bankAccount = init.getBankAccount(this.account);
         const version = init.getMaxSupportedTransactionVersion(HKKAZ.Id);
         if (!version) {
             throw Error(`There is no supported version for business transaction '${HKKAZ.Id}'`);
         }
+        const account = version <= 6 ? nationalAccount(bankAccount) : internationalAccount(init, bankAccount);
         const hkkaz = {
             header: { segId: HKKAZ.Id, segNr: 0, version: version },
-            account,
+            account: account,
             allAccounts: false,
             from: this.from,
             to: this.to,

package/dist/message.js

@@ -143,9 +143,13 @@ export class CustomerMessage extends Message {
                 throw new Error('no signature segment found in message');
             }
             const now = new Date();
+            // The encryption header carries the same security profile as the
+            // signature: PIN version 2 for a two-step TAN method, 1 for one-step.
+            // Some banks (Consorsbank, BLZ 76030080) reject a two-step dialog whose
+            // HNVSK still says PIN:1 with "9010 Ungültiger Signaturaufbau".
             const hnvsk = {
                 header: { segId: HNVSK.Id, segNr: 998, version: HNVSK.Version },
-                secProfile: { secMethod: 'PIN', secVersion: 1 },
+                secProfile: { secMethod: 'PIN', secVersion: firstSignature.secProfile.secVersion },
                 secFunc: 998,
                 secRole: 1,
                 secId: { partyType: 1, partyId: firstSignature.secId.partyId },

package/dist/segments/HKKAZ.js

@@ -3,7 +3,7 @@ import { Dat } from '../dataElements/Dat.js';
 import { Numeric } from '../dataElements/Numeric.js';
 import { YesNo } from '../dataElements/YesNo.js';
 import { AccountGroup } from '../dataGroups/Account.js';
-import { InternationalAccountGroup } from '../dataGroups/InternationalAccount.js';
+import { InternationalAccountGroup, } from '../dataGroups/InternationalAccount.js';
 import { SegmentDefinition } from '../segmentDefinition.js';
 /**
  * Request account transactions in a given period

package/dist/tests/accountDescriptor.test.js

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { internationalAccount, nationalAccount } from '../accountDescriptor.js';
+import { AccountType } from '../bankAccount.js';
+import { Language } from '../codes.js';
+import { FinTSConfig } from '../config.js';
+const account = {
+    accountNumber: '1234567890',
+    subAccountId: 'Girokonto',
+    bank: { country: 280, bankId: '10020030' },
+    iban: 'DE89370400440532013000',
+    bic: 'BANKDEFFXXX',
+    customerId: 'customer1',
+    accountType: AccountType.CheckingAccount,
+    currency: 'EUR',
+    holder1: 'Test User',
+};
+const depot = {
+    ...account,
+    accountNumber: '9876543210',
+    iban: undefined,
+    bic: undefined,
+};
+function configWith(allowedTransactions) {
+    return FinTSConfig.fromBankingInformation('product', '1.0', {
+        systemId: 'SYSTEM01',
+        bpd: {
+            version: 1,
+            url: 'https://bank.example.com/fints',
+            countryCode: 280,
+            bankId: '10020030',
+            bankName: 'Example Bank',
+            allowedTransactions,
+            maxTransactionsPerMessage: 1,
+            supportedLanguages: [Language.German],
+            supportedHbciVersions: [300],
+            supportedTanMethods: [],
+            availableTanMethodIds: [],
+        },
+        upd: { version: 1, usage: 0, bankAccounts: [account, depot] },
+        bankMessages: [],
+    });
+}
+const hispas = (nationalAccountAllowed) => ({
+    transId: 'HKSPA',
+    versions: [1],
+    tanRequired: false,
+    params: {
+        individualAccountRetrievalAllowed: false,
+        nationalAccountAllowed,
+        structuredPurposeAllowed: false,
+    },
+});
+describe('nationalAccount', () => {
+    it('carries the three fields the data group has, and nothing else', () => {
+        expect(nationalAccount(account)).toEqual({
+            accountNumber: '1234567890',
+            subAccountId: 'Girokonto',
+            bank: { country: 280, bankId: '10020030' },
+        });
+    });
+});
+describe('internationalAccount', () => {
+    it('leaves the national fields out when the bank forbids them', () => {
+        const descriptor = internationalAccount(configWith([hispas(false)]), account);
+        expect(descriptor).toEqual({ iban: 'DE89370400440532013000', bic: 'BANKDEFFXXX' });
+    });
+    it('includes the national fields when the bank allows them', () => {
+        const descriptor = internationalAccount(configWith([hispas(true)]), account);
+        expect(descriptor).toEqual({
+            iban: 'DE89370400440532013000',
+            bic: 'BANKDEFFXXX',
+            accountNumber: '1234567890',
+            subAccountId: 'Girokonto',
+            bank: { country: 280, bankId: '10020030' },
+        });
+    });
+    it('keeps them when the bank announces no HISPAS at all', () => {
+        // Silence is not a refusal. Only a bank that says false gets the shorter form,
+        // so a bank working today cannot regress on a rule it never stated — see #25,
+        // where Postbank required the national fields for identification.
+        const descriptor = internationalAccount(configWith([]), account);
+        expect(descriptor).toEqual({
+            iban: 'DE89370400440532013000',
+            bic: 'BANKDEFFXXX',
+            accountNumber: '1234567890',
+            subAccountId: 'Girokonto',
+            bank: { country: 280, bankId: '10020030' },
+        });
+    });
+    it('keeps the national fields for an account without an IBAN, whatever the flag says', () => {
+        // A securities account typically has none, and nothing else identifies it.
+        const descriptor = internationalAccount(configWith([hispas(false)]), depot);
+        expect(descriptor).toEqual({
+            accountNumber: '9876543210',
+            subAccountId: 'Girokonto',
+            bank: { country: 280, bankId: '10020030' },
+        });
+    });
+});

package/dist/tests/accountReference.test.js

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+import { AccountType, describeAccount } from '../bankAccount.js';
+import { Language } from '../codes.js';
+import { FinTSConfig } from '../config.js';
+import { HKSAL } from '../segments/HKSAL.js';
+import { HKWPD } from '../segments/HKWPD.js';
+// A bank that gives a securities account and the current account it settles through
+// the same number, distinguishing them only by sub-account id. That is within the
+// specification: FinTS identifies an account by both together.
+const checkingAccount = {
+    accountNumber: '1234567890',
+    subAccountId: 'Girokonto',
+    bank: { country: 280, bankId: '10020030' },
+    iban: 'DE89370400440532013000',
+    bic: 'BANKDEFFXXX',
+    customerId: 'customer1',
+    accountType: AccountType.Miscellaneous,
+    currency: 'EUR',
+    holder1: 'Test User',
+    allowedTransactions: [{ transId: HKSAL.Id, numSignatures: 0 }],
+};
+const securitiesAccount = {
+    ...checkingAccount,
+    subAccountId: 'Depot',
+    iban: undefined,
+    bic: undefined,
+    allowedTransactions: [{ transId: HKWPD.Id, numSignatures: 0 }],
+};
+const singleAccount = {
+    ...checkingAccount,
+    accountNumber: '5555555555',
+    subAccountId: undefined,
+};
+function configWith(accounts) {
+    return FinTSConfig.fromBankingInformation('product', '1.0', {
+        systemId: 'SYSTEM01',
+        bpd: {
+            version: 1,
+            url: 'https://bank.example.com/fints',
+            countryCode: 280,
+            bankId: '10020030',
+            bankName: 'Example Bank',
+            allowedTransactions: [],
+            maxTransactionsPerMessage: 1,
+            supportedLanguages: [Language.German],
+            supportedHbciVersions: [300],
+            supportedTanMethods: [],
+            availableTanMethodIds: [],
+        },
+        upd: { version: 1, usage: 0, bankAccounts: accounts },
+        bankMessages: [],
+    });
+}
+describe('addressing an account by number', () => {
+    it('resolves a number that only one account has', () => {
+        const config = configWith([checkingAccount, singleAccount]);
+        expect(config.getBankAccount('5555555555').subAccountId).toBeUndefined();
+    });
+    it('refuses a number two accounts share, instead of picking one', () => {
+        // Picking the first is what makes the failure invisible: a balance comes back,
+        // it is the other account's, and nothing in the response says so.
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(() => config.getBankAccount('1234567890')).toThrow(/not unique/);
+    });
+    it('names the sub-account ids, so the caller can tell them apart', () => {
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(() => config.getBankAccount('1234567890')).toThrow(/Girokonto, Depot/);
+    });
+    it('still says so when the number matches nothing', () => {
+        expect(() => configWith([checkingAccount]).getBankAccount('0000000000')).toThrow(/not found in UPD/);
+    });
+});
+describe('addressing an account by the account itself', () => {
+    it('reaches the one a shared number cannot', () => {
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(config.getBankAccount(securitiesAccount).subAccountId).toBe('Depot');
+        expect(config.getBankAccount(checkingAccount).subAccountId).toBe('Girokonto');
+    });
+    it('decides what that account may do, not what the other one may', () => {
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(config.isAccountTransactionSupported(securitiesAccount, HKWPD.Id)).toBe(true);
+        expect(config.isAccountTransactionSupported(checkingAccount, HKWPD.Id)).toBe(false);
+        expect(config.isAccountTransactionSupported(checkingAccount, HKSAL.Id)).toBe(true);
+    });
+    it('resolves against the UPD rather than trusting what it was handed', () => {
+        // A caller may hold an account from a persisted earlier session. The entry the
+        // bank sent this time is the one carrying the current allowed transactions.
+        const staleAccount = { ...securitiesAccount, allowedTransactions: [] };
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(config.isAccountTransactionSupported(staleAccount, HKWPD.Id)).toBe(true);
+    });
+    it('refuses an account the bank did not report', () => {
+        const config = configWith([checkingAccount]);
+        const unreportedAccount = { ...checkingAccount, subAccountId: 'Sparkonto' };
+        expect(() => config.getBankAccount(unreportedAccount)).toThrow(/not found in UPD/);
+    });
+});
+describe('naming an account in an error', () => {
+    it('reads as the number alone where that is all there is', () => {
+        expect(describeAccount('1234567890')).toBe('1234567890');
+        expect(describeAccount(singleAccount)).toBe('5555555555');
+    });
+    it('adds the sub-account id where there is one', () => {
+        // Otherwise an account passed as an object prints as [object Object].
+        expect(describeAccount(securitiesAccount)).toBe('1234567890 (Depot)');
+    });
+});
+describe('matching an account the bank itself named', () => {
+    it('uses the sub-account id where the bank repeated it', () => {
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(config.matchBankAccount({ accountNumber: '1234567890', subAccountId: 'Depot' })?.subAccountId).toBe('Depot');
+    });
+    it('still finds an account whose number only it has, sub-account id or not', () => {
+        // Banks are not consistent about repeating it, and a number only one account
+        // has identifies that account either way.
+        const config = configWith([checkingAccount, singleAccount]);
+        expect(config.matchBankAccount({ accountNumber: '5555555555' })?.accountNumber).toBe('5555555555');
+    });
+    it('gives up quietly where it cannot tell, rather than throwing', () => {
+        // This runs for entries the bank supplied — HISPA travels with every dialog —
+        // so throwing here would fail every request at a bank that shares numbers,
+        // before any of them reached its order. That is exactly what happened once.
+        const config = configWith([checkingAccount, securitiesAccount]);
+        expect(config.matchBankAccount({ accountNumber: '1234567890' })).toBeUndefined();
+    });
+});

package/dist/tests/interactionAccountDescriptor.test.js

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import { AccountType } from '../bankAccount.js';
+import { Language } from '../codes.js';
+import { FinTSConfig } from '../config.js';
+import { BalanceInteraction } from '../interactions/balanceInteraction.js';
+import { ElectronicStatementInteraction } from '../interactions/electronicStatementInteraction.js';
+import { PortfolioInteraction } from '../interactions/portfolioInteraction.js';
+import { StatementInteractionCAMT } from '../interactions/statementInteractionCAMT.js';
+import { StatementInteractionMT940 } from '../interactions/statementInteractionMT940.js';
+import { registerSegments } from '../segments/registry.js';
+registerSegments();
+// The layer between "the segment encodes correctly" and "the client picks the right
+// interaction": what an interaction puts into the account connection. Nothing
+// covered it before — the segment tests build their account by hand, and the client
+// tests mock `Dialog.start`, which throws the built request away.
+const GIRO = '1234567890';
+const DEPOT = '9876543210';
+const BANK = { country: 280, bankId: '10020030' };
+const IBAN = 'DE89370400440532013000';
+const konto = (accountNumber, transIds, iban) => ({
+    accountNumber,
+    subAccountId: 'Girokonto',
+    bank: BANK,
+    iban,
+    bic: iban ? 'BANKDEFFXXX' : undefined,
+    customerId: 'customer1',
+    accountType: AccountType.CheckingAccount,
+    currency: 'EUR',
+    holder1: 'Test User',
+    allowedTransactions: transIds.map((transId) => ({ transId, numSignatures: 1 })),
+});
+function configFor(transactions, nationalAccountAllowed) {
+    const allowedTransactions = Object.entries(transactions).map(([transId, versions]) => ({ transId, versions, tanRequired: false }));
+    if (nationalAccountAllowed !== undefined) {
+        allowedTransactions.push({
+            transId: 'HKSPA',
+            versions: [1],
+            tanRequired: false,
+            params: {
+                individualAccountRetrievalAllowed: false,
+                nationalAccountAllowed,
+                structuredPurposeAllowed: false,
+            },
+        });
+    }
+    return FinTSConfig.fromBankingInformation('product', '1.0', {
+        systemId: 'SYSTEM01',
+        bpd: {
+            version: 1,
+            url: 'https://bank.example.com/fints',
+            countryCode: 280,
+            bankId: '10020030',
+            bankName: 'Example Bank',
+            allowedTransactions,
+            maxTransactionsPerMessage: 1,
+            supportedLanguages: [Language.German],
+            supportedHbciVersions: [300],
+            supportedTanMethods: [],
+            availableTanMethodIds: [],
+        },
+        upd: {
+            version: 1,
+            usage: 0,
+            bankAccounts: [
+                konto(GIRO, ['HKSAL', 'HKKAZ', 'HKCAZ', 'HKEKA'], IBAN),
+                konto(DEPOT, ['HKWPD'], undefined),
+            ],
+        },
+        bankMessages: [],
+    });
+}
+// biome-ignore lint/suspicious/noExplicitAny: reading one field off a built segment
+const account = (segment) => segment.account;
+describe('HKCAZ — international at every version', () => {
+    it('sends IBAN and BIC only when the bank forbids the national fields', () => {
+        const config = configFor({ HKCAZ: [1] }, false);
+        const [hkcaz] = new StatementInteractionCAMT(GIRO).createSegments(config);
+        expect(account(hkcaz)).toEqual({ iban: IBAN, bic: 'BANKDEFFXXX' });
+    });
+    it('sends both halves when the bank allows them', () => {
+        const config = configFor({ HKCAZ: [1] }, true);
+        const [hkcaz] = new StatementInteractionCAMT(GIRO).createSegments(config);
+        expect(account(hkcaz)).toEqual({
+            iban: IBAN,
+            bic: 'BANKDEFFXXX',
+            accountNumber: GIRO,
+            subAccountId: 'Girokonto',
+            bank: BANK,
+        });
+    });
+});
+describe('HKSAL — national up to version 6, international from 7', () => {
+    it('sends the national form at version 6, with no IBAN', () => {
+        const [hksal] = new BalanceInteraction(GIRO).createSegments(configFor({ HKSAL: [6] }, false));
+        expect(account(hksal)).toEqual({ accountNumber: GIRO, subAccountId: 'Girokonto', bank: BANK });
+    });
+    it('honours the flag at version 7 instead of filling both halves', () => {
+        const [hksal] = new BalanceInteraction(GIRO).createSegments(configFor({ HKSAL: [7] }, false));
+        expect(account(hksal)).toEqual({ iban: IBAN, bic: 'BANKDEFFXXX' });
+    });
+});
+describe('HKKAZ — national up to version 6, international from 7', () => {
+    it('sends the national form at version 6', () => {
+        const [hkkaz] = new StatementInteractionMT940(GIRO).createSegments(configFor({ HKKAZ: [6] }, false));
+        expect(account(hkkaz)).toEqual({ accountNumber: GIRO, subAccountId: 'Girokonto', bank: BANK });
+    });
+    it('honours the flag at version 7', () => {
+        const [hkkaz] = new StatementInteractionMT940(GIRO).createSegments(configFor({ HKKAZ: [7] }, false));
+        expect(account(hkkaz)).toEqual({ iban: IBAN, bic: 'BANKDEFFXXX' });
+    });
+});
+describe('HKEKA — national up to version 3, international from 4', () => {
+    it('sends the national form at version 3', () => {
+        const [hkeka] = new ElectronicStatementInteraction(GIRO, {}).createSegments(configFor({ HKEKA: [3] }, false));
+        expect(account(hkeka)).toEqual({ accountNumber: GIRO, subAccountId: 'Girokonto', bank: BANK });
+    });
+    it('honours the flag at version 4', () => {
+        const [hkeka] = new ElectronicStatementInteraction(GIRO, {}).createSegments(configFor({ HKEKA: [4] }, false));
+        expect(account(hkeka)).toEqual({ iban: IBAN, bic: 'BANKDEFFXXX' });
+    });
+});
+describe('HKWPD — national at every version', () => {
+    it('sends the national form, and the depot has no IBAN to send anyway', () => {
+        const [hkwpd] = new PortfolioInteraction(DEPOT).createSegments(configFor({ HKWPD: [5] }, false));
+        // biome-ignore lint/suspicious/noExplicitAny: reading one field off a built segment
+        expect(hkwpd.depot).toEqual({
+            accountNumber: DEPOT,
+            subAccountId: 'Girokonto',
+            bank: BANK,
+        });
+    });
+});
+// The two banks that pulled this in opposite directions. #19/#20 reduced the CAMT
+// descriptor to IBAN and BIC because comdirect rejects anything more; #25 reported
+// Postbank answering "Angaben zur nationalen Kontoverbindung für Identifikation
+// erforderlich", and the reduction was reverted. Neither bank was wrong, and neither
+// fix could hold, because the choice was hard-coded either way. It is data now.
+describe('the two banks that pulled this in opposite directions', () => {
+    it('a bank refusing the national fields gets IBAN and BIC only', () => {
+        const [hkcaz] = new StatementInteractionCAMT(GIRO).createSegments(configFor({ HKCAZ: [1] }, false));
+        expect(account(hkcaz)).toEqual({ iban: IBAN, bic: 'BANKDEFFXXX' });
+    });
+    it('a bank that says nothing keeps them, so nothing working today regresses', () => {
+        const [hkcaz] = new StatementInteractionCAMT(GIRO).createSegments(configFor({ HKCAZ: [1] }));
+        expect(account(hkcaz)).toEqual({
+            iban: IBAN,
+            bic: 'BANKDEFFXXX',
+            accountNumber: GIRO,
+            subAccountId: 'Girokonto',
+            bank: BANK,
+        });
+    });
+});

package/dist/tests/message.test.js

@@ -77,4 +77,22 @@ describe('CustomerMessage', () => {
         const encodedMessage = customerMessage.encode();
         const _message = Message.decode(encodedMessage);
     });
+    it('encrypts with the security profile version of the signature (two-step: PIN:2)', () => {
+        const customerMessage = new CustomerMessage('0', 1);
+        customerMessage.addSegment(hkidn);
+        customerMessage.addSegment(hkvvb);
+        customerMessage.sign(280, '12030000', '12345678', '123', '0', 900, '12345');
+        const encodedMessage = customerMessage.encode();
+        expect(encodedMessage).toContain("'HNVSK:998:3+PIN:2+998+");
+        expect(encodedMessage).toContain('HNSHK:2:4+PIN:2+900+');
+    });
+    it('encrypts with the security profile version of the signature (one-step: PIN:1)', () => {
+        const customerMessage = new CustomerMessage('0', 1);
+        customerMessage.addSegment(hkidn);
+        customerMessage.addSegment(hkvvb);
+        customerMessage.sign(280, '12030000', '12345678', '123', '0');
+        const encodedMessage = customerMessage.encode();
+        expect(encodedMessage).toContain("'HNVSK:998:3+PIN:1+998+");
+        expect(encodedMessage).toContain('HNSHK:2:4+PIN:1+999+');
+    });
 });

package/dist/types/accountDescriptor.d.ts

@@ -0,0 +1,49 @@
+import type { BankAccount } from './bankAccount.js';
+import type { FinTSConfig } from './config.js';
+import type { Account } from './dataGroups/Account.js';
+import type { InternationalAccount } from './dataGroups/InternationalAccount.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 declare function nationalAccount(account: BankAccount): Account;
+/**
+ * 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 declare function internationalAccount(config: FinTSConfig, account: BankAccount): InternationalAccount;
+//# sourceMappingURL=accountDescriptor.d.ts.map

package/dist/types/accountDescriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountDescriptor.d.ts","sourceRoot":"","sources":["../../src/accountDescriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAIjF;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAM7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,WAAW,GAClB,oBAAoB,CAgBtB"}

package/dist/types/bankAccount.d.ts

@@ -22,5 +22,18 @@ export type BankAccount = SepaAccount & {
     limit?: AccountLimit;
     allowedTransactions?: AllowedTransactions[];
 };
+/**
+ * How a caller names an account.
+ *
+ * An account number is not by itself unique: FinTS identifies an account by number
+ * *and* sub-account id together, and banks use that — a securities account and the
+ * current account it settles through commonly share a number and differ only in the
+ * sub-account id. Where that happens, a number alone cannot say which one is meant,
+ * so the account itself can be passed instead. Take it from
+ * `config.bankingInformation.upd.bankAccounts`.
+ */
+export type AccountRef = string | BankAccount;
+/** How an account reference reads in an error message. */
+export declare function describeAccount(account: AccountRef): string;
 export declare function finTsAccountTypeToEnum(accountType: number): AccountType;
 //# sourceMappingURL=bankAccount.d.ts.map

package/dist/types/bankAccount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bankAccount.d.ts","sourceRoot":"","sources":["../../src/bankAccount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,oBAAY,WAAW;IACtB,eAAe,oBAAoB;IACnC,cAAc,mBAAmB;IACjC,mBAAmB,wBAAwB;IAC3C,iBAAiB,sBAAsB;IACvC,mBAAmB,wBAAwB;IAC3C,iBAAiB,sBAAsB;IACvC,qBAAqB,0BAA0B;IAC/C,mBAAmB,wBAAwB;IAC3C,eAAe,oBAAoB;IACnC,aAAa,kBAAkB;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC5C,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAWvE"}
+{"version":3,"file":"bankAccount.d.ts","sourceRoot":"","sources":["../../src/bankAccount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE7E,oBAAY,WAAW;IACtB,eAAe,oBAAoB;IACnC,cAAc,mBAAmB;IACjC,mBAAmB,wBAAwB;IAC3C,iBAAiB,sBAAsB;IACvC,mBAAmB,wBAAwB;IAC3C,iBAAiB,sBAAsB;IACvC,qBAAqB,0BAA0B;IAC/C,mBAAmB,wBAAwB;IAC3C,eAAe,oBAAoB;IACnC,aAAa,kBAAkB;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAC5C,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,CAAC;AAE9C,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAK3D;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAWvE"}