@coderoftime/fints 0.1.0 → 0.3.0

package/src/client.ts

@@ -0,0 +1,293 @@
+import { Account } from './core/account.js';
+import type { Balance } from './core/balance.js';
+import type { BankInfo } from './core/bank-info.js';
+import type { FinTsClient, FinTsClientOptions, TransactionQuery } from './core/client.js';
+import { FinTsConfig, requirePin, type FinTsConfigInit } from './core/config.js';
+import { FinTsStateError, FinTsUnsupportedError, type FinTsLoginRefusedError } from './core/errors.js';
+import type { Transaction, TransactionFormat } from './core/transaction.js';
+import type { FinTsTransport } from './core/transport.js';
+import { DialogRunner } from './session/dialog-runner.js';
+import { LoginGuard } from './session/login-guard.js';
+import { SepaAccounts } from './session/sepa-accounts.js';
+import { SessionSetup } from './session/session-setup.js';
+import { restoreSession, saveSession, type SessionState } from './session/session-state.js';
+import { TanSelection } from './session/tan-selection.js';
+import { UserPrompts } from './session/user-prompts.js';
+import { TanMedium, type TanMethod } from './tan/tan-models.js';
+import { optionalString, requireString } from './util/arguments.js';
+import { SerialExecutor } from './util/async.js';
+import { CallContext } from './util/call-context.js';
+import { calendarDay, notAfterToday } from './util/dates.js';
+import { invalidArgument } from './util/errors.js';
+import { ParameterStore } from './v3/parameter-store.js';
+import { FinTs3Protocol } from './v3/protocol.js';
+import { balanceQuery, tanMediaQuery, transactionsQuery } from './v3/queries.js';
+
+/** What `FinTs3Client` takes. */
+export interface FinTs3ClientInit {
+  /** Where and as whom to log in: a `FinTsConfig`, or what its constructor takes. */
+  config: FinTsConfig | FinTsConfigInit;
+  /**
+   * The user's PIN. The client keeps it in memory only, never logs it, and forgets it once it is closed or the bank has
+   * refused the login. It is out of reach of `JSON.stringify` and Node.js's `util.inspect` of the client, but not of a
+   * debugger or the browser's DevTools: never log the client. A client whose `options.state` holds a refused login
+   * does not send it (`FinTsClient.loginRefusal`).
+   */
+  pin: string;
+  /** How the client reaches the user and the bank. */
+  options: FinTsClientOptions;
+}
+
+/** A token of the client call running now, so that a call from inside its callbacks is recognized. */
+const runningCalls = new CallContext<object>();
+
+/**
+ * `transport`, `undefined` for `null`; throws `TypeError` unless it is neither or has the functions of a
+ * `FinTsTransport`.
+ */
+function optionalTransport(transport: unknown): FinTsTransport | undefined {
+  if (transport === undefined || transport === null) return undefined;
+  const candidate = transport as Partial<FinTsTransport>;
+  if (typeof candidate.post !== 'function' || typeof candidate.close !== 'function') {
+    throw invalidArgument('Must have the functions post and close', 'transport');
+  }
+  return transport as FinTsTransport;
+}
+
+/** Throws `TypeError` for anything but an `Account`, such as one written to JSON and read back. */
+function requireAccount(account: unknown): void {
+  if (!(account instanceof Account)) throw invalidArgument('Must be an Account', 'account');
+}
+
+/**
+ * The calendar day of `bound`, the `name` bound of a `TransactionQuery`: the bank takes dates without time of day.
+ * Throws `TypeError` for anything but a valid `Date`, such as an Invalid Date, which would go out as `0NaNNaNNaN`.
+ */
+function requestedDay(bound: unknown, name: string): Date | undefined {
+  if (bound === undefined) return undefined;
+  if (!(bound instanceof Date) || Number.isNaN(bound.getTime())) throw invalidArgument('Not a valid Date', name);
+  return calendarDay(bound);
+}
+
+/**
+ * The format a `TransactionQuery` asks for with `format`: `auto` where it is `undefined`. Throws `TypeError` for anything
+ * but a `TransactionFormat`, such as `'CAMT'` or `null`.
+ */
+function requestedFormat(format: unknown): TransactionFormat {
+  if (format === undefined) return 'auto';
+  if (format === 'auto' || format === 'mt940' || format === 'camt') return format;
+  throw invalidArgument("Must be 'auto', 'mt940' or 'camt'", 'format');
+}
+
+/** FinTS 3.0 PIN/TAN client, the version German banks use. */
+export class FinTs3Client implements FinTsClient {
+  // A call such as `getBalance` runs through these parts:
+  // 1. `DialogRunner.open` reuses the session's dialog or logs in, through `SessionSetup.remedied`, which logs in once
+  //    more for each refusal it can take care of.
+  // 2. `SessionSetup.prepare` first settles what is open: the bank parameter data, the synchronization, and through
+  //    `TanSelection` the TAN method and medium.
+  // 3. `SignedDialog.login` sends the login and completes the strong authentication the bank asks for, a TAN or an app
+  //    approval (`AppApprovalWait`).
+  // 4. `DialogRunner.query` sends the order in that dialog, completes its approval the same way, and fetches all pages.
+  //
+  // `FinTs3Protocol` builds, signs and posts the messages of each `FinTs3Dialog`, the queries build the orders and read
+  // the answers, and the `ParameterStore` keeps the bank's parameter data and IDs. `SepaAccounts` completes IBAN and
+  // BIC, and `UserPrompts` is everything the app is told or asked. The `LoginGuard` holds the PIN: the protocol takes it
+  // from the guard for every message it signs, and `SignedDialog` has the guard judge every answer, so that the PIN does
+  // not go out after a refusal.
+  //
+  // The fields are ECMAScript private, so that neither `util.inspect` nor `JSON.stringify` of a client reaches the PIN
+  // or the account data behind them.
+
+  readonly #prompts: UserPrompts;
+  readonly #guard: LoginGuard;
+  readonly #parameters: ParameterStore;
+  readonly #protocol: FinTs3Protocol;
+  readonly #sessionState: SessionState;
+  readonly #tans: TanSelection;
+  readonly #setup: SessionSetup;
+  readonly #dialogs: DialogRunner;
+  readonly #sepa: SepaAccounts;
+  readonly #queue = new SerialExecutor();
+  #closed: Promise<void> | undefined;
+
+  /** The call running now, which a call from inside its callbacks would wait for. */
+  #runningCall: object | undefined;
+
+  /**
+   * A client with the session restored from `FinTsClientOptions.state` where it was saved for this user and bank.
+   *
+   * Throws `TypeError` if the configuration is invalid, as the constructor of `FinTsConfig` tells, or the PIN is empty,
+   * begins or ends with a blank, or has characters FinTS 3.0 cannot send: it uses ISO 8859-1, so `€` and most
+   * non-Latin letters are not possible. Throws `TypeError` as well for an option of another type than
+   * `FinTsClientOptions` names, as `FinTsClientOptions` tells.
+   */
+  constructor(init: FinTs3ClientInit) {
+    const config = init.config instanceof FinTsConfig ? init.config : new FinTsConfig(init.config);
+    const { state, transport } = init.options;
+    this.#prompts = new UserPrompts(init.options);
+    this.#guard = new LoginGuard(requirePin(init.pin));
+    this.#parameters = new ParameterStore(config);
+    this.#protocol = new FinTs3Protocol(
+      this.#parameters,
+      this.#guard,
+      optionalTransport(transport),
+      this.#prompts.logger,
+    );
+    this.#sessionState = restoreSession(optionalString(state, 'state'), this.#parameters, this.#guard);
+    this.#tans = new TanSelection(this.#protocol, this.#sessionState, this.#prompts);
+    const session = {
+      parameters: this.#parameters,
+      state: this.#sessionState,
+      prompts: this.#prompts,
+      guard: this.#guard,
+    };
+    this.#setup = new SessionSetup(session, this.#protocol, this.#tans);
+    this.#dialogs = new DialogRunner(this.#setup);
+    this.#sepa = new SepaAccounts(this.#parameters, this.#sessionState, this.#dialogs);
+  }
+
+  get state(): string {
+    return saveSession(this.#parameters, this.#guard, this.#sessionState);
+  }
+
+  get loginRefusal(): FinTsLoginRefusedError | undefined {
+    return this.#guard.refusal;
+  }
+
+  get selectedTanMethod(): string | undefined {
+    return this.#sessionState.tanMethod;
+  }
+
+  get selectedTanMedium(): string | undefined {
+    return this.#sessionState.tanMedium;
+  }
+
+  async selectTanMethod(securityFunction: string, tanMedium?: string): Promise<void> {
+    // Checked before the dialog ends; an async method, so that every argument error is a rejection.
+    const method = requireString(securityFunction, 'securityFunction');
+    const medium = optionalString(tanMedium, 'tanMedium');
+    return this.#serialized(async () => {
+      await this.#dialogs.end();
+      this.#tans.select(method, medium);
+    });
+  }
+
+  clearLoginRefusal(pin: string): Promise<void> {
+    return this.#serialized(async () => {
+      const sendable = requirePin(pin);
+      // The dialog ends with the PIN it was opened with.
+      await this.#dialogs.end();
+      this.#guard.replacePin(sendable);
+      this.#tans.forgetMedium();
+    });
+  }
+
+  getBankInfo(): Promise<BankInfo> {
+    return this.#serialized(() => this.#setup.remedied(() => this.#setup.bankInfo()));
+  }
+
+  getTanMethods(): Promise<TanMethod[]> {
+    return this.#serialized(() => this.#setup.remedied(() => this.#setup.methods()));
+  }
+
+  getTanMedia(): Promise<TanMedium[]> {
+    return this.#serialized(async () => {
+      // The session keeps the list of a lookup that found no medium; the app gets media of its own.
+      const lookedUp = (await this.#setup.remedied(() => this.#setup.prepare())) ?? this.#tans.lookedUpMedia;
+      return (
+        lookedUp?.map((m) => new TanMedium(m)) ??
+        (await this.#dialogs.query(() => {
+          const query = tanMediaQuery(this.#parameters);
+          if (query === undefined) throw new FinTsUnsupportedError('The bank does not list TAN media');
+          return query;
+        }))
+      );
+    });
+  }
+
+  getAccounts(): Promise<Account[]> {
+    return this.#serialized(() => this.#sepa.completedAccounts());
+  }
+
+  async getBalance(account: Account): Promise<Balance> {
+    // Checked before the call waits for others; an async method, so that every argument error is a rejection.
+    requireAccount(account);
+    return this.#serialized(async () => {
+      const completed = await this.#sepa.complete(account);
+      // The dialog start delivers the user parameter data, which may carry the complete balance: then the client must
+      // not ask for it separately (Formals E.3.1.1, F.3.2).
+      await this.#dialogs.open();
+      return (
+        this.#parameters.userParameters?.completeBalance(completed) ??
+        (await this.#dialogs.query(() => balanceQuery(this.#parameters, completed)))
+      );
+    });
+  }
+
+  async getTransactions(account: Account, query: TransactionQuery = {}): Promise<Transaction[]> {
+    // Checked before the call waits for others; an async method, so that every argument error is a rejection.
+    requireAccount(account);
+    const firstDay = requestedDay(query.from, 'from');
+    const lastDay = requestedDay(query.to, 'to');
+    if (firstDay !== undefined && lastDay !== undefined && firstDay.getTime() > lastDay.getTime()) {
+      throw invalidArgument('`from` lies on a day after `to`', 'from');
+    }
+    const format = requestedFormat(query.format);
+    return this.#serialized(async () => {
+      const completed = await this.#sepa.complete(account);
+      const transactions = await this.#dialogs.query(() =>
+        transactionsQuery(this.#parameters, completed, format, notAfterToday(firstDay), notAfterToday(lastDay)),
+      );
+      // A stable sort, so that transactions of the same day keep the bank's order.
+      return transactions.sort(
+        (a, b) => (a.bookingDate ?? a.valueDate).getTime() - (b.bookingDate ?? b.valueDate).getTime(),
+      );
+    });
+  }
+
+  close(): Promise<void> {
+    this.#closed ??= this.#closeNow();
+    return this.#closed;
+  }
+
+  #closeNow(): Promise<void> {
+    this.#prompts.close();
+    this.#protocol.beginClose();
+    return this.#queue.run(() =>
+      this.#prompts.reportingCallbackErrors(async () => {
+        try {
+          await this.#dialogs.end();
+        } finally {
+          this.#guard.close();
+          this.#protocol.close();
+        }
+      }),
+    );
+  }
+
+  #serialized<T>(action: () => Promise<T>): Promise<T> {
+    const caller = runningCalls.current;
+    if (caller !== undefined && caller === this.#runningCall) {
+      // The call would wait behind the running one, which waits for the callback: neither would ever end.
+      return Promise.reject(new FinTsStateError('The FinTS client was called from inside one of its callbacks'));
+    }
+    return this.#queue.run(async () => {
+      const call = {};
+      this.#runningCall = call;
+      try {
+        return await runningCalls.run(call, () =>
+          this.#guard.runCall(async () => {
+            this.#prompts.checkOpen();
+            const result = await this.#prompts.reportingCallbackErrors(action);
+            // Also where the last answer arrived after `close`: a closed client hands out no account data.
+            this.#prompts.checkOpen();
+            return result;
+          }),
+        );
+      } finally {
+        this.#runningCall = undefined;
+      }
+    });
+  }
+}

package/src/core/account.ts

@@ -1,5 +1,10 @@
+import { optionalBoolean, optionalInteger, optionalString, requireString } from '../util/arguments.js';
+import { copyDate } from '../util/dates.js';
+import { invalidArgument } from '../util/errors.js';
 import { ImmutableMap } from '../util/immutable-map.js';
-import { maskedId } from '../util/text.js';
+import { inspectCustom } from '../util/inspect.js';
+import { isString } from '../util/json.js';
+import { maskedId, nonBlank } from '../util/text.js';
 import { defaultCountryCode } from './config.js';
 
 /** Account kind derived from the FinTS account type code. */
@@ -40,7 +45,7 @@ const categoriesByTens: readonly AccountCategory[] = [
 ];
 
 /** The category of the FinTS account type `code`, which is `undefined` if the bank states none. */
-export function accountCategoryOf(code: number | undefined): AccountCategory {
+function accountCategoryOf(code: number | undefined): AccountCategory {
   if (code === undefined || code < 1) return 'unknown';
   return categoriesByTens[Math.floor(code / 10)] ?? 'other';
 }
@@ -63,7 +68,15 @@ export interface AccountInit {
   dataStatus?: AccountDataStatus | undefined;
 }
 
-/** A bank account as reported by the user parameter data or the SEPA account query. */
+/**
+ * A bank account as reported by the user parameter data or the SEPA account query.
+ *
+ * An account the app builds itself, such as from a stored IBAN, stands for the one of `getAccounts` it `matches`:
+ * queries take the details the bank states of that one, and the transactions the bank permits for it. One the bank
+ * names nowhere goes out with its account number, sub-account, IBAN, BIC, bank and country code and currency only, and
+ * is refused with `FinTsUnsupportedError` where the bank's lists of permitted transactions are complete. Queries never
+ * take the permitted transactions from the app's account.
+ */
 export class Account {
   /** National account number. */
   readonly accountNumber: string | undefined;
@@ -77,10 +90,13 @@ export class Account {
   /** Numeric country code of the bank, `280` for Germany. */
   readonly countryCode: string;
 
-  /** International bank account number. */
+  /**
+   * International bank account number, in its electronic format: without blanks and in capitals, however
+   * `AccountInit.iban` wrote it, such as in groups of four as printed.
+   */
   readonly iban: string | undefined;
 
-  /** Bank identifier code of the bank holding the account. */
+  /** Bank identifier code of the bank holding the account, without blanks and in capitals. */
   readonly bic: string | undefined;
 
   /** Customer ID the account is assigned to; may differ from the login name. */
@@ -101,8 +117,8 @@ export class Account {
   /**
    * 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.
+   * The client applies them itself: `getBalance` and `getTransactions` do not send a query they rule out, and fail with
+   * `FinTsUnsupportedError`.
    */
   readonly allowedTransactions: readonly string[];
 
@@ -115,21 +131,28 @@ export class Account {
   /** What the bank tells about the data it holds for the account, where it does. */
   readonly dataStatus: AccountDataStatus | undefined;
 
+  /**
+   * Takes copies of the permitted transactions and the data status of `init`, which no other account shares.
+   *
+   * Throws `TypeError` for a detail of another type than `AccountInit` names, such as a number as `bankCode` or
+   * `accountNumber`, or a missing `bankCode`; `null` counts as a detail not given. The message leaves out the value.
+   */
   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;
+    this.accountNumber = optionalString(init.accountNumber, 'accountNumber');
+    this.subAccount = optionalString(init.subAccount, 'subAccount');
+    this.bankCode = requireString(init.bankCode, 'bankCode');
+    this.countryCode = optionalString(init.countryCode, 'countryCode') ?? defaultCountryCode;
+    this.iban = electronicFormat(optionalString(init.iban, 'iban'));
+    this.bic = electronicFormat(optionalString(init.bic, 'bic'));
+    this.customerId = optionalString(init.customerId, 'customerId');
+    this.currency = optionalString(init.currency, 'currency');
+    this.ownerName = optionalString(init.ownerName, 'ownerName');
+    this.productName = optionalString(init.productName, 'productName');
+    this.typeCode = optionalInteger(init.typeCode, 'typeCode');
+    this.allowedTransactions = Object.freeze(segmentIds(init.allowedTransactions));
+    this.allowedTransactionsComplete =
+      optionalBoolean(init.allowedTransactionsComplete, 'allowedTransactionsComplete') ?? false;
+    this.dataStatus = copiedDataStatus(init.dataStatus);
   }
 
   /** The kind of account, derived from `typeCode`. */
@@ -146,10 +169,10 @@ export class Account {
    */
   matches(other: Account): boolean {
     if (this.iban !== undefined && other.iban !== undefined) return this.iban === other.iban;
-    const number = this.accountNumber?.replace(/^0+/, '');
+    const number = nationalNumber(this);
     return (
       number !== undefined &&
-      number === other.accountNumber?.replace(/^0+/, '') &&
+      number === nationalNumber(other) &&
       (this.subAccount ?? '') === (other.subAccount ?? '') &&
       sameOrUnstated(this.bankCode, other.bankCode) &&
       sameOrUnstated(this.countryCode, other.countryCode)
@@ -188,12 +211,109 @@ export class Account {
     ];
     return `Account(${parts.join(', ')})`;
   }
+
+  /** What Node.js's `util.inspect` and `console.log` show: `toString`, not the fields. */
+  [inspectCustom](): string {
+    return this.toString();
+  }
+}
+
+/**
+ * An IBAN or BIC in the form the bank sends and compares, without blanks, U+0085 (NEL) among them, and in capitals;
+ * `undefined` for blanks only.
+ */
+function electronicFormat(code: string | undefined): string | undefined {
+  return nonBlank(code?.replace(/[\s\u0085]/g, '').toUpperCase());
+}
+
+/** A copy of `ids`, none for `undefined` or `null`; throws `TypeError` unless they are an array of strings. */
+function segmentIds(ids: unknown): string[] {
+  if (ids === undefined || ids === null) return [];
+  if (!Array.isArray(ids) || !ids.every(isString)) {
+    throw invalidArgument('Must be an array of strings', 'allowedTransactions');
+  }
+  return [...ids];
+}
+
+/** A copy of `status`, none for `undefined` or `null`; throws `TypeError` unless it is an `AccountDataStatus`. */
+function copiedDataStatus(status: unknown): AccountDataStatus | undefined {
+  if (status === undefined || status === null) return undefined;
+  if (!(status instanceof AccountDataStatus)) throw invalidArgument('Must be an AccountDataStatus', 'dataStatus');
+  return new AccountDataStatus(status);
 }
 
 function sameOrUnstated(a: string, b: string): boolean {
   return a === '' || b === '' || a === b;
 }
 
+/** The account number as `Account.matches` compares it: without leading zeros. */
+function nationalNumber(account: Account): string | undefined {
+  return account.accountNumber?.replace(/^0+/, '');
+}
+
+/**
+ * Accounts by IBAN and by national account, to find the first one an account `matches` without comparing it with each:
+ * a bank may list tens of thousands.
+ */
+export class AccountIndex {
+  private readonly byIban = new Map<string, number>();
+
+  /** By national account, under its bank and country code and under `null` for any of each, as `matches` takes them. */
+  private readonly byNational = new Map<string, number>();
+
+  /** Those without IBAN only: an account with IBAN matches one with IBAN by that alone. */
+  private readonly byNationalWithoutIban = new Map<string, number>();
+
+  constructor(private readonly accounts: readonly Account[]) {
+    accounts.forEach((account, i) => {
+      if (account.iban !== undefined) keepFirst(this.byIban, account.iban, i);
+      const number = nationalNumber(account);
+      if (number === undefined) return;
+      for (const bankCode of [account.bankCode, null]) {
+        for (const countryCode of [account.countryCode, null]) {
+          const national = nationalKey(number, account.subAccount, bankCode, countryCode);
+          keepFirst(this.byNational, national, i);
+          if (account.iban === undefined) keepFirst(this.byNationalWithoutIban, national, i);
+        }
+      }
+    });
+  }
+
+  /** The first of the accounts that `account` matches. */
+  find(account: Account): Account | undefined {
+    const number = nationalNumber(account);
+    const byNational = account.iban === undefined ? this.byNational : this.byNationalWithoutIban;
+    const found = [account.iban === undefined ? undefined : this.byIban.get(account.iban)];
+    if (number !== undefined) {
+      for (const bankCode of codesMatching(account.bankCode)) {
+        for (const countryCode of codesMatching(account.countryCode)) {
+          found.push(byNational.get(nationalKey(number, account.subAccount, bankCode, countryCode)));
+        }
+      }
+    }
+    const positions = found.filter((i) => i !== undefined);
+    return positions.length === 0 ? undefined : this.accounts[Math.min(...positions)];
+  }
+}
+
+/** The keys of the codes that `code` matches: an empty one matches any, and a stated one also an empty one. */
+function codesMatching(code: string): (string | null)[] {
+  return code === '' ? [null] : [code, ''];
+}
+
+function nationalKey(
+  number: string,
+  subAccount: string | undefined,
+  bankCode: string | null,
+  countryCode: string | null,
+): string {
+  return JSON.stringify([number, subAccount ?? '', bankCode, countryCode]);
+}
+
+function keepFirst(index: Map<string, number>, key: string, position: number): void {
+  if (!index.has(key)) index.set(key, position);
+}
+
 /**
  * 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).
@@ -226,6 +346,7 @@ export class AccountDataStatus {
   /** Whether the balances the transactions carry are the current ones. */
   readonly transactionBalancesCurrent: boolean;
 
+  /** Takes copies of the inventory and the date of `init`, which no other status shares. */
   constructor(init: {
     inventory?: ReadonlyMap<string, string>;
     lastTransactions?: string | undefined;
@@ -234,7 +355,7 @@ export class AccountDataStatus {
   }) {
     this.inventory = new ImmutableMap(init.inventory ?? []);
     this.lastTransactions = init.lastTransactions;
-    this.nextTransactionsAt = init.nextTransactionsAt;
+    this.nextTransactionsAt = copyDate(init.nextTransactionsAt);
     this.transactionBalancesCurrent = init.transactionBalancesCurrent ?? false;
   }
 
@@ -247,4 +368,12 @@ export class AccountDataStatus {
   get camtTransactionsId(): string | undefined {
     return this.inventory.get('HKCAZ');
   }
+
+  /**
+   * What Node.js's `util.inspect` and `console.log` show: the queries `inventory` holds an ID for, not the IDs, which
+   * mark the user's data.
+   */
+  [inspectCustom](): string {
+    return `AccountDataStatus(${[...this.inventory.keys()].join(', ')})`;
+  }
 }

package/src/core/amount.ts

@@ -1,4 +1,7 @@
-import { FormatError } from '../util/errors.js';
+import { requireString } from '../util/arguments.js';
+import { FormatError, invalidArgument } from '../util/errors.js';
+import { inspectCustom } from '../util/inspect.js';
+import { trimBlanks } from '../util/text.js';
 
 /** Most decimal places an amount has: ISO 20022, the widest of the bank formats, allows five. */
 const maxScale = 5;
@@ -10,6 +13,9 @@ 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;
 
+/** Most characters a parsed value has: room for the zeros banks pad amounts with besides `maxDigits` digits. */
+const maxLength = 64;
+
 const decimal = /^([+-]?)(\d*)(?:[.,](\d*))?$/;
 
 /** Decimal places of the minor unit of `currency` (ISO 4217): two, except for the currencies listed here. */
@@ -63,8 +69,13 @@ export class Amount {
   /**
    * 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.
+   * Throws `TypeError` for `minorUnits` or `scale` that are no number, such as `'1234'`, and a `currency` that is no
+   * string.
    */
   constructor(minorUnits: number, scale: number, currency: string) {
+    if (typeof minorUnits !== 'number') throw invalidArgument('Must be a number', 'minorUnits');
+    if (typeof scale !== 'number') throw invalidArgument('Must be a number', 'scale');
+    requireString(currency, 'currency');
     if (!Number.isInteger(scale) || scale < 0 || scale > maxScale) {
       throw new RangeError(`scale must be an integer from 0 to ${maxScale}: ${scale}`);
     }
@@ -83,11 +94,15 @@ export class Amount {
    * `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.
+   * Throws `FormatError` for anything else, so that `1.234,56` in bank data is an error, not a guess, for more than
+   * five decimal places (trailing zeros aside) or more than 15 digits, and for more than 64 characters, zeros included
+   * and surrounding blanks aside. Throws `TypeError` for a `value` or `currency` that is no string.
    */
   static parseDecimal(value: string, currency: string): Amount {
-    const match = decimal.exec(value.trim());
+    const trimmed = trimBlanks(requireString(value, 'value'));
+    requireString(currency, 'currency');
+    if (trimmed.length > maxLength) throw new FormatError(`Amount longer than ${maxLength} characters`, value);
+    const match = decimal.exec(trimmed);
     const whole = match?.[2] ?? '';
     let fraction = match?.[3] ?? '';
     if (!match || (whole === '' && fraction === '')) throw new FormatError('Invalid amount', value);
@@ -175,14 +190,15 @@ export class Amount {
     return `${this.toDecimalString()} ${this.currency}`;
   }
 
+  /** What Node.js's `util.inspect` and `console.log` show: `toString`, not the fields. */
+  [inspectCustom](): string {
+    return this.toString();
+  }
+
   /** 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]!);
+    return [unitsAtScale(this, target), unitsAtScale(other, target)];
   }
 
   private compareValue(other: Amount): number {
@@ -197,12 +213,31 @@ export class Amount {
   }
 }
 
+function unitsAtScale(amount: Amount, scale: number): bigint {
+  return BigInt(amount.minorUnits) * BigInt(powersOfTen[scale - amount.scale]!);
+}
+
+/**
+ * Whether `parts` are all in the currency of `total` and add up to exactly `total`; unlike `add`, also where a sum on
+ * the way lies beyond what an amount holds.
+ */
+export function addsUpTo(parts: readonly Amount[], total: Amount): boolean {
+  let sum = 0n;
+  for (const part of parts) {
+    if (part.currency !== total.currency) return false;
+    sum += unitsAtScale(part, maxScale);
+  }
+  return sum === unitsAtScale(total, maxScale);
+}
+
 /**
  * `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.
+ * 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);