@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/core/transaction.ts

@@ -0,0 +1,161 @@
+import { copyDate, 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;
+
+  /**
+   * The SEPA keywords of the purpose, keyed by keyword (EREF, KREF, MREF, CRED, SVWZ, …): those `SepaPurpose` reads. In
+   * camt, EREF, MREF and CRED are those of `endToEndId`, `mandateId` and `creditorId`, which the bank states apart,
+   * never keywords of the remittance text the payer or the payee writes.
+   */
+  readonly purposeCodes: ReadonlyMap<string, string>;
+
+  /** Takes copies of the dates and purpose codes of `init`: each transaction has its own, which no other one shares. */
+  constructor(init: TransactionInit) {
+    this.status = init.status ?? 'booked';
+    this.bookingDate = copyDate(init.bookingDate);
+    this.valueDate = copyDate(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,189 @@
+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. */
+export interface FinTsTransport {
+  /**
+   * Posts `body` to `url` and returns the response body.
+   *
+   * 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, signal: AbortSignal): 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.
+   *
+   * 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. At
+   * most 2147483647 (about 24 days), the longest `setTimeout` waits.
+   */
+  timeoutMs?: number;
+  /** 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`.
+ *
+ * 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;
+
+  /**
+   * Throws `TypeError` if `timeoutMs` is not a positive number of at most 2147483647, or `maxResponseBytes` is not a
+   * positive number.
+   */
+  constructor(options: HttpTransportOptions = {}) {
+    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');
+  }
+
+  /** 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();
+    // 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), stopped]);
+    } catch (error) {
+      if (controller.signal.aborted) throw controller.signal.reason as FinTsTransportError;
+      if (error instanceof FinTsTransportError) throw error;
+      throw new FinTsTransportError(failureMessage(error));
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+    }
+  }
+
+  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');
+    }
+    // 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 discard(response);
+      throw new FinTsTransportError(`HTTP ${response.status} ${response.statusText}`.trim(), {
+        statusCode: response.status,
+      });
+    }
+    return this.readBody(response);
+  }
+
+  private async readBody(response: Response): Promise<Uint8Array> {
+    // 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 (;;) {
+      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 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.
+  }
+}
+
+/** `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

@@ -0,0 +1,266 @@
+import { Amount } from '../core/amount.js';
+import { Transaction, type TransactionStatus } from '../core/transaction.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';
+
+/** 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 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.
+   */
+  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;
+
+/**
+ * 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.
+ */
+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;
+  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[];
+
+  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');
+    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.bookingText = entry.textAt(['AddtlNtryInf']);
+    this.bankReference = entry.textAt(['AcctSvcrRef']);
+    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 = 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'));
+    if (amounts.includes(undefined)) return [booking];
+    const split = details.map((detail, i) =>
+      this.transaction(
+        detail,
+        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?.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?.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);
+    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.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']),
+      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.bankReference,
+      transactionCode: this.proprietaryCode[1],
+      transactionTypeId: typeId,
+      primaNota: this.proprietaryCode[2],
+      ultimateCreditor: partyName(parties?.child('UltmtCdtr')),
+      ultimateDebtor: partyName(parties?.child('UltmtDbtr')),
+      purposeCodes,
+    });
+  }
+}
+
+/**
+ * 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. */
+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);
+  }
+}
+
+/**
+ * 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 {
+  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 {
+  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 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']);
+}