@coderoftime/fints 0.1.0 → 0.2.0

package/src/client.ts

@@ -0,0 +1,252 @@
+import type { 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 } from './core/transaction.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 { 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>();
+
+/**
+ * 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);
+}
+
+/** 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.
+   */
+  constructor(init: FinTs3ClientInit) {
+    const config = init.config instanceof FinTsConfig ? init.config : new FinTsConfig(init.config);
+    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, init.options.transport, this.#prompts.logger);
+    this.#sessionState = restoreSession(init.options.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;
+  }
+
+  selectTanMethod(securityFunction: string, tanMedium?: string): Promise<void> {
+    return this.#serialized(async () => {
+      await this.#dialogs.end();
+      this.#tans.select(securityFunction, tanMedium);
+    });
+  }
+
+  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());
+  }
+
+  getBalance(account: Account): Promise<Balance> {
+    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.
+    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');
+    }
+    return this.#serialized(async () => {
+      const completed = await this.#sepa.complete(account);
+      const transactions = await this.#dialogs.query(() =>
+        transactionsQuery(
+          this.#parameters,
+          completed,
+          query.format ?? 'auto',
+          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(() => {
+            this.#prompts.checkOpen();
+            return this.#prompts.reportingCallbackErrors(action);
+          }),
+        );
+      } finally {
+        this.#runningCall = undefined;
+      }
+    });
+  }
+}

package/src/core/account.ts

@@ -1,5 +1,6 @@
+import { copyDate } from '../util/dates.js';
 import { ImmutableMap } from '../util/immutable-map.js';
-import { maskedId } from '../util/text.js';
+import { maskedId, nonBlank } from '../util/text.js';
 import { defaultCountryCode } from './config.js';
 
 /** Account kind derived from the FinTS account type code. */
@@ -40,7 +41,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 +64,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 +86,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 +113,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,13 +127,14 @@ 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. */
   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.iban = electronicFormat(init.iban);
+    this.bic = electronicFormat(init.bic);
     this.customerId = init.customerId;
     this.currency = init.currency;
     this.ownerName = init.ownerName;
@@ -129,7 +142,7 @@ export class Account {
     this.typeCode = init.typeCode;
     this.allowedTransactions = Object.freeze([...(init.allowedTransactions ?? [])]);
     this.allowedTransactionsComplete = init.allowedTransactionsComplete ?? false;
-    this.dataStatus = init.dataStatus;
+    this.dataStatus = init.dataStatus && new AccountDataStatus(init.dataStatus);
   }
 
   /** The kind of account, derived from `typeCode`. */
@@ -146,10 +159,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)
@@ -190,10 +203,69 @@ export class Account {
   }
 }
 
+/**
+ * An IBAN or BIC in the form the bank sends and compares, without blanks and in capitals; `undefined` for blanks only.
+ */
+function electronicFormat(code: string | undefined): string | undefined {
+  return nonBlank(code?.replace(/\s/g, '').toUpperCase());
+}
+
 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.
+ *
+ * Bank and country codes count as they are, where `matches` takes an empty one for any: the accounts a bank lists state
+ * both.
+ */
+export class AccountIndex {
+  private readonly byIban = new Map<string, number>();
+  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) => {
+      const national = nationalKey(account);
+      if (account.iban !== undefined) keepFirst(this.byIban, account.iban, i);
+      if (national === undefined) return;
+      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 national = nationalKey(account);
+    const byNational = account.iban === undefined ? this.byNational : this.byNationalWithoutIban;
+    const found = [
+      account.iban === undefined ? undefined : this.byIban.get(account.iban),
+      national === undefined ? undefined : byNational.get(national),
+    ].filter((i) => i !== undefined);
+    return found.length === 0 ? undefined : this.accounts[Math.min(...found)];
+  }
+}
+
+function nationalKey(account: Account): string | undefined {
+  const number = nationalNumber(account);
+  return number === undefined
+    ? undefined
+    : JSON.stringify([number, account.subAccount ?? '', account.bankCode, account.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 +298,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 +307,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;
   }
 

package/src/core/amount.ts

@@ -200,9 +200,11 @@ export class Amount {
 /**
  * `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);

package/src/core/balance.ts

@@ -1,4 +1,4 @@
-import { formatIsoDate } from '../util/dates.js';
+import { copyDate, formatIsoDate } from '../util/dates.js';
 import type { Account } from './account.js';
 import type { Amount } from './amount.js';
 
@@ -59,18 +59,19 @@ export class Balance {
   /** 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 = init.bookedAsOf;
-    this.bookedAsOfTime = init.bookedAsOfTime;
+    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 = init.bookingDate;
-    this.bookingTime = init.bookingTime;
+    this.bookingDate = copyDate(init.bookingDate);
+    this.bookingTime = copyDate(init.bookingTime);
     this.productName = init.productName;
   }
 

package/src/core/bank-info.ts

@@ -26,7 +26,7 @@ export class BankInfo {
 
   /**
    * 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.
+   * 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;
 

package/src/core/client.ts

@@ -3,6 +3,7 @@ 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';
@@ -49,9 +50,15 @@ export interface FinTsClientOptions {
   logger?: MessageLogger;
 
   /**
-   * The `FinTsClient.state` of a previous session, which skips the bank setup steps.
+   * 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 saved for another user or bank is ignored.
+   * 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;
 
@@ -76,22 +83,33 @@ export interface TransactionQuery {
 /**
  * Read access to a bank account over FinTS.
  *
- * All calls share one bank dialog, so strong authentication happens once per session. Calls run one after another; call
- * `close` when done.
+ * 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 and Bun such a call fails with `FinTsStateError`; elsewhere it would wait forever. `close` works
- * from anywhere.
+ * 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, and the SEPA account list.
+   * 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.
+   * 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;
 
@@ -106,10 +124,25 @@ export interface FinTsClient {
    */
   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. */
+  /**
+   * 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. */
@@ -124,7 +157,8 @@ export interface FinTsClient {
    * 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.
    *
-   * Throws `FinTsUnsupportedError`, without asking the bank, where the parameter data rule the query out.
+   * 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>;
 
@@ -133,17 +167,20 @@ export interface FinTsClient {
    * 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`. Throws `TypeError` if `from` lies on a day after
-   * `to`, and `FinTsUnsupportedError`, without asking the bank, where the parameter data rule the query out.
+   * `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 and releases the connection.
+   * 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 awaited, at most for the transport's
-   * timeout.
+   * `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>;
 }