@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/core/transaction.ts

@@ -0,0 +1,156 @@
+import { formatIsoDate } from '../util/dates.js';
+import { ImmutableMap } from '../util/immutable-map.js';
+import type { Amount } from './amount.js';
+
+/** Whether a transaction is booked or still pending. */
+export type TransactionStatus = 'booked' | 'pending';
+
+/** Transaction format to request; `auto` prefers camt.052 when the bank supports it. */
+export type TransactionFormat =
+  /** camt.052 where the bank offers it, otherwise MT940. */
+  | 'auto'
+  /** SWIFT MT940 (booked) and MT942 (pending). */
+  | 'mt940'
+  /** ISO 20022 camt.052. */
+  | 'camt';
+
+/** What `Transaction` takes; the parsers fill in what the bank states. */
+export interface TransactionInit {
+  status?: TransactionStatus;
+  bookingDate?: Date | undefined;
+  valueDate: Date;
+  amount: Amount;
+  isReversal?: boolean;
+  bookingText?: string | undefined;
+  purpose?: string | undefined;
+  counterpartyName?: string | undefined;
+  counterpartyIban?: string | undefined;
+  counterpartyBic?: string | undefined;
+  counterpartyAccountNumber?: string | undefined;
+  counterpartyBankCode?: string | undefined;
+  endToEndId?: string | undefined;
+  mandateId?: string | undefined;
+  creditorId?: string | undefined;
+  customerReference?: string | undefined;
+  bankReference?: string | undefined;
+  transactionCode?: string | undefined;
+  transactionTypeId?: string | undefined;
+  primaNota?: string | undefined;
+  ultimateCreditor?: string | undefined;
+  ultimateDebtor?: string | undefined;
+  purposeCodes?: ReadonlyMap<string, string>;
+}
+
+/** A single account transaction, parsed from camt.052 or MT940/MT942. */
+export class Transaction {
+  /** Whether the transaction is booked or pending. */
+  readonly status: TransactionStatus;
+
+  /**
+   * Booking date; `undefined` where the bank states none, as for some pending transactions and MT940 entries without an
+   * entry date. A local `Date` at midnight, like every calendar date.
+   */
+  readonly bookingDate: Date | undefined;
+
+  /** Value date (Valuta); for a camt entry that states its booking date only, the booking date. */
+  readonly valueDate: Date;
+
+  /** Signed amount; negative for debits. */
+  readonly amount: Amount;
+
+  /** Whether this is a reversal (Storno) of an earlier booking. */
+  readonly isReversal: boolean;
+
+  /** Booking type text, for example `SEPA-UEBERWEISUNG`. */
+  readonly bookingText: string | undefined;
+
+  /** Remittance information; the `SVWZ+` part when the bank sends SEPA keywords. */
+  readonly purpose: string | undefined;
+
+  /** Payee for debits, payer for credits; for a reversal, the counterparty of the booking it reverses. */
+  readonly counterpartyName: string | undefined;
+
+  /** IBAN of the counterparty. */
+  readonly counterpartyIban: string | undefined;
+
+  /** BIC of the counterparty's bank. */
+  readonly counterpartyBic: string | undefined;
+
+  /** National account number of the counterparty, where the bank does not state an IBAN. */
+  readonly counterpartyAccountNumber: string | undefined;
+
+  /** German bank code of the counterparty's bank, where the bank does not state a BIC. */
+  readonly counterpartyBankCode: string | undefined;
+
+  /** SEPA end-to-end reference (EREF). */
+  readonly endToEndId: string | undefined;
+
+  /** SEPA direct debit mandate reference (MREF). */
+  readonly mandateId: string | undefined;
+
+  /** SEPA creditor identifier (CRED). */
+  readonly creditorId: string | undefined;
+
+  /** Reference the customer gave the order. */
+  readonly customerReference: string | undefined;
+
+  /** Reference the bank gave the booking. */
+  readonly bankReference: string | undefined;
+
+  /** German business transaction code (Geschäftsvorfallcode, GVC). */
+  readonly transactionCode: string | undefined;
+
+  /** SWIFT transaction type, for example `NTRF`. */
+  readonly transactionTypeId: string | undefined;
+
+  /** Prima nota number of the booking. */
+  readonly primaNota: string | undefined;
+
+  /** The party the payee acts for, where that is not the payee itself. */
+  readonly ultimateCreditor: string | undefined;
+
+  /** The party the payer acts for, where that is not the payer itself. */
+  readonly ultimateDebtor: string | undefined;
+
+  /** All SEPA keywords found in the purpose, keyed by keyword (EREF, KREF, MREF, CRED, SVWZ, …). */
+  readonly purposeCodes: ReadonlyMap<string, string>;
+
+  constructor(init: TransactionInit) {
+    this.status = init.status ?? 'booked';
+    this.bookingDate = init.bookingDate;
+    this.valueDate = init.valueDate;
+    this.amount = init.amount;
+    this.isReversal = init.isReversal ?? false;
+    this.bookingText = init.bookingText;
+    this.purpose = init.purpose;
+    this.counterpartyName = init.counterpartyName;
+    this.counterpartyIban = init.counterpartyIban;
+    this.counterpartyBic = init.counterpartyBic;
+    this.counterpartyAccountNumber = init.counterpartyAccountNumber;
+    this.counterpartyBankCode = init.counterpartyBankCode;
+    this.endToEndId = init.endToEndId;
+    this.mandateId = init.mandateId;
+    this.creditorId = init.creditorId;
+    this.customerReference = init.customerReference;
+    this.bankReference = init.bankReference;
+    this.transactionCode = init.transactionCode;
+    this.transactionTypeId = init.transactionTypeId;
+    this.primaNota = init.primaNota;
+    this.ultimateCreditor = init.ultimateCreditor;
+    this.ultimateDebtor = init.ultimateDebtor;
+    this.purposeCodes = new ImmutableMap(init.purposeCodes ?? []);
+  }
+
+  /** Whether the transaction is still pending. */
+  get isPending(): boolean {
+    return this.status === 'pending';
+  }
+
+  /**
+   * The date and status only, without amount, counterparty or purpose, so that logs and crash reports do not collect
+   * account data.
+   */
+  toString(): string {
+    return `Transaction(${formatIsoDate(this.bookingDate ?? this.valueDate)}, ${this.status}${this.isReversal ? ', reversal' : ''})`;
+  }
+}

package/src/core/transport.ts

@@ -0,0 +1,114 @@
+import { concatBytes } from '../util/bytes.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. */
+export interface FinTsTransport {
+  /**
+   * Posts `body` to `url` and returns the response body.
+   *
+   * Implementations report failures as `FinTsTransportError`.
+   */
+  post(url: URL, body: Uint8Array, contentType: string): Promise<Uint8Array>;
+
+  /** Releases the connection; the client calls it when it is closed. */
+  close(): void;
+}
+
+/** 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. */
+  fetch?: typeof fetch;
+  /** Time for the whole exchange in milliseconds, from sending the request to the last byte of the response; 90 s. */
+  timeoutMs?: number;
+  /** Largest response accepted, so that a faulty server cannot exhaust the memory; 16 MiB. */
+  maxResponseBytes?: number;
+}
+
+/**
+ * Default `FinTsTransport`: HTTP POST with `fetch`.
+ *
+ * In a browser it only reaches servers that allow the page's origin (CORS), which bank servers do not: a web app needs
+ * a server of its own between browser and bank, reached with a `FinTsTransport` of its own.
+ */
+export class HttpTransport implements FinTsTransport {
+  readonly timeoutMs: number;
+  readonly maxResponseBytes: number;
+  private readonly fetchFn: typeof fetch;
+
+  constructor(options: HttpTransportOptions = {}) {
+    this.fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+    this.timeoutMs = options.timeoutMs ?? 90_000;
+    this.maxResponseBytes = options.maxResponseBytes ?? 16 << 20;
+  }
+
+  async post(url: URL, body: Uint8Array, contentType: string): Promise<Uint8Array> {
+    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);
+    });
+    try {
+      return await Promise.race([this.exchange(url, body, contentType, controller.signal), timedOut]);
+    } catch (error) {
+      if (error instanceof FinTsTransportError) throw error;
+      if (controller.signal.aborted) throw new FinTsTransportError('Request timed out');
+      throw new FinTsTransportError(describe(error));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private async exchange(url: URL, body: Uint8Array, contentType: string, signal: AbortSignal): Promise<Uint8Array> {
+    const response = await this.fetchFn(url, {
+      method: 'POST',
+      body: body as Uint8Array<ArrayBuffer>,
+      headers: { 'Content-Type': contentType, 'Cache-Control': 'no-cache', Pragma: 'no-cache' },
+      // The PIN travels in the body: never let the request be repeated at another address.
+      redirect: 'manual',
+      signal,
+    });
+    if (response.type === 'opaqueredirect') {
+      throw new FinTsTransportError('The server redirects the request, which the client does not follow');
+    }
+    if (response.status < 200 || response.status > 299) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new FinTsTransportError(`HTTP ${response.status} ${response.statusText}`.trim(), {
+        statusCode: response.status,
+      });
+    }
+    return this.readBody(response);
+  }
+
+  private async readBody(response: Response): Promise<Uint8Array> {
+    const reader = response.body?.getReader();
+    if (reader === undefined) return new Uint8Array(await response.arrayBuffer());
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      size += value.length;
+      if (size > this.maxResponseBytes) {
+        await reader.cancel().catch(() => undefined);
+        throw new FinTsTransportError(`Response larger than ${this.maxResponseBytes} bytes`);
+      }
+    }
+    return concatBytes(chunks);
+  }
+
+  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 {
+  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

@@ -0,0 +1,169 @@
+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 { parseXml, type XmlElement } from '../util/xml.js';
+import { providedReference, SepaPurpose } from './sepa-purpose.js';
+
+/** Parser for ISO 20022 camt.052 and camt.053 account reports. */
+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.
+   */
+  parseTransactions(xml: string, status?: TransactionStatus): Transaction[] {
+    const root = parseXml(xml.trim());
+    return root.descendantsNamed('Ntry').flatMap((entry) => new CamtEntry(entry, status).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.
+ *
+ * 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.
+ */
+class CamtEntry {
+  private readonly amountElement: XmlElement;
+  private readonly currency: string;
+  private readonly debit: boolean;
+  private readonly reversal: boolean;
+  private readonly status: TransactionStatus;
+  private readonly bookingDate: Date | undefined;
+  private readonly valueDate: Date;
+
+  /** German banks send `transaction type+GVC+prima nota`, for example `NDDT+105+9310`. */
+  private readonly proprietaryCode: readonly string[];
+
+  constructor(
+    private readonly entry: XmlElement,
+    forcedStatus: TransactionStatus | undefined,
+  ) {
+    this.amountElement = entry.child('Amt') ?? fail('camt entry without amount');
+    this.currency = this.amountElement.getAttribute('Ccy') ?? fail('camt amount without currency');
+    this.debit = debitIndicator(entry.textAt(['CdtDbtInd'])) ?? fail('camt entry without credit/debit indicator');
+    this.reversal = ['true', '1'].includes(entry.textAt(['RvslInd']) ?? '');
+    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.proprietaryCode = entry.textAt(['BkTxCd', 'Prtry', 'Cd'])?.split('+') ?? [];
+  }
+
+  private statusOfEntry(): TransactionStatus {
+    const code = this.entry.textAt(['Sts', 'Cd']) ?? this.entry.textAt(['Sts']);
+    return code === 'PDNG' || code === 'INFO' ? 'pending' : 'booked';
+  }
+
+  transactions(): Transaction[] {
+    const total = Amount.parseDecimal(this.amountElement.innerText, this.currency);
+    const details = this.entry.descendantsNamed('TxDtls');
+    if (details.length <= 1) return [this.transaction(details[0], 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(
+        detail,
+        Amount.parseDecimal(amount.innerText, amount.getAttribute('Ccy') ?? this.currency),
+        // A detail may book in the other direction than the batch as a whole.
+        debitIndicator(detail.textAt(['CdtDbtInd'])) ?? this.debit,
+      );
+    });
+  }
+
+  /** 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 {
+    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 keywords = SepaPurpose.parseParts(purposeParts);
+    const endToEndId = providedReference(details?.textAt(['Refs', 'EndToEndId']));
+    const mandateId = details?.textAt(['Refs', 'MndtId']);
+    const creditorId = creditorIdOf(parties);
+    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);
+    if (purposeCode !== undefined) purposeCodes.set('PURP', purposeCode);
+    return new Transaction({
+      status: this.status,
+      bookingDate: this.bookingDate,
+      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),
+      counterpartyName: partyName(parties?.child(counterparty)),
+      counterpartyIban: parties?.child(`${counterparty}Acct`)?.textAt(['Id', 'IBAN']),
+      counterpartyAccountNumber: parties?.child(`${counterparty}Acct`)?.textAt(['Id', 'Othr', 'Id']),
+      counterpartyBic: bicOf(agents?.child(`${counterparty}Agt`)),
+      endToEndId,
+      mandateId,
+      creditorId,
+      customerReference: details?.textAt(['Refs', 'InstrId']) ?? details?.textAt(['Refs', 'PmtInfId']),
+      bankReference: details?.textAt(['Refs', 'AcctSvcrRef']) ?? this.entry.textAt(['AcctSvcrRef']),
+      transactionCode: this.proprietaryCode[1],
+      transactionTypeId: typeId,
+      primaNota: this.proprietaryCode[2],
+      ultimateCreditor: partyName(parties?.child('UltmtCdtr')),
+      ultimateDebtor: partyName(parties?.child('UltmtDbtr')),
+      purposeCodes,
+    });
+  }
+}
+
+function fail(message: string): never {
+  throw new FormatError(message);
+}
+
+/** `true` for `DBIT`, `false` for `CRDT`, `undefined` if `indicator` is missing; throws for any other value. */
+function debitIndicator(indicator: string | undefined): boolean | undefined {
+  switch (indicator) {
+    case 'DBIT':
+      return true;
+    case 'CRDT':
+      return false;
+    case undefined:
+      return undefined;
+    default:
+      throw new FormatError('camt credit/debit indicator is neither CRDT nor DBIT', indicator);
+  }
+}
+
+function dateOf(e: XmlElement | undefined): Date | undefined {
+  return parseIsoDate(e?.textAt(['Dt']) ?? e?.textAt(['DtTm']));
+}
+
+function partyName(party: XmlElement | undefined): string | undefined {
+  return party?.textAt(['Nm']) ?? party?.textAt(['Pty', 'Nm']);
+}
+
+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;
+}