@coderoftime/fints 0.1.0 → 0.2.0

package/src/core/config.ts

@@ -1,13 +1,22 @@
 import { invalidArgument } from '../util/errors.js';
+import { isLatin1 } from '../util/text.js';
 
-/** Numeric country code of Germany (ISO 3166), where FinTS banks are. */
+/**
+ * The country code FinTS gives Germany, where FinTS banks are: the ISO 3166 code of the Federal Republic before 1990,
+ * not today's `276`.
+ */
 export const defaultCountryCode = '280';
 
+/** Longest bank code (Kreditinstitutscode), product ID (Produktbezeichnung) and product version FinTS 3.0 takes. */
+const maxBankCodeLength = 30;
+const maxProductIdLength = 25;
+const maxProductVersionLength = 5;
+
 /** What `FinTsConfig` takes. */
 export interface FinTsConfigInit {
-  /** The bank's FinTS PIN/TAN endpoint; must be https. */
+  /** The bank's FinTS PIN/TAN endpoint; must be https, without user name or password. */
   url: string | URL;
-  /** German bank code (BLZ). */
+  /** Bank code: for a German bank its BLZ, eight digits. */
   bankCode: string;
   /** Login name (Benutzerkennung / Legitimations-ID). */
   userId: string;
@@ -17,7 +26,7 @@ export interface FinTsConfigInit {
   productId: string;
   /** Version of the app as registered with the product; at most five characters. `1.0` by default. */
   productVersion?: string;
-  /** Numeric country code of the bank, `280` (Germany) by default. */
+  /** Country code of the bank, three digits: `280`, the default, for Germany. */
   countryCode?: string;
   /**
    * Allows plain http for the loopback addresses `localhost`, `127.x.x.x` and `::1`, for tests against a local server.
@@ -29,10 +38,10 @@ export interface FinTsConfigInit {
 
 /** Connection and login data for one bank user. */
 export class FinTsConfig {
-  /** Numeric country code of Germany (ISO 3166), where FinTS banks are. */
+  /** The country code FinTS gives Germany, where FinTS banks are: `280`, not today's ISO 3166 code `276`. */
   static readonly defaultCountryCode = defaultCountryCode;
 
-  readonly url: URL;
+  private readonly href: string;
   readonly bankCode: string;
   readonly userId: string;
   private readonly explicitCustomerId: string | undefined;
@@ -42,8 +51,15 @@ export class FinTsConfig {
   readonly allowInsecureUrl: boolean;
 
   /**
-   * Throws `TypeError` if `url` is not a valid URL, has no host or is not https, unless `allowInsecureUrl` is set and
-   * `url` is a loopback address, and if a login detail or the product is empty: the bank would refuse the login.
+   * Throws `TypeError` if `url` is not a valid URL, has no host, holds a user name or password, or is not https, unless
+   * `allowInsecureUrl` is set and `url` is a loopback address. Throws as well where the bank would refuse the login: for
+   * a login or product detail that is empty, has characters FinTS 3.0 cannot send (it uses ISO 8859-1, so `€` and most
+   * non-Latin letters are not possible) or is longer than its field (30 characters for the bank code, 25 for the
+   * product ID, 5 for its version), for a country code of other than three digits, and for a German bank code of other
+   * than eight. The message leaves out the value.
+   *
+   * Drops leading and trailing blanks of the login details and the product, as FinTS sends them without (Formals
+   * B.4.1): `'alice '` is the user `alice`, also for a saved state.
    */
   constructor(init: FinTsConfigInit) {
     // `URL` would read `https:bank` and `https:///bank` as the host `bank`; such a URL is a mistake, not a host.
@@ -56,21 +72,29 @@ export class FinTsConfig {
     } catch {
       throw invalidArgument('Not a valid URL', 'url');
     }
-    this.url = url;
-    this.bankCode = init.bankCode;
-    this.userId = init.userId;
-    this.explicitCustomerId = init.customerId;
-    this.productId = init.productId;
-    this.productVersion = init.productVersion ?? '1.0';
-    this.countryCode = init.countryCode ?? defaultCountryCode;
+    this.href = url.href;
     this.allowInsecureUrl = init.allowInsecureUrl ?? false;
     requireSecureUrl(url, this.allowInsecureUrl);
-    requireNotBlank(this.bankCode, 'bankCode');
-    requireNotBlank(this.userId, 'userId');
-    if (this.explicitCustomerId !== undefined) requireNotBlank(this.explicitCustomerId, 'customerId');
-    requireNotBlank(this.productId, 'productId');
-    requireNotBlank(this.productVersion, 'productVersion');
-    requireNotBlank(this.countryCode, 'countryCode');
+    this.countryCode = requireValue(init.countryCode ?? defaultCountryCode, 'countryCode');
+    if (!/^\d{3}$/.test(this.countryCode)) {
+      throw invalidArgument('Must be three digits, 280 for Germany', 'countryCode');
+    }
+    this.bankCode = requireValue(init.bankCode, 'bankCode', maxBankCodeLength);
+    if (this.countryCode === defaultCountryCode && !/^\d{8}$/.test(this.bankCode)) {
+      throw invalidArgument('A German bank code (BLZ) has eight digits', 'bankCode');
+    }
+    this.userId = requireValue(init.userId, 'userId');
+    this.explicitCustomerId = init.customerId === undefined ? undefined : requireValue(init.customerId, 'customerId');
+    this.productId = requireValue(init.productId, 'productId', maxProductIdLength);
+    this.productVersion = requireValue(init.productVersion ?? '1.0', 'productVersion', maxProductVersionLength);
+  }
+
+  /**
+   * The bank's FinTS PIN/TAN endpoint, as checked by the constructor. A new `URL` on each access, so that changing one
+   * cannot change where the client posts the PIN.
+   */
+  get url(): URL {
+    return new URL(this.href);
   }
 
   /** Customer ID; defaults to `userId`. */
@@ -79,8 +103,22 @@ export class FinTsConfig {
   }
 }
 
-function requireNotBlank(value: string, name: string): void {
-  if (value.trim() === '') throw invalidArgument('Must not be empty', name);
+/**
+ * `value` without leading and trailing blanks; throws `TypeError` if nothing is left, or what is left is not sendable
+ * (`requireLatin1`) or longer than `maxLength`: cut short, a value would be one the bank does not know.
+ */
+function requireValue(value: string, name: string, maxLength = Number.POSITIVE_INFINITY): string {
+  const trimmed = value.trim();
+  if (trimmed === '') throw invalidArgument('Must not be empty', name);
+  requireLatin1(trimmed, name);
+  if (trimmed.length > maxLength) throw invalidArgument(`At most ${maxLength} characters in FinTS 3.0`, name);
+  return trimmed;
+}
+
+/** `text`, unless it has characters FinTS 3.0 cannot send (ISO 8859-1 only); the message leaves out the value. */
+export function requireLatin1(text: string, name: string): string {
+  if (!isLatin1(text)) throw invalidArgument('Contains characters FinTS 3.0 cannot send (ISO 8859-1 only)', name);
+  return text;
 }
 
 /** The host of `url` without the brackets of an IPv6 address, as `URL` writes it. */
@@ -92,24 +130,27 @@ export function hostOf(url: URL): string {
 /**
  * Throws `TypeError` unless `url` names a host and uses https: the PIN travels with every message.
  *
- * With `allowInsecure`, http is accepted for loopback hosts only.
+ * With `allowInsecure`, http is accepted for loopback hosts only. Throws as well for a user name or password in `url`:
+ * `fetch` refuses such a URL, with the whole URL in its error message. The message leaves them out.
  */
-export function requireSecureUrl(url: URL, allowInsecure = false): void {
+function requireSecureUrl(url: URL, allowInsecure = false): void {
   if (hostOf(url) === '') throw invalidArgument('The URL has no host', 'url');
+  if (url.username !== '' || url.password !== '') throw invalidArgument('The URL must not contain credentials', 'url');
   const loopbackHttp = allowInsecure && url.protocol === 'http:' && isLoopback(hostOf(url));
   if (url.protocol !== 'https:' && !loopbackHttp) throw invalidArgument('PIN/TAN requires an https URL', 'url');
 }
 
 /**
- * Throws `TypeError` for an empty PIN, which the bank would count as a failed attempt, and for one with leading or
- * trailing blanks: FinTS values carry none (Formals B.4.1), so such a PIN could only go out changed.
+ * `pin`, unless FinTS 3.0 cannot send it: throws `TypeError` for an empty PIN, which the bank would count as a failed
+ * attempt, for one with leading or trailing blanks, which would go out without them since FinTS values carry none
+ * (Formals B.4.1), and for one with characters outside ISO 8859-1.
  *
  * The message leaves out the value.
  */
 export function requirePin(pin: string): string {
   if (pin.trim() === '') throw invalidArgument('The PIN is empty', 'pin');
   if (pin.trim() !== pin) throw invalidArgument('The PIN begins or ends with a blank', 'pin');
-  return pin;
+  return requireLatin1(pin, 'pin');
 }
 
 /**

package/src/core/errors.ts

@@ -1,54 +1,68 @@
 import { FormatError } from '../util/errors.js';
-import { endsDialog, FeedbackCodes, type FinTsFeedback } from './feedback.js';
+import { nonBlank } from '../util/text.js';
+import { endsDialog, FeedbackCodes, hasCode, type FinTsFeedback } from './feedback.js';
 
-/** Base class of all errors the client raises about the bank and its data. */
+/**
+ * Base class of all errors the client raises about the bank and its data.
+ *
+ * Each error class states its `name`: a minifier renames classes, and `constructor.name` would show a meaningless one.
+ */
 export abstract class FinTsError extends Error {
-  protected constructor(name: string, message: string, cause?: unknown) {
-    super(message, cause === undefined ? undefined : { cause });
-    // Set explicitly: a minifier renames classes, and `constructor.name` would show a meaningless name.
-    this.name = name;
-  }
+  abstract override name: string;
 }
 
-/** The connection to the bank failed or returned an HTTP error. */
+/**
+ * The connection to the bank failed or returned an HTTP error.
+ *
+ * It carries no `cause`: the transport's own error may hold the message it was sending, PIN and TAN included.
+ */
 export class FinTsTransportError extends FinTsError {
-  /** The HTTP status code of the response, `undefined` if there was none, for example after a timeout. */
+  override name = 'FinTsTransportError';
+
+  /**
+   * The HTTP status code of the bank's answer, `undefined` where none came, for example after a timeout; the client
+   * acts on it (`FinTsTransport.post`).
+   */
   readonly statusCode: number | undefined;
 
-  constructor(message: string, options?: { statusCode?: number; cause?: unknown }) {
-    super('FinTsTransportError', message, options?.cause);
+  constructor(message: string, options?: { statusCode?: number }) {
+    super(message);
     this.statusCode = options?.statusCode;
   }
 }
 
 /** The bank's response could not be understood. */
 export class FinTsProtocolError extends FinTsError {
-  constructor(message: string) {
-    super('FinTsProtocolError', message);
-  }
+  override name = 'FinTsProtocolError';
 }
 
 /** The bank does not offer the requested business transaction. */
 export class FinTsUnsupportedError extends FinTsError {
-  constructor(message: string) {
-    super('FinTsUnsupportedError', message);
-  }
+  override name = 'FinTsUnsupportedError';
 }
 
 /**
- * The bank rejected the request; `feedback` holds all return codes.
+ * The client has no TAN method or medium to log in with: the method in use needs a TAN medium the client could not
+ * learn, or the bank offers the user only TAN methods the client cannot run. Pass a medium to
+ * `FinTsClient.selectTanMethod`, or choose another method.
  *
- * After a refused login every later call that would send the PIN fails with the same error, without contacting the
- * bank; create a new client to try again. The README tells which errors refuse a login.
+ * The client does not send a login the bank would refuse for it, but the steps before, such as the synchronization or
+ * the lookup of the TAN media, may have gone out.
  */
+export class FinTsTanSetupError extends FinTsError {
+  override name = 'FinTsTanSetupError';
+}
+
+/** The bank rejected the request; `feedback` holds all return codes. A refused login is a `FinTsLoginRefusedError`. */
 export class FinTsBankError extends FinTsError {
+  override name = 'FinTsBankError';
+
   /** All return codes of the response, warnings and successes included. */
   readonly feedback: readonly FinTsFeedback[];
 
   /** A rejection with the return codes in `feedback`; `message` defaults to the errors among them. */
-  constructor(feedback: readonly FinTsFeedback[], message?: string, name = 'FinTsBankError') {
+  constructor(feedback: readonly FinTsFeedback[], message?: string) {
     super(
-      name,
       message ??
         feedback
           .filter((f) => f.isError)
@@ -64,29 +78,44 @@ export class FinTsBankError extends FinTsError {
   }
 }
 
-/** Wrong or blocked PIN, a refused login as `FinTsBankError` describes it. */
-export class FinTsPinError extends FinTsBankError {
-  constructor(feedback: readonly FinTsFeedback[]) {
-    super(feedback, undefined, 'FinTsPinError');
-  }
+/**
+ * The bank refused the login, so the client sends the PIN no more: every later call that would send it fails with this
+ * error without contacting the bank, also in a client restored from the saved state, until
+ * `FinTsClient.clearLoginRefusal` takes a PIN the user has entered anew; for good where the bank has changed the login
+ * data (`FinTsLoginDataChangedError`).
+ *
+ * Banks lock the access after a few failed logins, and a return code does not always tell whether the PIN was the
+ * reason, so any error in the answer to a login refuses it, also one that ends the dialog, and so does a wrong PIN
+ * wherever the bank reports it. Only where the bank names a reason the client can take care of, another TAN method or a
+ * new customer system ID, does the same call log in once more, for each reason once. The client refuses the login
+ * itself where it could not read the answers to two logins in a row, which the bank may have counted as failed
+ * attempts; `feedback` is empty then.
+ */
+export class FinTsLoginRefusedError extends FinTsBankError {
+  override name = 'FinTsLoginRefusedError';
+}
+
+/** Wrong or blocked PIN. */
+export class FinTsPinError extends FinTsLoginRefusedError {
+  override name = 'FinTsPinError';
 }
 
 /** Invalid, expired or rejected TAN, as the bank reports it in answer to a TAN or to an approval status request. */
 export class FinTsTanError extends FinTsBankError {
-  constructor(feedback: readonly FinTsFeedback[]) {
-    super(feedback, undefined, 'FinTsTanError');
-  }
+  override name = 'FinTsTanError';
 }
 
 /**
  * The bank has changed the user's login data and expects the new ones from now on (return code 3072).
  *
- * The client has ended the dialog, and every later call fails with this error. Create a new client with the new data; a
- * `loginName` replaces user ID and customer ID: pass it as `userId`, without a customer ID.
+ * The client has ended the dialog, where the bank opened one, and logs in with the old data no more. Create a new
+ * client with the new data; a `loginName` replaces user ID and customer ID: pass it as `userId`, without a customer ID.
  */
-export class FinTsLoginDataChangedError extends FinTsBankError {
+export class FinTsLoginDataChangedError extends FinTsLoginRefusedError {
+  override name = 'FinTsLoginDataChangedError';
+
   constructor(feedback: readonly FinTsFeedback[]) {
-    super(feedback, 'The bank has changed the login data', 'FinTsLoginDataChangedError');
+    super(feedback, 'The bank has changed the login data');
   }
 
   /** The new user ID (Benutzerkennung); `undefined` where the bank names none. */
@@ -106,29 +135,36 @@ export class FinTsLoginDataChangedError extends FinTsBankError {
 
   private parameter(index: number): string | undefined {
     const change = this.feedback.find((f) => f.code === FeedbackCodes.newLoginData);
-    const value = change?.parameters[index]?.trim();
-    return value === undefined || value === '' ? undefined : value;
+    return nonBlank(change?.parameters[index]);
   }
 }
 
-/** The bank ended the dialog, for example after a timeout. */
+/**
+ * The bank ended the dialog, for example after a timeout; the next call logs in anew. Where the bank ends the dialog
+ * in answer to a login, the call fails with `FinTsLoginRefusedError` instead.
+ */
 export class FinTsDialogAbortedError extends FinTsBankError {
-  constructor(feedback: readonly FinTsFeedback[]) {
-    super(feedback, undefined, 'FinTsDialogAbortedError');
-  }
+  override name = 'FinTsDialogAbortedError';
 }
 
 /** The user cancelled the TAN entry or the approval in the banking app. */
 export class FinTsTanCancelledError extends FinTsError {
+  override name = 'FinTsTanCancelledError';
+
   constructor() {
-    super('FinTsTanCancelledError', 'TAN entry cancelled');
+    super('TAN entry cancelled');
   }
 }
 
-/** The user did not approve in the banking app within the bank's polling limit. */
+/**
+ * The user did not approve in the banking app in time: within the status requests the bank allows, 60 where it states
+ * none, and 10 minutes of polling at most.
+ */
 export class FinTsDecoupledTimeoutError extends FinTsError {
+  override name = 'FinTsDecoupledTimeoutError';
+
   constructor() {
-    super('FinTsDecoupledTimeoutError', 'Approval on the separate device was not completed in time');
+    super('Approval on the separate device was not completed in time');
   }
 }
 
@@ -138,10 +174,12 @@ export class FinTsDecoupledTimeoutError extends FinTsError {
  * It does not extend `FinTsError`: it tells about the app's use of the client, not about the bank.
  */
 export class FinTsStateError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'FinTsStateError';
-  }
+  override name = 'FinTsStateError';
+}
+
+/** The error of whatever a closed client is asked to do. */
+export function clientClosedError(): FinTsStateError {
+  return new FinTsStateError('The FinTS client is closed');
 }
 
 /**
@@ -192,7 +230,23 @@ export function bankErrorFor(feedback: readonly FinTsFeedback[], completesApprov
   return new FinTsBankError(feedback);
 }
 
-/** Runs `parse` on data from the bank and reports malformed data as `FinTsProtocolError`. */
+/**
+ * The refusal of a login whose answer carried `feedback`: `FinTsPinError` for a rejected PIN, else
+ * `FinTsLoginDataChangedError` for new login data, also next to other errors, and `FinTsLoginRefusedError` for anything
+ * else. The same for a refusal restored from the saved state, which keeps only `feedback`.
+ *
+ * New login data end the old ones for good, so the session takes care of no other reason the answer names.
+ */
+export function loginRefusalFor(feedback: readonly FinTsFeedback[]): FinTsLoginRefusedError {
+  if (feedback.some(isPinError)) return new FinTsPinError(feedback);
+  if (hasCode(feedback, FeedbackCodes.newLoginData)) return new FinTsLoginDataChangedError(feedback);
+  return new FinTsLoginRefusedError(feedback);
+}
+
+/**
+ * Runs `parse` on data from the bank and reports malformed data as `FinTsProtocolError`, whose message leaves the data
+ * out (`FormatError`).
+ */
 export function parseBankData<T>(parse: () => T): T {
   try {
     return parse();
@@ -201,3 +255,23 @@ export function parseBankData<T>(parse: () => T): T {
     throw error;
   }
 }
+
+/**
+ * Runs `lookup`, which only completes data, such as the SEPA account list; `undefined` where the bank rejects it, so
+ * that the caller carries on without it. An aborted dialog counts as a rejection: banks end the dialog along with many.
+ * A refused login and a rejected TAN fail the call: the user must hear of them.
+ */
+export async function tryLookUp<T>(lookup: () => Promise<T>): Promise<T | undefined> {
+  try {
+    return await lookup();
+  } catch (error) {
+    if (
+      !(error instanceof FinTsBankError) ||
+      error instanceof FinTsLoginRefusedError ||
+      error instanceof FinTsTanError
+    ) {
+      throw error;
+    }
+    return undefined;
+  }
+}

package/src/core/feedback.ts

@@ -9,7 +9,10 @@ export class FinTsFeedback {
   /** The bank's explanation of the code. */
   readonly text: string;
 
-  /** Values the bank adds to the code, such as the position to continue at. */
+  /**
+   * Values the bank adds to the code, such as the position to continue at: one character per byte the bank sent (ISO
+   * 8859-1, the FinTS character set), since the client and the app send them back as they came.
+   */
   readonly parameters: readonly string[];
 
   constructor(init: { code: string; reference?: string | undefined; text: string; parameters?: readonly string[] }) {

package/src/core/transaction.ts

@@ -1,4 +1,4 @@
-import { formatIsoDate } from '../util/dates.js';
+import { copyDate, formatIsoDate } from '../util/dates.js';
 import { ImmutableMap } from '../util/immutable-map.js';
 import type { Amount } from './amount.js';
 
@@ -112,13 +112,18 @@ export class Transaction {
   /** The party the payer acts for, where that is not the payer itself. */
   readonly ultimateDebtor: string | undefined;
 
-  /** All SEPA keywords found in the purpose, keyed by keyword (EREF, KREF, MREF, CRED, SVWZ, …). */
+  /**
+   * The SEPA keywords of the purpose, keyed by keyword (EREF, KREF, MREF, CRED, SVWZ, …): those `SepaPurpose` reads. In
+   * camt, EREF, MREF and CRED are those of `endToEndId`, `mandateId` and `creditorId`, which the bank states apart,
+   * never keywords of the remittance text the payer or the payee writes.
+   */
   readonly purposeCodes: ReadonlyMap<string, string>;
 
+  /** Takes copies of the dates and purpose codes of `init`: each transaction has its own, which no other one shares. */
   constructor(init: TransactionInit) {
     this.status = init.status ?? 'booked';
-    this.bookingDate = init.bookingDate;
-    this.valueDate = init.valueDate;
+    this.bookingDate = copyDate(init.bookingDate);
+    this.valueDate = copyDate(init.valueDate);
     this.amount = init.amount;
     this.isReversal = init.isReversal ?? false;
     this.bookingText = init.bookingText;