@coderoftime/fints 0.2.0 → 0.3.0

package/src/formats/camt.ts

@@ -1,8 +1,11 @@
-import { Amount } from '../core/amount.js';
-import { Transaction, type TransactionStatus } from '../core/transaction.js';
-import { germanDay, parseIsoDate, parseIsoMoment } from '../util/dates.js';
+import { addsUpTo, Amount } from '../core/amount.js';
+import { requireStatus, Transaction, type TransactionStatus } from '../core/transaction.js';
+import { parseIsoDate } from '../util/dates.js';
 import { fail, FormatError } from '../util/errors.js';
+import { frozenWithInspect } from '../util/inspect.js';
+import { counted, maskedId, nonBlank, trimBlanks } from '../util/text.js';
 import { parseXml, type XmlElement } from '../util/xml.js';
+import { maxFieldLength } from './mt940.js';
 import { RecordBudget } from './record-budget.js';
 import { providedReference, SepaPurpose } from './sepa-purpose.js';
 
@@ -28,24 +31,32 @@ export const Camt = Object.freeze({
    * statements of several accounts, which `parse` keeps apart. Throws as `parse` does.
    */
   parseTransactions(xml: string, status?: TransactionStatus): Transaction[] {
-    return Camt.parse(xml, status).flatMap((s) => [...s.transactions]);
+    return Camt.parse(xml, status).flatMap((s) => s.transactions);
   },
 
   /**
-   * Parses all statements, each with the account it is for. Throws `FormatError` for malformed XML, for a document
-   * without any statement, for an entry without amount, currency, credit/debit indicator or date, for a date it cannot
-   * read, and for more than 200,000 statements and transactions.
+   * Parses all statements, each with the account it is for. Throws `FormatError` for malformed XML, for XML nested more
+   * than 100 levels deep or of more than 500,000 nodes besides text or one per 16 characters, whichever is more, for a
+   * document without any statement, for an entry without amount, currency, credit/debit indicator or date, for a date
+   * it cannot read, for remittance information of more than 65,536 characters, and for more than 200,000 statements and
+   * transactions.
    *
-   * `status` overrides the booking status stated in the entries.
+   * `status` overrides the booking status stated in the entries, unless it is `undefined` or `null`; throws `TypeError`
+   * for one other than `booked` and `pending`.
    */
   parse(xml: string, status?: TransactionStatus): CamtStatement[] {
-    return parseCamt(xml, status, new RecordBudget());
+    return parseCamt(xml, forcedStatus(status), new RecordBudget());
   },
 });
 
+/** The `status` of `Camt.parse`; `undefined` for `null`, the status the entries state. */
+function forcedStatus(status: unknown): TransactionStatus | undefined {
+  return status === undefined || status === null ? undefined : requireStatus(status);
+}
+
 /** `Camt.parse`, which takes each statement and transaction from `budget`, before it builds it. */
 export function parseCamt(xml: string, status: TransactionStatus | undefined, budget: RecordBudget): CamtStatement[] {
-  const root = parseXml(xml.trim());
+  const root = parseXml(trimBlanks(xml));
   const statements = root.childElements.flatMap((message) =>
     message.childElements.filter((c) => statementNames.has(c.localName)),
   );
@@ -54,25 +65,21 @@ export function parseCamt(xml: string, status: TransactionStatus | undefined, bu
     budget.take();
     const account = statement.child('Acct');
     const entries = statement.childrenNamed('Ntry');
-    return Object.freeze({
-      reference: statement.textAt(['Id']),
-      accountId: account?.textAt(['Id', 'IBAN']) ?? account?.textAt(['Id', 'Othr', 'Id']),
-      currency: account?.textAt(['Ccy']),
-      transactions: Object.freeze(entries.flatMap((entry) => new CamtEntry(entry, status, budget).transactions())),
-    });
+    return frozenWithInspect(
+      {
+        reference: statement.textAt(['Id']),
+        accountId: account?.textAt(['Id', 'IBAN']) ?? account?.textAt(['Id', 'Othr', 'Id']),
+        currency: account?.textAt(['Ccy']),
+        transactions: Object.freeze(entries.flatMap((entry) => new CamtEntry(entry, status, budget).transactions())),
+      },
+      (s) => `CamtStatement(${maskedId(s.accountId ?? '')}, ${counted(s.transactions.length, 'transaction')})`,
+    );
   });
 }
 
 /** Width of the purpose lines banks cut the remittance information into, as in MT940 and DTAUS. */
 const cutLineLength = 35;
 
-/**
- * The SEPA keywords of `purposeCodes` that count only where the bank states them apart, as `endToEndId`, `mandateId`
- * and `creditorId`: in the remittance text, which the payer or the payee writes, a creditor ID or mandate reference
- * could be that of a creditor the app trusts.
- */
-const keywordsStatedApart = new Set(['EREF', 'MREF', 'CRED']);
-
 /**
  * One booking (`Ntry`) of a report; a batch booking yields one transaction per transaction detail (`TxDtls`) when the
  * details state their amounts and these add up to the booked amount.
@@ -134,7 +141,8 @@ class CamtEntry {
         debitIndicator(detail.textAt(['CdtDbtInd'])) ?? this.debit,
       ),
     );
-    return addUpTo(split, booking) ? split : [booking];
+    const parts = split.map((t) => t.amount);
+    return addsUpTo(parts, booking.amount) ? split : [booking];
   }
 
   /** A transaction of `amount`, booked as a debit if `debit`, with what `details` tell about it. */
@@ -148,25 +156,24 @@ class CamtEntry {
     const counterparty = originalDebit ? 'Cdtr' : 'Dbtr';
     const lines = (details?.child('RmtInf')?.childrenNamed('Ustrd') ?? [])
       .map((line) => line.innerText)
-      .filter((text) => text.trim() !== '');
+      .filter((text) => trimBlanks(text) !== '');
     // A line of 35 characters goes on in the next one as it is, maybe in the middle of a word or before a blank; any
     // other line ends a phrase, which the next one follows after a blank.
     const cut = (i: number): boolean => lines[i]?.length === cutLineLength;
     const purposeParts = lines.map((line, i) => {
-      const part = cut(i) ? line : line.trimEnd();
-      return i === 0 || cut(i - 1) ? part : ` ${part.trimStart()}`;
+      const part = cut(i) ? line : trimBlanks(line, { start: false });
+      return i === 0 || cut(i - 1) ? part : ` ${trimBlanks(part, { end: false })}`;
     });
-    const purpose = purposeParts.join('').trim();
+    const remittance = purposeParts.join('');
+    // As long as an MT940 field: the keywords of megabytes of text would take memory without limit.
+    if (remittance.length > maxFieldLength) throw new FormatError('camt remittance information too long');
     const keywords = SepaPurpose.parseParts(purposeParts);
     const endToEndId = providedReference(details?.textAt(['Refs', 'EndToEndId']));
     const mandateId = details?.textAt(['Refs', 'MndtId']);
     const creditorId = creditorIdOf(parties?.child('Cdtr'));
     const purposeCode = details?.textAt(['Purp', 'Cd']);
     const typeId = this.proprietaryCode[0]?.length === 4 ? this.proprietaryCode[0] : undefined;
-    const purposeCodes = new Map([...keywords].filter(([keyword]) => !keywordsStatedApart.has(keyword)));
-    if (endToEndId !== undefined) purposeCodes.set('EREF', endToEndId);
-    if (mandateId !== undefined) purposeCodes.set('MREF', mandateId);
-    if (creditorId !== undefined) purposeCodes.set('CRED', creditorId);
+    const purposeCodes = withKeywordsStatedApart(keywords, { EREF: endToEndId, MREF: mandateId, CRED: creditorId });
     if (purposeCode !== undefined) purposeCodes.set('PURP', purposeCode);
     return new Transaction({
       status: this.status,
@@ -175,7 +182,11 @@ class CamtEntry {
       amount: debit ? amount.negate() : amount,
       isReversal: this.reversal,
       bookingText: this.bookingText ?? details?.textAt(['AddtlTxInf']),
-      purpose: keywords.get('SVWZ') ?? (purpose === '' ? details?.textAt(['AddtlTxInf']) : purpose),
+      purpose:
+        keywords.get('SVWZ') ??
+        nonBlank(remittance) ??
+        details?.textAt(['RmtInf', 'Strd', 'CdtrRefInf', 'Ref']) ??
+        details?.textAt(['AddtlTxInf']),
       counterpartyName: partyName(parties?.child(counterparty)),
       counterpartyIban: parties?.child(`${counterparty}Acct`)?.textAt(['Id', 'IBAN']),
       counterpartyAccountNumber: parties?.child(`${counterparty}Acct`)?.textAt(['Id', 'Othr', 'Id']),
@@ -206,18 +217,20 @@ function amountOf(element: XmlElement, currency: string): Amount {
 }
 
 /**
- * Whether the amounts of `parts` add up to that of `whole`, in its currency; amounts whose sum an `Amount` cannot hold
- * do not.
+ * `keywords` with the values of EREF, MREF and CRED that the bank `stated` apart, as `endToEndId`, `mandateId` and
+ * `creditorId`, in the place the text gives them, and without those it does not state: in the remittance text, which
+ * the payer or the payee writes, a creditor ID or mandate reference could be that of a creditor the app trusts.
  */
-function addUpTo(parts: readonly Transaction[], whole: Transaction): boolean {
-  const total = whole.amount;
-  if (parts.some((part) => part.amount.currency !== total.currency)) return false;
-  try {
-    return parts.reduce((sum, part) => sum.add(part.amount), new Amount(0, 0, total.currency)).equals(total);
-  } catch (error) {
-    if (error instanceof RangeError) return false;
-    throw error;
+function withKeywordsStatedApart(
+  keywords: ReadonlyMap<string, string>,
+  stated: Readonly<Record<'EREF' | 'MREF' | 'CRED', string | undefined>>,
+): Map<string, string> {
+  const codes = new Map(keywords);
+  for (const [keyword, value] of Object.entries(stated)) {
+    if (value === undefined) codes.delete(keyword);
+    else codes.set(keyword, value);
   }
+  return codes;
 }
 
 /** `true` for `DBIT`, `false` for `CRDT`, `undefined` if `indicator` is missing; throws for any other value. */
@@ -235,16 +248,14 @@ function debitIndicator(indicator: string | undefined): boolean | undefined {
 }
 
 /**
- * The calendar date of `e`: its date (`Dt`), or the German day of its date and time (`DtTm`), which may be stated in
- * UTC or another offset; `undefined` if it states neither. Throws `FormatError` for one it cannot read, which would
- * pass for a missing one otherwise, such as a value date the booking date stands in for.
+ * The calendar date of `e`: its date (`Dt`), or else its date and time (`DtTm`), both read by `parseIsoDate`, so that
+ * a date and time, which may be stated in UTC or another offset, counts on its German day; `undefined` if it states
+ * neither. Throws `FormatError` for one it cannot read, which would pass for a missing one otherwise, such as a value
+ * date the booking date stands in for.
  */
 function dateOf(e: XmlElement | undefined): Date | undefined {
-  const date = e?.textAt(['Dt']);
-  if (date !== undefined) return parseIsoDate(date) ?? fail('Unreadable camt date', date);
-  const dateTime = e?.textAt(['DtTm']);
-  if (dateTime === undefined) return undefined;
-  return germanDay(parseIsoMoment(dateTime) ?? fail('Unreadable camt date', dateTime));
+  const date = e?.textAt(['Dt']) ?? e?.textAt(['DtTm']);
+  return date === undefined ? undefined : (parseIsoDate(date) ?? fail('Unreadable camt date', date));
 }
 
 function partyName(party: XmlElement | undefined): string | undefined {

package/src/formats/mt940.ts

@@ -1,8 +1,10 @@
-import { Amount } from '../core/amount.js';
-import { Transaction, type TransactionStatus } from '../core/transaction.js';
+import { addsUpTo, Amount } from '../core/amount.js';
+import { requireStatus, Transaction, type TransactionStatus } from '../core/transaction.js';
+import { optionalString } from '../util/arguments.js';
 import { clampedDate, parseSwiftDate } from '../util/dates.js';
-import { FormatError } from '../util/errors.js';
-import { nonBlank } from '../util/text.js';
+import { fail, FormatError } from '../util/errors.js';
+import { frozenWithInspect } from '../util/inspect.js';
+import { counted, maskedId, nonBlank, trimBlanks } from '../util/text.js';
 import { RecordBudget } from './record-budget.js';
 import { providedReference, SepaPurpose } from './sepa-purpose.js';
 
@@ -18,11 +20,17 @@ export interface Mt940Statement {
   readonly currency: string | undefined;
   /** The balance at the start of the statement (field 60), negative for a debit. */
   readonly openingBalance: Amount | undefined;
-  /** The date of `openingBalance`. */
+  /**
+   * The date of `openingBalance`; `undefined` where the bank states none, as `0` or `000000` for the first statement of
+   * an account.
+   */
   readonly openingDate: Date | undefined;
   /** The balance at the end of the statement (field 62), negative for a debit. */
   readonly closingBalance: Amount | undefined;
-  /** The date of `closingBalance`. */
+  /**
+   * The date of `closingBalance`; `undefined` where the bank states none, as `0` or `000000` for the first statement of
+   * an account.
+   */
   readonly closingDate: Date | undefined;
   /**
    * The transactions of the statement, in the order the bank lists them; they lead from `openingBalance` to
@@ -41,26 +49,35 @@ export interface Mt940Options {
 
 const tagPattern = /^:(\d{2}[A-Z]?):/gm;
 
+/** Longest field the parser reads, from its tag to the next one: SWIFT fields have a few hundred characters. */
+export const maxFieldLength = 65_536;
+
 /** Parser for SWIFT MT940/MT942 statements, including German structured `:86:` fields. */
 export const Mt940 = Object.freeze({
   /** Parses all transactions; see `parse`. */
   parseTransactions(text: string, options: Mt940Options = {}): Transaction[] {
-    return Mt940.parse(text, options).flatMap((s) => [...s.transactions]);
+    return Mt940.parse(text, options).flatMap((s) => s.transactions);
   },
 
   /**
    * Parses all statements. Their lines are separated by line breaks, and by `@@` as well where the first line holds it,
    * as some banks separate them.
    *
-   * Throws `FormatError` for text without any field, and if a transaction line (`:61:`) or a balance cannot be read or
-   * the currency of a transaction is unknown. It does as well for a statement that states only one of its opening and
-   * closing balances, one of them, its account or its number twice, or transactions that do not lead from the one
+   * Throws `FormatError` for text without any field, if a transaction line (`:61:`), a balance or the creation date of
+   * an MT942 (`:13D:`) cannot be read or the currency of a transaction is unknown, and for a closing balance dated
+   * before the opening one. It does as well for a statement that states only one of its opening and closing balances,
+   * one of them, its account, its number or its creation date twice, or transactions that do not lead from the one
    * balance to the other: a line of a purpose that starts like a field, such as `:61:` or `:25:`, would pass for a
    * transaction, the account or a statement of its own otherwise. Text of more than 200,000 statements and
-   * transactions is a `FormatError` as well.
+   * transactions, or with a field of more than 65,536 characters, is a `FormatError` as well.
+   *
+   * Throws `TypeError` for a `status` other than `booked` and `pending`, `null` included, and for a `currency` that is
+   * no string; `null` counts as no currency.
    */
   parse(text: string, options: Mt940Options = {}): Mt940Statement[] {
-    return parseMt940(text, options, new RecordBudget());
+    const status = options.status === undefined ? undefined : requireStatus(options.status);
+    const currency = optionalString(options.currency, 'currency');
+    return parseMt940(text, { status, currency }, new RecordBudget());
   },
 });
 
@@ -71,6 +88,7 @@ export function parseMt940(text: string, options: Mt940Options, budget: RecordBu
   const statements: Mt940Statement[] = [];
   let current: StatementBuilder | undefined;
   for (const [tag, value] of taggedParts(normalized, tagPattern)) {
+    if (value.length > maxFieldLength) throw new FormatError(`MT940 field :${tag}: too long`);
     if (tag === '20' || current === undefined) {
       if (current !== undefined) statements.push(current.build());
       budget.take();
@@ -102,27 +120,32 @@ function* taggedParts(text: string, tag: RegExp): Generator<[tag: string, text:
 }
 
 /**
- * `text` with line feeds between its lines. Some banks separate them with `@@`, and may still break the line between
- * statements or at the ends. So `@@` separates lines where the first line holds it, which the bank writes; in other
- * text, `@@` may be part of a purpose, which the payer writes.
+ * `text` with line feeds between its lines, without the blanks and the byte order mark it may start with, which would
+ * hide its first tag. Some banks separate the lines with `@@`, and may still break the line between statements or at
+ * the ends. So `@@` separates lines where the first line holds it, which the bank writes; in other text, `@@` may be
+ * part of a purpose, which the payer writes.
  */
 function withLineFeeds(text: string): string {
-  const lines = text.replace(/\r\n?/g, '\n');
-  return lines.trimStart().split('\n', 1)[0]!.includes('@@') ? lines.replace(/@@/g, '\n') : lines;
+  const lines = trimBlanks(text.replace(/\r\n?/g, '\n'), { end: false });
+  return lines.split('\n', 1)[0]!.includes('@@') ? lines.replace(/@@/g, '\n') : lines;
 }
 
 /**
- * The value of a field in `text`, which runs from its tag to the next one: without the blanks and the statement end
- * (`-`) at its end.
+ * The value of a field in `text`, which runs from its tag to the next one: without the statement end (`-`) and the line
+ * feeds at its end. Other blanks there stay: the subfield of a `:86:` that ends it may precede others in the purpose.
  *
  * Trimmed without a pattern such as `/\n+$/`, which takes quadratic time on a long run of line breaks.
  */
 function fieldValue(text: string): string {
-  const value = text.trimEnd();
-  return value.endsWith('\n-') ? value.substring(0, value.length - 2).trimEnd() : value;
+  const trimmed = text.trimEnd();
+  let end = trimmed.endsWith('\n-') ? trimmed.length - 2 : text.length;
+  while (end > 0 && text.charCodeAt(end - 1) === 0x0a) end--;
+  return text.substring(0, end);
 }
 
-const balancePattern = /^([CD])(\d{6})([A-Z]{3})(\d+,\d*)/;
+/** The date is `0` or `000000` for the first statement of an account. */
+const balancePattern = /^([CD])(\d{6}|0)([A-Z]{3})(\d+,\d*)/;
+const dateTimePattern = /^(\d{6})\d{4}/;
 const currencyPrefix = /^([A-Z]{3})/;
 
 class StatementBuilder {
@@ -134,6 +157,8 @@ class StatementBuilder {
   openingDate: Date | undefined;
   closing: Amount | undefined;
   closingDate: Date | undefined;
+  /** The day an MT942 was created (field 13D). */
+  creationDate: Date | undefined;
   readonly transactions: TransactionLines[] = [];
 
   /**
@@ -151,19 +176,28 @@ class StatementBuilder {
   add(tag: string, value: string): void {
     switch (tag) {
       case '20':
-        this.reference = value.trim();
+        this.reference = trimBlanks(value);
         break;
       case '25':
         if (this.accountId !== undefined) throw new FormatError('MT940 statement with two accounts', this.reference);
-        this.accountId = value.trim();
+        this.accountId = trimBlanks(value);
         break;
       case '28C':
       case '28':
         if (this.statementNumber !== undefined) {
           throw new FormatError('MT940 statement with two statement numbers', this.reference);
         }
-        this.statementNumber = value.trim();
+        this.statementNumber = trimBlanks(value);
         break;
+      case '13D':
+      case '13': {
+        if (this.creationDate !== undefined) {
+          throw new FormatError('MT940 statement with two creation dates', this.reference);
+        }
+        const m = dateTimePattern.exec(trimBlanks(value));
+        this.creationDate = (m && parseSwiftDate(m[1]!)) ?? fail('Invalid MT940 creation date', value);
+        break;
+      }
       case '60F':
       case '60M': {
         if (this.opening !== undefined) {
@@ -187,7 +221,7 @@ class StatementBuilder {
         break;
       }
       case '34F':
-        this.currency ??= currencyPrefix.exec(value.trim())?.[1];
+        this.currency ??= currencyPrefix.exec(trimBlanks(value))?.[1];
         break;
       case '61':
         this.transactions.push(new TransactionLines(value));
@@ -205,20 +239,28 @@ class StatementBuilder {
       throw new FormatError('MT940 statement without currency', this.reference);
     }
     const { openingDate, closingDate } = this;
+    if (openingDate && closingDate && closingDate.getTime() < openingDate.getTime()) {
+      throw new FormatError('MT940 closing balance dated before the opening balance', this.reference);
+    }
     const period = openingDate && closingDate ? ([openingDate, closingDate] as const) : undefined;
-    const transactions = this.transactions.map((t) => t.toTransaction(statementCurrency!, this.status, period));
+    const transactions = this.transactions.map((t) =>
+      t.toTransaction(statementCurrency!, this.status, period, this.creationDate),
+    );
     this.checkBalances(transactions);
-    return Object.freeze({
-      reference: this.reference,
-      accountId: this.accountId,
-      statementNumber: this.statementNumber,
-      currency: statementCurrency,
-      openingBalance: this.opening,
-      openingDate: this.openingDate,
-      closingBalance: this.closing,
-      closingDate: this.closingDate,
-      transactions: Object.freeze(transactions),
-    });
+    return frozenWithInspect(
+      {
+        reference: this.reference,
+        accountId: this.accountId,
+        statementNumber: this.statementNumber,
+        currency: statementCurrency,
+        openingBalance: this.opening,
+        openingDate: this.openingDate,
+        closingBalance: this.closing,
+        closingDate: this.closingDate,
+        transactions: Object.freeze(transactions),
+      },
+      (s) => `Mt940Statement(${maskedId(s.accountId ?? '')}, ${counted(s.transactions.length, 'transaction')})`,
+    );
   }
 
   /** Checks that the statement states both balances or neither, and that its `transactions` lead from one to the other. */
@@ -231,28 +273,17 @@ class StatementBuilder {
     if (opening.currency !== this.currency || closing.currency !== this.currency) {
       throw new FormatError('MT940 balances in another currency than the statement', this.reference);
     }
-    if (!balanceAfter(opening, transactions).equals(closing)) {
+    if (!addsUpTo([opening, ...transactions.map((t) => t.amount)], closing)) {
       throw new FormatError('MT940 transactions do not add up to the closing balance', this.reference);
     }
   }
 }
 
-/** `opening` plus the amounts of `transactions`; throws `FormatError` for a sum beyond what an `Amount` holds. */
-function balanceAfter(opening: Amount, transactions: readonly Transaction[]): Amount {
-  try {
-    return transactions.reduce((balance, t) => balance.add(t.amount), opening);
-  } catch (error) {
-    if (error instanceof RangeError) throw new FormatError('MT940 amounts too large to add up');
-    throw error;
-  }
-}
-
-function parseBalance(value: string): [Amount, Date] {
-  const m = balancePattern.exec(value.trim());
+function parseBalance(value: string): [Amount, Date | undefined] {
+  const m = balancePattern.exec(trimBlanks(value));
   if (!m) throw new FormatError('Unreadable MT940 balance', value);
   const amount = Amount.parseDecimal(m[4]!, m[3]!);
-  const date = parseSwiftDate(m[2]!);
-  if (date === undefined) throw new FormatError('Invalid balance date', value);
+  const date = Number(m[2]) === 0 ? undefined : (parseSwiftDate(m[2]!) ?? fail('Invalid balance date', value));
   return [m[1] === 'D' ? amount.negate() : amount, date];
 }
 
@@ -263,27 +294,42 @@ function parseBalance(value: string): [Amount, Date] {
 const line61 =
   /^(\d{6})(\d{4})?(RC|RD|C|D)([A-Z])?(\d+,\d*)([NFS][A-Z0-9]{3})([^\n]*?)(?:\/\/([^\n]*))?(?:\n([\s\S]*))?$/;
 
-/** The dates of the opening and the closing balance of a statement, between which its transactions are booked. */
+/**
+ * The dates between which the transactions of a statement are booked: those of its opening and its closing balance. A
+ * statement without balances, such as an MT942, has the period from the value date of each to the date the statement
+ * was created, or that value date alone.
+ */
 type Period = readonly [first: Date, last: Date];
 
+function spanning(a: Date, b: Date): Period {
+  return a.getTime() <= b.getTime() ? [a, b] : [b, a];
+}
+
 /** The `:61:` line of a transaction and its `:86:` details. */
 class TransactionLines {
   details: string | undefined;
 
   constructor(readonly line: string) {}
 
-  toTransaction(currency: string, status: TransactionStatus, period: Period | undefined): Transaction {
-    const m = line61.exec(this.line.trim());
+  toTransaction(
+    currency: string,
+    status: TransactionStatus,
+    period: Period | undefined,
+    created: Date | undefined,
+  ): Transaction {
+    const m = line61.exec(trimBlanks(this.line));
     const valueDate = m ? parseSwiftDate(m[1]!) : undefined;
     if (!m || valueDate === undefined) throw new FormatError('Unreadable MT940 transaction line (:61:)', this.line);
     const mark = m[3]!;
     const amount = Amount.parseDecimal(m[5]!, currency);
     const debit = mark === 'D' || mark === 'RC';
-    const customerReference = nonBlank(m[7]);
     const d = Details.parse(this.details);
+    const reference = nonBlank(m[7]);
+    // `KREF+` stands for the customer reference that :86: states.
+    const customerReference = reference === 'KREF+' ? d.sepa.get('KREF') : reference;
     return new Transaction({
       status,
-      bookingDate: this.bookingDate(m[2], valueDate, period),
+      bookingDate: this.bookingDate(m[2], valueDate, period ?? spanning(valueDate, created ?? valueDate)),
       valueDate,
       amount: debit ? amount.negate() : amount,
       isReversal: mark.startsWith('R'),
@@ -310,14 +356,13 @@ class TransactionLines {
 
   /**
    * The booking date `MMDD`, in the year that places it within `period`, or else closest to it; of several such years,
-   * the one closest to `valueDate`; without a period, the year closest to `valueDate`. The value date alone misleads:
-   * banks book refunds and corrections with the value date of the original booking, up to 13 months before.
+   * the one closest to `valueDate`. The value date alone misleads: banks book refunds and corrections with the value
+   * date of the original booking, up to 13 months before.
    */
-  private bookingDate(mmdd: string | undefined, valueDate: Date, period: Period | undefined): Date | undefined {
+  private bookingDate(mmdd: string | undefined, valueDate: Date, [first, last]: Period): Date | undefined {
     if (mmdd === undefined) return undefined;
     const month = Number(mmdd.substring(0, 2));
     const day = Number(mmdd.substring(2, 4));
-    const [first, last] = period ?? [valueDate, valueDate];
     const outside = (date: Date): number =>
       Math.max(first.getTime() - date.getTime(), date.getTime() - last.getTime(), 0);
     const fromValueDate = (date: Date): number => Math.abs(date.getTime() - valueDate.getTime());
@@ -365,7 +410,7 @@ class Details {
     const text = raw.replace(/\n/g, '');
     if (!structuredPattern.test(text)) {
       // Free text, whose lines are separate phrases; the purpose and its keywords are read from the same text.
-      const free = raw.replace(/\n/g, ' ').trim();
+      const free = trimBlanks(raw.replace(/\n/g, ' '));
       d.sepa = SepaPurpose.parse(free);
       d.purpose = d.sepa.get('SVWZ') ?? nonBlank(free);
       return d;
@@ -384,8 +429,6 @@ class Details {
     d.purpose = d.sepa.get('SVWZ') ?? nonBlank(purposeParts.join(''));
     d.name = nonBlank(parts([32, 33]).join(''));
     d.readCounterpartyAccount(subfield(30), subfield(31));
-    d.iban ??= d.sepa.get('IBAN');
-    d.bic ??= d.sepa.get('BIC');
     return d;
   }
 
@@ -400,20 +443,13 @@ class Details {
   }
 
   /**
-   * Takes the counterparty's account from subfields 30 (bank) and 31 (account): IBAN and BIC, or account number and
-   * bank code.
+   * Takes the counterparty's account from subfields 30 (bank) and 31 (account): a BIC, or else a bank code, and an IBAN,
+   * or else an account number.
    */
   private readCounterpartyAccount(bank: string | undefined, account: string | undefined): void {
-    if (account !== undefined && ibanPattern.test(account)) {
-      this.iban = account;
-      this.bic = bank;
-      return;
-    }
-    this.accountNumber = account;
-    if (bank !== undefined && bicPattern.test(bank)) {
-      this.bic = bank;
-    } else {
-      this.bankCode = bank;
-    }
+    if (bank !== undefined && bicPattern.test(bank)) this.bic = bank;
+    else this.bankCode = bank;
+    if (account !== undefined && ibanPattern.test(account)) this.iban = account;
+    else this.accountNumber = account;
   }
 }

package/src/formats/readers.ts

@@ -29,11 +29,15 @@ export function mt940Transactions(
  *
  * Each part is decoded on its own, since a bank may start each page with a byte order mark. Each part ends a line
  * before the next one follows, since the parser finds fields at the start of a line and a bank need not end its pages
- * with a line break.
+ * with a line break. Where no part holds a line break, a part ends its line with `@@` instead: a line break after a
+ * first page without `@@`, such as `:20:X`, would make the parser read the `@@` of the others as text.
  */
 function joinedMt940(parts: readonly Uint8Array[]): string {
   const pages = parts.filter((part) => part.length > 0).map((part) => decodeBankText(part));
-  return pages.map((page, i) => (i + 1 < pages.length && !page.endsWith('\n') ? `${page}\n` : page)).join('');
+  const lineEnd = pages.some((page) => page.includes('\n') || page.includes('\r')) ? '\n' : '@@';
+  return pages
+    .map((page, i) => (i + 1 < pages.length && !page.endsWith(lineEnd) ? `${page}${lineEnd}` : page))
+    .join('');
 }
 
 /**

package/src/formats/sepa-purpose.ts

@@ -1,3 +1,6 @@
+import { invalidArgument } from '../util/errors.js';
+import { trimBlanks } from '../util/text.js';
+
 /** SEPA keywords German banks put into the purpose text, each followed by `+`. */
 const keywords = [
   'EREF',
@@ -26,8 +29,8 @@ export function providedReference(reference: string | undefined): string | undef
 
 const keywordPattern = new RegExp(`(${keywords.join('|')})\\+`, 'g');
 
-/** The keywords German banks write after the remittance information (`SVWZ`). */
-const afterRemittance = new Set(['ABWA', 'ABWE']);
+/** The keywords of the text the payer or the payee writes, which German banks put after every other keyword. */
+const payerText = new Set(['SVWZ', 'ABWA', 'ABWE']);
 
 /** Parser for the SEPA keywords in a purpose text. */
 export const SepaPurpose = Object.freeze({
@@ -39,10 +42,11 @@ export const SepaPurpose = Object.freeze({
    * `…4711EREF+` may be where one line ends and the next begins.
    *
    * The remittance information (`SVWZ+`) and the ultimate debtor and creditor (`ABWA+`, `ABWE+`) are text the payer or
-   * the payee writes, which banks put after every other keyword. So from the first of them on only `ABWA+` and `ABWE+`
-   * start a value: a keyword in that text, such as `IBAN+`, is part of it. A keyword that occurs twice has no value:
-   * which of the two the bank wrote cannot be told, since a reference the payee chose, such as `EREF+`, comes before
-   * the bank's `CRED+` and may hold `CRED+…` and `SVWZ+`, which turns the bank's value into remittance information.
+   * the payee writes, which banks put after every other keyword, some of them `ABWA+` or `ABWE+` first. So from the
+   * first of them on only these three start a value: any other keyword in that text, such as `IBAN+`, is part of it. A
+   * keyword that occurs twice has no value: which of the two the bank wrote cannot be told, since a reference the payee
+   * chose, such as `EREF+`, comes before the bank's `CRED+` and may hold `CRED+…` and `SVWZ+`, which turns the bank's
+   * value into remittance information.
    */
   parse(purpose: string): Map<string, string> {
     return split(purpose, new Set());
@@ -54,11 +58,15 @@ export const SepaPurpose = Object.freeze({
    *
    * A keyword also counts at the start of a part, where the previous value may end in a capital letter, as in
    * `EREF+NOTPROVIDED` followed by a part `MREF+…`.
+   *
+   * Throws `TypeError` for a string, whose characters would count as parts, and for parts that are no strings.
    */
   parseParts(parts: Iterable<string>): Map<string, string> {
+    if (typeof parts === 'string') throw invalidArgument('Must be the parts, not one string', 'parts');
     let text = '';
     const partStarts = new Set<number>();
     for (const part of parts) {
+      if (typeof part !== 'string') throw invalidArgument('Must be strings', 'parts');
       partStarts.add(text.length);
       text += part;
     }
@@ -76,14 +84,14 @@ function split(purpose: string, partStarts: ReadonlySet<number>): Map<string, st
     if (!atWordStart(m.index)) continue;
     const keyword = m[1]!;
     occurrences.set(keyword, (occurrences.get(keyword) ?? 0) + 1);
-    if (inPayerText && !afterRemittance.has(keyword)) continue;
-    inPayerText ||= keyword === 'SVWZ' || afterRemittance.has(keyword);
+    if (inPayerText && !payerText.has(keyword)) continue;
+    inPayerText ||= payerText.has(keyword);
     matches.push(m);
   }
   const result = new Map<string, string>();
   matches.forEach((m, i) => {
     const end = i + 1 < matches.length ? matches[i + 1]!.index : purpose.length;
-    if (occurrences.get(m[1]!) === 1) result.set(m[1]!, purpose.substring(m.index + m[0].length, end).trim());
+    if (occurrences.get(m[1]!) === 1) result.set(m[1]!, trimBlanks(purpose.substring(m.index + m[0].length, end)));
   });
   return result;
 }