@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/v3/queries.ts

@@ -0,0 +1,190 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { Account } from '../core/account.js';
+import type { Balance } from '../core/balance.js';
+import { FinTsBankError, FinTsProtocolError, FinTsUnsupportedError } from '../core/errors.js';
+import type { FinTsFeedback } from '../core/feedback.js';
+import type { Transaction, TransactionFormat } from '../core/transaction.js';
+import { camtTransactions, mt940Transactions } from '../formats/readers.js';
+import type { TanMedium } from '../tan/tan-models.js';
+import type { IncomingMessage3 } from './message.js';
+import type { ParameterStore } from './parameter-store.js';
+import { lists, offeredVersion, requireBankParameters } from './parameters.js';
+import { balanceAccount, camtAccount, parseBalance, parseSepaAccounts, parseTanMedia, Segments } from './segments.js';
+import type { Segment, SegmentSpec } from './syntax.js';
+
+/**
+ * A business transaction: the order to send for each page, and how to read all pages the bank sent.
+ *
+ * Where the bank does not offer the transaction, the builders of the lookups the session makes for itself, of the TAN
+ * media and the SEPA accounts, return `undefined`, and those of the app's queries, of a balance and of transactions,
+ * throw `FinTsUnsupportedError`.
+ */
+export interface Query<T> {
+  /** The order for the page at `continuation`; `undefined` for the first page. */
+  readonly order: (continuation: string | undefined) => SegmentSpec;
+
+  /** Reads the result; throws `FormatError` for malformed data. */
+  readonly read: (pages: readonly IncomingMessage3[]) => T;
+}
+
+/** The segments of `type` in all `pages`. */
+function all(pages: readonly IncomingMessage3[], type: string): Segment[] {
+  return pages.flatMap((p) => p.findAll(type));
+}
+
+function version(
+  parameters: ParameterStore,
+  transaction: string,
+  implemented: readonly number[],
+  options: { account?: Account; requiresEntry?: boolean } = {},
+): number | undefined {
+  return offeredVersion(
+    parameters.bankParameters,
+    parameters.userParameters,
+    transaction,
+    new Set(implemented),
+    options,
+  );
+}
+
+/** Lists the TAN media, and keeps the names as the bank sent them in `parameters`; `undefined` if the bank does not. */
+export function tanMediaQuery(parameters: ParameterStore): Query<TanMedium[]> | undefined {
+  const offered = version(parameters, 'HKTAB', [4, 5]);
+  if (offered === undefined) return undefined;
+  return {
+    order: () => Segments.tanMedia(offered),
+    read: (pages) => {
+      const names = new Map<string, string>();
+      const media = all(pages, 'HITAB').flatMap((s) => parseTanMedia(s, names));
+      parameters.keepTanMediumNames(names);
+      return media;
+    },
+  };
+}
+
+/** Lists IBAN and BIC of the accounts; `undefined` if the bank does not offer it. */
+export function sepaAccountsQuery(parameters: ParameterStore): Query<Account[]> | undefined {
+  const offered = version(parameters, 'HKSPA', [1, 2, 3], { requiresEntry: true });
+  if (offered === undefined) return undefined;
+  const { countryCode, bankCode } = parameters.config;
+  return {
+    order: (continuation) => Segments.sepaAccounts(offered, continuation),
+    read: (pages) => all(pages, 'HISPA').flatMap((s) => parseSepaAccounts(s, countryCode, bankCode)),
+  };
+}
+
+/**
+ * The balance (HISAL) of `account` in `records`: the one whose account matches. A single record must match as well,
+ * though the query asked for this one account only: it names the account it is for.
+ *
+ * Throws `FinTsBankError` with the bank's `feedback` if there is none, and `FinTsProtocolError` if none matches.
+ *
+ * @internal Exported for the tests.
+ */
+export function balanceRecord(
+  records: readonly Segment[],
+  account: Account,
+  feedback: readonly FinTsFeedback[],
+): Segment {
+  if (records.length === 0) throw new FinTsBankError(feedback, 'No balance returned');
+  const match = records.find((record) => balanceAccount(record).matches(account));
+  if (match === undefined) {
+    throw new FinTsProtocolError('The bank returned balances, but none for the requested account');
+  }
+  return match;
+}
+
+/**
+ * The balance of `account`, which the session has taken as the bank knows it, with the transactions the bank permits
+ * for it (`SepaAccounts.complete`); throws `FinTsUnsupportedError` if the bank does not report balances.
+ */
+export function balanceQuery(parameters: ParameterStore, account: Account): Query<Balance> {
+  const offered = version(parameters, 'HKSAL', [6, 7, 8], { account });
+  if (offered === undefined) {
+    throw new FinTsUnsupportedError('The bank reports no balance (HKSAL) for this account');
+  }
+  return {
+    order: (continuation) => Segments.balance(offered, account, continuation),
+    read: (pages) =>
+      parseBalance(
+        balanceRecord(
+          all(pages, 'HISAL'),
+          account,
+          pages.flatMap((p) => p.feedback),
+        ),
+        account,
+      ),
+  };
+}
+
+/**
+ * The transactions of `account` in `format`, from the day of `from` to that of `to`. The session has taken `account` as
+ * the bank knows it, with the transactions the bank permits for it and its currency (`SepaAccounts.complete`).
+ *
+ * The client reads camt.052 only, so camt counts as offered only where the bank offers a camt.052 format. With `auto`
+ * the client takes camt where the bank offers it, unless the user parameter data list only MT940 transactions for the
+ * account.
+ *
+ * Throws `FinTsUnsupportedError` if the bank does not offer the chosen format for the account.
+ */
+export function transactionsQuery(
+  parameters: ParameterStore,
+  account: Account,
+  format: TransactionFormat,
+  from: Date | undefined,
+  to: Date | undefined,
+): Query<Transaction[]> {
+  const camtFormats = requireBankParameters(parameters.bankParameters).camtFormats.filter((f) =>
+    f.includes('camt.052'),
+  );
+  const camtVersion = camtFormats.length === 0 ? undefined : version(parameters, 'HKCAZ', [1], { account });
+  const camt =
+    format === 'camt' ||
+    (format === 'auto' && camtVersion !== undefined && (lists(account, 'HKCAZ') || !lists(account, 'HKKAZ')));
+  const offered = camt ? camtVersion : version(parameters, 'HKKAZ', [6, 7], { account });
+  if (offered === undefined) {
+    throw new FinTsUnsupportedError(
+      `The bank offers no ${camt ? 'camt ' : ''}transactions (${camt ? 'HKCAZ' : 'HKKAZ'}) for this account`,
+    );
+  }
+  if (camt) {
+    return {
+      order: (continuation) => Segments.transactionsCamt(offered, account, camtFormats, { from, to, continuation }),
+      // The first element names the account, the third element group holds the booked documents, the fourth
+      // element the pending one.
+      read: (pages) => {
+        const segments = all(pages, 'HICAZ');
+        if (!segments.every((s) => camtAccount(s).matches(account))) {
+          throw new FinTsProtocolError('The bank returned the transactions of another account than the one asked for');
+        }
+        return camtTransactions(
+          segments.flatMap((s) =>
+            s
+              .group(3)
+              .filter((d) => !d.isEmpty)
+              .map((d) => d.bytes),
+          ),
+          segments.map((s) => s.binary(4)).filter((d) => d !== undefined),
+        );
+      },
+    };
+  }
+  return {
+    order: (continuation) => Segments.transactionsMt940(offered, account, { from, to, continuation }),
+    // The first element holds the booked transactions, the second the pending ones. Unlike HICAZ, HIKAZ names no
+    // account, and banks write the account line of a statement (`:25:`) in many ways, so it is not compared with
+    // `account`: a strict comparison would fail every query of such a bank.
+    read: (pages) =>
+      mt940Transactions(
+        all(pages, 'HIKAZ')
+          .map((s) => s.binary(1))
+          .filter((d) => d !== undefined),
+        all(pages, 'HIKAZ')
+          .map((s) => s.binary(2))
+          .filter((d) => d !== undefined),
+        // The currency of statements that state none.
+        account.currency,
+      ),
+  };
+}

package/src/v3/segments.ts

@@ -0,0 +1,374 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { Account } from '../core/account.js';
+import { Amount, withMark } from '../core/amount.js';
+import { Balance } from '../core/balance.js';
+import { TanMedium, tanMediumStatusOf } from '../tan/tan-models.js';
+import { formatFintsDate, parseFintsDate, parseFintsDateTime } from '../util/dates.js';
+import { FormatError } from '../util/errors.js';
+import { type Segment, SegmentSpec, type SegmentValue, Verbatim } from './syntax.js';
+
+/**
+ * The filler the specification names for a reference that does not exist.
+ *
+ * The bank puts it into a dummy answer when no approval is needed. The client sends it as the TAN medium name in the
+ * dialog that looks up the TAN media, before it knows a medium; the bank ignores it there (PIN/TAN B.4.3.1.3).
+ */
+export const noReference = 'noref';
+
+/** Bank identification (KIK): country code and bank code. */
+function bankIdentification(countryCode: string, bankCode: string): SegmentValue {
+  return [countryCode, bankCode];
+}
+
+/** National account (KTV): account number, sub-account and bank identification. */
+function nationalAccount(a: Account): SegmentValue[] {
+  return [a.accountNumber, a.subAccount, a.countryCode, a.bankCode];
+}
+
+/** International account (KTI): IBAN, BIC, then the national account. */
+function internationalAccount(a: Account): SegmentValue[] {
+  return [a.iban, a.bic, ...nationalAccount(a)];
+}
+
+function dateOrEmpty(date: Date | undefined): string | undefined {
+  return date === undefined ? undefined : formatFintsDate(date);
+}
+
+// HKTAN fields: order reference (Auftragsreferenz), "more TANs follow" and the TAN medium name.
+const orderReferenceField = 5;
+const moreTansField = 6;
+const tanMediumField = 11;
+
+/**
+ * Builders for the request segments the client sends. Values the bank issued, such as the customer system ID, the TAN
+ * order reference and the position to continue at, go back as `Verbatim`.
+ */
+export const Segments = Object.freeze({
+  /** HKIDN: who is logging in, from which customer system. */
+  identification(parts: {
+    countryCode: string;
+    bankCode: string;
+    customerId: string;
+    systemId: string;
+    systemIdRequired: boolean;
+  }): SegmentSpec {
+    return new SegmentSpec('HKIDN', 2, [
+      bankIdentification(parts.countryCode, parts.bankCode),
+      parts.customerId,
+      new Verbatim(parts.systemId),
+      parts.systemIdRequired ? 1 : 0,
+    ]);
+  },
+
+  /** HKVVB: the parameter data versions the client knows, the dialog language and the registered product. */
+  processingPreparation(parts: {
+    bpdVersion: number;
+    updVersion: number;
+    language: number;
+    productId: string;
+    productVersion: string;
+  }): SegmentSpec {
+    return new SegmentSpec('HKVVB', 3, [
+      parts.bpdVersion,
+      parts.updVersion,
+      parts.language,
+      parts.productId,
+      parts.productVersion,
+    ]);
+  },
+
+  /** HKSYN: requests a new customer system ID. */
+  synchronization(): SegmentSpec {
+    return new SegmentSpec('HKSYN', 3, [0]);
+  },
+
+  dialogEnd(dialogId: string): SegmentSpec {
+    return new SegmentSpec('HKEND', 1, [new Verbatim(dialogId)]);
+  },
+
+  /**
+   * HKTAN process 4: asks for strong customer authentication of the `segmentType` sent in the same message, with the TAN
+   * medium `mediumName`, as the bank sent it.
+   */
+  tanProcess4(version: number, segmentType: string, mediumName?: string): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, {
+      1: '4',
+      2: segmentType,
+      [tanMediumField]: Verbatim.of(mediumName),
+    });
+  },
+
+  /** HKTAN process 2: submits the TAN (carried in the signature) for the order with `reference`. */
+  tanProcess2(version: number, reference: string): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, {
+      1: '2',
+      [orderReferenceField]: new Verbatim(reference),
+      [moreTansField]: false,
+    });
+  },
+
+  /** HKTAN process S: asks whether the order with `reference` was approved in the banking app. */
+  tanProcessStatus(version: number, reference: string): SegmentSpec {
+    return SegmentSpec.numbered('HKTAN', version, {
+      1: 'S',
+      [orderReferenceField]: new Verbatim(reference),
+      [moreTansField]: false,
+    });
+  },
+
+  /** HKSAL: the balance of one account (not of all accounts). */
+  balance(version: number, account: Account, continuation?: string): SegmentSpec {
+    return new SegmentSpec('HKSAL', version, [
+      version >= 7 ? internationalAccount(account) : nationalAccount(account),
+      false,
+      null,
+      Verbatim.of(continuation),
+    ]);
+  },
+
+  /** HKKAZ: MT940 transactions of one account. */
+  transactionsMt940(
+    version: number,
+    account: Account,
+    period: { from?: Date | undefined; to?: Date | undefined; continuation?: string | undefined },
+  ): SegmentSpec {
+    return new SegmentSpec('HKKAZ', version, [
+      version >= 7 ? internationalAccount(account) : nationalAccount(account),
+      false,
+      dateOrEmpty(period.from),
+      dateOrEmpty(period.to),
+      null,
+      Verbatim.of(period.continuation),
+    ]);
+  },
+
+  /** HKCAZ: camt transactions of one account in one of `formats`. */
+  transactionsCamt(
+    version: number,
+    account: Account,
+    formats: readonly string[],
+    period: { from?: Date | undefined; to?: Date | undefined; continuation?: string | undefined },
+  ): SegmentSpec {
+    return new SegmentSpec('HKCAZ', version, [
+      internationalAccount(account),
+      formats,
+      false,
+      dateOrEmpty(period.from),
+      dateOrEmpty(period.to),
+      null,
+      Verbatim.of(period.continuation),
+    ]);
+  },
+
+  /** HKSPA: IBAN and BIC of all accounts. */
+  sepaAccounts(version: number, continuation?: string): SegmentSpec {
+    return new SegmentSpec('HKSPA', version, [null, ...(version >= 2 ? [null, Verbatim.of(continuation)] : [])]);
+  },
+
+  /** HKTAB: all TAN media of all classes. */
+  tanMedia(version: number): SegmentSpec {
+    return new SegmentSpec('HKTAB', version, [0, 'A']);
+  },
+});
+
+/** Positions of the data elements in the TAN part of a response (HITAN versions 6 and 7), after the segment header. */
+const Hitan = { process: 1, reference: 3, challenge: 4, hhdUc: 5, validUntil: 6, mediumName: 7 } as const;
+
+/** The TAN part of a response (HITAN). */
+export class TanResponse {
+  constructor(
+    /** The TAN process the segment answers: `4` asks for an approval, `S` answers a status request. */
+    readonly process: string | undefined,
+    /** The order reference, as `Segment.verbatim` reads it, to send back byte for byte. */
+    readonly reference: string | undefined,
+    readonly challenge: string | undefined,
+    readonly hhdUc: Uint8Array | undefined,
+    readonly validUntil: Date | undefined,
+    readonly mediumName: string | undefined,
+  ) {}
+
+  static parse(s: Segment): TanResponse {
+    return new TanResponse(
+      s.text(Hitan.process),
+      s.verbatim(Hitan.reference),
+      s.text(Hitan.challenge),
+      s.binary(Hitan.hhdUc),
+      parseFintsDateTime(s.text(Hitan.validUntil, 0), s.text(Hitan.validUntil, 1)),
+      s.text(Hitan.mediumName),
+    );
+  }
+
+  /** Whether the bank needs no approval although it answered with a TAN segment. */
+  get isDummy(): boolean {
+    return this.reference === undefined || this.reference === noReference;
+  }
+}
+
+/** Positions of the data elements in a balance (HISAL), after the segment header. */
+const Hisal = {
+  account: 1,
+  productName: 2,
+  accountCurrency: 3,
+  bookedBalance: 4,
+  pendingBalance: 5,
+  creditLine: 6,
+  availableAmount: 7,
+  usedAmount: 8,
+  overdraft: 9,
+  bookingTime: 10,
+} as const;
+
+/** Positions inside a balance (SDO): credit/debit mark, value, currency, date and time. */
+const Sdo = { mark: 0, value: 1, currency: 2, date: 3, time: 4 } as const;
+
+/** An amount with currency (BTG) at `index`, or `undefined` if empty. */
+function amountAt(s: Segment, index: number, fallbackCurrency: string): Amount | undefined {
+  const value = s.text(index, 0);
+  if (value === undefined) return undefined;
+  return Amount.parseDecimal(value, s.text(index, 1) ?? fallbackCurrency);
+}
+
+/**
+ * Parses a balance (HISAL); throws `FormatError` if the booked balance is missing or malformed, or a balance has no
+ * credit/debit mark.
+ */
+export function parseBalance(s: Segment, account: Account): Balance {
+  const currency = s.text(Hisal.accountCurrency) ?? account.currency;
+  const signedBalance = (index: number): Amount | undefined => {
+    const value = s.text(index, Sdo.value);
+    if (value === undefined) return undefined;
+    const amountCurrency = s.text(index, Sdo.currency) ?? currency;
+    if (amountCurrency === undefined) throw new FormatError('Balance without currency');
+    return withMark(Amount.parseDecimal(value, amountCurrency), s.text(index, Sdo.mark), 'C', 'D');
+  };
+
+  const booked = signedBalance(Hisal.bookedBalance);
+  if (booked === undefined) throw new FormatError('Balance without booked amount');
+  const bookedDate = s.text(Hisal.bookedBalance, Sdo.date);
+  const bookedAsOf = parseFintsDate(bookedDate);
+  if (bookedAsOf === undefined) throw new FormatError('Balance without date');
+  return new Balance({
+    account,
+    productName: s.text(Hisal.productName),
+    booked,
+    bookedAsOf,
+    bookedAsOfTime: parseFintsDateTime(bookedDate, s.text(Hisal.bookedBalance, Sdo.time)),
+    pending: signedBalance(Hisal.pendingBalance),
+    creditLine: amountAt(s, Hisal.creditLine, booked.currency),
+    available: amountAt(s, Hisal.availableAmount, booked.currency),
+    used: amountAt(s, Hisal.usedAmount, booked.currency),
+    overdraft: amountAt(s, Hisal.overdraft, booked.currency),
+    bookingDate: parseFintsDate(s.text(Hisal.bookingTime, 0)),
+    bookingTime: parseFintsDateTime(s.text(Hisal.bookingTime, 0), s.text(Hisal.bookingTime, 1)),
+  });
+}
+
+/**
+ * The account a balance (HISAL) belongs to: international (IBAN, BIC, then national) from version 7, national before.
+ */
+export function balanceAccount(s: Segment): Account {
+  return accountAt(s, Hisal.account, s.version >= 7);
+}
+
+/** The account camt transactions (HICAZ) belong to, which the first element names (international). */
+export function camtAccount(s: Segment): Account {
+  return accountAt(s, 1, true);
+}
+
+/** The account at `index` of `s`: an `international` one (KTI), else a national one (KTV). */
+function accountAt(s: Segment, index: number, international: boolean): Account {
+  const fields = s.texts(index);
+  const national = international ? 2 : 0;
+  return new Account({
+    iban: international ? fields[0] : undefined,
+    bic: international ? fields[1] : undefined,
+    accountNumber: fields[national],
+    subAccount: fields[national + 1],
+    countryCode: fields[national + 2] ?? '',
+    bankCode: fields[national + 3] ?? '',
+  });
+}
+
+/** Positions inside an account of the SEPA account list (HISPA "Kontoverbindung SEPA"). */
+const Hispa = {
+  isSepaAccount: 0,
+  iban: 1,
+  bic: 2,
+  accountNumber: 3,
+  subAccount: 4,
+  countryCode: 5,
+  bankCode: 6,
+} as const;
+
+/**
+ * Parses the SEPA account list (HISPA), one account per data element. An account the bank marks as no payment account
+ * ("Kontoverwendung SEPA" N) is left out: it has no SEPA connection.
+ */
+export function parseSepaAccounts(s: Segment, defaultCountry: string, defaultBank: string): Account[] {
+  const accounts: Account[] = [];
+  for (let i = 1; i < s.length; i++) {
+    if (s.text(i, Hispa.isSepaAccount) === 'N') continue;
+    if (s.text(i, Hispa.iban) === undefined && s.text(i, Hispa.accountNumber) === undefined) continue;
+    accounts.push(
+      new Account({
+        iban: s.text(i, Hispa.iban),
+        bic: s.text(i, Hispa.bic),
+        accountNumber: s.text(i, Hispa.accountNumber),
+        subAccount: s.text(i, Hispa.subAccount),
+        countryCode: s.text(i, Hispa.countryCode) ?? defaultCountry,
+        bankCode: s.text(i, Hispa.bankCode) ?? defaultBank,
+      }),
+    );
+  }
+  return accounts;
+}
+
+/**
+ * Elements of the account a TAN medium belongs to, a national account (`ktv`: account number, sub-account, country
+ * code, bank code), which shifts every field behind it.
+ */
+const accountWidth = 4;
+
+/**
+ * Parses the TAN media list (HITAB versions 4 and 5, PIN/TAN "TAN-Medium-Liste").
+ *
+ * Each name whose text is not what `Segment.verbatim` reads, such as a name in UTF-8, goes into `namesAsSent`, keyed
+ * by its text: it has to go back as the bank sent it, which its text does not tell where it fits ISO 8859-1.
+ */
+export function parseTanMedia(s: Segment, namesAsSent?: Map<string, string>): TanMedium[] {
+  // Version 5 adds the security function in front of the card number.
+  const version5 = s.version >= 5;
+  const cardNumber = version5 ? 3 : 2;
+  // The card number, card sequence number and card type are followed by the account. Behind it come: valid from, valid
+  // until, TAN list number, name, masked and full mobile number, SMS charge account (six elements), number of free TANs,
+  // last use, activation.
+  const after = cardNumber + 3 + accountWidth;
+  const media: TanMedium[] = [];
+  // The first data element is the TAN usage option; the media follow.
+  for (let i = 2; i < s.length; i++) {
+    const fields = s.texts(i);
+    const mediumClass = fields[0];
+    if (mediumClass === undefined) continue;
+    const name = fields[after + 3];
+    const nameAsSent = s.verbatim(i, after + 3);
+    if (name !== undefined && nameAsSent !== undefined && nameAsSent !== name) namesAsSent?.set(name, nameAsSent);
+    media.push(
+      new TanMedium({
+        mediumClass,
+        status: tanMediumStatusOf(fields[1]),
+        securityFunction: version5 ? fields[2] : undefined,
+        cardNumber: fields[cardNumber],
+        cardSequenceNumber: fields[cardNumber + 1],
+        validFrom: parseFintsDate(fields[after]),
+        validUntil: parseFintsDate(fields[after + 1]),
+        name,
+        mobileNumberMasked: fields[after + 4],
+        mobileNumber: fields[after + 5],
+        lastUsed: parseFintsDate(fields[after + 13]),
+        activatedOn: parseFintsDate(fields[after + 14]),
+      }),
+    );
+  }
+  return media;
+}