@coderoftime/fints 0.1.0 → 0.2.0

package/src/core/transport.ts

@@ -1,4 +1,5 @@
 import { concatBytes } from '../util/bytes.js';
+import { invalidArgument } from '../util/errors.js';
 import { FinTsTransportError } from './errors.js';
 
 /** Sends one FinTS message and returns the bank's reply; replace it for a relay, proxies, pinning or tests. */
@@ -6,9 +7,16 @@ export interface FinTsTransport {
   /**
    * Posts `body` to `url` and returns the response body.
    *
-   * Implementations report failures as `FinTsTransportError`.
+   * The client aborts `signal` once it is closed: a transport that stops the request then keeps `close` from waiting
+   * for the answer.
+   *
+   * Implementations report failures as `FinTsTransportError`, with the HTTP status as `statusCode` where the bank
+   * answered with an HTTP error: an anonymous request for the bank parameter data that fails so goes out once more,
+   * without the announcement of strong authentication, which some banks fail on. Of any other error, another
+   * `FinTsError` included, the client keeps only its message and that of its cause, as a `FinTsTransportError` without
+   * `statusCode`. `body` holds PIN and TAN in plain text: keep it out of error messages and logs.
    */
-  post(url: URL, body: Uint8Array, contentType: string): Promise<Uint8Array>;
+  post(url: URL, body: Uint8Array, contentType: string, signal: AbortSignal): Promise<Uint8Array>;
 
   /** Releases the connection; the client calls it when it is closed. */
   close(): void;
@@ -16,14 +24,26 @@ export interface FinTsTransport {
 
 /** What `HttpTransport` takes; all optional. */
 export interface HttpTransportOptions {
-  /** The `fetch` to send with, for example one with a proxy agent; the global `fetch` by default. */
+  /**
+   * The `fetch` to send with, for example one with a proxy agent; the global `fetch` by default.
+   *
+   * It must post to the URL it is given: an answer from another URL counts as a redirect, which fails the request. Of
+   * an answer whose `body` is no `ReadableStream`, as with node-fetch, the size can only be checked once it is read
+   * whole.
+   */
   fetch?: typeof fetch;
-  /** Time for the whole exchange in milliseconds, from sending the request to the last byte of the response; 90 s. */
+  /**
+   * Time for the whole exchange in milliseconds, from sending the request to the last byte of the response; 90 s. At
+   * most 2147483647 (about 24 days), the longest `setTimeout` waits.
+   */
   timeoutMs?: number;
-  /** Largest response accepted, so that a faulty server cannot exhaust the memory; 16 MiB. */
+  /** Largest response accepted in bytes, so that a faulty server cannot exhaust the memory; 16 MiB. */
   maxResponseBytes?: number;
 }
 
+/** The longest delay `setTimeout` takes; it fires at once for a longer one, such as `Infinity`. */
+const maxTimeoutMs = 2 ** 31 - 1;
+
 /**
  * Default `FinTsTransport`: HTTP POST with `fetch`.
  *
@@ -35,30 +55,47 @@ export class HttpTransport implements FinTsTransport {
   readonly maxResponseBytes: number;
   private readonly fetchFn: typeof fetch;
 
+  /**
+   * Throws `TypeError` if `timeoutMs` is not a positive number of at most 2147483647, or `maxResponseBytes` is not a
+   * positive number.
+   */
   constructor(options: HttpTransportOptions = {}) {
-    this.fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+    const custom = options.fetch;
+    // Called as a plain function: a browser's native `fetch` fails as a method of another object.
+    this.fetchFn = custom === undefined ? (input, init) => fetch(input, init) : (input, init) => custom(input, init);
     this.timeoutMs = options.timeoutMs ?? 90_000;
     this.maxResponseBytes = options.maxResponseBytes ?? 16 << 20;
+    if (!isPositive(this.timeoutMs) || this.timeoutMs > maxTimeoutMs) {
+      throw invalidArgument(`Must be a positive number of at most ${maxTimeoutMs}`, 'timeoutMs');
+    }
+    if (!isPositive(this.maxResponseBytes)) throw invalidArgument('Must be a positive number', 'maxResponseBytes');
   }
 
-  async post(url: URL, body: Uint8Array, contentType: string): Promise<Uint8Array> {
+  /** Fails with `FinTsTransportError` at the timeout or once `signal` is aborted; sends nothing if it is already. */
+  async post(url: URL, body: Uint8Array, contentType: string, signal?: AbortSignal): Promise<Uint8Array> {
+    if (signal?.aborted) throw new FinTsTransportError('Request aborted');
     const controller = new AbortController();
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    // Waiting for the timeout as well covers a `fetch` that cannot abort a request.
-    const timedOut = new Promise<never>((_, reject) => {
-      timer = setTimeout(() => {
-        controller.abort();
-        reject(new FinTsTransportError('Request timed out'));
-      }, this.timeoutMs);
+    // Raced with the exchange, for a `fetch` that cannot abort a request.
+    const stopped = new Promise<never>((_, reject) => {
+      controller.signal.addEventListener('abort', () => {
+        reject(controller.signal.reason as FinTsTransportError);
+      });
     });
+    const stop = (message: string) => (): void => {
+      controller.abort(new FinTsTransportError(message));
+    };
+    const timer = setTimeout(stop('Request timed out'), this.timeoutMs);
+    const abort = stop('Request aborted');
+    signal?.addEventListener('abort', abort);
     try {
-      return await Promise.race([this.exchange(url, body, contentType, controller.signal), timedOut]);
+      return await Promise.race([this.exchange(url, body, contentType, controller.signal), stopped]);
     } catch (error) {
+      if (controller.signal.aborted) throw controller.signal.reason as FinTsTransportError;
       if (error instanceof FinTsTransportError) throw error;
-      if (controller.signal.aborted) throw new FinTsTransportError('Request timed out');
-      throw new FinTsTransportError(describe(error));
+      throw new FinTsTransportError(failureMessage(error));
     } finally {
       clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
     }
   }
 
@@ -74,8 +111,13 @@ export class HttpTransport implements FinTsTransport {
     if (response.type === 'opaqueredirect') {
       throw new FinTsTransportError('The server redirects the request, which the client does not follow');
     }
+    // A `fetch` that ignores `redirect`, as one over XMLHttpRequest does, shows a redirect it followed only here.
+    if (response.redirected || (response.url && response.url !== withoutFragment(url))) {
+      await discard(response);
+      throw new FinTsTransportError('The fetch followed a redirect: the request may have gone to another address');
+    }
     if (response.status < 200 || response.status > 299) {
-      await response.body?.cancel().catch(() => undefined);
+      await discard(response);
       throw new FinTsTransportError(`HTTP ${response.status} ${response.statusText}`.trim(), {
         statusCode: response.status,
       });
@@ -84,8 +126,14 @@ export class HttpTransport implements FinTsTransport {
   }
 
   private async readBody(response: Response): Promise<Uint8Array> {
-    const reader = response.body?.getReader();
-    if (reader === undefined) return new Uint8Array(await response.arrayBuffer());
+    // A `fetch` that does not stream, as one over XMLHttpRequest or node-fetch, gives no body or one of another kind.
+    const body = response.body as ReadableStream<Uint8Array> | null | undefined;
+    if (typeof body?.getReader !== 'function') {
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      if (bytes.length > this.maxResponseBytes) throw this.tooLarge();
+      return bytes;
+    }
+    const reader = body.getReader();
     const chunks: Uint8Array[] = [];
     let size = 0;
     for (;;) {
@@ -95,19 +143,46 @@ export class HttpTransport implements FinTsTransport {
       size += value.length;
       if (size > this.maxResponseBytes) {
         await reader.cancel().catch(() => undefined);
-        throw new FinTsTransportError(`Response larger than ${this.maxResponseBytes} bytes`);
+        throw this.tooLarge();
       }
     }
     return concatBytes(chunks);
   }
 
+  private tooLarge(): FinTsTransportError {
+    return new FinTsTransportError(`Response larger than ${this.maxResponseBytes} bytes`);
+  }
+
   close(): void {
     // `fetch` keeps no connection the transport could release.
   }
 }
 
-/** The message of a `fetch` failure, with its cause: Node.js reports `fetch failed` and the reason in the cause. */
-function describe(error: unknown): string {
+/** `url` as `Response.url` gives it: without fragment. */
+function withoutFragment(url: URL): string {
+  const copy = new URL(url);
+  copy.hash = '';
+  return copy.href;
+}
+
+/** Cancels the body of a response the transport rejects, unless it cannot be cancelled, as a Node.js stream cannot. */
+async function discard(response: Response): Promise<void> {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // The response is rejected all the same.
+  }
+}
+
+function isPositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+/**
+ * The message of a failed request, with the message of its cause: Node.js reports `fetch failed` and the reason in the
+ * cause. Only the messages, since the error may hold the request, PIN and TAN included.
+ */
+export function failureMessage(error: unknown): string {
   if (!(error instanceof Error)) return String(error);
   const cause: unknown = error.cause;
   return cause instanceof Error ? `${error.message}: ${cause.message}` : error.message;

package/src/formats/camt.ts

@@ -1,30 +1,81 @@
 import { Amount } from '../core/amount.js';
 import { Transaction, type TransactionStatus } from '../core/transaction.js';
-import { parseIsoDate } from '../util/dates.js';
-import { FormatError } from '../util/errors.js';
+import { germanDay, parseIsoDate, parseIsoMoment } from '../util/dates.js';
+import { fail, FormatError } from '../util/errors.js';
 import { parseXml, type XmlElement } from '../util/xml.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.
+   * 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[] {
+    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.
    *
    * `status` overrides the booking status stated in the entries.
    */
-  parseTransactions(xml: string, status?: TransactionStatus): Transaction[] {
-    const root = parseXml(xml.trim());
-    return root.descendantsNamed('Ntry').flatMap((entry) => new CamtEntry(entry, status).transactions());
+  parse(xml: string, status?: TransactionStatus): CamtStatement[] {
+    return parseCamt(xml, status, new RecordBudget());
   },
 });
 
+/** `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 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 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())),
+    });
+  });
+}
+
 /** 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.
+ * 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.
  *
  * 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 +88,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 +97,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 +106,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,44 +117,53 @@ 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,
-      );
-    });
+      ),
+    );
+    return addUpTo(split, booking) ? 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) => text.trim() !== '');
+    // 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 purpose = purposeParts.join('').trim();
     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);
+    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);
@@ -109,7 +174,7 @@ class CamtEntry {
       valueDate: this.valueDate,
       amount: debit ? amount.negate() : amount,
       isReversal: this.reversal,
-      bookingText: this.entry.textAt(['AddtlNtryInf']) ?? details?.textAt(['AddtlTxInf']),
+      bookingText: this.bookingText ?? details?.textAt(['AddtlTxInf']),
       purpose: keywords.get('SVWZ') ?? (purpose === '' ? details?.textAt(['AddtlTxInf']) : purpose),
       counterpartyName: partyName(parties?.child(counterparty)),
       counterpartyIban: parties?.child(`${counterparty}Acct`)?.textAt(['Id', 'IBAN']),
@@ -119,7 +184,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 +195,29 @@ 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;
+}
+
+/**
+ * Whether the amounts of `parts` add up to that of `whole`, in its currency; amounts whose sum an `Amount` cannot hold
+ * do not.
+ */
+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;
+  }
 }
 
 /** `true` for `DBIT`, `false` for `CRDT`, `undefined` if `indicator` is missing; throws for any other value. */
@@ -148,8 +234,17 @@ 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.
+ */
 function dateOf(e: XmlElement | undefined): Date | undefined {
-  return parseIsoDate(e?.textAt(['Dt']) ?? e?.textAt(['DtTm']));
+  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));
 }
 
 function partyName(party: XmlElement | undefined): string | undefined {
@@ -160,10 +255,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']);
 }