@coderoftime/fints 0.1.0 → 0.3.0

package/src/v3/protocol.ts

@@ -1,112 +1,79 @@
 // Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
 
-import type { Account } from '../core/account.js';
-import type { Balance } from '../core/balance.js';
 import type { MessageLogger } from '../core/client.js';
-import { requirePin, type FinTsConfig } from '../core/config.js';
-import { FinTsError, FinTsTransportError, FinTsUnsupportedError } from '../core/errors.js';
-import { hasErrors } from '../core/feedback.js';
-import type { Transaction, TransactionFormat } from '../core/transaction.js';
+import { requirePinLength, type FinTsConfig } from '../core/config.js';
+import { clientClosedError } from '../core/errors.js';
 import type { FinTsTransport } from '../core/transport.js';
-import { camtTransactions, mt940Transactions } from '../formats/readers.js';
-import { BankConnection, checkMessageSize } from '../session/bank-connection.js';
-import { LoginGuard } from '../session/login-guard.js';
-import { offeredVersion, requireBankParameters } from '../session/parameter-data.js';
-import {
-  balanceQuery,
-  checkBeforeSigning,
-  chooseTransactions,
-  type PinTanProtocol,
-  type Query,
-  type Synchronization,
-} from '../session/protocol.js';
-import type { TanMedium, TanMethod } from '../tan/tan-models.js';
-import { invalidArgument } from '../util/errors.js';
-import { readOptionalString, type JsonObject } from '../util/json.js';
 import { decodeBankText } from '../util/text.js';
-import { FinTs3Dialog, type FinTs3DialogHost, type Signing3 } from './dialog.js';
-import { buildMessage, decodeTransport, encodeTransport, IncomingMessage3 } from './message.js';
-import { Bpd3, decodeSegments, encodeSegments, Upd3 } from './parameters.js';
-import { balanceAccount, parseBalance, parseSepaAccounts, parseTanMedia, Segments } from './segments.js';
-import { isLatin1, type Segment, type SegmentSpec } from './syntax.js';
+import { BankConnection, checkMessageSize } from './bank-connection.js';
+import { buildMessage, decodeTransport, encodeTransport } from './message.js';
+import type { MessageLimits, ParameterStore } from './parameter-store.js';
+import { Segments } from './segments.js';
+import type { SegmentSpec } from './syntax.js';
 
 /** Customer ID the specification reserves for anonymous dialogs. */
 const anonymousCustomerId = '9999999999';
 
-/** Longest product ID (Produktbezeichnung) and product version HKVVB takes. */
-const maxProductIdLength = 25;
-const maxProductVersionLength = 5;
+/**
+ * How long the request on its way when the client is closed may take, and then its dialog ends, where the transport
+ * takes the abort (`beginClose`).
+ */
+const closingGraceMs = 5000;
 
-/** A business transaction in FinTS 3.0. */
-export type FinTs3Query<T> = Query<IncomingMessage3, SegmentSpec, T>;
-
-function requireLatin1(text: string, name: string): string {
-  // The message leaves out the value, which may be the PIN.
-  if (!isLatin1(text)) throw invalidArgument(`${name} contains characters FinTS 3.0 cannot send (ISO 8859-1 only)`);
-  return text;
+/** How a message is signed: the security function of the TAN method and the customer system ID. */
+export interface Signing3 {
+  readonly securityFunction: string;
+  readonly systemId: string;
 }
 
-function requireMaxLength(text: string, maxLength: number, name: string): void {
-  if (text.length > maxLength) throw invalidArgument(`At most ${maxLength} characters in FinTS 3.0`, name);
+/** Hands out the PIN for each message the protocol signs, and so decides whether one may go out. */
+export interface PinGuard {
+  /** The PIN to sign a message with; throws instead where none may go out. */
+  readonly pin: string;
+
+  /** Counts a login signed with the PIN, the first message of a dialog, before it goes out. */
+  loginSent(): void;
 }
 
-function requireSendable(config: FinTsConfig): FinTsConfig {
-  requireLatin1(config.userId, 'userId');
-  requireLatin1(config.customerId, 'customerId');
-  requireLatin1(config.productId, 'productId');
-  requireLatin1(config.productVersion, 'productVersion');
-  // Cut short, the product would be one the bank does not know.
-  requireMaxLength(config.productId, maxProductIdLength, 'productId');
-  requireMaxLength(config.productVersion, maxProductVersionLength, 'productVersion');
-  return config;
+/**
+ * Throws if `limits` rule out a message of `size` bytes, or the length of `loginPin`, the PIN of a login: `TypeError`
+ * for the PIN, which the bank would count as a failed attempt, and `FinTsProtocolError` for the size.
+ */
+function checkLimits(limits: MessageLimits, size: number, loginPin: string | undefined): void {
+  if (loginPin !== undefined) requirePinLength(loginPin, limits.pinLength?.min, limits.pinLength?.max);
+  checkMessageSize(size, limits.maxMessageSize);
 }
 
-/** The segments of `type` in all `pages`. */
-function all(pages: readonly IncomingMessage3[], type: string): Segment[] {
-  return pages.flatMap((p) => p.findAll(type));
+/** Whether `segments` are those of a dialog end, the one message a closing client still sends. */
+function isDialogEnd(segments: readonly SegmentSpec[]): boolean {
+  return segments.length === 1 && segments[0]!.type === 'HKEND';
 }
 
-/** FinTS 3.0 messages and business transactions (HBCI segment syntax, PIN/TAN security). */
-export class FinTs3Protocol implements PinTanProtocol<IncomingMessage3, SegmentSpec>, FinTs3DialogHost {
-  readonly config: FinTsConfig;
-  private readonly pin: string;
+/**
+ * Builds, signs and posts FinTS 3.0 messages (HBCI segment syntax, PIN/TAN security) for the user `parameters.config`
+ * names, with the parameter data and IDs `parameters` keeps. Every message signed with the PIN takes it from the
+ * `PinGuard` (`post`), which keeps it from going out after a refused login.
+ */
+export class FinTs3Protocol {
+  private readonly config: FinTsConfig;
   private readonly connection: BankConnection;
-  readonly loginGuard = new LoginGuard();
-
-  /** Customer system ID the bank assigned in the synchronization. */
-  systemId: string | undefined;
-  private bpd: Bpd3 | undefined;
-  private upd: Upd3 | undefined;
-
-  /**
-   * Throws `TypeError` if the PIN is empty, if the PIN or login data contain characters FinTS 3.0 cannot send (ISO
-   * 8859-1 only), or the product ID or version is longer than its field in HKVVB.
-   */
-  constructor(config: FinTsConfig, pin: string, transport?: FinTsTransport, logger?: MessageLogger) {
-    this.config = requireSendable(config);
-    this.pin = requireLatin1(requirePin(pin), 'pin');
-    this.connection = new BankConnection(config.url, transport, logger);
-  }
-
-  get bankParameters(): Bpd3 | undefined {
-    return this.bpd;
-  }
 
-  get userParameters(): Upd3 | undefined {
-    return this.upd;
-  }
+  private closing = false;
 
-  /** Dialogs cannot start without the customer system ID. */
-  get synchronization(): Synchronization {
-    return this.systemId === undefined ? 'required' : 'none';
-  }
+  /** The error with which the limits last stopped a login (`stoppedLogin`). */
+  private stoppedLoginError: unknown;
 
-  forgetSystemId(): boolean {
-    const had = this.systemId !== undefined;
-    this.systemId = undefined;
-    return had;
+  constructor(
+    readonly parameters: ParameterStore,
+    private readonly guard: PinGuard,
+    transport?: FinTsTransport,
+    logger?: MessageLogger,
+  ) {
+    this.config = parameters.config;
+    this.connection = new BankConnection(this.config.url, transport, logger);
   }
 
+  /** Identification (HKIDN) and processing preparation (HKVVB), which open every dialog. */
   initSegments(systemId: string, anonymous = false): SegmentSpec[] {
     return [
       Segments.identification({
@@ -117,15 +84,21 @@ export class FinTs3Protocol implements PinTanProtocol<IncomingMessage3, SegmentS
         systemIdRequired: !anonymous,
       }),
       Segments.processingPreparation({
-        bpdVersion: this.bpd?.version ?? 0,
-        updVersion: anonymous ? 0 : (this.upd?.version ?? 0),
-        language: this.bpd?.dialogLanguage ?? 0,
+        bpdVersion: this.parameters.reportedBpdVersion,
+        updVersion: anonymous ? 0 : this.parameters.reportedUpdVersion,
+        language: this.parameters.bankParameters?.dialogLanguage ?? 0,
         productId: this.config.productId,
         productVersion: this.config.productVersion,
       }),
     ];
   }
 
+  /**
+   * Sends `segments` as message `number` of the dialog `dialogId` and returns the bank's answer, not yet parsed.
+   *
+   * With `signing` the message is signed with the PIN, which `PinGuard.pin` hands out, and the `tan`; without, it
+   * goes out unsigned, as in an anonymous dialog.
+   */
   async post(message: {
     dialogId: string;
     number: number;
@@ -133,196 +106,73 @@ export class FinTs3Protocol implements PinTanProtocol<IncomingMessage3, SegmentS
     signing: Signing3 | undefined;
     tan: string | undefined;
   }): Promise<Uint8Array> {
+    if (this.closing && !isDialogEnd(message.segments)) throw clientClosedError();
     const signing = message.signing;
-    if (signing !== undefined) checkBeforeSigning(this.loginGuard, this.pin, this.bpd);
+    const security =
+      signing === undefined
+        ? undefined
+        : {
+            countryCode: this.config.countryCode,
+            bankCode: this.config.bankCode,
+            userId: this.config.userId,
+            systemId: signing.systemId,
+            pin: this.guard.pin,
+            securityFunction: signing.securityFunction,
+          };
+    // The first message of a signed dialog logs in: from here on the bank may count the PIN.
+    const login = security !== undefined && message.number === 1;
     const outgoing = buildMessage({
       dialogId: message.dialogId,
       messageNumber: message.number,
       segments: message.segments,
-      security:
-        signing === undefined
-          ? undefined
-          : {
-              countryCode: this.config.countryCode,
-              bankCode: this.config.bankCode,
-              userId: this.config.userId,
-              systemId: signing.systemId,
-              pin: this.pin,
-              securityFunction: signing.securityFunction,
-            },
+      security,
       tan: message.tan,
     });
-    checkMessageSize(outgoing.bytes.length, this.bpd?.bankInfo.maxMessageSize);
+    this.checkOutgoing(outgoing.bytes.length, login ? security.pin : undefined);
+    this.connection.checkSendable();
     this.connection.log('outgoing', () => outgoing.masked);
+    if (login) this.guard.loginSent();
     const bytes = decodeTransport(await this.connection.post(encodeTransport(outgoing.bytes), 'text/plain'));
     this.connection.log('incoming', () => decodeBankText(bytes));
     return bytes;
   }
 
-  keepParameterData(response: IncomingMessage3): void {
-    this.keepBankParameters(response);
-    this.upd = Upd3.fromSegments(response.segments, this.config.bankCode, this.config.countryCode) ?? this.upd;
-    this.systemId = response.find('HISYN')?.text(1) ?? this.systemId;
-  }
-
-  private keepBankParameters(response: IncomingMessage3): void {
-    this.bpd = Bpd3.fromSegments(response.segments, this.config.bankCode) ?? this.bpd;
-  }
-
-  /** Keeps the bank parameter data of an anonymous dialog, and nothing that belongs to a user. */
-  async fetchBankParametersAnonymously(): Promise<IncomingMessage3> {
-    const response = await this.requestBankParametersAnonymously();
-    this.keepBankParameters(response);
-    return response;
-  }
-
   /**
-   * Asks for the bank parameter data in an anonymous dialog that announces strong customer authentication; a bank that
-   * rejects the announcement, with a return code or by failing on it, is asked again without it.
+   * Throws if the limits of the parameter data rule out a message of `size` bytes, or the length of `loginPin`, the PIN
+   * of a login (`checkLimits`). The later messages of a dialog, its end included, take the PIN the bank has accepted,
+   * whatever the parameter data it delivered since say.
    *
-   * A timeout or a broken connection is not a reason to ask again: it would only double the wait.
+   * Remembers the error that stops a login (`stoppedLogin`): the parameter data may be outdated, as saved ones are,
+   * and new ones would come only in answer to the login they rule out.
    */
-  private async requestBankParametersAnonymously(): Promise<IncomingMessage3> {
-    let announced: IncomingMessage3;
+  private checkOutgoing(size: number, loginPin: string | undefined): void {
     try {
-      announced = await this.anonymousDialog(true);
+      checkLimits(this.parameters.limits, size, loginPin);
     } catch (error) {
-      if (error instanceof FinTsTransportError && error.statusCode === undefined) throw error;
-      if (!(error instanceof FinTsError)) throw error;
-      return this.anonymousDialog(false);
-    }
-    if (!hasErrors(announced.feedback) || announced.find('HIBPA') !== undefined) return announced;
-    return this.anonymousDialog(false);
-  }
-
-  private async anonymousDialog(announceSca: boolean): Promise<IncomingMessage3> {
-    const dialog = FinTs3Dialog.anonymous(this);
-    try {
-      return await dialog.requestBankParameters(announceSca);
-    } finally {
-      await dialog.end();
+      if (loginPin !== undefined) this.stoppedLoginError = error;
+      throw error;
     }
   }
 
-  newDialog(method: TanMethod, tanMedium?: string): FinTs3Dialog {
-    return FinTs3Dialog.signed(this, method, tanMedium);
-  }
-
-  combine(first: IncomingMessage3, second: IncomingMessage3): IncomingMessage3 {
-    return IncomingMessage3.combine(first, second);
-  }
-
-  // --- Business transactions ---
-
-  private version(
-    transaction: string,
-    implemented: readonly number[],
-    options: { account?: Account; requiresEntry?: boolean } = {},
-  ): number | undefined {
-    return offeredVersion(this.bpd, this.upd, transaction, new Set(implemented), options);
-  }
-
-  tanMedia(): FinTs3Query<TanMedium[]> | undefined {
-    const version = this.version('HKTAB', [4, 5]);
-    if (version === undefined) return undefined;
-    return {
-      order: () => Segments.tanMedia(version),
-      read: (pages) => all(pages, 'HITAB').flatMap(parseTanMedia),
-    };
+  /** Whether `error` is the one with which the limits of the parameter data last stopped a login. */
+  stoppedLogin(error: unknown): boolean {
+    return this.stoppedLoginError !== undefined && this.stoppedLoginError === error;
   }
 
-  sepaAccounts(): FinTs3Query<Account[]> | undefined {
-    const version = this.version('HKSPA', [1, 2, 3], { requiresEntry: true });
-    if (version === undefined) return undefined;
-    return {
-      order: (continuation) => Segments.sepaAccounts(version, continuation),
-      read: (pages) =>
-        all(pages, 'HISPA').flatMap((s) => parseSepaAccounts(s, this.config.countryCode, this.config.bankCode)),
-    };
+  /** Whether the client is closing, so that only dialog ends go out (`beginClose`). */
+  get isClosing(): boolean {
+    return this.closing;
   }
 
-  balance(account: Account): FinTs3Query<Balance> {
-    const version = this.version('HKSAL', [6, 7, 8], { account });
-    if (version === undefined) {
-      throw new FinTsUnsupportedError('The bank reports no balance (HKSAL) for this account');
-    }
-    return balanceQuery<IncomingMessage3, SegmentSpec, Segment>(account, {
-      order: (continuation) => Segments.balance(version, account, continuation),
-      records: (pages) => all(pages, 'HISAL'),
-      accountOf: balanceAccount,
-      read: parseBalance,
-    });
-  }
-
-  transactions(
-    account: Account,
-    format: TransactionFormat,
-    from: Date | undefined,
-    to: Date | undefined,
-  ): FinTs3Query<Transaction[]> {
-    const request = chooseTransactions(format, account, this.upd, {
-      camt: { name: 'HKCAZ', version: this.version('HKCAZ', [1], { account }) },
-      camtFormats: requireBankParameters(this.bpd).camtFormats,
-      mt940: { name: 'HKKAZ', version: this.version('HKKAZ', [6, 7], { account }) },
-    });
-    const version = request.version;
-    if (request.camt) {
-      return {
-        order: (continuation) =>
-          Segments.transactionsCamt(version, account, request.camtFormats, { from, to, continuation }),
-        // The third element group holds the booked documents, the fourth element the pending one.
-        read: (pages) =>
-          camtTransactions(
-            all(pages, 'HICAZ').flatMap((s) =>
-              s
-                .group(3)
-                .filter((d) => !d.isEmpty)
-                .map((d) => d.bytes),
-            ),
-            all(pages, 'HICAZ')
-              .map((s) => s.binary(4))
-              .filter((d) => d !== undefined),
-          ),
-      };
-    }
-    return {
-      order: (continuation) => Segments.transactionsMt940(version, account, { from, to, continuation }),
-      // The first element holds the booked transactions, the second the pending ones.
-      read: (pages) =>
-        mt940Transactions(
-          all(pages, 'HIKAZ')
-            .map((s) => s.binary(1))
-            .filter((d) => d !== undefined),
-          all(pages, 'HIKAZ')
-            .map((s) => s.binary(2))
-            .filter((d) => d !== undefined),
-          request.currency,
-        ),
-    };
-  }
-
-  // --- Saved state ---
-
-  saveState(): JsonObject {
-    return {
-      systemId: this.systemId ?? null,
-      bpd: this.bpd === undefined ? null : encodeSegments(this.bpd.segments),
-      upd: this.upd === undefined ? null : encodeSegments(this.upd.segments),
-    };
-  }
-
-  restoreState(saved: JsonObject): void {
-    const bpd = readOptionalString(saved, 'bpd');
-    const upd = readOptionalString(saved, 'upd');
-    const restoredSystemId = readOptionalString(saved, 'systemId');
-    const restoredBpd = bpd === undefined ? undefined : Bpd3.fromSegments(decodeSegments(bpd), this.config.bankCode);
-    const restoredUpd =
-      upd === undefined
-        ? undefined
-        : Upd3.fromSegments(decodeSegments(upd), this.config.bankCode, this.config.countryCode);
-    this.systemId = restoredSystemId;
-    this.bpd = restoredBpd;
-    this.upd = restoredUpd;
+  /**
+   * Sends nothing but dialog ends from now on: any other message fails with `FinTsStateError` before it goes out, so
+   * that a call under way stops at its next one. The request on its way has `closingGraceMs` to bring its answer, which
+   * counts as any other, and is aborted then; the dialog ends have as long again once it is over, and none goes out
+   * later. The client calls it as soon as it is closed, and `close` once it has ended its dialog.
+   */
+  beginClose(): void {
+    this.closing = true;
+    this.connection.abortRequestsAfter(closingGraceMs);
   }
 
   close(): void {

package/src/v3/queries.ts

@@ -0,0 +1,198 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import type { Account } from '../core/account.js';
+import type { Balance } from '../core/balance.js';
+import { FinTsBankError, FinTsProtocolError, FinTsUnsupportedError } from '../core/errors.js';
+import type { FinTsFeedback } from '../core/feedback.js';
+import type { Transaction, TransactionFormat } from '../core/transaction.js';
+import { camtTransactions, mt940Transactions } from '../formats/readers.js';
+import type { TanMedium } from '../tan/tan-models.js';
+import type { IncomingMessage3 } from './message.js';
+import type { ParameterStore } from './parameter-store.js';
+import { lists, offeredVersion, requireBankParameters } from './parameters.js';
+import { balanceAccount, camtAccount, parseBalance, parseSepaAccounts, parseTanMedia, Segments } from './segments.js';
+import type { Segment, SegmentSpec } from './syntax.js';
+
+/**
+ * A business transaction: the order to send for each page, and how to read all pages the bank sent.
+ *
+ * Where the bank does not offer the transaction, the builders of the lookups the session makes for itself, of the TAN
+ * media and the SEPA accounts, return `undefined`, and those of the app's queries, of a balance and of transactions,
+ * throw `FinTsUnsupportedError`.
+ */
+export interface Query<T> {
+  /** The order for the page at `continuation`; `undefined` for the first page. */
+  readonly order: (continuation: string | undefined) => SegmentSpec;
+
+  /** Reads the result; throws `FormatError` for malformed data. */
+  readonly read: (pages: readonly IncomingMessage3[]) => T;
+}
+
+/** The segments of `type` in all `pages`. */
+function all(pages: readonly IncomingMessage3[], type: string): Segment[] {
+  return pages.flatMap((p) => p.findAll(type));
+}
+
+function version(
+  parameters: ParameterStore,
+  transaction: string,
+  implemented: readonly number[],
+  options: { account?: Account; requiresEntry?: boolean } = {},
+): number | undefined {
+  return offeredVersion(
+    parameters.bankParameters,
+    parameters.userParameters,
+    transaction,
+    new Set(implemented),
+    options,
+  );
+}
+
+/** Lists the TAN media, and keeps the names as the bank sent them in `parameters`; `undefined` if the bank does not. */
+export function tanMediaQuery(parameters: ParameterStore): Query<TanMedium[]> | undefined {
+  const offered = version(parameters, 'HKTAB', [4, 5]);
+  if (offered === undefined) return undefined;
+  return {
+    order: () => Segments.tanMedia(offered),
+    read: (pages) => {
+      const names = new Map<string, string>();
+      const media = all(pages, 'HITAB').flatMap((s) => parseTanMedia(s, names));
+      parameters.keepTanMediumNames(names);
+      return media;
+    },
+  };
+}
+
+/** Lists IBAN and BIC of the accounts; `undefined` if the bank does not offer it. */
+export function sepaAccountsQuery(parameters: ParameterStore): Query<Account[]> | undefined {
+  const offered = version(parameters, 'HKSPA', [1, 2, 3], { requiresEntry: true });
+  if (offered === undefined) return undefined;
+  const { countryCode, bankCode } = parameters.config;
+  return {
+    order: (continuation) => Segments.sepaAccounts(offered, continuation),
+    read: (pages) => all(pages, 'HISPA').flatMap((s) => parseSepaAccounts(s, countryCode, bankCode)),
+  };
+}
+
+/**
+ * The balance (HISAL) of `account` in `records`: the one whose account matches. A single record must match as well,
+ * though the query asked for this one account only: it names the account it is for.
+ *
+ * Throws `FinTsBankError` with the bank's `feedback` if there is none, and `FinTsProtocolError` if none matches.
+ *
+ * @internal Exported for the tests.
+ */
+export function balanceRecord(
+  records: readonly Segment[],
+  account: Account,
+  feedback: readonly FinTsFeedback[],
+): Segment {
+  if (records.length === 0) throw new FinTsBankError(feedback, 'No balance returned');
+  const match = records.find((record) => balanceAccount(record).matches(account));
+  if (match === undefined) {
+    throw new FinTsProtocolError('The bank returned balances, but none for the requested account');
+  }
+  return match;
+}
+
+/**
+ * The balance of `account`, which the session has taken as the bank knows it, with the transactions the bank permits
+ * for it (`SepaAccounts.complete`); throws `FinTsUnsupportedError` if the bank does not report balances.
+ */
+export function balanceQuery(parameters: ParameterStore, account: Account): Query<Balance> {
+  const offered = version(parameters, 'HKSAL', [6, 7, 8], { account });
+  if (offered === undefined) {
+    throw new FinTsUnsupportedError('The bank reports no balance (HKSAL) for this account');
+  }
+  const nationalAllowed = requireBankParameters(parameters.bankParameters).nationalAccountAllowed;
+  return {
+    order: (continuation) => Segments.balance(offered, account, nationalAllowed, continuation),
+    read: (pages) =>
+      parseBalance(
+        balanceRecord(
+          all(pages, 'HISAL'),
+          account,
+          pages.flatMap((p) => p.feedback),
+        ),
+        account,
+      ),
+  };
+}
+
+/**
+ * The transactions of `account` in `format`, from the day of `from` to that of `to`. The session has taken `account` as
+ * the bank knows it, with the transactions the bank permits for it and its currency (`SepaAccounts.complete`).
+ *
+ * The client reads camt.052 only, so camt counts as offered only where the bank offers a camt.052 format. With `auto`
+ * the client takes camt where the bank offers it, unless MT940 can be requested for the account and the user parameter
+ * data list only MT940 transactions for it.
+ *
+ * Throws `FinTsUnsupportedError` if the bank does not offer the chosen format for the account.
+ */
+export function transactionsQuery(
+  parameters: ParameterStore,
+  account: Account,
+  format: TransactionFormat,
+  from: Date | undefined,
+  to: Date | undefined,
+): Query<Transaction[]> {
+  const bpd = requireBankParameters(parameters.bankParameters);
+  const camtVersion = bpd.camtFormats.length === 0 ? undefined : version(parameters, 'HKCAZ', [1], { account });
+  const mt940Version = version(parameters, 'HKKAZ', [6, 7], { account });
+  const camt =
+    format === 'camt' ||
+    (format === 'auto' &&
+      camtVersion !== undefined &&
+      (mt940Version === undefined || lists(account, 'HKCAZ') || !lists(account, 'HKKAZ')));
+  const offered = camt ? camtVersion : mt940Version;
+  if (offered === undefined) {
+    throw new FinTsUnsupportedError(
+      `The bank offers no ${camt ? 'camt ' : ''}transactions (${camt ? 'HKCAZ' : 'HKKAZ'}) for this account`,
+    );
+  }
+  if (camt) {
+    return {
+      order: (continuation) =>
+        Segments.transactionsCamt(offered, account, bpd.nationalAccountAllowed, bpd.camtFormats, {
+          from,
+          to,
+          continuation,
+        }),
+      // The first element names the account, the third element group holds the booked documents, the fourth
+      // element the pending one: binary data, which a bank may send as text instead.
+      read: (pages) => {
+        const segments = all(pages, 'HICAZ');
+        if (!segments.every((s) => camtAccount(s).matches(account))) {
+          throw new FinTsProtocolError('The bank returned the transactions of another account than the one asked for');
+        }
+        return camtTransactions(
+          segments.flatMap((s) =>
+            s
+              .group(3)
+              .filter((d) => !d.isEmpty)
+              .map((d) => d.bytes),
+          ),
+          segments.map((s) => s.bytes(4)).filter((d) => d !== undefined),
+        );
+      },
+    };
+  }
+  return {
+    order: (continuation) =>
+      Segments.transactionsMt940(offered, account, bpd.nationalAccountAllowed, { from, to, continuation }),
+    // The first element holds the booked transactions, the second the pending ones: binary data, which a bank may send
+    // as text instead. Unlike HICAZ, HIKAZ names no account, and banks write the account line of a statement (`:25:`)
+    // in many ways, so it is not compared with `account`: a strict comparison would fail every query of such a bank.
+    read: (pages) =>
+      mt940Transactions(
+        all(pages, 'HIKAZ')
+          .map((s) => s.bytes(1))
+          .filter((d) => d !== undefined),
+        all(pages, 'HIKAZ')
+          .map((s) => s.bytes(2))
+          .filter((d) => d !== undefined),
+        // The currency of statements that state none.
+        account.currency,
+      ),
+  };
+}