@coderoftime/fints 0.0.0-stage → 0.1.0

package/src/util/dates.ts

@@ -0,0 +1,193 @@
+// A value is either a calendar date, a local `Date` at midnight of which only the day counts, or the exact moment of a
+// date with a time of day, which the bank states in German time (see `germanTime`). The parsers keep the two apart: a
+// date without a valid time of day is not a moment.
+
+const hourMs = 3_600_000;
+
+function twoDigits(n: number): string {
+  return n.toString().padStart(2, '0');
+}
+
+function year(d: Date): string {
+  return d.getFullYear().toString().padStart(4, '0');
+}
+
+/** `YYYYMMDD`, the FinTS 3.0 date format. */
+export function formatFintsDate(d: Date): string {
+  return `${year(d)}${twoDigits(d.getMonth() + 1)}${twoDigits(d.getDate())}`;
+}
+
+/** `HHMMSS`, the FinTS 3.0 time format. */
+export function formatFintsTime(d: Date): string {
+  return `${twoDigits(d.getHours())}${twoDigits(d.getMinutes())}${twoDigits(d.getSeconds())}`;
+}
+
+/** `YYYY-MM-DD`, the ISO 8601 date format of camt. */
+export function formatIsoDate(d: Date): string {
+  return `${year(d)}-${twoDigits(d.getMonth() + 1)}-${twoDigits(d.getDate())}`;
+}
+
+const fintsDate = /^(\d{4})(\d{2})(\d{2})$/;
+const fintsTime = /^(\d{2})(\d{2})(\d{2})/;
+const isoDate = /^(\d{4})-(\d{2})-(\d{2})/;
+const isoTime = /^(\d{2}):(\d{2}):(\d{2})/;
+
+/** Parses a FinTS 3.0 date `YYYYMMDD` as a calendar date; `undefined` if it is missing or invalid. */
+export function parseFintsDate(date: string | undefined): Date | undefined {
+  return parseDate(fintsDate, date);
+}
+
+/**
+ * Parses a FinTS 3.0 date `YYYYMMDD` and time `HHMMSS` as the moment they name; `undefined` if either is missing or
+ * invalid.
+ */
+export function parseFintsDateTime(date: string | undefined, time: string | undefined): Date | undefined {
+  return moment(parseDate(fintsDate, date), fintsTime, time);
+}
+
+/**
+ * Parses an ISO 8601 date `YYYY-MM-DD` as a calendar date, ignoring extra characters such as a time part; `undefined`
+ * if it is missing or invalid.
+ */
+export function parseIsoDate(date: string | undefined): Date | undefined {
+  return parseDate(isoDate, date);
+}
+
+/** Parses an ISO 8601 date `YYYY-MM-DD` and time `HH:MM:SS` as the moment they name. */
+export function parseIsoDateTime(date: string | undefined, time: string | undefined): Date | undefined {
+  return moment(parseDate(isoDate, date), isoTime, time);
+}
+
+function parseDate(pattern: RegExp, date: string | undefined): Date | undefined {
+  const d = date === undefined ? null : pattern.exec(date);
+  return d ? validDate(Number(d[1]), Number(d[2]), Number(d[3])) : undefined;
+}
+
+/** The moment of the German time matched by `timePattern` in `time` on `day`. */
+function moment(day: Date | undefined, timePattern: RegExp, time: string | undefined): Date | undefined {
+  const t = time === undefined ? null : timePattern.exec(time);
+  if (day === undefined || !t) return undefined;
+  const [hour, minute, second] = [Number(t[1]), Number(t[2]), Number(t[3])];
+  if (hour > 23 || minute > 59 || second > 59) return undefined;
+  return germanTime(day.getFullYear(), day.getMonth() + 1, day.getDate(), hour, minute, second);
+}
+
+/**
+ * Parses a FinTS 3.0 date `YYYYMMDD` and time `HHMMSS` given in UTC+01:00 all year round, as the account extension of
+ * the user parameter data states its times (Formals E.3.1); `undefined` if either is missing or invalid. A time with
+ * fewer than six digits lost its leading zeros as a JSON number.
+ */
+export function parseUtcPlusOneDateTime(date: string | undefined, time: string | undefined): Date | undefined {
+  const day = parseDate(fintsDate, date);
+  const t = time === undefined ? null : fintsTime.exec(time.padStart(6, '0'));
+  if (day === undefined || !t) return undefined;
+  const [hour, minute, second] = [Number(t[1]), Number(t[2]), Number(t[3])];
+  if (hour > 23 || minute > 59 || second > 59) return undefined;
+  return new Date(utc(day.getFullYear(), day.getMonth() + 1, day.getDate(), hour, minute, second) - hourMs);
+}
+
+/**
+ * The moment a German clock shows the given time.
+ *
+ * German time is CET (UTC+1), and CEST (UTC+2) from 01:00 UTC on the last Sunday of March to 01:00 UTC on the last
+ * Sunday of October (the EU rule). The hour the clocks show twice in October counts as CEST; a time in the hour that is
+ * skipped in March counts as CET.
+ */
+export function germanTime(
+  year: number,
+  month: number,
+  day: number,
+  hour: number,
+  minute: number,
+  second: number,
+): Date {
+  const clock = utc(year, month, day, hour, minute, second);
+  const summer = clock - 2 * hourMs;
+  return new Date(isSummerTime(summer) ? summer : clock - hourMs);
+}
+
+/** The calendar day a German clock shows at `moment`, as a local `Date` at midnight like every calendar date. */
+export function germanDay(moment: Date): Date {
+  const utcMs = moment.getTime();
+  const clock = new Date(utcMs + (isSummerTime(utcMs) ? 2 : 1) * hourMs);
+  return localDate(clock.getUTCFullYear(), clock.getUTCMonth() + 1, clock.getUTCDate());
+}
+
+function isSummerTime(utcMs: number): boolean {
+  const y = new Date(utcMs).getUTCFullYear();
+  return utcMs >= clockChange(y, 3) && utcMs < clockChange(y, 10);
+}
+
+/** 01:00 UTC on the last Sunday of `month`, when the EU changes the clocks. */
+function clockChange(year: number, month: number): number {
+  const lastDay = daysInMonth(year, month);
+  const weekday = new Date(utc(year, month, lastDay, 0, 0, 0)).getUTCDay();
+  return utc(year, month, lastDay - weekday, 1, 0, 0);
+}
+
+/** Milliseconds since the epoch of the UTC time; `month` counts from 1, and years below 100 are not moved to 19xx. */
+function utc(year: number, month: number, day: number, hour: number, minute: number, second: number): number {
+  const d = new Date(0);
+  d.setUTCFullYear(year, month - 1, day);
+  d.setUTCHours(hour, minute, second, 0);
+  return d.getTime();
+}
+
+/** Local midnight of the day; `month` counts from 1, and years below 100 are not moved to 19xx. */
+export function localDate(year: number, month: number, day: number): Date {
+  const d = new Date(0);
+  d.setFullYear(year, month - 1, day);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}
+
+/** The date, or `undefined` if `month` or `day` is out of range; `Date` would roll it over into another date. */
+export function validDate(year: number, month: number, day: number): Date | undefined {
+  if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) return undefined;
+  return localDate(year, month, day);
+}
+
+/**
+ * The date, with a day beyond the end of the month moved to its last day: banks write 30 February or 31 April for
+ * month-end bookings. `undefined` for a month or day that no month has.
+ */
+export function clampedDate(year: number, month: number, day: number): Date | undefined {
+  if (month < 1 || month > 12 || day < 1 || day > 31) return undefined;
+  return validDate(year, month, day) ?? localDate(year, month, daysInMonth(year, month));
+}
+
+const swiftDate = /^(\d{2})(\d{2})(\d{2})$/;
+
+/**
+ * Parses a SWIFT date `YYMMDD`, as MT940 writes it, with month ends as `clampedDate` reads them; years from 80 on count
+ * as 19xx. `undefined` if the date is invalid.
+ */
+export function parseSwiftDate(yymmdd: string): Date | undefined {
+  const m = swiftDate.exec(yymmdd);
+  if (!m) return undefined;
+  const yy = Number(m[1]);
+  return clampedDate(yy >= 80 ? 1900 + yy : 2000 + yy, Number(m[2]), Number(m[3]));
+}
+
+/** Number of days the `month` (1 to 12) of `year` has. */
+export function daysInMonth(year: number, month: number): number {
+  if (month === 2) return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28;
+  return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+
+/** The calendar day `moment` falls on in local time, as a local `Date` at midnight. */
+export function calendarDay(moment: Date): Date {
+  return localDate(moment.getFullYear(), moment.getMonth() + 1, moment.getDate());
+}
+
+/**
+ * The calendar `day`, moved back to the bank's today if it lies after it: banks reject future dates in queries.
+ *
+ * The bank's today is the German day at `now`, the current time by default; east of Germany the local day starts
+ * earlier.
+ */
+export function notAfterToday(day: Date | undefined, now: Date = new Date()): Date | undefined {
+  if (day === undefined) return undefined;
+  const today = germanDay(now);
+  return day.getTime() > today.getTime() ? today : day;
+}

package/src/util/errors.ts

@@ -0,0 +1,16 @@
+/** Data that do not have the expected format, such as a malformed MT940 line or amount. */
+export class FormatError extends Error {
+  /** The part of the data that is malformed, where the parser can tell it. */
+  readonly source: string | undefined;
+
+  constructor(message: string, source?: string) {
+    super(source === undefined ? message : `${message}: ${source}`);
+    this.name = 'FormatError';
+    this.source = 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,51 @@
+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 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 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,82 @@
+import { base64Decode, 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. */
+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;
+  if (content.every((b) => b < 0x80)) return latin1Decode(content);
+  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. */
+export function decodeWindows1252(bytes: Uint8Array): string {
+  let text = '';
+  for (const b of bytes) text += String.fromCharCode(b >= 0x80 && b < 0xa0 ? windows1252High[b - 0x80]! : b);
+  return text;
+}
+
+/**
+ * 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)}`;
+}
+
+/** `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));
+}
+
+/** `text` with every match of `pattern`, a literal string, escaped for use in a regular expression. */
+export function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\/-]/g, '\\$&');
+}
+
+/** 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,172 @@
+import { FormatError } from './errors.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.childElements.find((c) => 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 {
+    const text = this.at(path)?.innerText.trim();
+    return text === undefined || text === '' ? undefined : text;
+  }
+
+  /** All elements below this one called `localName`, in document order. */
+  descendantsNamed(localName: string): XmlElement[] {
+    const found: XmlElement[] = [];
+    const visit = (element: XmlElement): void => {
+      for (const c of element.childElements) {
+        if (c.localName === localName) found.push(c);
+        visit(c);
+      }
+    };
+    visit(this);
+    return found;
+  }
+}
+
+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: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+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 hex = name.startsWith('#x');
+      const digits = name.substring(hex ? 2 : 1);
+      const code = (hex ? /^[0-9a-fA-F]+$/ : /^\d+$/).test(digits) ? parseInt(digits, hex ? 16 : 10) : NaN;
+      if (!(code > 0 && code <= 0x10ffff && (code < 0xd800 || code > 0xdfff))) {
+        throw new FormatError('Invalid XML character reference', match);
+      }
+      return String.fromCodePoint(code);
+    }
+    const value = predefinedEntities[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.
+ *
+ * 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;
+
+  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 {
+      position++;
+      const name = matchAt(namePattern, xml, position)?.[0] ?? fail('missing element name');
+      position += name.length;
+      const attributes = new Map<string, string>();
+      for (;;) {
+        const attribute = matchAt(attributePattern, xml, position);
+        if (!attribute) break;
+        position += attribute[0].length;
+        const attributeName = attribute[1]!;
+        if (attributeName !== 'xmlns' && !attributeName.startsWith('xmlns:')) {
+          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);
+      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');
+}