@fin.cx/einvoice 9.0.0 → 10.0.1

package/ts/formats/utils/date.value.ts

@@ -50,3 +50,109 @@ export const getWritableDueDate = (issueTimestamp: unknown, dueInDays: unknown,
   dueDate.setUTCDate(dueDate.getUTCDate() + dueInDays);
   return dueDate;
 };
+
+/**
+ * The UTC midnight of a calendar day, or undefined when there is no such day
+ * @param year The year, 1 or later
+ * @param month The month, 1 to 12
+ * @param day The day of the month
+ */
+const utcMidnightOf = (year: number, month: number, day: number): number | undefined => {
+  if (year < 1) {
+    return undefined;
+  }
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    return undefined;
+  }
+  return date.getTime();
+};
+
+/**
+ * Whether a time of day is one: hours 0 to 23, minutes and seconds 0 to 59
+ * @param hours The hours
+ * @param minutes The minutes
+ * @param seconds The seconds, 0 when not stated
+ */
+const isTimeOfDay = (hours: number, minutes: number, seconds: number): boolean =>
+  hours <= 23 && minutes <= 59 && seconds <= 59;
+
+/**
+ * Whether a time zone offset is one an `xsd:date` or `xsd:dateTime` may carry:
+ * at most 14:00
+ * @param hours The hours of the offset
+ * @param minutes The minutes of the offset
+ */
+const isZoneOffset = (hours: number, minutes: number): boolean =>
+  hours < 14 ? minutes <= 59 : hours === 14 && minutes === 0;
+
+/**
+ * The calendar day a UBL `xsd:date` names (BT-2, BT-9, BT-26, BT-72, BT-73,
+ * BT-74), as the UTC midnight of that day; undefined when the value is no such
+ * date. The value is `YYYY-MM-DD`, optionally followed by a time zone: `Z`, or
+ * `+hh:mm` / `-hh:mm` of at most 14:00. The zone says where the day is; it
+ * does not name another day, so `2026-08-01+02:00` and `2026-08-01-12:00` both
+ * name 1 August 2026. EN 16931 dates are calendar days without a zone, and CII
+ * format 102 has none, so the day is what every format reads and writes.
+ * @param value The date as the document states it
+ */
+export const parseXsdDateDay = (value: string): number | undefined => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})(?:Z|[+-](\d{2}):(\d{2}))?$/.exec(value.trim());
+  if (!match) {
+    return undefined;
+  }
+  if (match[4] !== undefined && !isZoneOffset(Number(match[4]), Number(match[5]))) {
+    return undefined;
+  }
+  return utcMidnightOf(Number(match[1]), Number(match[2]), Number(match[3]));
+};
+
+/**
+ * The calendar day an ISO 8601 date, or date and time, names, as the UTC
+ * midnight of that day; undefined when the value is no such date. A CII date
+ * without a format code may be stated so. The value is `YYYY-MM-DD`,
+ * optionally followed by a time of day `Thh:mm`, `Thh:mm:ss` or
+ * `Thh:mm:ss.fff`, and then optionally by a time zone: `Z`, or `+hh:mm` /
+ * `-hh:mm` of at most 14:00. Neither the time of day nor the zone moves the
+ * day the document states: `2026-09-11T00:30:00+02:00` is 22:30 UTC on
+ * 10 September, but the document states 11 September, and that is the day an
+ * invoice is dated with (§ 14 Abs. 4 Satz 1 Nr. 3 UStG asks for the issue date,
+ * a calendar day).
+ * @param value The date as the document states it
+ */
+export const parseIsoDateTimeDay = (value: string): number | undefined => {
+  const match =
+    /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(?:Z|[+-](\d{2}):(\d{2}))?$/.exec(value.trim());
+  if (!match) {
+    return undefined;
+  }
+  if (match[4] !== undefined && !isTimeOfDay(Number(match[4]), Number(match[5]), Number(match[6] ?? 0))) {
+    return undefined;
+  }
+  if (match[7] !== undefined && !isZoneOffset(Number(match[7]), Number(match[8]))) {
+    return undefined;
+  }
+  return utcMidnightOf(Number(match[1]), Number(match[2]), Number(match[3]));
+};
+
+/**
+ * The calendar day a CII date in format 102 (`YYYYMMDD`), 203
+ * (`YYYYMMDDhhmm`) or 204 (`YYYYMMDDhhmmss`) names, as the UTC midnight of that
+ * day; undefined when the value is no such date in that format. A time of day
+ * in formats 203 and 204 does not move the day stated; the formats carry no
+ * time zone.
+ * @param value The date as the document states it
+ * @param format The format code: '102', '203' or '204'
+ */
+export const parseCiiDateDay = (value: string, format: '102' | '203' | '204'): number | undefined => {
+  const timeDigits = { '102': '', '203': '(\\d{2})(\\d{2})', '204': '(\\d{2})(\\d{2})(\\d{2})' }[format];
+  const match = new RegExp(`^(\\d{4})(\\d{2})(\\d{2})${timeDigits}$`).exec(value.trim());
+  if (!match) {
+    return undefined;
+  }
+  if (format !== '102' && !isTimeOfDay(Number(match[4]), Number(match[5]), Number(match[6] ?? 0))) {
+    return undefined;
+  }
+  return utcMidnightOf(Number(match[1]), Number(match[2]), Number(match[3]));
+};

package/ts/formats/utils/format.detector.ts

@@ -97,12 +97,19 @@ export class FormatDetector {
       if (/xrechnung/i.test(guidelineId)) {
         return InvoiceFormat.XRECHNUNG;
       }
-      if (/factur-x/i.test(guidelineId) || /urn:cen\.eu:en16931:2017/i.test(guidelineId)) {
+      // an identifier that names Factur-X or ZUGFeRD decides; ZUGFeRD 2.0 BASIC and EXTENDED name ZUGFeRD
+      // after the EN 16931 identifier they extend (urn:cen.eu:en16931:2017#...#urn:zugferd.de:2p0:...)
+      if (/factur-x/i.test(guidelineId)) {
         return InvoiceFormat.FACTURX;
       }
-      if (/zugferd/i.test(guidelineId) || /urn:ferd:/i.test(guidelineId) || /urn:zugferd/i.test(guidelineId)) {
+      if (/zugferd/i.test(guidelineId) || /urn:ferd:/i.test(guidelineId)) {
         return InvoiceFormat.ZUGFERD;
       }
+      // the EN 16931 profile identifier is shared by Factur-X 1.0 and ZUGFeRD 2.x, one standard with one
+      // XML: an XML-only document of it reads as Factur-X
+      if (/urn:cen\.eu:en16931:2017/i.test(guidelineId)) {
+        return InvoiceFormat.FACTURX;
+      }
       return InvoiceFormat.CII;
     }
 
@@ -287,13 +294,11 @@ export class FormatDetector {
           for (const idNode of Array.from(idNodes)) {
             const profileText = idNode.textContent || '';
             
-            // Check for ZUGFeRD profiles (v1 and v2)
+            // Check for ZUGFeRD profiles: v1, the ZUGFeRD 2.0 identifiers (urn:zugferd.de:2p0:...) and the
+            // urn:zugferd:... identifiers earlier releases of this library wrote
             if (
               profileText.includes('zugferd') ||
               profileText.includes('urn:ferd:') ||
-              profileText === CII_PROFILE_IDS.ZUGFERD_BASIC ||
-              profileText === CII_PROFILE_IDS.ZUGFERD_COMFORT ||
-              profileText === CII_PROFILE_IDS.ZUGFERD_EXTENDED ||
               profileText === CII_PROFILE_IDS.ZUGFERD_V1_BASIC ||
               profileText === CII_PROFILE_IDS.ZUGFERD_V1_COMFORT ||
               profileText === CII_PROFILE_IDS.ZUGFERD_V1_EXTENDED
@@ -301,12 +306,13 @@ export class FormatDetector {
               return InvoiceFormat.ZUGFERD;
             }
 
-            // Check for Factur-X profiles
+            // Check for Factur-X profiles; the EN 16931 profile of ZUGFeRD 2.x has the same identifier, and
+            // an XML-only document of it is Factur-X: ZUGFeRD 2.x and Factur-X 1.0 are one standard
             if (
               profileText.includes('factur-x') ||
               profileText === CII_PROFILE_IDS.FACTURX_MINIMUM ||
-              profileText === CII_PROFILE_IDS.FACTURX_BASIC ||
-              profileText === CII_PROFILE_IDS.FACTURX_EN16931
+              profileText === CII_PROFILE_IDS.FACTURX_BASIC_WL ||
+              profileText === CII_PROFILE_IDS.EN16931
             ) {
               return InvoiceFormat.FACTURX;
             }

package/ts/formats/utils/party.contact.ts

@@ -0,0 +1,30 @@
+import type { business } from '@tsclass/tsclass';
+
+/** The contact of a party: the seller contact (BG-6) or the buyer contact (BG-9) */
+export interface IPartyContact {
+  /** Contact point (BT-41, BT-56) */
+  name?: string;
+  /** Telephone number (BT-42, BT-57) */
+  phone?: string;
+  /** Email address (BT-43, BT-58) */
+  email?: string;
+}
+
+/** A party with the contact metadata the decoders read back (`metadata.contactInformation`) */
+type TPartyWithContactMetadata = business.TContact & { metadata?: { contactInformation?: IPartyContact } };
+
+/**
+ * The contact a party states, as the encoders write it: the contact metadata first, otherwise
+ * the party's own name, telephone number and email address; none when the party states neither.
+ * @param party The seller or the buyer
+ */
+export const getPartyContact = (party: business.TContact | undefined): IPartyContact | undefined => {
+  const explicit = (party as TPartyWithContactMetadata | undefined)?.metadata?.contactInformation;
+  if (explicit && (explicit.name || explicit.phone || explicit.email)) {
+    return explicit;
+  }
+  if (party?.email || party?.phone) {
+    return { name: party.name, phone: party.phone, email: party.email };
+  }
+  return undefined;
+};

package/ts/formats/utils/party.identifier.ts

@@ -0,0 +1,61 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import { EInvoiceFormatError } from '../../errors.js';
+
+/** A party identifier: the seller identifier (BT-29) or the buyer identifier (BT-46), with its scheme */
+export interface IPartyIdentifier {
+  value: string;
+  /** The identification scheme (BT-29-1, BT-46-1): an ISO/IEC 6523 ICD code, or SEPA for a creditor identifier */
+  scheme?: string;
+}
+
+/**
+ * The party identifiers (BT-29 seller, BT-46 buyer) a party carries in
+ * `additionalIdentifiers`, where the decoders keep the ones a document states;
+ * the envelope has no typed field for them. Entries without a value are
+ * skipped, a blank scheme is none.
+ * @param party The seller or the buyer
+ */
+export const getPartyIdentifiers = (party: unknown): IPartyIdentifier[] => {
+  const entries: unknown = (party as { additionalIdentifiers?: unknown } | undefined)?.additionalIdentifiers;
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  const identifiers: IPartyIdentifier[] = [];
+  for (const entry of entries) {
+    const { value, scheme } = (entry ?? {}) as { value?: unknown; scheme?: unknown };
+    if (typeof value !== 'string' || !value.trim()) {
+      continue;
+    }
+    const trimmedScheme = typeof scheme === 'string' ? scheme.trim() : '';
+    identifiers.push({ value: value.trim(), ...(trimmedScheme ? { scheme: trimmedScheme } : {}) });
+  }
+  return identifiers;
+};
+
+/**
+ * Refuses a document whose buyer carries an identifier (BT-46) with the scheme
+ * SEPA, naming the rule. The SEPA scheme is the creditor identifier (BT-90) of
+ * the seller or the payee. The CEN artefacts 1.3.16 report it on a buyer as
+ * BR-CL-10, "Any identifier identification scheme identifier MUST be coded
+ * using one of the ISO 6523 ICD list.": UBL admits it in a party identification
+ * of the seller and the payee only, and CII in no `ram:GlobalID` at all, which
+ * is where CII writes an identifier with a scheme. Nothing is left out
+ * silently.
+ * @param accountingDoc The document
+ * @param targetFormat The format being written
+ */
+export const assertPartyIdentifiersWritable = (accountingDoc: Pick<TAccountingDoc, 'to'>, targetFormat: string): void => {
+  const entries: unknown = (accountingDoc.to as { additionalIdentifiers?: unknown } | undefined)?.additionalIdentifiers;
+  if (!Array.isArray(entries)) {
+    return;
+  }
+  entries.forEach((entry: unknown, index: number) => {
+    const { scheme } = (entry ?? {}) as { scheme?: unknown };
+    if (typeof scheme === 'string' && scheme.trim().toUpperCase() === 'SEPA') {
+      throw new EInvoiceFormatError(
+        `BR-CL-10: Any identifier identification scheme identifier MUST be coded using one of the ISO 6523 ICD list. to.additionalIdentifiers[${index}] states the scheme SEPA, the creditor identifier (BT-90) of a seller or payee, which a buyer identifier (BT-46) cannot have`,
+        { targetFormat, unsupportedFeatures: ['BR-CL-10'] },
+      );
+    }
+  });
+};

package/ts/formats/utils/peppol.profile.ts

@@ -0,0 +1,13 @@
+import { UBL_CUSTOMIZATION_IDS } from '../ubl/ubl.types.js';
+
+/**
+ * Whether a specification identifier (BT-24) is that of PEPPOL BIS Billing 3.0,
+ * `urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0`,
+ * the one identifier the PEPPOL BIS Billing 3.0 rules apply to. PINT, the
+ * A-NZ, Singapore and other PEPPOL derivatives, and the PEPPOL business process
+ * type (BT-23, `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`), which an
+ * EN 16931 document may state as well, do not make a document one.
+ * @param customizationId The specification identifier
+ */
+export const isPeppolBisBilling3 = (customizationId: string | undefined): boolean =>
+  (customizationId ?? '').trim() === UBL_CUSTOMIZATION_IDS.PEPPOL_BIS;

package/ts/formats/utils/seller.identifier.ts

@@ -0,0 +1,102 @@
+import type { TAccountingDoc } from '../../interfaces/common.js';
+import { EInvoiceFormatError } from '../../errors.js';
+import { DOMParser, xpath } from '../../plugins.js';
+import { CII_NAMESPACES } from '../cii/cii.types.js';
+import { UBL_NAMESPACES } from '../ubl/ubl.types.js';
+import { getPartyIdentifiers } from './party.identifier.js';
+
+/**
+ * The official text of EN 16931 BR-CO-26 (CEN/TC 434 EN 16931 validation
+ * artefacts 1.3.16, fatal in UBL and CII)
+ */
+export const BR_CO_26_TEXT =
+  'In order for the buyer to automatically identify a supplier, the Seller identifier (BT-29), the Seller legal registration identifier (BT-30) and/or the Seller VAT identifier (BT-31) shall be present.';
+
+const ublSelect = xpath.useNamespaces({ cac: UBL_NAMESPACES.CAC, cbc: UBL_NAMESPACES.CBC });
+const ciiSelect = xpath.useNamespaces({ rsm: CII_NAMESPACES.RSM, ram: CII_NAMESPACES.RAM });
+const nodesOf = (result: xpath.SelectReturnType): Node[] => (Array.isArray(result) ? result : []);
+
+/**
+ * Whether the seller of a UBL document meets BR-CO-26, as the CEN artefacts
+ * check it on `cac:AccountingSupplierParty`: a VAT identifier (BT-31, a
+ * `cac:PartyTaxScheme` with the scheme VAT), a seller identifier (BT-29, a
+ * `cac:PartyIdentification` whose scheme is not SEPA) or a legal registration
+ * identifier (BT-30, `cac:PartyLegalEntity/cbc:CompanyID`). A document without
+ * a seller party is not checked; BR-06 and BR-08 report that.
+ * @param doc The UBL document
+ */
+export const ublSellerMeetsBrCo26 = (doc: Document): boolean => {
+  const sellers = nodesOf(ublSelect('/*/cac:AccountingSupplierParty', doc));
+  return sellers.every((seller) => {
+    const vatSchemes = nodesOf(ublSelect('./cac:Party/cac:PartyTaxScheme/cac:TaxScheme/cbc:ID', seller)).filter(
+      (node) => (node.textContent ?? '').trim().toUpperCase() === 'VAT',
+    );
+    const hasVatIdentifier = vatSchemes.some(
+      (scheme) => nodesOf(ublSelect('../../cbc:CompanyID', scheme)).length > 0,
+    );
+    const hasSellerIdentifier = nodesOf(ublSelect("./cac:Party/cac:PartyIdentification/cbc:ID[not(@schemeID = 'SEPA')]", seller)).length > 0;
+    const hasLegalRegistration = nodesOf(ublSelect('./cac:Party/cac:PartyLegalEntity/cbc:CompanyID', seller)).length > 0;
+    return hasVatIdentifier || hasSellerIdentifier || hasLegalRegistration;
+  });
+};
+
+/**
+ * Whether the seller of a CII document meets BR-CO-26, as the CEN artefacts
+ * check it on `ram:SellerTradeParty`: a seller identifier (BT-29, `ram:ID` or
+ * `ram:GlobalID`), a legal registration identifier (BT-30,
+ * `ram:SpecifiedLegalOrganization/ram:ID`) or a VAT identifier (BT-31,
+ * `ram:SpecifiedTaxRegistration/ram:ID` with the scheme VA).
+ * @param doc The CII document
+ */
+export const ciiSellerMeetsBrCo26 = (doc: Document): boolean =>
+  nodesOf(ciiSelect('//ram:SellerTradeParty', doc)).every(
+    (seller) =>
+      nodesOf(
+        ciiSelect(
+          "./ram:ID | ./ram:GlobalID | ./ram:SpecifiedLegalOrganization/ram:ID | ./ram:SpecifiedTaxRegistration/ram:ID[@schemeID='VA']",
+          seller,
+        ),
+      ).length > 0,
+  );
+
+/**
+ * Whether the seller of an envelope states an identifier BR-CO-26 accepts:
+ * the VAT identifier (BT-31, `registrationDetails.vatId`), the legal
+ * registration identifier (BT-30, `registrationDetails.registrationId`) or a
+ * seller identifier (BT-29), which a decoded UBL document keeps in the
+ * party's `additionalIdentifiers`. A tax number (BT-32) is none of them.
+ * @param accountingDoc The document
+ */
+export const envelopeSellerMeetsBrCo26 = (accountingDoc: Pick<TAccountingDoc, 'from'>): boolean => {
+  const seller = accountingDoc.from;
+  if (!seller) {
+    return true;
+  }
+  const details = seller.registrationDetails;
+  const hasSellerIdentifier = getPartyIdentifiers(seller).some((identifier) => identifier.scheme?.toUpperCase() !== 'SEPA');
+  return Boolean(details?.vatId?.trim() || details?.registrationId?.trim() || hasSellerIdentifier);
+};
+
+const writtenParser = new DOMParser();
+
+/**
+ * Refuses a written document whose seller fails BR-CO-26, naming the rule; no
+ * identifier is put in place of a missing one. The seller states its VAT
+ * identifier (`registrationDetails.vatId`, BT-31) or its legal registration
+ * identifier (`registrationDetails.registrationId`, BT-30); a tax number
+ * (BT-32) alone does not identify it. A seller identifier (BT-29) is written
+ * from the party's `additionalIdentifiers` (no typed field in the envelope).
+ * @param xml The written document
+ * @param syntax The syntax it is written in
+ * @param targetFormat The format being written
+ */
+export const assertSellerIdentified = (xml: string, syntax: 'ubl' | 'cii', targetFormat: string): void => {
+  const doc = writtenParser.parseFromString(xml, 'application/xml');
+  const meets = syntax === 'ubl' ? ublSellerMeetsBrCo26(doc) : ciiSellerMeetsBrCo26(doc);
+  if (!meets) {
+    throw new EInvoiceFormatError(
+      `BR-CO-26: ${BR_CO_26_TEXT} The seller states none of them: set from.registrationDetails.vatId (BT-31) or .registrationId (BT-30), or give the seller a seller identifier (BT-29) in from.additionalIdentifiers, where a decoded document keeps it; a tax number (BT-32, .taxNumber) does not identify the seller`,
+      { targetFormat, unsupportedFeatures: ['BR-CO-26'] },
+    );
+  }
+};