@open-nav/core 0.1.0

package/src/money/summary.ts

@@ -0,0 +1,380 @@
+import type { ValidationIssue } from '../errors.js';
+import type {
+  InvoiceData,
+  InvoiceType,
+  LineType,
+  SummaryByVatRateType,
+  SummarySimplifiedType,
+  SummaryType,
+  VatRateType,
+} from '../generated/types.js';
+import { Decimal, sum, type RoundingMode } from './decimal.js';
+
+/** Decimal places NAV's MonetaryType permits. */
+const MONETARY_SCALE = 2;
+
+export interface SummaryOptions {
+  /** Decimal places for computed amounts. Defaults to 2, per MonetaryType. */
+  scale?: number;
+  mode?: RoundingMode;
+}
+
+/**
+ * Compute the invoice summary from the lines.
+ *
+ * The summary is not free-form: `summaryByVatRate` must carry one entry per
+ * distinct VAT rate appearing on the lines, its net and VAT amounts must be
+ * the sums of the corresponding line amounts, and the invoice totals must be
+ * the sums of those. NAV rejects the whole batch when they disagree, so this
+ * derives them rather than trusting a caller to keep them in step.
+ *
+ * Lines are grouped by their entire `lineVatRate` value, not by percentage
+ * alone: a 27% line and an exempt line are different rates, and so are two
+ * exempt lines citing different legal grounds.
+ */
+export function computeInvoiceSummary(
+  invoice: InvoiceType,
+  options: SummaryOptions = {},
+): SummaryType {
+  const scale = options.scale ?? MONETARY_SCALE;
+  const mode = options.mode ?? 'half-up';
+  const lines = invoice.invoiceLines?.line ?? [];
+
+  const normal = lines.filter((line) => line.lineAmountsNormal !== undefined);
+  const simplified = lines.filter((line) => line.lineAmountsSimplified !== undefined);
+
+  const summary: SummaryType = {};
+
+  if (simplified.length > 0) {
+    summary.summarySimplified = groupBy(
+      simplified,
+      (line) => line.lineAmountsSimplified!.lineVatRate,
+    ).map(([vatRate, group]): SummarySimplifiedType => ({
+      vatRate,
+      vatContentGrossAmount: total(
+        group.map((line) => line.lineAmountsSimplified!.lineGrossAmountSimplified),
+        scale,
+        mode,
+      ),
+      vatContentGrossAmountHUF: total(
+        group.map((line) => line.lineAmountsSimplified!.lineGrossAmountSimplifiedHUF),
+        scale,
+        mode,
+      ),
+    }));
+  }
+
+  if (normal.length > 0 || simplified.length === 0) {
+    const byVatRate = groupBy(normal, (line) => line.lineAmountsNormal!.lineVatRate).map(
+      ([vatRate, group]): SummaryByVatRateType => ({
+        vatRate,
+        vatRateNetData: {
+          vatRateNetAmount: total(
+            group.map((line) => line.lineAmountsNormal!.lineNetAmountData.lineNetAmount),
+            scale,
+            mode,
+          ),
+          vatRateNetAmountHUF: total(
+            group.map((line) => line.lineAmountsNormal!.lineNetAmountData.lineNetAmountHUF),
+            scale,
+            mode,
+          ),
+        },
+        vatRateVatData: {
+          vatRateVatAmount: total(
+            group.map((line) => lineVatAmount(line, 'amount', scale, mode)),
+            scale,
+            mode,
+          ),
+          vatRateVatAmountHUF: total(
+            group.map((line) => lineVatAmount(line, 'huf', scale, mode)),
+            scale,
+            mode,
+          ),
+        },
+      }),
+    );
+
+    summary.summaryNormal = {
+      summaryByVatRate: byVatRate,
+      invoiceNetAmount: total(
+        byVatRate.map((entry) => entry.vatRateNetData.vatRateNetAmount),
+        scale,
+        mode,
+      ),
+      invoiceNetAmountHUF: total(
+        byVatRate.map((entry) => entry.vatRateNetData.vatRateNetAmountHUF),
+        scale,
+        mode,
+      ),
+      invoiceVatAmount: total(
+        byVatRate.map((entry) => entry.vatRateVatData.vatRateVatAmount),
+        scale,
+        mode,
+      ),
+      invoiceVatAmountHUF: total(
+        byVatRate.map((entry) => entry.vatRateVatData.vatRateVatAmountHUF),
+        scale,
+        mode,
+      ),
+    };
+  }
+
+  summary.summaryGrossData = {
+    invoiceGrossAmount: grossTotal(summary, 'amount', scale, mode),
+    invoiceGrossAmountHUF: grossTotal(summary, 'huf', scale, mode),
+  };
+
+  return summary;
+}
+
+/**
+ * Check that an invoice's stated summary agrees with its lines.
+ *
+ * Returns the discrepancies rather than throwing, because a report that lists
+ * every mismatch at once is far more useful than the first one NAV happens to
+ * complain about.
+ */
+export function checkInvoiceSummary(
+  invoice: InvoiceType,
+  options: SummaryOptions = {},
+): ValidationIssue[] {
+  if (!hasAmountBearingLines(invoice)) return [];
+
+  const issues: ValidationIssue[] = [];
+  const stated = invoice.invoiceSummary;
+  const expected = computeInvoiceSummary(invoice, options);
+
+  const compare = (path: string, actual: string | undefined, wanted: string | undefined): void => {
+    if (actual === undefined || wanted === undefined) return;
+    if (!Decimal.from(actual).equals(Decimal.from(wanted))) {
+      issues.push({
+        path,
+        code: 'SUMMARY_MISMATCH',
+        message: `is ${actual} but the lines total ${wanted}`,
+      });
+    }
+  };
+
+  if (stated.summaryNormal && expected.summaryNormal) {
+    const statedNormal = stated.summaryNormal;
+    const expectedNormal = expected.summaryNormal;
+    compare(
+      'invoiceSummary.summaryNormal.invoiceNetAmount',
+      statedNormal.invoiceNetAmount,
+      expectedNormal.invoiceNetAmount,
+    );
+    compare(
+      'invoiceSummary.summaryNormal.invoiceNetAmountHUF',
+      statedNormal.invoiceNetAmountHUF,
+      expectedNormal.invoiceNetAmountHUF,
+    );
+    compare(
+      'invoiceSummary.summaryNormal.invoiceVatAmount',
+      statedNormal.invoiceVatAmount,
+      expectedNormal.invoiceVatAmount,
+    );
+    compare(
+      'invoiceSummary.summaryNormal.invoiceVatAmountHUF',
+      statedNormal.invoiceVatAmountHUF,
+      expectedNormal.invoiceVatAmountHUF,
+    );
+
+    if (statedNormal.summaryByVatRate.length !== expectedNormal.summaryByVatRate.length) {
+      issues.push({
+        path: 'invoiceSummary.summaryNormal.summaryByVatRate',
+        code: 'SUMMARY_VAT_RATE_COUNT',
+        message:
+          `has ${statedNormal.summaryByVatRate.length} entries but the lines use ` +
+          `${expectedNormal.summaryByVatRate.length} distinct VAT rates`,
+      });
+    } else {
+      // Order is not significant, so match entries by their VAT rate.
+      for (const [index, statedEntry] of statedNormal.summaryByVatRate.entries()) {
+        const key = vatRateKey(statedEntry.vatRate);
+        const expectedEntry = expectedNormal.summaryByVatRate.find(
+          (candidate) => vatRateKey(candidate.vatRate) === key,
+        );
+        const path = `invoiceSummary.summaryNormal.summaryByVatRate.${index}`;
+        if (!expectedEntry) {
+          issues.push({
+            path,
+            code: 'SUMMARY_VAT_RATE_UNKNOWN',
+            message: 'states a VAT rate that no line uses',
+          });
+          continue;
+        }
+        compare(
+          `${path}.vatRateNetData.vatRateNetAmount`,
+          statedEntry.vatRateNetData.vatRateNetAmount,
+          expectedEntry.vatRateNetData.vatRateNetAmount,
+        );
+        compare(
+          `${path}.vatRateVatData.vatRateVatAmount`,
+          statedEntry.vatRateVatData.vatRateVatAmount,
+          expectedEntry.vatRateVatData.vatRateVatAmount,
+        );
+      }
+    }
+  }
+
+  if (stated.summaryGrossData && expected.summaryGrossData) {
+    compare(
+      'invoiceSummary.summaryGrossData.invoiceGrossAmount',
+      stated.summaryGrossData.invoiceGrossAmount,
+      expected.summaryGrossData.invoiceGrossAmount,
+    );
+    compare(
+      'invoiceSummary.summaryGrossData.invoiceGrossAmountHUF',
+      stated.summaryGrossData.invoiceGrossAmountHUF,
+      expected.summaryGrossData.invoiceGrossAmountHUF,
+    );
+  }
+
+  return issues;
+}
+
+/**
+ * Check every invoice in a document, including batch modification documents.
+ *
+ * Paths are prefixed with the batch index so a caller can tell which invoice
+ * of a multi-invoice document is out.
+ */
+export function checkDocumentSummaries(
+  document: InvoiceData,
+  options: SummaryOptions = {},
+): ValidationIssue[] {
+  const single = document.invoiceMain.invoice;
+  if (single) return checkInvoiceSummary(single, options);
+
+  return (document.invoiceMain.batchInvoice ?? []).flatMap((entry) =>
+    checkInvoiceSummary(entry.invoice, options).map((issue) => ({
+      ...issue,
+      path: `batchInvoice.${entry.batchIndex}.${issue.path}`,
+    })),
+  );
+}
+
+function grossTotal(
+  summary: SummaryType,
+  which: 'amount' | 'huf',
+  scale: number,
+  mode: RoundingMode,
+): string {
+  const parts: string[] = [];
+  if (summary.summaryNormal) {
+    parts.push(
+      which === 'amount'
+        ? summary.summaryNormal.invoiceNetAmount
+        : summary.summaryNormal.invoiceNetAmountHUF,
+      which === 'amount'
+        ? summary.summaryNormal.invoiceVatAmount
+        : summary.summaryNormal.invoiceVatAmountHUF,
+    );
+  }
+  for (const entry of summary.summarySimplified ?? []) {
+    parts.push(which === 'amount' ? entry.vatContentGrossAmount : entry.vatContentGrossAmountHUF);
+  }
+  return total(parts, scale, mode);
+}
+
+/**
+ * VAT of a line, stated or derived.
+ *
+ * `lineVatData` is optional in the schema, and NAV's own advance-invoice
+ * samples omit it: the line states its net amount and its rate, and the VAT
+ * follows from the two. Treating an absent `lineVatData` as zero would make
+ * every such invoice look unbalanced.
+ *
+ * When the rate is not a percentage — exempt, out of scope, reverse charge —
+ * there is no VAT to derive and the contribution is zero.
+ */
+function lineVatAmount(
+  line: LineType,
+  which: 'amount' | 'huf',
+  scale: number,
+  mode: RoundingMode,
+): string {
+  const amounts = line.lineAmountsNormal!;
+  const stated =
+    which === 'amount' ? amounts.lineVatData?.lineVatAmount : amounts.lineVatData?.lineVatAmountHUF;
+  if (stated !== undefined) return stated;
+
+  const percentage = amounts.lineVatRate.vatPercentage;
+  if (percentage === undefined) return '0';
+
+  const net =
+    which === 'amount'
+      ? amounts.lineNetAmountData.lineNetAmount
+      : amounts.lineNetAmountData.lineNetAmountHUF;
+  return Decimal.from(net).multiply(percentage).round(scale, mode).toString();
+}
+
+/**
+ * Whether any line carries amounts at all.
+ *
+ * A line-data modification document can reference lines of the original
+ * invoice without restating amounts. There is nothing to reconcile then, and
+ * reporting a mismatch would be a false positive.
+ */
+export function hasAmountBearingLines(invoice: InvoiceType): boolean {
+  return (invoice.invoiceLines?.line ?? []).some(
+    (line) => line.lineAmountsNormal !== undefined || line.lineAmountsSimplified !== undefined,
+  );
+}
+
+function total(values: string[], scale: number, mode: RoundingMode): string {
+  return sum(values).round(scale, mode).toString();
+}
+
+function groupBy(
+  lines: LineType[],
+  rateOf: (line: LineType) => VatRateType,
+): Array<[VatRateType, LineType[]]> {
+  const groups = new Map<string, [VatRateType, LineType[]]>();
+  for (const line of lines) {
+    const rate = rateOf(line);
+    const key = vatRateKey(rate);
+    const existing = groups.get(key);
+    if (existing) existing[1].push(line);
+    else groups.set(key, [rate, [line]]);
+  }
+  return [...groups.values()];
+}
+
+/**
+ * Stable identity of a VAT rate.
+ *
+ * Numeric rates are compared by value, so `0.27` and `0.2700` group together.
+ *
+ * Exemption and out-of-scope rates are identified by their `case` — the legal
+ * ground code — and *not* by the accompanying `reason`, which is free text.
+ * NAV's own new-means-of-transport sample makes the point: the line cites
+ * case `KBAUK` with reason "Áfa tv. 89. §" while the summary cites the same
+ * case with reason "Adómentes Közösségen belüli új közlekedési eszköz
+ * értékesítés". Same rate, different prose. Grouping on the prose would split
+ * one rate into two and report a spurious mismatch.
+ */
+export function vatRateKey(rate: VatRateType): string {
+  const parts: string[] = [];
+  for (const key of Object.keys(rate).sort()) {
+    const value = (rate as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    if ((key === 'vatPercentage' || key === 'vatContent') && typeof value === 'string') {
+      parts.push(`${key}=${Decimal.from(value).round(6).toString()}`);
+    } else if (isDetailedReason(value)) {
+      parts.push(`${key}=${value.case}`);
+    } else {
+      parts.push(`${key}=${JSON.stringify(value)}`);
+    }
+  }
+  return parts.join('|');
+}
+
+function isDetailedReason(value: unknown): value is { case: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { case?: unknown }).case === 'string'
+  );
+}

package/src/time.ts

@@ -0,0 +1,44 @@
+import { NavValidationError } from './errors.js';
+
+/**
+ * Render the `header/timestamp` value: UTC, ISO 8601, millisecond precision,
+ * e.g. `2026-09-03T14:25:11.482Z`.
+ */
+export function toHeaderTimestamp(value: Date | string = new Date()): string {
+  return toDate(value).toISOString();
+}
+
+/**
+ * Render a timestamp the way the request signature consumes it: UTC,
+ * `yyyyMMddHHmmss`, truncated to whole seconds, no separators.
+ *
+ * This must correspond to the same instant as the `header/timestamp` of the
+ * request, otherwise NAV rejects the signature.
+ */
+export function toSignatureTimestamp(value: Date | string = new Date()): string {
+  const iso = toDate(value).toISOString();
+  // 2026-09-03T14:25:11.482Z -> 20260903142511
+  return `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}`;
+}
+
+/** Render a NAV `date` field (`xs:date`) as `yyyy-MM-dd` in UTC. */
+export function toNavDate(value: Date | string = new Date()): string {
+  if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return value;
+  }
+  return toDate(value).toISOString().slice(0, 10);
+}
+
+function toDate(value: Date | string): Date {
+  const date = typeof value === 'string' ? new Date(value) : value;
+  if (Number.isNaN(date.getTime())) {
+    throw new NavValidationError('Invalid timestamp', [
+      {
+        path: 'timestamp',
+        code: 'INVALID_TIMESTAMP',
+        message: `cannot be parsed as a date: ${JSON.stringify(value)}`,
+      },
+    ]);
+  }
+  return date;
+}

package/src/validation/issue.ts

@@ -0,0 +1,102 @@
+import type { NavFaultCode } from '../generated/fault-codes.js';
+import { NAV_FAULT_MESSAGES } from '../generated/fault-codes.js';
+
+/**
+ * How much a finding matters.
+ *
+ * `error` means NAV would reject the report. `warning` means the data is
+ * accepted but suspect — a tax number whose check digit is wrong, say, which
+ * NAV validates against its taxpayer registry rather than arithmetically.
+ * Keeping the two apart is what makes the validator usable: a validator that
+ * cries wolf gets switched off.
+ */
+export type Severity = 'error' | 'warning';
+
+/**
+ * Findings this library reports that NAV has no code for.
+ *
+ * Kept separate from NAV's codes rather than forced into an approximate one,
+ * so it is always clear whether a finding means "the service would say this"
+ * or "we noticed this".
+ */
+export type LocalFaultCode =
+  /** A tax number's check digit does not match. NAV checks its registry instead. */
+  | 'LOCAL_TAXPAYER_ID_CHECK_DIGIT'
+  /** A county code outside the set NAV is known to issue. */
+  | 'LOCAL_COUNTY_CODE_UNKNOWN'
+  /** A VAT percentage that is not a current Hungarian rate. */
+  | 'LOCAL_VAT_PERCENTAGE_UNUSUAL';
+
+export type FaultCode = NavFaultCode | LocalFaultCode;
+
+export interface InvoiceValidationIssue {
+  /**
+   * The fault code. Where NAV defines one it is used verbatim, so a local
+   * failure names exactly what the service would have said, and the compiler
+   * checks it against the generated catalogue.
+   */
+  code: FaultCode;
+  /** `nav` for a code NAV defines, `local` for one of ours. */
+  origin: 'nav' | 'local';
+  severity: Severity;
+  /** Dotted path to the offending value, e.g. `invoiceLines.line.2.quantity`. */
+  path: string;
+  /** What is wrong, with the offending values quoted. */
+  message: string;
+  /** NAV's own description of the fault, in the requested language. */
+  navMessage?: string;
+}
+
+export interface ValidationReport {
+  /** True when there are no errors. Warnings do not make a report invalid. */
+  valid: boolean;
+  errors: InvoiceValidationIssue[];
+  warnings: InvoiceValidationIssue[];
+  /** Everything, in the order found. */
+  issues: InvoiceValidationIssue[];
+}
+
+export type MessageLanguage = 'en' | 'hu' | 'de';
+
+/** Collects findings while rules run, then assembles the report. */
+export class IssueCollector {
+  private readonly collected: InvoiceValidationIssue[] = [];
+
+  constructor(private readonly language: MessageLanguage = 'en') {}
+
+  add(code: FaultCode, severity: Severity, path: string, message: string): void {
+    const navMessage = isNavCode(code) ? NAV_FAULT_MESSAGES[code][this.language] : undefined;
+    this.collected.push({
+      code,
+      origin: isNavCode(code) ? 'nav' : 'local',
+      severity,
+      path,
+      message,
+      ...(navMessage ? { navMessage } : {}),
+    });
+  }
+
+  error(code: FaultCode, path: string, message: string): void {
+    this.add(code, 'error', path, message);
+  }
+
+  warn(code: FaultCode, path: string, message: string): void {
+    this.add(code, 'warning', path, message);
+  }
+
+  report(): ValidationReport {
+    const errors = this.collected.filter((issue) => issue.severity === 'error');
+    const warnings = this.collected.filter((issue) => issue.severity === 'warning');
+    return { valid: errors.length === 0, errors, warnings, issues: [...this.collected] };
+  }
+}
+
+/** Whether a code is one NAV defines, as opposed to one of ours. */
+export function isNavCode(code: FaultCode): code is NavFaultCode {
+  return code in NAV_FAULT_MESSAGES;
+}
+
+/** NAV's description of a fault code, for surfacing in your own UI. */
+export function faultMessage(code: FaultCode, language: MessageLanguage = 'en'): string {
+  return isNavCode(code) ? (NAV_FAULT_MESSAGES[code][language] ?? '') : '';
+}