@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/core/amount.ts

@@ -0,0 +1,211 @@
+import { FormatError } from '../util/errors.js';
+
+/** Most decimal places an amount has: ISO 20022, the widest of the bank formats, allows five. */
+const maxScale = 5;
+
+/** Largest `minorUnits` an amount holds: 2^53 - 1, which JavaScript numbers represent exactly. */
+const maxMinorUnits = Number.MAX_SAFE_INTEGER;
+const powersOfTen = [1, 10, 100, 1000, 10000, 100000];
+
+/** Most digits a parsed amount has: few enough that the sum of two parsed amounts still fits. */
+const maxDigits = 15;
+
+const decimal = /^([+-]?)(\d*)(?:[.,](\d*))?$/;
+
+/** Decimal places of the minor unit of `currency` (ISO 4217): two, except for the currencies listed here. */
+function minorUnitDigits(currency: string): number {
+  switch (currency) {
+    case 'BIF':
+    case 'CLP':
+    case 'DJF':
+    case 'GNF':
+    case 'ISK':
+    case 'JPY':
+    case 'KMF':
+    case 'KRW':
+    case 'PYG':
+    case 'RWF':
+    case 'UGX':
+    case 'UYI':
+    case 'VND':
+    case 'VUV':
+    case 'XAF':
+    case 'XOF':
+    case 'XPF':
+      return 0;
+    case 'BHD':
+    case 'IQD':
+    case 'JOD':
+    case 'KWD':
+    case 'LYD':
+    case 'OMR':
+    case 'TND':
+      return 3;
+    case 'CLF':
+    case 'UYW':
+      return 4;
+    default:
+      return 2;
+  }
+}
+
+/** A money amount stored as an integer number of `scale`-digit minor units. */
+export class Amount {
+  /** The amount in units of 10^-`scale` of the currency, negative for a debit: 1234 with scale 2 is 12.34. */
+  readonly minorUnits: number;
+
+  /** Number of decimal places `minorUnits` has, from 0 to 5. */
+  readonly scale: number;
+
+  /** ISO 4217 currency code, for example `EUR`. */
+  readonly currency: string;
+
+  /**
+   * An amount of `minorUnits` with `scale` decimal places; throws `RangeError` for a `scale` outside 0 to 5, and for
+   * `minorUnits` that are no integer or beyond 2^53 - 1 in either direction, about 90 trillion at two decimal places.
+   */
+  constructor(minorUnits: number, scale: number, currency: string) {
+    if (!Number.isInteger(scale) || scale < 0 || scale > maxScale) {
+      throw new RangeError(`scale must be an integer from 0 to ${maxScale}: ${scale}`);
+    }
+    if (!Number.isSafeInteger(minorUnits)) throw new RangeError(`minorUnits out of range: ${minorUnits}`);
+    // No negative zero, which would format as `-0.00`.
+    this.minorUnits = minorUnits === 0 ? 0 : minorUnits;
+    this.scale = scale;
+    this.currency = currency;
+  }
+
+  /**
+   * Parses a number as banks send it: digits with at most one decimal separator, `,` (FinTS 3.0, MT940) or `.` (camt),
+   * and no thousands separators.
+   *
+   * The amount has the decimal places of the `currency`'s minor unit (ISO 4217): two for most currencies, none for
+   * `JPY`, three for `KWD`. It has more where the value has more significant digits. So `100,` in `EUR` is `100.00`, in
+   * `JPY` `100`.
+   *
+   * Throws `FormatError` for anything else, so that `1.234,56` in bank data is an error, not a guess, and for more than
+   * five decimal places (trailing zeros aside) or more than 15 digits.
+   */
+  static parseDecimal(value: string, currency: string): Amount {
+    const match = decimal.exec(value.trim());
+    const whole = match?.[2] ?? '';
+    let fraction = match?.[3] ?? '';
+    if (!match || (whole === '' && fraction === '')) throw new FormatError('Invalid amount', value);
+    const minorDigits = minorUnitDigits(currency);
+    while (fraction.length > minorDigits && fraction.endsWith('0')) {
+      fraction = fraction.substring(0, fraction.length - 1);
+    }
+    fraction = fraction.padEnd(minorDigits, '0');
+    const digits = `${whole.replace(/^0+/, '')}${fraction}`;
+    if (fraction.length > maxScale || digits.length > maxDigits) {
+      throw new FormatError(`Amount with more than ${maxScale} decimal places or ${maxDigits} digits`, value);
+    }
+    // Nothing is left of a zero without decimal places, such as `0` in `JPY`.
+    const units = digits === '' ? 0 : Number(digits);
+    return new Amount(match[1] === '-' ? -units : units, fraction.length, currency);
+  }
+
+  /** The amount as a floating-point number, which cannot hold every decimal fraction exactly; do not calculate with it. */
+  get value(): number {
+    return this.minorUnits / powersOfTen[this.scale]!;
+  }
+
+  /** Whether the amount is below zero. */
+  get isNegative(): boolean {
+    return this.minorUnits < 0;
+  }
+
+  /** Whether the amount is zero. */
+  get isZero(): boolean {
+    return this.minorUnits === 0;
+  }
+
+  /** This amount with the opposite sign. */
+  negate(): Amount {
+    return new Amount(-this.minorUnits, this.scale, this.currency);
+  }
+
+  /** This amount without its sign. */
+  abs(): Amount {
+    return this.isNegative ? this.negate() : this;
+  }
+
+  /**
+   * The sum with `other`, at the larger of the two scales; throws `TypeError` for another currency and `RangeError` for
+   * a sum beyond what an amount holds.
+   */
+  add(other: Amount): Amount {
+    this.checkCurrency(other);
+    const [mine, theirs] = this.atCommonScale(other);
+    const sum = mine + theirs;
+    const limit = BigInt(maxMinorUnits);
+    if (sum > limit || sum < -limit)
+      throw new RangeError(`The sum of ${this.toString()} and ${other.toString()} is too large for an Amount`);
+    return new Amount(Number(sum), Math.max(this.scale, other.scale), this.currency);
+  }
+
+  /** The difference to `other`; throws `TypeError` for another currency. */
+  subtract(other: Amount): Amount {
+    return this.add(other.negate());
+  }
+
+  /** Compares by value, whatever the scales; throws `TypeError` for another currency. */
+  compareTo(other: Amount): number {
+    this.checkCurrency(other);
+    return this.compareValue(other);
+  }
+
+  /** Whether `other` is the same amount in the same currency, whatever the `scale`: 1.50 equals 1.500. */
+  equals(other: unknown): boolean {
+    return other instanceof Amount && other.currency === this.currency && this.compareValue(other) === 0;
+  }
+
+  /** Formats the amount without currency, for example `-12.50`. */
+  toDecimalString(decimalSeparator = '.'): string {
+    const digits = Math.abs(this.minorUnits)
+      .toString()
+      .padStart(this.scale + 1, '0');
+    const whole = digits.substring(0, digits.length - this.scale);
+    const fraction = digits.substring(digits.length - this.scale);
+    const sign = this.isNegative ? '-' : '';
+    return this.scale === 0 ? `${sign}${whole}` : `${sign}${whole}${decimalSeparator}${fraction}`;
+  }
+
+  toString(): string {
+    return `${this.toDecimalString()} ${this.currency}`;
+  }
+
+  /** The minor units of both amounts at the larger scale, as `bigint`s, since the factor could leave the safe range. */
+  private atCommonScale(other: Amount): [bigint, bigint] {
+    const target = Math.max(this.scale, other.scale);
+    return [this.rescale(target), other.rescale(target)];
+  }
+
+  private rescale(target: number): bigint {
+    return BigInt(this.minorUnits) * BigInt(powersOfTen[target - this.scale]!);
+  }
+
+  private compareValue(other: Amount): number {
+    if (this.scale === other.scale) return Math.sign(this.minorUnits - other.minorUnits);
+    const [mine, theirs] = this.atCommonScale(other);
+    return mine === theirs ? 0 : mine < theirs ? -1 : 1;
+  }
+
+  private checkCurrency(other: Amount): void {
+    if (other.currency !== this.currency)
+      throw new TypeError(`Currency mismatch: ${this.currency} vs ${other.currency}`);
+  }
+}
+
+/**
+ * `amount` as a credit (unchanged) or a debit (negated), by the bank's credit/debit `mark`.
+ *
+ * Throws `FormatError` for any other `mark`, `undefined` included: a missing mark must not be read as a credit. It does
+ * as well for a negative `amount`, whose sign the mark would turn: the mark alone gives the direction.
+ */
+export function withMark(amount: Amount, mark: string | undefined, credit: string, debit: string): Amount {
+  if (amount.isNegative) throw new FormatError('Negative amount with a credit/debit mark', amount.toString());
+  if (mark === credit) return amount;
+  if (mark === debit) return amount.negate();
+  throw new FormatError(`Credit/debit mark is neither "${credit}" nor "${debit}"`, mark);
+}

package/src/core/balance.ts

@@ -0,0 +1,85 @@
+import { copyDate, formatIsoDate } from '../util/dates.js';
+import type { Account } from './account.js';
+import type { Amount } from './amount.js';
+
+/** What `Balance` takes; the bank states the amounts it knows. */
+export interface BalanceInit {
+  account: Account;
+  booked: Amount;
+  bookedAsOf: Date;
+  bookedAsOfTime?: Date | undefined;
+  pending?: Amount | undefined;
+  creditLine?: Amount | undefined;
+  available?: Amount | undefined;
+  used?: Amount | undefined;
+  overdraft?: Amount | undefined;
+  bookingDate?: Date | undefined;
+  bookingTime?: Date | undefined;
+  productName?: string | undefined;
+}
+
+/** Account balance as reported by the bank. */
+export class Balance {
+  /** The account the balance belongs to. */
+  readonly account: Account;
+
+  /** Booked balance; negative when overdrawn. */
+  readonly booked: Amount;
+
+  /**
+   * The calendar day the bank states with the booked balance: the day it transmitted the balance, which need not be the
+   * day the balance was booked (`bookingDate`). A local `Date` at midnight.
+   */
+  readonly bookedAsOf: Date;
+
+  /** The exact moment of `bookedAsOf`, where the bank states the time of day as well; `undefined` otherwise. */
+  readonly bookedAsOfTime: Date | undefined;
+
+  /** Balance of pending (not yet booked) transactions, if the bank reports it. */
+  readonly pending: Amount | undefined;
+
+  /** Arranged overdraft limit. */
+  readonly creditLine: Amount | undefined;
+
+  /** Amount currently available for payments. */
+  readonly available: Amount | undefined;
+
+  /** Amount already drawn on the account's limit. */
+  readonly used: Amount | undefined;
+
+  /** Amount by which the account exceeds its limit. */
+  readonly overdraft: Amount | undefined;
+
+  /** The calendar day the booked balance was booked (Buchungszeitpunkt), where the bank states it. */
+  readonly bookingDate: Date | undefined;
+
+  /** The exact moment of `bookingDate`, where the bank states the time of day as well; `undefined` otherwise. */
+  readonly bookingTime: Date | undefined;
+
+  /** The bank's name for the account, for example `Girokonto`. */
+  readonly productName: string | undefined;
+
+  /** Takes copies of the dates of `init`: each balance has its own, which no other one shares. */
+  constructor(init: BalanceInit) {
+    this.account = init.account;
+    this.booked = init.booked;
+    this.bookedAsOf = copyDate(init.bookedAsOf);
+    this.bookedAsOfTime = copyDate(init.bookedAsOfTime);
+    this.pending = init.pending;
+    this.creditLine = init.creditLine;
+    this.available = init.available;
+    this.used = init.used;
+    this.overdraft = init.overdraft;
+    this.bookingDate = copyDate(init.bookingDate);
+    this.bookingTime = copyDate(init.bookingTime);
+    this.productName = init.productName;
+  }
+
+  /**
+   * The account, as `Account.toString` shows it, and the date; no amount, so that logs and crash reports do not collect
+   * account data.
+   */
+  toString(): string {
+    return `Balance(${this.account.toString()}, ${formatIsoDate(this.bookedAsOf)})`;
+  }
+}

package/src/core/bank-info.ts

@@ -0,0 +1,66 @@
+/** General bank information from the bank parameter data (BPD). */
+export class BankInfo {
+  /** German bank code (BLZ). */
+  readonly bankCode: string;
+
+  /** The bank's name. */
+  readonly name: string | undefined;
+
+  /** Version of the bank parameter data this information comes from. */
+  readonly bpdVersion: number;
+
+  /** FinTS versions the bank supports, as it names them. */
+  readonly supportedVersions: readonly string[];
+
+  /** Languages the bank's messages come in, as codes the bank defines. */
+  readonly languages: readonly string[];
+
+  /** Largest message in kilobytes (1024 bytes) the bank accepts; the client sends nothing larger. */
+  readonly maxMessageSize: number | undefined;
+
+  /**
+   * Time in seconds before which a client must not send a life-indicator message to keep an idle dialog open, `0` for
+   * none (HIBPA, Formals C.9). This client sends no such messages.
+   */
+  readonly minTimeout: number | undefined;
+
+  /**
+   * Time in seconds after which the bank will likely end a dialog without messages, `0` for no limit (HIBPA, Formals
+   * C.9). The client starts a new dialog for a call after that time, or after 5 minutes where the bank states none.
+   */
+  readonly maxTimeout: number | undefined;
+
+  constructor(init: {
+    bankCode: string;
+    name?: string | undefined;
+    bpdVersion: number;
+    supportedVersions?: readonly string[];
+    languages?: readonly string[];
+    maxMessageSize?: number | undefined;
+    minTimeout?: number | undefined;
+    maxTimeout?: number | undefined;
+  }) {
+    this.bankCode = init.bankCode;
+    this.name = init.name;
+    this.bpdVersion = init.bpdVersion;
+    this.supportedVersions = Object.freeze([...(init.supportedVersions ?? [])]);
+    this.languages = Object.freeze([...(init.languages ?? [])]);
+    this.maxMessageSize = init.maxMessageSize;
+    this.minTimeout = init.minTimeout;
+    this.maxTimeout = init.maxTimeout;
+  }
+}
+
+/** Free-text message sent by the bank during login. */
+export class BankMessage {
+  constructor(
+    /** What the message is about. */
+    readonly subject: string,
+    /** The message itself. */
+    readonly text: string,
+  ) {}
+
+  toString(): string {
+    return `${this.subject}: ${this.text}`;
+  }
+}

package/src/core/client.ts

@@ -0,0 +1,186 @@
+import type { TanCallback, TanMediumSelector, TanMethodSelector } from '../tan/challenge.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+import type { Account } from './account.js';
+import type { Balance } from './balance.js';
+import type { BankInfo, BankMessage } from './bank-info.js';
+import type { FinTsLoginRefusedError } from './errors.js';
+import type { FinTsFeedback } from './feedback.js';
+import type { Transaction, TransactionFormat } from './transaction.js';
+import type { FinTsTransport } from './transport.js';
+
+/** Which way a FinTS message travels: from the client to the bank, or back. */
+export type MessageDirection = 'outgoing' | 'incoming';
+
+/** Receives every FinTS message with PIN and TAN masked. */
+export type MessageLogger = (direction: MessageDirection, message: string) => void;
+
+/** Receives free-text messages the bank sends during login. */
+export type BankMessageHandler = (message: BankMessage) => void;
+
+/** Receives a warning the bank sends, a return code from 3000 to 3999. */
+export type WarningHandler = (warning: FinTsFeedback) => void;
+
+/**
+ * How a client reaches the user and the bank, apart from the login data in `FinTsConfig`.
+ *
+ * An error thrown by a callback that only informs the app (`onBankMessage`, `onWarning`, `logger`) fails the call once
+ * the call's exchange with the bank is over, so that it cannot break off a dialog half-way; an error of the call itself
+ * takes precedence.
+ */
+export interface FinTsClientOptions {
+  /** Called whenever the bank asks for a TAN or an app approval. */
+  tanCallback: TanCallback;
+
+  /** Picks the TAN method when the bank offers several; the first is used without it. */
+  tanMethodSelector?: TanMethodSelector;
+
+  /** Picks the TAN medium when the method needs one and the user has several; the first is used without it. */
+  tanMediumSelector?: TanMediumSelector;
+
+  /** Receives the free-text messages the bank sends during login. */
+  onBankMessage?: BankMessageHandler;
+
+  /**
+   * Receives the bank's warnings, such as 3951 (switch to another TAN method), but not those the client acts on itself,
+   * such as 3040 (more data follow). Show them to the user with code and text, as the specification asks.
+   */
+  onWarning?: WarningHandler;
+
+  /** Receives every FinTS message with PIN and TAN masked, for diagnosis; the messages contain account data. */
+  logger?: MessageLogger;
+
+  /**
+   * The `FinTsClient.state` of a previous session, which skips the bank setup steps. A refused login in it keeps the
+   * client from sending the PIN (`FinTsClient.loginRefusal`).
+   *
+   * A state belongs to one client at a time: restore the clients of one bank user one after another, each from the
+   * state the one before saved, never two at once from the same state. The state saved last wins, and could lift a
+   * refused login the other client saved.
+   *
+   * A state saved for another user or bank is ignored, and of one saved for another server of the bank, such as before
+   * the bank moved its FinTS URL, only the refused login holds.
+   */
+  state?: string | undefined;
+
+  /**
+   * Sends the messages; an `HttpTransport` by default.
+   *
+   * The client closes it on `FinTsClient.close`, so hand each client a transport of its own.
+   */
+  transport?: FinTsTransport;
+}
+
+/** What `getTransactions` takes besides the account. */
+export interface TransactionQuery {
+  /** The first day, a day in the future counting as today; banks typically ask for a TAN beyond 90 days ago. */
+  from?: Date | undefined;
+  /** The last day, a day in the future counting as today. */
+  to?: Date | undefined;
+  /** The format to ask for; `auto` by default. */
+  format?: TransactionFormat;
+}
+
+/**
+ * Read access to a bank account over FinTS.
+ *
+ * A call logs in where it needs to, which sends the PIN and may ask the callbacks for a TAN method, a TAN medium and an
+ * approval. Calls share one bank dialog while it is open, so that the approval of its login serves them all. The next
+ * call logs in anew, which may ask for another approval, once the dialog has idled longer than `BankInfo.maxTimeout`,
+ * after `selectTanMethod` and `clearLoginRefusal`, once the bank has ended the dialog, and after a message failed with
+ * another error than the bank's (`FinTsBankError`), such as a cancelled approval or a broken connection. Calls run one
+ * after another; call `close` when done.
+ *
+ * A callback in `FinTsClientOptions` must not wait for another call of its client, which would wait for the running
+ * call. On Node.js, Deno 2.1 and Bun 1.2.6 or later such a call fails with `FinTsStateError`; elsewhere it waits
+ * forever. `close` works from anywhere.
+ */
+export interface FinTsClient {
+  /**
+   * Serialized session data: bank and user parameters, customer system ID, the TAN methods the user may use, the chosen
+   * TAN method and medium, the SEPA account list, and a refused login (`loginRefusal`).
+   *
+   * Contains no PIN or TAN, but account details, so store it encrypted. It holds what this client knows, and replaces
+   * the state it was restored from: one client at a time per state (`FinTsClientOptions.state`).
+   */
+  readonly state: string;
+
+  /**
+   * The refused login that keeps the client from sending the PIN again (`FinTsLoginRefusedError`); `undefined` while
+   * there is none. It is kept in `state` until `clearLoginRefusal`.
+   */
+  readonly loginRefusal: FinTsLoginRefusedError | undefined;
+
+  /** Security function code of the TAN method in use, for example `942`; `undefined` before the first login. */
+  readonly selectedTanMethod: string | undefined;
+
+  /** Name of the TAN medium sent to the bank, if the method needs one. */
+  readonly selectedTanMedium: string | undefined;
+
+  /**
+   * Switches to another TAN method, and optionally TAN medium, for the following calls.
+   *
+   * Ends the current dialog, so the next call logs in again with the new method. If the bank does not offer
+   * `securityFunction`, the client picks another method at that login.
+   */
+  selectTanMethod(securityFunction: string, tanMedium?: string): Promise<void>;
+
+  /**
+   * Lifts `loginRefusal` and signs with `pin` from now on. Ends the current dialog, so that the next call logs in with
+   * it, and forgets the TAN medium, which the bank may have refused, such as that of a phone the user has replaced: where
+   * the TAN method needs one, the next call looks the media up anew and asks the `tanMediumSelector`.
+   *
+   * Pass a PIN the user has entered after the refusal, never a stored one unasked: banks lock the access after a few
+   * failed logins. Rejects with `TypeError` for a PIN the client cannot send, as its constructor throws, and with the
+   * refusal where it is a `FinTsLoginDataChangedError`: only a new client with the new login data can log in.
+   */
+  clearLoginRefusal(pin: string): Promise<void>;
+
+  /** General information about the bank, from the bank parameter data. */
+  getBankInfo(): Promise<BankInfo>;
+
+  /**
+   * TAN procedures the bank allows for this user, which the synchronization reports. Where the session has no customer
+   * system ID yet, as without a saved state, this call logs in for it: it may ask `tanMethodSelector` where the bank
+   * refuses the one-step method, and `tanCallback` for an approval.
+   */
+  getTanMethods(): Promise<TanMethod[]>;
+
+  /** TAN devices registered for this user. */
+  getTanMedia(): Promise<TanMedium[]>;
+
+  /** Accounts of the user, completed with IBAN and BIC where the bank provides them. */
+  getAccounts(): Promise<Account[]>;
+
+  /**
+   * The balance of `account`.
+   *
+   * Where the user parameter data carry the complete balance (account extension), possibly from the saved `state`, it
+   * comes from there without a query; `Balance.bookedAsOf` tells the day it states.
+   *
+   * Rejects with `FinTsUnsupportedError` where the parameter data rule the query out, without sending it; the login,
+   * which delivers them, may have gone out.
+   */
+  getBalance(account: Account): Promise<Balance>;
+
+  /**
+   * Transactions from the day of `from` to the day of `to`, both included, booked and pending, sorted by date; those of
+   * the same day in the bank's order.
+   *
+   * Only the local calendar day counts, and a day in the future counts as today. Banks typically ask for a TAN when
+   * `from` is more than 90 days ago; see also `Account.dataStatus`. Rejects with `TypeError`, before it waits for other
+   * calls, if `from` or `to` is no valid `Date` or `from` lies on a day after `to`, and with `FinTsUnsupportedError`,
+   * without sending the query, where the parameter data rule it out; the login may have gone out.
+   */
+  getTransactions(account: Account, query?: TransactionQuery): Promise<Transaction[]>;
+
+  /**
+   * Ends the bank dialog, releases the connection and forgets the PIN.
+   *
+   * A running call stops at its next step, also while it waits for a TAN, an app approval or a selection, and fails with
+   * `FinTsStateError`, as do all later calls. A request already on its way is aborted where the transport supports it,
+   * as `HttpTransport` does: the call fails with `FinTsTransportError` then, as after a broken connection, and an aborted
+   * login counts as one whose answer was lost. Another transport is awaited, at most for its timeout; after the
+   * request, the call sends nothing but the end of its dialogs.
+   */
+  close(): Promise<void>;
+}