@ekwo-ai/factur-x 0.11.1 → 0.12.1

package/CHANGELOG.md

@@ -6,6 +6,31 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+### Added
+- **Reading a received invoice.** `readCii()` reads a CII D16B
+  `CrossIndustryInvoice` of any profile — MINIMUM, BASIC WL, BASIC, EN 16931,
+  EXTENDED, ZUGFeRD 2.x spellings included — and says which profile it
+  declares. `readFacturX()` of `@ekwo-ai/factur-x/pdf` reads it out of the
+  PDF. The result is the `ReceivedInvoice` that `readUbl()` of
+  `@ekwo-ai/peppol-ubl` returns, from byte-for-byte copies of the same files:
+  figures as the decimal text the file wrote, the EN 16931 arithmetic reported
+  in `violations`, an `InvoiceFileError` with a code for what is not an
+  invoice.
+- `extractFacturX()` also finds `xrechnung.xml`, the name ZUGFeRD gives the
+  XML of its XRECHNUNG profile.
+- `buildXmpMetadata()` takes `author`, `subject`, `keywords` and
+  `creationDate`, written as `dc:creator`, `dc:description`, `pdf:Keywords`
+  and `xmp:CreateDate`. Without them it writes what it wrote before.
+
+### Fixed
+- **The XMP of `embedFacturX()` now says what the information dictionary
+  says.** It wrote the tool as `dc:creator` beside an `Author` naming the
+  seller, the time of embedding as `xmp:CreateDate` beside the PDF's own
+  `CreationDate`, and nothing for `Subject` or `Keywords`; PDF/A wants each
+  entry of the dictionary and its XMP counterpart to agree. The packet is now
+  written from the dictionary of the PDF it is given, after the title, creator,
+  producer and dates of the options are set in it.
+
 ## [0.2.0] — 2026-09-14
 
 Released with Ekwo OS `v0.2.0`, the first tagged release of the repository this

package/README.md

@@ -7,7 +7,9 @@ Factur-X / ZUGFeRD electronic invoices in TypeScript.
   `BR-IC`, `BR-G`, `BR-O`). Profiles MINIMUM, BASIC WL, BASIC (default), EN 16931, EXTENDED.
 - **PDF/A-3 embedding.** Attaches the XML as `factur-x.xml` with `AFRelationship /Alternative`
   and writes the XMP packet with the Factur-X extension schema.
-- **Extraction.** Reads `factur-x.xml` or `zugferd-invoice.xml` back from any PDF.
+- **Extraction.** Reads `factur-x.xml`, `zugferd-invoice.xml` or `xrechnung.xml` back from any PDF.
+- **Reading a received invoice.** `readCii` and `readFacturX` turn the CII of any profile
+  into the same plain result `@ekwo-ai/peppol-ubl` returns from UBL — see [Reading](#reading).
 - **Totals you can trust.** One VAT group per category and rate, VAT computed on the rounded
   basis, prepayments, credit notes referencing the original invoice.
 - Zero dependencies for the XML part; `pdf-lib` only for the PDF part (separate entry point).
@@ -92,17 +94,91 @@ back to `C62` (unit). See `UNIT_CODES` and `toUnitCode`.
 | `buildXmpMetadata`, `CONFORMANCE_LEVELS`, `GUIDELINES`, `DOCUMENT_TYPE_CODES` | Constants of the specification. |
 | `embedFacturX(pdf, xml, { profile?, title?, creator?, producer?, date? })` *(`/pdf`)* | Returns a new PDF with the XML attached and the PDF/A-3 XMP packet. |
 | `extractFacturX(pdf)` *(`/pdf`)* | `{ filename, xml }` or `null`. |
+| `readCii(xml, { maxBytes?, maxDepth?, maxElements? })` | `{ invoice, violations, profile }`, see [Reading](#reading). |
+| `readFacturX(pdf, options?)` *(`/pdf`)* | The same, read out of the PDF, with the `filename` of the attachment. |
+| `InvoiceFileError`, `profileOf`, `checkReceived`, `isValidIban`, `CREDIT_NOTE_TYPE_CODES` | What reading refuses, and the helpers it uses. |
 
 ## Scope and limitations
 
 - Allowances and charges (BG-20, BG-21, BG-27, BG-28), gross prices with discounts and
   multiple deliveries are not modelled yet.
-- The PDF part embeds the data and declares PDF/A-3; it does not convert the visual PDF to
-  PDF/A (fonts, colour profiles, output intent). Validate the result with the tool of your
+- The PDF part embeds the data, declares PDF/A-3 and writes an XMP packet that agrees with
+  the document information dictionary; it does not convert the visual PDF to PDF/A (fonts,
+  colour profiles, output intent). A PDF rendered by
+  [`@ekwo-ai/invoice-pdf`](../invoice-pdf/README.md#pdfa-3) has them, and veraPDF finds no
+  failed rule of PDF/A-3b in it once embedded; validate any other PDF with the tool of your
   platform before going live.
 - No XSD or Schematron validation is performed. Test against a validator such as the FNFE
   Factur-X validator or the Mustang project.
 
+## Reading
+
+The invoice a supplier sends you as Factur-X or ZUGFeRD, turned into a plain object a
+purchase draft can be made from.
+
+```ts
+import { readCii, InvoiceFileError } from '@ekwo-ai/factur-x';
+import { readFacturX } from '@ekwo-ai/factur-x/pdf';
+
+const { invoice, violations, profile, filename } = await readFacturX(pdfBytes);
+profile;                 // 'minimum' | 'basic-wl' | 'basic' | 'en16931' | 'extended' | null
+invoice.kind;            // 'invoice' | 'credit_note', from the type code
+invoice.totals.payable;  // '648.40', a decimal as text, never a number
+
+const same = readCii(xmlBytesOrText);   // the XML alone, without pdf-lib
+```
+
+- `readCii(input: string | Uint8Array, options?: ReadOptions): ReceivedCiiFile` reads a
+  CII D16B `CrossIndustryInvoice` — Factur-X 1.0, ZUGFeRD 2.x, an XRechnung in CII — and
+  returns `{ invoice, violations, profile }`.
+- `readFacturX(pdf: Uint8Array | ArrayBuffer, options?: ReadOptions): Promise<ReceivedFacturX>`
+  *(`/pdf`)* finds the XML attached to the PDF and reads it with `readCii`; the result
+  adds the `filename` it was attached under.
+- `profileOf(guideline)` is the profile a guideline identifier (BT-24) declares. An
+  EN 16931 CIUS (`urn:cen.eu:en16931:2017#compliant#…`, XRechnung for one) reads as
+  `en16931`; an identifier this package does not know is `null`, and
+  `invoice.customizationId` keeps what the file wrote.
+
+**The shape is the UBL reader's.** `invoice` is a `ReceivedInvoice`, the type
+`readUbl` of `@ekwo-ai/peppol-ubl` returns: each field names the EN 16931 business term it
+holds, and a business term is in the same field whichever syntax carried it — the test
+suite reads one invoice written in both syntaxes and gets the same object from both. The
+two bricks do not depend on each other; they hold byte-for-byte copies of the files that
+define the shape, the checks, the XML reader and the decimals, and a test keeps them
+identical. `syntax` says which one was read.
+
+**Nothing is recomputed, nothing is defaulted.** A figure is the text the file wrote,
+checked to be a decimal; an absent element is `null` — a MINIMUM or BASIC WL file has no
+line and no line total, and comes back so. The arithmetic of EN 16931 (BR-CO-10 to
+BR-CO-17) is checked on exact decimals and reported in `violations`. CII-specific
+findings are there too: `invalid_iban` (an `IBANID` whose check digits fail, still
+returned as written), `invalid_attachment`, `unsupported_date_format` (a date in a
+format other than 102, returned as `null`). Where CII writes something once for the
+document that UBL writes per means of payment — the payment reference (BT-83) and the
+direct debit mandate (BT-89) — it is returned on every means of payment.
+
+**What is not an invoice throws an `InvoiceFileError`** with a `code`: the codes of the
+UBL reader (`malformed_xml`, `unsupported_encoding`, `doctype_forbidden`,
+`undefined_entity`, `too_large`, `too_deep`, `too_many_elements`, `not_an_invoice`,
+`missing_element`, `invalid_value`), plus `not_a_pdf` and `no_embedded_invoice` from
+`readFacturX`. A line is required except in the MINIMUM and BASIC WL profiles. No raw
+error of the XML parser or of `pdf-lib` escapes. The XML is read by a strict reader of
+the package's own: no DOCTYPE and so no entity expansion, UTF-8 only, size, depth and
+element limits.
+
+**Limits.**
+
+- The PDF is opened with `pdf-lib`, already the dependency of the `/pdf` entry point:
+  the attachment is found in the `EmbeddedFiles` name tree of the catalogue, under one
+  of the three names above. An attachment reachable only from a page annotation, an
+  encrypted PDF, and a stream in a filter `pdf-lib` does not decode are not read: they
+  are refused with one of the codes above, never read wrongly. The XMP metadata is not read: the profile
+  comes from the XML.
+- ZUGFeRD 1.0 (`CrossIndustryDocument`, another namespace) is refused as
+  `not_an_invoice`.
+- Elements of EXTENDED beyond EN 16931 (several deliveries, line sub-structures…) are not
+  read. Nothing is validated against the CII schema or a Schematron.
+
 ## Development
 
 ```sh

package/dist/cii-read.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A received CII invoice or credit note, read.
+ *
+ * The XML of a Factur-X or ZUGFeRD file — UN/CEFACT Cross Industry Invoice
+ * D16B — turned into the plain shape of `received.ts`, which the UBL reader of
+ * the Peppol brick returns too: a business term is in the same field whichever
+ * syntax carried it. The reader follows the CII binding of EN 16931 (which
+ * business term lives in which element) and reads every profile of Factur-X
+ * 1.0 and ZUGFeRD 2.x, from MINIMUM to EXTENDED; `profile` says which one the
+ * file declares, and what a lighter profile does not carry comes back null or
+ * empty, never invented. EXTENDED elements beyond EN 16931 are not read.
+ *
+ * It reads what the file says and judges only the arithmetic (see
+ * `received-checks.ts`). A file that is not an invoice at all — not XML, not
+ * CII, no number, an amount that is not one — is an {@link InvoiceFileError},
+ * never a raw error of the parser.
+ */
+import type { ReadOptions, ReceivedInvoiceFile } from './received.js';
+import type { Profile } from './types.js';
+/**
+ * The profile a guideline identifier declares. Another specification built on
+ * EN 16931 by restriction — a CIUS such as XRechnung, written
+ * `urn:cen.eu:en16931:2017#compliant#…` — is EN 16931 for a reader: it holds
+ * nothing EN 16931 does not. Anything else is null, and `customizationId`
+ * keeps what the file wrote.
+ */
+export declare function profileOf(guideline: string | null): Profile | null;
+/** What {@link readCii} returns: the invoice, what does not add up, and the profile the file declares. */
+export interface ReceivedCiiFile extends ReceivedInvoiceFile {
+    /** From the guideline identifier (BT-24); null where it names no profile this reader knows. */
+    profile: Profile | null;
+}
+/**
+ * Reads the XML of a Factur-X or ZUGFeRD invoice: a CII D16B
+ * `CrossIndustryInvoice`, whatever its profile. To read it out of the PDF,
+ * `readFacturX` of `@ekwo-ai/factur-x/pdf`.
+ *
+ * Throws an {@link InvoiceFileError} when there is no invoice to return: the
+ * bytes are not XML or not UTF-8, the document is not CII, or it lacks a
+ * number, a type code, a date, a currency or its totals, or holds an amount
+ * or a date that is not one. Everything else comes back, with `violations`
+ * naming what does not add up.
+ *
+ * Whether the document is a credit note is said by its type code (BT-3)
+ * alone, as CII has a single root for both; the figures stay as written.
+ */
+export declare function readCii(input: string | Uint8Array, options?: ReadOptions): ReceivedCiiFile;
+//# sourceMappingURL=cii-read.d.ts.map

package/dist/cii-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cii-read.d.ts","sourceRoot":"","sources":["../src/cii-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAEV,WAAW,EAOX,mBAAmB,EAMpB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAkC1C;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAKlE;AAED,0GAA0G;AAC1G,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,+FAA+F;IAC/F,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AA+PD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,GAAE,WAAgB,GAAG,eAAe,CAqK9F"}

package/dist/cii-read.js

@@ -0,0 +1,462 @@
+/**
+ * A received CII invoice or credit note, read.
+ *
+ * The XML of a Factur-X or ZUGFeRD file — UN/CEFACT Cross Industry Invoice
+ * D16B — turned into the plain shape of `received.ts`, which the UBL reader of
+ * the Peppol brick returns too: a business term is in the same field whichever
+ * syntax carried it. The reader follows the CII binding of EN 16931 (which
+ * business term lives in which element) and reads every profile of Factur-X
+ * 1.0 and ZUGFeRD 2.x, from MINIMUM to EXTENDED; `profile` says which one the
+ * file declares, and what a lighter profile does not carry comes back null or
+ * empty, never invented. EXTENDED elements beyond EN 16931 are not read.
+ *
+ * It reads what the file says and judges only the arithmetic (see
+ * `received-checks.ts`). A file that is not an invoice at all — not XML, not
+ * CII, no number, an amount that is not one — is an {@link InvoiceFileError},
+ * never a raw error of the parser.
+ */
+import { InvoiceFileError } from './errors.js';
+import { CREDIT_NOTE_TYPE_CODES, checkReceived, decimalText, decodeBase64, isValidIban } from './received-checks.js';
+import { parseXml } from './xml.js';
+const NS = {
+    rsm: 'urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100',
+    ram: 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100',
+    udt: 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100',
+    qdt: 'urn:un:unece:uncefact:data:standard:QualifiedDataType:100',
+    ublInvoice: 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2',
+    ublCreditNote: 'urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2',
+};
+const CII_NAMESPACES = new Set([NS.rsm, NS.ram, NS.udt, NS.qdt]);
+const DEFAULTS = { maxBytes: 64 * 1024 * 1024, maxDepth: 64, maxElements: 500_000 };
+/**
+ * The guideline identifiers (BT-24) of Factur-X 1.0 and ZUGFeRD 2.x, by
+ * profile, as the specifications of the two (FNFE-MPE and FeRD) list them.
+ * The `urn:zugferd.de:2p0` spellings are those of ZUGFeRD 2.0, written before
+ * the two specifications converged on the Factur-X ones.
+ */
+const PROFILE_GUIDELINES = {
+    'urn:factur-x.eu:1p0:minimum': 'minimum',
+    'urn:zugferd.de:2p0:minimum': 'minimum',
+    'urn:factur-x.eu:1p0:basicwl': 'basic-wl',
+    'urn:zugferd.de:2p0:basicwl': 'basic-wl',
+    'urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic': 'basic',
+    'urn:cen.eu:en16931:2017#compliant#urn:zugferd.de:2p0:basic': 'basic',
+    'urn:cen.eu:en16931:2017': 'en16931',
+    'urn:cen.eu:en16931:2017#conformant#urn:factur-x.eu:1p0:extended': 'extended',
+    'urn:cen.eu:en16931:2017#conformant#urn:zugferd.de:2p0:extended': 'extended',
+};
+/**
+ * The profile a guideline identifier declares. Another specification built on
+ * EN 16931 by restriction — a CIUS such as XRechnung, written
+ * `urn:cen.eu:en16931:2017#compliant#…` — is EN 16931 for a reader: it holds
+ * nothing EN 16931 does not. Anything else is null, and `customizationId`
+ * keeps what the file wrote.
+ */
+export function profileOf(guideline) {
+    if (guideline === null)
+        return null;
+    const known = PROFILE_GUIDELINES[guideline];
+    if (known !== undefined)
+        return known;
+    return guideline.startsWith('urn:cen.eu:en16931:2017#compliant#') ? 'en16931' : null;
+}
+function isCii(element, name) {
+    return element.name === name && CII_NAMESPACES.has(element.namespace);
+}
+function find(parent, path) {
+    let current = parent;
+    for (const name of path) {
+        if (current === undefined)
+            return undefined;
+        current = current.children.find((each) => isCii(each, name));
+    }
+    return current;
+}
+function all(parent, name) {
+    if (parent === undefined)
+        return [];
+    return parent.children.filter((each) => isCii(each, name));
+}
+/** The trimmed text at a path, or null when absent or blank. */
+function text(parent, ...path) {
+    const value = find(parent, path)?.text.trim();
+    return value === undefined || value === '' ? null : value;
+}
+function attribute(element, name) {
+    const value = element?.attributes[name]?.trim();
+    return value === undefined || value === '' ? null : value;
+}
+function required(parent, what, ...path) {
+    const value = text(parent, ...path);
+    if (value === null)
+        throw new InvoiceFileError('missing_element', `the document has no ${what} (${path.join('/')})`);
+    return value;
+}
+function amount(parent, what, ...path) {
+    const value = text(parent, ...path);
+    return value === null ? null : decimalText(value, what);
+}
+function requiredAmount(parent, what, ...path) {
+    return decimalText(required(parent, what, ...path), what);
+}
+function identifier(element) {
+    const value = element?.text.trim();
+    if (element === undefined || value === undefined || value === '')
+        return null;
+    return { value, scheme: attribute(element, 'schemeID') };
+}
+const DAY_102 = /^([0-9]{4})([0-9]{2})([0-9]{2})$/;
+/**
+ * One reading, holding the violations it finds on the way: a date in a format
+ * EN 16931 does not use is reported and returned as null rather than refused.
+ */
+class Reader {
+    violations = [];
+    /**
+     * A date of CII: a `DateTimeString` (or `DateString`) of format 102,
+     * `YYYYMMDD` — the only format the CII binding of EN 16931 (EN 16931-3-3)
+     * uses for a date. `holder` is the element that contains the string,
+     * `IssueDateTime` and the like.
+     */
+    date(holder, what) {
+        if (holder === undefined)
+            return null;
+        const string = holder.children.find((each) => isCii(each, 'DateTimeString') || isCii(each, 'DateString'));
+        const raw = string?.text.trim() ?? '';
+        if (string === undefined || raw === '')
+            return null;
+        const format = attribute(string, 'format');
+        if (format !== null && format !== '102') {
+            this.violations.push({
+                code: 'unsupported_date_format',
+                message: `${what} is written in format ${format}; EN 16931 dates are format 102 (YYYYMMDD), and it was not read.`,
+            });
+            return null;
+        }
+        const match = DAY_102.exec(raw);
+        const year = Number(match?.[1]);
+        const month = Number(match?.[2]);
+        const day = Number(match?.[3]);
+        const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+        const length = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+        if (match === null || length === undefined || day < 1 || day > length) {
+            throw new InvoiceFileError('invalid_value', `${what} is not a date: ${JSON.stringify(raw)}`);
+        }
+        return `${match[1]}-${match[2]}-${match[3]}`;
+    }
+    period(element, what) {
+        if (element === undefined)
+            return null;
+        return {
+            start: this.date(find(element, ['StartDateTime']), `the start of ${what}`),
+            end: this.date(find(element, ['EndDateTime']), `the end of ${what}`),
+        };
+    }
+    /** CII says which kind of account it holds; an IBAN whose digits fail is still the IBAN the file wrote, and reported. */
+    iban(value, what) {
+        if (value === null)
+            return null;
+        const compact = value.replace(/\s+/g, '').toUpperCase();
+        if (!isValidIban(compact)) {
+            this.violations.push({ code: 'invalid_iban', message: `${what}, ${value}, is written as an IBAN and its check digits fail.` });
+        }
+        return { kind: 'iban', value: compact };
+    }
+}
+// --- the parts -------------------------------------------------------------
+function address(element) {
+    if (element === undefined)
+        return null;
+    const lines = [text(element, 'LineOne'), text(element, 'LineTwo'), text(element, 'LineThree')].filter((line) => line !== null);
+    const result = {
+        lines,
+        city: text(element, 'CityName'),
+        postalCode: text(element, 'PostcodeCode'),
+        region: text(element, 'CountrySubDivisionName'),
+        country: text(element, 'CountryID'),
+    };
+    return lines.length > 0 || Object.values(result).some((value) => typeof value === 'string') ? result : null;
+}
+function party(element, who) {
+    let vatId = null;
+    let taxRegistrationId = null;
+    for (const registration of all(element, 'SpecifiedTaxRegistration')) {
+        const id = find(registration, ['ID']);
+        const value = id?.text.trim();
+        if (value === undefined || value === '')
+            continue;
+        const scheme = (attribute(id, 'schemeID') ?? '').toUpperCase();
+        if (scheme === 'VA')
+            vatId ??= value;
+        else if (scheme === 'FC' && who === 'seller')
+            taxRegistrationId ??= value;
+    }
+    const legal = find(element, ['SpecifiedLegalOrganization']);
+    const contact = find(element, ['DefinedTradeContact']);
+    const contactFields = {
+        name: text(contact, 'PersonName') ?? text(contact, 'DepartmentName'),
+        phone: text(contact, 'TelephoneUniversalCommunication', 'CompleteNumber'),
+        email: text(contact, 'EmailURIUniversalCommunication', 'URIID'),
+    };
+    return {
+        name: text(element, 'Name'),
+        tradeName: text(legal, 'TradingBusinessName'),
+        // BT-29 / BT-46: GlobalID where the identifier has a scheme, ID where it has none.
+        identifiers: [...all(element, 'ID'), ...all(element, 'GlobalID')]
+            .map((each) => identifier(each))
+            .filter((each) => each !== null),
+        legalId: identifier(find(legal, ['ID'])),
+        vatId,
+        taxRegistrationId,
+        legalForm: who === 'seller' ? text(element, 'Description') : null,
+        electronicAddress: identifier(find(element, ['URIUniversalCommunication', 'URIID'])),
+        address: address(find(element, ['PostalTradeAddress'])),
+        contact: Object.values(contactFields).some((value) => value !== null) ? contactFields : null,
+    };
+}
+function allowanceCharge(element, where, onLine) {
+    const indicator = text(element, 'ChargeIndicator', 'Indicator');
+    if (indicator !== 'true' && indicator !== 'false') {
+        throw new InvoiceFileError('invalid_value', `an allowance or charge of ${where} says neither true nor false: ${JSON.stringify(indicator)}`);
+    }
+    const charge = indicator === 'true';
+    const what = `${charge ? 'a charge' : 'an allowance'} of ${where}`;
+    return {
+        charge,
+        amount: requiredAmount(element, `the amount of ${what}`, 'ActualAmount'),
+        baseAmount: amount(element, `the base of ${what}`, 'BasisAmount'),
+        percent: amount(element, `the percentage of ${what}`, 'CalculationPercent'),
+        reason: text(element, 'Reason'),
+        reasonCode: text(element, 'ReasonCode'),
+        vatCategory: onLine ? null : text(element, 'CategoryTradeTax', 'CategoryCode'),
+        vatRate: onLine ? null : amount(element, `the VAT rate of ${what}`, 'CategoryTradeTax', 'RateApplicablePercent'),
+    };
+}
+function line(reader, element, position) {
+    const document = find(element, ['AssociatedDocumentLineDocument']);
+    const id = text(document, 'LineID');
+    if (id === null)
+        throw new InvoiceFileError('missing_element', `line ${position} has no identifier (BT-126)`);
+    const where = `line ${id}`;
+    const product = find(element, ['SpecifiedTradeProduct']);
+    const agreement = find(element, ['SpecifiedLineTradeAgreement']);
+    const gross = find(agreement, ['GrossPriceProductTradePrice']);
+    const net = find(agreement, ['NetPriceProductTradePrice']);
+    const settlement = find(element, ['SpecifiedLineTradeSettlement']);
+    const tax = find(settlement, ['ApplicableTradeTax']);
+    const quantity = find(element, ['SpecifiedLineTradeDelivery', 'BilledQuantity']);
+    // BT-149 and BT-150 are written on the net price, and may be on the gross one.
+    const baseQuantity = find(net, ['BasisQuantity']) ?? find(gross, ['BasisQuantity']);
+    const summation = find(settlement, ['SpecifiedTradeSettlementLineMonetarySummation']);
+    return {
+        id,
+        note: text(document, 'IncludedNote', 'Content'),
+        quantity: quantity === undefined || quantity.text.trim() === '' ? null : decimalText(quantity.text, `the quantity of ${where}`),
+        unitCode: attribute(quantity, 'unitCode'),
+        netAmount: requiredAmount(summation, `the net amount of ${where}`, 'LineTotalAmount'),
+        orderLineReference: text(agreement, 'BuyerOrderReferencedDocument', 'LineID'),
+        period: reader.period(find(settlement, ['BillingSpecifiedPeriod']), where),
+        allowances: all(settlement, 'SpecifiedTradeAllowanceCharge').map((each) => allowanceCharge(each, where, true)),
+        netPrice: amount(net, `the net price of ${where}`, 'ChargeAmount'),
+        priceDiscount: amount(gross, `the price discount of ${where}`, 'AppliedTradeAllowanceCharge', 'ActualAmount'),
+        grossPrice: amount(gross, `the gross price of ${where}`, 'ChargeAmount'),
+        priceBaseQuantity: baseQuantity === undefined || baseQuantity.text.trim() === ''
+            ? null
+            : decimalText(baseQuantity.text, `the base quantity of the price of ${where}`),
+        priceBaseUnitCode: attribute(baseQuantity, 'unitCode'),
+        vatCategory: text(tax, 'CategoryCode'),
+        vatRate: amount(tax, `the VAT rate of ${where}`, 'RateApplicablePercent'),
+        name: text(product, 'Name'),
+        description: text(product, 'Description'),
+        sellerItemId: text(product, 'SellerAssignedID'),
+        buyerItemId: text(product, 'BuyerAssignedID'),
+        standardItemId: identifier(find(product, ['GlobalID'])),
+    };
+}
+function paymentMeans(reader, element, reference, mandateReference) {
+    const payee = find(element, ['PayeePartyCreditorFinancialAccount']);
+    const payeeIban = text(payee, 'IBANID');
+    const proprietary = text(payee, 'ProprietaryID');
+    return {
+        code: text(element, 'TypeCode'),
+        text: text(element, 'Information'),
+        reference,
+        account: payeeIban !== null
+            ? reader.iban(payeeIban, 'The account to pay')
+            : proprietary === null
+                ? null
+                : { kind: 'other', value: proprietary },
+        accountName: text(payee, 'AccountName'),
+        bic: text(element, 'PayeeSpecifiedCreditorFinancialInstitution', 'BICID'),
+        cardNumber: text(element, 'ApplicableTradeSettlementFinancialCard', 'ID'),
+        mandateReference,
+        debitedAccount: reader.iban(text(element, 'PayerPartyDebtorFinancialAccount', 'IBANID'), 'The account to debit'),
+    };
+}
+/**
+ * Reads the XML of a Factur-X or ZUGFeRD invoice: a CII D16B
+ * `CrossIndustryInvoice`, whatever its profile. To read it out of the PDF,
+ * `readFacturX` of `@ekwo-ai/factur-x/pdf`.
+ *
+ * Throws an {@link InvoiceFileError} when there is no invoice to return: the
+ * bytes are not XML or not UTF-8, the document is not CII, or it lacks a
+ * number, a type code, a date, a currency or its totals, or holds an amount
+ * or a date that is not one. Everything else comes back, with `violations`
+ * naming what does not add up.
+ *
+ * Whether the document is a credit note is said by its type code (BT-3)
+ * alone, as CII has a single root for both; the figures stay as written.
+ */
+export function readCii(input, options = {}) {
+    const limits = { ...DEFAULTS, ...options };
+    const root = parseXml(input, limits);
+    if (root.namespace === NS.ublInvoice || root.namespace === NS.ublCreditNote) {
+        throw new InvoiceFileError('not_an_invoice', 'the file is a UBL invoice (Peppol), not CII: read it with the UBL reader');
+    }
+    if (root.name !== 'CrossIndustryInvoice' || root.namespace !== NS.rsm) {
+        throw new InvoiceFileError('not_an_invoice', `the document is <${root.name}> in ${root.namespace === '' ? 'no namespace' : root.namespace}, not a CII D16B CrossIndustryInvoice`);
+    }
+    const reader = new Reader();
+    const context = find(root, ['ExchangedDocumentContext']);
+    const exchanged = find(root, ['ExchangedDocument']);
+    if (exchanged === undefined)
+        throw new InvoiceFileError('missing_element', 'the document has no header (ExchangedDocument)');
+    const transaction = find(root, ['SupplyChainTradeTransaction']);
+    const agreement = find(transaction, ['ApplicableHeaderTradeAgreement']);
+    const delivery = find(transaction, ['ApplicableHeaderTradeDelivery']);
+    const settlement = find(transaction, ['ApplicableHeaderTradeSettlement']);
+    if (settlement === undefined) {
+        throw new InvoiceFileError('missing_element', 'the document has no settlement (ApplicableHeaderTradeSettlement)');
+    }
+    const guideline = text(context, 'GuidelineSpecifiedDocumentContextParameter', 'ID');
+    const typeCode = required(exchanged, 'type code (BT-3)', 'TypeCode');
+    const number = required(exchanged, 'number', 'ID');
+    const issueDate = reader.date(find(exchanged, ['IssueDateTime']), 'the issue date');
+    if (issueDate === null)
+        throw new InvoiceFileError('missing_element', 'the document has no issue date (IssueDateTime)');
+    const currency = required(settlement, 'currency', 'InvoiceCurrencyCode');
+    const taxCurrency = text(settlement, 'TaxCurrencyCode');
+    // BT-110 and BT-111 are both TaxTotalAmount, told apart by their currency.
+    const summation = find(settlement, ['SpecifiedTradeSettlementHeaderMonetarySummation']);
+    if (summation === undefined) {
+        throw new InvoiceFileError('missing_element', 'the document has no totals (SpecifiedTradeSettlementHeaderMonetarySummation)');
+    }
+    const taxTotals = all(summation, 'TaxTotalAmount');
+    const inCurrency = (each, code) => {
+        const written = attribute(each, 'currencyID');
+        return written === null ? code === currency : written === code;
+    };
+    const documentTax = taxTotals.find((each) => inCurrency(each, currency)) ?? (taxCurrency === null ? taxTotals[0] : undefined);
+    const taxCurrencyTax = taxCurrency !== null && taxCurrency !== currency
+        ? taxTotals.find((each) => each !== documentTax && inCurrency(each, taxCurrency))
+        : undefined;
+    const totalOf = (element, what) => element === undefined || element.text.trim() === '' ? null : decimalText(element.text, what);
+    const taxes = all(settlement, 'ApplicableTradeTax').map((group) => {
+        const label = `the VAT group ${text(group, 'CategoryCode') ?? '?'} ${text(group, 'RateApplicablePercent') ?? ''}`.trim();
+        return {
+            category: text(group, 'CategoryCode'),
+            rate: amount(group, `the rate of ${label}`, 'RateApplicablePercent'),
+            base: requiredAmount(group, `the base of ${label}`, 'BasisAmount'),
+            tax: requiredAmount(group, `the tax of ${label}`, 'CalculatedAmount'),
+            exemptionReasonCode: text(group, 'ExemptionReasonCode'),
+            exemptionReason: text(group, 'ExemptionReason'),
+        };
+    });
+    // BT-7 is written on the VAT breakdown in CII, once per group and the same in each.
+    const taxPointDate = all(settlement, 'ApplicableTradeTax')
+        .map((group) => reader.date(find(group, ['TaxPointDate']), 'the tax point date'))
+        .find((each) => each !== null) ?? null;
+    // BG-24 is an additional document of type 916; type 130 is an invoiced
+    // object (BT-18) and type 50 a tender or lot (BT-17), neither an attachment.
+    const attachments = [];
+    for (const reference of all(agreement, 'AdditionalReferencedDocument')) {
+        const documentType = text(reference, 'TypeCode');
+        if (documentType === '130' || documentType === '50')
+            continue;
+        const embedded = find(reference, ['AttachmentBinaryObject']);
+        let content = null;
+        if (embedded !== undefined) {
+            content = decodeBase64(embedded.text);
+            if (content === null) {
+                reader.violations.push({
+                    code: 'invalid_attachment',
+                    message: `The document ${text(reference, 'IssuerAssignedID') ?? 'attached'} is not base64, and was not decoded.`,
+                });
+            }
+        }
+        attachments.push({
+            id: text(reference, 'IssuerAssignedID'),
+            description: text(reference, 'Name'),
+            filename: attribute(embedded, 'filename'),
+            mimeType: attribute(embedded, 'mimeCode'),
+            content,
+            uri: text(reference, 'URIID'),
+        });
+    }
+    // BT-9, BT-20 and BT-89 are in the payment terms; BT-83 is one reference for
+    // the document. Each is returned on every means of payment, as UBL has them.
+    const terms = all(settlement, 'SpecifiedTradePaymentTerms');
+    const dueDate = terms.map((each) => reader.date(find(each, ['DueDateDateTime']), 'the due date')).find((each) => each !== null) ?? null;
+    const descriptions = terms.map((each) => text(each, 'Description')).filter((each) => each !== null);
+    const mandate = terms.map((each) => text(each, 'DirectDebitMandateID')).find((each) => each !== null) ?? null;
+    const paymentReference = text(settlement, 'PaymentReference');
+    const shipTo = find(delivery, ['ShipToTradeParty']);
+    const profile = profileOf(guideline);
+    const lineElements = all(transaction, 'IncludedSupplyChainTradeLineItem');
+    if (lineElements.length === 0 && profile !== 'minimum' && profile !== 'basic-wl') {
+        throw new InvoiceFileError('missing_element', 'the document has no line, and its profile is not one that carries none (MINIMUM, BASIC WL)');
+    }
+    const invoice = {
+        syntax: 'cii',
+        customizationId: guideline,
+        profileId: text(context, 'BusinessProcessSpecifiedDocumentContextParameter', 'ID'),
+        kind: CREDIT_NOTE_TYPE_CODES.has(typeCode) ? 'credit_note' : 'invoice',
+        typeCode,
+        number,
+        issueDate,
+        dueDate,
+        taxPointDate,
+        currency,
+        taxCurrency,
+        buyerReference: text(agreement, 'BuyerReference'),
+        orderReference: text(agreement, 'BuyerOrderReferencedDocument', 'IssuerAssignedID'),
+        salesOrderReference: text(agreement, 'SellerOrderReferencedDocument', 'IssuerAssignedID'),
+        contractReference: text(agreement, 'ContractReferencedDocument', 'IssuerAssignedID'),
+        projectReference: text(agreement, 'SpecifiedProcuringProject', 'ID'),
+        accountingCost: text(settlement, 'ReceivableSpecifiedTradeAccountingAccount', 'ID'),
+        precedingInvoices: all(settlement, 'InvoiceReferencedDocument')
+            .filter((each) => text(each, 'IssuerAssignedID') !== null)
+            .map((each) => ({
+            number: text(each, 'IssuerAssignedID'),
+            issueDate: reader.date(find(each, ['FormattedIssueDateTime']), 'the date of a preceding invoice'),
+        })),
+        notes: all(exchanged, 'IncludedNote')
+            .map((each) => text(each, 'Content'))
+            .filter((each) => each !== null),
+        seller: party(find(agreement, ['SellerTradeParty']), 'seller'),
+        buyer: party(find(agreement, ['BuyerTradeParty']), 'buyer'),
+        deliveryDate: reader.date(find(delivery, ['ActualDeliverySupplyChainEvent', 'OccurrenceDateTime']), 'the delivery date'),
+        deliveryAddress: address(find(shipTo, ['PostalTradeAddress'])),
+        invoicingPeriod: reader.period(find(settlement, ['BillingSpecifiedPeriod']), 'the invoicing period'),
+        paymentTerms: descriptions.length === 0 ? null : descriptions.join('\n'),
+        paymentMeans: all(settlement, 'SpecifiedTradeSettlementPaymentMeans').map((each) => paymentMeans(reader, each, paymentReference, mandate)),
+        allowances: all(settlement, 'SpecifiedTradeAllowanceCharge').map((each) => allowanceCharge(each, 'the document', false)),
+        taxes,
+        totals: {
+            lineTotal: amount(summation, 'the sum of the lines', 'LineTotalAmount'),
+            allowanceTotal: amount(summation, 'the sum of the allowances', 'AllowanceTotalAmount'),
+            chargeTotal: amount(summation, 'the sum of the charges', 'ChargeTotalAmount'),
+            taxExclusive: requiredAmount(summation, 'the total without VAT', 'TaxBasisTotalAmount'),
+            taxTotal: totalOf(documentTax, 'the total VAT'),
+            taxTotalInTaxCurrency: totalOf(taxCurrencyTax, 'the total VAT in the tax currency'),
+            taxInclusive: requiredAmount(summation, 'the total with VAT', 'GrandTotalAmount'),
+            prepaid: amount(summation, 'the amount paid', 'TotalPrepaidAmount'),
+            rounding: amount(summation, 'the rounding amount', 'RoundingAmount'),
+            payable: requiredAmount(summation, 'the amount due', 'DuePayableAmount'),
+        },
+        lines: lineElements.map((each, index) => line(reader, each, index + 1)),
+        attachments,
+    };
+    return { invoice, violations: [...reader.violations, ...checkReceived(invoice)], profile };
+}
+//# sourceMappingURL=cii-read.js.map