@coderoftime/fints 0.1.0 → 0.3.0

package/src/formats/sepa-purpose.ts

@@ -1,3 +1,6 @@
+import { invalidArgument } from '../util/errors.js';
+import { trimBlanks } from '../util/text.js';
+
 /** SEPA keywords German banks put into the purpose text, each followed by `+`. */
 const keywords = [
   'EREF',
@@ -26,6 +29,9 @@ export function providedReference(reference: string | undefined): string | undef
 
 const keywordPattern = new RegExp(`(${keywords.join('|')})\\+`, 'g');
 
+/** The keywords of the text the payer or the payee writes, which German banks put after every other keyword. */
+const payerText = new Set(['SVWZ', 'ABWA', 'ABWE']);
+
 /** Parser for the SEPA keywords in a purpose text. */
 export const SepaPurpose = Object.freeze({
   /**
@@ -34,6 +40,13 @@ export const SepaPurpose = Object.freeze({
    * A keyword counts unless a capital letter comes right before it, so `XEREF+` does not open an EREF value. After a
    * digit or a small letter it does: a purpose line cut at 35 characters is joined to the next one without a space, so
    * `…4711EREF+` may be where one line ends and the next begins.
+   *
+   * The remittance information (`SVWZ+`) and the ultimate debtor and creditor (`ABWA+`, `ABWE+`) are text the payer or
+   * the payee writes, which banks put after every other keyword, some of them `ABWA+` or `ABWE+` first. So from the
+   * first of them on only these three start a value: any other keyword in that text, such as `IBAN+`, is part of it. A
+   * keyword that occurs twice has no value: which of the two the bank wrote cannot be told, since a reference the payee
+   * chose, such as `EREF+`, comes before the bank's `CRED+` and may hold `CRED+…` and `SVWZ+`, which turns the bank's
+   * value into remittance information.
    */
   parse(purpose: string): Map<string, string> {
     return split(purpose, new Set());
@@ -45,11 +58,15 @@ export const SepaPurpose = Object.freeze({
    *
    * A keyword also counts at the start of a part, where the previous value may end in a capital letter, as in
    * `EREF+NOTPROVIDED` followed by a part `MREF+…`.
+   *
+   * Throws `TypeError` for a string, whose characters would count as parts, and for parts that are no strings.
    */
   parseParts(parts: Iterable<string>): Map<string, string> {
+    if (typeof parts === 'string') throw invalidArgument('Must be the parts, not one string', 'parts');
     let text = '';
     const partStarts = new Set<number>();
     for (const part of parts) {
+      if (typeof part !== 'string') throw invalidArgument('Must be strings', 'parts');
       partStarts.add(text.length);
       text += part;
     }
@@ -60,11 +77,21 @@ export const SepaPurpose = Object.freeze({
 function split(purpose: string, partStarts: ReadonlySet<number>): Map<string, string> {
   const atWordStart = (index: number): boolean =>
     index === 0 || partStarts.has(index) || !isCapitalLetter(purpose, index - 1);
-  const matches = [...purpose.matchAll(keywordPattern)].filter((m) => atWordStart(m.index));
+  const occurrences = new Map<string, number>();
+  const matches: RegExpExecArray[] = [];
+  let inPayerText = false;
+  for (const m of purpose.matchAll(keywordPattern)) {
+    if (!atWordStart(m.index)) continue;
+    const keyword = m[1]!;
+    occurrences.set(keyword, (occurrences.get(keyword) ?? 0) + 1);
+    if (inPayerText && !payerText.has(keyword)) continue;
+    inPayerText ||= payerText.has(keyword);
+    matches.push(m);
+  }
   const result = new Map<string, string>();
   matches.forEach((m, i) => {
     const end = i + 1 < matches.length ? matches[i + 1]!.index : purpose.length;
-    result.set(m[1]!, purpose.substring(m.index + m[0].length, end).trim());
+    if (occurrences.get(m[1]!) === 1) result.set(m[1]!, trimBlanks(purpose.substring(m.index + m[0].length, end)));
   });
   return result;
 }

package/src/index.ts

@@ -7,6 +7,7 @@
  * @packageDocumentation
  */
 
+export { FinTs3Client, type FinTs3ClientInit } from './client.js';
 export { Account, AccountDataStatus, type AccountCategory, type AccountInit } from './core/account.js';
 export { Amount } from './core/amount.js';
 export { Balance, type BalanceInit } from './core/balance.js';
@@ -27,11 +28,13 @@ export {
   FinTsDialogAbortedError,
   FinTsError,
   FinTsLoginDataChangedError,
+  FinTsLoginRefusedError,
   FinTsPinError,
   FinTsProtocolError,
   FinTsStateError,
   FinTsTanCancelledError,
   FinTsTanError,
+  FinTsTanSetupError,
   FinTsTransportError,
   FinTsUnsupportedError,
 } from './core/errors.js';
@@ -43,7 +46,7 @@ export {
   type TransactionStatus,
 } from './core/transaction.js';
 export { HttpTransport, type FinTsTransport, type HttpTransportOptions } from './core/transport.js';
-export { Camt } from './formats/camt.js';
+export { Camt, type CamtStatement } from './formats/camt.js';
 export { Mt940, type Mt940Options, type Mt940Statement } from './formats/mt940.js';
 export { SepaPurpose } from './formats/sepa-purpose.js';
 export {
@@ -65,4 +68,3 @@ export {
   type TanMethodInit,
 } from './tan/tan-models.js';
 export { FormatError } from './util/errors.js';
-export { FinTs3Client, type FinTs3ClientInit } from './v3/client.js';

package/src/session/app-approval.ts

@@ -1,10 +1,15 @@
 import { FinTsDecoupledTimeoutError, FinTsTanCancelledError } from '../core/errors.js';
-import { FeedbackCodes, hasCode } from '../core/feedback.js';
+import { FeedbackCodes, hasCode, type FinTsFeedback } from '../core/feedback.js';
 import { nextAttempt, withResolved, type TanAnswer, type TanChallenge } from '../tan/challenge.js';
 import type { TanMethod } from '../tan/tan-models.js';
 import { Deferred } from '../util/async.js';
 import { invalidArgument } from '../util/errors.js';
-import type { Approval, BankResponse } from './protocol.js';
+import type { Approval } from '../v3/dialog.js';
+
+/** What a wait reads of the bank's answer to a status request: its return codes. */
+interface StatusAnswer {
+  readonly feedback: readonly FinTsFeedback[];
+}
 
 /** How long to wait for an app approval when the bank does not say. */
 const defaultMaxStatusPolls = 60;
@@ -17,10 +22,10 @@ const maxPollDelayMs = 60_000;
 const maxApprovalWaitMs = 10 * 60_000;
 
 /** Shows a challenge and returns the user's answer. */
-export type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
+type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
 
 /** Waits for `delayMs`, or until `interrupt` settles. */
-export type Pause = (delayMs: number, interrupt?: Promise<unknown>) => Promise<void>;
+type Pause = (delayMs: number, interrupt?: Promise<unknown>) => Promise<void>;
 
 /** What an `AppApprovalWait` needs: `ask` shows a challenge, `pause` waits, `receive` takes in each status response. */
 export interface AppApprovalHooks<R> {
@@ -44,7 +49,7 @@ export interface AppApprovalHooks<R> {
  * handles one `Approval`; `run` may be called once. A failure of `ask` or `pause`, such as a closed client, ends the
  * wait.
  */
-export function appApprovalWait<R extends BankResponse>(
+export function appApprovalWait<R extends StatusAnswer>(
   approval: Approval<R>,
   hooks: AppApprovalHooks<R>,
 ): AppApprovalWait<R> {
@@ -53,7 +58,7 @@ export function appApprovalWait<R extends BankResponse>(
   return automatic ? new PollingWhileShown(approval, hooks) : new PollingAfterReports(approval, hooks);
 }
 
-export abstract class AppApprovalWait<R extends BankResponse> {
+export abstract class AppApprovalWait<R extends StatusAnswer> {
   private requests = 0;
 
   /** The time the client waited by itself, which counts towards the longest wait. */
@@ -122,19 +127,20 @@ export abstract class AppApprovalWait<R extends BankResponse> {
 }
 
 /**
- * The client polls by itself while the callback shows the instructions, and settles `TanChallenge.resolved` when it is
- * done.
+ * The client polls by itself while the callback shows the instructions, and settles the `TanChallenge.resolved` of a
+ * prompt when it needs no more answer to it.
  *
  * `run` shows the prompt, waits the bank's first delay, then asks the bank until it confirms, waiting the interval in
- * between. The callback's answer only records what the user did:
+ * between. A status answer with new instructions replaces the prompt with one that shows them. The callback's answer
+ * only records what the user did, and counts while its prompt is shown:
  * - `stopped` settles on a cancel, a TAN or a failing callback; the loop stops before its next request.
  * - `report` settles on a report of the approval, which cuts the current wait short once, though not below a second.
  *   The report closed the prompt, so it is shown anew while the bank has not confirmed yet.
  * - A user who cannot report the approval has every answer but `TanAnswer.cancelled` ignored.
  */
-class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
-  /** Settles when the client needs no more answer, which `TanChallenge.resolved` tells the callback. */
-  private readonly finished = new Deferred<void>();
+class PollingWhileShown<R extends StatusAnswer> extends AppApprovalWait<R> {
+  /** Settles when the prompt shown now needs no more answer, which its `TanChallenge.resolved` tells the callback. */
+  private shown: Deferred<void> | undefined;
 
   /** Settles when the user cancels or the callback fails; `stopReason` holds the error that ends the wait. */
   private readonly stopped = new Deferred<void>();
@@ -154,38 +160,45 @@ class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
         const response = await this.requestStatus();
         if (!isPending(response)) return response;
         this.throwIfStopped();
-        // The user reported the approval, which closed the prompt, but the bank has not confirmed it yet.
-        if (this.userConfirms && this.report === undefined)
-          this.show((challenge = this.nextPrompt(challenge, response)));
+        // A report closed the prompt, but the bank has not confirmed the approval yet; or the bank's instructions changed.
+        const reported = this.userConfirms && this.report === undefined;
+        const next = this.nextPrompt(challenge, response);
+        if (reported || next.message !== challenge.message) this.show((challenge = next));
         await this.sleep(this.pollIntervalMs, minPollIntervalMs);
       }
     } finally {
-      this.finished.resolve();
+      this.shown?.resolve();
     }
   }
 
-  /** Shows `challenge` without waiting for the answer. */
+  /** Shows `challenge` in place of the prompt before, without waiting for the answer. */
   private show(challenge: TanChallenge): void {
+    this.shown?.resolve();
+    const shown = (this.shown = new Deferred<void>());
     const report = (this.report = this.userConfirms ? new Deferred<void>() : undefined);
-    void this.hooks.ask(withResolved(challenge, this.finished.promise)).then(
-      (answer) => {
-        switch (answer.kind) {
-          case 'cancelled':
-            this.stop(new FinTsTanCancelledError());
-            break;
-          case 'approved':
-            report?.resolve();
-            break;
-          case 'tan':
-            if (report !== undefined) this.stop(tanForApproval());
-            break;
-          // The user cannot report the approval: the client waits for the bank.
-        }
-      },
-      (error: unknown) => {
-        this.stop(error);
-      },
-    );
+    // Asked a microtask later: the app closes the prompt before on its `resolved` first, and then opens this one.
+    void Promise.resolve()
+      .then(() => this.hooks.ask(withResolved(challenge, shown.promise)))
+      .then(
+        (answer) => {
+          if (shown.isCompleted) return;
+          switch (answer.kind) {
+            case 'cancelled':
+              this.stop(new FinTsTanCancelledError());
+              break;
+            case 'approved':
+              report?.resolve();
+              break;
+            case 'tan':
+              if (report !== undefined) this.stop(tanForApproval());
+              break;
+            // The user cannot report the approval: the client waits for the bank.
+          }
+        },
+        (error: unknown) => {
+          if (!shown.isCompleted) this.stop(error);
+        },
+      );
   }
 
   private stop(error: unknown): void {
@@ -219,7 +232,7 @@ class PollingWhileShown<R extends BankResponse> extends AppApprovalWait<R> {
  * The client asks the bank after each report of the user; while the approval is pending, the user is asked again with
  * the bank's latest instructions.
  */
-class PollingAfterReports<R extends BankResponse> extends AppApprovalWait<R> {
+class PollingAfterReports<R extends StatusAnswer> extends AppApprovalWait<R> {
   async run(): Promise<R> {
     let challenge = this.approval.challenge;
     await this.confirm(challenge);
@@ -248,7 +261,7 @@ class PollingAfterReports<R extends BankResponse> extends AppApprovalWait<R> {
 }
 
 /** Whether `response` tells that the approval is still pending (return code 3956). */
-function isPending(response: BankResponse): boolean {
+function isPending(response: StatusAnswer): boolean {
   return hasCode(response.feedback, FeedbackCodes.decoupledStillPending);
 }
 

package/src/session/dialog-runner.ts

@@ -1,14 +1,26 @@
 import { FinTsBankError, FinTsProtocolError, parseBankData } from '../core/errors.js';
 import { continuations, FeedbackCodes, hasCode } from '../core/feedback.js';
-import type { BankResponse, ProtocolDialog, Query } from './protocol.js';
-import type { ResponseHandler } from './response-handler.js';
+import type { IncomingMessage3 } from '../v3/message.js';
+import type { Query } from '../v3/queries.js';
+import type { SegmentSpec } from '../v3/syntax.js';
 import type { SessionSetup } from './session-setup.js';
-import type { UserPrompts } from './user-prompts.js';
+import type { SignedDialog } from './signed-dialog.js';
 
 /** Most pages the client fetches for one query, far more than banks send. */
 const maxPages = 1000;
 
-/** Most data one query may hold, summed over its pages: the transport bounds a single response only. */
+/**
+ * Most further pages of one query that may ask for an approval, as its first page may: enough for a bank that asks anew
+ * for each page of a query of four pages, while the user approves four times per query at most, and loses the pages
+ * approved so far with any approval they cancel.
+ */
+const maxPageApprovals = 3;
+
+/**
+ * Most data one query may hold, summed over its pages as `IncomingMessage3.size` measures it: the transport and the
+ * parser bound a single response only. The statements and transactions read from them have a budget of their own
+ * (`RecordBudget`).
+ */
 const maxQueryMebibytes = 128;
 
 /**
@@ -18,17 +30,13 @@ const maxQueryMebibytes = 128;
  * client does not repeat the call by itself, since the bank's answer cannot tell a dialog that had ended before from an
  * order it refuses along with ending the dialog, and a new login may cost the user another approval.
  */
-export class DialogRunner<R extends BankResponse, O> {
-  private dialog: ProtocolDialog<R, O> | undefined;
+export class DialogRunner {
+  private dialog: SignedDialog | undefined;
 
-  constructor(
-    private readonly setup: SessionSetup<R, O>,
-    private readonly responses: ResponseHandler<R>,
-    private readonly prompts: UserPrompts,
-  ) {}
+  constructor(private readonly setup: SessionSetup) {}
 
   /** The open dialog, or a new one once the setup is complete and the user has passed strong authentication. */
-  async open(): Promise<ProtocolDialog<R, O>> {
+  async open(): Promise<SignedDialog> {
     const current = this.dialog;
     if (current?.isActive === true) return current;
     this.dialog = undefined;
@@ -37,10 +45,10 @@ export class DialogRunner<R extends BankResponse, O> {
     return dialog;
   }
 
-  private async login(): Promise<ProtocolDialog<R, O>> {
+  private async login(): Promise<SignedDialog> {
     const dialog = await this.setup.newDialog();
     try {
-      await this.responses.startDialog(dialog, () => dialog.start());
+      await dialog.login();
       return dialog;
     } catch (error) {
       // After a refused login the dialog is discarded already, and ending it sends nothing. After any other failure,
@@ -62,37 +70,64 @@ export class DialogRunner<R extends BankResponse, O> {
    *
    * The query is built once the dialog is open, since building it takes the parameter data.
    */
-  async query<T>(build: () => Query<R, O, T>): Promise<T> {
+  async query<T>(build: () => Query<T>): Promise<T> {
     const dialog = await this.open();
     const query = build();
     const pages = await this.fetchPages(dialog, query.order);
     return parseBankData(() => query.read(pages));
   }
 
-  /** Sends `order` in `dialog` and completes its approval. */
-  private async run(dialog: ProtocolDialog<R, O>, order: O): Promise<R> {
-    this.prompts.checkOpen();
+  /** Sends `order` in `dialog` and completes its approval, which `admitApproval` may refuse (`SignedDialog.send`). */
+  private async run(
+    dialog: SignedDialog,
+    order: SegmentSpec,
+    admitApproval: (() => void) | undefined,
+  ): Promise<IncomingMessage3> {
     try {
-      return await this.responses.complete(dialog, await dialog.send(order));
+      return await dialog.send(order, admitApproval);
     } catch (error) {
       // The bank rejected the order and the dialog stays usable, or the bank ended the dialog or rejected the PIN and
-      // the dialog is discarded already. A cancelled or failed approval, or a broken connection, leaves the dialog in an
-      // unknown state.
+      // the dialog is discarded already. A cancelled, failed or refused approval, or a broken connection, leaves the
+      // dialog in an unknown state.
       if (!(error instanceof FinTsBankError)) await this.end();
       throw error;
     }
   }
 
-  /** Sends the order built by `order` until the bank has delivered all pages (Formals B.6.3, "Aufsetzpunkt"). */
-  private async fetchPages(dialog: ProtocolDialog<R, O>, order: (continuation: string | undefined) => O): Promise<R[]> {
-    const pages: R[] = [];
+  /**
+   * Sends the order built by `order` until the bank has delivered all pages (Formals B.6.3, "Aufsetzpunkt"), and
+   * completes the approval each asks for, that of `maxPageApprovals` further pages at most.
+   */
+  private async fetchPages(
+    dialog: SignedDialog,
+    order: (continuation: string | undefined) => SegmentSpec,
+  ): Promise<IncomingMessage3[]> {
+    const pages: IncomingMessage3[] = [];
     const seen = new Set<string>();
     let size = 0;
+    let pageApprovals = 0;
+    const admitPageApproval = (): void => {
+      if (pageApprovals === maxPageApprovals) {
+        throw new FinTsProtocolError(
+          `The bank asks for an approval of more than ${maxPageApprovals} further pages of one query; ask for a shorter period`,
+        );
+      }
+      pageApprovals++;
+    };
     let continuation: string | undefined;
     for (;;) {
-      const page = await this.run(dialog, order(continuation));
+      const page = await this.run(
+        dialog,
+        order(continuation),
+        continuation === undefined ? undefined : admitPageApproval,
+      );
       pages.push(page);
       size += page.size;
+      if (size > maxQueryMebibytes * 1024 * 1024) {
+        throw new FinTsProtocolError(
+          `The bank sends more than ${maxQueryMebibytes} MiB for one query; ask for a shorter period`,
+        );
+      }
       const positions = [...continuations(page.feedback)];
       // A message carries one order, so the bank names one position at most.
       if (positions.length > 1) throw new FinTsProtocolError('The bank names several positions to continue at');
@@ -104,16 +139,11 @@ export class DialogRunner<R extends BankResponse, O> {
         }
         return pages;
       }
-      // A repeated position or endless pages would keep the client busy forever, and unbounded pages exhaust memory.
+      // A repeated position or endless pages would keep the client busy forever.
       if (seen.has(continuation) || pages.length === maxPages) {
         throw new FinTsProtocolError('The bank does not stop sending pages');
       }
       seen.add(continuation);
-      if (size > maxQueryMebibytes * 1024 * 1024) {
-        throw new FinTsProtocolError(
-          `The bank sends more than ${maxQueryMebibytes} MiB for one query; ask for a shorter period`,
-        );
-      }
     }
   }
 }