@coderoftime/fints 0.1.0 → 0.2.0

package/src/formats/mt940.ts

@@ -2,7 +2,8 @@ import { Amount } from '../core/amount.js';
 import { Transaction, type TransactionStatus } from '../core/transaction.js';
 import { clampedDate, parseSwiftDate } from '../util/dates.js';
 import { FormatError } from '../util/errors.js';
-import { escapeRegExp } from '../util/text.js';
+import { nonBlank } from '../util/text.js';
+import { RecordBudget } from './record-budget.js';
 import { providedReference, SepaPurpose } from './sepa-purpose.js';
 
 /** One statement from an MT940 or MT942 file, with its balances and transactions. */
@@ -23,7 +24,10 @@ export interface Mt940Statement {
   readonly closingBalance: Amount | undefined;
   /** The date of `closingBalance`. */
   readonly closingDate: Date | undefined;
-  /** The transactions of the statement, in the order the bank lists them. */
+  /**
+   * The transactions of the statement, in the order the bank lists them; they lead from `openingBalance` to
+   * `closingBalance` where the statement states these.
+   */
   readonly transactions: readonly Transaction[];
 }
 
@@ -36,8 +40,6 @@ export interface Mt940Options {
 }
 
 const tagPattern = /^:(\d{2}[A-Z]?):/gm;
-const statementEnd = /\n-\s*$/;
-const trailingNewlines = /\n+$/;
 
 /** Parser for SWIFT MT940/MT942 statements, including German structured `:86:` fields. */
 export const Mt940 = Object.freeze({
@@ -47,35 +49,79 @@ export const Mt940 = Object.freeze({
   },
 
   /**
-   * Parses all statements.
+   * 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` if a transaction line (`:61:`) cannot be read or the currency of a transaction is unknown.
+   * 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
+   * 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.
    */
   parse(text: string, options: Mt940Options = {}): Mt940Statement[] {
-    const status = options.status ?? 'booked';
-    const lines = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-    // Some banks separate lines with `@@` instead of line breaks; where there are line breaks, `@@` is text.
-    const normalized = lines.includes('\n') ? lines : lines.replace(/@@/g, '\n');
-    const tags = [...normalized.matchAll(tagPattern)];
-    const statements: Mt940Statement[] = [];
-    let current: StatementBuilder | undefined;
-    tags.forEach((tag, i) => {
-      const end = i + 1 < tags.length ? tags[i + 1]!.index : normalized.length;
-      const value = normalized
-        .substring(tag.index + tag[0].length, end)
-        .replace(statementEnd, '')
-        .replace(trailingNewlines, '');
-      if (tag[1] === '20' || current === undefined) {
-        if (current !== undefined) statements.push(current.build());
-        current = new StatementBuilder(status, options.currency);
-      }
-      current.add(tag[1]!, value);
-    });
-    if (current !== undefined) statements.push(current.build());
-    return statements;
+    return parseMt940(text, options, new RecordBudget());
   },
 });
 
+/** `Mt940.parse`, which takes each statement and transaction from `budget`, before it builds it. */
+export function parseMt940(text: string, options: Mt940Options, budget: RecordBudget): Mt940Statement[] {
+  const status = options.status ?? 'booked';
+  const normalized = withLineFeeds(text);
+  const statements: Mt940Statement[] = [];
+  let current: StatementBuilder | undefined;
+  for (const [tag, value] of taggedParts(normalized, tagPattern)) {
+    if (tag === '20' || current === undefined) {
+      if (current !== undefined) statements.push(current.build());
+      budget.take();
+      current = new StatementBuilder(status, options.currency);
+    }
+    if (tag === '61') budget.take();
+    current.add(tag, fieldValue(value));
+  }
+  if (current !== undefined) statements.push(current.build());
+  else if (normalized.trim() !== '') throw new FormatError('MT940 data without fields');
+  return statements;
+}
+
+/**
+ * The parts of `text` that the matches of `tag` start, each the first group of its match and the text up to the next
+ * match: the fields of a statement, or the subfields of a `:86:`. One by one: text of a few megabytes holds millions of
+ * them. A pattern that matched the text up to the next tag as well would run out of backtracking stack on a part of a
+ * few million characters.
+ */
+function* taggedParts(text: string, tag: RegExp): Generator<[tag: string, text: string]> {
+  let current: string | undefined;
+  let start = 0;
+  for (const match of text.matchAll(tag)) {
+    if (current !== undefined) yield [current, text.substring(start, match.index)];
+    current = match[1]!;
+    start = match.index + match[0].length;
+  }
+  if (current !== undefined) yield [current, text.substring(start)];
+}
+
+/**
+ * `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.
+ */
+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;
+}
+
+/**
+ * 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.
+ *
+ * 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 balancePattern = /^([CD])(\d{6})([A-Z]{3})(\d+,\d*)/;
 const currencyPrefix = /^([A-Z]{3})/;
 
@@ -108,28 +154,36 @@ class StatementBuilder {
         this.reference = value.trim();
         break;
       case '25':
+        if (this.accountId !== undefined) throw new FormatError('MT940 statement with two accounts', this.reference);
         this.accountId = value.trim();
         break;
       case '28C':
       case '28':
+        if (this.statementNumber !== undefined) {
+          throw new FormatError('MT940 statement with two statement numbers', this.reference);
+        }
         this.statementNumber = value.trim();
         break;
       case '60F':
       case '60M': {
-        const balance = parseBalance(value);
-        if (balance) {
-          [this.opening, this.openingDate] = balance;
-          this.currency ??= balance[0].currency;
+        if (this.opening !== undefined) {
+          throw new FormatError('MT940 statement with two opening balances', this.reference);
         }
+        const [balance, date] = parseBalance(value);
+        this.opening = balance;
+        this.openingDate = date;
+        this.currency ??= balance.currency;
         break;
       }
       case '62F':
       case '62M': {
-        const balance = parseBalance(value);
-        if (balance) {
-          [this.closing, this.closingDate] = balance;
-          this.currency ??= balance[0].currency;
+        if (this.closing !== undefined) {
+          throw new FormatError('MT940 statement with two closing balances', this.reference);
         }
+        const [balance, date] = parseBalance(value);
+        this.closing = balance;
+        this.closingDate = date;
+        this.currency ??= balance.currency;
         break;
       }
       case '34F':
@@ -150,6 +204,10 @@ class StatementBuilder {
     if (statementCurrency === undefined && this.transactions.length > 0) {
       throw new FormatError('MT940 statement without currency', this.reference);
     }
+    const { openingDate, closingDate } = this;
+    const period = openingDate && closingDate ? ([openingDate, closingDate] as const) : undefined;
+    const transactions = this.transactions.map((t) => t.toTransaction(statementCurrency!, this.status, period));
+    this.checkBalances(transactions);
     return Object.freeze({
       reference: this.reference,
       accountId: this.accountId,
@@ -159,14 +217,39 @@ class StatementBuilder {
       openingDate: this.openingDate,
       closingBalance: this.closing,
       closingDate: this.closingDate,
-      transactions: Object.freeze(this.transactions.map((t) => t.toTransaction(statementCurrency!, this.status))),
+      transactions: Object.freeze(transactions),
     });
   }
+
+  /** Checks that the statement states both balances or neither, and that its `transactions` lead from one to the other. */
+  private checkBalances(transactions: readonly Transaction[]): void {
+    const { opening, closing } = this;
+    if (opening === undefined && closing === undefined) return;
+    if (opening === undefined || closing === undefined) {
+      throw new FormatError('MT940 statement with only one of its balances', this.reference);
+    }
+    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)) {
+      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] | undefined {
+function parseBalance(value: string): [Amount, Date] {
   const m = balancePattern.exec(value.trim());
-  if (!m) return undefined;
+  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);
@@ -180,34 +263,33 @@ function parseBalance(value: string): [Amount, Date] | undefined {
 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. */
+type Period = readonly [first: Date, last: Date];
+
 /** The `:61:` line of a transaction and its `:86:` details. */
 class TransactionLines {
   details: string | undefined;
 
   constructor(readonly line: string) {}
 
-  toTransaction(currency: string, status: TransactionStatus): Transaction {
+  toTransaction(currency: string, status: TransactionStatus, period: Period | undefined): Transaction {
     const m = line61.exec(this.line.trim());
     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 = m[7]?.trim();
-    const bankReference = m[8]?.trim();
+    const customerReference = nonBlank(m[7]);
     const d = Details.parse(this.details);
     return new Transaction({
       status,
-      bookingDate: this.bookingDate(m[2], valueDate),
+      bookingDate: this.bookingDate(m[2], valueDate, period),
       valueDate,
       amount: debit ? amount.negate() : amount,
       isReversal: mark.startsWith('R'),
       transactionTypeId: m[6],
-      customerReference:
-        customerReference === undefined || customerReference === '' || customerReference === 'NONREF'
-          ? undefined
-          : customerReference,
-      bankReference: bankReference === undefined || bankReference === '' ? undefined : bankReference,
+      customerReference: customerReference === 'NONREF' ? undefined : customerReference,
+      bankReference: nonBlank(m[8]),
       transactionCode: d.transactionCode,
       bookingText: d.bookingText,
       primaNota: d.primaNota,
@@ -226,34 +308,44 @@ class TransactionLines {
     });
   }
 
-  /** The booking date `MMDD`, in the year that places it closest to `valueDate` (across a year end). */
-  private bookingDate(mmdd: string | undefined, valueDate: Date): Date | undefined {
+  /**
+   * 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.
+   */
+  private bookingDate(mmdd: string | undefined, valueDate: Date, period: Period | undefined): Date | undefined {
     if (mmdd === undefined) return undefined;
     const month = Number(mmdd.substring(0, 2));
     const day = Number(mmdd.substring(2, 4));
-    let year = valueDate.getFullYear();
-    if (month === 12 && valueDate.getMonth() === 0) year--;
-    if (month === 1 && valueDate.getMonth() === 11) year++;
-    const date = clampedDate(year, month, day);
-    if (date === undefined) throw new FormatError('Invalid booking date', this.line);
-    return date;
+    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());
+    // The best year lies next to one of these, however long the period.
+    const years = new Set(
+      [first, valueDate, last].flatMap((d) => [d.getFullYear() - 1, d.getFullYear(), d.getFullYear() + 1]),
+    );
+    let best: Date | undefined;
+    for (const year of years) {
+      const date = clampedDate(year, month, day);
+      if (date === undefined) throw new FormatError('Invalid booking date', this.line);
+      if (best === undefined || (outside(date) - outside(best) || fromValueDate(date) - fromValueDate(best)) < 0) {
+        best = date;
+      }
+    }
+    return best;
   }
 }
 
 /**
- * Three-digit business transaction code (GVC), then the first subfield: a separator, usually `?`, and its two-digit
- * number. Text that merely starts with three digits, such as `100 Euro`, is free text.
+ * Three-digit business transaction code (GVC), then the first subfield: `?` and its two-digit number. Text that merely
+ * starts with three digits, such as `100 Euro` or `100,00 EUR`, is free text.
  */
-const structuredPattern = /^(\d{3})([^\w\s])\d{2}/;
+const structuredPattern = /^\d{3}\?\d{2}/;
+const subfieldTag = /\?(\d{2})/g;
 const ibanPattern = /^[A-Z]{2}\d{2}[A-Z0-9]+$/;
 const bicPattern = /^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/;
 
-/** Subfield pattern for a separator: the separator, a two-digit key, then everything up to the next subfield. */
-function subfieldPattern(separator: string): RegExp {
-  const s = escapeRegExp(separator);
-  return new RegExp(`${s}(\\d{2})((?:(?!${s}\\d{2})[\\s\\S])*)`, 'g');
-}
-
 /** The German structured `:86:` field: a business transaction code and `?nn` subfields. */
 class Details {
   transactionCode: string | undefined;
@@ -271,20 +363,16 @@ class Details {
     const d = new Details();
     if (raw === undefined) return d;
     const text = raw.replace(/\n/g, '');
-    const structured = structuredPattern.exec(text);
-    if (!structured) {
+    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();
       d.sepa = SepaPurpose.parse(free);
-      d.purpose = d.sepa.get('SVWZ') ?? (free === '' ? undefined : free);
+      d.purpose = d.sepa.get('SVWZ') ?? nonBlank(free);
       return d;
     }
-    d.transactionCode = structured[1];
-    const subfields = Details.subfields(text.substring(3), structured[2]!);
-    const subfield = (key: number): string | undefined => {
-      const value = subfields.get(key)?.trim();
-      return value === undefined || value === '' ? undefined : value;
-    };
+    d.transactionCode = text.substring(0, 3);
+    const subfields = Details.subfields(text.substring(3));
+    const subfield = (key: number): string | undefined => nonBlank(subfields.get(key));
     // Subfields continue each other: they are joined keeping the spaces at their boundaries.
     const parts = (keys: number[]): string[] =>
       keys.map((k) => subfields.get(k)).filter((v): v is string => v !== undefined);
@@ -292,11 +380,9 @@ class Details {
     d.bookingText = subfield(0);
     d.primaNota = subfield(10);
     const purposeParts = parts([20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 60, 61, 62, 63]);
-    const purpose = purposeParts.join('').trim();
     d.sepa = SepaPurpose.parseParts(purposeParts);
-    d.purpose = d.sepa.get('SVWZ') ?? (purpose === '' ? undefined : purpose);
-    const name = parts([32, 33]).join('').trim();
-    d.name = name === '' ? undefined : name;
+    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');
@@ -304,11 +390,11 @@ class Details {
   }
 
   /** The text of each subfield (`?nn` and what follows), by its number; a subfield that appears twice is joined. */
-  private static subfields(text: string, separator: string): Map<number, string> {
+  private static subfields(text: string): Map<number, string> {
     const subfields = new Map<number, string>();
-    for (const m of text.matchAll(subfieldPattern(separator))) {
-      const key = Number(m[1]);
-      subfields.set(key, (subfields.get(key) ?? '') + m[2]!);
+    for (const [tag, value] of taggedParts(text, subfieldTag)) {
+      const key = Number(tag);
+      subfields.set(key, (subfields.get(key) ?? '') + value);
     }
     return subfields;
   }

package/src/formats/readers.ts

@@ -1,56 +1,49 @@
 import type { Transaction } from '../core/transaction.js';
-import { BytesBuilder } from '../util/bytes.js';
 import { decodeBankText, decodeXmlText } from '../util/text.js';
-import { Camt } from './camt.js';
-import { Mt940 } from './mt940.js';
+import { parseCamt } from './camt.js';
+import { parseMt940 } from './mt940.js';
+import { RecordBudget } from './record-budget.js';
 
 /**
  * The transactions in MT940 data: the `booked` parts joined, since a statement may continue on the next page, then the
  * `pending` ones (MT942).
  *
- * `currency` applies to statements that do not state one; throws `FormatError` if both are missing.
+ * `currency` applies to statements that do not state one; throws `FormatError` if both are missing, and for more than
+ * 200,000 statements and transactions in all.
  */
 export function mt940Transactions(
   booked: readonly Uint8Array[],
   pending: readonly Uint8Array[],
   currency: string | undefined,
 ): Transaction[] {
+  const budget = new RecordBudget();
   return [
-    ...Mt940.parseTransactions(joinedMt940(booked), { currency }),
-    ...Mt940.parseTransactions(joinedMt940(pending), { currency, status: 'pending' }),
-  ];
+    ...parseMt940(joinedMt940(booked), { currency }, budget),
+    ...parseMt940(joinedMt940(pending), { currency, status: 'pending' }, budget),
+  ].flatMap((statement) => statement.transactions);
 }
 
-const lineFeed = 0x0a;
-const carriageReturn = 0x0d;
-const atSign = 0x40;
-
 /**
- * The MT940 `parts` as one text.
+ * The MT940 `parts` as one text, whose line separator the parser takes from its first line: a later page may start
+ * with a purpose, which the payer writes.
  *
- * 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. Banks that separate lines with `@@` get that separator.
+ * 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.
  */
 function joinedMt940(parts: readonly Uint8Array[]): string {
-  const pages = parts.filter((part) => part.length > 0);
-  const atSigns = !pages.some((p) => p.includes(lineFeed) || p.includes(carriageReturn));
-  const endsLine = (page: Uint8Array): boolean =>
-    atSigns
-      ? page.length >= 2 && page[page.length - 1] === atSign && page[page.length - 2] === atSign
-      : page.at(-1) === lineFeed || page.at(-1) === carriageReturn;
-
-  const bytes = new BytesBuilder();
-  pages.forEach((page, i) => {
-    if (i > 0 && !endsLine(pages[i - 1]!)) bytes.add(atSigns ? [atSign, atSign] : [lineFeed]);
-    bytes.add(page);
-  });
-  return decodeBankText(bytes.takeBytes());
+  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('');
 }
 
-/** The transactions in camt documents; each document stands on its own. */
+/**
+ * The transactions in camt documents; each document stands on its own. Throws `FormatError` for more than 200,000
+ * statements and transactions in all.
+ */
 export function camtTransactions(booked: readonly Uint8Array[], pending: readonly Uint8Array[]): Transaction[] {
+  const budget = new RecordBudget();
   return [
-    ...booked.flatMap((document) => Camt.parseTransactions(decodeXmlText(document))),
-    ...pending.flatMap((document) => Camt.parseTransactions(decodeXmlText(document), 'pending')),
-  ];
+    ...booked.flatMap((document) => parseCamt(decodeXmlText(document), undefined, budget)),
+    ...pending.flatMap((document) => parseCamt(decodeXmlText(document), 'pending', budget)),
+  ].flatMap((statement) => statement.transactions);
 }

package/src/formats/record-budget.ts

@@ -0,0 +1,18 @@
+import { FormatError } from '../util/errors.js';
+
+/**
+ * Most statements and transactions the parsers build for one query: several times what a year of a busy business
+ * account holds, and few enough that a hostile answer cannot exhaust the memory, at about 600 bytes each. The size of
+ * the answer does not bound them: a transaction takes up to 25 times the bytes of its MT940 line.
+ */
+const maxRecords = 200_000;
+
+/** The statements and transactions the parsers may still build; the parses of one query share one budget. */
+export class RecordBudget {
+  private left = maxRecords;
+
+  /** Counts a statement or transaction about to be built; throws `FormatError` for one beyond the budget. */
+  take(): void {
+    if (--this.left < 0) throw new FormatError(`More than ${maxRecords} statements and transactions`);
+  }
+}

package/src/formats/sepa-purpose.ts

@@ -26,6 +26,9 @@ 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']);
+
 /** Parser for the SEPA keywords in a purpose text. */
 export const SepaPurpose = Object.freeze({
   /**
@@ -34,6 +37,12 @@ export const SepaPurpose = Object.freeze({
    * A keyword counts unless a capital letter comes right before it, so `XEREF+` does not open an EREF value. After a
    * digit or a small letter it does: a purpose line cut at 35 characters is joined to the next one without a space, so
    * `…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.
    */
   parse(purpose: string): Map<string, string> {
     return split(purpose, new Set());
@@ -60,11 +69,21 @@ export const SepaPurpose = Object.freeze({
 function split(purpose: string, partStarts: ReadonlySet<number>): Map<string, string> {
   const atWordStart = (index: number): boolean =>
     index === 0 || partStarts.has(index) || !isCapitalLetter(purpose, index - 1);
-  const matches = [...purpose.matchAll(keywordPattern)].filter((m) => atWordStart(m.index));
+  const occurrences = new Map<string, number>();
+  const matches: RegExpExecArray[] = [];
+  let inPayerText = false;
+  for (const m of purpose.matchAll(keywordPattern)) {
+    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);
+    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;
-    result.set(m[1]!, purpose.substring(m.index + m[0].length, end).trim());
+    if (occurrences.get(m[1]!) === 1) result.set(m[1]!, purpose.substring(m.index + m[0].length, end).trim());
   });
   return result;
 }

package/src/index.ts

@@ -7,6 +7,7 @@
  * @packageDocumentation
  */
 
+export { FinTs3Client, type FinTs3ClientInit } from './client.js';
 export { Account, AccountDataStatus, type AccountCategory, type AccountInit } from './core/account.js';
 export { Amount } from './core/amount.js';
 export { Balance, type BalanceInit } from './core/balance.js';
@@ -27,11 +28,13 @@ export {
   FinTsDialogAbortedError,
   FinTsError,
   FinTsLoginDataChangedError,
+  FinTsLoginRefusedError,
   FinTsPinError,
   FinTsProtocolError,
   FinTsStateError,
   FinTsTanCancelledError,
   FinTsTanError,
+  FinTsTanSetupError,
   FinTsTransportError,
   FinTsUnsupportedError,
 } from './core/errors.js';
@@ -43,7 +46,7 @@ export {
   type TransactionStatus,
 } from './core/transaction.js';
 export { HttpTransport, type FinTsTransport, type HttpTransportOptions } from './core/transport.js';
-export { Camt } from './formats/camt.js';
+export { Camt, type CamtStatement } from './formats/camt.js';
 export { Mt940, type Mt940Options, type Mt940Statement } from './formats/mt940.js';
 export { SepaPurpose } from './formats/sepa-purpose.js';
 export {
@@ -65,4 +68,3 @@ export {
   type TanMethodInit,
 } from './tan/tan-models.js';
 export { FormatError } from './util/errors.js';
-export { FinTs3Client, type FinTs3ClientInit } from './v3/client.js';