@coderoftime/fints 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+## 0.1.0
+
+First release: a TypeScript port of the FinTS 3.0 client of the Dart package `fints`.
+
+- `FinTs3Client`: accounts, balances and transactions (camt.052 and MT940/MT942), with paging and SEPA account details.
+- One-step and two-step TAN, PSD2 strong customer authentication and app approval (decoupled), timed by the bank's
+  parameters; TAN method and medium selection, chipTAN flicker codes and photoTAN images.
+- Bank parameter data, customer system ID and the chosen TAN method in an exportable state string, in the layout of the
+  Dart package.
+- A client never sends its PIN again once the bank has refused a login.
+- Runs wherever `fetch`, Web Crypto and `TextDecoder` are available; no runtime dependencies.

package/LICENSE

@@ -0,0 +1,28 @@
+Copyright 2026, the fints project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @coderoftime/fints
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A FinTS 3.0 client for German banks, written in TypeScript, without runtime dependencies. It reads accounts, balances and transactions with PIN/TAN, including PSD2 strong customer authentication and app approval (pushTAN, SecureGo plus and the like).
+
+It is a port of the Dart package [`fints`](https://pub.dev/packages/fints) and behaves the same: same session logic, same safeguards, same tests. FinTS 4.1, which hardly any bank offers, is not part of the port.
+
+## Features
+
+- **PIN/TAN** with the one-step method (`999`) and two-step methods of process variant 2 (`HKTAN` process 4, then 2 or `S`).
+- **Strong customer authentication** at login and per transaction where the bank asks for it, including exemptions (`3076`).
+- **App approval** (decoupled), polled by the bank's own parameters; the client stops when the app is closed or the user cancels.
+- **TAN media** lookup and selection, **chipTAN flicker codes** (HHD 1.3 and 1.4, as frames to animate) and **photoTAN/QR images** (as `data:` URLs).
+- **Balances** (`HKSAL` 6–8) and **transactions** as camt.052 (`HKCAZ`) or MT940/MT942 (`HKKAZ` 6–7), with automatic paging.
+- **IBAN and BIC** from the SEPA account list (`HKSPA`), and the account extension of the user parameter data.
+- **Safe by default**: the PIN is never sent again after the bank refused a login, so a retrying app cannot lock the access; only what the bank's parameter data permit is sent; PIN and TAN are masked in every log.
+- **Saved sessions**: bank and user parameters, customer system ID and the chosen TAN method in one state string, which spares the setup steps at the next start.
+- Parsers for MT940 (German structured `:86:` fields, SEPA keywords) and camt.052/053.
+
+## Requirements
+
+1. **A FinTS product registration.** German banks only accept registered products. Register for free with the Deutsche Kreditwirtschaft at <https://www.fints.org/de/hersteller/produktregistrierung> and pass the ID as `productId`. Keep it out of your repository.
+2. **Your bank's FinTS URL and bank code (BLZ)**, for example from the DK institute list.
+3. **A runtime with `fetch`, Web Crypto and `TextDecoder`**: Node.js 22.12 or later, Deno, Bun, or a browser behind a server of your own (see [Using it with Vue](#using-it-with-vue)). The type declarations need TypeScript 5.6 or later.
+
+## Usage
+
+```ts
+import { FinTs3Client, TanAnswer } from '@coderoftime/fints';
+
+const client = new FinTs3Client({
+  config: {
+    url: 'https://fints.example-bank.de/fints',
+    bankCode: '12345678',
+    userId: 'my-login',
+    productId: process.env.FINTS_PRODUCT_ID!,
+    productVersion: '1.0',
+  },
+  pin,
+  options: {
+    state: savedState, // from a previous session, or undefined
+    tanMethodSelector: (methods) => pickMethod(methods),
+    tanMediumSelector: (media) => pickMedium(media),
+    onBankMessage: (message) => showNotice(message.subject, message.text),
+    onWarning: (warning) => showNotice(warning.code, warning.text), // banks want code and text shown
+    tanCallback: async (challenge) => {
+      if (challenge.isDecoupled) {
+        // Close the prompt when challenge.resolved settles; offer "approved" only if challenge.manualConfirmation.
+        const confirmed = await showApprovalPrompt(challenge);
+        return confirmed ? TanAnswer.approved : TanAnswer.cancelled;
+      }
+      // Show challenge.plainMessage, challenge.image?.toDataUrl() or challenge.flickerCode?.frames().
+      const tan = await askForTan(challenge);
+      return tan === undefined ? TanAnswer.cancelled : TanAnswer.tan(tan);
+    },
+  },
+});
+
+try {
+  const accounts = await client.getAccounts();
+  const balance = await client.getBalance(accounts[0]!);
+  const transactions = await client.getTransactions(accounts[0]!, { from: new Date(2024, 0, 1) });
+} finally {
+  saveEncrypted(client.state); // no PIN or TAN, but account data
+  await client.close();
+}
+```
+
+All calls share one bank dialog, so the user approves once per session. Calls run one after another; a call from inside a callback would wait for itself, so on Node.js, Deno and Bun it fails with `FinTsStateError` (in browsers it is not detected).
+
+Calendar dates, such as `Transaction.bookingDate`, are `Date`s at local midnight, of which only the day counts. Moments, such as `Balance.bookedAsOfTime`, are exact; the bank states them in German time.
+
+## Using it with Vue
+
+**A web page cannot talk to a bank's FinTS server directly.** Browsers only let a page call another origin if the server allows it (CORS), and bank servers do not. So some server of yours always sits between the browser and the bank, and **that server sees the PIN**: FinTS PIN/TAN messages carry it in plain text inside TLS. It must be a server you and your users trust.
+
+There are three ways to set it up:
+
+1. **The client runs on your server** (Nuxt server routes, Express, …). The Vue app calls your own API; the server keeps one `FinTs3Client` per session and passes the TAN challenges to the browser, for example with a pending request the browser answers. This keeps the bank traffic and the product ID on the server.
+2. **The client runs in the browser, through a relay.** The library runs in the Vue app, so TAN prompts are plain local UI, and a small endpoint of yours forwards each message to the bank. Pass a transport that posts to it:
+
+   ```ts
+   import type { FinTsTransport } from '@coderoftime/fints';
+
+   const relay: FinTsTransport = {
+     async post(url, body, contentType) {
+       const response = await fetch('/api/fints-relay', {
+         method: 'POST',
+         headers: { 'Content-Type': contentType, 'X-FinTS-URL': url.href },
+         body,
+       });
+       if (!response.ok) throw new Error(`Relay: HTTP ${response.status}`);
+       return new Uint8Array(await response.arrayBuffer());
+     },
+     close() {},
+   };
+   ```
+
+   The relay must forward only to the bank URLs of the DK institute list, never to any URL a caller names, or it is an open proxy. The product ID ends up in the page; anyone can read it there.
+
+3. **The app is not a web page**: Electron, Tauri or Capacitor can send requests without CORS. Pass a `FinTsTransport` that uses the platform's HTTP client, or `HttpTransport` where `fetch` is not bound by CORS.
+
+A TAN prompt in Vue fits the callback as a promise the dialog resolves:
+
+```ts
+import { ref } from 'vue';
+import { TanAnswer, type TanChallenge } from '@coderoftime/fints';
+
+export const pending = ref<{ challenge: TanChallenge; answer: (a: TanAnswer) => void }>();
+
+export function tanCallback(challenge: TanChallenge): Promise<TanAnswer> {
+  return new Promise((answer) => {
+    pending.value = { challenge, answer };
+    void challenge.resolved?.then(() => (pending.value = undefined)); // the bank confirmed the app approval
+  });
+}
+// The dialog component shows pending.value.challenge and calls pending.value.answer(TanAnswer.tan(input)),
+// TanAnswer.approved or TanAnswer.cancelled, then clears pending.value.
+```
+
+## Errors
+
+| Error                        | Meaning                                                                                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `FinTsPinError`              | Wrong or blocked PIN. The client sends no PIN any more; create a new client to try again.                                                        |
+| `FinTsTanError`              | Wrong, expired or used TAN. The session stays usable.                                                                                            |
+| `FinTsTanCancelledError`     | The user cancelled the TAN or the app approval.                                                                                                  |
+| `FinTsDecoupledTimeoutError` | The app approval did not come within the bank's limit.                                                                                           |
+| `FinTsLoginDataChangedError` | The bank issued new login data (`3072`); `loginName` tells it.                                                                                   |
+| `FinTsDialogAbortedError`    | The bank ended the dialog; the next call logs in anew.                                                                                           |
+| `FinTsBankError`             | Any other rejection; `feedback` holds the return codes. After a refused login, later calls fail with the same error without contacting the bank. |
+| `FinTsUnsupportedError`      | The bank or the user's parameter data do not offer the transaction; nothing was sent.                                                            |
+| `FinTsProtocolError`         | The bank's answer could not be read.                                                                                                             |
+| `FinTsTransportError`        | No connection, an HTTP error or a timeout.                                                                                                       |
+| `FinTsStateError`            | The client was closed, or called from inside one of its callbacks.                                                                               |
+| `TypeError`                  | An invalid argument, such as an empty PIN or a period that ends before it starts; the message never contains the PIN.                            |
+
+The client never sends a message larger than the bank's maximum (`BankInfo.maxMessageSize`, in kilobytes), and never repeats a call by itself: the bank's answer cannot tell whether an order went through.
+
+## Differences from the Dart package
+
+- Errors are named `…Error` instead of `…Exception`; invalid arguments are `TypeError`s, malformed data `FormatError`s.
+- `getTransactions(account, { from, to, format })` takes an options object; enums are string unions such as `'mt940'`.
+- The polling parameters of `TanMethod` are in seconds: `decoupledFirstPollDelaySeconds`, `decoupledPollIntervalSeconds`.
+- `HttpTransport` takes a `fetch` and `timeoutMs`; `TanImage.toDataUrl()` is new.
+- The saved state has the same layout, so a state saved by one package can be restored by the other.
+
+## Development
+
+```sh
+npm install
+npm run check   # type check, lint, format check and tests
+npm run build
+```
+
+## License
+
+BSD 3-Clause, see [LICENSE](LICENSE). Commercial use is allowed; a product that ships the library must reproduce its copyright notice and license in its documentation or notices.

package/dist/core/account.d.ts

@@ -0,0 +1,140 @@
+/** Account kind derived from the FinTS account type code. */
+export type AccountCategory = 
+/** Current account (type codes 1 to 9). */
+'checking'
+/** Savings account (10 to 19). */
+ | 'savings'
+/** Fixed-term deposit (20 to 29). */
+ | 'fixedDeposit'
+/** Securities account (30 to 39). */
+ | 'securities'
+/** Loan account (40 to 49). */
+ | 'loan'
+/** Credit card account (50 to 59). */
+ | 'creditCard'
+/** Fund deposit (60 to 69). */
+ | 'fund'
+/** Home savings contract (70 to 79). */
+ | 'homeSavings'
+/** Insurance (80 to 89). */
+ | 'insurance'
+/** Any other type code. */
+ | 'other'
+/** The bank states no type code. */
+ | 'unknown';
+/** The category of the FinTS account type `code`, which is `undefined` if the bank states none. */
+export declare function accountCategoryOf(code: number | undefined): AccountCategory;
+/** What `Account` takes; the bank states the details it knows. */
+export interface AccountInit {
+    accountNumber?: string | undefined;
+    subAccount?: string | undefined;
+    bankCode: string;
+    countryCode?: string | undefined;
+    iban?: string | undefined;
+    bic?: string | undefined;
+    customerId?: string | undefined;
+    currency?: string | undefined;
+    ownerName?: string | undefined;
+    productName?: string | undefined;
+    typeCode?: number | undefined;
+    allowedTransactions?: readonly string[] | undefined;
+    allowedTransactionsComplete?: boolean | undefined;
+    dataStatus?: AccountDataStatus | undefined;
+}
+/** A bank account as reported by the user parameter data or the SEPA account query. */
+export declare class Account {
+    /** National account number. */
+    readonly accountNumber: string | undefined;
+    /** Sub-account characteristic (Unterkontomerkmal). */
+    readonly subAccount: string | undefined;
+    /** German bank code (BLZ) of the bank holding the account. */
+    readonly bankCode: string;
+    /** Numeric country code of the bank, `280` for Germany. */
+    readonly countryCode: string;
+    /** International bank account number. */
+    readonly iban: string | undefined;
+    /** Bank identifier code of the bank holding the account. */
+    readonly bic: string | undefined;
+    /** Customer ID the account is assigned to; may differ from the login name. */
+    readonly customerId: string | undefined;
+    /** Currency of the account, for example `EUR`. */
+    readonly currency: string | undefined;
+    /** Name of the account holder. */
+    readonly ownerName: string | undefined;
+    /** The bank's name for the account, for example `Girokonto`. */
+    readonly productName: string | undefined;
+    /** Raw FinTS account type (1–99); see `category`. */
+    readonly typeCode: number | undefined;
+    /**
+     * The transactions the bank lists as permitted for this account, by their segment IDs, such as `HKSAL`.
+     *
+     * The client applies them itself: `getBalance` and `getTransactions` throw `FinTsUnsupportedError`, without asking
+     * the bank, where the parameter data rule the query out.
+     */
+    readonly allowedTransactions: readonly string[];
+    /**
+     * Whether `allowedTransactions` is complete: the bank permits nothing it does not list (FinTS "UPD-Verwendung" 0).
+     * Otherwise the bank's lists say nothing about a transaction they leave out, and only the bank can tell.
+     */
+    readonly allowedTransactionsComplete: boolean;
+    /** What the bank tells about the data it holds for the account, where it does. */
+    readonly dataStatus: AccountDataStatus | undefined;
+    constructor(init: AccountInit);
+    /** The kind of account, derived from `typeCode`. */
+    get category(): AccountCategory;
+    /**
+     * Whether `other` is the same account: by IBAN when both have one, otherwise by account number, sub-account and
+     * bank.
+     *
+     * Account numbers are compared without leading zeros, since banks pad them differently. An empty bank or country
+     * code, as of a balance record without bank identification, matches any.
+     */
+    matches(other: Account): boolean;
+    /** This account with the given details replaced; a detail that is `undefined` stays as it is. */
+    copyWith(changes: Omit<Partial<AccountInit>, 'bankCode' | 'countryCode'>): Account;
+    /**
+     * The product name and the last digits of the IBAN or account number only, so that logs and crash reports do not
+     * collect account data.
+     */
+    toString(): string;
+}
+/**
+ * What the bank tells about the data it holds for an account, so that an app asks only for what has changed (FinTS 3.0
+ * user parameter data, "Erweiterung, kontobezogen", Formals E.3.1 and F).
+ *
+ * The rules are binding for an app that stores transactions; banks may refuse an app that ignores them:
+ * - Do not fetch the transactions again while the bank names the ID they were stored with (`mt940TransactionsId` or
+ *   `camtTransactionsId`, for the format the app asked for, so pass `format` to `getTransactions` explicitly), or, in
+ *   the older format, the timestamp `lastTransactions`.
+ * - Do not fetch them before `nextTransactionsAt`.
+ * - Do not ask for the balance separately where `transactionBalancesCurrent` says that the transactions carry the
+ *   current one.
+ */
+export declare class AccountDataStatus {
+    /**
+     * IDs of the data the bank holds for the user, keyed by the segment ID of the query that fetches them, for example
+     * `HKKAZ` (transactions as MT940) or `HKCAZ` (as camt): the data have changed when the ID changes. An empty ID means
+     * that the user has no such data; a query the map leaves out, that the bank tells nothing about it.
+     */
+    readonly inventory: ReadonlyMap<string, string>;
+    /**
+     * The timestamp of the last transactions the bank provided, in the older format of the extension (`umsltzt`);
+     * compared like an ID in `inventory`.
+     */
+    readonly lastTransactions: string | undefined;
+    /** The moment before which the bank provides no new transactions. */
+    readonly nextTransactionsAt: Date | undefined;
+    /** Whether the balances the transactions carry are the current ones. */
+    readonly transactionBalancesCurrent: boolean;
+    constructor(init: {
+        inventory?: ReadonlyMap<string, string>;
+        lastTransactions?: string | undefined;
+        nextTransactionsAt?: Date | undefined;
+        transactionBalancesCurrent?: boolean;
+    });
+    /** The ID of the transactions the bank holds as MT940, its entry for `HKKAZ` in `inventory`. */
+    get mt940TransactionsId(): string | undefined;
+    /** The ID of the transactions the bank holds as camt, its entry for `HKCAZ` in `inventory`. */
+    get camtTransactionsId(): string | undefined;
+}
+//# sourceMappingURL=account.d.ts.map

package/dist/core/account.d.ts.map

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

package/dist/core/account.js

@@ -0,0 +1,174 @@
+import { ImmutableMap } from '../util/immutable-map.js';
+import { maskedId } from '../util/text.js';
+import { defaultCountryCode } from './config.js';
+const categoriesByTens = [
+    'checking',
+    'savings',
+    'fixedDeposit',
+    'securities',
+    'loan',
+    'creditCard',
+    'fund',
+    'homeSavings',
+    'insurance',
+];
+/** The category of the FinTS account type `code`, which is `undefined` if the bank states none. */
+export function accountCategoryOf(code) {
+    if (code === undefined || code < 1)
+        return 'unknown';
+    return categoriesByTens[Math.floor(code / 10)] ?? 'other';
+}
+/** A bank account as reported by the user parameter data or the SEPA account query. */
+export class Account {
+    /** National account number. */
+    accountNumber;
+    /** Sub-account characteristic (Unterkontomerkmal). */
+    subAccount;
+    /** German bank code (BLZ) of the bank holding the account. */
+    bankCode;
+    /** Numeric country code of the bank, `280` for Germany. */
+    countryCode;
+    /** International bank account number. */
+    iban;
+    /** Bank identifier code of the bank holding the account. */
+    bic;
+    /** Customer ID the account is assigned to; may differ from the login name. */
+    customerId;
+    /** Currency of the account, for example `EUR`. */
+    currency;
+    /** Name of the account holder. */
+    ownerName;
+    /** The bank's name for the account, for example `Girokonto`. */
+    productName;
+    /** Raw FinTS account type (1–99); see `category`. */
+    typeCode;
+    /**
+     * The transactions the bank lists as permitted for this account, by their segment IDs, such as `HKSAL`.
+     *
+     * The client applies them itself: `getBalance` and `getTransactions` throw `FinTsUnsupportedError`, without asking
+     * the bank, where the parameter data rule the query out.
+     */
+    allowedTransactions;
+    /**
+     * Whether `allowedTransactions` is complete: the bank permits nothing it does not list (FinTS "UPD-Verwendung" 0).
+     * Otherwise the bank's lists say nothing about a transaction they leave out, and only the bank can tell.
+     */
+    allowedTransactionsComplete;
+    /** What the bank tells about the data it holds for the account, where it does. */
+    dataStatus;
+    constructor(init) {
+        this.accountNumber = init.accountNumber;
+        this.subAccount = init.subAccount;
+        this.bankCode = init.bankCode;
+        this.countryCode = init.countryCode ?? defaultCountryCode;
+        this.iban = init.iban;
+        this.bic = init.bic;
+        this.customerId = init.customerId;
+        this.currency = init.currency;
+        this.ownerName = init.ownerName;
+        this.productName = init.productName;
+        this.typeCode = init.typeCode;
+        this.allowedTransactions = Object.freeze([...(init.allowedTransactions ?? [])]);
+        this.allowedTransactionsComplete = init.allowedTransactionsComplete ?? false;
+        this.dataStatus = init.dataStatus;
+    }
+    /** The kind of account, derived from `typeCode`. */
+    get category() {
+        return accountCategoryOf(this.typeCode);
+    }
+    /**
+     * Whether `other` is the same account: by IBAN when both have one, otherwise by account number, sub-account and
+     * bank.
+     *
+     * Account numbers are compared without leading zeros, since banks pad them differently. An empty bank or country
+     * code, as of a balance record without bank identification, matches any.
+     */
+    matches(other) {
+        if (this.iban !== undefined && other.iban !== undefined)
+            return this.iban === other.iban;
+        const number = this.accountNumber?.replace(/^0+/, '');
+        return (number !== undefined &&
+            number === other.accountNumber?.replace(/^0+/, '') &&
+            (this.subAccount ?? '') === (other.subAccount ?? '') &&
+            sameOrUnstated(this.bankCode, other.bankCode) &&
+            sameOrUnstated(this.countryCode, other.countryCode));
+    }
+    /** This account with the given details replaced; a detail that is `undefined` stays as it is. */
+    copyWith(changes) {
+        return new Account({
+            accountNumber: changes.accountNumber ?? this.accountNumber,
+            subAccount: changes.subAccount ?? this.subAccount,
+            bankCode: this.bankCode,
+            countryCode: this.countryCode,
+            iban: changes.iban ?? this.iban,
+            bic: changes.bic ?? this.bic,
+            customerId: changes.customerId ?? this.customerId,
+            currency: changes.currency ?? this.currency,
+            ownerName: changes.ownerName ?? this.ownerName,
+            productName: changes.productName ?? this.productName,
+            typeCode: changes.typeCode ?? this.typeCode,
+            allowedTransactions: changes.allowedTransactions ?? this.allowedTransactions,
+            allowedTransactionsComplete: changes.allowedTransactionsComplete ?? this.allowedTransactionsComplete,
+            dataStatus: changes.dataStatus ?? this.dataStatus,
+        });
+    }
+    /**
+     * The product name and the last digits of the IBAN or account number only, so that logs and crash reports do not
+     * collect account data.
+     */
+    toString() {
+        const id = this.iban ?? this.accountNumber;
+        const parts = [
+            ...(id === undefined ? [] : [maskedId(id)]),
+            ...(this.productName === undefined ? [] : [this.productName]),
+        ];
+        return `Account(${parts.join(', ')})`;
+    }
+}
+function sameOrUnstated(a, b) {
+    return a === '' || b === '' || a === b;
+}
+/**
+ * What the bank tells about the data it holds for an account, so that an app asks only for what has changed (FinTS 3.0
+ * user parameter data, "Erweiterung, kontobezogen", Formals E.3.1 and F).
+ *
+ * The rules are binding for an app that stores transactions; banks may refuse an app that ignores them:
+ * - Do not fetch the transactions again while the bank names the ID they were stored with (`mt940TransactionsId` or
+ *   `camtTransactionsId`, for the format the app asked for, so pass `format` to `getTransactions` explicitly), or, in
+ *   the older format, the timestamp `lastTransactions`.
+ * - Do not fetch them before `nextTransactionsAt`.
+ * - Do not ask for the balance separately where `transactionBalancesCurrent` says that the transactions carry the
+ *   current one.
+ */
+export class AccountDataStatus {
+    /**
+     * IDs of the data the bank holds for the user, keyed by the segment ID of the query that fetches them, for example
+     * `HKKAZ` (transactions as MT940) or `HKCAZ` (as camt): the data have changed when the ID changes. An empty ID means
+     * that the user has no such data; a query the map leaves out, that the bank tells nothing about it.
+     */
+    inventory;
+    /**
+     * The timestamp of the last transactions the bank provided, in the older format of the extension (`umsltzt`);
+     * compared like an ID in `inventory`.
+     */
+    lastTransactions;
+    /** The moment before which the bank provides no new transactions. */
+    nextTransactionsAt;
+    /** Whether the balances the transactions carry are the current ones. */
+    transactionBalancesCurrent;
+    constructor(init) {
+        this.inventory = new ImmutableMap(init.inventory ?? []);
+        this.lastTransactions = init.lastTransactions;
+        this.nextTransactionsAt = init.nextTransactionsAt;
+        this.transactionBalancesCurrent = init.transactionBalancesCurrent ?? false;
+    }
+    /** The ID of the transactions the bank holds as MT940, its entry for `HKKAZ` in `inventory`. */
+    get mt940TransactionsId() {
+        return this.inventory.get('HKKAZ');
+    }
+    /** The ID of the transactions the bank holds as camt, its entry for `HKCAZ` in `inventory`. */
+    get camtTransactionsId() {
+        return this.inventory.get('HKCAZ');
+    }
+}
+//# sourceMappingURL=account.js.map

package/dist/core/account.js.map

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

package/dist/core/amount.d.ts

@@ -0,0 +1,62 @@
+/** A money amount stored as an integer number of `scale`-digit minor units. */
+export declare class Amount {
+    /** The amount in units of 10^-`scale` of the currency, negative for a debit: 1234 with scale 2 is 12.34. */
+    readonly minorUnits: number;
+    /** Number of decimal places `minorUnits` has, from 0 to 5. */
+    readonly scale: number;
+    /** ISO 4217 currency code, for example `EUR`. */
+    readonly currency: string;
+    /**
+     * An amount of `minorUnits` with `scale` decimal places; throws `RangeError` for a `scale` outside 0 to 5, and for
+     * `minorUnits` that are no integer or beyond 2^53 - 1 in either direction, about 90 trillion at two decimal places.
+     */
+    constructor(minorUnits: number, scale: number, currency: string);
+    /**
+     * Parses a number as banks send it: digits with at most one decimal separator, `,` (FinTS 3.0, MT940) or `.` (camt),
+     * and no thousands separators.
+     *
+     * The amount has the decimal places of the `currency`'s minor unit (ISO 4217): two for most currencies, none for
+     * `JPY`, three for `KWD`. It has more where the value has more significant digits. So `100,` in `EUR` is `100.00`, in
+     * `JPY` `100`.
+     *
+     * Throws `FormatError` for anything else, so that `1.234,56` in bank data is an error, not a guess, and for more than
+     * five decimal places (trailing zeros aside) or more than 15 digits.
+     */
+    static parseDecimal(value: string, currency: string): Amount;
+    /** The amount as a floating-point number, which cannot hold every decimal fraction exactly; do not calculate with it. */
+    get value(): number;
+    /** Whether the amount is below zero. */
+    get isNegative(): boolean;
+    /** Whether the amount is zero. */
+    get isZero(): boolean;
+    /** This amount with the opposite sign. */
+    negate(): Amount;
+    /** This amount without its sign. */
+    abs(): Amount;
+    /**
+     * The sum with `other`, at the larger of the two scales; throws `TypeError` for another currency and `RangeError` for
+     * a sum beyond what an amount holds.
+     */
+    add(other: Amount): Amount;
+    /** The difference to `other`; throws `TypeError` for another currency. */
+    subtract(other: Amount): Amount;
+    /** Compares by value, whatever the scales; throws `TypeError` for another currency. */
+    compareTo(other: Amount): number;
+    /** Whether `other` is the same amount in the same currency, whatever the `scale`: 1.50 equals 1.500. */
+    equals(other: unknown): boolean;
+    /** Formats the amount without currency, for example `-12.50`. */
+    toDecimalString(decimalSeparator?: string): string;
+    toString(): string;
+    /** The minor units of both amounts at the larger scale, as `bigint`s, since the factor could leave the safe range. */
+    private atCommonScale;
+    private rescale;
+    private compareValue;
+    private checkCurrency;
+}
+/**
+ * `amount` as a credit (unchanged) or a debit (negated), by the bank's credit/debit `mark`.
+ *
+ * Throws `FormatError` for any other `mark`, `undefined` included: a missing mark must not be read as a credit.
+ */
+export declare function withMark(amount: Amount, mark: string | undefined, credit: string, debit: string): Amount;
+//# sourceMappingURL=amount.d.ts.map

package/dist/core/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../src/core/amount.ts"],"names":[],"mappings":"AAmDA,+EAA+E;AAC/E,qBAAa,MAAM;IACjB,4GAA4G;IAC5G,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;gBACS,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAW/D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAmB5D,yHAAyH;IACzH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,wCAAwC;IACxC,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,kCAAkC;IAClC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,0CAA0C;IAC1C,MAAM,IAAI,MAAM;IAIhB,oCAAoC;IACpC,GAAG,IAAI,MAAM;IAIb;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAU1B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI/B,uFAAuF;IACvF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAKhC,wGAAwG;IACxG,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAI/B,iEAAiE;IACjE,eAAe,CAAC,gBAAgB,SAAM,GAAG,MAAM;IAU/C,QAAQ,IAAI,MAAM;IAIlB,sHAAsH;IACtH,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,aAAa;CAItB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxG"}