@endevops/peppol-schema 0.1.2 → 0.1.4

package/dist/schematron.js

@@ -1,11 +1,18 @@
 import { t as PeppolIsoDateString } from "./peppol-iso-date-string-BXLxzxdz.js";
 import { c as chargeReasonCodesKeys, f as currencyCodesKeys, i as vatDateCodesKeys, m as mimeCodesKeys, n as electronicAddressCodesKeys, o as countryCodesKeys, u as allowanceChargeReasonCodesKeys } from "./eas-codes.generated-D8jjHFij.js";
-import { n as normalizeSpace, t as isValidMod97_0208 } from "./is-valid-mod97-0208-CzMOXMO-.js";
-import { c as isValidGLN, d as isValidIBAN, l as isValidMod11, n as checkSEOrgnr, o as checkCF, r as checkPIVAseIT, t as isValidABN, u as greekTinVerification } from "./is-valid-abn-160i38PG.js";
+import { n as normalizeSpace, t as isValidMod97_0208 } from "./is-valid-mod97-0208-CjR324eG.js";
+import { c as isValidGLN, d as isValidIBAN, l as isValidMod11, n as checkSEOrgnr, o as checkCF, r as checkPIVAseIT, t as isValidABN, u as greekTinVerification } from "./is-valid-abn-D7eSygBG.js";
 import { Context, DateTime, Effect, Layer, Predicate, Schema } from "effect";
 //#region src/schematron/errors.ts
 /**
 * @description Failure of a single schematron rule against a document.
+*
+* @example
+*   ```ts
+*   new SchematronRuleError({ id: 'PEPPOL-EN16931-R001', level: 'fatal', message: 'The document must carry a number.' });
+*   ```;
+*
+* @see {@link SchematronValidationError}
 */
 var SchematronRuleError = class extends Schema.TaggedError()("SchematronRuleError", {
 	id: Schema.String,
@@ -14,12 +21,32 @@ var SchematronRuleError = class extends Schema.TaggedError()("SchematronRuleErro
 }) {};
 /**
 * @description Failure of a schematron validation run, wrapping every rule that failed.
+*
+* @example
+*   ```ts
+*   new SchematronValidationError({ errors: [ruleError] });
+*   ```;
+*
+* @see {@link SchematronRuleError}
 */
 var SchematronValidationError = class extends Schema.TaggedError()("SchematronValidationError", { errors: Schema.Array(SchematronRuleError) }) {};
 //#endregion
 //#region src/schematron/helpers.ts
 /**
 * @description Builds an effectful validator from rule metadata and a pure predicate.
+*
+* @example
+*   ```ts
+*   const metadata: SchematronRule = { id: 'PEPPOL-EN16931-R001', level: 'fatal', message: 'The document must carry a number.' };
+*   const validate = schematronRule(metadata, document => document.taxTotals.length > 0);
+*   ```;
+*
+* @param rule - The rule identifier, severity and message reported on failure.
+* @param predicate - The pure check applied to the document; returning `false` fails the rule.
+*
+* @returns A {@link SchematronDocumentValidator} that succeeds for a passing document and fails with a `SchematronRuleError` otherwise.
+*
+* @see {@link SchematronRule}
 */
 function schematronRule(rule, predicate) {
 	return Effect.fn(`schematron.${rule.id}`)(function* (document) {
@@ -32,12 +59,32 @@ function schematronRule(rule, predicate) {
 }
 /**
 * @description Rounds a number to 2 decimals, mirroring the schematron `round(x * 10 * 10) div 100`.
+*
+* @example
+*   ```ts
+*   round2(1.2345); // 1.23
+*   ```;
+*
+* @param value - The number to round.
+*
+* @returns The value rounded to 2 decimals.
 */
 function round2(value) {
 	return Math.round(value * 100) / 100;
 }
 /**
 * @description Checks that `val` is within `slack` of `exp`, mirroring the schematron `u:slack` function.
+*
+* @example
+*   ```ts
+*   slack(100, 100.5, 1); // true
+*   ```;
+*
+* @param exp - The expected value, the centre of the accepted range.
+* @param val - The actual value to test.
+* @param tolerance - The absolute slack allowed on either side of `exp`.
+*
+* @returns `true` when `val` is within `tolerance` of `exp`, otherwise `false`.
 */
 function slack(exp, val, tolerance) {
 	return exp + tolerance >= val && exp - tolerance <= val;
@@ -45,6 +92,15 @@ function slack(exp, val, tolerance) {
 /**
 * @description Extracts the process number from the business process identifier, mirroring the schematron `$profile` variable. Returns `'Unknown'` when the
 * identifier does not match the expected format.
+*
+* @example
+*   ```ts
+*   getProfile(document); // '01'
+*   ```;
+*
+* @param document - The document whose `profileId` is read.
+*
+* @returns The two digit process number, for example `'01'`, or `'Unknown'` when the identifier does not match the expected billing profile format.
 */
 function getProfile(document) {
 	const profileId = document.profileId;
@@ -53,6 +109,15 @@ function getProfile(document) {
 }
 /**
 * @description Resolves the supplier country from the VAT identifier prefix or the supplier postal address, mirroring the schematron `$supplierCountry` variable.
+*
+* @example
+*   ```ts
+*   getSupplierCountry(document); // 'IT'
+*   ```;
+*
+* @param document - The document whose supplier VAT identifiers and postal address are read.
+*
+* @returns The upper case ISO 3166-1 alpha-2 country code, defaulting to `'XX'` when neither the VAT prefix nor the postal address provides one.
 */
 function getSupplierCountry(document) {
 	const prefix = (document.accountingSupplierParty.partyTaxSchemes?.find((s) => s.taxSchemeId.id === "VAT"))?.companyId?.slice(0, 2);
@@ -67,6 +132,15 @@ function getSupplierCountry(document) {
 }
 /**
 * @description Resolves the customer country from the VAT identifier prefix or the customer postal address, mirroring the schematron `$customerCountry` variable.
+*
+* @example
+*   ```ts
+*   getCustomerCountry(document); // 'DE'
+*   ```;
+*
+* @param document - The document whose customer VAT identifiers and postal address are read.
+*
+* @returns The upper case ISO 3166-1 alpha-2 country code, defaulting to `'XX'` when neither the VAT prefix nor the postal address provides one.
 */
 function getCustomerCountry(document) {
 	const prefix = (document.accountingCustomerParty.partyTaxSchemes?.find((s) => s.taxSchemeId.id === "VAT"))?.companyId?.slice(0, 2);
@@ -76,18 +150,45 @@ function getCustomerCountry(document) {
 }
 /**
 * @description Whether the supplier postal address country is Germany, mirroring the schematron `$supplierCountryIsDE` variable.
+*
+* @example
+*   ```ts
+*   isSupplierGermany(document); // false
+*   ```;
+*
+* @param document - The document whose supplier postal address is read.
+*
+* @returns `true` when the supplier postal address country code is `DE`, otherwise `false`.
 */
 function isSupplierGermany(document) {
 	return document.accountingSupplierParty.postalAddress.countryCode.identificationCode.toUpperCase() === "DE";
 }
 /**
 * @description Whether the customer postal address country is Germany, mirroring the schematron `$customerCountryIsDE` variable.
+*
+* @example
+*   ```ts
+*   isCustomerGermany(document); // false
+*   ```;
+*
+* @param document - The document whose customer postal address is read.
+*
+* @returns `true` when the customer postal address country code is `DE`, otherwise `false`.
 */
 function isCustomerGermany(document) {
 	return document.accountingCustomerParty.postalAddress.countryCode.identificationCode.toUpperCase() === "DE";
 }
 /**
 * @description Whether both the supplier and customer countries are Denmark, mirroring the schematron `$supplierCountryIsDK` and `$customerCountryIsDK` variables.
+*
+* @example
+*   ```ts
+*   isDanishSupplierAndCustomer(document); // true
+*   ```;
+*
+* @param document - The document whose supplier and customer countries are read.
+*
+* @returns `true` when both {@link getSupplierCountry} and {@link getCustomerCountry} return `DK`, otherwise `false`.
 */
 function isDanishSupplierAndCustomer(document) {
 	return getSupplierCountry(document) === "DK" && getCustomerCountry(document) === "DK";
@@ -95,12 +196,30 @@ function isDanishSupplierAndCustomer(document) {
 /**
 * @description Whether both the supplier and customer postal address countries are Germany, mirroring the schematron `$supplierCountryIsDE` and
 * `$customerCountryIsDE` variables.
+*
+* @example
+*   ```ts
+*   isGermanSupplierAndCustomer(document); // true
+*   ```;
+*
+* @param document - The document whose supplier and customer postal addresses are read.
+*
+* @returns `true` when both postal address country codes are `DE`, otherwise `false`.
 */
 function isGermanSupplierAndCustomer(document) {
 	return isSupplierGermany(document) && isCustomerGermany(document);
 }
 /**
 * @description Returns the invoice lines or credit note lines of a document.
+*
+* @example
+*   ```ts
+*   getLines(document).length; // 3
+*   ```;
+*
+* @param document - The invoice or credit note whose lines are read.
+*
+* @returns The `invoiceLines` or `creditNoteLines` array, or an empty array when the document carries neither.
 */
 function getLines(document) {
 	if ("invoiceLines" in document && Array.isArray(document.invoiceLines)) return document.invoiceLines;
@@ -109,6 +228,15 @@ function getLines(document) {
 }
 /**
 * @description Returns the line quantity (invoiced or credited quantity) of a line, defaulting to 1.
+*
+* @example
+*   ```ts
+*   getLineQuantity(line); // 2
+*   ```;
+*
+* @param line - The invoice or credit note line whose quantity is read.
+*
+* @returns The `invoicedQuantity` or `creditedQuantity` value, or `1` when the line carries neither.
 */
 function getLineQuantity(line) {
 	const quantity = "invoicedQuantity" in line ? line.invoicedQuantity : "creditedQuantity" in line ? line.creditedQuantity : void 0;
@@ -116,6 +244,15 @@ function getLineQuantity(line) {
 }
 /**
 * @description Returns all document level and line level allowance/charges of a document.
+*
+* @example
+*   ```ts
+*   getAllAllowanceCharges(document).length; // 2
+*   ```;
+*
+* @param document - The document whose document level and line level allowance/charges are collected.
+*
+* @returns Every allowance and charge as a flat array of normalised records, document level entries first.
 */
 function getAllAllowanceCharges(document) {
 	const documentLevel = (document.allowanceCharges ?? []).map((ac) => ({
@@ -140,12 +277,32 @@ function getAllAllowanceCharges(document) {
 }
 /**
 * @description Whether a VAT breakdown group (BG-23) contains a VAT category code equal to `code`.
+*
+* @example
+*   ```ts
+*   hasVatBreakdownCode(document, 'S'); // true
+*   ```;
+*
+* @param document - The document whose VAT breakdown groups (BG-23) are read.
+* @param code - The VAT category code (BT-118) to look for, for example `'S'`.
+*
+* @returns `true` when any VAT breakdown group carries `code`, otherwise `false`.
 */
 function hasVatBreakdownCode(document, code) {
 	return document.taxTotals.some((t) => t.taxSubtotals?.some((s) => s.taxCategory.id === code) ?? false);
 }
 /**
 * @description Whether the document contains a VAT category code (BT-151, BT-95 or BT-102) equal to `code`.
+*
+* @example
+*   ```ts
+*   hasVatCategoryCode(document, 'S'); // true
+*   ```;
+*
+* @param document - The document whose lines and document level allowance/charges are read.
+* @param code - The VAT category code (BT-151, BT-95 or BT-102) to look for.
+*
+* @returns `true` when any line or document level allowance/charge carries `code`, otherwise `false`.
 */
 function hasVatCategoryCode(document, code) {
 	const lineCategories = getLines(document).some((line) => line.item.classifiedTaxCategory.id === code);
@@ -154,24 +311,63 @@ function hasVatCategoryCode(document, code) {
 }
 /**
 * @description Whether the supplier has a VAT identifier (BT-31), a seller tax registration identifier (BT-32) or a tax representative VAT identifier (BT-63).
+*
+* @example
+*   ```ts
+*   hasSellerTaxIdentifier(document); // true
+*   ```;
+*
+* @param document - The document whose supplier party tax schemes are read.
+*
+* @returns `true` when the supplier carries at least one non-empty company identifier, otherwise `false`.
 */
 function hasSellerTaxIdentifier(document) {
 	return document.accountingSupplierParty.partyTaxSchemes?.some((scheme) => scheme.companyId.trim() !== "") ?? false;
 }
 /**
 * @description Whether a number has at most two fraction digits, mirroring the schematron `string-length(substring-after(.,'.'))<=2` checks.
+*
+* @example
+*   ```ts
+*   hasMaxTwoDecimals(1.25); // true
+*   hasMaxTwoDecimals(1.255); // false
+*   ```;
+*
+* @param value - The number to inspect.
+*
+* @returns `true` when the value has at most two fraction digits, otherwise `false`.
 */
 function hasMaxTwoDecimals(value) {
 	return Math.abs(Math.round(value * 100) / 100 - value) < 1e-9;
 }
 /**
 * @description Whether two monetary values are equal, tolerating floating point drift of parsed decimals.
+*
+* @example
+*   ```ts
+*   amountsEqual(100, 100.0000000001); // true
+*   ```;
+*
+* @param a - The first monetary value.
+* @param b - The second monetary value.
+*
+* @returns `true` when the two values differ by less than `1e-9`, otherwise `false`.
 */
 function amountsEqual(a, b) {
 	return Math.abs(a - b) < 1e-9;
 }
 /**
 * @description Counts the VAT breakdown groups (BG-23) whose VAT category code (BT-118) equals `code`.
+*
+* @example
+*   ```ts
+*   countVatBreakdownCode(document, 'S'); // 1
+*   ```;
+*
+* @param document - The document whose VAT breakdown groups (BG-23) are counted.
+* @param code - The VAT category code (BT-118) to count.
+*
+* @returns The number of VAT breakdown groups carrying `code`.
 */
 function countVatBreakdownCode(document, code) {
 	return document.taxTotals.reduce((count, total) => count + (total.taxSubtotals?.filter((subtotal) => subtotal.taxCategory.id === code).length ?? 0), 0);
@@ -184,36 +380,93 @@ function countVatCategoryCode(document, code) {
 }
 /**
 * @description Whether an invoice line (BG-25) carries a VAT category code (BT-151) equal to `code`.
+*
+* @example
+*   ```ts
+*   hasLineVatCategoryCode(document, 'S'); // true
+*   ```;
+*
+* @param document - The document whose invoice lines (BG-25) are read.
+* @param code - The VAT category code (BT-151) to look for.
+*
+* @returns `true` when any invoice line carries `code`, otherwise `false`.
 */
 function hasLineVatCategoryCode(document, code) {
 	return getLines(document).some((line) => line.item.classifiedTaxCategory.id === code);
 }
 /**
 * @description Whether a document level allowance (BG-20) carries a VAT category code (BT-95) equal to `code`.
+*
+* @example
+*   ```ts
+*   hasDocumentAllowanceVatCategoryCode(document, 'S'); // false
+*   ```;
+*
+* @param document - The document whose document level allowances (BG-20) are read.
+* @param code - The VAT category code (BT-95) to look for.
+*
+* @returns `true` when any document level allowance carries `code`, otherwise `false`.
 */
 function hasDocumentAllowanceVatCategoryCode(document, code) {
 	return (document.allowanceCharges ?? []).some((ac) => !ac.chargeIndicator && ac.taxCategory?.id === code);
 }
 /**
 * @description Whether a document level charge (BG-21) carries a VAT category code (BT-102) equal to `code`.
+*
+* @example
+*   ```ts
+*   hasDocumentChargeVatCategoryCode(document, 'S'); // false
+*   ```;
+*
+* @param document - The document whose document level charges (BG-21) are read.
+* @param code - The VAT category code (BT-102) to look for.
+*
+* @returns `true` when any document level charge carries `code`, otherwise `false`.
 */
 function hasDocumentChargeVatCategoryCode(document, code) {
 	return (document.allowanceCharges ?? []).some((ac) => ac.chargeIndicator && ac.taxCategory?.id === code);
 }
 /**
 * @description Whether the supplier has a VAT identifier (BT-31) on a party tax scheme whose tax scheme is "VAT".
+*
+* @example
+*   ```ts
+*   hasSellerVatCompanyId(document); // true
+*   ```;
+*
+* @param document - The document whose supplier party tax schemes are read.
+*
+* @returns `true` when the supplier has a non-empty VAT identifier on a `VAT` tax scheme, otherwise `false`.
 */
 function hasSellerVatCompanyId(document) {
 	return document.accountingSupplierParty.partyTaxSchemes?.some((scheme) => scheme.taxSchemeId.id.toUpperCase() === "VAT" && scheme.companyId.trim() !== "") ?? false;
 }
 /**
 * @description Whether the buyer has a VAT identifier (BT-48) on a party tax scheme whose tax scheme is "VAT".
+*
+* @example
+*   ```ts
+*   hasBuyerVatCompanyId(document); // false
+*   ```;
+*
+* @param document - The document whose buyer party tax schemes are read.
+*
+* @returns `true` when the buyer has a non-empty VAT identifier on a `VAT` tax scheme, otherwise `false`.
 */
 function hasBuyerVatCompanyId(document) {
 	return document.accountingCustomerParty.partyTaxSchemes?.some((scheme) => scheme.taxSchemeId.id.toUpperCase() === "VAT" && scheme.companyId.trim() !== "") ?? false;
 }
 /**
 * @description Whether the seller tax representative has a VAT identifier (BT-63) on a "VAT" tax scheme.
+*
+* @example
+*   ```ts
+*   hasTaxRepresentativeVatCompanyId(document); // false
+*   ```;
+*
+* @param document - The document whose seller tax representative party is read.
+*
+* @returns `true` when a tax representative exists with a non-empty VAT identifier on a `VAT` tax scheme, otherwise `false`.
 */
 function hasTaxRepresentativeVatCompanyId(document) {
 	const taxRepresentative = document.taxRepresentativeParty;
@@ -222,6 +475,15 @@ function hasTaxRepresentativeVatCompanyId(document) {
 }
 /**
 * @description Whether the buyer has a legal registration identifier (BT-47).
+*
+* @example
+*   ```ts
+*   hasBuyerLegalCompanyId(document); // false
+*   ```;
+*
+* @param document - The document whose buyer legal entity is read.
+*
+* @returns `true` when the buyer has a non-empty legal registration identifier (BT-47), otherwise `false`.
 */
 function hasBuyerLegalCompanyId(document) {
 	const id = document.accountingCustomerParty.partyLegalEntity.companyId?.id;
@@ -229,18 +491,51 @@ function hasBuyerLegalCompanyId(document) {
 }
 /**
 * @description Whether every invoice line carrying a VAT category code (BT-151) equal to `code` satisfies `predicate` on its VAT rate (BT-152).
+*
+* @example
+*   ```ts
+*   everyLineCategoryPercent(document, 'S', percent => percent !== undefined && percent > 0); // true
+*   ```;
+*
+* @param document - The document whose invoice lines are read.
+* @param code - The VAT category code (BT-151) to match.
+* @param predicate - The check applied to the VAT rate (BT-152) of matching lines.
+*
+* @returns `true` when every matching line satisfies `predicate`, otherwise `false`.
 */
 function everyLineCategoryPercent(document, code, predicate) {
 	return getLines(document).every((line) => line.item.classifiedTaxCategory.id !== code || predicate(line.item.classifiedTaxCategory.percent));
 }
 /**
 * @description Whether every document level allowance carrying a VAT category code (BT-95) equal to `code` satisfies `predicate` on its VAT rate (BT-96).
+*
+* @example
+*   ```ts
+*   everyDocumentAllowanceCategoryPercent(document, 'S', percent => percent === 0); // false
+*   ```;
+*
+* @param document - The document whose document level allowances are read.
+* @param code - The VAT category code (BT-95) to match.
+* @param predicate - The check applied to the VAT rate (BT-96) of matching allowances.
+*
+* @returns `true` when every matching allowance satisfies `predicate`, otherwise `false`.
 */
 function everyDocumentAllowanceCategoryPercent(document, code, predicate) {
 	return (document.allowanceCharges ?? []).every((ac) => ac.chargeIndicator || ac.taxCategory?.id !== code || predicate(ac.taxCategory.percent));
 }
 /**
 * @description Whether every document level charge carrying a VAT category code (BT-102) equal to `code` satisfies `predicate` on its VAT rate (BT-103).
+*
+* @example
+*   ```ts
+*   everyDocumentChargeCategoryPercent(document, 'S', percent => percent === 0); // false
+*   ```;
+*
+* @param document - The document whose document level charges are read.
+* @param code - The VAT category code (BT-102) to match.
+* @param predicate - The check applied to the VAT rate (BT-103) of matching charges.
+*
+* @returns `true` when every matching charge satisfies `predicate`, otherwise `false`.
 */
 function everyDocumentChargeCategoryPercent(document, code, predicate) {
 	return (document.allowanceCharges ?? []).every((ac) => !ac.chargeIndicator || ac.taxCategory?.id !== code || predicate(ac.taxCategory.percent));
@@ -248,6 +543,16 @@ function everyDocumentChargeCategoryPercent(document, code, predicate) {
 /**
 * @description Sum of invoice line net amounts (BT-131) plus document level charge amounts (BT-99) minus document level allowance amounts (BT-92) where the VAT
 * category codes (BT-151, BT-102, BT-95) equal `code`.
+*
+* @example
+*   ```ts
+*   categoryTaxableSum(document, 'S'); // 1000
+*   ```;
+*
+* @param document - The document whose lines and document level allowance/charges are summed.
+* @param code - The VAT category code (BT-151, BT-102 or BT-95) to sum.
+*
+* @returns The sum of matching invoice line net amounts plus charges minus allowances.
 */
 function categoryTaxableSum(document, code) {
 	const lineSum = getLines(document).filter((line) => line.item.classifiedTaxCategory.id === code).reduce((sum, line) => sum + line.lineExtensionAmount.value, 0);
@@ -257,6 +562,16 @@ function categoryTaxableSum(document, code) {
 }
 /**
 * @description Returns the VAT breakdown groups (BG-23) whose VAT category code (BT-118) equals `code`.
+*
+* @example
+*   ```ts
+*   getTaxSubtotalsWithCode(document, 'S').length; // 1
+*   ```;
+*
+* @param document - The document whose VAT breakdown groups are read.
+* @param code - The VAT category code (BT-118) to collect.
+*
+* @returns The matching VAT breakdown groups with their amounts and category details.
 */
 function getTaxSubtotalsWithCode(document, code) {
 	return document.taxTotals.flatMap((total) => (total.taxSubtotals ?? []).filter((subtotal) => subtotal.taxCategory.id === code).map((subtotal) => ({
@@ -282,6 +597,15 @@ function categoryTaxableSumAtRate(document, code, rate) {
 }
 /**
 * @description Whether the seller has a legal registration identifier (BT-30), used by BR-CO-26.
+*
+* @example
+*   ```ts
+*   hasSellerLegalCompanyId(document); // true
+*   ```;
+*
+* @param document - The document whose supplier legal entity is read.
+*
+* @returns `true` when the supplier has a non-empty legal registration identifier (BT-30), otherwise `false`.
 */
 function hasSellerLegalCompanyId(document) {
 	const id = document.accountingSupplierParty.partyLegalEntity.companyId?.id;
@@ -289,6 +613,16 @@ function hasSellerLegalCompanyId(document) {
 }
 /**
 * @description Whether every ISO 3166-1 alpha-2 country code present on the document equals `code`, used by BR-B-01.
+*
+* @example
+*   ```ts
+*   everyCountryCodeIs(document, 'DE'); // false
+*   ```;
+*
+* @param document - The document whose country codes are read.
+* @param code - The upper case ISO 3166-1 alpha-2 code to match.
+*
+* @returns `true` when every non-empty country code on the document equals `code`, otherwise `false`.
 */
 function everyCountryCodeIs(document, code) {
 	return [
@@ -301,6 +635,15 @@ function everyCountryCodeIs(document, code) {
 }
 /**
 * @description Whether every VAT identifier (BT-31, BT-63, BT-48) carries a country prefix from the ISO 3166-1 alpha-2 list (including EL), used by BR-CO-09.
+*
+* @example
+*   ```ts
+*   allVatCompanyIdsHaveValidPrefix(document); // true
+*   ```;
+*
+* @param document - The document whose supplier, customer and tax representative VAT identifiers are read.
+*
+* @returns `true` when every VAT identifier starts with a known ISO 3166-1 alpha-2 country code (including `EL`), otherwise `false`.
 */
 function allVatCompanyIdsHaveValidPrefix(document) {
 	const companyIds = [];
@@ -314,6 +657,15 @@ function allVatCompanyIdsHaveValidPrefix(document) {
 }
 /**
 * @description Whether every invoice period / line period has an end date after or equal to its start date, used by BR-29 and BR-30.
+*
+* @example
+*   ```ts
+*   everyPeriodEndAfterStart(document); // true
+*   ```;
+*
+* @param document - The document whose invoice periods and line invoice periods are read.
+*
+* @returns `true` when every period with both dates has an end date on or after its start date, otherwise `false`.
 */
 function everyPeriodEndAfterStart(document) {
 	const ok = (period) => {
@@ -325,6 +677,15 @@ function everyPeriodEndAfterStart(document) {
 }
 /**
 * @description Whether every invoice period has a start/end date or a description code, used by BR-CO-19 and BR-CO-20.
+*
+* @example
+*   ```ts
+*   everyPeriodHasDateOrDescriptionCode(document); // true
+*   ```;
+*
+* @param document - The document whose invoice periods and line invoice periods are read.
+*
+* @returns `true` when every period has a start date, an end date or a description code, otherwise `false`.
 */
 function everyPeriodHasDateOrDescriptionCode(document) {
 	const ok = (period) => {
@@ -336,6 +697,15 @@ function everyPeriodHasDateOrDescriptionCode(document) {
 }
 /**
 * @description Whether the note subject code, when present, is coded using UNTDID 4451, used by BR-CL-08.
+*
+* @example
+*   ```ts
+*   noteSubjectCodeIsUncl4451(document); // true
+*   ```;
+*
+* @param document - The document whose note is read.
+*
+* @returns `true` when the note has no subject code, or the subject code is a UNTDID 4451 charge reason code, otherwise `false`.
 */
 function noteSubjectCodeIsUncl4451(document) {
 	const note = document.note;
@@ -346,18 +716,47 @@ function noteSubjectCodeIsUncl4451(document) {
 }
 /**
 * @description Total number of VAT breakdown groups (BG-23) present on the document.
+*
+* @example
+*   ```ts
+*   countAllVatBreakdowns(document); // 1
+*   ```;
+*
+* @param document - The document whose VAT breakdown groups (BG-23) are counted.
+*
+* @returns The total number of VAT breakdown groups.
 */
 function countAllVatBreakdowns(document) {
 	return document.taxTotals.reduce((count, total) => count + (total.taxSubtotals?.length ?? 0), 0);
 }
 /**
 * @description Whether the document contains a VAT category code (BT-151, BT-95, BT-102) or a VAT breakdown category code (BT-118) equal to `code`.
+*
+* @example
+*   ```ts
+*   hasAnyVatCategoryCode(document, 'S'); // true
+*   ```;
+*
+* @param document - The document whose VAT categories and breakdowns are read.
+* @param code - The VAT category code to look for.
+*
+* @returns `true` when the code appears on a line, an allowance/charge or a VAT breakdown group, otherwise `false`.
 */
 function hasAnyVatCategoryCode(document, code) {
 	return countVatCategoryCode(document, code) > 0 || countVatBreakdownCode(document, code) > 0;
 }
 /**
 * @description Whether `a` and `b` are within 1 of each other, mirroring the schematron slack used by BR-S-08, BR-AF-08 and BR-AG-08.
+*
+* @example
+*   ```ts
+*   withinSlackOne(100, 100.5); // true
+*   ```;
+*
+* @param a - The first value.
+* @param b - The second value.
+*
+* @returns `true` when the two values differ by less than `1`, otherwise `false`.
 */
 function withinSlackOne(a, b) {
 	return Math.abs(a - b) < 1;
@@ -365,6 +764,16 @@ function withinSlackOne(a, b) {
 /**
 * @description Whether the VAT category tax amount (BT-117) equals the VAT category taxable amount (BT-116) multiplied by the VAT category rate (BT-119), allowing
 * for a slack of 1, mirroring BR-CO-17.
+*
+* @example
+*   ```ts
+*   vatCategoryTaxAmountMatchesRate(subtotal); // true
+*   ```;
+*
+* @param subtotal - The VAT breakdown group (BG-23) whose tax amount and rate are compared.
+*
+* @returns `true` when the tax amount (BT-117) matches the taxable amount (BT-116) times the rate (BT-119), or when both are zero for a missing or
+*   zero rate; otherwise `false`.
 */
 function vatCategoryTaxAmountMatchesRate(subtotal) {
 	const percent = subtotal.taxCategory.percent;
@@ -377,6 +786,16 @@ function vatCategoryTaxAmountMatchesRate(subtotal) {
 * @description Whether every VAT breakdown (BG-23) whose VAT category code (BT-118) is "Standard rated", "IGIC" or "IPSI" has a VAT category taxable amount
 * (BT-116) that equals the sum of invoice line net amounts (BT-131) plus document level charge amounts (BT-99) minus document level allowance amounts
 * (BT-92) at the same VAT rate, allowing a slack of 1, mirroring BR-S-08, BR-AF-08 and BR-AG-08.
+*
+* @example
+*   ```ts
+*   everyVatBreakdownTaxableMatchesRateSum(document); // true
+*   ```;
+*
+* @param document - The document whose VAT breakdown groups are checked.
+*
+* @returns `true` when every standard rated, IGIC or IPSI breakdown matches the summed line and allowance/charge amounts at its rate, otherwise
+*   `false`.
 */
 function everyVatBreakdownTaxableMatchesRateSum(document) {
 	for (const total of document.taxTotals) for (const subtotal of total.taxSubtotals ?? []) {
@@ -390,6 +809,15 @@ function everyVatBreakdownTaxableMatchesRateSum(document) {
 }
 /**
 * @description Returns all identifiers carrying a scheme identifier, used by the PEPPOL-COMMON-R* rules.
+*
+* @example
+*   ```ts
+*   getIdentifiersWithSchemeId(document); // [{ id: '00743110157', schemeId: '0088' }]
+*   ```;
+*
+* @param document - The document whose supplier, customer and payee identifiers are read.
+*
+* @returns Every identifier that carries both an `id` and a `schemeId`, in supplier, customer then payee order.
 */
 function getIdentifiersWithSchemeId(document) {
 	const candidates = [];
@@ -5001,6 +5429,16 @@ function evaluateSeR013(document) {
 const validateSeR013 = schematronRule(rule, evaluateSeR013);
 //#endregion
 //#region src/schematron/run-all-rules.ts
+/**
+* @description Every schematron rule validator of this library, in evaluation order.
+*
+* @example
+*   ```ts
+*   ruleValidators.length; // 360
+*   ```;
+*
+* @see {@link SchematronDocumentValidator}
+*/
 const ruleValidators = [
 	validateCenEn16931BrAe01,
 	validateCenEn16931BrAe02,
@@ -5367,8 +5805,21 @@ const ruleValidators = [
 //#region src/schematron/schematron.ts
 /**
 * @description Runs the schematron rules of this library against a PEPPOL document.
+*
+* @example
+*   ```ts
+*   const program = Effect.gen(function* () {
+*     const schematron = yield* Schematron;
+*     return yield* schematron.run(document);
+*   });
+*   ```;
+*
+* @see {@link SchematronShape}
 */
 var Schematron = class Schematron extends Context.Service()("@endevops/peppol-schema/schematron/Schematron") {
+	/**
+	* @description Layer that builds the {@link Schematron} service from the rule validators in `ruleValidators`.
+	*/
 	static layer = Layer.effect(Schematron, Effect.gen(function* () {
 		const run = Effect.fn("Schematron.run")(function* (document) {
 			const [errors] = yield* Effect.partition(ruleValidators, (validator) => validator(document));