@coderoftime/fints 0.0.0-stage → 0.2.0

package/dist/formats/sepa-purpose.js

@@ -0,0 +1,89 @@
+/** SEPA keywords German banks put into the purpose text, each followed by `+`. */
+const keywords = [
+    'EREF',
+    'KREF',
+    'MREF',
+    'CRED',
+    'DEBT',
+    'COAM',
+    'OAMT',
+    'SVWZ',
+    'ABWA',
+    'ABWE',
+    'IBAN',
+    'BIC',
+    'PURP',
+    'SQTP',
+];
+/** The filler SEPA prescribes where the payer gave no end-to-end reference. */
+const notProvided = 'NOTPROVIDED';
+/** `reference`, or `undefined` if it is missing or the filler for a reference the payer did not give. */
+export function providedReference(reference) {
+    return reference === notProvided ? undefined : reference;
+}
+const keywordPattern = new RegExp(`(${keywords.join('|')})\\+`, 'g');
+/** The keywords German banks write after the remittance information (`SVWZ`). */
+const afterRemittance = new Set(['ABWA', 'ABWE']);
+/** Parser for the SEPA keywords in a purpose text. */
+export const SepaPurpose = Object.freeze({
+    /**
+     * Splits `purpose` into its SEPA keywords (EREF, KREF, MREF, CRED, SVWZ, …) and their values.
+     *
+     * 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. So from the first of them on only `ABWA+` and `ABWE+`
+     * start a value: a 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) {
+        return split(purpose, new Set());
+    },
+    /**
+     * Like `parse` for a purpose the bank sends in `parts`, such as the MT940 subfields `?20` to `?29`, which continue
+     * each other without a separator.
+     *
+     * 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+…`.
+     */
+    parseParts(parts) {
+        let text = '';
+        const partStarts = new Set();
+        for (const part of parts) {
+            partStarts.add(text.length);
+            text += part;
+        }
+        return split(text, partStarts);
+    },
+});
+function split(purpose, partStarts) {
+    const atWordStart = (index) => index === 0 || partStarts.has(index) || !isCapitalLetter(purpose, index - 1);
+    const occurrences = new Map();
+    const matches = [];
+    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 && !afterRemittance.has(keyword))
+            continue;
+        inPayerText ||= keyword === 'SVWZ' || afterRemittance.has(keyword);
+        matches.push(m);
+    }
+    const result = new Map();
+    matches.forEach((m, i) => {
+        const end = i + 1 < matches.length ? matches[i + 1].index : purpose.length;
+        if (occurrences.get(m[1]) === 1)
+            result.set(m[1], purpose.substring(m.index + m[0].length, end).trim());
+    });
+    return result;
+}
+function isCapitalLetter(text, index) {
+    const c = text.charCodeAt(index);
+    return c >= 0x41 && c <= 0x5a;
+}
+//# sourceMappingURL=sepa-purpose.js.map

package/dist/formats/sepa-purpose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sepa-purpose.js","sourceRoot":"","sources":["../../src/formats/sepa-purpose.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * FinTS 3.0 client for German banks: accounts, balances and transactions with PIN/TAN, PSD2 strong customer
+ * authentication and decoupled app approval.
+ *
+ * Start with `FinTs3Client`. The public API is what this file names; everything else is internal.
+ *
+ * @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';
+export { BankInfo, BankMessage } from './core/bank-info.js';
+export type { BankMessageHandler, FinTsClient, FinTsClientOptions, MessageDirection, MessageLogger, TransactionQuery, WarningHandler, } from './core/client.js';
+export { FinTsConfig, type FinTsConfigInit } from './core/config.js';
+export { FinTsBankError, FinTsDecoupledTimeoutError, FinTsDialogAbortedError, FinTsError, FinTsLoginDataChangedError, FinTsLoginRefusedError, FinTsPinError, FinTsProtocolError, FinTsStateError, FinTsTanCancelledError, FinTsTanError, FinTsTanSetupError, FinTsTransportError, FinTsUnsupportedError, } from './core/errors.js';
+export { FeedbackCodes, FinTsFeedback } from './core/feedback.js';
+export { Transaction, type TransactionFormat, type TransactionInit, type TransactionStatus, } from './core/transaction.js';
+export { HttpTransport, type FinTsTransport, type HttpTransportOptions } from './core/transport.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 { TanAnswer, TanChallenge, type TanCallback, type TanChallengeInit, type TanMediumSelector, type TanMethodSelector, } from './tan/challenge.js';
+export { FlickerCode, type HhdVersion } from './tan/flicker.js';
+export { TanImage } from './tan/tan-image.js';
+export { TanMedium, TanMethod, type TanMediumInit, type TanMediumRequirement, type TanMediumStatus, type TanMethodInit, } from './tan/tan-models.js';
+export { FormatError } from './util/errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACvG,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,uBAAuB,EACvB,UAAU,EACV,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,IAAI,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EACL,SAAS,EACT,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EACL,SAAS,EACT,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * FinTS 3.0 client for German banks: accounts, balances and transactions with PIN/TAN, PSD2 strong customer
+ * authentication and decoupled app approval.
+ *
+ * Start with `FinTs3Client`. The public API is what this file names; everything else is internal.
+ *
+ * @packageDocumentation
+ */
+export { FinTs3Client } from './client.js';
+export { Account, AccountDataStatus } from './core/account.js';
+export { Amount } from './core/amount.js';
+export { Balance } from './core/balance.js';
+export { BankInfo, BankMessage } from './core/bank-info.js';
+export { FinTsConfig } from './core/config.js';
+export { FinTsBankError, FinTsDecoupledTimeoutError, FinTsDialogAbortedError, FinTsError, FinTsLoginDataChangedError, FinTsLoginRefusedError, FinTsPinError, FinTsProtocolError, FinTsStateError, FinTsTanCancelledError, FinTsTanError, FinTsTanSetupError, FinTsTransportError, FinTsUnsupportedError, } from './core/errors.js';
+export { FeedbackCodes, FinTsFeedback } from './core/feedback.js';
+export { Transaction, } from './core/transaction.js';
+export { HttpTransport } from './core/transport.js';
+export { Camt } from './formats/camt.js';
+export { Mt940 } from './formats/mt940.js';
+export { SepaPurpose } from './formats/sepa-purpose.js';
+export { TanAnswer, TanChallenge, } from './tan/challenge.js';
+export { FlickerCode } from './tan/flicker.js';
+export { TanImage } from './tan/tan-image.js';
+export { TanMedium, TanMethod, } from './tan/tan-models.js';
+export { FormatError } from './util/errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAyB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAA0C,MAAM,mBAAmB,CAAC;AACvG,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAoB,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAU5D,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,uBAAuB,EACvB,UAAU,EACV,0BAA0B,EAC1B,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EACL,WAAW,GAIZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAkD,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,IAAI,EAAsB,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAA0C,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EACL,SAAS,EACT,YAAY,GAKb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAmB,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EACL,SAAS,EACT,SAAS,GAKV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/session/app-approval.d.ts

@@ -0,0 +1,66 @@
+import { type FinTsFeedback } from '../core/feedback.js';
+import { type TanAnswer, type TanChallenge } from '../tan/challenge.js';
+import type { TanMethod } from '../tan/tan-models.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[];
+}
+/** Shows a challenge and returns the user's answer. */
+type AskUser = (challenge: TanChallenge) => Promise<TanAnswer>;
+/** Waits for `delayMs`, or until `interrupt` settles. */
+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> {
+    readonly ask: AskUser;
+    readonly pause: Pause;
+    /** Takes in each status response; throws if it reports errors. */
+    readonly receive: (response: R) => void;
+}
+/**
+ * Waits for the user to approve a message in the banking app, and for the bank to confirm it (PIN/TAN B.4.2.2).
+ *
+ * The bank's parameters decide who triggers the status requests:
+ * - The client polls by itself while the callback shows the instructions (`PollingWhileShown`) where the bank allows
+ *   automatic status requests and announces no push message (3957), and also where the user cannot report the
+ *   approval: then polling is the one way left to complete it, whatever the other parameters say (step 2a).
+ * - Otherwise the client asks after each report of the user (`PollingAfterReports`), which stands in for the push
+ *   message the client cannot receive.
+ *
+ * The bank's limit on status requests holds either way, and two requests are at least a second apart. One instance
+ * handles one `Approval`; `run` may be called once. A failure of `ask` or `pause`, such as a closed client, ends the
+ * wait.
+ */
+export declare function appApprovalWait<R extends StatusAnswer>(approval: Approval<R>, hooks: AppApprovalHooks<R>): AppApprovalWait<R>;
+export declare abstract class AppApprovalWait<R extends StatusAnswer> {
+    protected readonly approval: Approval<R>;
+    protected readonly hooks: AppApprovalHooks<R>;
+    private requests;
+    /** The time the client waited by itself, which counts towards the longest wait. */
+    protected waitedMs: number;
+    constructor(approval: Approval<R>, hooks: AppApprovalHooks<R>);
+    /**
+     * Returns the bank's response once the approval is through. Throws `FinTsTanCancelledError` if the user cancels and
+     * `FinTsDecoupledTimeoutError` if the approval takes too long.
+     */
+    abstract run(): Promise<R>;
+    protected get method(): TanMethod;
+    /** Whether the user may report the approval (PIN/TAN, "Manuelle Bestätigung möglich"). */
+    protected get userConfirms(): boolean;
+    protected get pollIntervalMs(): number;
+    protected get firstPollDelayMs(): number;
+    /**
+     * Sends the next status request and returns the answer, once `receive` has taken it in.
+     *
+     * Throws if the answer reports errors, and `FinTsDecoupledTimeoutError` if the approval is still pending after as
+     * many requests as the bank allows, or after the longest wait.
+     */
+    protected requestStatus(): Promise<R>;
+    /**
+     * `challenge` as the next prompt, with the new instructions of `pending`, the last status answer, where it gives any
+     * (PIN/TAN B.4.2.2.1, step 2b).
+     */
+    protected nextPrompt(challenge: TanChallenge, pending: R): TanChallenge;
+}
+export {};
+//# sourceMappingURL=app-approval.d.ts.map

package/dist/session/app-approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-approval.d.ts","sourceRoot":"","sources":["../../src/session/app-approval.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAA6B,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,oFAAoF;AACpF,UAAU,YAAY;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAYD,uDAAuD;AACvD,KAAK,OAAO,GAAG,CAAC,SAAS,EAAE,YAAY,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;AAE/D,yDAAyD;AACzD,KAAK,KAAK,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E,wHAAwH;AACxH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACzB,eAAe,CAAC,CAAC,CAAC,CAIpB;AAED,8BAAsB,eAAe,CAAC,CAAC,SAAS,YAAY;IAOxD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAP/C,OAAO,CAAC,QAAQ,CAAK;IAErB,mFAAmF;IACnF,SAAS,CAAC,QAAQ,SAAK;gBAGF,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAG/C;;;OAGG;IACH,QAAQ,CAAC,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAE1B,SAAS,KAAK,MAAM,IAAI,SAAS,CAEhC;IAED,0FAA0F;IAC1F,SAAS,KAAK,YAAY,IAAI,OAAO,CAEpC;IAED,SAAS,KAAK,cAAc,IAAI,MAAM,CAMrC;IAED,SAAS,KAAK,gBAAgB,IAAI,MAAM,CAEvC;IAED;;;;;OAKG;cACa,aAAa,IAAI,OAAO,CAAC,CAAC,CAAC;IAe3C;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,GAAG,YAAY;CAGxE"}

package/dist/session/app-approval.js

@@ -0,0 +1,226 @@
+import { FinTsDecoupledTimeoutError, FinTsTanCancelledError } from '../core/errors.js';
+import { FeedbackCodes, hasCode } from '../core/feedback.js';
+import { nextAttempt, withResolved } from '../tan/challenge.js';
+import { Deferred } from '../util/async.js';
+import { invalidArgument } from '../util/errors.js';
+/** How long to wait for an app approval when the bank does not say. */
+const defaultMaxStatusPolls = 60;
+const defaultFirstPollDelayMs = 2_000;
+const defaultPollIntervalMs = 2_000;
+/** Bounds for the bank's polling parameters, against faulty parameter data. */
+const minPollIntervalMs = 1_000;
+const maxPollDelayMs = 60_000;
+const maxApprovalWaitMs = 10 * 60_000;
+/**
+ * Waits for the user to approve a message in the banking app, and for the bank to confirm it (PIN/TAN B.4.2.2).
+ *
+ * The bank's parameters decide who triggers the status requests:
+ * - The client polls by itself while the callback shows the instructions (`PollingWhileShown`) where the bank allows
+ *   automatic status requests and announces no push message (3957), and also where the user cannot report the
+ *   approval: then polling is the one way left to complete it, whatever the other parameters say (step 2a).
+ * - Otherwise the client asks after each report of the user (`PollingAfterReports`), which stands in for the push
+ *   message the client cannot receive.
+ *
+ * The bank's limit on status requests holds either way, and two requests are at least a second apart. One instance
+ * 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(approval, hooks) {
+    const method = approval.challenge.method;
+    const automatic = !method.decoupledManualConfirmation || (method.decoupledAutomaticPolling && !approval.waitForPush);
+    return automatic ? new PollingWhileShown(approval, hooks) : new PollingAfterReports(approval, hooks);
+}
+export class AppApprovalWait {
+    approval;
+    hooks;
+    requests = 0;
+    /** The time the client waited by itself, which counts towards the longest wait. */
+    waitedMs = 0;
+    constructor(approval, hooks) {
+        this.approval = approval;
+        this.hooks = hooks;
+    }
+    get method() {
+        return this.approval.challenge.method;
+    }
+    /** Whether the user may report the approval (PIN/TAN, "Manuelle Bestätigung möglich"). */
+    get userConfirms() {
+        return this.method.decoupledManualConfirmation;
+    }
+    get pollIntervalMs() {
+        return clamp(seconds(this.method.decoupledPollIntervalSeconds) ?? defaultPollIntervalMs, minPollIntervalMs, maxPollDelayMs);
+    }
+    get firstPollDelayMs() {
+        return clamp(seconds(this.method.decoupledFirstPollDelaySeconds) ?? defaultFirstPollDelayMs, 0, maxPollDelayMs);
+    }
+    /**
+     * Sends the next status request and returns the answer, once `receive` has taken it in.
+     *
+     * Throws if the answer reports errors, and `FinTsDecoupledTimeoutError` if the approval is still pending after as
+     * many requests as the bank allows, or after the longest wait.
+     */
+    async requestStatus() {
+        const response = await this.approval.checkStatus();
+        this.requests++;
+        this.hooks.receive(response);
+        // A maximum of 0 allows any number of requests (PIN/TAN, "Maximale Anzahl Statusabfragen Decoupled").
+        const maxRequests = this.method.decoupledMaxPolls ?? defaultMaxStatusPolls;
+        if (isPending(response) &&
+            ((maxRequests > 0 && this.requests >= maxRequests) || this.waitedMs >= maxApprovalWaitMs)) {
+            throw new FinTsDecoupledTimeoutError();
+        }
+        return response;
+    }
+    /**
+     * `challenge` as the next prompt, with the new instructions of `pending`, the last status answer, where it gives any
+     * (PIN/TAN B.4.2.2.1, step 2b).
+     */
+    nextPrompt(challenge, pending) {
+        return nextAttempt(challenge, this.approval.instructionsIn(pending));
+    }
+}
+/**
+ * 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. 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 extends AppApprovalWait {
+    /** Settles when the prompt shown now needs no more answer, which its `TanChallenge.resolved` tells the callback. */
+    shown;
+    /** Settles when the user cancels or the callback fails; `stopReason` holds the error that ends the wait. */
+    stopped = new Deferred();
+    stopReason;
+    /** Settles when the user reports the approval in the prompt shown now; `undefined` once the report was used. */
+    report;
+    async run() {
+        let challenge = this.approval.challenge;
+        this.show(challenge);
+        try {
+            await this.sleep(this.firstPollDelayMs);
+            for (;;) {
+                this.throwIfStopped();
+                // A request under way is awaited even when the user cancels meanwhile; its answer counts.
+                const response = await this.requestStatus();
+                if (!isPending(response))
+                    return response;
+                this.throwIfStopped();
+                // 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.shown?.resolve();
+        }
+    }
+    /** Shows `challenge` in place of the prompt before, without waiting for the answer. */
+    show(challenge) {
+        this.shown?.resolve();
+        const shown = (this.shown = new Deferred());
+        const report = (this.report = this.userConfirms ? new Deferred() : undefined);
+        // 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) => {
+            if (!shown.isCompleted)
+                this.stop(error);
+        });
+    }
+    stop(error) {
+        if (this.stopped.isCompleted)
+            return;
+        this.stopReason = { error };
+        this.stopped.resolve();
+    }
+    throwIfStopped() {
+        if (this.stopReason !== undefined)
+            throw this.stopReason.error;
+    }
+    /**
+     * Waits for `delayMs`, or until the user cancels or reports the approval; a report does not cut the wait below
+     * `floorMs`. A wait cut short counts towards the longest wait with its floor only.
+     */
+    async sleep(delayMs, floorMs = 0) {
+        const report = this.report;
+        if (floorMs > 0)
+            await this.hooks.pause(floorMs, this.stopped.promise);
+        const interrupt = report === undefined ? this.stopped.promise : Promise.race([this.stopped.promise, report.promise]);
+        await this.hooks.pause(delayMs - floorMs, interrupt);
+        const cutShort = report?.isCompleted ?? false;
+        this.waitedMs += cutShort ? floorMs : delayMs;
+        // One report, one early request.
+        if (cutShort)
+            this.report = undefined;
+    }
+}
+/**
+ * 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 extends AppApprovalWait {
+    async run() {
+        let challenge = this.approval.challenge;
+        await this.confirm(challenge);
+        for (;;) {
+            const response = await this.requestStatus();
+            if (!isPending(response))
+                return response;
+            challenge = this.nextPrompt(challenge, response);
+            // The prompt comes back at once; however fast the user reports again, the next request waits a second.
+            await Promise.all([this.confirm(challenge), this.hooks.pause(minPollIntervalMs)]);
+            this.waitedMs += minPollIntervalMs;
+        }
+    }
+    /** Shows `challenge` and waits until the user reports the approval or cancels. */
+    async confirm(challenge) {
+        const answer = await this.hooks.ask(challenge);
+        switch (answer.kind) {
+            case 'approved':
+                return;
+            case 'cancelled':
+                throw new FinTsTanCancelledError();
+            case 'tan':
+                throw tanForApproval();
+        }
+    }
+}
+/** Whether `response` tells that the approval is still pending (return code 3956). */
+function isPending(response) {
+    return hasCode(response.feedback, FeedbackCodes.decoupledStillPending);
+}
+function tanForApproval() {
+    return invalidArgument('Answered an approval in the banking app with a TAN', 'tanCallback');
+}
+function seconds(value) {
+    return value === undefined ? undefined : value * 1000;
+}
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+//# sourceMappingURL=app-approval.js.map

package/dist/session/app-approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-approval.js","sourceRoot":"","sources":["../../src/session/app-approval.ts"],"names":[],"mappings":"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"}

package/dist/session/dialog-runner.d.ts

@@ -0,0 +1,31 @@
+import type { Query } from '../v3/queries.js';
+import type { SessionSetup } from './session-setup.js';
+import type { SignedDialog } from './signed-dialog.js';
+/**
+ * Keeps one dialog open for all calls and runs the queries in it.
+ *
+ * A dialog the bank has ended is not used again: the call that learns of it fails, and the next call logs in anew. The
+ * 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 declare class DialogRunner {
+    private readonly setup;
+    private dialog;
+    constructor(setup: SessionSetup);
+    /** The open dialog, or a new one once the setup is complete and the user has passed strong authentication. */
+    open(): Promise<SignedDialog>;
+    private login;
+    /** Ends the open dialog, if there is one. */
+    end(): Promise<void>;
+    /**
+     * Runs the query `build` returns in the session's dialog and reads all its pages.
+     *
+     * The query is built once the dialog is open, since building it takes the parameter data.
+     */
+    query<T>(build: () => Query<T>): Promise<T>;
+    /** Sends `order` in `dialog` and completes its approval, which only the `firstPage` of a query may ask for. */
+    private run;
+    /** Sends the order built by `order` until the bank has delivered all pages (Formals B.6.3, "Aufsetzpunkt"). */
+    private fetchPages;
+}
+//# sourceMappingURL=dialog-runner.d.ts.map

package/dist/session/dialog-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog-runner.d.ts","sourceRoot":"","sources":["../../src/session/dialog-runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYvD;;;;;;GAMG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,MAAM,CAA2B;gBAEZ,KAAK,EAAE,YAAY;IAEhD,8GAA8G;IACxG,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC;YASrB,KAAK;IAanB,6CAA6C;IACvC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1B;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAOjD,+GAA+G;YACjG,GAAG;IAYjB,+GAA+G;YACjG,UAAU;CAmCzB"}

package/dist/session/dialog-runner.js

@@ -0,0 +1,111 @@
+import { FinTsBankError, FinTsProtocolError, parseBankData } from '../core/errors.js';
+import { continuations, FeedbackCodes, hasCode } from '../core/feedback.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 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;
+/**
+ * Keeps one dialog open for all calls and runs the queries in it.
+ *
+ * A dialog the bank has ended is not used again: the call that learns of it fails, and the next call logs in anew. The
+ * 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 {
+    setup;
+    dialog;
+    constructor(setup) {
+        this.setup = setup;
+    }
+    /** The open dialog, or a new one once the setup is complete and the user has passed strong authentication. */
+    async open() {
+        const current = this.dialog;
+        if (current?.isActive === true)
+            return current;
+        this.dialog = undefined;
+        const dialog = await this.setup.remedied(() => this.login());
+        this.dialog = dialog;
+        return dialog;
+    }
+    async login() {
+        const dialog = await this.setup.newDialog();
+        try {
+            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,
+            // such as a cancelled TAN, the bank still knows the dialog.
+            await dialog.end();
+            throw error;
+        }
+    }
+    /** Ends the open dialog, if there is one. */
+    async end() {
+        const dialog = this.dialog;
+        this.dialog = undefined;
+        await dialog?.end();
+    }
+    /**
+     * Runs the query `build` returns in the session's dialog and reads all its pages.
+     *
+     * The query is built once the dialog is open, since building it takes the parameter data.
+     */
+    async query(build) {
+        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, which only the `firstPage` of a query may ask for. */
+    async run(dialog, order, firstPage) {
+        try {
+            return firstPage ? await dialog.send(order) : await dialog.sendFurtherPage(order);
+        }
+        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.
+            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"). */
+    async fetchPages(dialog, order) {
+        const pages = [];
+        const seen = new Set();
+        let size = 0;
+        let continuation;
+        for (;;) {
+            const page = await this.run(dialog, order(continuation), continuation === undefined);
+            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');
+            continuation = positions[0];
+            if (continuation === undefined) {
+                // Read as the last page, more data without a position would look like all there is.
+                if (hasCode(page.feedback, FeedbackCodes.moreData)) {
+                    throw new FinTsProtocolError('The bank has more data, but names no position to continue at');
+                }
+                return pages;
+            }
+            // 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);
+        }
+    }
+}
+//# sourceMappingURL=dialog-runner.js.map

package/dist/session/dialog-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog-runner.js","sourceRoot":"","sources":["../../src/session/dialog-runner.ts"],"names":[],"mappings":"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"}