@open-nav/invoicing 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@open-nav/invoicing",
+  "version": "0.1.0",
+  "description": "Render Hungarian invoices as printable documents, and produce the tax authority data export",
+  "keywords": [
+    "nav",
+    "onlineszamla",
+    "hungary",
+    "invoice",
+    "szamla",
+    "adatexport",
+    "pdf"
+  ],
+  "license": "MIT",
+  "author": "open-nav contributors",
+  "homepage": "https://github.com/eshton/open-nav#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eshton/open-nav.git",
+    "directory": "packages/invoicing"
+  },
+  "bugs": "https://github.com/eshton/open-nav/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "pdfmake": "^0.3.11",
+    "@open-nav/core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

package/src/color.ts

@@ -0,0 +1,170 @@
+/**
+ * Colour conversion for the PDF engine.
+ *
+ * A browser accepts every CSS colour form; PDF does not — pdfkit understands
+ * hex and the CSS colour keywords. Converting here means a theme behaves the
+ * same whichever engine renders it, rather than silently losing a colour in
+ * one of them.
+ */
+
+/** CSS colour keywords, kept to the ones a document is plausibly styled with. */
+const KEYWORDS: Record<string, string> = {
+  black: '#000000',
+  white: '#ffffff',
+  red: '#ff0000',
+  green: '#008000',
+  blue: '#0000ff',
+  navy: '#000080',
+  teal: '#008080',
+  olive: '#808000',
+  purple: '#800080',
+  maroon: '#800000',
+  gray: '#808080',
+  grey: '#808080',
+  silver: '#c0c0c0',
+  orange: '#ffa500',
+  yellow: '#ffff00',
+  rebeccapurple: '#663399',
+  transparent: '#ffffff',
+};
+
+/**
+ * Convert any accepted theme colour to `#rrggbb`.
+ *
+ * Alpha is dropped: PDF has no per-colour alpha in this position, and a
+ * silently half-transparent rule is worse than an opaque one.
+ */
+export function toHexColor(value: string, fallback = '#000000'): string {
+  const input = value.trim().toLowerCase();
+
+  const keyword = KEYWORDS[input];
+  if (keyword) return keyword;
+
+  if (input.startsWith('#')) {
+    const digits = input.slice(1);
+    if (digits.length === 3 || digits.length === 4) {
+      const [r, g, b] = [...digits.slice(0, 3)];
+      return `#${r}${r}${g}${g}${b}${b}`;
+    }
+    if (digits.length === 6 || digits.length === 8) return `#${digits.slice(0, 6)}`;
+    return fallback;
+  }
+
+  const rgb = /^rgba?\(([^)]+)\)$/.exec(input);
+  if (rgb) {
+    const parts = splitComponents(rgb[1]!);
+    if (parts.length < 3) return fallback;
+    return hex(channel(parts[0]!), channel(parts[1]!), channel(parts[2]!));
+  }
+
+  const hsl = /^hsla?\(([^)]+)\)$/.exec(input);
+  if (hsl) {
+    const parts = splitComponents(hsl[1]!);
+    if (parts.length < 3) return fallback;
+    return hslToHex(angle(parts[0]!), percent(parts[1]!), percent(parts[2]!));
+  }
+
+  return fallback;
+}
+
+function splitComponents(body: string): string[] {
+  return body
+    .split(/[,\s/]+/)
+    .map((part) => part.trim())
+    .filter((part) => part !== '');
+}
+
+/** An rgb channel: 0-255, or a percentage. */
+function channel(part: string): number {
+  const value = part.endsWith('%')
+    ? (Number.parseFloat(part) / 100) * 255
+    : Number.parseFloat(part);
+  return clamp(Math.round(value), 0, 255);
+}
+
+function angle(part: string): number {
+  const value = Number.parseFloat(part);
+  return Number.isFinite(value) ? ((value % 360) + 360) % 360 : 0;
+}
+
+function percent(part: string): number {
+  const value = Number.parseFloat(part);
+  return clamp(Number.isFinite(value) ? value / 100 : 0, 0, 1);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+function hex(r: number, g: number, b: number): string {
+  return `#${[r, g, b].map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+}
+
+function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const sector = hue / 60;
+  const second = chroma * (1 - Math.abs((sector % 2) - 1));
+  const [r, g, b] =
+    sector < 1
+      ? [chroma, second, 0]
+      : sector < 2
+        ? [second, chroma, 0]
+        : sector < 3
+          ? [0, chroma, second]
+          : sector < 4
+            ? [0, second, chroma]
+            : sector < 5
+              ? [second, 0, chroma]
+              : [chroma, 0, second];
+  const offset = lightness - chroma / 2;
+  return hex(
+    Math.round((r + offset) * 255),
+    Math.round((g + offset) * 255),
+    Math.round((b + offset) * 255),
+  );
+}
+
+/** Units CSS uses that convert to PDF points without a layout context. */
+const UNIT_TO_POINTS: Record<string, number> = {
+  pt: 1,
+  px: 0.75,
+  pc: 12,
+  mm: 72 / 25.4,
+  cm: 72 / 2.54,
+  in: 72,
+};
+
+/**
+ * Convert a CSS length to PDF points.
+ *
+ * `em`, `rem` and `%` are relative to a layout that does not exist here, so
+ * they fall back rather than being guessed at.
+ */
+export function toPoints(value: string, fallback: number): number {
+  const match = /^([0-9.]+)([a-z%]*)$/.exec(value.trim());
+  if (!match) return fallback;
+  const size = Number.parseFloat(match[1]!);
+  if (!Number.isFinite(size)) return fallback;
+  const unit = match[2] === '' ? 'pt' : match[2]!;
+  const factor = UNIT_TO_POINTS[unit];
+  return factor === undefined ? fallback : size * factor;
+}
+
+/**
+ * Expand a CSS margin shorthand into PDF's `[left, top, right, bottom]`.
+ *
+ * CSS orders shorthand clockwise from the top; pdfmake starts at the left.
+ * Getting that wrong swaps the margins on a non-square page, which is exactly
+ * the kind of error nobody notices until something prints.
+ */
+export function toMargins(value: string, fallback: number): [number, number, number, number] {
+  const parts = value.trim().split(/\s+/).filter(Boolean);
+  const points = parts.map((part) => toPoints(part, fallback));
+  const [
+    top = fallback,
+    right = points[0] ?? fallback,
+    bottom = points[0] ?? fallback,
+    left = points[1] ?? points[0] ?? fallback,
+  ] = points;
+  return [left, top, right, bottom];
+}

package/src/export.ts

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { serializeDocument, type InvoiceData } from '@open-nav/core';
+
+/**
+ * The data export an invoicing program must be able to produce.
+ *
+ * Decree 23/2014. (VI. 30.) NGM requires every invoicing program to have a
+ * built-in "adóhatósági ellenőrzési adatszolgáltatás" function that exports
+ * the invoices issued in a given date range, or in a given invoice number
+ * range, as XML.
+ *
+ * Two structures are permitted. Annexes 2 and 3 of the decree define one
+ * (`szamla.xsd`); section 13/A(1) permits the other — the structure published
+ * for the online invoice data service, which is `invoiceData.xsd`. This
+ * implementation produces the second, because it is the same schema this
+ * project already generates, validates and round-trips against NAV's own
+ * sample documents.
+ *
+ * That choice belongs to the taxpayer, not to this library. If your auditor
+ * asks for the Annex 3 structure specifically, this export is not it.
+ */
+
+export interface DataExportSelection {
+  /** First issue date to include, inclusive, as `yyyy-mm-dd`. */
+  issueDateFrom?: string;
+  /** Last issue date to include, inclusive. */
+  issueDateTo?: string;
+  /** First invoice number to include, inclusive. */
+  invoiceNumberFrom?: string;
+  /** Last invoice number to include, inclusive. */
+  invoiceNumberTo?: string;
+}
+
+export interface DataExportOptions extends DataExportSelection {
+  /**
+   * How invoice numbers are ordered when a number range is given.
+   *
+   * The default compares digit runs numerically, so `2024/9` sorts before
+   * `2024/10`. Plain text ordering puts them the other way round and would
+   * silently drop invoices from the middle of a requested range — which is
+   * the kind of mistake an audit is precisely designed to find.
+   */
+  compareInvoiceNumbers?: (left: string, right: string) => number;
+  /** Injectable clock, so an export is reproducible in tests. */
+  now?: () => Date;
+}
+
+export interface ExportedFile {
+  /** Path within the export, e.g. `invoices/2024-000123.xml`. */
+  name: string;
+  contents: string;
+}
+
+export interface ExportedInvoice {
+  invoiceNumber: string;
+  invoiceIssueDate: string;
+  file: string;
+  /** SHA-256 of the file, so the export can be shown to be unaltered. */
+  sha256: string;
+}
+
+export interface DataExportManifest {
+  /** What was asked for. */
+  selection: DataExportSelection;
+  /** The structure used, and the provision that permits it. */
+  structure: {
+    schema: string;
+    namespace: string;
+    basis: string;
+  };
+  generatedAt: string;
+  invoiceCount: number;
+  invoices: ExportedInvoice[];
+}
+
+export interface DataExportResult {
+  /** Every file in the export, manifest included. */
+  files: ExportedFile[];
+  manifest: DataExportManifest;
+}
+
+/**
+ * Natural ordering for invoice numbers: digit runs compare as numbers.
+ *
+ * `2024/9` before `2024/10`, and `A-2` before `A-10`.
+ */
+export function compareInvoiceNumbersNaturally(left: string, right: string): number {
+  const chunk = /(\d+|\D+)/g;
+  const leftParts = left.match(chunk) ?? [];
+  const rightParts = right.match(chunk) ?? [];
+
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    const a = leftParts[index];
+    const b = rightParts[index];
+    if (a === undefined) return -1;
+    if (b === undefined) return 1;
+
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) {
+      // BigInt, because an invoice number can be longer than a safe integer.
+      const difference = BigInt(a) - BigInt(b);
+      if (difference !== 0n) return difference < 0n ? -1 : 1;
+      continue;
+    }
+    if (a !== b) return a < b ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Whether an invoice falls inside the requested selection. */
+export function isSelected(invoice: InvoiceData, options: DataExportOptions): boolean {
+  const compare = options.compareInvoiceNumbers ?? compareInvoiceNumbersNaturally;
+
+  if (options.issueDateFrom && invoice.invoiceIssueDate < options.issueDateFrom) return false;
+  if (options.issueDateTo && invoice.invoiceIssueDate > options.issueDateTo) return false;
+  if (options.invoiceNumberFrom && compare(invoice.invoiceNumber, options.invoiceNumberFrom) < 0) {
+    return false;
+  }
+  if (options.invoiceNumberTo && compare(invoice.invoiceNumber, options.invoiceNumberTo) > 0) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Build the export from a set of invoices.
+ *
+ * One XML file per invoice, plus a manifest recording what was selected and
+ * the SHA-256 of every file, so the export can later be shown to be the one
+ * that was produced.
+ */
+export function createDataExport(
+  invoices: InvoiceData[],
+  options: DataExportOptions = {},
+): DataExportResult {
+  const now = options.now ?? (() => new Date());
+  const compare = options.compareInvoiceNumbers ?? compareInvoiceNumbersNaturally;
+
+  const selected = invoices
+    .filter((invoice) => isSelected(invoice, options))
+    .sort((left, right) => compare(left.invoiceNumber, right.invoiceNumber));
+
+  const files: ExportedFile[] = [];
+  const entries: ExportedInvoice[] = [];
+  const usedNames = new Set<string>();
+
+  for (const invoice of selected) {
+    const name = uniqueName(`invoices/${safeFileName(invoice.invoiceNumber)}.xml`, usedNames);
+    const contents = serializeDocument('InvoiceData', invoice, { indent: '  ' });
+    files.push({ name, contents });
+    entries.push({
+      invoiceNumber: invoice.invoiceNumber,
+      invoiceIssueDate: invoice.invoiceIssueDate,
+      file: name,
+      sha256: createHash('sha256').update(contents, 'utf8').digest('hex'),
+    });
+  }
+
+  const selection: DataExportSelection = {
+    ...(options.issueDateFrom ? { issueDateFrom: options.issueDateFrom } : {}),
+    ...(options.issueDateTo ? { issueDateTo: options.issueDateTo } : {}),
+    ...(options.invoiceNumberFrom ? { invoiceNumberFrom: options.invoiceNumberFrom } : {}),
+    ...(options.invoiceNumberTo ? { invoiceNumberTo: options.invoiceNumberTo } : {}),
+  };
+
+  const manifest: DataExportManifest = {
+    selection,
+    structure: {
+      schema: 'invoiceData.xsd',
+      namespace: 'http://schemas.nav.gov.hu/OSA/3.0/data',
+      basis:
+        '23/2014. (VI. 30.) NGM rendelet 13/A. § (1) — the data structure published ' +
+        'for the online invoice data service',
+    },
+    generatedAt: now().toISOString(),
+    invoiceCount: entries.length,
+    invoices: entries,
+  };
+
+  files.push({ name: 'manifest.json', contents: `${JSON.stringify(manifest, null, 2)}\n` });
+  return { files, manifest };
+}
+
+/** An invoice number can contain `/`, which a file name cannot. */
+function safeFileName(invoiceNumber: string): string {
+  const cleaned = invoiceNumber.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return cleaned === '' ? 'invoice' : cleaned;
+}
+
+/** Two invoice numbers can sanitise to the same name; keep them distinct. */
+function uniqueName(name: string, used: Set<string>): string {
+  if (!used.has(name)) {
+    used.add(name);
+    return name;
+  }
+  for (let suffix = 2; ; suffix += 1) {
+    const candidate = name.replace(/\.xml$/, `-${suffix}.xml`);
+    if (!used.has(candidate)) {
+      used.add(candidate);
+      return candidate;
+    }
+  }
+}

package/src/format.ts

@@ -0,0 +1,66 @@
+import { Decimal } from '@open-nav/core';
+
+export type DocumentLanguage = 'hu' | 'en';
+
+/**
+ * Format an exact decimal for display without going through a JavaScript
+ * number.
+ *
+ * The amounts on an invoice are exact decimal strings precisely so they do
+ * not lose precision; rendering them through `Number` to get thousands
+ * separators would throw that away at the top of NAV's 18 digit range.
+ */
+export function formatAmount(
+  value: string,
+  language: DocumentLanguage,
+  fractionDigits = 2,
+): string {
+  const amount = Decimal.from(value).round(fractionDigits);
+  const text = amount.abs().toFixed(fractionDigits);
+  const [whole = '0', fraction = ''] = text.split('.');
+
+  // A non-breaking space, so a grouped amount never breaks across a line,
+  // which is the Hungarian typographic convention for thousands.
+  const groupSeparator = language === 'hu' ? '\u00a0' : ',';
+  const decimalSeparator = language === 'hu' ? ',' : '.';
+  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, groupSeparator);
+
+  const sign = amount.isNegative() ? '-' : '';
+  return fraction === '' ? `${sign}${grouped}` : `${sign}${grouped}${decimalSeparator}${fraction}`;
+}
+
+/** Format a VAT rate like `0.27` as a percentage. */
+export function formatPercentage(value: string, language: DocumentLanguage): string {
+  const percent = Decimal.from(value).multiply('100');
+  const trimmed = percent
+    .toString()
+    .replace(/\.0+$/, '')
+    .replace(/(\.\d*?)0+$/, '$1');
+  return `${language === 'hu' ? trimmed.replace('.', ',') : trimmed}%`;
+}
+
+/** Dates are ISO in the data; Hungarian documents write them with dots. */
+export function formatDate(value: string, language: DocumentLanguage): string {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+  if (language === 'en') return value;
+  const [year, month, day] = value.split('-');
+  return `${year}. ${month}. ${day}.`;
+}
+
+/** Compose a tax number from its parts, in the written form. */
+export function formatTaxNumber(parts: {
+  taxpayerId: string;
+  vatCode?: string;
+  countyCode?: string;
+}): string {
+  return [parts.taxpayerId, parts.vatCode, parts.countyCode].filter(Boolean).join('-');
+}
+
+/** Escape text for HTML. */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}