@coderoftime/fints 0.0.0-stage → 0.1.0

package/dist/session/tan-selection.d.ts

@@ -0,0 +1,88 @@
+import { TanMethod, type TanMedium } from '../tan/tan-models.js';
+import { type BankResponse, type PinTanProtocol, type ProtocolDialog } from './protocol.js';
+import type { SessionState } from './session-state.js';
+import type { UserPrompts } from './user-prompts.js';
+/**
+ * The TAN method and medium the session's messages are signed with, chosen by the user among what the bank offers and
+ * the user may use, and kept in the session state.
+ */
+export declare class TanSelection<R extends BankResponse, O> {
+    private readonly protocol;
+    private readonly state;
+    private readonly prompts;
+    /** TAN methods whose media were looked up in this session. A lookup is not repeated, even where it gave no medium. */
+    private readonly mediaLookedUp;
+    /** The list the last lookup gave, until `takeLookedUpMedia` hands it out. */
+    private lookedUpMedia;
+    /** Whether the bank refused a login signed with the one-step method in this session. */
+    private oneStepRefused;
+    constructor(protocol: PinTanProtocol<R, O>, state: SessionState, prompts: UserPrompts);
+    /** The TAN method in use; the one-step method until one is chosen. */
+    get method(): TanMethod;
+    /** Switches to `securityFunction` and `tanMedium` for the dialogs to come. */
+    select(securityFunction: string, tanMedium: string | undefined): void;
+    /**
+     * A dialog signed with the TAN method in use and its medium.
+     *
+     * Throws `FinTsUnsupportedError` if the method needs a medium the user has not chosen: the bank would refuse the
+     * login, and the client would not send the PIN again.
+     */
+    newDialog(): ProtocolDialog<R, O>;
+    /**
+     * The dialog that looks up the TAN media, signed with the TAN method in use.
+     *
+     * It runs before the medium is known, so it names a placeholder where the method needs one; the bank ignores the
+     * medium in this dialog (PIN/TAN B.4.3.1.3).
+     */
+    lookupDialog(): ProtocolDialog<R, O>;
+    /**
+     * The synchronization dialog. It runs before the TAN media are looked up, so its method must do without a medium the
+     * user has not chosen: the placeholder for one is meant for the lookup only (PIN/TAN B.4.3.1.3). The first method
+     * that does signs it:
+     * 1. the TAN method in use;
+     * 2. the one-step method, as for a user whose methods are not known yet (PIN/TAN B.4.3.1), unless the bank has refused
+     *    a one-step login;
+     * 3. another two-step method the user may use.
+     *
+     * Throws `FinTsUnsupportedError` if none does, before the bank could refuse the login.
+     */
+    synchronizationDialog(): ProtocolDialog<R, O>;
+    /** Whether `method` needs a medium the user has not chosen. */
+    private lacksMedium;
+    /**
+     * The two-step TAN methods the bank offers, the user may use and this client can run; the one-step method if there
+     * are none.
+     *
+     * Throws `FinTsUnsupportedError` if the bank offers the user nothing but methods the client cannot run.
+     */
+    available(): TanMethod[];
+    /**
+     * Stops using `rejected`, the method of a login the bank refused; returns whether another available method is left.
+     *
+     * The user chooses that method, unless the one in use is still available: a refused one-step synchronization does
+     * not rule out the method the user chose before.
+     */
+    replace(rejected: TanMethod): Promise<boolean>;
+    /** Keeps the chosen TAN method if it is still available, otherwise lets the user choose. */
+    ensureMethodChosen(): Promise<void>;
+    /**
+     * Whether the media of the method in use have to be looked up: it needs a medium the user has not chosen, and they
+     * were not looked up for it in this session.
+     */
+    get mediumToLookUp(): boolean;
+    /**
+     * Lets the user choose the medium of the method in use among the active ones in `media`, the result of a lookup;
+     * none where the lookup gave no list or no active medium.
+     */
+    chooseMedium(media: TanMedium[] | undefined): Promise<void>;
+    /**
+     * The list of the last lookup, once; `undefined` if there was none since the last time.
+     *
+     * `getTanMedia` takes it, so that the list is not asked for twice in a row. It also outlasts a call that failed for
+     * want of an active medium, so that the app can show the user the list that tells why; later calls ask anew.
+     */
+    takeLookedUpMedia(): TanMedium[] | undefined;
+    /** The name of the medium the user chooses among the active ones in `media`; `undefined` if none is active. */
+    private chooseMediumOf;
+}
+//# sourceMappingURL=tan-selection.d.ts.map

package/dist/session/tan-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tan-selection.d.ts","sourceRoot":"","sources":["../../src/session/tan-selection.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAe,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;GAGG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,CAAC;IAW/C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZ1B,sHAAsH;IACtH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD,6EAA6E;IAC7E,OAAO,CAAC,aAAa,CAA0B;IAE/C,wFAAwF;IACxF,OAAO,CAAC,cAAc,CAAS;gBAGZ,QAAQ,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,WAAW;IAGvC,sEAAsE;IACtE,IAAI,MAAM,IAAI,SAAS,CAItB;IAED,8EAA8E;IAC9E,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAKrE;;;;;OAKG;IACH,SAAS,IAAI,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAYjC;;;;;OAKG;IACH,YAAY,IAAI,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAKpC;;;;;;;;;;OAUG;IACH,qBAAqB,IAAI,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAY7C,+DAA+D;IAC/D,OAAO,CAAC,WAAW;IAInB;;;;;OAKG;IACH,SAAS,IAAI,SAAS,EAAE;IAgBxB;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IASpD,4FAA4F;IACtF,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAQzC;;;OAGG;IACH,IAAI,cAAc,IAAI,OAAO,CAG5B;IAED;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjE;;;;;OAKG;IACH,iBAAiB,IAAI,SAAS,EAAE,GAAG,SAAS;IAM5C,+GAA+G;YACjG,cAAc;CAQ7B"}

package/dist/session/tan-selection.js

@@ -0,0 +1,178 @@
+import { FinTsUnsupportedError } from '../core/errors.js';
+import { TanMethod } from '../tan/tan-models.js';
+import { noReference } from './protocol.js';
+/**
+ * The TAN method and medium the session's messages are signed with, chosen by the user among what the bank offers and
+ * the user may use, and kept in the session state.
+ */
+export class TanSelection {
+    protocol;
+    state;
+    prompts;
+    /** TAN methods whose media were looked up in this session. A lookup is not repeated, even where it gave no medium. */
+    mediaLookedUp = new Set();
+    /** The list the last lookup gave, until `takeLookedUpMedia` hands it out. */
+    lookedUpMedia;
+    /** Whether the bank refused a login signed with the one-step method in this session. */
+    oneStepRefused = false;
+    constructor(protocol, state, prompts) {
+        this.protocol = protocol;
+        this.state = state;
+        this.prompts = prompts;
+    }
+    /** The TAN method in use; the one-step method until one is chosen. */
+    get method() {
+        const code = this.state.tanMethod;
+        if (code === undefined || code === TanMethod.oneStep.securityFunction)
+            return TanMethod.oneStep;
+        return this.protocol.bankParameters?.tanMethods.find((m) => m.securityFunction === code) ?? TanMethod.oneStep;
+    }
+    /** Switches to `securityFunction` and `tanMedium` for the dialogs to come. */
+    select(securityFunction, tanMedium) {
+        this.state.useTanMethod(securityFunction, tanMedium);
+        this.mediaLookedUp.delete(securityFunction);
+    }
+    /**
+     * A dialog signed with the TAN method in use and its medium.
+     *
+     * Throws `FinTsUnsupportedError` if the method needs a medium the user has not chosen: the bank would refuse the
+     * login, and the client would not send the PIN again.
+     */
+    newDialog() {
+        const method = this.method;
+        if (this.lacksMedium(method)) {
+            throw new FinTsUnsupportedError(`The TAN method ${method.name} needs a TAN medium, and the client could not learn one: the bank lists no ` +
+                'active medium for it, or does not offer or permit the list of TAN media, or rejected it. Pass a medium to ' +
+                'selectTanMethod, or choose another method');
+        }
+        return this.protocol.newDialog(method, this.state.tanMedium);
+    }
+    /**
+     * The dialog that looks up the TAN media, signed with the TAN method in use.
+     *
+     * It runs before the medium is known, so it names a placeholder where the method needs one; the bank ignores the
+     * medium in this dialog (PIN/TAN B.4.3.1.3).
+     */
+    lookupDialog() {
+        const method = this.method;
+        return this.protocol.newDialog(method, this.lacksMedium(method) ? noReference : this.state.tanMedium);
+    }
+    /**
+     * The synchronization dialog. It runs before the TAN media are looked up, so its method must do without a medium the
+     * user has not chosen: the placeholder for one is meant for the lookup only (PIN/TAN B.4.3.1.3). The first method
+     * that does signs it:
+     * 1. the TAN method in use;
+     * 2. the one-step method, as for a user whose methods are not known yet (PIN/TAN B.4.3.1), unless the bank has refused
+     *    a one-step login;
+     * 3. another two-step method the user may use.
+     *
+     * Throws `FinTsUnsupportedError` if none does, before the bank could refuse the login.
+     */
+    synchronizationDialog() {
+        const method = this.method;
+        if (!this.lacksMedium(method))
+            return this.protocol.newDialog(method, this.state.tanMedium);
+        if (!this.oneStepRefused)
+            return this.protocol.newDialog(TanMethod.oneStep);
+        const other = this.available().find((m) => !m.isOneStep && !this.lacksMedium(m));
+        if (other !== undefined)
+            return this.protocol.newDialog(other);
+        throw new FinTsUnsupportedError(`The bank refuses the one-step method, and the TAN method ${method.name} needs a TAN medium, which the client ` +
+            'can look up only after the synchronization. Pass the medium to selectTanMethod, or choose another method');
+    }
+    /** Whether `method` needs a medium the user has not chosen. */
+    lacksMedium(method) {
+        return this.state.tanMedium === undefined && needsMediumChoice(method);
+    }
+    /**
+     * The two-step TAN methods the bank offers, the user may use and this client can run; the one-step method if there
+     * are none.
+     *
+     * Throws `FinTsUnsupportedError` if the bank offers the user nothing but methods the client cannot run.
+     */
+    available() {
+        const bpd = this.protocol.bankParameters;
+        if (bpd === undefined)
+            return [TanMethod.oneStep];
+        const allowed = this.state.allowedMethods ?? this.protocol.userParameters?.allowedTanMethods;
+        const isAllowed = (securityFunction) => allowed === undefined || allowed.length === 0 || allowed.includes(securityFunction);
+        const runnable = bpd.tanMethods.filter((m) => isAllowed(m.securityFunction));
+        if (runnable.length === 0 && bpd.unsupportedTanMethods.some(isAllowed)) {
+            throw new FinTsUnsupportedError('The bank offers only TAN methods this client cannot run: process variant 1, or methods that need an SMS ' +
+                'charge account or an HHD_UC answer');
+        }
+        return runnable.length === 0 ? [TanMethod.oneStep] : runnable;
+    }
+    /**
+     * Stops using `rejected`, the method of a login the bank refused; returns whether another available method is left.
+     *
+     * The user chooses that method, unless the one in use is still available: a refused one-step synchronization does
+     * not rule out the method the user chose before.
+     */
+    async replace(rejected) {
+        if (rejected.isOneStep)
+            this.oneStepRefused = true;
+        const others = this.available().filter((m) => m.securityFunction !== rejected.securityFunction);
+        if (others.some((m) => m.securityFunction === this.state.tanMethod))
+            return true;
+        if (others.length === 0)
+            return false;
+        this.state.useTanMethod((await this.prompts.chooseMethod(others)).securityFunction);
+        return true;
+    }
+    /** Keeps the chosen TAN method if it is still available, otherwise lets the user choose. */
+    async ensureMethodChosen() {
+        const candidates = this.available();
+        const method = candidates.find((m) => m.securityFunction === this.state.tanMethod) ??
+            (await this.prompts.chooseMethod(candidates));
+        if (method.securityFunction !== this.state.tanMethod)
+            this.state.useTanMethod(method.securityFunction);
+    }
+    /**
+     * Whether the media of the method in use have to be looked up: it needs a medium the user has not chosen, and they
+     * were not looked up for it in this session.
+     */
+    get mediumToLookUp() {
+        const method = this.method;
+        return this.lacksMedium(method) && !this.mediaLookedUp.has(method.securityFunction);
+    }
+    /**
+     * Lets the user choose the medium of the method in use among the active ones in `media`, the result of a lookup;
+     * none where the lookup gave no list or no active medium.
+     */
+    async chooseMedium(media) {
+        const method = this.method;
+        this.lookedUpMedia = media;
+        this.state.useTanMedium(media === undefined ? undefined : await this.chooseMediumOf(method, media));
+        this.mediaLookedUp.add(method.securityFunction);
+    }
+    /**
+     * The list of the last lookup, once; `undefined` if there was none since the last time.
+     *
+     * `getTanMedia` takes it, so that the list is not asked for twice in a row. It also outlasts a call that failed for
+     * want of an active medium, so that the app can show the user the list that tells why; later calls ask anew.
+     */
+    takeLookedUpMedia() {
+        const media = this.lookedUpMedia;
+        this.lookedUpMedia = undefined;
+        return media;
+    }
+    /** The name of the medium the user chooses among the active ones in `media`; `undefined` if none is active. */
+    async chooseMediumOf(method, media) {
+        const active = media.filter((m) => m.isActive && m.name !== undefined);
+        // HITAB version 5 names the method each medium belongs to; a medium of another method would not do.
+        const ofMethod = active.filter((m) => m.securityFunction === method.securityFunction);
+        const candidates = ofMethod.length === 0 ? active : ofMethod;
+        if (candidates.length === 0)
+            return undefined;
+        return (await this.prompts.chooseMedium(candidates)).name;
+    }
+}
+/**
+ * Whether messages signed with `method` must name the TAN medium: the method requires the name, and the user may have
+ * several media (PIN/TAN, HKTAN "Bezeichnung des TAN-Mediums").
+ */
+function needsMediumChoice(method) {
+    return method.needsMediumName && (method.activeMediaCount ?? 0) > 1;
+}
+//# sourceMappingURL=tan-selection.js.map

package/dist/session/tan-selection.js.map

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

package/dist/session/user-prompts.d.ts

@@ -0,0 +1,61 @@
+import type { BankMessage } from '../core/bank-info.js';
+import type { FinTsClientOptions, MessageLogger } from '../core/client.js';
+import type { FinTsFeedback } from '../core/feedback.js';
+import type { TanAnswer, TanChallenge } from '../tan/challenge.js';
+import type { TanMedium, TanMethod } from '../tan/tan-models.js';
+/**
+ * Everything a session tells the app, asks of it or waits for: the bank's messages, warnings and log, the TAN callback,
+ * the selectors and the pauses between status requests.
+ *
+ * Once the client is closed nothing is told or asked, and every wait ends with `FinTsStateError`. Errors of the
+ * callbacks that only inform the app wait for `reportingCallbackErrors`, as `FinTsClientOptions` promises.
+ */
+export declare class UserPrompts {
+    private readonly options;
+    private closed;
+    /** The first error an informing callback threw during the running call. */
+    private callbackError;
+    /** Aborts the waits under way; each wait removes its abort when it is over. */
+    private readonly aborts;
+    constructor(options: FinTsClientOptions);
+    /** Ends every wait; the client calls it once. */
+    close(): void;
+    /** Throws `FinTsStateError` once `close` was called. */
+    checkOpen(): void;
+    /**
+     * Runs `call` and then fails it with the first error an informing callback threw meanwhile; an error of `call` itself
+     * takes precedence.
+     */
+    reportingCallbackErrors<T>(call: () => Promise<T>): Promise<T>;
+    /** The app's logger, whose errors are kept for `reportingCallbackErrors`; `undefined` without one. */
+    get logger(): MessageLogger | undefined;
+    /** Passes the bank's `message` to the app, unless the client is closed. */
+    showBankMessage(message: BankMessage): void;
+    /** Passes the bank's `warning` to the app, unless the client is closed. */
+    showWarning(warning: FinTsFeedback): void;
+    private inform;
+    /** Shows `challenge` through the TAN callback and returns its answer. */
+    askTan(challenge: TanChallenge): Promise<TanAnswer>;
+    /** Waits for `delayMs` milliseconds, or until `interrupt` settles. */
+    pause(delayMs: number, interrupt?: Promise<unknown>): Promise<void>;
+    /**
+     * The TAN method to use among `candidates`: the app's choice, or the first without a selector or an answer.
+     *
+     * Throws `TypeError` if the selector returns a method that is not among `candidates`.
+     */
+    chooseMethod(candidates: readonly TanMethod[]): Promise<TanMethod>;
+    /**
+     * The TAN medium to use among the active `media`: the app's choice, or the first without a selector or an answer.
+     *
+     * Throws `TypeError` if the selector returns a medium that is not among `media`.
+     */
+    chooseMedium(media: readonly TanMedium[]): Promise<TanMedium>;
+    /**
+     * Starts `wait` and ends it with `FinTsStateError` if `close` is called before it is over.
+     *
+     * Once the client is closed, the returned promise rejects rather than this function throwing: a caller that starts
+     * several waits at once would otherwise leave the failure of those started first unheard.
+     */
+    private unlessClosed;
+}
+//# sourceMappingURL=user-prompts.d.ts.map

package/dist/session/user-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-prompts.d.ts","sourceRoot":"","sources":["../../src/session/user-prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAQjE;;;;;;GAMG;AACH,qBAAa,WAAW;IASV,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,MAAM,CAAS;IAEvB,2EAA2E;IAC3E,OAAO,CAAC,aAAa,CAAiC;IAEtD,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;gBAEnB,OAAO,EAAE,kBAAkB;IAExD,iDAAiD;IACjD,KAAK,IAAI,IAAI;IAMb,wDAAwD;IACxD,SAAS,IAAI,IAAI;IAIjB;;;OAGG;IACG,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASpE,sGAAsG;IACtG,IAAI,MAAM,IAAI,aAAa,GAAG,SAAS,CAQtC;IAED,2EAA2E;IAC3E,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAS3C,2EAA2E;IAC3E,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IASzC,OAAO,CAAC,MAAM;IAQd,yEAAyE;IACzE,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IAInD,sEAAsE;IACtE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnE;;;;OAIG;IACG,YAAY,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAUxE;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAUnE;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CAsBrB"}

package/dist/session/user-prompts.js

@@ -0,0 +1,164 @@
+import { FinTsStateError } from '../core/errors.js';
+import { Deferred } from '../util/async.js';
+import { invalidArgument } from '../util/errors.js';
+function closedError() {
+    return new FinTsStateError('The FinTS client is closed');
+}
+/**
+ * Everything a session tells the app, asks of it or waits for: the bank's messages, warnings and log, the TAN callback,
+ * the selectors and the pauses between status requests.
+ *
+ * Once the client is closed nothing is told or asked, and every wait ends with `FinTsStateError`. Errors of the
+ * callbacks that only inform the app wait for `reportingCallbackErrors`, as `FinTsClientOptions` promises.
+ */
+export class UserPrompts {
+    options;
+    closed = false;
+    /** The first error an informing callback threw during the running call. */
+    callbackError;
+    /** Aborts the waits under way; each wait removes its abort when it is over. */
+    aborts = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Ends every wait; the client calls it once. */
+    close() {
+        this.closed = true;
+        for (const abort of [...this.aborts])
+            abort();
+        this.aborts.clear();
+    }
+    /** Throws `FinTsStateError` once `close` was called. */
+    checkOpen() {
+        if (this.closed)
+            throw closedError();
+    }
+    /**
+     * Runs `call` and then fails it with the first error an informing callback threw meanwhile; an error of `call` itself
+     * takes precedence.
+     */
+    async reportingCallbackErrors(call) {
+        this.callbackError = undefined;
+        const result = await call();
+        // Set by a callback while `call` ran, which the compiler cannot see.
+        const failure = this.callbackError;
+        if (failure !== undefined)
+            throw failure.error;
+        return result;
+    }
+    /** The app's logger, whose errors are kept for `reportingCallbackErrors`; `undefined` without one. */
+    get logger() {
+        const logger = this.options.logger;
+        if (logger === undefined)
+            return undefined;
+        return (direction, message) => {
+            this.inform(() => {
+                logger(direction, message);
+            });
+        };
+    }
+    /** Passes the bank's `message` to the app, unless the client is closed. */
+    showBankMessage(message) {
+        const handler = this.options.onBankMessage;
+        if (handler !== undefined && !this.closed) {
+            this.inform(() => {
+                handler(message);
+            });
+        }
+    }
+    /** Passes the bank's `warning` to the app, unless the client is closed. */
+    showWarning(warning) {
+        const handler = this.options.onWarning;
+        if (handler !== undefined && !this.closed) {
+            this.inform(() => {
+                handler(warning);
+            });
+        }
+    }
+    inform(callback) {
+        try {
+            callback();
+        }
+        catch (error) {
+            this.callbackError ??= { error };
+        }
+    }
+    /** Shows `challenge` through the TAN callback and returns its answer. */
+    askTan(challenge) {
+        return this.unlessClosed(() => this.options.tanCallback(challenge));
+    }
+    /** Waits for `delayMs` milliseconds, or until `interrupt` settles. */
+    pause(delayMs, interrupt) {
+        if (this.closed)
+            return Promise.reject(closedError());
+        let timer;
+        const elapsed = new Promise((resolve) => {
+            timer = setTimeout(resolve, Math.max(0, delayMs));
+        });
+        // Neither an interrupted wait nor a closed client may leave a timer behind that keeps the process alive.
+        return this.unlessClosed(() => Promise.race([elapsed, ...(interrupt === undefined ? [] : [interrupt.then(() => undefined)])])).finally(() => {
+            clearTimeout(timer);
+        });
+    }
+    /**
+     * The TAN method to use among `candidates`: the app's choice, or the first without a selector or an answer.
+     *
+     * Throws `TypeError` if the selector returns a method that is not among `candidates`.
+     */
+    async chooseMethod(candidates) {
+        const selector = this.options.tanMethodSelector;
+        if (candidates.length === 1 || selector === undefined)
+            return candidates[0];
+        const chosen = await this.unlessClosed(() => selector(candidates));
+        if (chosen === undefined)
+            return candidates[0];
+        const match = candidates.find((m) => m.securityFunction === chosen.securityFunction);
+        if (match === undefined)
+            throw invalidArgument('Returned a TAN method the bank did not offer', 'tanMethodSelector');
+        return match;
+    }
+    /**
+     * The TAN medium to use among the active `media`: the app's choice, or the first without a selector or an answer.
+     *
+     * Throws `TypeError` if the selector returns a medium that is not among `media`.
+     */
+    async chooseMedium(media) {
+        const selector = this.options.tanMediumSelector;
+        if (media.length === 1 || selector === undefined)
+            return media[0];
+        const chosen = await this.unlessClosed(() => selector(media));
+        if (chosen === undefined)
+            return media[0];
+        const match = media.find((m) => m.name === chosen.name);
+        if (match === undefined)
+            throw invalidArgument('Returned a TAN medium the bank did not list', 'tanMediumSelector');
+        return match;
+    }
+    /**
+     * Starts `wait` and ends it with `FinTsStateError` if `close` is called before it is over.
+     *
+     * Once the client is closed, the returned promise rejects rather than this function throwing: a caller that starts
+     * several waits at once would otherwise leave the failure of those started first unheard.
+     */
+    unlessClosed(wait) {
+        if (this.closed)
+            return Promise.reject(closedError());
+        const result = new Deferred();
+        const abort = () => {
+            result.reject(closedError());
+        };
+        this.aborts.add(abort);
+        // Runs `wait` at once, as far as its first `await`, and turns an error it throws into a rejection.
+        const started = (async () => wait())();
+        started
+            .then((value) => {
+            result.resolve(value);
+        }, (error) => {
+            result.reject(error);
+        })
+            .finally(() => this.aborts.delete(abort))
+            .catch(() => undefined);
+        return result.promise;
+    }
+}
+//# sourceMappingURL=user-prompts.js.map

package/dist/session/user-prompts.js.map

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

package/dist/tan/challenge.d.ts

@@ -0,0 +1,114 @@
+import { FlickerCode } from './flicker.js';
+import { TanImage } from './tan-image.js';
+import type { TanMedium, TanMethod } from './tan-models.js';
+/** `message`, or `undefined` where it is empty or the filler banks send when there is nothing to show. */
+export declare function challengeText(message: string | undefined): string | undefined;
+/** What `TanChallenge` takes. */
+export interface TanChallengeInit {
+    method: TanMethod;
+    reference: string;
+    message?: string | undefined;
+    hhdUc?: Uint8Array | undefined;
+    flickerCode?: FlickerCode | undefined;
+    image?: TanImage | undefined;
+    isDecoupled?: boolean;
+    validUntil?: Date | undefined;
+    tanMediumName?: string | undefined;
+    attempt?: number;
+    resolved?: Promise<void> | undefined;
+}
+/** A request from the bank to authorize an action with a TAN or an app approval. */
+export declare class TanChallenge {
+    /** The TAN method the challenge is for. */
+    readonly method: TanMethod;
+    /** Bank reference of the pending action. */
+    readonly reference: string;
+    /** Challenge text as sent by the bank; may contain simple HTML. See `plainMessage`. */
+    readonly message: string | undefined;
+    /** Raw challenge data for TAN generators (HHD_UC). */
+    readonly hhdUc: Uint8Array | undefined;
+    /** chipTAN optical flicker code, if the challenge contains one. */
+    readonly flickerCode: FlickerCode | undefined;
+    /** photoTAN / QR-TAN image, if the challenge contains one. */
+    readonly image: TanImage | undefined;
+    /** Approval happens in a separate app; see `TanCallback` for what to answer. */
+    readonly isDecoupled: boolean;
+    /** The exact moment until which the bank accepts the TAN or the approval, where it states date and time of day. */
+    readonly validUntil: Date | undefined;
+    /** Name of the TAN medium the bank sent the challenge to. */
+    readonly tanMediumName: string | undefined;
+    /** Counts repeated prompts for the same decoupled approval. */
+    readonly attempt: number;
+    /**
+     * Settles when the client needs no more answer to this challenge: the bank confirmed the approval, or the approval
+     * failed, timed out or was cancelled. Set where the client asks the bank by itself while the callback shows the
+     * challenge (`TanCallback`), `undefined` otherwise. It never rejects.
+     */
+    readonly resolved: Promise<void> | undefined;
+    /** A challenge as the bank sent it. Use `TanChallenge.create` to have a flicker code or image detected in the data. */
+    constructor(init: TanChallengeInit);
+    /** Builds a challenge and detects a photoTAN image or chipTAN flicker code in `hhdUc` or `message`. */
+    static create(init: Omit<TanChallengeInit, 'flickerCode' | 'image' | 'resolved'>): TanChallenge;
+    /**
+     * Whether the user can report the approval in the banking app; `false` where only the bank's confirmation completes
+     * it, which `TanCallback` tells how to handle.
+     */
+    get manualConfirmation(): boolean;
+    /**
+     * `message` as the user reads it.
+     *
+     * A method with structured challenges (`TanMethod.structuredChallenge`) may use the formatting tags the specification
+     * defines. Line breaks, paragraphs and list items become new lines. Bold, italics, underlining and list tags are
+     * removed, and the entity references of such markup are resolved. Any other challenge stays as the bank sent it,
+     * which is how the specification wants it shown.
+     */
+    get plainMessage(): string | undefined;
+}
+/** `challenge` again, counted as the next prompt for the same approval, with the bank's new instructions `message`. */
+export declare function nextAttempt(challenge: TanChallenge, message?: string): TanChallenge;
+/** `challenge` with `TanChallenge.resolved` set to `resolved`. */
+export declare function withResolved(challenge: TanChallenge, resolved: Promise<void>): TanChallenge;
+/** The user's answer to a `TanChallenge`: `TanAnswer.tan(…)`, `TanAnswer.approved` or `TanAnswer.cancelled`. */
+export type TanAnswer = 
+/** The TAN the user entered; an empty one cancels. */
+{
+    readonly kind: 'tan';
+    readonly tan: string;
+}
+/** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+ | {
+    readonly kind: 'approved';
+}
+/** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+ | {
+    readonly kind: 'cancelled';
+};
+/** The answers a `TanCallback` returns. */
+export declare const TanAnswer: Readonly<{
+    /** The TAN the user entered; an empty one cancels. */
+    tan: (tan: string) => TanAnswer;
+    /** The user reports the approval in the banking app (`TanChallenge.isDecoupled`); the client then asks the bank. */
+    approved: {
+        readonly kind: "approved";
+    };
+    /** The user cancels: the client ends the bank dialog, and the call fails with `FinTsTanCancelledError`. */
+    cancelled: {
+        readonly kind: "cancelled";
+    };
+}>;
+/**
+ * Shows the `TanChallenge` to the user and returns the `TanAnswer`: `TanAnswer.tan(…)` for a TAN, `TanAnswer.approved`
+ * once the user reports an approval in the banking app (`TanChallenge.isDecoupled`), `TanAnswer.cancelled` to cancel
+ * either. An answer that does not fit the challenge fails the call with a `TypeError`.
+ *
+ * Where the client polls the bank by itself, it sets `TanChallenge.resolved`: close the prompt when it settles, the
+ * callback's result is no longer waited for then. If the bank has not confirmed a reported approval yet, the callback is
+ * called again with the next `TanChallenge.attempt`. Where `TanChallenge.manualConfirmation` is `false`, offer no
+ * confirm button: any answer but `TanAnswer.cancelled` is ignored.
+ */
+export type TanCallback = (challenge: TanChallenge) => TanAnswer | Promise<TanAnswer>;
+/** Picks one of several allowed TAN methods; the first is used when this returns `undefined`. */
+export type TanMethodSelector = (methods: readonly TanMethod[]) => TanMethod | undefined | Promise<TanMethod | undefined>;
+/** Picks one of several active TAN media; the first is used when this returns `undefined`. */
+export type TanMediumSelector = (media: readonly TanMedium[]) => TanMedium | undefined | Promise<TanMedium | undefined>;
+//# sourceMappingURL=challenge.d.ts.map

package/dist/tan/challenge.d.ts.map

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