@open-nav/core 0.1.0

package/src/validation/schema.ts

@@ -0,0 +1,315 @@
+import { ROOTS, TYPES } from '../generated/schema.js';
+import { Decimal } from '../money/decimal.js';
+import { XS_PRIMITIVES, type PrimitiveKind, type SimpleDescriptor } from '../xml/descriptor.js';
+import { IssueCollector } from './issue.js';
+
+/**
+ * Validate a document against the schema, using the generated descriptors.
+ *
+ * This covers what an XSD validator would: mandatory elements, value
+ * constraints, cardinality and choice exclusivity. Doing it from the same
+ * descriptor table that drives serialisation means the two cannot disagree,
+ * and it needs no native XML library.
+ *
+ * NAV reports all of these as `SCHEMA_VIOLATION`, except a missing mandatory
+ * element which it reports as `MANDATORY_CONTENT_MISSING`.
+ */
+export function collectSchemaIssues(
+  rootName: string,
+  value: unknown,
+  collector: IssueCollector,
+): void {
+  const root = ROOTS[rootName];
+  if (!root) {
+    collector.error('SCHEMA_VIOLATION', '', `unknown document root ${rootName}`);
+    return;
+  }
+  walk(root.type, value, '', collector);
+}
+
+function walk(typeKey: string, value: unknown, path: string, collector: IssueCollector): void {
+  const primitive = XS_PRIMITIVES[typeKey];
+  if (primitive) {
+    checkPrimitive(primitive, undefined, value, path, collector);
+    return;
+  }
+
+  const descriptor = TYPES[typeKey];
+  if (!descriptor) {
+    collector.error('SCHEMA_VIOLATION', path, `unknown type ${typeKey}`);
+    return;
+  }
+
+  if (descriptor.kind === 'simple') {
+    checkPrimitive(descriptor.primitive, descriptor, value, path, collector);
+    return;
+  }
+
+  if (descriptor.content === 'simple') {
+    if (!isRecord(value)) {
+      collector.error('SCHEMA_VIOLATION', path, `expected an object, got ${describe(value)}`);
+      return;
+    }
+    const contentType = descriptor.contentType;
+    if (contentType) walk(contentType, value['value'], `${path}.value`, collector);
+    for (const attribute of descriptor.attributes ?? []) {
+      const attributeValue = value[attribute.name];
+      if (attributeValue === undefined || attributeValue === null) {
+        if (attribute.required) {
+          collector.error(
+            'MANDATORY_CONTENT_MISSING',
+            `${path}@${attribute.name}`,
+            'attribute is required',
+          );
+        }
+        continue;
+      }
+      walk(attribute.type, attributeValue, `${path}@${attribute.name}`, collector);
+    }
+    return;
+  }
+
+  if (!isRecord(value)) {
+    collector.error('SCHEMA_VIOLATION', path, `expected an object, got ${describe(value)}`);
+    return;
+  }
+
+  for (const field of descriptor.fields) {
+    const fieldPath = path ? `${path}.${field.name}` : field.name;
+    const fieldValue = value[field.name];
+
+    if (fieldValue === undefined || fieldValue === null) {
+      if (!field.optional) {
+        collector.error('MANDATORY_CONTENT_MISSING', fieldPath, 'is required');
+      }
+      continue;
+    }
+
+    if (field.repeated) {
+      if (!Array.isArray(fieldValue)) {
+        collector.error('SCHEMA_VIOLATION', fieldPath, 'is repeatable and expects an array');
+        continue;
+      }
+      if (fieldValue.length === 0) {
+        if (!field.optional) {
+          collector.error('MANDATORY_CONTENT_MISSING', fieldPath, 'must have at least one entry');
+        }
+        continue;
+      }
+      if (field.maxOccurs !== undefined && fieldValue.length > field.maxOccurs) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          fieldPath,
+          `allows at most ${field.maxOccurs} entries, got ${fieldValue.length}`,
+        );
+      }
+      for (const [index, item] of fieldValue.entries()) {
+        walk(field.type, item, `${fieldPath}.${index}`, collector);
+      }
+      continue;
+    }
+
+    if (Array.isArray(fieldValue)) {
+      collector.error('SCHEMA_VIOLATION', fieldPath, 'occurs at most once');
+      continue;
+    }
+
+    walk(field.type, fieldValue, fieldPath, collector);
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!descriptor.fields.some((field) => field.name === key)) {
+      const isAttribute = (descriptor.attributes ?? []).some((attribute) => attribute.name === key);
+      if (!isAttribute) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path ? `${path}.${key}` : key,
+          `is not part of ${descriptor.name}`,
+        );
+      }
+    }
+  }
+
+  // Choice groups: NAV nests these inside sequences, so they are checked
+  // against the flattened field list rather than by structural position.
+  for (const group of descriptor.choiceGroups ?? []) {
+    const present = group.members.filter(
+      (member) => value[member] !== undefined && value[member] !== null,
+    );
+    if (present.length > 1) {
+      collector.error(
+        'SCHEMA_VIOLATION',
+        path,
+        `only one of ${group.members.join(', ')} may be set, found ${present.join(' and ')}`,
+      );
+    } else if (present.length === 0 && group.required) {
+      collector.error(
+        'MANDATORY_CONTENT_MISSING',
+        path,
+        `one of ${group.members.join(', ')} is required`,
+      );
+    }
+  }
+}
+
+function checkPrimitive(
+  kind: PrimitiveKind,
+  descriptor: SimpleDescriptor | undefined,
+  value: unknown,
+  path: string,
+  collector: IssueCollector,
+): void {
+  switch (kind) {
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        collector.error('SCHEMA_VIOLATION', path, `expected a boolean, got ${describe(value)}`);
+      }
+      return;
+
+    case 'integer': {
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        collector.error('SCHEMA_VIOLATION', path, `expected an integer, got ${describe(value)}`);
+        return;
+      }
+      // Numeric comparison, not lexicographic: '2' sorts after '100' as text.
+      checkBounds(String(value), descriptor, path, collector, true);
+      if (descriptor?.totalDigits !== undefined) {
+        const digits = Math.abs(value).toString().length;
+        if (digits > descriptor.totalDigits) {
+          collector.error(
+            'SCHEMA_VIOLATION',
+            path,
+            `has ${digits} digits, at most ${descriptor.totalDigits} allowed`,
+          );
+        }
+      }
+      return;
+    }
+
+    case 'decimal': {
+      if (typeof value !== 'string' && typeof value !== 'number') {
+        collector.error('SCHEMA_VIOLATION', path, `expected a decimal, got ${describe(value)}`);
+        return;
+      }
+      let amount: Decimal;
+      try {
+        amount = Decimal.from(value);
+      } catch {
+        collector.error('SCHEMA_VIOLATION', path, `${JSON.stringify(value)} is not a decimal`);
+        return;
+      }
+      if (descriptor?.fractionDigits !== undefined && amount.scale > descriptor.fractionDigits) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `has ${amount.scale} decimal places, at most ${descriptor.fractionDigits} allowed`,
+        );
+      }
+      if (descriptor?.totalDigits !== undefined && amount.totalDigits() > descriptor.totalDigits) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `has ${amount.totalDigits()} significant digits, at most ${descriptor.totalDigits} allowed`,
+        );
+      }
+      checkBounds(amount.toString(), descriptor, path, collector, true);
+      return;
+    }
+
+    default: {
+      if (typeof value !== 'string') {
+        collector.error('SCHEMA_VIOLATION', path, `expected a string, got ${describe(value)}`);
+        return;
+      }
+      if (!descriptor) return;
+      if (descriptor.enumValues && !descriptor.enumValues.includes(value)) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `${JSON.stringify(value)} is not one of ${descriptor.enumValues.join(', ')}`,
+        );
+      }
+      if (descriptor.length !== undefined && value.length !== descriptor.length) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `must be exactly ${descriptor.length} characters, got ${value.length}`,
+        );
+      }
+      if (descriptor.minLength !== undefined && value.length < descriptor.minLength) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `must be at least ${descriptor.minLength} characters, got ${value.length}`,
+        );
+      }
+      if (descriptor.maxLength !== undefined && value.length > descriptor.maxLength) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `must be at most ${descriptor.maxLength} characters, got ${value.length}`,
+        );
+      }
+      if (descriptor.pattern !== undefined && !anchored(descriptor.pattern).test(value)) {
+        collector.error(
+          'SCHEMA_VIOLATION',
+          path,
+          `${JSON.stringify(value)} does not match ${descriptor.pattern}`,
+        );
+      }
+      // Dates and timestamps carry their bounds as text, and NAV's are all
+      // lexicographically comparable ISO forms.
+      checkBounds(value, descriptor, path, collector);
+      return;
+    }
+  }
+}
+
+function checkBounds(
+  value: string,
+  descriptor: SimpleDescriptor | undefined,
+  path: string,
+  collector: IssueCollector,
+  numeric = false,
+): void {
+  if (!descriptor) return;
+  const compare = numeric
+    ? (left: string, right: string) => Decimal.from(left).compare(right)
+    : (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+
+  const checks: Array<[keyof SimpleDescriptor, (result: number) => boolean, string]> = [
+    ['minInclusive', (result) => result < 0, 'must not be less than'],
+    ['maxInclusive', (result) => result > 0, 'must not be greater than'],
+    ['minExclusive', (result) => result <= 0, 'must be greater than'],
+    ['maxExclusive', (result) => result >= 0, 'must be less than'],
+  ];
+
+  for (const [facet, violates, wording] of checks) {
+    const bound = descriptor[facet];
+    if (typeof bound !== 'string') continue;
+    if (violates(compare(value, bound))) {
+      collector.error('SCHEMA_VIOLATION', path, `${wording} ${bound}, got ${value}`);
+    }
+  }
+}
+
+const anchoredCache = new Map<string, RegExp>();
+
+/** XSD patterns match the whole value, unlike JavaScript regular expressions. */
+function anchored(pattern: string): RegExp {
+  const cached = anchoredCache.get(pattern);
+  if (cached) return cached;
+  const compiled = new RegExp(`^(?:${pattern})$`, 'u');
+  anchoredCache.set(pattern, compiled);
+  return compiled;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function describe(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return typeof value;
+}

package/src/validation/tax-number.ts

@@ -0,0 +1,96 @@
+/**
+ * Hungarian tax number checks.
+ *
+ * A tax number is eleven digits in three parts: an eight digit core
+ * (törzsszám) whose last digit is a check digit, a one digit VAT code
+ * (áfakód), and a two digit county code (megyekód). NAV's schemas carry the
+ * three parts separately, in `taxpayerId`, `vatCode` and `countyCode`.
+ */
+
+/** Weights applied to the first seven digits of the core number. */
+const CHECK_WEIGHTS = [9, 7, 3, 1, 9, 7, 3] as const;
+
+/**
+ * County codes NAV issues.
+ *
+ * This set is **not** in the XSD, which only constrains the field to two
+ * digits, so it is best-effort and is reported as a warning rather than an
+ * error. Budapest and Pest county use 41 to 44; 51 is used for taxpayers
+ * registered by the large taxpayers directorate.
+ */
+const COUNTY_CODES = new Set([
+  ...range(2, 20), // the counties, alphabetically
+  ...range(22, 44), // remaining counties plus the capital
+  51,
+]);
+
+function range(from: number, to: number): number[] {
+  return Array.from({ length: to - from + 1 }, (_, index) => from + index);
+}
+
+/**
+ * Whether the check digit of an eight digit core tax number is consistent.
+ *
+ * Verified against the real tax numbers in NAV's published samples. Note that
+ * two of the four tax numbers those samples use (`98765432`, `87654321`) are
+ * obvious placeholders and do *not* satisfy the check — evidence that NAV
+ * validates a tax number against its taxpayer registry rather than
+ * arithmetically. Treat a failure here as a likely typo, and use
+ * `queryTaxpayer` when you need an authoritative answer.
+ */
+export function isValidTaxpayerId(taxpayerId: string): boolean {
+  if (!/^\d{8}$/.test(taxpayerId)) return false;
+  const sum = CHECK_WEIGHTS.reduce(
+    (total, weight, index) => total + Number(taxpayerId[index]) * weight,
+    0,
+  );
+  return (10 - (sum % 10)) % 10 === Number(taxpayerId[7]);
+}
+
+/** The check digit an eight digit core tax number should end with. */
+export function taxpayerIdCheckDigit(firstSevenDigits: string): number {
+  if (!/^\d{7}$/.test(firstSevenDigits)) {
+    throw new Error(`Expected seven digits, got ${JSON.stringify(firstSevenDigits)}`);
+  }
+  const sum = CHECK_WEIGHTS.reduce(
+    (total, weight, index) => total + Number(firstSevenDigits[index]) * weight,
+    0,
+  );
+  return (10 - (sum % 10)) % 10;
+}
+
+/** Whether a VAT code is one NAV defines. */
+export function isValidVatCode(vatCode: string): boolean {
+  return /^[1-5]$/.test(vatCode);
+}
+
+/** Whether a county code is one NAV issues. Best-effort; see COUNTY_CODES. */
+export function isValidCountyCode(countyCode: string): boolean {
+  return /^\d{2}$/.test(countyCode) && COUNTY_CODES.has(Number(countyCode));
+}
+
+export interface ParsedTaxNumber {
+  taxpayerId: string;
+  vatCode?: string;
+  countyCode?: string;
+}
+
+/**
+ * Split an eleven digit tax number into the three parts NAV's schema wants.
+ *
+ * Accepts the common written forms — `12345678-2-41`, `12345678 2 41` and
+ * `12345678241` — because that is how the number appears on paper, and
+ * pasting it whole into `taxpayerId` is the mistake this avoids.
+ */
+export function parseTaxNumber(input: string): ParsedTaxNumber {
+  const digits = input.replace(/[\s-]/g, '');
+  if (/^\d{8}$/.test(digits)) return { taxpayerId: digits };
+  if (/^\d{11}$/.test(digits)) {
+    return {
+      taxpayerId: digits.slice(0, 8),
+      vatCode: digits.slice(8, 9),
+      countyCode: digits.slice(9, 11),
+    };
+  }
+  throw new Error(`Expected an 8 or 11 digit Hungarian tax number, got ${JSON.stringify(input)}`);
+}

package/src/validation/validate.ts

@@ -0,0 +1,45 @@
+import type { InvoiceData } from '../generated/types.js';
+import { IssueCollector, type MessageLanguage, type ValidationReport } from './issue.js';
+import { collectSchemaIssues } from './schema.js';
+import { collectBusinessIssues, type InvoiceValidationContext } from './rules.js';
+
+export interface ValidateInvoiceOptions extends InvoiceValidationContext {
+  /** Language for NAV's own fault descriptions. Defaults to English. */
+  language?: MessageLanguage;
+  /** Skip the business rules and check only the schema. */
+  schemaOnly?: boolean;
+}
+
+/**
+ * Check an invoice data report before sending it.
+ *
+ * Two layers run: the schema, derived from NAV's XSDs, and the business rules
+ * that are decidable from the document alone. Every finding carries NAV's own
+ * fault code where one exists, so a failure here reads the same as the
+ * rejection it prevents.
+ *
+ * Warnings do not make a report invalid. The distinction matters: a tax number
+ * whose check digit is wrong is worth flagging, but NAV validates tax numbers
+ * against its registry, so treating it as an error would reject documents the
+ * service accepts.
+ *
+ * ```ts
+ * const report = validateInvoice(invoice, { operation: 'CREATE' });
+ * if (!report.valid) console.error(report.errors);
+ * ```
+ */
+export function validateInvoice(
+  document: InvoiceData,
+  options: ValidateInvoiceOptions = {},
+): ValidationReport {
+  const collector = new IssueCollector(options.language ?? 'en');
+  collectSchemaIssues('InvoiceData', document, collector);
+
+  const report = collector.report();
+  // Business rules read the document as typed data; running them over a
+  // structurally invalid document would produce noise, not findings.
+  if (options.schemaOnly || report.errors.length > 0) return report;
+
+  collectBusinessIssues(document, collector, options);
+  return collector.report();
+}

package/src/xml/descriptor.ts

@@ -0,0 +1,112 @@
+/**
+ * Runtime description of the NAV schemas.
+ *
+ * The generated `TYPES` table in `../generated/schema.js` is the single source
+ * of truth for element order, namespaces, cardinality, choice exclusivity and
+ * value constraints. Serialisation, parsing and validation are all driven from
+ * it, so moving to a future interface version is a regeneration rather than a
+ * rewrite of three separate hand-maintained code paths.
+ */
+
+/** Short key for each namespace in the Online Számla schemas. */
+export type NsKey = 'common' | 'base' | 'data' | 'api' | 'annul' | 'metrics';
+
+export const NAMESPACE_URIS: Record<NsKey, string> = {
+  common: 'http://schemas.nav.gov.hu/NTCA/1.0/common',
+  base: 'http://schemas.nav.gov.hu/OSA/3.0/base',
+  data: 'http://schemas.nav.gov.hu/OSA/3.0/data',
+  api: 'http://schemas.nav.gov.hu/OSA/3.0/api',
+  annul: 'http://schemas.nav.gov.hu/OSA/3.0/annul',
+  metrics: 'http://schemas.nav.gov.hu/OSA/3.0/metrics',
+};
+
+/** How a value is carried in XML. */
+export type PrimitiveKind =
+  'string' | 'decimal' | 'integer' | 'boolean' | 'date' | 'dateTime' | 'base64Binary';
+
+export interface FieldDescriptor {
+  /** Element local name. */
+  name: string;
+  /** Namespace that *declares* this element, which may differ from its parent's. */
+  ns: NsKey;
+  /** Key into the `TYPES` table, or an `xs:` primitive. */
+  type: string;
+  /** `minOccurs="0"`. Choice members are always optional. */
+  optional?: boolean;
+  /** `maxOccurs` greater than one, or unbounded. */
+  repeated?: boolean;
+  /** Upper bound when the schema states a finite one. */
+  maxOccurs?: number;
+}
+
+export interface ChoiceGroupDescriptor {
+  members: string[];
+  /** `true` when exactly one member must be present; `false` when at most one may be. */
+  required: boolean;
+}
+
+export interface AttributeDescriptor {
+  name: string;
+  type: string;
+  required: boolean;
+}
+
+export interface ComplexDescriptor {
+  kind: 'complex';
+  name: string;
+  ns: NsKey;
+  /** Name of the corresponding generated TypeScript type. */
+  tsName: string;
+  /** `element` for child elements, `simple` for text content plus attributes. */
+  content: 'element' | 'simple';
+  /** Type of the text value when `content` is `simple`. */
+  contentType?: string;
+  /** Child elements in schema order — which is the order NAV requires. */
+  fields: FieldDescriptor[];
+  choiceGroups?: ChoiceGroupDescriptor[];
+  attributes?: AttributeDescriptor[];
+}
+
+export interface SimpleDescriptor {
+  kind: 'simple';
+  name: string;
+  ns: NsKey;
+  tsName: string;
+  primitive: PrimitiveKind;
+  /** Permitted values, when the type is an enumeration. */
+  enumValues?: string[];
+  /** Most derived `xs:pattern` of the restriction chain. */
+  pattern?: string;
+  length?: number;
+  minLength?: number;
+  maxLength?: number;
+  totalDigits?: number;
+  fractionDigits?: number;
+  minInclusive?: string;
+  maxInclusive?: string;
+  minExclusive?: string;
+  maxExclusive?: string;
+}
+
+export type Descriptor = ComplexDescriptor | SimpleDescriptor;
+
+export interface RootDescriptor {
+  name: string;
+  ns: NsKey;
+  type: string;
+}
+
+/** Primitive kinds of the `xs:` built-ins referenced directly by the schemas. */
+export const XS_PRIMITIVES: Record<string, PrimitiveKind> = {
+  'xs:string': 'string',
+  'xs:decimal': 'decimal',
+  'xs:int': 'integer',
+  'xs:integer': 'integer',
+  'xs:long': 'integer',
+  'xs:nonNegativeInteger': 'integer',
+  'xs:positiveInteger': 'integer',
+  'xs:boolean': 'boolean',
+  'xs:date': 'date',
+  'xs:dateTime': 'dateTime',
+  'xs:base64Binary': 'base64Binary',
+};