@coderoftime/fints 0.1.0 → 0.2.0

package/src/session/sepa-accounts.ts

@@ -1,55 +1,85 @@
-import type { Account } from '../core/account.js';
-import { FinTsDialogAbortedError } from '../core/errors.js';
+import { Account, AccountIndex } from '../core/account.js';
+import { FinTsUnsupportedError, tryLookUp } from '../core/errors.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import { sepaAccountsQuery } from '../v3/queries.js';
 import type { DialogRunner } from './dialog-runner.js';
-import type { LoginGuard } from './login-guard.js';
-import type { BankResponse, PinTanProtocol } from './protocol.js';
 import type { SessionState } from './session-state.js';
 
 /**
  * IBAN and BIC of the user's accounts, from the bank's SEPA account list where the user parameter data lack them
- * (Formals F.3.4).
+ * (Formals F.3.4), and the accounts the app passes completed from both.
  *
  * The list is read once per version of the user parameter data and kept in the saved state. Under version 0, which
- * holds for one dialog only (Formals E.2), without user parameter data, or where the bank rejects the list, it is kept
- * for this client only. Where the bank ends the dialog in answer to the list, the next call asks once more.
+ * holds for one dialog only (Formals E.2), without user parameter data, or where the bank rejects the list, also by
+ * ending the dialog, or names no account in it, it is kept for this client only: an empty list completes nothing, and
+ * saved it would outlast a fault of a single answer until the bank changes its user parameter data.
  */
-export class SepaAccounts<R extends BankResponse, O> {
+export class SepaAccounts {
   /**
    * The list this client keeps unsaved, with the version of the user parameter data it was read under; empty where the
-   * bank rejected it.
+   * bank rejected it or named no account.
    */
   private unsaved: { updVersion: number | undefined; accounts: readonly Account[] } | undefined;
 
-  /** Whether a call already went on without the list because the bank ended the dialog in answer to it. */
-  private abortSkipped = false;
-
   constructor(
-    private readonly protocol: PinTanProtocol<R, O>,
+    private readonly parameters: ParameterStore,
     private readonly state: SessionState,
-    private readonly dialogs: DialogRunner<R, O>,
-    private readonly guard: LoginGuard,
+    private readonly dialogs: DialogRunner,
   ) {}
 
   /** The accounts of the user parameter data completed with IBAN and BIC, then the accounts only the list names. */
   async completedAccounts(): Promise<Account[]> {
     const sepa = await this.list();
-    const accounts = this.protocol.userParameters?.accounts ?? [];
+    const accounts = this.parameters.userParameters?.accounts ?? [];
+    const listed = new AccountIndex(sepa);
+    const known = new AccountIndex(accounts);
     return [
-      ...accounts.map((account) => withSepaDetails(account, sepa)),
-      ...sepa.filter((s) => !accounts.some((a) => s.matches(a))),
+      ...accounts.map((account) => withSepaDetails(account, listed.find(account))),
+      ...sepa.filter((s) => known.find(s) === undefined),
     ];
   }
 
-  /** `account` with IBAN and BIC filled in from the list. */
+  /**
+   * `account` as the bank knows it: the one of `completedAccounts` it matches, with what the bank states of it first,
+   * so that an account the app has built itself, such as from an IBAN alone, goes out with the account number, the
+   * sub-account and the BIC the bank's orders take, and the currency of its statements. Where the bank names none it
+   * matches, only what identifies `account`, and its currency: the rest, such as the transactions it permits, only the
+   * bank can state.
+   *
+   * Throws `FinTsUnsupportedError` for such an account where the user parameter data list all permitted transactions:
+   * they permit nothing for an account they leave out, and the client cannot tell it from a mistyped one.
+   */
   async complete(account: Account): Promise<Account> {
-    if (account.iban !== undefined && account.bic !== undefined) return account;
-    return withSepaDetails(account, await this.list());
+    const known = (await this.completedAccounts()).find((a) => account.matches(a));
+    if (known !== undefined) {
+      // A sub-account belongs to the account number it comes with.
+      const national = known.accountNumber === undefined ? account : known;
+      return known.copyWith({
+        accountNumber: national.accountNumber,
+        subAccount: national.subAccount,
+        iban: known.iban ?? account.iban,
+        bic: known.bic ?? account.bic,
+        currency: known.currency ?? account.currency,
+      });
+    }
+    if (this.parameters.userParameters?.listsAllTransactions === true) {
+      throw new FinTsUnsupportedError("The bank does not name this account among the user's, and so permits nothing");
+    }
+    return new Account({
+      accountNumber: account.accountNumber,
+      subAccount: account.subAccount,
+      bankCode: account.bankCode,
+      countryCode: account.countryCode,
+      iban: account.iban,
+      bic: account.bic,
+      currency: account.currency,
+    });
   }
 
   /** The list, read in the session's dialog, whose start delivers the user parameter data it is cached for. */
   private async list(): Promise<readonly Account[]> {
     await this.dialogs.open();
-    const upd = this.protocol.userParameters;
+    const upd = this.parameters.userParameters;
     if (
       upd !== undefined &&
       upd.accounts.length > 0 &&
@@ -61,26 +91,12 @@ export class SepaAccounts<R extends BankResponse, O> {
     const saved = this.state.sepaAccounts(updVersion);
     if (saved !== undefined) return saved;
     if (this.unsaved !== undefined && this.unsaved.updVersion === updVersion) return this.unsaved.accounts;
-    const query = this.protocol.sepaAccounts();
+    const query = sepaAccountsQuery(this.parameters);
     if (query === undefined) return [];
-    // Where the bank rejects the list, the accounts stay as the user parameter data state them.
-    const outcome = { aborted: false };
-    const accounts = await this.guard.tryLookUp(async () => {
-      try {
-        return await this.dialogs.query(() => query);
-      } catch (error) {
-        if (error instanceof FinTsDialogAbortedError) outcome.aborted = true;
-        throw error;
-      }
-    });
-    if (outcome.aborted && !this.abortSkipped) {
-      // The bank may have ended the dialog for a reason of its own, such as a timeout, so this call goes on without the
-      // list and the next one asks again in its new dialog. Only once: banks also end the dialog when they reject the
-      // list, and each time costs the next call a login.
-      this.abortSkipped = true;
-      return [];
-    }
-    if (accounts !== undefined && updVersion !== undefined && updVersion > 0) {
+    // Where the bank rejects the list, also by ending the dialog, the accounts stay as the user parameter data state
+    // them: asked again, a bank that ends the dialog in answer would cost each call a login.
+    const accounts = await tryLookUp(() => this.dialogs.query(() => query));
+    if (accounts !== undefined && accounts.length > 0 && updVersion !== undefined && updVersion > 0) {
       this.state.cacheSepaAccounts(accounts, updVersion);
     } else {
       this.unsaved = { updVersion, accounts: accounts ?? [] };
@@ -89,9 +105,11 @@ export class SepaAccounts<R extends BankResponse, O> {
   }
 }
 
-function withSepaDetails(account: Account, sepa: readonly Account[]): Account {
-  const match = sepa.find((s) => account.matches(s));
-  if (match === undefined) return account;
+/**
+ * A copy of `account`, which shares no date with the user parameter data, with the IBAN and BIC of `match`, its entry
+ * in the SEPA account list, if any.
+ */
+function withSepaDetails(account: Account, match: Account | undefined): Account {
   // A BIC of the list takes precedence over the one of the user parameter data (Formals E.3.1.1, "BIC").
-  return account.copyWith({ iban: account.iban ?? match.iban, bic: match.bic ?? account.bic });
+  return account.copyWith({ iban: account.iban ?? match?.iban, bic: match?.bic ?? account.bic });
 }

package/src/session/session-setup.ts

@@ -1,10 +1,14 @@
 import type { BankInfo } from '../core/bank-info.js';
-import { FinTsBankError, FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData } from '../core/errors.js';
+import { FinTsError, FinTsProtocolError, FinTsTransportError, parseBankData, tryLookUp } from '../core/errors.js';
+import { hasErrors } from '../core/feedback.js';
 import type { TanMedium, TanMethod } from '../tan/tan-models.js';
-import type { LoginGuard, RefusalReason } from './login-guard.js';
-import { requireBankParameters } from './parameter-data.js';
-import type { BankResponse, PinTanProtocol, ProtocolDialog } from './protocol.js';
-import type { ResponseHandler } from './response-handler.js';
+import { FinTs3Dialog } from '../v3/dialog.js';
+import type { IncomingMessage3 } from '../v3/message.js';
+import { requireBankParameters } from '../v3/parameters.js';
+import type { FinTs3Protocol } from '../v3/protocol.js';
+import { tanMediaQuery } from '../v3/queries.js';
+import type { RefusalReason } from './login-guard.js';
+import { SignedDialog, type SessionParts } from './signed-dialog.js';
 import type { TanSelection } from './tan-selection.js';
 
 /**
@@ -13,15 +17,11 @@ import type { TanSelection } from './tan-selection.js';
  *
  * Where the bank refuses a login for a reason the session can take care of, `remedied` does so and logs in again.
  */
-export class SessionSetup<R extends BankResponse, O> {
-  /** Whether a synchronization dialog ran, so that a helpful one runs once only. */
-  private synchronizationTried = false;
-
+export class SessionSetup {
   constructor(
-    private readonly protocol: PinTanProtocol<R, O>,
-    private readonly responses: ResponseHandler<R>,
-    private readonly tans: TanSelection<R, O>,
-    private readonly guard: LoginGuard,
+    private readonly session: SessionParts,
+    private readonly protocol: FinTs3Protocol,
+    private readonly tans: TanSelection,
   ) {}
 
   /**
@@ -29,9 +29,9 @@ export class SessionSetup<R extends BankResponse, O> {
    * No TAN method or medium is chosen for it.
    */
   async bankInfo(): Promise<BankInfo> {
-    if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
-    if (this.protocol.bankParameters === undefined) await this.synchronizeIfDue();
-    return requireBankParameters(this.protocol.bankParameters).bankInfo;
+    if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    if (this.session.parameters.bankParameters === undefined) await this.synchronizeIfDue();
+    return requireBankParameters(this.session.parameters.bankParameters).bankInfo;
   }
 
   /** The TAN methods the bank allows for this user, which the synchronization reports. */
@@ -40,56 +40,43 @@ export class SessionSetup<R extends BankResponse, O> {
     return this.tans.available();
   }
 
-  /** Settles what is still open: the bank parameter data, the synchronization, the TAN method and medium. */
-  async prepare(): Promise<void> {
+  /**
+   * Settles what is still open: the bank parameter data, the synchronization, the TAN method and medium. Returns the TAN
+   * media it looked up to choose the medium; `undefined` where it looked up none, or the bank listed none.
+   */
+  async prepare(): Promise<TanMedium[] | undefined> {
     await this.loadParameters();
     await this.tans.ensureMethodChosen();
-    if (this.tans.mediumToLookUp) await this.tans.chooseMedium(await this.lookUpTanMedia());
+    if (!this.tans.mediumToLookUp) return undefined;
+    const media = await this.lookUpTanMedia();
+    await this.tans.chooseMedium(media);
+    return media;
   }
 
   /** A new dialog signed with the TAN method and medium in use, once `prepare` has settled them. */
-  async newDialog(): Promise<ProtocolDialog<R, O>> {
+  async newDialog(): Promise<SignedDialog> {
     await this.prepare();
-    return this.tans.newDialog();
+    return new SignedDialog(this.tans.newDialog(), this.session);
   }
 
-  /**
-   * Runs `attempt`, which may log in, and runs it once more for each reason of a refused login the session can take
-   * care of, so that a bank that keeps refusing fails with its own error:
-   *
-   * | Refusal (`LoginGuard.remediableReasons`) | Remedy |
-   * | --- | --- |
-   * | 3920 without the method, or 9075 after the one-step method | another allowed method (`TanSelection.replace`) |
-   * | 9391 | a new synchronization, which issues a customer system ID |
-   */
-  async remedied<T>(attempt: () => Promise<T>): Promise<T> {
-    // A refusal of an earlier call stops the attempt before it sends the PIN; there is nothing to remedy.
-    if (this.guard.hasRefusal) return attempt();
-    const remedied = new Set<RefusalReason>();
-    for (;;) {
-      try {
-        return await attempt();
-      } catch (error) {
-        if (!(error instanceof FinTsBankError)) throw error;
-        const reason = this.guard.remediableReasons(error).find((r) => !remedied.has(r));
-        const rejected = this.guard.refusedMethod;
-        if (reason === undefined || rejected === undefined || !(await this.remedy(reason, rejected))) throw error;
-        remedied.add(reason);
-        this.guard.pardon(error);
-      }
-    }
+  /** Runs `attempt`, which may log in, once more after each refused login `remedy` takes care of. */
+  remedied<T>(attempt: () => Promise<T>): Promise<T> {
+    return this.session.guard.remedied(attempt, (reason, rejected) => this.remedy(reason, rejected));
   }
 
-  /** Takes care of `reason`, given for refusing a login signed with `rejected`; returns whether it could. */
+  /**
+   * Takes care of `reason`, given for refusing a login signed with `rejected`, with another TAN method or a new
+   * synchronization; returns whether it could.
+   */
   private async remedy(reason: RefusalReason, rejected: TanMethod): Promise<boolean> {
     switch (reason) {
       case 'tanMethodNotAllowed':
         // The parameter data name the methods to choose from; the refusal may be the first to deliver them.
-        if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+        if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
         return this.tans.replace(rejected);
       case 'systemIdRejected':
         // Without a customer system ID there is none to lose, and logging in once more would only send the PIN again.
-        return this.protocol.forgetSystemId();
+        return this.session.parameters.forgetSystemId();
     }
   }
 
@@ -103,35 +90,66 @@ export class SessionSetup<R extends BankResponse, O> {
    * After a refused login it throws the refusal right away, before the user is asked for a TAN method or medium.
    */
   private async loadParameters(): Promise<void> {
-    this.guard.check();
-    if (this.protocol.bankParameters === undefined) await this.fetchBankParametersAnonymously();
+    this.session.guard.check();
+    if (this.session.parameters.bankParameters === undefined) await this.fetchBankParametersAnonymously();
     await this.synchronizeIfDue();
   }
 
   /**
-   * Asks for the bank parameter data without logging in. A bank that does not answer anonymously is no error, but a
-   * failed connection is: the synchronization would only wait for the same server again.
+   * Asks for the bank parameter data without logging in, keeps them where there are none from a dialog signed with the
+   * PIN (`ParameterStore.keepAnonymous`), and passes the bank's messages on: all an anonymous dialog tells, since the
+   * TAN methods it lists are not those of a user. A bank that does not answer anonymously is no error, but a failed
+   * connection is: the synchronization would only wait for the same server again.
    */
   private async fetchBankParametersAnonymously(): Promise<void> {
     try {
-      this.responses.showBankMessages(await this.protocol.fetchBankParametersAnonymously());
+      const response = await this.requestBankParametersAnonymously();
+      this.session.parameters.keepAnonymous(response);
+      for (const message of response.bankMessages) this.session.prompts.showBankMessage(message);
     } catch (error) {
       // Optional: the login delivers the parameters as well.
       if (error instanceof FinTsTransportError || !(error instanceof FinTsError)) throw error;
     }
   }
 
-  /** Runs the synchronization dialog where it is due (`TanSelection.synchronizationDialog`). */
+  /**
+   * 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.
+   *
+   * A timeout or a broken connection is not a reason to ask again: it would only double the wait.
+   */
+  private async requestBankParametersAnonymously(): Promise<IncomingMessage3> {
+    let announced: IncomingMessage3;
+    try {
+      announced = await this.anonymousDialog(true);
+    } 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.protocol);
+    try {
+      return await dialog.requestBankParameters(announceSca);
+    } finally {
+      await dialog.end();
+    }
+  }
+
+  /**
+   * Runs the synchronization, a login in a dialog of its own, while there is no customer system ID, without which no
+   * regular dialog starts. It runs before the TAN method and medium are settled (`TanSelection.synchronizationDialog`
+   * tells which method signs it).
+   */
   private async synchronizeIfDue(): Promise<void> {
-    const due =
-      this.protocol.synchronization === 'required' ||
-      (this.protocol.synchronization === 'helpful' && !this.synchronizationTried);
-    if (!due) return;
-    this.synchronizationTried = true;
-    await this.once(this.tans.synchronizationDialog(), (dialog) =>
-      this.responses.startDialog(dialog, () => dialog.start(true)),
-    );
-    if (this.protocol.synchronization === 'required') {
+    if (this.session.parameters.systemId !== undefined) return;
+    await this.once(this.tans.synchronizationDialog(), (dialog) => dialog.login(true));
+    // Set by the synchronization, which the compiler cannot see.
+    if ((this.session.parameters.systemId as string | undefined) === undefined) {
       throw new FinTsProtocolError('The bank did not complete the synchronization');
     }
   }
@@ -144,22 +162,23 @@ export class SessionSetup<R extends BankResponse, O> {
    * medium the list tells (PIN/TAN B.4.3.1.3).
    */
   private async lookUpTanMedia(): Promise<TanMedium[] | undefined> {
-    const query = this.protocol.tanMedia();
+    const query = tanMediaQuery(this.session.parameters);
     if (query === undefined) return undefined;
-    return this.guard.tryLookUp(() =>
+    return tryLookUp(() =>
       this.once(this.tans.lookupDialog(), async (dialog) => {
-        const pages = await this.responses.startDialogWith(dialog, dialog.startWith(query.order(undefined)));
-        return parseBankData(() => query.read(pages));
+        const answers = await dialog.loginWith(query.order(undefined));
+        return parseBankData(() => query.read(answers));
       }),
     );
   }
 
   /** Runs `use` in `dialog`, a dialog of its own, and ends it afterwards, however `use` ends. */
-  private async once<T>(dialog: ProtocolDialog<R, O>, use: (dialog: ProtocolDialog<R, O>) => Promise<T>): Promise<T> {
+  private async once<T>(dialog: FinTs3Dialog, use: (dialog: SignedDialog) => Promise<T>): Promise<T> {
+    const signed = new SignedDialog(dialog, this.session);
     try {
-      return await use(dialog);
+      return await use(signed);
     } finally {
-      await dialog.end();
+      await signed.end();
     }
   }
 }

package/src/session/session-state.ts

@@ -1,16 +1,19 @@
 import { Account } from '../core/account.js';
 import { hostOf, type FinTsConfig } from '../core/config.js';
+import { FinTsFeedback } from '../core/feedback.js';
 import { FormatError } from '../util/errors.js';
 import {
   isJsonObject,
   isString,
   readObject,
   readOptionalInt,
+  readOptionalObject,
   readOptionalList,
   readOptionalString,
   type JsonObject,
 } from '../util/json.js';
-import type { BankResponse, PinTanProtocol } from './protocol.js';
+import type { ParameterStore } from '../v3/parameter-store.js';
+import type { LoginGuard, LoginGuardState } from './login-guard.js';
 
 /** Layout of the saved session; a state of another layout is ignored. */
 const stateFormat = 1;
@@ -18,40 +21,40 @@ const stateFormat = 1;
 /** The protocol version the state is for, named as the Dart package names it, so that both read each other's states. */
 const protocolVersion = 'v300';
 
-/** The session and the protocol's parameter data as one JSON string, which `restoreSession` reads. */
-export function saveSession<R extends BankResponse, O>(protocol: PinTanProtocol<R, O>, session: SessionState): string {
+/** The session, the parameter data and the guard's refusal as JSON, which `restoreSession` reads. */
+export function saveSession(parameters: ParameterStore, guard: LoginGuard, session: SessionState): string {
   return JSON.stringify({
     format: stateFormat,
     version: protocolVersion,
-    owner: ownerOf(protocol.config),
+    owner: ownerOf(parameters.config),
     session: session.toJson(),
-    protocol: protocol.saveState(),
+    // Under the key the Dart package reads as well.
+    protocol: parameters.saveState(),
+    loginGuard: guardStateToJson(guard.saveState()),
   });
 }
 
 /**
- * The session saved in `json`, and the protocol's parameter data restored from it.
+ * The session saved in `json`, and the parameter data and the guard's refused login restored from it.
  *
  * A missing or damaged state, or one saved for another user, bank, server or protocol version, gives a new session,
- * which only costs a new synchronization.
+ * which only costs a new synchronization. The refused login belongs to the user at the bank, so it comes first: it holds
+ * for another server or protocol version as well, and where the rest is damaged; a state saved by the Dart package or
+ * an earlier version has none.
  */
-export function restoreSession<R extends BankResponse, O>(
-  json: string | undefined,
-  protocol: PinTanProtocol<R, O>,
-): SessionState {
+export function restoreSession(json: string | undefined, parameters: ParameterStore, guard: LoginGuard): SessionState {
   if (json === undefined) return new SessionState();
   try {
     const saved: unknown = JSON.parse(json);
-    if (!isJsonObject(saved) || saved.format !== stateFormat || saved.version !== protocolVersion) {
-      return new SessionState();
-    }
-    const owner = readOptionalList(saved, 'owner', isString);
-    const expected = ownerOf(protocol.config);
-    if (owner?.length !== expected.length || owner.some((value, i) => value !== expected[i])) {
-      return new SessionState();
-    }
+    if (!isJsonObject(saved) || saved.format !== stateFormat) return new SessionState();
+    const [server, ...user] = readOptionalList(saved, 'owner', isString) ?? [];
+    const expected = userOf(parameters.config);
+    if (user.length !== expected.length || user.some((value, i) => value !== expected[i])) return new SessionState();
+    const loginGuard = readOptionalObject(saved, 'loginGuard');
+    if (loginGuard !== undefined) guard.restoreState(guardStateFromJson(loginGuard));
+    if (server !== hostOf(parameters.config.url) || saved.version !== protocolVersion) return new SessionState();
     const session = SessionState.fromJson(readObject(saved, 'session'));
-    protocol.restoreState(readObject(saved, 'protocol'));
+    parameters.restoreState(readObject(saved, 'protocol'));
     return session;
   } catch (error) {
     // Damaged JSON, base64 or parameter data, and values of the wrong type, only cost a new synchronization.
@@ -60,9 +63,14 @@ export function restoreSession<R extends BankResponse, O>(
   }
 }
 
-/** Whose data a state holds, so that the state of another user or bank is never used. */
+/** Whose data a state holds, so that the state of another user or bank is never used: the server, then `userOf`. */
 function ownerOf(config: FinTsConfig): string[] {
-  return [hostOf(config.url), config.bankCode, config.userId, config.customerId];
+  return [hostOf(config.url), ...userOf(config)];
+}
+
+/** The user at the bank, whom a refused login belongs to. */
+function userOf(config: FinTsConfig): string[] {
+  return [config.bankCode, config.userId, config.customerId];
 }
 
 /**
@@ -168,3 +176,29 @@ function accountFromJson(json: JsonObject): Account {
     bankCode,
   });
 }
+
+function guardStateToJson(state: LoginGuardState): JsonObject {
+  return { refusal: state.refusal?.map(feedbackToJson) ?? null, unreadLogins: state.unreadLogins };
+}
+
+function guardStateFromJson(json: JsonObject): LoginGuardState {
+  return {
+    refusal: readOptionalList(json, 'refusal', isJsonObject)?.map(feedbackFromJson),
+    unreadLogins: readOptionalInt(json, 'unreadLogins') ?? 0,
+  };
+}
+
+function feedbackToJson(f: FinTsFeedback): JsonObject {
+  return { code: f.code, reference: f.reference ?? null, text: f.text, parameters: [...f.parameters] };
+}
+
+function feedbackFromJson(json: JsonObject): FinTsFeedback {
+  const code = readOptionalString(json, 'code');
+  if (code === undefined) throw new FormatError('Saved state: return code without code');
+  return new FinTsFeedback({
+    code,
+    reference: readOptionalString(json, 'reference'),
+    text: readOptionalString(json, 'text') ?? '',
+    parameters: readOptionalList(json, 'parameters', isString) ?? [],
+  });
+}