@coderoftime/fints 0.1.0 → 0.3.0

package/src/formats/camt.ts

@@ -1,30 +1,88 @@
-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 { parseIsoDate } from '../util/dates.js';
-import { FormatError } from '../util/errors.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';
 
-/** Parser for ISO 20022 camt.052 and camt.053 account reports. */
+/** One report (camt.052), statement (camt.053) or notification (camt.054): the entries of one account. */
+export interface CamtStatement {
+  /** The bank's identification of the statement (`Id`). */
+  readonly reference: string | undefined;
+  /** The account the statement is for: its IBAN, or the bank's other identification of it where it states none. */
+  readonly accountId: string | undefined;
+  /** The currency of the account, where the statement states it. */
+  readonly currency: string | undefined;
+  /** The transactions of the statement, in the order the bank lists them. */
+  readonly transactions: readonly Transaction[];
+}
+
+/** Local names of the elements of a document that hold the entries of one account. */
+const statementNames = new Set(['Rpt', 'Stmt', 'Ntfctn']);
+
+/** Parser for ISO 20022 camt.052, camt.053 and camt.054 account reports, statements and notifications. */
 export const Camt = Object.freeze({
   /**
-   * Parses all entries; throws `FormatError` for malformed XML, and for an entry without amount, currency, credit/debit
-   * indicator or date.
-   *
-   * `status` overrides the booking status stated in the entries.
+   * Parses the transactions of all statements in one list, which does not tell the account of each: a document may hold
+   * statements of several accounts, which `parse` keeps apart. Throws as `parse` does.
    */
   parseTransactions(xml: string, status?: TransactionStatus): Transaction[] {
-    const root = parseXml(xml.trim());
-    return root.descendantsNamed('Ntry').flatMap((entry) => new CamtEntry(entry, status).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 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, unless it is `undefined` or `null`; throws `TypeError`
+   * for one other than `booked` and `pending`.
+   */
+  parse(xml: string, status?: TransactionStatus): CamtStatement[] {
+    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(trimBlanks(xml));
+  const statements = root.childElements.flatMap((message) =>
+    message.childElements.filter((c) => statementNames.has(c.localName)),
+  );
+  if (statements.length === 0) throw new FormatError('camt document without report, statement or notification');
+  return statements.map((statement) => {
+    budget.take();
+    const account = statement.child('Acct');
+    const entries = statement.childrenNamed('Ntry');
+    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;
 
 /**
- * One booking (`Ntry`) of a report; a batch booking yields one transaction per transaction detail (`TxDtls`) when every
- * detail states its amount.
+ * 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.
  *
  * Nothing is guessed: what the entry lacks, and what the reader needs, is a `FormatError`. The one exception is the
  * value date, which `Transaction.valueDate` requires: an entry with a booking date only takes that.
@@ -37,6 +95,8 @@ class CamtEntry {
   private readonly status: TransactionStatus;
   private readonly bookingDate: Date | undefined;
   private readonly valueDate: Date;
+  private readonly bookingText: string | undefined;
+  private readonly bankReference: string | undefined;
 
   /** German banks send `transaction type+GVC+prima nota`, for example `NDDT+105+9310`. */
   private readonly proprietaryCode: readonly string[];
@@ -44,6 +104,7 @@ class CamtEntry {
   constructor(
     private readonly entry: XmlElement,
     forcedStatus: TransactionStatus | undefined,
+    private readonly budget: RecordBudget,
   ) {
     this.amountElement = entry.child('Amt') ?? fail('camt entry without amount');
     this.currency = this.amountElement.getAttribute('Ccy') ?? fail('camt amount without currency');
@@ -52,6 +113,8 @@ class CamtEntry {
     this.status = forcedStatus ?? this.statusOfEntry();
     this.bookingDate = dateOf(entry.child('BookgDt'));
     this.valueDate = dateOf(entry.child('ValDt')) ?? this.bookingDate ?? fail('camt entry without date');
+    this.bookingText = entry.textAt(['AddtlNtryInf']);
+    this.bankReference = entry.textAt(['AcctSvcrRef']);
     this.proprietaryCode = entry.textAt(['BkTxCd', 'Prtry', 'Cd'])?.split('+') ?? [];
   }
 
@@ -61,47 +124,56 @@ class CamtEntry {
   }
 
   transactions(): Transaction[] {
-    const total = Amount.parseDecimal(this.amountElement.innerText, this.currency);
-    const details = this.entry.descendantsNamed('TxDtls');
+    const total = amountOf(this.amountElement, this.currency);
+    const details = this.entry.childrenNamed('NtryDtls').flatMap((d) => d.childrenNamed('TxDtls'));
     if (details.length <= 1) return [this.transaction(details[0], total, this.debit)];
+    // A batch is split only into details that make up its booking: each states its amount, and they add up to the
+    // booked one, in its currency. It stays one booking otherwise, without the details of any one of them, which would
+    // describe the others wrongly.
+    const booking = this.transaction(undefined, total, this.debit);
     const amounts = details.map((detail) => detail.at(['AmtDtls', 'TxAmt', 'Amt']) ?? detail.child('Amt'));
-    // Without the amount of every detail the batch cannot be split. It stays one booking then, without the details of
-    // any one of them, which would describe the others wrongly.
-    if (amounts.includes(undefined)) return [this.transaction(undefined, total, this.debit)];
-    return details.map((detail, i) => {
-      const amount = amounts[i]!;
-      return this.transaction(
+    if (amounts.includes(undefined)) return [booking];
+    const split = details.map((detail, i) =>
+      this.transaction(
         detail,
-        Amount.parseDecimal(amount.innerText, amount.getAttribute('Ccy') ?? this.currency),
+        amountOf(amounts[i]!, this.currency),
         // A detail may book in the other direction than the batch as a whole.
         debitIndicator(detail.textAt(['CdtDbtInd'])) ?? this.debit,
-      );
-    });
+      ),
+    );
+    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. */
   private transaction(details: XmlElement | undefined, amount: Amount, debit: boolean): Transaction {
+    this.budget.take();
     const parties = details?.child('RltdPties');
     const agents = details?.child('RltdAgts');
     // The related parties describe the original operation, which a reversal books the other way round (ISO 20022
     // `RvslInd`: with `CRDT` the original operation was a debit, with `DBIT` a credit).
     const originalDebit = debit !== this.reversal;
     const counterparty = originalDebit ? 'Cdtr' : 'Dbtr';
-    const lines = (details?.descendantsNamed('Ustrd') ?? [])
-      .map((line) => line.innerText.trim())
-      .filter((text) => text !== '');
-    const purposeParts = lines.map((line, i) => (i > 0 && lines[i - 1]!.length !== cutLineLength ? ` ${line}` : line));
-    const purpose = purposeParts.join('');
+    const lines = (details?.child('RmtInf')?.childrenNamed('Ustrd') ?? [])
+      .map((line) => line.innerText)
+      .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 : trimBlanks(line, { start: false });
+      return i === 0 || cut(i - 1) ? part : ` ${trimBlanks(part, { end: false })}`;
+    });
+    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);
+    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);
-    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,
@@ -109,8 +181,12 @@ class CamtEntry {
       valueDate: this.valueDate,
       amount: debit ? amount.negate() : amount,
       isReversal: this.reversal,
-      bookingText: this.entry.textAt(['AddtlNtryInf']) ?? details?.textAt(['AddtlTxInf']),
-      purpose: keywords.get('SVWZ') ?? (purpose === '' ? details?.textAt(['AddtlTxInf']) : purpose),
+      bookingText: this.bookingText ?? details?.textAt(['AddtlTxInf']),
+      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']),
@@ -119,7 +195,7 @@ class CamtEntry {
       mandateId,
       creditorId,
       customerReference: details?.textAt(['Refs', 'InstrId']) ?? details?.textAt(['Refs', 'PmtInfId']),
-      bankReference: details?.textAt(['Refs', 'AcctSvcrRef']) ?? this.entry.textAt(['AcctSvcrRef']),
+      bankReference: details?.textAt(['Refs', 'AcctSvcrRef']) ?? this.bankReference,
       transactionCode: this.proprietaryCode[1],
       transactionTypeId: typeId,
       primaNota: this.proprietaryCode[2],
@@ -130,8 +206,31 @@ class CamtEntry {
   }
 }
 
-function fail(message: string): never {
-  throw new FormatError(message);
+/**
+ * The amount `element` states, in its currency or else in `currency`; throws `FormatError` for a negative one, whose
+ * sign the credit/debit indicator would turn: the indicator alone gives the direction.
+ */
+function amountOf(element: XmlElement, currency: string): Amount {
+  const amount = Amount.parseDecimal(element.innerText, element.getAttribute('Ccy') ?? currency);
+  if (amount.isNegative) throw new FormatError('Negative camt amount', element.innerText);
+  return amount;
+}
+
+/**
+ * `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 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. */
@@ -148,8 +247,15 @@ function debitIndicator(indicator: string | undefined): boolean | undefined {
   }
 }
 
+/**
+ * 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 {
-  return parseIsoDate(e?.textAt(['Dt']) ?? e?.textAt(['DtTm']));
+  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 {
@@ -160,10 +266,12 @@ function bicOf(agent: XmlElement | undefined): string | undefined {
   return agent?.textAt(['FinInstnId', 'BIC']) ?? agent?.textAt(['FinInstnId', 'BICFI']);
 }
 
-/** The SEPA creditor identifier: the `Othr` identification in the scheme `SEPA`. */
-function creditorIdOf(parties: XmlElement | undefined): string | undefined {
-  for (const other of parties?.descendantsNamed('Othr') ?? []) {
-    if (other.textAt(['SchmeNm', 'Prtry']) === 'SEPA') return other.textAt(['Id']);
-  }
-  return undefined;
+/**
+ * The SEPA creditor identifier of the `creditor`: its private `Othr` identification in the scheme `SEPA`. The other
+ * parties' identifications are the creditor's or the debtor's to choose, and may be in that scheme as well.
+ */
+function creditorIdOf(creditor: XmlElement | undefined): string | undefined {
+  const identifications = creditor?.at(['Id', 'PrvtId']) ?? creditor?.at(['Pty', 'Id', 'PrvtId']);
+  const sepa = identifications?.childrenNamed('Othr').find((other) => other.textAt(['SchmeNm', 'Prtry']) === 'SEPA');
+  return sepa?.textAt(['Id']);
 }