@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/core/account.ts

@@ -0,0 +1,250 @@
+import { ImmutableMap } from '../util/immutable-map.js';
+import { maskedId } from '../util/text.js';
+import { defaultCountryCode } from './config.js';
+
+/** Account kind derived from the FinTS account type code. */
+export type AccountCategory =
+  /** Current account (type codes 1 to 9). */
+  | 'checking'
+  /** Savings account (10 to 19). */
+  | 'savings'
+  /** Fixed-term deposit (20 to 29). */
+  | 'fixedDeposit'
+  /** Securities account (30 to 39). */
+  | 'securities'
+  /** Loan account (40 to 49). */
+  | 'loan'
+  /** Credit card account (50 to 59). */
+  | 'creditCard'
+  /** Fund deposit (60 to 69). */
+  | 'fund'
+  /** Home savings contract (70 to 79). */
+  | 'homeSavings'
+  /** Insurance (80 to 89). */
+  | 'insurance'
+  /** Any other type code. */
+  | 'other'
+  /** The bank states no type code. */
+  | 'unknown';
+
+const categoriesByTens: readonly AccountCategory[] = [
+  'checking',
+  'savings',
+  'fixedDeposit',
+  'securities',
+  'loan',
+  'creditCard',
+  'fund',
+  'homeSavings',
+  'insurance',
+];
+
+/** The category of the FinTS account type `code`, which is `undefined` if the bank states none. */
+export function accountCategoryOf(code: number | undefined): AccountCategory {
+  if (code === undefined || code < 1) return 'unknown';
+  return categoriesByTens[Math.floor(code / 10)] ?? 'other';
+}
+
+/** What `Account` takes; the bank states the details it knows. */
+export interface AccountInit {
+  accountNumber?: string | undefined;
+  subAccount?: string | undefined;
+  bankCode: string;
+  countryCode?: string | undefined;
+  iban?: string | undefined;
+  bic?: string | undefined;
+  customerId?: string | undefined;
+  currency?: string | undefined;
+  ownerName?: string | undefined;
+  productName?: string | undefined;
+  typeCode?: number | undefined;
+  allowedTransactions?: readonly string[] | undefined;
+  allowedTransactionsComplete?: boolean | undefined;
+  dataStatus?: AccountDataStatus | undefined;
+}
+
+/** A bank account as reported by the user parameter data or the SEPA account query. */
+export class Account {
+  /** National account number. */
+  readonly accountNumber: string | undefined;
+
+  /** Sub-account characteristic (Unterkontomerkmal). */
+  readonly subAccount: string | undefined;
+
+  /** German bank code (BLZ) of the bank holding the account. */
+  readonly bankCode: string;
+
+  /** Numeric country code of the bank, `280` for Germany. */
+  readonly countryCode: string;
+
+  /** International bank account number. */
+  readonly iban: string | undefined;
+
+  /** Bank identifier code of the bank holding the account. */
+  readonly bic: string | undefined;
+
+  /** Customer ID the account is assigned to; may differ from the login name. */
+  readonly customerId: string | undefined;
+
+  /** Currency of the account, for example `EUR`. */
+  readonly currency: string | undefined;
+
+  /** Name of the account holder. */
+  readonly ownerName: string | undefined;
+
+  /** The bank's name for the account, for example `Girokonto`. */
+  readonly productName: string | undefined;
+
+  /** Raw FinTS account type (1–99); see `category`. */
+  readonly typeCode: number | undefined;
+
+  /**
+   * The transactions the bank lists as permitted for this account, by their segment IDs, such as `HKSAL`.
+   *
+   * The client applies them itself: `getBalance` and `getTransactions` throw `FinTsUnsupportedError`, without asking
+   * the bank, where the parameter data rule the query out.
+   */
+  readonly allowedTransactions: readonly string[];
+
+  /**
+   * Whether `allowedTransactions` is complete: the bank permits nothing it does not list (FinTS "UPD-Verwendung" 0).
+   * Otherwise the bank's lists say nothing about a transaction they leave out, and only the bank can tell.
+   */
+  readonly allowedTransactionsComplete: boolean;
+
+  /** What the bank tells about the data it holds for the account, where it does. */
+  readonly dataStatus: AccountDataStatus | undefined;
+
+  constructor(init: AccountInit) {
+    this.accountNumber = init.accountNumber;
+    this.subAccount = init.subAccount;
+    this.bankCode = init.bankCode;
+    this.countryCode = init.countryCode ?? defaultCountryCode;
+    this.iban = init.iban;
+    this.bic = init.bic;
+    this.customerId = init.customerId;
+    this.currency = init.currency;
+    this.ownerName = init.ownerName;
+    this.productName = init.productName;
+    this.typeCode = init.typeCode;
+    this.allowedTransactions = Object.freeze([...(init.allowedTransactions ?? [])]);
+    this.allowedTransactionsComplete = init.allowedTransactionsComplete ?? false;
+    this.dataStatus = init.dataStatus;
+  }
+
+  /** The kind of account, derived from `typeCode`. */
+  get category(): AccountCategory {
+    return accountCategoryOf(this.typeCode);
+  }
+
+  /**
+   * Whether `other` is the same account: by IBAN when both have one, otherwise by account number, sub-account and
+   * bank.
+   *
+   * Account numbers are compared without leading zeros, since banks pad them differently. An empty bank or country
+   * code, as of a balance record without bank identification, matches any.
+   */
+  matches(other: Account): boolean {
+    if (this.iban !== undefined && other.iban !== undefined) return this.iban === other.iban;
+    const number = this.accountNumber?.replace(/^0+/, '');
+    return (
+      number !== undefined &&
+      number === other.accountNumber?.replace(/^0+/, '') &&
+      (this.subAccount ?? '') === (other.subAccount ?? '') &&
+      sameOrUnstated(this.bankCode, other.bankCode) &&
+      sameOrUnstated(this.countryCode, other.countryCode)
+    );
+  }
+
+  /** This account with the given details replaced; a detail that is `undefined` stays as it is. */
+  copyWith(changes: Omit<Partial<AccountInit>, 'bankCode' | 'countryCode'>): Account {
+    return new Account({
+      accountNumber: changes.accountNumber ?? this.accountNumber,
+      subAccount: changes.subAccount ?? this.subAccount,
+      bankCode: this.bankCode,
+      countryCode: this.countryCode,
+      iban: changes.iban ?? this.iban,
+      bic: changes.bic ?? this.bic,
+      customerId: changes.customerId ?? this.customerId,
+      currency: changes.currency ?? this.currency,
+      ownerName: changes.ownerName ?? this.ownerName,
+      productName: changes.productName ?? this.productName,
+      typeCode: changes.typeCode ?? this.typeCode,
+      allowedTransactions: changes.allowedTransactions ?? this.allowedTransactions,
+      allowedTransactionsComplete: changes.allowedTransactionsComplete ?? this.allowedTransactionsComplete,
+      dataStatus: changes.dataStatus ?? this.dataStatus,
+    });
+  }
+
+  /**
+   * The product name and the last digits of the IBAN or account number only, so that logs and crash reports do not
+   * collect account data.
+   */
+  toString(): string {
+    const id = this.iban ?? this.accountNumber;
+    const parts = [
+      ...(id === undefined ? [] : [maskedId(id)]),
+      ...(this.productName === undefined ? [] : [this.productName]),
+    ];
+    return `Account(${parts.join(', ')})`;
+  }
+}
+
+function sameOrUnstated(a: string, b: string): boolean {
+  return a === '' || b === '' || a === b;
+}
+
+/**
+ * What the bank tells about the data it holds for an account, so that an app asks only for what has changed (FinTS 3.0
+ * user parameter data, "Erweiterung, kontobezogen", Formals E.3.1 and F).
+ *
+ * The rules are binding for an app that stores transactions; banks may refuse an app that ignores them:
+ * - Do not fetch the transactions again while the bank names the ID they were stored with (`mt940TransactionsId` or
+ *   `camtTransactionsId`, for the format the app asked for, so pass `format` to `getTransactions` explicitly), or, in
+ *   the older format, the timestamp `lastTransactions`.
+ * - Do not fetch them before `nextTransactionsAt`.
+ * - Do not ask for the balance separately where `transactionBalancesCurrent` says that the transactions carry the
+ *   current one.
+ */
+export class AccountDataStatus {
+  /**
+   * IDs of the data the bank holds for the user, keyed by the segment ID of the query that fetches them, for example
+   * `HKKAZ` (transactions as MT940) or `HKCAZ` (as camt): the data have changed when the ID changes. An empty ID means
+   * that the user has no such data; a query the map leaves out, that the bank tells nothing about it.
+   */
+  readonly inventory: ReadonlyMap<string, string>;
+
+  /**
+   * The timestamp of the last transactions the bank provided, in the older format of the extension (`umsltzt`);
+   * compared like an ID in `inventory`.
+   */
+  readonly lastTransactions: string | undefined;
+
+  /** The moment before which the bank provides no new transactions. */
+  readonly nextTransactionsAt: Date | undefined;
+
+  /** Whether the balances the transactions carry are the current ones. */
+  readonly transactionBalancesCurrent: boolean;
+
+  constructor(init: {
+    inventory?: ReadonlyMap<string, string>;
+    lastTransactions?: string | undefined;
+    nextTransactionsAt?: Date | undefined;
+    transactionBalancesCurrent?: boolean;
+  }) {
+    this.inventory = new ImmutableMap(init.inventory ?? []);
+    this.lastTransactions = init.lastTransactions;
+    this.nextTransactionsAt = init.nextTransactionsAt;
+    this.transactionBalancesCurrent = init.transactionBalancesCurrent ?? false;
+  }
+
+  /** The ID of the transactions the bank holds as MT940, its entry for `HKKAZ` in `inventory`. */
+  get mt940TransactionsId(): string | undefined {
+    return this.inventory.get('HKKAZ');
+  }
+
+  /** The ID of the transactions the bank holds as camt, its entry for `HKCAZ` in `inventory`. */
+  get camtTransactionsId(): string | undefined {
+    return this.inventory.get('HKCAZ');
+  }
+}

package/src/core/amount.ts

@@ -0,0 +1,209 @@
+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.
+ */
+export function withMark(amount: Amount, mark: string | undefined, credit: string, debit: string): Amount {
+  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,84 @@
+import { 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;
+
+  constructor(init: BalanceInit) {
+    this.account = init.account;
+    this.booked = init.booked;
+    this.bookedAsOf = init.bookedAsOf;
+    this.bookedAsOfTime = init.bookedAsOfTime;
+    this.pending = init.pending;
+    this.creditLine = init.creditLine;
+    this.available = init.available;
+    this.used = init.used;
+    this.overdraft = init.overdraft;
+    this.bookingDate = init.bookingDate;
+    this.bookingTime = 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.
+   */
+  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}`;
+  }
+}