@coderoftime/fints 0.0.0-stage → 0.2.0

package/src/util/errors.ts

@@ -0,0 +1,27 @@
+/**
+ * Data that do not have the expected format, such as a malformed MT940 line or amount.
+ *
+ * The message leaves out `source`, which may hold account data, such as amounts, names and IBANs, so that logs and
+ * crash reports do not collect them.
+ */
+export class FormatError extends Error {
+  override name = 'FormatError';
+
+  /** The part of the data that is malformed, where the parser can tell it. */
+  readonly source: string | undefined;
+
+  constructor(message: string, source?: string) {
+    super(message);
+    this.source = source;
+  }
+}
+
+/** Throws a `FormatError`, where an expression is expected, such as `value ?? fail('…')`. */
+export function fail(message: string, source?: string): never {
+  throw new FormatError(message, source);
+}
+
+/** An argument the function cannot work with, such as an empty PIN. The message never contains a PIN. */
+export function invalidArgument(message: string, name?: string): TypeError {
+  return new TypeError(name === undefined ? message : `Invalid argument (${name}): ${message}`);
+}

package/src/util/immutable-map.ts

@@ -0,0 +1,47 @@
+/** A map that cannot be changed, also not at runtime: it has no `set`, `delete` or `clear`. */
+export class ImmutableMap<K, V> implements ReadonlyMap<K, V> {
+  private readonly map: Map<K, V>;
+
+  constructor(entries?: Iterable<readonly [K, V]>) {
+    this.map = new Map(entries);
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  get(key: K): V | undefined {
+    return this.map.get(key);
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  forEach(callback: (value: V, key: K, map: ReadonlyMap<K, V>) => void): void {
+    this.map.forEach((value, key) => {
+      callback(value, key, this);
+    });
+  }
+
+  entries(): MapIterator<[K, V]> {
+    return this.map.entries();
+  }
+
+  keys(): MapIterator<K> {
+    return this.map.keys();
+  }
+
+  values(): MapIterator<V> {
+    return this.map.values();
+  }
+
+  [Symbol.iterator](): MapIterator<[K, V]> {
+    return this.map.entries();
+  }
+
+  /** A plain object of the entries, for JSON and for display. */
+  toJSON(): Record<string, V> {
+    return Object.fromEntries([...this.map].map(([key, value]) => [String(key), value]));
+  }
+}

package/src/util/json.ts

@@ -0,0 +1,67 @@
+import { FormatError } from './errors.js';
+
+/** A JSON object read from a saved state. */
+export type JsonObject = Record<string, unknown>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The optional string at `key`; throws `FormatError` for a value of another type. */
+export function readOptionalString(json: JsonObject, key: string): string | undefined {
+  const value = json[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') throw new FormatError(`Saved state: "${key}" is not a string`);
+  return value;
+}
+
+/** The optional integer at `key`; throws `FormatError` for a value of another type. */
+export function readOptionalInt(json: JsonObject, key: string): number | undefined {
+  const value = json[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new FormatError(`Saved state: "${key}" is not an integer`);
+  }
+  return value;
+}
+
+/** The optional boolean at `key`; throws `FormatError` for a value of another type. */
+export function readOptionalBoolean(json: JsonObject, key: string): boolean | undefined {
+  const value = json[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'boolean') throw new FormatError(`Saved state: "${key}" is not a boolean`);
+  return value;
+}
+
+/** The object at `key`; throws `FormatError` if it is missing or not an object. */
+export function readObject(json: JsonObject, key: string): JsonObject {
+  const value = json[key];
+  if (!isJsonObject(value)) throw new FormatError(`Saved state: "${key}" is not an object`);
+  return value;
+}
+
+/** The optional object at `key`; throws `FormatError` for a value of another type. */
+export function readOptionalObject(json: JsonObject, key: string): JsonObject | undefined {
+  const value = json[key];
+  if (value === undefined || value === null) return undefined;
+  if (!isJsonObject(value)) throw new FormatError(`Saved state: "${key}" is not an object`);
+  return value;
+}
+
+/** The optional list at `key`, each element checked by `isElement`; throws `FormatError` for anything else. */
+export function readOptionalList<T>(
+  json: JsonObject,
+  key: string,
+  isElement: (value: unknown) => value is T,
+): T[] | undefined {
+  const value = json[key];
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value) || !value.every(isElement)) {
+    throw new FormatError(`Saved state: "${key}" is not a list of the expected values`);
+  }
+  return value;
+}
+
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}

package/src/util/text.ts

@@ -0,0 +1,112 @@
+import { base64Decode, fromCharCodes, latin1Decode, utf8Decode } from './bytes.js';
+import { FormatError } from './errors.js';
+
+const xmlEncodingDeclaration = /encoding\s*=\s*["']([A-Za-z0-9._-]+)["']/;
+const whitespace = /\s/g;
+
+/**
+ * Decodes text from the bank, which may be UTF-8 (with or without BOM) or ISO 8859-1; ASCII reads the same in both.
+ *
+ * UTF-8 comes first, since some banks send it. ISO 8859-1 text that happens to be valid UTF-8, such as `ß°`, reads as
+ * UTF-8 then: a rare misreading of text shown, as values sent back to the bank are read byte for byte
+ * (`Segment.verbatim`).
+ */
+export function decodeBankText(bytes: Uint8Array): string {
+  const hasBom = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+  const content = hasBom ? bytes.subarray(3) : bytes;
+  try {
+    return utf8Decode(content);
+  } catch (error) {
+    if (!(error instanceof FormatError)) throw error;
+    return hasBom ? utf8Decode(content, true) : latin1Decode(content);
+  }
+}
+
+/** Decodes an XML document, honouring an ISO 8859-1 or Windows-1252 encoding declaration. */
+export function decodeXmlText(bytes: Uint8Array): string {
+  const head = latin1Decode(bytes.length > 200 ? bytes.subarray(0, 200) : bytes);
+  switch (xmlEncodingDeclaration.exec(head)?.[1]?.toLowerCase()) {
+    case 'windows-1252':
+    case 'cp1252':
+      return decodeWindows1252(bytes);
+    case 'iso-8859-1':
+    case 'iso8859-1':
+    case 'latin1':
+    case 'latin-1':
+      return latin1Decode(bytes);
+    default:
+      return decodeBankText(bytes);
+  }
+}
+
+/**
+ * The code points of the Windows-1252 bytes 0x80 to 0x9F, where ISO 8859-1 has control characters; the five unassigned
+ * bytes keep their code.
+ */
+const windows1252High = [
+  0x20ac, 0x0081, 0x201a, 0x0192, 0x201e, 0x2026, 0x2020, 0x2021, 0x02c6, 0x2030, 0x0160, 0x2039, 0x0152, 0x008d,
+  0x017d, 0x008f, 0x0090, 0x2018, 0x2019, 0x201c, 0x201d, 0x2022, 0x2013, 0x2014, 0x02dc, 0x2122, 0x0161, 0x203a,
+  0x0153, 0x009d, 0x017e, 0x0178,
+];
+
+/**
+ * Decodes Windows-1252, which matches ISO 8859-1 except for `€`, typographic quotes and a few letters.
+ *
+ * @internal Exported for the tests.
+ */
+export function decodeWindows1252(bytes: Uint8Array): string {
+  const codes = new Uint16Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i]!;
+    codes[i] = b >= 0x80 && b < 0xa0 ? windows1252High[b - 0x80]! : b;
+  }
+  return fromCharCodes(codes);
+}
+
+/**
+ * The last four characters of `id`, such as an IBAN or a card number, after an ellipsis: enough to tell two apart, too
+ * little to identify one in a log.
+ */
+export function maskedId(id: string): string {
+  return id.length <= 4 ? '…' : `…${id.substring(id.length - 4)}`;
+}
+
+/** Whether `value` fits into ISO 8859-1, the FinTS 3.0 character set. */
+export function isLatin1(value: string): boolean {
+  for (let i = 0; i < value.length; i++) if (value.charCodeAt(i) > 0xff) return false;
+  return true;
+}
+
+/** `text` without blanks around it; `undefined` if that leaves nothing. */
+export function nonBlank(text: string | undefined): string | undefined {
+  const trimmed = text?.trim();
+  return trimmed === '' ? undefined : trimmed;
+}
+
+/**
+ * The character the numeric character reference `name` names, such as `#x41` or `#65`; `undefined` for any other name,
+ * and for a number that is no character as XML defines them: `NUL`, half a surrogate pair, or beyond Unicode.
+ */
+export function characterReference(name: string): string | undefined {
+  const m = /^#(?:x([0-9a-fA-F]+)|([0-9]+))$/.exec(name);
+  if (!m) return undefined;
+  const code = m[1] === undefined ? parseInt(m[2]!, 10) : parseInt(m[1], 16);
+  return code > 0 && (code < 0xd800 || code > 0xdfff) && code <= 0x10ffff ? String.fromCodePoint(code) : undefined;
+}
+
+/** `text` without spaces and line breaks. */
+export function withoutWhitespace(text: string): string {
+  return text.replace(whitespace, '');
+}
+
+/** Decodes base64 that may be broken into lines; throws `FormatError` if it is invalid. */
+export function decodeBase64Lines(text: string): Uint8Array {
+  return base64Decode(withoutWhitespace(text));
+}
+
+/** The integer `text` states, decimal digits with an optional sign and blanks around; `undefined` for anything else. */
+export function tryParseInt(text: string | undefined): number | undefined {
+  if (text === undefined) return undefined;
+  const match = /^\s*([+-]?\d+)\s*$/.exec(text);
+  return match ? Number(match[1]) : undefined;
+}

package/src/util/xml.ts

@@ -0,0 +1,183 @@
+import { FormatError } from './errors.js';
+import { characterReference, nonBlank } from './text.js';
+
+/**
+ * An element of a parsed XML document, looked up by local name: camt documents come with and without namespace
+ * prefixes.
+ */
+export class XmlElement {
+  readonly children: (XmlElement | string)[] = [];
+
+  constructor(
+    /** The name without namespace prefix. */
+    readonly localName: string,
+    /** The attributes by name without namespace prefix; namespace declarations are left out. */
+    readonly attributes: ReadonlyMap<string, string>,
+  ) {}
+
+  get childElements(): XmlElement[] {
+    return this.children.filter((c): c is XmlElement => c instanceof XmlElement);
+  }
+
+  /** The text of this element and all below it. */
+  get innerText(): string {
+    return this.children.map((c) => (c instanceof XmlElement ? c.innerText : c)).join('');
+  }
+
+  getAttribute(localName: string): string | undefined {
+    return this.attributes.get(localName);
+  }
+
+  /** The first child element called `localName`. */
+  child(localName: string): XmlElement | undefined {
+    return this.children.find((c): c is XmlElement => c instanceof XmlElement && c.localName === localName);
+  }
+
+  /** The element reached by following child names along `path`; this element for an empty path. */
+  at(path: readonly string[]): XmlElement | undefined {
+    return path.reduce<XmlElement | undefined>((element, name) => element?.child(name), this);
+  }
+
+  /** The trimmed text of the element at `path`, or `undefined` if it is missing or empty. */
+  textAt(path: readonly string[]): string | undefined {
+    return nonBlank(this.at(path)?.innerText);
+  }
+
+  /** The child elements called `localName`, in document order. */
+  childrenNamed(localName: string): XmlElement[] {
+    return this.children.filter((c): c is XmlElement => c instanceof XmlElement && c.localName === localName);
+  }
+}
+
+const namePattern = /[^\s<>/=!?"']+/y;
+const attributePattern = /\s+([^\s<>/=!?"']+)\s*=\s*(?:"([^"<]*)"|'([^'<]*)')/y;
+
+/** The match of the sticky `pattern` at `position` in `text`. */
+function matchAt(pattern: RegExp, text: string, position: number): RegExpExecArray | null {
+  pattern.lastIndex = position;
+  return pattern.exec(text);
+}
+const predefinedEntities = new Map([
+  ['amp', '&'],
+  ['lt', '<'],
+  ['gt', '>'],
+  ['quot', '"'],
+  ['apos', "'"],
+]);
+
+/** Deepest nesting of elements the parser takes: camt needs fewer than 20 levels, and `innerText` recurses. */
+const maxDepth = 256;
+
+/**
+ * Most elements and attributes one document may hold. Real camt spends about 20 bytes on each, so the largest answer a
+ * bank can send holds fewer than 600,000, while a hostile document stays within about 150 MB of memory.
+ */
+const maxNodes = 1_000_000;
+
+const noAttributes: ReadonlyMap<string, string> = new Map();
+
+function localNameOf(qualified: string): string {
+  const colon = qualified.indexOf(':');
+  return colon < 0 ? qualified : qualified.substring(colon + 1);
+}
+
+/** Resolves the character and predefined entity references in `text`; throws `FormatError` for any other. */
+function decodeEntities(text: string): string {
+  return text.replace(/&([^;&\s]*);?/g, (match, name: string) => {
+    if (!match.endsWith(';')) throw new FormatError('Invalid XML: unterminated entity reference');
+    if (name.startsWith('#')) {
+      const character = characterReference(name);
+      if (character === undefined) throw new FormatError('Invalid XML character reference', match);
+      return character;
+    }
+    const value = predefinedEntities.get(name);
+    if (value === undefined) throw new FormatError('Invalid XML: unknown entity', match);
+    return value;
+  });
+}
+
+/**
+ * Parses an XML document and returns its root element; throws `FormatError` if it is not well-formed, nests elements
+ * deeper than 256 levels or holds more than a million elements and attributes.
+ *
+ * A document type declaration is refused: bank data have none, and its entities could expand without limit.
+ */
+export function parseXml(xml: string): XmlElement {
+  let position = 0;
+  const stack: XmlElement[] = [];
+  let root: XmlElement | undefined;
+  let nodes = 0;
+
+  const fail = (reason: string): never => {
+    throw new FormatError(`Invalid XML: ${reason} at position ${position}`);
+  };
+  const skipPast = (terminator: string, what: string): void => {
+    const end = xml.indexOf(terminator, position);
+    if (end < 0) fail(`unterminated ${what}`);
+    position = end + terminator.length;
+  };
+
+  while (position < xml.length) {
+    const lt = xml.indexOf('<', position);
+    const textEnd = lt < 0 ? xml.length : lt;
+    if (textEnd > position) {
+      const text = xml.substring(position, textEnd);
+      const parent = stack.at(-1);
+      if (parent) parent.children.push(decodeEntities(text));
+      else if (text.trim() !== '') fail('text outside the root element');
+      position = textEnd;
+      continue;
+    }
+    if (xml.startsWith('<?', position)) {
+      skipPast('?>', 'processing instruction');
+    } else if (xml.startsWith('<!--', position)) {
+      skipPast('-->', 'comment');
+    } else if (xml.startsWith('<![CDATA[', position)) {
+      const parent = stack.at(-1) ?? fail('CDATA outside the root element');
+      const start = position + 9;
+      skipPast(']]>', 'CDATA section');
+      parent.children.push(xml.substring(start, position - 3));
+    } else if (xml.startsWith('<!', position)) {
+      fail('document type declarations are not supported');
+    } else if (xml.startsWith('</', position)) {
+      position += 2;
+      const name = matchAt(namePattern, xml, position)?.[0] ?? fail('missing end tag name');
+      position += name.length;
+      while (/\s/.test(xml.charAt(position))) position++;
+      if (xml.charAt(position) !== '>') fail('malformed end tag');
+      position++;
+      const open = stack.pop();
+      if (open === undefined || open.localName !== localNameOf(name)) fail(`unexpected end tag ${name}`);
+    } else {
+      if (stack.length >= maxDepth) fail(`elements nested deeper than ${maxDepth} levels`);
+      if (++nodes > maxNodes) fail(`more than ${maxNodes} elements and attributes`);
+      position++;
+      const name = matchAt(namePattern, xml, position)?.[0] ?? fail('missing element name');
+      position += name.length;
+      let attributes: Map<string, string> | undefined;
+      for (;;) {
+        const attribute = matchAt(attributePattern, xml, position);
+        if (!attribute) break;
+        position += attribute[0].length;
+        if (++nodes > maxNodes) fail(`more than ${maxNodes} elements and attributes`);
+        const attributeName = attribute[1]!;
+        if (attributeName !== 'xmlns' && !attributeName.startsWith('xmlns:')) {
+          attributes ??= new Map();
+          attributes.set(localNameOf(attributeName), decodeEntities(attribute[2] ?? attribute[3] ?? ''));
+        }
+      }
+      while (/\s/.test(xml.charAt(position))) position++;
+      const selfClosing = xml.startsWith('/>', position);
+      if (!selfClosing && xml.charAt(position) !== '>') fail(`malformed start tag ${name}`);
+      position += selfClosing ? 2 : 1;
+      const element = new XmlElement(localNameOf(name), attributes ?? noAttributes);
+      const parent = stack.at(-1);
+      if (parent) parent.children.push(element);
+      else if (root) fail('a second root element');
+      else root = element;
+      if (!selfClosing) stack.push(element);
+    }
+  }
+  if (stack.length > 0) fail(`unclosed element ${stack.at(-1)!.localName}`);
+  return root ?? fail('no root element');
+}

package/src/v3/account-extension.ts

@@ -0,0 +1,185 @@
+// Internal to the package, and named after the FinTS specification. Documentation is where the meaning is not evident.
+
+import { AccountDataStatus, type Account } from '../core/account.js';
+import { Amount, withMark } from '../core/amount.js';
+import { Balance } from '../core/balance.js';
+import { parseFintsDate, parseUtcPlusOneDateTime } from '../util/dates.js';
+import { fail, FormatError } from '../util/errors.js';
+import { isJsonObject } from '../util/json.js';
+import { nonBlank } from '../util/text.js';
+
+/** A booked or pending balance of the extension: credit/debit mark, value, date and time. */
+interface Saldo {
+  readonly amount: Amount;
+  readonly date: Date;
+  readonly time: Date | undefined;
+}
+
+/** The balance of the extension (`AcctBal`, built like HISAL version 7), read without the account it belongs to. */
+interface AccountBalance {
+  readonly booked: Saldo;
+  readonly pending: Saldo | undefined;
+  readonly creditLine: Amount | undefined;
+  readonly available: Amount | undefined;
+  readonly used: Amount | undefined;
+  readonly overdraft: Amount | undefined;
+  readonly bookingDate: Date | undefined;
+  readonly bookingTime: Date | undefined;
+}
+
+/**
+ * The account extension of the user parameter data (HIUPD "Erweiterung, kontobezogen", Formals E.3.1): JSON with the
+ * BIC, the balance, and what the bank tells about the data it holds for the account.
+ */
+export class AccountExtension {
+  private constructor(
+    /** The BIC of the account, which spares the SEPA account list (Formals F.3.4). */
+    readonly bic: string | undefined,
+    /** What the bank tells about the account's data. */
+    readonly status: AccountDataStatus,
+    private readonly balance: AccountBalance | undefined,
+    /** Whether `balance` holds all a balance query would deliver (`BalComplete`). */
+    private readonly balanceComplete: boolean,
+  ) {}
+
+  /**
+   * Reads `json`; `undefined` if it is not a JSON object or any element is malformed, which voids the whole extension
+   * (Formals F.2, KF3).
+   */
+  static tryParse(json: string): AccountExtension | undefined {
+    try {
+      const decoded: unknown = JSON.parse(json);
+      return isJsonObject(decoded) ? AccountExtension.read(new Json(decoded)) : undefined;
+    } catch (error) {
+      if (error instanceof FormatError || error instanceof SyntaxError) return undefined;
+      throw error;
+    }
+  }
+
+  private static read(json: Json): AccountExtension {
+    const balance = json.object('AcctBal');
+    const next = json.object('AcctStatNext');
+    return new AccountExtension(
+      json.string('BIC'),
+      new AccountDataStatus({
+        inventory: json.object('Inventory')?.strings ?? new Map(),
+        lastTransactions: json.string('umsltzt'),
+        nextTransactionsAt: next === undefined ? undefined : moment(next, '000000'),
+        transactionBalancesCurrent: json.flag('BalStatAcct') || json.flag('BalStatAct'),
+      }),
+      balance === undefined ? undefined : readBalance(balance),
+      json.flag('BalComplete'),
+    );
+  }
+
+  /** The balance of `account`, where the extension holds all a balance query would deliver (Formals F.3.2). */
+  completeBalance(account: Account): Balance | undefined {
+    const b = this.balance;
+    if (b === undefined || !this.balanceComplete) return undefined;
+    return new Balance({
+      account,
+      productName: account.productName,
+      booked: b.booked.amount,
+      bookedAsOf: b.booked.date,
+      bookedAsOfTime: b.booked.time,
+      pending: b.pending?.amount,
+      creditLine: b.creditLine,
+      available: b.available,
+      used: b.used,
+      overdraft: b.overdraft,
+      bookingDate: b.bookingDate,
+      bookingTime: b.bookingTime,
+    });
+  }
+}
+
+function readBalance(json: Json): AccountBalance {
+  const currency = json.string('Cur') ?? fail('Extension balance without currency');
+  const amount = (key: string): Amount | undefined => {
+    const value = json.string(key);
+    return value === undefined ? undefined : Amount.parseDecimal(value, currency);
+  };
+  const saldo = (key: string): Saldo | undefined => {
+    const s = json.object(key);
+    if (s === undefined) return undefined;
+    const value = s.string('Val') ?? fail('Extension balance without value');
+    return {
+      amount: withMark(Amount.parseDecimal(value, currency), s.string('DebCrd'), 'C', 'D'),
+      date: parseFintsDate(s.string('Date')) ?? fail('Extension balance without date'),
+      time: moment(s),
+    };
+  };
+  const bookTime = json.object('BookTime');
+  return {
+    booked: saldo('CurValBal') ?? fail('Extension balance without booked balance'),
+    pending: saldo('InclPendTransBal'),
+    creditLine: amount('OverdraftLim'),
+    available: amount('AvailFunds'),
+    used: amount('AlrdyDrwnOnBal'),
+    overdraft: amount('OverDraft'),
+    bookingDate: bookTime === undefined ? undefined : parseFintsDate(bookTime.string('Date')),
+    bookingTime: bookTime === undefined ? undefined : moment(bookTime),
+  };
+}
+
+/**
+ * The moment of `Date` and `Time` in `json`, which the extension states in UTC+01:00 all year round; `undefined`
+ * without a time, unless `defaultTime` stands in for it.
+ */
+function moment(json: Json, defaultTime?: string): Date | undefined {
+  const time = json.string('Time') ?? defaultTime;
+  if (time === undefined) return undefined;
+  return parseUtcPlusOneDateTime(json.string('Date'), time) ?? fail('Extension date or time is malformed');
+}
+
+/**
+ * A JSON object of the extension, read by key without regard to case: the specification itself spells some keys
+ * differently (`OverDraftLim` and `OverdraftLim`). Values of the wrong type are a `FormatError`.
+ */
+class Json {
+  private readonly values = new Map<string, unknown>();
+
+  constructor(values: Record<string, unknown>) {
+    for (const [key, value] of Object.entries(values)) this.values.set(key.toLowerCase(), value);
+  }
+
+  private value(key: string): unknown {
+    return this.values.get(key.toLowerCase());
+  }
+
+  /** A string, or a number written as string: dates and times come as either. */
+  string(key: string): string | undefined {
+    const value = this.value(key);
+    if (value === undefined || value === null) return undefined;
+    if (typeof value === 'string') return nonBlank(value);
+    if (typeof value === 'number') return String(value);
+    throw new FormatError(`Extension element "${key}" is not text`);
+  }
+
+  flag(key: string): boolean {
+    const value = this.value(key);
+    if (value === undefined || value === null) return false;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') return value === 'J' || value.toLowerCase() === 'true';
+    throw new FormatError(`Extension element "${key}" is not a flag`);
+  }
+
+  object(key: string): Json | undefined {
+    const value = this.value(key);
+    if (value === undefined || value === null) return undefined;
+    if (isJsonObject(value)) return new Json(value);
+    throw new FormatError(`Extension element "${key}" is not an object`);
+  }
+
+  /** The object's values as strings, keyed in capitals, as segment IDs are written. */
+  get strings(): Map<string, string> {
+    const result = new Map<string, string>();
+    for (const [key, value] of this.values) {
+      if (value === null) result.set(key.toUpperCase(), '');
+      else if (typeof value === 'string') result.set(key.toUpperCase(), value);
+      else if (typeof value === 'number') result.set(key.toUpperCase(), String(value));
+      else throw new FormatError(`Extension element "${key}" is not text`);
+    }
+    return result;
+  }
+}