@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/formats/mt940.ts

@@ -0,0 +1,333 @@
+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 { providedReference, SepaPurpose } from './sepa-purpose.js';
+
+/** One statement from an MT940 or MT942 file, with its balances and transactions. */
+export interface Mt940Statement {
+  /** The sender's reference of the statement (field 20). */
+  readonly reference: string | undefined;
+  /** The account the statement is for (field 25). */
+  readonly accountId: string | undefined;
+  /** Statement and sequence number (field 28C). */
+  readonly statementNumber: string | undefined;
+  /** Currency of the statement; `undefined` for a statement without balances and transactions. */
+  readonly currency: string | undefined;
+  /** The balance at the start of the statement (field 60), negative for a debit. */
+  readonly openingBalance: Amount | undefined;
+  /** The date of `openingBalance`. */
+  readonly openingDate: Date | undefined;
+  /** The balance at the end of the statement (field 62), negative for a debit. */
+  readonly closingBalance: Amount | undefined;
+  /** The date of `closingBalance`. */
+  readonly closingDate: Date | undefined;
+  /** The transactions of the statement, in the order the bank lists them. */
+  readonly transactions: readonly Transaction[];
+}
+
+/** What the MT940 parser takes besides the text. */
+export interface Mt940Options {
+  /** The status of the transactions: `booked` (MT940, the default) or `pending` (MT942). */
+  status?: TransactionStatus;
+  /** The currency of statements that state none in their balances. */
+  currency?: string | undefined;
+}
+
+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({
+  /** Parses all transactions; see `parse`. */
+  parseTransactions(text: string, options: Mt940Options = {}): Transaction[] {
+    return Mt940.parse(text, options).flatMap((s) => [...s.transactions]);
+  },
+
+  /**
+   * Parses all statements.
+   *
+   * Throws `FormatError` if a transaction line (`:61:`) cannot be read or the currency of a transaction is unknown.
+   */
+  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;
+  },
+});
+
+const balancePattern = /^([CD])(\d{6})([A-Z]{3})(\d+,\d*)/;
+const currencyPrefix = /^([A-Z]{3})/;
+
+class StatementBuilder {
+  reference: string | undefined;
+  accountId: string | undefined;
+  statementNumber: string | undefined;
+  currency: string | undefined;
+  opening: Amount | undefined;
+  openingDate: Date | undefined;
+  closing: Amount | undefined;
+  closingDate: Date | undefined;
+  readonly transactions: TransactionLines[] = [];
+
+  /**
+   * The tag added last: a `:86:` right after a `:61:` details the transaction, anywhere else it informs the account
+   * owner about the statement.
+   */
+  private previousTag: string | undefined;
+
+  constructor(
+    private readonly status: TransactionStatus,
+    /** Currency to use when the statement states none. */
+    private readonly fallbackCurrency: string | undefined,
+  ) {}
+
+  add(tag: string, value: string): void {
+    switch (tag) {
+      case '20':
+        this.reference = value.trim();
+        break;
+      case '25':
+        this.accountId = value.trim();
+        break;
+      case '28C':
+      case '28':
+        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;
+        }
+        break;
+      }
+      case '62F':
+      case '62M': {
+        const balance = parseBalance(value);
+        if (balance) {
+          [this.closing, this.closingDate] = balance;
+          this.currency ??= balance[0].currency;
+        }
+        break;
+      }
+      case '34F':
+        this.currency ??= currencyPrefix.exec(value.trim())?.[1];
+        break;
+      case '61':
+        this.transactions.push(new TransactionLines(value));
+        break;
+      case '86':
+        if (this.previousTag === '61') this.transactions.at(-1)!.details = value;
+        break;
+    }
+    this.previousTag = tag;
+  }
+
+  build(): Mt940Statement {
+    const statementCurrency = this.currency ?? this.fallbackCurrency;
+    if (statementCurrency === undefined && this.transactions.length > 0) {
+      throw new FormatError('MT940 statement without currency', this.reference);
+    }
+    return Object.freeze({
+      reference: this.reference,
+      accountId: this.accountId,
+      statementNumber: this.statementNumber,
+      currency: statementCurrency,
+      openingBalance: this.opening,
+      openingDate: this.openingDate,
+      closingBalance: this.closing,
+      closingDate: this.closingDate,
+      transactions: Object.freeze(this.transactions.map((t) => t.toTransaction(statementCurrency!, this.status))),
+    });
+  }
+}
+
+function parseBalance(value: string): [Amount, Date] | undefined {
+  const m = balancePattern.exec(value.trim());
+  if (!m) return undefined;
+  const amount = Amount.parseDecimal(m[4]!, m[3]!);
+  const date = parseSwiftDate(m[2]!);
+  if (date === undefined) throw new FormatError('Invalid balance date', value);
+  return [m[1] === 'D' ? amount.negate() : amount, date];
+}
+
+/**
+ * Value date, optional booking date (MMDD), debit/credit mark, funds code, amount, transaction type, customer
+ * reference, optional bank reference and supplementary details.
+ */
+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 `:61:` line of a transaction and its `:86:` details. */
+class TransactionLines {
+  details: string | undefined;
+
+  constructor(readonly line: string) {}
+
+  toTransaction(currency: string, status: TransactionStatus): 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 d = Details.parse(this.details);
+    return new Transaction({
+      status,
+      bookingDate: this.bookingDate(m[2], valueDate),
+      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,
+      transactionCode: d.transactionCode,
+      bookingText: d.bookingText,
+      primaNota: d.primaNota,
+      purpose: d.purpose,
+      counterpartyName: d.name,
+      counterpartyIban: d.iban,
+      counterpartyBic: d.bic,
+      counterpartyAccountNumber: d.accountNumber,
+      counterpartyBankCode: d.bankCode,
+      endToEndId: providedReference(d.sepa.get('EREF')),
+      mandateId: d.sepa.get('MREF'),
+      creditorId: d.sepa.get('CRED'),
+      ultimateCreditor: d.sepa.get('ABWE'),
+      ultimateDebtor: d.sepa.get('ABWA'),
+      purposeCodes: d.sepa,
+    });
+  }
+
+  /** 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 {
+    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;
+  }
+}
+
+/**
+ * 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.
+ */
+const structuredPattern = /^(\d{3})([^\w\s])\d{2}/;
+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;
+  bookingText: string | undefined;
+  primaNota: string | undefined;
+  purpose: string | undefined;
+  name: string | undefined;
+  iban: string | undefined;
+  bic: string | undefined;
+  accountNumber: string | undefined;
+  bankCode: string | undefined;
+  sepa = new Map<string, string>();
+
+  static parse(raw: string | undefined): Details {
+    const d = new Details();
+    if (raw === undefined) return d;
+    const text = raw.replace(/\n/g, '');
+    const structured = structuredPattern.exec(text);
+    if (!structured) {
+      // 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);
+      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;
+    };
+    // 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);
+
+    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.readCounterpartyAccount(subfield(30), subfield(31));
+    d.iban ??= d.sepa.get('IBAN');
+    d.bic ??= d.sepa.get('BIC');
+    return d;
+  }
+
+  /** 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> {
+    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]!);
+    }
+    return subfields;
+  }
+
+  /**
+   * Takes the counterparty's account from subfields 30 (bank) and 31 (account): IBAN and BIC, or account number and
+   * bank code.
+   */
+  private readCounterpartyAccount(bank: string | undefined, account: string | undefined): void {
+    if (account !== undefined && ibanPattern.test(account)) {
+      this.iban = account;
+      this.bic = bank;
+      return;
+    }
+    this.accountNumber = account;
+    if (bank !== undefined && bicPattern.test(bank)) {
+      this.bic = bank;
+    } else {
+      this.bankCode = bank;
+    }
+  }
+}

package/src/formats/readers.ts

@@ -0,0 +1,56 @@
+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';
+
+/**
+ * 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.
+ */
+export function mt940Transactions(
+  booked: readonly Uint8Array[],
+  pending: readonly Uint8Array[],
+  currency: string | undefined,
+): Transaction[] {
+  return [
+    ...Mt940.parseTransactions(joinedMt940(booked), { currency }),
+    ...Mt940.parseTransactions(joinedMt940(pending), { currency, status: 'pending' }),
+  ];
+}
+
+const lineFeed = 0x0a;
+const carriageReturn = 0x0d;
+const atSign = 0x40;
+
+/**
+ * The MT940 `parts` as one text.
+ *
+ * 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.
+ */
+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());
+}
+
+/** The transactions in camt documents; each document stands on its own. */
+export function camtTransactions(booked: readonly Uint8Array[], pending: readonly Uint8Array[]): Transaction[] {
+  return [
+    ...booked.flatMap((document) => Camt.parseTransactions(decodeXmlText(document))),
+    ...pending.flatMap((document) => Camt.parseTransactions(decodeXmlText(document), 'pending')),
+  ];
+}

package/src/formats/sepa-purpose.ts

@@ -0,0 +1,75 @@
+/** SEPA keywords German banks put into the purpose text, each followed by `+`. */
+const keywords = [
+  'EREF',
+  'KREF',
+  'MREF',
+  'CRED',
+  'DEBT',
+  'COAM',
+  'OAMT',
+  'SVWZ',
+  'ABWA',
+  'ABWE',
+  'IBAN',
+  'BIC',
+  'PURP',
+  'SQTP',
+];
+
+/** The filler SEPA prescribes where the payer gave no end-to-end reference. */
+const notProvided = 'NOTPROVIDED';
+
+/** `reference`, or `undefined` if it is missing or the filler for a reference the payer did not give. */
+export function providedReference(reference: string | undefined): string | undefined {
+  return reference === notProvided ? undefined : reference;
+}
+
+const keywordPattern = new RegExp(`(${keywords.join('|')})\\+`, 'g');
+
+/** Parser for the SEPA keywords in a purpose text. */
+export const SepaPurpose = Object.freeze({
+  /**
+   * Splits `purpose` into its SEPA keywords (EREF, KREF, MREF, CRED, SVWZ, …) and their values.
+   *
+   * 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.
+   */
+  parse(purpose: string): Map<string, string> {
+    return split(purpose, new Set());
+  },
+
+  /**
+   * Like `parse` for a purpose the bank sends in `parts`, such as the MT940 subfields `?20` to `?29`, which continue
+   * each other without a separator.
+   *
+   * A keyword also counts at the start of a part, where the previous value may end in a capital letter, as in
+   * `EREF+NOTPROVIDED` followed by a part `MREF+…`.
+   */
+  parseParts(parts: Iterable<string>): Map<string, string> {
+    let text = '';
+    const partStarts = new Set<number>();
+    for (const part of parts) {
+      partStarts.add(text.length);
+      text += part;
+    }
+    return split(text, partStarts);
+  },
+});
+
+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 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());
+  });
+  return result;
+}
+
+function isCapitalLetter(text: string, index: number): boolean {
+  const c = text.charCodeAt(index);
+  return c >= 0x41 && c <= 0x5a;
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * FinTS 3.0 client for German banks: accounts, balances and transactions with PIN/TAN, PSD2 strong customer
+ * authentication and decoupled app approval.
+ *
+ * Start with `FinTs3Client`. The public API is what this file names; everything else is internal.
+ *
+ * @packageDocumentation
+ */
+
+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';
+export { BankInfo, BankMessage } from './core/bank-info.js';
+export type {
+  BankMessageHandler,
+  FinTsClient,
+  FinTsClientOptions,
+  MessageDirection,
+  MessageLogger,
+  TransactionQuery,
+  WarningHandler,
+} from './core/client.js';
+export { FinTsConfig, type FinTsConfigInit } from './core/config.js';
+export {
+  FinTsBankError,
+  FinTsDecoupledTimeoutError,
+  FinTsDialogAbortedError,
+  FinTsError,
+  FinTsLoginDataChangedError,
+  FinTsPinError,
+  FinTsProtocolError,
+  FinTsStateError,
+  FinTsTanCancelledError,
+  FinTsTanError,
+  FinTsTransportError,
+  FinTsUnsupportedError,
+} from './core/errors.js';
+export { FeedbackCodes, FinTsFeedback } from './core/feedback.js';
+export {
+  Transaction,
+  type TransactionFormat,
+  type TransactionInit,
+  type TransactionStatus,
+} from './core/transaction.js';
+export { HttpTransport, type FinTsTransport, type HttpTransportOptions } from './core/transport.js';
+export { Camt } from './formats/camt.js';
+export { Mt940, type Mt940Options, type Mt940Statement } from './formats/mt940.js';
+export { SepaPurpose } from './formats/sepa-purpose.js';
+export {
+  TanAnswer,
+  TanChallenge,
+  type TanCallback,
+  type TanChallengeInit,
+  type TanMediumSelector,
+  type TanMethodSelector,
+} from './tan/challenge.js';
+export { FlickerCode, type HhdVersion } from './tan/flicker.js';
+export { TanImage } from './tan/tan-image.js';
+export {
+  TanMedium,
+  TanMethod,
+  type TanMediumInit,
+  type TanMediumRequirement,
+  type TanMediumStatus,
+  type TanMethodInit,
+} from './tan/tan-models.js';
+export { FormatError } from './util/errors.js';
+export { FinTs3Client, type FinTs3ClientInit } from './v3/client.js';